# 小白复盘人工维护与本地切换指南

> 适用目录：`webapp/app/`
> 当前状态：迁移候选已完成自动验收，尚未获得最终人工验收，不得替换正式部署

## 1. 先确认哪个版本是正式版本

- 当前正式基线仍是`webapp/`根目录及根目录`data/review.db`。
- `webapp/app/`是保真迁移候选，运行代码来自原版的移动、机械拆分和去重，不是重新开发。
- `webapp/next/`是已否决的冻结版本，禁止部署、继续开发或复制实现。
- 用户人工验收前，不要删除根级原版，不要让`app/`写入正式数据库，也不要修改NAS容器。

发生产品含义冲突时，依次以用户明确决定、原版真实运行、原版源码与数据、产品规格书为准。

## 2. 迁移版目录怎么找代码

```text
app/
  server.py                 进程兼容入口；正式实现装配在backend/
  backend/bootstrap/        路径、环境、配置、依赖组装和HTTP服务器
  backend/http/             鉴权、路由元数据、响应与静态资源传输
  backend/features/         按产品领域组织的服务和Repository
  backend/data/             数据网关、质量策略、实时聚合和供应商适配
  backend/database/         SQLite连接、schema和组合Repository
  backend/jobs/             后台任务定义、状态、调度与重试
  backend/llm/              所有模型调用、流式传输、额度与审计边界
  frontend/shared/          API、状态、Shell、组件和跨页能力
  frontend/pages/           每个产品页面的原版行为；问天样式也在对应目录
  frontend/styles/          原版七层样式和共享令牌
  config/                   页面、功能、API、任务、字段和数据质量注册表
  tests/                    单元、边界、保真差分和浏览器回归
  tools/                    清单、API/数据库差分和保真运行工具
  data/                     运行数据库、私有Skill和备份；不提交Git
  游资skills/               可公开的问师Skill
```

根级`app/*.py`多数是兼容导入壳。维护业务时先到`backend/features/<领域>/`找正式实现，
不要在兼容壳中新增第二套逻辑。所有浏览器网络请求必须继续经过
`frontend/shared/api.js`，所有LLM调用必须继续经过`backend/llm/`。

## 3. 本地隔离启动

不要直接拿正式数据库做迁移验收。先创建一个目录并用SQLite backup API生成一致副本，或使用
`app/data/backups/`中专门的验收副本。然后在`webapp`根目录运行：

```powershell
python -u app\tools\run_preservation_runtime.py `
  --runtime-root app `
  --data-dir app\data\backups\manual-acceptance `
  --port 8797
```

浏览器打开`http://127.0.0.1:8797/`。该命令不占用正式`8765`，并把数据库、私有Skill和
运行写入限制在指定测试目录。验收完成后先停止该进程，再处理测试副本。

## 4. 每次改动的最低流程

1. 阅读`AGENTS.md`、保真迁移状态、迁移账本和对应领域测试。
2. 从`config/pages.config.json`与`features.config.json`确认页面、功能和权限边界。
3. 只修改一个完整领域路径；不要同时在兼容壳和正式模块写实现。
4. 新增API时同步检查`config/api.config.json`及`backend/http/`的权限元数据。
5. 用户私有表必须包含并按`user_id`查询，补充跨账号隔离测试。
6. 行情字段必须登记来源、时间、单位、复权、新鲜度和降级规则，不允许静默换源。
7. 先跑领域测试，再跑下面的全量门槛，最后用真实浏览器检查桌面、夜间和移动端。
8. 更新迁移/维护文档后再提交；一个可回档节点只包含一个可以独立解释的改动。

## 5. 全量验证命令

原版基线：

```powershell
cd webapp
python -m unittest discover -s tests -q
```

迁移版：

```powershell
cd webapp\app
python -m unittest discover -s tests -q
npx.cmd playwright test --reporter=dot
```

JavaScript和Git差异：

```powershell
cd webapp\app
$files = Get-ChildItem frontend -Recurse -Filter *.js
foreach ($file in $files) { node --check $file.FullName }
cd ..
git diff --check
```

Playwright需要能够启动本机无头Edge。若测试停在浏览器启动前且没有`msedge`进程，先检查执行
环境是否禁止GUI/无头浏览器进程；这不是页面失败，不要通过删除测试或延长产品超时绕过。

API和数据库差分工具：

```text
app/tools/compare_preservation_apis.py
app/tools/compare_preservation_databases.py
```

运行前先查看脚本参数，并使用同一时点生成的原版/迁移版数据库副本。任何`all_equal=false`都应
阻止提交和切换。

## 6. 数据、密钥和私有内容

- SQLite数据库与`.env`中的`APP_ENCRYPTION_KEY`必须成对备份；密钥丢失后不能恢复加密字段。
- `data/private-mentor-skills/`只属于管理员本机/服务器，不进入Git和Docker镜像。
- 不要用文件管理器复制正在写入的`review.db`；使用SQLite backup API或停服后复制。
- 不要把Tushare、iFinD、LLM Token、账号密码、数据库副本或私有Skill提交到仓库。
- 切换期间只有一个数据库可以成为写入主库，禁止让原版与迁移版长期各写一份后再人工合并。

## 7. 人工验收清单

- 用同一账号、日期和主题对照原版与迁移版全部页面。
- 检查日间/夜间、1080P/4K、390像素移动端和浏览器缩放后的滚动与弹窗。
- 检查图表悬浮、股票/板块/题材/指数详情、全局搜索和日期切换。
- 检查选股三个工作区、策略跟踪、刷新后结果保持和候选来源隔离。
- 检查问师流式回答只出现一次、置顶排序、历史和会员限制。
- 检查问天三页全部过场、呼吸/铜钱、加载动画、历史和解读结果。
- 使用两个账号检查自选、笔记、交易日志、提醒和对话互不可见。
- 检查系统管理、会员期限、模型池、数据回补和后台任务状态。

人工验收发现差异时，记录页面、账号、日期、主题、视口、输入和截图；先对照原版复现，再判断
是迁移回归还是原版既有问题。

## 8. 获得批准后的本地切换方案

以下只是准备步骤，本次迁移没有执行：

1. 停止原版和迁移版进程，确认没有后台任务继续写库。
2. 对根目录正式数据库执行SQLite一致性备份，同时备份`.env`和私有Skill。
3. 把同一份最新正式数据恢复到`app/data/`，保持原`APP_ENCRYPTION_KEY`不变。
4. 在非`8765`端口启动`app/server.py`并完成健康、登录、关键页面和写入冒烟测试。
5. 记录切换提交、数据库备份位置和启动时间后，才把正式入口指向`app/`。
6. 切换观察期内保留根级原版和切换前数据库，只允许迁移版写主库。

Docker/NAS切换应以`app/`作为构建上下文，另行执行构建、卷挂载、权限、健康检查和回退演练。
本轮没有进行这些操作。

## 9. 回退方案

若切换后出现问题：

1. 立即停止迁移版，避免继续写库。
2. 保存故障日志和当前数据库副本用于调查。
3. 恢复切换前成对备份的`review.db`与`.env`。
4. 从切换记录指定的原版提交重新启动根级`server.py`。
5. 验证登录、健康接口、最近交易日、私有数据和模型配置后恢复使用。

切片11试删可从`xiaobai-preservation-slice-10-20260731`单项恢复；不要用破坏性的Git重置覆盖
正式数据或用户未提交的代码。