docs(phase3a): Web API 完整化完成报告（8 task, 44+74 passed, NAS smoke 6/6, 已合并 master）

2026-07-06 20:22:54 +08:00
parent 1a05086aab
commit b2c2a1305b
1 changed files with 76 additions and 0 deletions
@@ -0,0 +1,76 @@
+# Phase 3a Web API 完整化 — 完成报告
+
+> **日期**: 2026-07-06
+> **分支**: `feat/web-api`（已 push gitea，b3cb6fd..4723554，11 commits）
+> **前置**: Phase 1 数据层 + Phase 2 因子/回测层（已 DONE）
+> **spec**: `docs/superpowers/specs/2026-07-06-phase3a-web-api-design.md`
+> **plan**: `docs/superpowers/plans/2026-07-06-phase3a-web-api.md`（8 task）
+
+## 一句话结论
+
+Phase 3a 后端完整化全部完成：8 task 通过 subagent-driven（每 task fresh implementer + review），74 容器测试 + 44 本地测试全绿，覆盖率 81%，NAS 容器冒烟 6/6 PASS，三向一致性检查通过，成果物已 push gitea。
+
+## 业务目标达成（spec §0 五项）
+
+| # | 目标 | 体验意义 | 实现 | 状态 |
+|---|------|---------|------|------|
+| ① | 回测异步化 | 提交回测立即返回、后台跑，不卡主进程 | T3 pool(spawn PPE) + T4 runner async submit + wrap_future bridge | ✅ |
+| ② | WS 阶段进度推送 | 实时看任务跑到哪步（排队/回测中/完成） | T2 ConnectionManager + T5 app `_on_stage` broadcast + WS route | ✅ |
+| ③ | JWT 单用户登录 | 账号密码登录拿 token，业务接口鉴权 | T1 auth.py（bcrypt 直调）+ T5 routes `Depends(verify_token)` + login | ✅ |
+| ④ | alpha tears 完整化 | 因子分析出完整 alphalens 报告（IC/分层） | T6 compute_factors + T7 tears pipeline（real alphalens API） | ✅ |
+| ⑤ | optimize/factor 路由补完 | optimize/factor 接口真正调 orchestrator | T5 async routes await orchestrator | ✅ |
+
+不做清单遵守：✅ 不引 Qlib/Celery；✅ 不做组合回测/多用户/Vue 前端（留 Phase 3b/4）。
+
+## 任务清单（subagent-driven，每 task implementer + reviewer）
+
+| Task | 内容 | Commit | Review |
+|------|------|--------|--------|
+| T1 | config + auth.py（JWT 单用户） | 2227a91 | Approved（1 Minor） |
+| T2 | ws.py（WS 连接池 ConnectionManager） | 48a9058 | Approved（1 Minor） |
+| T3 | pool.py 异步化（spawn PPE + stage） | 66aa27e | Approved（1 Minor — submit_work task_id 暂未用） |
+| T4 | runner.py async submit + on_stage | f5a69b3 | Approved（Minors — stage 文案/type hints/docstring） |
+| T5 | routes.py 完整（login+JWT+optimize/factor+WS route） | efaac41 | Approved（fastapi-reviewer，1 Minor） |
+| T6 | alpha_lab compute_factors | 8972d10 | Approved（2 Minor — 缓存无界/test polars top-import） |
+| T7 | analyzer tears pipeline | ff0d535 + 30897aa（fix） | Needs fixes→修复后 Approved（cumsum 警告 + report_paths dict + 异常类型） |
+| T8 | 端到端冒烟 + multiprocessing guard + 覆盖率 | effd3ca | — |
+| follow-up | auth passlib→bcrypt 直调（修容器登录） | 4723554 | — |
+
+关键修复：
+- **T7 review fix**：cumsum 兜底价格改为显式 `warnings.warn` + ic_summary 标记 `warning_unreliable_prices`；`report_path`（单值）→ `report_paths`（per-factor dict）；异常类型记入 ic_summary。
+- **T8 multiprocessing**：vnpy.alpha `AlphaDataset.prepare_data()` 起 `multiprocessing.Pool`，直接脚本调用需 `if __name__=='__main__'` guard。smoke 脚本加 guard 后真实 tears 端到端跑通。
+- **auth bcrypt**：passlib 1.7.4 probe `bcrypt.__about__.__version__`（新版 bcrypt 已移除）→ 容器登录失败。改 auth.py 直接用 `bcrypt.hashpw/checkpw`，本地+容器均工作。
+
+## 测试
+
+| 环境 | 范围 | 结果 |
+|------|------|------|
+| 本地 Mac Python 3.14 | tests/api + tests/orchestrator（mock，无 polars/alphalens） | **44 passed**, 81% coverage（api 94%/auth 92%/routes 76%/ws 89%；orchestrator pool+task 100%/runner 64%） |
+| NAS 容器 Python 3.10 | tests/api + tests/orchestrator + tests/factor + tests/backtest（真实 polars/alphalens/vnpy_ctastrategy） | **74 passed** |
+| NAS 容器 smoke | `scripts/smoke_phase3a.py`（sys.path/login/protected/orchestrator async/WS wiring/真实 tears） | **6/6 PASS** |
+
+容器需 `pytest-asyncio`（async 测试用），已 `pip install` 于容器内（生产运行用 smoke 脚本 asyncio.run，不依赖 pytest-asyncio）。
+
+## 三向一致性检查（需求 ↔ 设计 ↔ 编码）
+
+5 个业务目标 spec → design 组件 → code 实现 全对齐，无 CONSISTENCY_ISSUE。详见 progress.md。
+
+## 部署冒烟（NAS）
+
+- rsync 本机 → `/volume1/homes/admin/.sanguo_projects/sanguo_vnpy_v2`（容器 /app）
+- 容器 `sanguo_vnpy_v2` 全量测试 74 passed + smoke 6/6 PASS（含真实 factor tears 端到端 + JWT login）
+- 未改动容器端口/反向代理（https://vnpy.mysanguo.top 外网链路保持）
+
+## 已知限制（deferred Minors，不阻塞）
+
+- factor tears 的 `ic_summary` 仅记 status/report，未提取真实 IC 数值（alphalens merged_data 含 IC，留后续细化）
+- forward-return `periods=(1,5,10)` 硬编码（未配参）
+- `_loaded_bars` 缓存无界（单用户内部工具，规模小）
+- `submit_work(task_id, ...)` 的 task_id 暂未用（预留 logging）
+- 短 JWT test key 警告（仅测试，生产用长 secret）
+
+## 下一步
+
+- **merge feat/web-api → master**：待用户确认（Phase 2 时用户选「先 merge」）
+- **Phase 3b**：Vue 前端（未规划）
+- **Phase 4**：组合回测（未规划）