docs/05-migration.md

# 旧代码与数据迁移

## 本轮实际同步

源：D:/Work/zhenxun_plugin_farm，Beta 分支，
提交 b015c6c1997f146f651b677382980d338a306bb2。
复制工作区中受版本管理的文件，不复制 .git、未跟踪的工具安装目录。
源 .gitignore 含上轮 Comet 规则，未复制；新主仓库使用自己的忽略策略。

目的地：legacy/zhenxun_plugin_farm。827 个文件、35 个 Python 文件、
静态配置、HTML、图片以及两个仅含 plant/sqlite_sequence 表的作物库。
两库只读 quick_check 均为 ok，未复制运行中的 farm.db 或玩家备份。
静态资源是否全有合法分发授权尚未确认。

唯一源码差异：utils/request.py 的硬编码服务令牌改为读取
FARM_SERVICE_TOKEN，未把原值复制到新仓库。
来源哈希、复制哈希及差异说明见 legacy-manifest.json。
原项目未修改，服务端令牌轮换需另行处理。

## 旧模块复用地图

| 旧位置 | 新去向 | 迁移方式 |
|---|---|---|
| command.py、根 __init__.py | integrations/zhenxun | 保留用户指令契约，重写生命周期和参数适配 |
| core/farm.py、core/shop.py | application、domain | 按用例提取，先修计算和交易缺陷 |
| core/database | infrastructure/sqlite | 明确 schema 与事务所有权，不直接照搬 |
| core/player | 领域模型/查询模型 | 首期移除余额权威缓存，不移植后台线程池 |
| utils/darw、HTML | presentation/资源 | 去除真寻 BuildImage 依赖，支持文本降级 |
| utils/request、utils/json | resources | 配置校验、版本固定、下载原子性 |
| event | 提交后副作用 | 逐个核对必要用途，不先移植通用信号层 |
| core/activity/activity.py、effect.py | 后续玩法候选 | 隔离加载失败，不接入首版 |
| resource/db | 版本化作物目录 | 区分内置只读目录与可写玩家数据库 |

## 真实用户数据迁移建议

当前没有读写任何真实玩家库，以下尚未实施：

1. 盘点实际部署版本、schema、来源平台、玩家数量和货币含义。
2. 停写并备份，记录 schema、文件哈希和备份位置；备份不入 Git。
3. 使用副本进行只读预检：主键、重复、负数、孤儿地块、未知作物、
   作物成熟时间、锁定、签到日期、币种和数值范围。
4. 明确旧裸 UID 到新身份命名空间的映射，不自动跨平台合并。
5. 版本化迁移脚本写入新数据库，保存 migration_id 和 schema_version。
6. 校验用户数、各币种合计、种子/作物数量、地块数及抽样业务状态，
   对每一项转换或舍弃生成报告；再次执行不得重复导入。
7. 在目标框架演练最小玩法闭环、时区与资源加载，再切换数据目录。
8. 若失败，停写后恢复旧程序与原备份，不让两个版本并行写同一数据库。

旧代码存在余额和经验重复增加，无法仅凭当前余额还原“正确历史值”。
是否保留已有资产、重置、补偿或人工对账必须由用户明确决定，
不在迁移脚本中暗自纠正或清零。

## 首次发布仓库接管

当前本地 Beta 基线不等于三个发布仓库 main。
未来需要取得重新拉取授权后，对比现有功能和依赖，记录有价值的框架
接入代码与差异，再决定复用方式。不能本轮默认把远程现有代码覆盖成
Beta，也不能把已有 AstrBot/NoneBot 实现宣称已经合并进新主仓库。

发布仓库地址已纳入设计，检出已按用户要求删除。仅迁移基线保留在
主仓库，主仓库没有 Git 子模块和发布仓库副本。