Simon
82240e383d
- USAGE 新增 §6.3.1「归档的日常操作」：查看 / 筛选（回写 URL）/ 导出完整 JSON / 以此参数再跑 / 删除（写明「删除即失去结果，结果只存归档一份」）/ 历史归档用 restore_experiment_from_job 按原 id 重建；并说明归档完整度如何标注 - USAGE/README 更正技术栈与图表基座：TradingView Lightweight Charts 4.2.3 为唯一 图表基座（ECharts 已从 package.json、pnpm-lock.yaml、node_modules、文档与 架构图标注中全部清除），并记录实测证据（个股页图表根节点为 div.tv-lightweight-charts，页面 canvas 无一来自其它图表库） - ARCHITECTURE 更正「当前数据库」（原写 SQLite/未来 MySQL）：现为本机 MariaDB 10.11， §6 补目标库硬约束；USAGE 补服务器身份与实测连接证据 - AGENT.md 新增 §0.1：数据库目标只允许本机 MariaDB，禁止 192.168.1.10， 由 config.py::assert_db_target_allowed 硬拦截（命中直接抛错，不静默降级） - DEV_PLAN_DIVIDEND_BACKTEST 记录三轮实施与验证、归档恢复边界（§12.5）、已知限制 - DEV_PLAN v2/v3 标注为历史记录（避免把当时的远端库地址当现状照抄）； ROADMAP 更正 M3 图表选型
257 lines
18 KiB
Markdown
257 lines
18 KiB
Markdown
# 下阶段开发计划（架构 v2 落地 · 2026-09 · 选股系统为主线）
|
||
|
||
> 依据：[ARCHITECTURE_v2.md](./ARCHITECTURE_v2.md)（新架构 v2）、[AGENT.md](../AGENT.md)（开发约束）、
|
||
> 两份 2026-09 只读调研（后端研究/量化层、前端/Agent/数据层）与 docs/ROADMAP.md 的 M0–M5 记录。
|
||
> 本文件回答：**M5（AI Agent Phase 5）之后，下一阶段做什么、按什么顺序做。**
|
||
> 2026-09 更新（用户定调）：**下一阶段以「选股系统」为独立主线并提前执行**
|
||
> （原"研究层落地"后移为 M7 支撑），先交付可用的选股 MVP，再补因子层增强。
|
||
|
||
---
|
||
|
||
## 0. 当前状态与总判断
|
||
|
||
**已完成（M0–M5）**：数据层（Tushare 首选 + 新浪兜底 + 审计）→ ResearchSpec → 本地研究引擎
|
||
（9 个行情因子 / IC·分层评估 / 低频 TopN 等权回测）→ Job/Experiment 异步归档 → Web 六页 →
|
||
AI Agent（6 个受控 Tool）。**数据库已于 2026-09 从 SQLite 全量迁移至 MySQL**（见 §1）。
|
||
|
||
**对照 v2 的核心差距**（调研结论）：
|
||
|
||
1. **选股没有独立成系统**：v2 强调 Factor Research / Composite Factor / **Selection** / Signal /
|
||
Portfolio 分层；当前"选股"只是回测器内部 TopN 逻辑，无法单独回答 v2 §8 的两个核心问题：
|
||
「2023-08-15 为什么选这只股票」「2026-09-08 当前有哪些股票满足策略」。
|
||
2. **因子定义 / 策略等研究元数据未入库**：DB 只有 8 张表（stock / stock_daily / adjust_factor /
|
||
financial_indicator / trading_calendar / sync_log / job / experiment）；v2 §8 期望的
|
||
factor_definition / universe / selection_rule / selection_result / signal_rule / strategy 等全缺。
|
||
3. **口径与数据完整性风险待修**：研究链路不消费复权因子（stock_daily 混合 tushare 不复权与新浪前复权行）；
|
||
universe 用"当前名称含 ST"近似、无历史成分/停牌；Job.stage 从未赋值、SSE 是查库轮询。
|
||
4. **前端/Agent 待做实**：Selection/Signal 页面不存在；Agent 工具仅 6 个，
|
||
v2 §24 期望的 screen_stocks / explain_selection 等依赖尚未存在的选股引擎。
|
||
|
||
**阶段命名**：**M6 选股系统（主线）→ M7 因子层落地（支撑）→ M8 引擎延伸与平台化**。
|
||
数据库专项单独记 M-DB。
|
||
|
||
---
|
||
|
||
## 1. 执行状态（2026-09：M6–M8 主干已交付）
|
||
|
||
> M6 选股系统、M7 因子层、M8（Signal/Portfolio/Strategy/Agent 工具/Web）均已完成并提交
|
||
> （ROADMAP 里程碑行含 commit；每阶段全量 pytest + ruff + tsc 验证通过；Alembic 迁移已应用 MySQL）。
|
||
> M8.4 Qlib 模型选股（Selection 模式 C）为「按需」项，未阻塞主线 —— 当前延后，
|
||
> 前置：qlib_adapter 特征/模型链路（Alpha158 + LightGBM walk-forward），启用时按 §5.4 推进。
|
||
|
||
## 2. M-DB：数据库 MySQL 迁移（已完成，本文件记录收尾项）
|
||
|
||
**已交付（2026-09）**：
|
||
|
||
- MySQL（192.168.1.10:3306，MariaDB 10.11，库 `qlib`，utf8mb4）建 8 张业务表 + alembic_version，
|
||
> ⚠️ 历史记录：该地址已**禁止作为 DB 目标**，现为本机 MariaDB（`127.0.0.1:3306/qlib`），见 `AGENT.md` §0.1。
|
||
全部经 `alembic upgrade head`（迁移 e4d18825…53113c80…91c4e27a…d3f6c9a2），结构由既有 ORM 模型保证。
|
||
- `scripts/migrate_sqlite_to_mysql.py`：一次性工具 —— sqlite 直连 + pymysql chunk 多值 INSERT +
|
||
keyset 分页续传 + 幂等（已迁则跳过）+ `--verify-only` 逐表 COUNT 与抽样比对；支持 `--only <表>` 并行大表、
|
||
`--throttle-sec` 低配服务器节流。
|
||
- 配置：`config.yaml → database.mysql`（host/port/db/user/charset 明文），密码经 `.env` 的
|
||
`MYSQL_PASSWORD`（AGENT.md §33：密钥不进 config/git）；URL 优先级
|
||
`DATABASE_URL 环境变量 > config.yaml database.mysql > sqlite:///./data/quant.db 兜底`；
|
||
实现集中在 `backend/app/core/config.py::_build_mysql_url`，业务层零改动（DAO/Repository 隔离兑现）。
|
||
- 测试隔离：`backend/tests/conftest.py` 强制每进程 `/tmp/qlib-pytest-<pid>.db` SQLite（测试绝不触 MySQL）。
|
||
- 驱动：`pymysql>=1.1` 已入 `backend/pyproject.toml`。迁移数据量 16,057,265 行，`--verify-only` 校验全部一致。
|
||
|
||
**遗留收尾（小任务，可随时做）**：
|
||
|
||
| 项 | 说明 | 建议 |
|
||
|---|---|---|
|
||
| `job/experiment.result_json` 用 MySQL `TEXT`（≤65,535B） | SQLite TEXT 无上限、测试测不出 | 日级回测结果变长后改 `MEDIUMTEXT`（新 Alembic 迁移 + Model 类型 variant） |
|
||
| Repository 批量 upsert 在 MySQL 的压测 | `tuple_.in_()` 行值、`add_all` 单事务无分块 | 全市场日线增量同步跑一次，观察锁等待/包大小 |
|
||
| MySQL 路径无自动化测试 | 测试全 SQLite 方言 | 视需要加一个「连 MySQL 的集成冒烟」开关（默认关，显式 env 开启） |
|
||
| `scripts/migrate_sqlite_to_mysql.py` 属一次性工具 | 保留供重建目标库 | 文档标注不可再对生产执行（除 --verify-only） |
|
||
| 前端/文档残留 "SQLite" 文案 | app-shell / page.tsx / sync.py docstring | 随各页面改动顺手清理 |
|
||
|
||
---
|
||
|
||
## 3. 下阶段总路线
|
||
|
||
```text
|
||
M6 选股系统（主线） Universe 选股范围 + Selection Engine(A条件/B评分)
|
||
│ + 结果落库/API + 回测共用引擎 + Web 选股页
|
||
↓
|
||
M7 因子层落地 因子定义入库 + Composite 模块化 + 研究口径修复（支撑选股增强）
|
||
↓
|
||
M8 引擎延伸与平台化 Signal Engine → Portfolio Engine → Strategy / Agent / Qlib 模型选股
|
||
```
|
||
|
||
设计红线（贯穿）：v2 §25「历史回测与当前选股用同一套 Engine」、v2 §9 时间与未来函数防护、
|
||
v2 §26 Experiment 可复现、AGENT.md「简单优先 / 每阶段可运行 / 一个功能一个 commit /
|
||
先 Domain 后 UI / 带测试」。
|
||
|
||
---
|
||
|
||
## 4. M6：选股系统（下一阶段主线）
|
||
|
||
> 目标：交付一个**独立、可解释、支持当前与历史日期**的选股系统（v2 §14 Selection Engine），
|
||
> 让回测器与"现在该选什么"共用同一套引擎（v2 §25 一致性红线）。
|
||
> MVP 全部复用**现有数据与因子能力**（stock / financial_indicator / stock_daily + 9 个内置行情因子 +
|
||
> composite_score），不依赖 M7 因子层，因此可最先做、尽快见到"选股结果"。
|
||
|
||
### 3.0 选股输入输出契约（先定 Domain / DTO）
|
||
|
||
- Domain `SelectionSpec`（v2 §14.2）：`universe 范围 + filters(条件) + scoring(因子/复合因子/权重) +
|
||
ranking(TopN / Top%) + as_of_date`；沿用并扩展现有 `ResearchSpec` 的 universe/factors/selection 结构，
|
||
新增 `as_of_date`（缺省 = 最近交易日）。
|
||
- Domain `SelectionResult`（v2 §14.3/§21.1）：`as_of_date, universe, candidates[{symbol, rank, score,
|
||
factor_values, filter_status, selection_reason}], statistics` —— 作为前后端/Agent 统一 DTO。
|
||
- 核心用例：`selection_service.select(spec, as_of=...) -> SelectionResult`（历史/当前日期都可执行）。
|
||
- 验收：SelectionResult 进入 `frontend/web/lib/types.ts` 与后端 entity 一一对应。
|
||
|
||
### 3.1 Universe：选股范围（MVP 规则化）
|
||
|
||
- 把 `ResearchService.filter_stocks` 的过滤逻辑（market / exclude_st / min_listing_days /
|
||
delist_date < as_of / 可选 symbol 白名单）抽成可复用的 `UniverseFilter` 执行器，
|
||
输入结构化条件（Pydantic），输出 as_of 时点下的股票范围。
|
||
- MVP 不建 universe 大表：条件随 `SelectionSpec` 一起存入 `selection_snapshot`（快照 JSON，
|
||
可复现）；`universe / universe_rule / index_constituent_history` 表推迟到 M8 需要历史成分时再落。
|
||
- 明确近似并写进结果：ST 按当前名称快照判定；停牌/退市边界显式标注（unimplemented 或近似说明）。
|
||
- 验收：同一组条件在"当前日"与"历史日"分别得到正确范围（含历史日上市/退市过滤）；
|
||
现有回测 universe 语义不变（回归）。
|
||
|
||
### 3.2 Selection Engine：A 条件选股 + B 因子评分
|
||
|
||
- **A. 条件选股**：结构化条件过滤（示例：`roe > 15 且 pe… 且 close > ma60`），
|
||
条件作用于现有字段/派生指标：
|
||
- 静态/财务：`market / industry / eps / roe / total_revenue / net_profit / gross_margin…`
|
||
（财务值按 `announce_date ≤ as_of` 可见，防未来函数）；
|
||
- 行情/技术：`close > ma20 / ma60、momentum_20>0、volume_ratio…`（复用 factors.py 的 `compute_factor`）。
|
||
- MVP 条件用**结构化 JSON**（字段 + 比较符 + 值，可 and/or 嵌套），不做自由表达式 parser（避免提前造轮子）。
|
||
- **B. 因子评分选股**：`score = composite_score(截面 zscore × 方向 × 权重)`（抽取 local_engine 现逻辑），
|
||
按 score 排序取 `top_n` / `top_pct`；同时支持阈值过滤。
|
||
- **C. 模型预测选股**（Qlib/LightGBM）留 M8.3，引擎接口先留 mode 字段占位。
|
||
- 每条候选输出 `selection_reason`（命中的条件 / 分数来源），支撑 v2「为什么选这只股票」。
|
||
- 验收：同 spec 下 A/B 模式输出与人工核对一致；条件/评分模式均可对历史 as_of 执行。
|
||
|
||
### 3.3 结果持久化与 API
|
||
|
||
- Model（→ Alembic → Repo，全部走 Model→Migration→Test）：
|
||
- `selection_result`（v2 §8：selection_id / strategy_id 占位 / as_of_date / symbol / rank / score /
|
||
factor_values / filter_status / selection_reason / created_at）；
|
||
- `selection_snapshot`（spec 与 universe/条件快照 JSON，供复现与"历史某日选了什么"查询）。
|
||
- `selection_rule`（可选的命名规则持久化，MVP 允许后置：snapshot 已含完整 spec）。
|
||
- API（业务对象导向，AGENT.md §17）：`POST /api/selections`（提交 spec+as_of，同步或 Job 计算并落库）、
|
||
`GET /api/selections/{id}`、`GET /api/selections?as_of=&strategy_id=`（历史选股查询）。
|
||
- 验收：提交一次选股 → 结果落库可查；重建同 spec+as_of 得到相同结果（可复现）。
|
||
|
||
### 3.4 回测一致性改造（v2 §25 红线）
|
||
|
||
- `TopKBacktestRunner._rebalance` 改为**调用 Selection Engine**（同 spec、同 as_of）得到候选
|
||
再进入成交/仓位逻辑——保证"当前选股 = 历史回测每期选股"用同一套代码。
|
||
- 默认配置下回测数值与改造前**逐项一致**（回归测试锁住）。
|
||
- 验收（v2 §27）：`select(strategy, 历史调仓日)` 与回测当日持仓选股逐 symbol 一致。
|
||
|
||
### 3.5 Web 选股页（可后端就绪后并行）
|
||
|
||
- 新路由 `/selection`（v2 §19/§21.1）：选股条件面板（范围 + A 条件 + B 评分/权重/TopN）+
|
||
as_of 日期（当前/历史）→ SelectionResult 表格（rank/score/因子值/理由）→「一键以该 spec 发起回测」。
|
||
- `lib/types.ts` 增加 SelectionSpec / SelectionResult；nav（app-shell）加入"股票筛选"入口。
|
||
- 验收：页面完成"选范围 → 配条件/评分 → 当前/历史 TopN 结果 → 跳回测"闭环；tsc --noEmit 通过。
|
||
|
||
### 3.6 M6 验收（里程碑完成判定）
|
||
|
||
- [ ] `select(spec, as_of=历史日)` 与回测该日调仓选股逐 symbol 一致（自动化测试）
|
||
- [ ] A/B 两模式都可对"当前日 / 历史日"执行并落库，`/api/selections` 可查
|
||
- [ ] 选股结果带 factor_values 与 selection_reason（可解释）
|
||
- [ ] Web 选股页闭环可用；SelectionResult DTO 前后端一致
|
||
- [ ] 全量 pytest 通过；相关迁移测试覆盖新表
|
||
|
||
---
|
||
|
||
## 5. M7：因子层落地（支撑选股增强，紧随 M6）
|
||
|
||
> 目标：把"因子"从代码注册表变成**可入库、可版本化、可组合**的研究资产，并修掉混合口径风险，
|
||
> 为选股 B 模式（更多/自定义因子）、因子研究做实提供基础。
|
||
|
||
- **4.1 因子定义入库 + 版本化目录**：Model `factor_definition` + seed 现有 9 因子元数据；
|
||
`GET /api/factors` 改读库；自定义因子元数据 CRUD（计算仍走代码注册表）。
|
||
- **4.2 Composite Factor Engine 模块化**：抽出 `quant/composite.py`
|
||
（`CompositeSpec{components[name,weight,direction], method}` → score 面板）；
|
||
`factor_composite(+component)` 表；选股 B 模式与回测共用同一实现。验收：默认 spec 回测结果与现一致。
|
||
- **4.3 研究读取口径修复（横切）**：Repository 读路径按 `source/adjust` 过滤或提供 qfq 查询；
|
||
ResearchSpec/SelectionSpec 增加 `price_adjustment` 字段并写入结果 config_snapshot。
|
||
验收：含新浪补缺行的股票回测/选股口径一致且可溯源。
|
||
- **4.4 因子测试结果结构化（可选）**：Model `factor_test`，多因子 spec 不再静默只测第一个。
|
||
|
||
---
|
||
|
||
## 6. M8：引擎延伸与平台化（Signal / Portfolio / Strategy / Agent / 模型选股）
|
||
|
||
- **5.1 Signal Engine（规则型）**：`signal_rule / signal_event{signal_date, symbol, signal_type,
|
||
trigger_reason, score, price}`；回测与选股都能产事件并落库；API `POST /api/signals`、历史查询。
|
||
验收：能回答「某策略某日为什么对这只股票给 BUY/SELL」。
|
||
- **5.2 Portfolio Engine**：把回测器 `_rebalance` 资金/仓位逻辑抽为 portfolio 模块
|
||
（等权起步 + 单股/行业上限/现金可选约束，约束默认关闭并如实标注 unimplemented）。
|
||
验收：默认配置回测数值与现一致。
|
||
- **5.3 Strategy 模型与 /api/strategies**：聚合 universe + selection(spec) + signal + portfolio +
|
||
rebalance；Experiment 归档 strategy_version；Agent 增加 `create_strategy`。
|
||
- **5.4 Qlib 模型链路 = 选股模式 C**（按需）：Alpha158 特征 + LightGBM walk-forward →
|
||
预测分 → Selection 模式 C。
|
||
- **5.5 AI Agent 工具补齐**（依赖上述引擎）：`inspect_factor / create_composite_factor /
|
||
screen_stocks / explain_selection / generate_signals / create_strategy / get_backtest_result /
|
||
create_experiment`，全部经白名单 + Job/Experiment 链路；前端加最小 AI 对话入口。
|
||
- **5.6 Web 页面做实**（前端主线，随后端里程碑推进）：回测页做实（trades/年度收益/持仓演化/成本参数/
|
||
config_snapshot，零新 API）、因子研究做实（IC 时序/对比）、Signal 页、Job SSE 进度 UI
|
||
（需先补 executor stage 上报，见 §6）。
|
||
|
||
---
|
||
|
||
## 7. 基础设施专项（含本机 Redis 的定位）
|
||
|
||
**本机已探测：Redis 服务在 127.0.0.1:6379 正常响应（无 redis-cli，连接经 socket 验证）。**
|
||
|
||
v2 §22 与 AGENT.md §19/§38 的原则是"第一版不引复杂队列；复杂后再引入 Redis + Celery/RQ"。
|
||
据此把 Redis 放入**明确的触发点**而非一开始就用：
|
||
|
||
| 触发场景 | Redis 用途 | 何时启用 |
|
||
|---|---|---|
|
||
| Job 并发/排队：subprocess 双并发上限打满、丢任务需可恢复队列 | RQ/普通队列替代 FastAPI BackgroundTasks 调度 | M8 之后 / 出现排队丢失问题 |
|
||
| Job 细粒度 stage + SSE 长连：executor 每阶段写 stage 后广播 | Redis pub/sub 做 SSE 事件总线（替代 0.4s 查库轮询） | M8.6 前端切 SSE 时（可先行） |
|
||
| 行情/因子查询热点：全市场选股重复预热 | 因子结果 / 最新交易日缓存（key 带 as_of 失效） | M6 选股高频查询后按 profile 决定 |
|
||
|
||
近期只需做一件准备工作：`config.yaml` 预留 `redis.url_env: "REDIS_URL"` + 可选
|
||
`redis.url: "redis://127.0.0.1:6379/0"` 配置段，代码不改；真正启用时再落基础设施代码。
|
||
|
||
**其余基础设施待办**（低优先）：Job `cancelled` 取消 API 与 `/api/jobs` 列表端点；executor 增加 stage
|
||
上报（data_loading/factor_calculation/backtesting…）——这是前端做 SSE 进度条的前提。
|
||
|
||
---
|
||
|
||
## 8. 建议的执行顺序（前 6 个 commit 序列）
|
||
|
||
按 AGENT.md「最小修改、每阶段可跑、一功能一 commit」，以选股 MVP 为起点的推荐顺序：
|
||
|
||
1. **M6.0 选股契约**：Domain `SelectionSpec / SelectionResult` + `selection_service.select(spec, as_of)`
|
||
骨架（先同步执行、复用 ResearchService 数据装配）。验收：对最近交易日返回 TopN 候选 + 理由。
|
||
2. **M6.1 Universe 过滤执行器**：抽 `UniverseFilter`（复用 filter_stocks 语义）。
|
||
验收：当前/历史日范围正确、回测回归不变。
|
||
3. **M6.2 Selection Engine A + B**：条件选股（结构化条件 JSON）+ 因子评分 TopN（复用因子与
|
||
composite_score）。验收：A/B 模式可执行、结果含 factor_values/reason。
|
||
4. **M6.3 落库与 API**：`selection_result / selection_snapshot` 表 + Repo + `POST/GET /api/selections`。
|
||
验收：迁移测试 + 提交可查、重建一致。
|
||
5. **M6.4 回测共用 Selection**：`TopKBacktestRunner` 改调 Selection Engine。
|
||
验收：默认 spec 回测结果逐项一致 + 历史日一致性测试。
|
||
6. **M6.5 Web 选股页**：`/selection` 路由 + SelectionResult 表 + 一键跳回测。
|
||
|
||
之后进入 M7（因子层落地）与 M8（Signal/Portfolio/Strategy/Agent/模型选股）与 §6 基础设施专项。
|
||
|
||
每步都遵循：Domain → Repository Protocol → Infra(Model→Migration→Repo) → Service → API → 前端 →
|
||
测试（相关模块）→ 更新文档；新增表一律 Model→Alembic→测试。
|
||
|
||
---
|
||
|
||
## 9. 风险清单（开发中持续检查）
|
||
|
||
- **历史一致性**：回测改用 Selection Engine 后默认结果必须与改造前一致（回归测试锁住，别让重构悄悄改策略语义）。
|
||
- **未来函数 / 幸存者偏差**：财务条件按 `announce_date ≤ as_of` 过滤；universe 的 ST/行业/成分历史
|
||
口径补齐前，结果须明示近似（ST 当前名称快照等）。
|
||
- **数据口径**：选股/回测所用行情口径（不复权 vs 前复权）必须一致并可溯源（M7.3 收口）。
|
||
- **范围控制**：M6 阶段不做自由表达式 parser / 不做模型选股（C 模式）/ 不建 universe 大表；
|
||
均留到后续里程碑，避免一次性跨层堆量。
|
||
- **MySQL 行为差异**：TEXT 上限、批量 upsert 锁等待、pymysql 流式读取 —— 见 §1 遗留收尾表。
|
||
- **前端契约**：SelectionResult/SignalResult 先定 DTO（后端 entity）再画页面，避免前后端口径漂移。
|