小白复盘人工维护指南

1. 正式边界

app/是唯一正式源码和运行目录。父目录旧程序与失败的next/不属于应用依赖，也不得作为后续实现来源。产品规格位于docs/product/，历史迁移证据位于docs/migration/。

2. 目录定位

server.py                  进程入口
backend/bootstrap/        配置、依赖组装和启动
backend/http/             鉴权、响应和公共HTTP能力
backend/features/         按产品领域组织的服务、路由和Repository
backend/data/             数据网关、质量规则和供应商适配
backend/database/         SQLite连接、迁移和Repository组合
backend/jobs/             后台任务、状态、锁与重试
backend/llm/              模型选择、鉴权、额度、流式和审计
frontend/shared/          API、状态、Shell和公共组件
frontend/pages/           页面结构、行为和页面样式
config/                   页面、功能、API、任务和数据字段注册表
data/                     正式数据库和私有数据，不进入Git
runtime/                  日志、PID、缓存和测试产物，不进入Git
tests/                    单元、契约、边界和浏览器回归
tools/                    启动、注册表生成和统一验收工具

3. 本地启动

cd app
python -m pip install -r requirements.txt
powershell -ExecutionPolicy Bypass -File tools/start_local.ps1 -Port 8797

日志、PID和Python缓存写入runtime/。前台启动可使用：

python server.py --host 127.0.0.1 --port 8797

4. 修改流程

阅读AGENTS.md、ARCHITECTURE.md、相关注册表和测试。
找到职责唯一所有者，不建立转发层或临时补丁文件。
保持API、数据库、权限、数据口径和用户可见行为兼容。
行情字段必须登记来源、时间、单位、复权、新鲜度和降级规则。
用户私有数据必须包含并按user_id隔离。
先运行领域测试，再运行统一验收，最后做真实浏览器检查。

5. 自动验收

python tools/verify_baseline.py
python tools/verify_baseline.py --e2e

统一验收覆盖全部Python测试、API与架构注册表、JavaScript语法、Git空白检查和SQLite只读完整性； --e2e额外运行Playwright。前端改动还需人工检查日间/夜间、1080P/4K、移动端、滚动、弹窗、图表、问师流式结果和问天动画。

6. 数据与密钥

正式数据库固定为data/review.db。
.env中的APP_ENCRYPTION_KEY必须与数据库成对备份。
不要复制正在写入的SQLite文件；停服或使用SQLite backup API。
.env、Token、密码、数据库、私有Skill和运行日志不得提交Git或写入Docker镜像。
同一时刻只允许一个正式实例写主库。

7. 部署与回退

Docker以当前目录为构建上下文，持久化挂载./data:/app/data。升级前保存当前Git提交、数据库一致性备份和.env；升级后验证健康、登录、最近交易日、私有数据、数据源、LLM和关键写入流程。

出现问题时先停止新进程，保存故障日志和数据库副本，再恢复上一Git提交及其成对数据库和.env。不要使用破坏性Git命令覆盖未提交数据。

3.3 KiB Raw Permalink Blame History