fixed # 修复迁移数据库失败的BUG

docs/05-migration.md

@@ -33,7 +33,8 @@ FARM_SERVICE_TOKEN，未把原值复制到新仓库。
 
 ## 真实用户数据迁移建议
 
-当前没有读写任何真实玩家库，以下尚未实施：
+当前没有读写任何真实玩家库。以下是真实部署时的建议；已实现的自动迁移
+范围见下一节，不能将隔离测试等同于真实玩家数据验收：
 
 1. 盘点实际部署版本、schema、来源平台、玩家数量和货币含义。
 2. 停写并备份，记录 schema、文件哈希和备份位置；备份不入 Git。
@@ -50,6 +51,33 @@ FARM_SERVICE_TOKEN，未把原值复制到新仓库。
 是否保留已有资产、重置、补偿或人工对账必须由用户明确决定，
 不在迁移脚本中暗自纠正或清零。
 
+## 真寻旧版 farm.db 自动迁移
+
+新版默认使用 `data/farm_db/farm.sqlite3`，只读同目录的旧版 `farm.db`。
+首次收到用户农场指令时，按旧裸 UID 查找数据并转换；没有旧账号则沿用
+正常注册流程。旧程序应停止写入，切换前自行备份，旧文件不会修改或删除。
+
+- 身份绑定：使用首次请求的 deployment、机器人 ID、平台、用户 ID。
+  导入记录和资产在同一 SQLite 事务提交，同 UID 在整个目标库只导入一次。
+  再次请求不重置余额，重启后仍保持绑定；其他机器人或平台请求会被拒绝。
+- 账户：保留名称、point、vipPoint、exp；不额外发放注册初始资产。
+  初始资产写入新版 ledger，并关联 `legacy_import` 操作。
+- 仓库：按名称唯一匹配内置作物 ID，合并种子与产物，保留数量与锁定。
+  同名歧义、未知作物、重复行、非法数值都会回滚，不猜测或清零。
+- 土地：按 soil 创建已解锁地块，缺失的行补为空地；保留作物、成熟时间、
+  收获季数与枯萎状态，土地等级映射为原有产量/经验加成。
+  旧虫害标志映射为一只虫；当前季保持旧成熟时间，不追溯套用新版生虫时钟，
+  下一季开始使用新版生长规则。
+- 保留：所有含 uid 字段的旧表中该用户的原始行，存入
+  `operations.result` 的 `legacy_rows`。道具、签到、偷菜、杂草、缺水、
+  施肥及土地等级原值等新版尚无完整对应玩法的状态可在此核查；这些状态
+  不宣称已恢复为可用功能。额外表列在 `unsupported_tables`，日志记录表行数。
+- 冲突：新账号已经存在时不覆盖、不累加；迁移失败不注册空账号。
+  检查服务器日志，修复副本并核对后再重试；原始旧库和已提交的新账号均保留。
+
+`farm_preview` 目录与未发布的 `farm-preview.sqlite3` 不在此迁移范围。
+本实现使用构造的旧版结构做隔离测试，尚未验证用户服务器上的真实数据库。
+
 ## 首次发布仓库接管
 
 当前本地 Beta 基线不等于三个发布仓库 main。