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

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

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

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

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

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

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根目录运行：

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. 每次改动的最低流程

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

5. 全量验证命令

原版基线：

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

迁移版：

cd webapp\app
python tools\verify_baseline.py
python tools\verify_baseline.py --e2e

第一条命令已经包含迁移版全量单元测试、API/架构注册表新鲜度、全部前端JavaScript语法、 Git空白错误和测试数据库只读完整性检查。第二条额外运行Playwright。工具的日常/验收/迁移期分类见app/tools/README.md；迁移期工具不是正常开发命令。

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

API和数据库差分工具：

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. 获得批准后的本地切换方案

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

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

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

9. 回退方案

若切换后出现问题：

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

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

7.6 KiB Raw Blame History