From 8abfd6538c905c6465127c892f523419833fb050 Mon Sep 17 00:00:00 2001 From: Simon Date: Wed, 9 Sep 2026 07:01:10 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=88=B6=E5=AE=9A=E6=9E=B6=E6=9E=84=20?= =?UTF-8?q?v3=20=E4=B8=8B=E9=98=B6=E6=AE=B5=E5=BC=80=E5=8F=91=E8=AE=A1?= =?UTF-8?q?=E5=88=92=EF=BC=88DEV=5FPLAN=5Fv3=EF=BC=8CChart/Signal=E2=86=94?= =?UTF-8?q?Fill/=E4=B8=AA=E8=82=A1=E9=A1=B5=E4=B8=BB=E7=BA=BF=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/DEV_PLAN_v3.md | 172 ++++++++++++++++++++++++++++++++++++++++++++ docs/ROADMAP.md | 2 + 2 files changed, 174 insertions(+) create mode 100644 docs/DEV_PLAN_v3.md diff --git a/docs/DEV_PLAN_v3.md b/docs/DEV_PLAN_v3.md new file mode 100644 index 0000000..4e9fcd7 --- /dev/null +++ b/docs/DEV_PLAN_v3.md @@ -0,0 +1,172 @@ +# 下阶段开发计划（架构 v3 · Chart Service / Signal↔Fill / 个股研究页 主线） + +> 依据：[ARCHITECTURE_v3.md](./ARCHITECTURE_v3.md)（新架构 v3）、[AGENT.md](../AGENT.md)（约束）、 +> [DEV_PLAN_v2.md](./DEV_PLAN_v2.md)（M6–M8 已执行完毕）、代码现状（2026-09，MySQL 已为默认库）。 +> 本文件回答：**v3 相对已落地能力的增量是什么、下一阶段做什么、按什么顺序。** + +--- + +## 0. 现状 vs v3（已完成清单） + +**数据库**：MySQL（qlib@192.168.1.10）默认，15 张业务表，Alembic head `e1f2a3b4c5d6`； +SQLite→MySQL 迁移数据 16,057,265 行校验一致（M-DB）。 + +**研究/选股主线（M6–M8 已完成）**： + +| 能力 | 落地位置 | v3 对应 | +|---|---|---| +| Universe 过滤（ST/上市天数/退市/白名单/as_of） | `quant/universe.py` | §14/§20 范围 | +| Selection：A 条件 + B 因子评分，当前/历史 as_of，可解释 | `quant/selection.py`、`selection_service` | §14/§22.1 | +| 选股结果落库 + `/api/selections` | `selection_snapshot/selection_result` | §8 | +| 回测与选股共用评分引擎（一致性测试锁定） | `quant/composite.build_score_panel` | §26 | +| 因子目录入库 + 组合落库 CRUD | `factor_definition`、`factor_composite` | §11/§13/§8 | +| 行情口径显式化（price_adjustment，研究默认不复权） | Repository `adjust` 过滤 | §20.5 前半 | +| Signal 规则引擎 + 落库 + `/api/signals` + Web 页 | `signal_snapshot/signal_event` | §15/§8 | +| Portfolio v1（等权；约束字段预留+如实标注） | `quant/portfolio.py` | §16 子集 | +| Strategy 命名资产 + `/api/strategies`（expand） | `strategy` 表 | §17 | +| Experiment/Job/SSE、Web 六页+选股/信号页 | — | §19/§23/§27 | +| Agent 10 工具 | `agent/tools_impl.py` | §25 子集 | + +**v3 主要增量（下一阶段目标）**： + +1. **Chart Service / 统一可视化**（§20/§21）：后端 Chart DTO + Chart API；前端 K 线等图表 + （推荐 TradingView Lightweight Charts）；**前端只展示、不重算**选股/信号/成交。 +2. **Signal 与 Actual Fill 严格区分并同图呈现**（§20.3/§22.3）：`signal_event`（策略信号） + 与 `backtest_trade`（实际成交）分别标记；回测结果补 `selection_history / signal_history / fills`。 +3. **Stock Research Page**（§20.4）：单只股票的 K 线 + 事件标记 + 技术指标 + 选股/信号/成交明细 + + 因子/理由的一站式页面。 +4. **A 股复权与回测价格口径**（§20.5）：图表显示价（不复权/前复权/后复权）与回测执行价 + 分开记录（`adjust_mode / price_basis / execution_price_basis`），必要时坐标转换。 +5. **Bar Replay**（§20.6，第二阶段）。 +6. **数据/规则底座补全**（§4/§8）：行业、指数与**历史成分**、停牌、ST 名单等同步 + （支撑 survivorship-bias-free Universe 与回测真实性）。 +7. **研究与模型增强**：因子相关性/暴露分析、Model Service（选股模式 C）、组合约束执行。 + +--- + +## 1. 下一阶段主线：M9 可视化与成交口径（对齐 v3 新重点） + +> 目标：把已能产生的 Selection / Signal / Backtest 结果变成**同一时间轴上、可解释、 +> Signal↔Fill 分明**的个股与组合视图。前端一律消费 Chart API 的 ChartResult（v3 §20.1）， +> 禁止前端自行重算。 + +### 1.1 Chart DTO 与 Chart Service（后端先行） + +- Domain `chart.py`：`ChartResult{symbol, name, adjust_mode, bars[], volume[], indicators{}, + selections[], signals[], fills[], holding_periods[], strategy_scores{}, factor_values{}, + benchmark{}, metadata{adjust_mode, price_basis, execution_price_basis}}`（v3 §20.2 结构）。 +- `application/services/chart_service.py`：只做**聚合与坐标整理**，不重算 Selection/Signal/Backtest + —— 输入来自各 engine/Repository 的既有结果。 +- API（v3 §20.2）： + - `GET /api/stocks/{symbol}/chart?range=&adjust=none|qfq`（K 线 + 量） + - `GET /api/stocks/{symbol}/signals` / `/selections`（该股参与过的信号/选股历史） + - `GET /api/backtests/{experiment_id}/stocks/{symbol}/chart`（回测视图：fills/holding） + - `GET /api/backtests/{experiment_id}/trades`、`/positions`（回测成交/持仓展开） +- 验收：Chart API 返回结构与 v3 §20.2 一致；K 线与 fills 价格位于同一坐标系。 + +### 1.2 回测结果补 selection_history / signal_history / fills（Signal↔Fill 区分） + +- `BacktestResult` 扩展（v3 §22.3）：`selection_history`（各调仓日选出的候选与排名）、 + `signal_history`（每期信号）、`fills`（实际成交记录：symbol/date/side/price/qty/cost/费/ + reason：signal→fill 或 被拒 reason）。 +- 引擎层：`TopKBacktestRunner` 调仓过程把「目标候选（Selection 视图）」「信号意图」与 + 「实际成交（扣除涨停/停牌/现金后的 Fill）」三份记录输出；既有一致性测试保持通过 + （重构不改默认策略语义）。 +- 前端标记语义：`BUY SIGNAL / SELL SIGNAL`（虚线）vs `EXECUTED BUY / EXECUTED SELL`（实心）， + 点击可见 signal→fill 或未成交原因。 +- 验收：回测里被涨停拦下而未成交的 Buy 意图在 UI 上可见且说明原因；默认回测数值回归一致。 + +### 1.3 K 线 Chart 组件（前端） + +- 引入图表方案：按 v3 推荐优先 **TradingView Lightweight Charts** + （npm 走 AGENT.md §0 代理）；若安装受限则回退 ECharts candlestick（依赖已有），组件层隔离 + 便于替换。 +- `components/StockChart/`：K 线 + 成交量 + 事件标记（signals/fills/selections）+ 技术指标开关 + （MA/MACD/RSI 至少 MA）。 +- 验收：同一 K 线上信号与成交用不同 marker；tooltip 显示价格/原因；tsc 通过。 + +### 1.4 Stock Research Page（个股研究页） + +- 新路由 `/stocks/[symbol]`（v3 §20.4 版式）：头部（代码/名称/当前信号/分数）→ K 线主图 → + 量 → 指标 → 明细表（selection/signal/trade，可点开原因）→ 因子值与理由 → 风险标注。 +- 数据全部来自 1.1/1.2 Chart API；股票池页每行可跳入本页。 +- 验收：任一有数据的股票可完整浏览「为什么信号/选股/成交」；无数据/停牌显示占位。 + +### 1.5 复权口径落地（图表显示价 vs 回测执行价） + +- Chart `adjust=none|qfq|hfq`：qfq/hfq 基于 `adjust_factor` 现算（不落地新行情）； + 回测执行保持研究主口径（`price_adjustment`，默认不复权）并写入 + `metadata.execution_price_basis`。 +- 图表与成交若口径不同由 Chart Service 做坐标换算（K 线同样复权到执行价基准，保证 marker 对齐）。 +- 验收：对发生过除权（有 adjust_factor）的股票，切换显示口径后 fills 仍贴合 K 线。 + +### 1.6 Bar Replay（第二阶段，置于 M9 尾部可选） + +- 按 as_of 逐日回放，仅用当时可得数据（复用 `resolve_observation_date`/repository `adjust` 过滤）， + 检查未来函数与 Selection/Signal 一致性。阶段验收：选定区间重放与静态回测结果一致。 + +--- + +## 2. 支撑线 B：数据与规则底座补全（为真实性与 Survivorship-free Universe） + +> 与 M9 并行、按需插入（不阻塞主线首个可用版本）。 + +| 任务 | 内容 | 验收 | +|---|---|---| +| B1 行业/指数/成分同步 | 新增 Tushare Provider + Repository 表 `industry / stock_industry / index / index_daily / index_constituent_history`（历史成分，v3 §9/§30 红线） | 指数成分可查历史某日名单；universe 支持「按指数成分」过滤并回测可用历史名单 | +| B2 停牌与 ST 名单 | `suspend_data / stock_st_data` 表 + 同步 + Repository；研究侧 `exclude_suspended`/ST 口径落地（不再仅当前名称快照） | Selection/回测的 ST/停牌处理基于 as_of 当日名单；一致性测试更新 | +| B3 财务扩展 | `income_statement / balance_sheet / cashflow_statement`（按 announce_date 版本化） | 条件选股可用更多 fundamental 字段（严格 announce 可见） | +| B4 研究结果结构化 | `factor_test` 结果落库；`selection_rule / signal_rule / universe` 由 JSON 快照升级为实体表（沿用现有 selection/signal 快照思路） | 历史查询/复用不再依赖解析 JSON；迁移测试通过 | + +--- + +## 3. 支撑线 C：研究与模型增强 + +| 任务 | 内容 | 验收 | +|---|---|---| +| C1 因子相关性/暴露 | Factor Research 增加因子相关性矩阵、行业/市值暴露、不同市场阶段统计（v3 §12） | 因子研究页展示 ≥2 因子相关性与暴露；单测 | +| C2 Portfolio 约束执行 | Portfolio v1.1：单股上限、行业上限、现金管理的实际权重分配（约束默认关保持向后兼容） | 开启约束的回测满足约束且结果 unimplemented 移除对应项 | +| C3 Model Service / 选股模式 C | qlib_adapter feature(Alpha158 子集)+model(LightGBM walk-forward，seed 固定)→预测分；Selection `method=model`（v3 §14.1C） | 模式 C 可选通（样本外 walk-forward 报告）；不阻塞主线 | + +--- + +## 4. 支撑线 D：基础设施与 Agent + +| 任务 | 内容 | 验收 | +|---|---|---| +| D1 Job stage 上报 + SSE 长连 | executor 写入 stage（data_loading/factor_calculation/selection/signal/backtesting…，v3 §23）；SSE 由 0.4s 轮询改事件推送；Job 列表/取消 API | 前端进度显示阶段名；取消可生效 | +| D2 全市场研究 Job 化 | 全市场选股/信号/因子研究统一走异步 Job（当前同步 60s+） | Web 选股页异步提交并轮询/SSE | +| D3 Redis（可选触发） | 本机 127.0.0.1:6379：Job 队列 / SSE pub-sub / 因子缓存（DEV_PLAN_v2 §7 触发点） | 按触发点启用并说明收益 | +| D4 Agent 工具补齐 | 按 v3 §25：`inspect_factor / create_composite_factor / get_backtest_result / create_experiment`（现 10 → 14） | Agent 编排用例通过；白名单不变式 | + +--- + +## 5. 建议执行顺序（前 8 个 commit 序列） + +每步遵循：Domain → Repository Protocol → Infra(Model→Migration→Repo) → Service → API → 前端 → +测试（相关模块）→ 更新文档；改结果结构先跑一致性回归，禁止悄悄改策略语义（v3 §26）。 + +1. **1.1 Chart DTO + Chart Service 骨架**（含复权坐标元数据）：定义 ChartResult、股票 + chart/信号/选股只读 API（数据来自现有 repo/engine）。验收：ChartResult 结构对齐 v3 §20.2。 +2. **1.2 回测补 selection_history/signal_history/fills**：引擎输出三份记录；默认回测数值 + 逐项一致回归（v3 §28 Selection/Signal Consistency）。验收：涨停未成交意图可见。 +3. **1.3 前端 K 线组件**（lightweight-charts 或 ECharts candlestick 兜底）+ marker。 + 验收：同图 signal↔fill 标记可辨、可点开原因。 +4. **1.4 Stock Research Page `/stocks/[symbol]`**：接入 1.1/1.2 API。验收：闭环页面可用。 +5. **1.5 复权口径落地**：Chart adjust 切换 + 坐标换算。验收：除权股 marker 对齐。 +6. **B1 行业/指数/历史成分同步 + Universe 成分过滤**（survivorship 红线）。 +7. **B2 停牌/ST 名单落地**（研究口径从名称快照升级为名单）。 +8. **C2/C1 组合约束执行 与 因子相关性**（二选一先做，另一项随后）。 + +之后：B3/B4 → 1.6 Bar Replay → C3 模型选股 → D1–D4 基础设施/Agent。 + +--- + +## 6. 风险与注意 + +- **重构保一致**：BacktestResult/引擎扩展时以默认配置数值一致回归为门禁（v3 §26/§28）。 +- **口径混用**：研究执行默认不复权；图表 qfq/hfq 仅在显示层换算 —— 严禁把 qfq 显示价写回研究数据。 +- **未来函数**：历史成分/停牌/ST 均须 as_of 当日名单（v3 §9/§30）；Chart/Replay 只消费 <=as_of。 +- **前端不重算**：所有 selection/signal/fill 标记来自后端 DTO；图表库选择尽量可替换。 +- **范围控制**：M9 不引入实盘、分布式、复杂表达式引擎；Bar Replay/模型选股按需推进。 +- **MySQL 收尾**（沿用 DEV_PLAN_v2 §2 遗留表）：大结果 MEDIUMTEXT、Repository 批量压测、MySQL 集成冒烟开关。 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 7504443..2af31bf 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -6,6 +6,8 @@ > （选股系统为主线：Universe 选股范围 + Selection Engine A条件/B评分 + 结果落库/API + > 回测共用引擎 + Web 选股页 → M7 因子层 → M8 Signal/Portfolio/Strategy/Agent） > 2026-09 增补：数据库已切 MySQL（见 M-DB 行），本文件 M0–M5 为历史记录，新计划以 DEV_PLAN_v2 为准。 +> 2026-09：M6–M8（DEV_PLAN_v2）已完成；**下一阶段按 [docs/DEV_PLAN_v3.md](./DEV_PLAN_v3.md)** +> （v3：Chart Service / Signal↔Fill / 个股研究页 / 复权口径 / 数据底座）。 ---