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

历史文档：记录迁移验收期间的双版本操作，已由docs/maintenance/人工维护指南.md取代。其中涉及父目录原版和迁移比较工具的命令不再作为当前维护流程执行。

适用目录：webapp/app/ 当前状态：本地迁移已完成自动与用户人工验收；正式数据库、Docker和NAS尚未切换

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

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

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

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

app/
  server.py                 稳定进程入口；正式实现装配在backend/
  database.py               SQLite初始schema与Repository组合入口
  api_access.py             API访问级别注册入口
  sync_data.py              手工行情同步命令
  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/           页面结构、行为与页面专属样式
  config/                   页面、功能、API、任务、字段和数据质量注册表
  tests/                    单元、边界、保真差分和浏览器回归
  tools/                    清单、API/数据库差分和保真运行工具
  data/                     运行数据库、私有Skill和备份；不提交Git
  runtime/                  本地日志、缓存、PID与浏览器测试产物；不提交Git
  游资skills/               可公开的问师Skill

根目录不再保留业务兼容导入壳。维护业务时直接到backend/features/<领域>/或 backend/data/寻找唯一实现，不得重新建立根级转发文件。所有浏览器网络请求必须继续经过 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. 人工验收清单

2026-08-01用户已在隔离端口8797完成全部页面和功能验收，确认视觉与功能迁移成功；所见问题几乎都属于原版遗留问题，未发现阻止验收的迁移回归。以下清单继续作为后续结构修改和部署切换时的回归标准：

用同一账号、日期和主题对照原版与迁移版全部页面。
检查日间/夜间、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重置覆盖正式数据或用户未提交的代码。

8.3 KiB Raw Blame History