xiaobaifupan/app/docs/migration/原版保真迁移总纲.md

小白复盘原版保真迁移总纲

状态：正式迁移 建立日期：2026-07-30 迁移性质：保行为、保视觉、保数据语义的源代码整理

1. 唯一目标

以当前可运行原版webapp为唯一母版，在用户批准的app/目录中建立更容易检索、理解和人工维护的 代码结构。迁移后的系统必须继续使用原版已经验收的功能、视觉、布局、动画、计算逻辑和交互， 不得依据说明文字重新开发一个相似产品。

本次工作相当于把原文件柜中的有效原件逐项分类搬入新文件柜，而不是重新制作原件。

2. 事实裁决顺序

发生不一致时按以下顺序处理：

1. 用户在当前或后续对话中的明确决定。
2. 原版在相同代码、数据、账号、配置、日期、主题和视口下的真实运行行为。
3. 原版源码、数据库结构、静态资产和现有测试共同证明的行为。
4. 《小白复盘完整产品规格说明书》用于盘点和解释，不得自行覆盖原版行为。
5. 无法确定时记录为待裁决，保持原状，不推测、不补全。

只有用户明确指出原版是Bug或要求改变时，才允许产生用户可观察差异，并必须单独记录。

3. 必须保持不变

• 全部页面、入口、功能和细节能力。
• PC与移动端布局、尺寸、字体、颜色、间距、滚动和响应式行为。
• 日间、夜间、加载、空、错误、禁用、悬停、选中和完成状态。
• 动画素材、形态、时序、过场、循环、静音和减少动态效果行为。
• API路径、请求、响应、错误语义和流式传输行为。
• 数据来源职责、日期、单位、复权、缺失、覆盖率、新鲜度和降级规则。
• 权限、会员、管理员标识、账户隔离和私有数据边界。
• 情绪、竞价、股池、选股、问天及统计计算结果。
• 数据库现有记录、唯一约束、历史兼容和后台任务语义。

4. 允许与禁止

允许：

• 移动文件并调整导入路径。
• 将巨型文件按已经存在的职责拆分。
• 抽出实际重复且行为相同的实现，让原调用方指向唯一实现。
• 为原行为增加刻画测试、API快照、数据库对比和视觉回归。
• 删除已证明无引用、无运行路径、无视觉影响、无数据兼容责任的代码。

禁止：

• 更换前端框架、后端框架、数据库或主要技术栈。
• 重写已经存在的页面、样式、动画、公式或数据流程。
• 以新的设计令牌、组件库或架构偏好改变最终视觉。
• 先建立空架构，再依据规格书补写功能。
• 以“更合理”为由修复未被用户确认的原版行为。
• 复制next/中的产品实现进入新的迁移目录。
• 为追求行数、文件数或测试数量而删除有效代码或制造空抽象。

5. 迁移单位

代码不能像独立照片一样任意逐文件搬运。每次迁移一个完整纵向切片：

用户入口 -> 页面结构 -> 样式与动画 -> 前端状态 -> API -> 业务计算 -> 数据库/外部数据

切片内部可以先原样复制，再在保持输出不变的前提下拆分。不得只搬页面而稍后重写接口，也不得先 重建全部后端再补前端。

6. 固定工作流

1. 冻结原版基线提交，使用数据副本，不写正式数据。
2. 建立资产清单和依赖图，逐项标记保留、移动、合并、待定或确认废弃。
3. 先规划目标目录职责；未确认前不建立业务代码。
4. 为待迁移切片记录原版API、数据库副作用、页面状态、截图和交互流程。
5. 从原版复制对应实现和资产，只调整迁移所必需的路径与依赖。
6. 对新旧版本执行同输入差异测试，结果不等价则回退本切片。
7. 等价后才允许拆分或去重；每次拆分再次执行同一组差异测试。
8. 更新迁移账本、状态文件和Git回档点，再进入下一个切片。
9. 所有切片完成后执行全量并行验收，用户确认前不切换部署。

7. 等价证据

每个切片至少同时具备：

证据	要求
源码映射	原文件、符号和资产到新位置的逐项记录
API差异	同请求的状态码、字段、值、顺序和错误一致
数据库差异	同操作的新增、修改、删除和事务结果一致
计算差异	固定输入得到逐字段相同结果
页面差异	同数据、主题和视口的截图及结构比较
交互差异	点击、键盘、滚动、弹窗、动画和刷新流程一致
人工确认	用户确认视觉与使用感受没有偏差

新版本自身的单元测试只能作为辅助，不能代替新旧差异证据。

8. 删除规则

任何代码只有同时满足以下条件才可不迁移或删除：

1. 静态引用和动态注册扫描均无消费者。
2. 运行覆盖和真实浏览器流程未经过该路径。
3. 不承担数据库迁移、历史兼容、配置读取或资源加载责任。
4. 删除后原版与迁移版的全量差异测试仍一致。
5. 迁移账本记录理由、证据和恢复提交。

条件不足时标记待定并保留，不能凭代码外观判断。

9. 上下文恢复协议

每次新任务、上下文压缩或执行中断后，必须先完成：

1. 读取仓库根目录AGENTS.md。
2. 读取本总纲、保真迁移状态.json及迁移账本。
3. 确认next/仍处于失败冻结状态。
4. 检查Git状态、当前基线提交和最后回档点。
5. 查看正在迁移切片的原版证据与未关闭差异。
6. 在继续编辑前向用户简述当前阶段、硬约束和下一步。

不得根据聊天摘要重新发明阶段、技术栈或验收口径。

10. 当前边界

• next/已失败冻结，不是迁移起点。
• 新目录名称、目标结构和迁移顺序已于2026-07-30获得用户确认。
• 第一切片必须先建立原样可运行副本，不允许直接开始重新实现或视觉重构。
• 原版保持唯一可运行产品，不执行Docker切换或数据清理。