xiaobaifupan/docs/migration/保真迁移账本.md

# 小白复盘保真迁移账本

> 当前状态：切片11自动验收完成，等待用户人工验收；正式切换尚未执行

本账本是上下文恢复和人工审计的连续记录。任何迁移提交必须在同一提交中更新本文件及
`保真迁移状态.json`。

## 固定事实

- 原版根目录是唯一产品和视觉基线。
- `next/`已被用户否决并冻结，不进入后续迁移。
- 新目标目录由用户批准为`app/`，最终作为正式程序目录。
- 后续采用原代码保真式迁移，不重新实现，不更换技术栈。
- 2026-07-30用户授权在既定约束内自主完成全部迁移，阶段性差异仍必须阻断后续切片。

## 当前检查点

| 日期 | 提交或标签 | 事件 | 结论 |
|---|---|---|---|
| 2026-07-30 | `xiaobai-next-rejected-20260730` | 冻结失败的`next/`实现 | 禁止部署或继续开发 |
| 2026-07-30 | `xiaobai-preservation-migration-charter-20260730` | 建立保真迁移总纲、状态和恢复协议 | 尚未开始新迁移 |
| 2026-07-30 | `41329943c4878fc09ed82ec376eb93ab151e4092` | 完成只读资产清查并由用户批准`app/`结构 | 开始切片00 |
| 2026-07-31 | `xiaobai-preservation-slice-01-20260731` | 启动、HTTP、账号、会员与系统管理原实现归位 | 自动差分通过，进入切片02 |
| 2026-07-31 | `xiaobai-preservation-slice-02-20260731` | 公共行情、搜索、详情、图表与数据适配原实现归位 | 自动与浏览器差分通过，进入切片03 |
| 2026-07-31 | `xiaobai-preservation-slice-03-20260731` | 情绪周期、五类股池与涨停表现原实现归位 | 自动、API与浏览器差分通过，进入切片04 |
| 2026-07-31 | `xiaobai-preservation-slice-04-20260731` | 市场天梯与板块轮动原实现归位 | 自动、API与浏览器差分通过，进入切片05 |
| 2026-07-31 | `xiaobai-preservation-slice-05-20260731` | 集合竞价、题材库、人气热榜与龙虎榜原实现归位 | 自动、API、数据库与浏览器差分通过，进入切片06 |
| 2026-07-31 | `xiaobai-preservation-slice-06-20260731` | 智能选股、自定义选股与策略持续跟踪原实现归位 | 自动、API、数据库与浏览器差分通过，进入切片07 |
| 2026-07-31 | `xiaobai-preservation-slice-07-20260731` | 问师、模型Skill与LLM流式链路原实现归位 | 自动、API、数据库、Skill与浏览器差分通过，进入切片08 |
| 2026-07-31 | `xiaobai-preservation-slice-08-20260731` | 问天、观势、观气与观心原实现归位 | 自动、API、数据库、动画与浏览器差分通过，进入切片09 |
| 2026-07-31 | `xiaobai-preservation-slice-09-20260731` | 复盘、自选、交易日志、提醒与复盘助手原实现归位 | 自动、API、数据库、账户隔离与浏览器差分通过，进入切片10 |
| 2026-07-31 | `xiaobai-preservation-slice-10-20260731` | 前端Shell、页面、CSS、动画与移动端职责归位 | 源码重组、自动、API、数据库、桌面、夜间、移动端与动画差分通过，进入切片11 |
| 2026-07-31 | `xiaobai-preservation-slice-11-candidate-20260731` | 不确定代码审计、全量验收与人工交接准备 | 自动、API、数据库和浏览器验收通过；等待人工确认，未切换部署 |

## 资产处置登记

开始清查后，每个资产必须登记，禁止只记录已迁移项而遗漏未处理项。

| 原位置/符号 | 类型 | 消费者 | 处置 | 新位置 | 等价证据 | 状态 |
|---|---|---|---|---|---|---|
| 原版运行源文件（排除`next/`、日志、缓存、构建产物和正式数据库） | 运行资产 | 全站 | 原样保留后逐项移动 | `app/` | 388项受控资产哈希一致；231项Python与45项Playwright测试通过 | 已复制 |
| `next/` | 失败实现 | 无正式消费者 | 原样保留但禁止迁移 | - | 用户冻结决定 | 已冻结 |
| `demo_data.py` | 旧演示代码 | 无运行、动态、配置或兼容消费者 | 候选试删 | 切片10标签可单项恢复 | 全量自动、API、数据库与浏览器验收通过 | 待人工确认 |
| `static/heaven-loading.js` | 旧动画 | 页面只加载`heaven-loading-v2.js` | 候选试删 | 切片10标签可单项恢复 | 问天三页加载动画与45项Playwright通过 | 待人工确认 |
| `commonReviewColumns`等5个前端函数 | 无引用符号 | 定义外引用为0 | 候选试删 | 切片10标签可按原行号恢复 | 审计白名单比较、24个JS语法和浏览器流程通过 | 待人工确认 |
| `wencai_saved_queries`及其方法 | 历史兼容数据 | 旧库兼容与用户隔离 | 原样保留 | `app/backend/database/`兼容区 | schema及关键表差分一致；清理契约持续保护 | 保留 |
| 现有7层CSS | 视觉运行资产 | 全部页面和主题 | 原样保留后逐页归档 | `app/frontend/` | 必须通过截图与计算样式差分 | 保留 |
| `sentiment_engine.py` | 情绪周期计算 | 总览、轮动、选股 | 移动并保留兼容别名 | `app/backend/features/sentiment/engine.py` | 文件哈希与原版一致；248项Python与45项Playwright通过 | 已移动 |
| `DashboardService`情绪及股池原因方法 | 业务服务 | 情绪页、五类股池、涨停表现 | 按职责机械移动 | `app/backend/features/sentiment/`、`app/backend/features/pools/` | 8个方法AST与原版一致；真实API完全一致 | 已移动 |
| `ReviewDatabase`原因覆盖方法 | 持久化 | 股池原因人工覆盖 | 按职责机械移动 | `app/backend/features/pools/repository.py` | 2个方法AST与原版一致；数据库schema哈希一致 | 已移动 |
| `DashboardService`板块轮动方法 | 业务服务 | 板块轮动页 | 按职责机械移动 | `app/backend/features/rotation/service.py` | 2个方法AST、真实API与原版一致 | 已移动 |
| Tushare天梯与轮动构造函数 | 公共数据计算 | 市场天梯、板块轮动 | 原位置保持唯一实现 | `app/backend/data/providers/tushare_client.py` | 2个构造函数AST与原版一致 | 已归位 |
| `MarketInsightsService` | 共享市场洞察服务 | 集合竞价、题材库、人气热榜 | 整体机械移动，保留唯一共享实现 | `app/backend/features/market/insights.py` | 22个方法AST与原版一致；根级模块为同一类对象别名 | 已移动 |
| `DashboardService`竞价、题材、人气与龙虎榜方法 | 业务服务 | 切片05四类页面与API | 按职责机械移动 | `app/backend/features/auction/`、`themes/`、`popularity/`、`dragon_tiger/` | 8个方法AST、7个真实API与原版一致 | 已移动 |
| `ReviewDatabase`竞价、人气与龙虎榜方法 | 持久化 | 市场洞察及后续智能选股 | 按职责机械移动并保持Mixin原接口 | `app/backend/features/auction/repository.py`、`popularity/repository.py`、`dragon_tiger/repository.py` | 7个方法AST一致；62个schema对象及5张关键表逐行一致 | 已移动 |
| Tushare游资名录与龙虎榜实现 | 公共数据计算 | 龙虎榜与游资档案 | 原位置保持唯一实现 | `app/backend/data/providers/tushare_client.py` | 2个方法AST与原版一致 | 已归位 |
| 选股引擎、策略库与公式编译器 | 业务计算 | 阶段、策略、自定义选股 | 整体机械移动并保留兼容别名 | `app/backend/features/screener/engine.py`、`strategies.py`、`compiler.py` | 原版AST/源码等价；根级模块为同一模块对象 | 已移动 |
| `DashboardService`选股方法 | 业务服务 | 选股三个工作区 | 按职责机械移动 | `app/backend/features/screener/service.py` | 13个方法AST及3个真实API一致 | 已移动 |
| `ReviewDatabase`选股方法 | 持久化 | 因子、策略运行、候选与跟踪 | 按职责机械移动并保持Mixin原接口 | `app/backend/features/screener/repository.py` | 25个方法AST一致；62个schema对象及13张关键表逐行一致 | 已移动 |
| `StrategyTrackingService` | 业务服务 | 手动候选持续跟踪 | 保持唯一实现并调整容器导入 | `app/backend/features/screener/tracking.py` | 类定义AST、真实API与浏览器行为一致 | 已归位 |
| `mentor_agent.py`与问师服务 | 业务服务 | Skill发现、问师上下文与流式回答 | 整体机械移动并保留兼容别名 | `app/backend/features/mentor/` | Agent文件哈希、8个服务方法AST、2个真实API及浏览器行为一致 | 已移动 |
| 问师消息与偏好方法 | 持久化 | 用户对话、置顶和排序 | 按职责机械移动并保持Mixin原接口 | `app/backend/features/mentor/repository.py` | 5个方法AST一致；相关表逐行一致 | 已移动 |
| `llm_stream.py`与模型访问方法 | 公共模型能力 | 问师、问天、复盘助手与策略编译 | 移入唯一模型边界并保留兼容别名 | `app/backend/llm/` | 流式文件哈希一致；21个服务方法与既有用户边界一致 | 已移动 |
| 公开`游资skills` | 运行资产 | 问师模型库 | 原样保留 | `app/游资skills/` | 190个文件逐路径和SHA-256一致 | 已复制 |
| `heaven_agent.py`、`heaven_engine.py`与问天服务 | 业务计算 | 观势、观气、观心 | 机械移动并保留兼容别名 | `app/backend/features/heaven/` | Agent文件哈希、引擎定义AST、20个服务方法、6个API及真实动画页面等价 | 已移动 |
| 问天历史方法 | 持久化 | 三类解读历史与当日解运复用 | 按职责机械移动 | `app/backend/features/heaven/repository.py` | 5个方法AST一致；62个schema对象及6张关键表逐行一致 | 已移动 |
| `assistant_agent.py`与复盘服务 | 业务服务 | 我的复盘、自选、交易日志与复盘助手 | 机械移动并保留兼容别名 | `app/backend/features/review/` | Agent文件哈希、8个服务方法AST、5个真实API及会员/非会员页面等价 | 已移动 |
| 复盘、自选、交易日志与助手消息方法 | 持久化 | 用户私有复盘数据 | 按职责机械移动并保持Mixin原接口 | `app/backend/features/review/repository.py` | 13个方法AST一致；相关表逐行一致；浏览器账户隔离通过 | 已移动 |
| 提醒编排与提醒持久化方法 | 业务服务/持久化 | 提醒中心与策略跟踪提醒 | 按职责机械移动 | `app/backend/features/alerts/` | 5个服务方法、6个Repository方法AST及真实API一致 | 已移动 |
| `static/app.js` | 前端总运行时 | 全站页面、状态、交互与动画 | 按原连续行机械拆分 | `app/frontend/app.js`、`pages/*/page.js`、`pages/market/runtime.js`、`shared/export.js` | 9,283行重组SHA-256与原版一致；85项前端专项测试通过 | 已移动 |
| `static/index.html` | 前端DOM骨架 | 全站 | 只调整资源路径和拆分脚本加载 | `app/frontend/index.html` | 反向替换路径与脚本后逐字符一致；浏览器差分通过 | 已移动 |
| `static/styles.css`等七层样式 | 视觉运行资产 | 全部页面、主题和移动端 | 字节级移动 | `app/frontend/styles/`、`app/frontend/pages/heaven/page.css`、`app/frontend/shared/tokens.css` | 逐文件SHA-256一致；桌面、夜间和移动端计算样式一致 | 已移动 |
| `static/ui-core.js`、页面/共享脚本和供应商资产 | 前端共享/第三方资产 | Shell、页面注册、通用组件与图标 | 字节级移动 | `app/frontend/shared/`、`pages/`、`vendor/` | 逐文件SHA-256一致；45项Playwright和真实浏览器差分通过 | 已移动 |

处置只允许：`原样保留`、`移动`、`合并重复`、`待定`、`确认废弃`。

## 切片记录

每个切片记录以下内容：原版基线、复制范围、必要路径调整、差异测试、人工验收、未关闭问题和回档提交。
已完成切片：`slice-00-exact-runtime-copy`。

- 原版基线：提交`41329943c4878fc09ed82ec376eb93ab151e4092`。
- 复制范围：确认参与运行、测试、部署和维护的原版文件；排除`next/`和运行产物。
- 允许改动：新目录中的路径配置、测试根目录和端口；不得改业务实现。
- 验收：新目录独立启动，231项Python测试、45项Playwright测试、数据库副本和静态资产哈希验证。
- 回档：本切片建立独立Git提交并推送Gitea。
- 完整证据：`docs/migration/evidence/slice-00/README.md`。
- 资产清单：`docs/migration/原版资产清单.json`，388项，0项哈希差异。

已完成切片：`slice-01-startup-http-accounts-system`。

- 原版基线：提交`4083dce`，即切片00原样副本。
- 迁移范围：进程入口、应用组装、HTTP传输、账号安全、账号/会员业务、账号/系统设置持久化。
- 兼容边界：根级`server.py`、`app_config.py`、`security.py`继续保留原导入和命令入口。
- API与数据库：API/功能注册表哈希一致；原版与副本数据库均为36表、62个schema对象且schema哈希一致。
- 验收：236项Python测试、5项切片专项测试、45项Playwright测试全部通过；前端运行资产未改动。
- 回档：标签`xiaobai-preservation-slice-01-20260731`。
- 完整证据：`docs/migration/evidence/slice-01/README.md`。

已完成切片：`slice-02-market-search-charts-data`。

- 原版基线：提交`4002f09`，即切片01回档点。
- 迁移范围：30个公共行情服务方法、11个行情持久化方法及Tushare/iFinD/图表/实时观察实现。
- 兼容边界：四个根级数据模块保留模块别名；未迁移功能继续使用旧导入且指向同一实现。
- 等价证明：41个方法AST逐项一致，三个数据文件哈希一致，图表定义AST一致，静态资产哈希一致。
- 验收：241项Python测试、6项切片源码等价测试、45项Playwright测试及真实服务搜索/详情流程通过。
- 既存状态：原版和迁移版的实时分时在当前环境均返回相同外部请求失败，不作为迁移回归处理。
- 回档：标签`xiaobai-preservation-slice-02-20260731`。
- 完整证据：`docs/migration/evidence/slice-02/README.md`。

已完成切片：`slice-03-sentiment-pools-performance`。

- 原版基线：提交`a426432`，即切片02回档点。
- 迁移范围：情绪计算引擎、2个情绪服务方法、6个股池原因与iFinD事件补全方法、2个原因覆盖持久化方法。
- 兼容边界：根级`sentiment_engine.py`保留同一模块对象别名；股池生成仍使用切片02的原Tushare总览实现。
- API与数据库：原版`8784`和迁移版`8785`的总览、情绪历史JSON完全一致；两库schema均为62项且哈希一致。
- 验收：248项Python测试、6项切片源码等价测试、45项Playwright测试及六个真实页面流程通过。
- 回档：标签`xiaobai-preservation-slice-03-20260731`。
- 完整证据：`docs/migration/evidence/slice-03/README.md`。

已完成切片：`slice-04-ladder-rotation`。

- 原版基线：提交`b3555d2`，即切片03回档点。
- 迁移范围：2个板块轮动服务方法；市场天梯继续使用切片02已归位的原Tushare数据构造实现。
- 兼容边界：`DashboardService`通过`RotationServiceMixin`保持所有原调用；天梯不制造空服务或第二套计算。
- API与错误：天梯与9日轮动历史JSON完全一致；成分股两版均返回同一Tushare外部失败语义。
- 验收：252项Python测试、4项切片源码等价测试、45项Playwright测试及两个真实页面流程通过。
- 回档：标签`xiaobai-preservation-slice-04-20260731`。
- 完整证据：`docs/migration/evidence/slice-04/README.md`。

已完成切片：`slice-05-auction-themes-popularity-dragon-tiger`。

- 原版基线：提交`814e757`，即切片04回档点。
- 迁移范围：共享市场洞察服务、竞价/题材/人气入口、龙虎榜与游资档案服务、7个相关持久化方法。
- 兼容边界：根级`market_insights.py`保留同一类对象别名；竞价与人气共用候选热度逻辑，不复制第二套实现。
- API与数据库：7个真实API逐字段一致，仅排除每次请求必然变化的`request_id`；62个schema对象与5张关键表完全一致。
- 验收：258项Python测试、6项切片源码等价测试、45项Playwright测试及四个真实页面流程通过。
- 回档：标签`xiaobai-preservation-slice-05-20260731`。
- 完整证据：`docs/migration/evidence/slice-05/README.md`。

已完成切片：`slice-06-screener-custom-tracking`。

- 原版基线：提交`cf2aad2`，即切片05回档点。
- 迁移范围：完整选股引擎、29套高级策略、策略编译器、13个页面服务方法、25个持久化方法及持续跟踪。
- 兼容边界：三个根级模块指向正式模块对象；选股引擎保留原版数据客户端依赖，不为通过边界测试改写算法。
- API与数据库：3个真实API业务JSON一致；62个schema对象和13张关键表逐行一致。
- 验收：原版231项、迁移版265项Python测试、7项切片源码等价测试、45项Playwright及四个真实工作区通过。
- 回档：标签`xiaobai-preservation-slice-06-20260731`。
- 完整证据：`docs/migration/evidence/slice-06/README.md`。

已完成切片：`slice-07-mentor-skills-llm-streaming`。

- 原版基线：提交`4bab921`，即切片06回档点。
- 迁移范围：问师Agent、Skill注册表、8个服务方法、5个持久化方法、模型解析、额度、回退、流式累积器和调用审计。
- 兼容边界：根级`mentor_agent.py`和`llm_stream.py`指向正式模块对象；系统管理继续独占模型池配置。
- API与数据库：2个真实API完全一致；62个schema对象及5张关键表逐行一致；190个公开Skill文件哈希一致。
- 验收：原版231项、迁移版273项Python测试、8项切片源码等价测试、45项Playwright及真实问师页面通过。
- 回档：标签`xiaobai-preservation-slice-07-20260731`。
- 完整证据：`docs/migration/evidence/slice-07/README.md`。

已完成切片：`slice-08-heaven-trend-fortune-heart`。

- 原版基线：提交`2919229`，即切片07回档点。
- 迁移范围：问天Agent、历法/卦象引擎、20个服务方法、5个持久化方法及3个HTTP入口。
- 兼容边界：根级`heaven_agent.py`和`heaven_engine.py`指向正式模块对象；原动画、DOM、JS与CSS未改动。
- API与数据库：6个固定输入真实API完全一致；62个schema对象及6张关键表逐行一致。
- 验收：原版231项、迁移版280项Python测试、7项切片源码等价测试、45项Playwright及1080P三模式动画页面通过。
- 回档：标签`xiaobai-preservation-slice-08-20260731`。
- 完整证据：`docs/migration/evidence/slice-08/README.md`。

已完成切片：`slice-09-review-watchlist-notes-journal-alerts-assistant`。

- 原版基线：提交`b3df070`，即切片08回档点。
- 迁移范围：复盘助手Agent、5个提醒编排方法、8个复盘编排方法、19个持久化方法及5个HTTP入口。
- 兼容边界：根级`assistant_agent.py`指向正式模块对象；提醒与交易日志旧服务继续作为唯一底层实现；包导出采用延迟加载以切断初始化循环。
- API与数据库：5个固定输入真实API完全一致；62个schema对象及8张关键表逐行一致。
- 验收：原版231项、迁移版287项Python测试、7项切片源码等价测试、45项Playwright及1920×1080会员/非会员真实页面通过。
- 回档：标签`xiaobai-preservation-slice-09-20260731`。
- 完整证据：`docs/migration/evidence/slice-09/README.md`。

已完成切片：`slice-10-frontend-shell-pages-components-css-mobile`。

- 原版基线：提交`38de3de`，即切片09回档点。
- 迁移范围：完整前端DOM、9,283行运行时、页面脚本、共享脚本、七层CSS、问天加载动画、供应商资产及移动端规则。
- 兼容边界：运行时只切换静态根目录和资源路径；原DOM、样式、动画及JS源码内容不重写。
- 源码证明：原`app.js`与全部拆分片段重组后的SHA-256均为`c020d0bc68f8a96b352a0ffa62c913a0ea3f5ca0afc41f70969f833e447166a6`。
- API与数据库：21个全站只读API全部一致；62个schema对象和21张关键表逐行一致。
- 验收：85项前端专项、原版231项、迁移版294项Python测试、45项Playwright（2.3分钟），以及1920×1080日间/夜间、390×844移动端和问天动画真实浏览器差分通过。
- 验收限制：同主机不同端口共享登录Cookie，双服务比较必须逐服务重新登录；动态动画帧、焦点和状态文字不以截图文件哈希作为唯一标准。
- 回档：标签`xiaobai-preservation-slice-10-20260731`。
- 完整证据：`docs/migration/evidence/slice-10/README.md`。

自动验收完成、等待人工确认的切片：`slice-11-uncertain-code-audit-final-acceptance-handoff`。

- 原版基线：提交`dec3cd12365df5e7d4c391369f14c457cf56d7d9`，即切片10回档点。
- 审计范围：`demo_data.py`、旧问天加载动画、5个无引用前端函数及`wencai_saved_queries`兼容责任。
- 处置：前3类进入可单项回档的候选试删；`wencai_saved_queries`表和方法因旧库兼容与用户隔离继续保留。
- 保护方式：全部历史前端源码测试统一使用审计白名单比较，只允许登记的原`app.js`行号缺失，其他差异仍会失败。
- API与数据库：21个全站只读API全部一致；62个schema对象和21张关键表逐行一致。
- 验收：原版231项、迁移版298项Python测试、24个JavaScript语法检查和45项Playwright（1.6分钟）通过；桌面日间/夜间、390×844五个移动入口和问天三页真实检查通过。
- 部署边界：未改正式数据库、`.env`、`8765`、Docker或NAS；原版仍是正式运行基线。
- 候选回档：标签`xiaobai-preservation-slice-11-candidate-20260731`；试删最终结论仍等待用户人工确认。
- 完整证据：`docs/migration/evidence/slice-11/README.md`。
- 维护交接：`docs/migration/人工维护与本地切换指南.md`。

## 决策记录

| 日期 | 决策 | 原因 |
|---|---|---|
| 2026-07-30 | 原版运行行为优先，规格书只用于盘点 | 防止再次依据文字重新开发 |
| 2026-07-30 | 不使用`next/`作为后续迁移起点 | 用户确认其视觉、布局和基础功能不可用 |
| 2026-07-30 | 目标结构确认前不创建业务目录 | 防止目录先行后再次补写功能 |
| 2026-07-30 | 目标目录确定为`app/` | 使用长期正式名称，不再建立新的版本式重写目录 |
| 2026-07-30 | 先建立原样可运行副本，再迁移目录职责 | 保证整理的是原件，而不是依据规格书重新实现 |
| 2026-07-30 | 不确定代码进入待删账本并延迟试删 | 删除必须能够单独回档并经自动与人工验收 |

## 恢复工作检查

- [x] 已阅读`AGENTS.md`与保真迁移总纲。
- [x] 已读取状态JSON和本账本最后一项。
- [x] 已确认Git工作区和基线提交。
- [x] 已确认没有修改`next/`或正式数据。
- [x] 已说明当前切片及新旧等价证据。
- [x] 已在编辑前确认没有未关闭差异。