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

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

## 1. 唯一目标

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

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

## 2. 事实裁决顺序

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

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

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

## 3. 必须保持不变

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

## 4. 允许与禁止

允许：

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

禁止：

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

## 5. 迁移单位

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

```text
用户入口 -> 页面结构 -> 样式与动画 -> 前端状态 -> 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切换或数据清理。