# 小白复盘人工维护指南

## 1. 正式边界

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

## 2. 目录定位

```text
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. 本地启动

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

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

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

## 4. 修改流程

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

## 5. 自动验收

```powershell
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命令覆盖未提交数据。