refactor: establish standalone application boundary

2026-08-03 21:42:25 +08:00
parent 656f28a96d
commit d6def3af15
322 changed files with 73872 additions and 44656 deletions
@@ -0,0 +1,76 @@
+# 小白复盘人工维护指南
+
+## 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命令覆盖未提交数据。