xiaobaifupan/docs/migration/重建迁移章程.md

小白复盘重建迁移章程

状态：执行中
建立日期：2026-07-30
产品真相源：docs/product/小白复盘-完整产品规格说明书.md

1. 唯一目标

在当前仓库的next/目录内，从零重建小白复盘。新系统必须完整实现产品规格说明书定义的功能、权限、数据口径、交互状态、视觉和终端行为，同时显著减少重复实现、补丁层和隐式依赖，使后续人工维护可操作。

迁移不是对旧系统继续重构，也不是增加新产品功能。旧系统在迁移期间保持可运行，只用于读取业务事实、算法、必要数据和视觉资产。

2. 不可违反的约束

1. 产品规格说明书中的“已确认产品标准”优先于旧代码现状。
2. 旧系统文件不移动、不批量改名、不作为新系统运行时依赖。
3. 新系统开发数据库独立，不直接写入旧系统数据库。
4. 不整文件复制旧server.py、app.js、样式覆盖层或巨型业务模块。
5. 每项业务规则只保留一个权威实现。
6. 全站只有一个浏览器API出口、一个数据网关、一个LLM网关、一个弹窗管理器和一套设计令牌。
7. 页面只负责取数、组织状态和组合组件，不拥有跨页面业务计算。
8. 外部数据源只能通过数据网关访问；公开网页源不得进入正式计算。
9. LLM只解释或编译受控公式，不参与确定性行情、情绪、选股和问天计算。
10. 用户私有数据的所有读写必须在服务端验证账号所有权。
11. 兼容层只能用于迁移，必须登记删除条件；最终交付不得保留双实现。
12. 不以“测试通过”替代产品验收；测试必须实际覆盖对应规格。
13. 不以“目录已建立”或“接口已预留”宣称功能迁移完成。
14. 不自动替换NAS生产容器；最终切换在全量验收后单独确认。

3. 技术与结构决策

3.1 技术栈

• 后端：Python、FastAPI、Pydantic。
• 数据库：SQLite，显式Repository与有序Migration，不引入ORM双重抽象。
• 前端：Vue 3、TypeScript、Vite、Pinia。
• 单元与集成测试：pytest。
• 浏览器验收：Playwright。
• 部署：多阶段Docker构建，运行时保持单容器模块化单体。

3.2 目标一级结构

next/
  frontend/
    src/
      shared/
      pages/
      app/
  backend/
    bootstrap/
    http/
    features/
    data/
    database/
    jobs/
    llm/
  config/
  tests/
  tools/
  docs/

只预建稳定的一级边界。二、三级业务目录随纵向切片建立，不创建无真实职责的空目录树。

3.3 依赖方向

浏览器页面 -> 前端共享层 -> HTTP接口
HTTP/后台任务 -> 业务服务 -> Repository/DataGateway/LLMGateway -> 基础设施

禁止反向依赖、跨功能直接读表、页面直接访问外部数据源，以及Controller中编写评分和持久化逻辑。

4. “做减法”验收标准

每个迁移切片必须证明：

• 旧系统同一行为的多个实现已经在新系统收敛为一个。
• 没有为了快速兼容复制第二份公式、请求逻辑或CSS组件。
• 新增共享抽象至少有两个真实调用方，或明确消除一个高风险全局出口。
• 页面专属样式不修改其他页面和全局Shell。
• 临时代码有明确删除条件，不使用永久legacy、v2-fix、override-final式补丁层。
• 重建后的文件按职责可读，不用巨型文件重新制造旧问题。
• 仅统计代码行数下降不能证明成功；功能等价、唯一职责和可删除旧实现同时成立才算减法。

建议性文件规模门禁：

• 前端页面容器目标不超过400行，超出时按稳定子组件拆分。
• 后端业务服务目标不超过500行，复杂确定性算法可独立成纯计算模块。
• 单个CSS文件目标不超过600行，按令牌、Shell、共享组件、页面、移动端分层。
• 超过门禁必须在本章程记录原因，不能静默放宽。

5. 迁移方法

采用纵向切片。每个切片同时交付：

1. 产品行为与状态。
2. 权限和账号数据边界。
3. 后端接口与Schema。
4. 业务计算与数据访问。
5. 前端页面、日间/夜间和响应式行为。
6. 单元、契约、集成和浏览器测试。
7. 与旧系统和产品规格的差异报告。
8. Git提交和远端回档节点。

禁止先迁移全部HTML、再迁移全部接口、最后补业务逻辑。这会产生长期空壳和无法验收的中间状态。

6. 执行阶段

阶段	内容	完成证据	状态
0	产品规格、迁移章程、旧系统只读基线	文档检查、Git节点	已完成
1	next/最小可运行骨架与工具链	前后端启动、健康检查、基础测试	已完成
2	配置、错误、日志、数据库迁移、Repository基础	迁移回退和错误契约测试	已完成
3	账户、会话、权限、会员和系统配置	权限矩阵与跨账号测试	已完成
4	前端Shell、路由、状态、API、弹窗、主题和令牌	1080P/4K/390px Shell截图	未开始
5	数据网关、日期、快照、图表和搜索	来源/时间/缺失/降级测试	未开始
6	情绪周期与五类股池	算法固定样本、页面E2E	未开始
7	涨停表现、市场天梯和板块轮动	结构统计与展开滚动验收	未开始
8	集合竞价、题材库、人气热榜和龙虎榜	生命周期、口径和空态验收	未开始
9	智能选股、36套策略、自定义选股和持续跟踪	109因子、确定性和隔离测试	未开始
10	问师、模型Skill、LLM流式网关	上下文路由、去重和回退测试	未开始
11	问天观势、观气、观心	公式、安全门、动画和历史验收	未开始
12	我的复盘、提醒和复盘助手	私有数据、汇总和弹窗验收	未开始
13	全站移动端重组和无障碍	320/390/430/768/横屏验收	未开始
14	数据迁移、Docker、备份恢复和性能安全	旧库副本迁移、回滚演练	未开始
15	全量验收、减法审计和切换准备	规格覆盖矩阵、最终报告	未开始

阶段编号不会因为上下文压缩重新规划。只有发现产品规格自身矛盾时，才记录决策并调整阶段内容；不得通过新增阶段掩盖未完成工作。

7. 每阶段质量门禁

每次提交前至少执行：

1. 格式、类型和静态检查。
2. 受影响模块的单元测试。
3. API契约和账号边界测试。
4. 数据库迁移前进/回退测试（涉及数据库时）。
5. Playwright关键流程（涉及运行时或前端时）。
6. 日间/夜间和目标视口截图（涉及视觉时）。
7. 浏览器控制台无未处理错误。
8. 密钥、Token、日志和生成物扫描。
9. 与产品规格固定验收案例的可追溯检查。
10. git diff --check和工作区来源确认。

8. Git与回档

• 当前main保留旧系统可运行状态和新系统迁移过程。
• 每个阶段至少一个独立提交，提交信息使用rebuild(stage-N): ...。
• 阶段门禁通过后推送Gitea。
• 不重写已推送历史，不使用破坏性重置。
• 大阶段内可有多个小提交，但最终必须有明确阶段完成节点。
• 规格说明书和本章程的变更与相应行为变更同提交或先提交。

9. 数据迁移与最终切换

• 开发期间只使用旧数据库的只读副本或脱敏样本。
• 迁移工具可重复运行，并输出逐表数量、校验和、跳过项和失败项。
• 首次完整迁移后进行账号、权限、共享快照和私有数据抽样比对。
• 最终切换前停止旧系统写入，执行最终增量迁移，再启动新容器。
• 保留旧镜像、旧数据库一致性备份和加密密钥，验证回退路径。
• 未经最终确认，不停止或替换NAS现有容器。

10. 持续状态记录

每完成一个阶段，在本节追加：

• 提交哈希和推送状态。
• 实际完成证据。
• 删除或避免的重复代码。
• 未完成项和残余风险。
• 下一阶段入口条件。

当前状态

• 阶段0已完成：产品规格说明书和迁移章程通过结构、表格和密钥扫描。
• 产品规格说明书包含16个工作区、36套策略、109个因子和85个固定验收案例。
• 旧系统保持原状。
• 阶段1已完成，代码提交为603e73d：建立隔离的FastAPI与Vue 3/TypeScript/Vite骨架、唯一前端API客户端、统一安全错误外壳、设计令牌起点及前后端基础测试。
• 后端门禁：Ruff通过，pytest为2项通过；存在1项FastAPI 0.141测试客户端上游弃用警告，阶段2改用显式ASGI传输层消除。
• 前端门禁：类型检查通过，Vitest为1个文件/2项通过，Vite生产构建通过；依赖安装审计为0个已知漏洞。
• 运行验收：8780/api/health返回开发环境健康状态，5173代理访问成功；1280x720浏览器实测无控制台错误、无横向溢出。
• 减法证据：删除未使用的jsdom及37个传递依赖；禁止TypeScript生成重复JavaScript测试产物；未复制旧server.py、app.js或CSS覆盖层。
• 阶段2已完成，代码提交为d969d2c：配置从环境唯一加载，SQLite连接启用WAL/外键/忙等待，迁移支持前进、显式回退、原子失败、校验和和连续历史校验。
• Repository基础只建立被健康检查真实使用的数据库状态Repository，未创建通用CRUD或空业务目录；数据库维护CLI支持状态、升级及需二次确认的回退。
• HTTP错误统一为code/message/request_id，404、验证错误、业务错误和未知异常均通过安全契约；请求编号同时写入响应头，未知异常不向前端泄露原文。
• 日志采用结构化JSON、Asia/Shanghai时间、10MB/3份轮转和嵌套/字符串敏感值脱敏；运行健康检查可区分进程和数据库状态。
• 阶段2门禁：Ruff通过，pytest为20项通过，前端2项测试、类型检查和生产构建通过；真实服务健康响应、请求编号及+08:00启动日志通过运行验收。
• 阶段3已完成，代码提交为f69972c并已推送：首个注册账号成为管理员，后续账号为普通用户；管理员权限与会员状态独立，管理员开通会员后同时具有管理员和会员标识。
• 会话Cookie为HttpOnly，CSRF使用Cookie与请求头双重校验；服务端只保存会话和CSRF哈希。修改密码保留当前会话并撤销其他会话，账号出生资料和系统凭据均加密落库且按权限隔离。
• 会员管理支持1个月、3个月、12个月、3年和永久，续期从有效到期日继续计算；会员每日智能调用上限进入会员配置。管理员无需伪装成会员即可使用智能功能，普通非会员被服务端拒绝。
• 模型池限制20个模型，首个模型自动成为主模型，支持独立选择主模型和辅助模型；选中模型不可删除，密钥不会通过管理接口返回。模型连通测试明确留给阶段10的唯一LLM网关，系统管理不建立第二个模型调用出口。
• 减法证据：HTTP Schema从路由中拆出，路由由412行降至314行；系统凭据职责从账户服务拆出，最长业务服务由429行降至382行。未建立通用CRUD、旧账号兼容层、第二套权限判断或明文密钥读取接口。
• 阶段3门禁：Ruff通过，pytest为40项通过；前端2项测试、类型检查和生产构建继续通过；数据库版本1和2的前进及倒序回退通过，真实账号密码和已提供令牌未进入next/。
• 阶段3残余边界：账号与系统管理的前端交互属于阶段4；LLM成功调用计次和模型连通性属于阶段10，不在阶段3提前实现。
• 新系统进入阶段4：建立唯一Shell、路由、前端状态、弹窗管理、日间/夜间主题和响应式骨架，并以1080P、4K和390px验收。
• 生产切换明确保留为最终人工确认项。