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。

docs/18-web-panel-and-data-directory.md

@@ -28,16 +28,16 @@
 
 ## 数据目录
 
-默认路径改为宿主 `DATA_PATH / farm_db`。为保持数据连续，数据库文件名
-`farm-preview.sqlite3`、日志文件名和 deployment 标识不变。
+默认路径为宿主 `DATA_PATH / farm_db`，新版数据库名为 `farm.sqlite3`。
+日志文件名和 deployment 标识保持不变。不再自动移动 `farm_preview`
+目录，也不再因两个目录同时存在而阻止启动。
 
-更新插件后下次启动时，若默认旧目录 `farm_preview` 中存在本项目 SQLite，
-且 `farm_db` 不存在，会把整个旧目录重命名为 `farm_db`，同时保留日志和
-SQLite 附属文件。迁移在打开数据库前进行，成功后记录迁移日志。
+同目录旧版 `farm.db` 按用户在首次使用指令时迁移。用户永久绑定首次请求
+的 deployment、机器人 ID 和平台，不跨身份重复导入；转换规则、失败处理
+和不支持字段的保留方式见 [旧数据迁移](05-migration.md)。
 
-若两个目录同时存在，启动失败并提示明确选择数据目录，禁止覆盖或默默
-创建空账户。文件被占用导致重命名失败时同样终止启动；应停止旧实例再启动。
-原有显式 `farm_preview_data_dir` 配置继续生效；该配置用于自定义路径，
-不会被自动移动。若显式配置仍指向 `farm_preview`，需自行更改该路径。
+原有显式 `farm_preview_data_dir` 配置继续生效。仅从选定目录读取旧版
+`farm.db`；不会搜索其他目录。未发布预览版的 `farm-preview.sqlite3`
+不自动改名或导入，预览数据由开发者手动处理。
 
 本轮只修改开发源并进行隔离测试；没有移动正在使用的宿主数据或重启机器人。