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