sanguo_vnpy_v2/docs/superpowers/reports/2026-07-06-phase3a-web-api-completion.md

# 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**：组合回测（未规划）