580 lines
17 KiB
Markdown
580 lines
17 KiB
Markdown
# AlphaX 多策略改造实施计划
|
||
|
||
本文档是 `MULTI_STRATEGY_ARCHITECTURE.md` 的施工版，用于把多策略架构拆成可开发、可验证、可上线观察的任务包。
|
||
|
||
今晚目标不是一次性完成所有长期架构，而是交付一个能真实运行的第一阶段：
|
||
|
||
- 每条推荐、挂单、持仓都能追溯到策略。
|
||
- 现有综合确认策略不被打断，统一标记为 `main_composite_v1`。
|
||
- `box_retest_4h_v1` 进入独立策略雏形，不再只是综合确认层里的一个因子。
|
||
- paper trading 和复盘能按策略看表现。
|
||
- 前端至少能看到策略来源，明早可以观察跑出来的数据。
|
||
|
||
## 0. 基础设施重构原则
|
||
|
||
这次属于策略基础设施重构，不允许为了赶进度留下明显技术债。
|
||
|
||
必须遵守：
|
||
|
||
- DB schema 变化必须走 migration，不允许业务函数里偷偷补字段。
|
||
- 策略身份必须用 `strategy_code`，版本必须用 `strategy_version`，不能继续混用。
|
||
- 新增策略输出必须走统一 `StrategySignal` 契约，不允许每个策略各写一套 JSON。
|
||
- 因子角色必须显式声明，未知因子默认只能作为 `attribution` 或 `unknown`，不能默认变成交易触发。
|
||
- paper trading、paper orders、recommendation 必须完整继承策略血缘，不能只在推荐层有策略，交易账本丢失。
|
||
- UI/API/复盘至少要有最小闭环，否则字段只是“存了但没人用”。
|
||
- 兼容旧数据可以回填为 `main_composite_v1`，但新数据不允许空策略来源。
|
||
- 不做全局散落的硬编码策略名，策略中文名、启用状态、描述应集中维护。
|
||
|
||
允许的兼容：
|
||
|
||
- 旧综合确认策略继续运行，但必须标记为 `main_composite_v1`，并与其他策略平等。
|
||
- 第一版 `box_retest_4h_v1` 可以先 paper-only / observe-only。
|
||
- 复杂仲裁可以先做最小规则，但接口要为后续多策略扩展留好。
|
||
|
||
不允许的临时方案：
|
||
|
||
- 不允许把 `box_breakout_pullback_4h` 直接当 `strategy_code`。
|
||
- 不允许只给 paper trades 加字段，却不改写入链路。
|
||
- 不允许只写文档不补测试。
|
||
- 不允许把策略表现继续只按 `strategy_version` 聚合。
|
||
- 不允许前端继续完全看不到策略来源。
|
||
|
||
## 1. 总体交付分层
|
||
|
||
### P0：策略血缘打通
|
||
|
||
必须完成。目标是先让系统所有后续数据都带上策略来源。
|
||
|
||
- 新增策略标准结构。
|
||
- 新增因子角色定义。
|
||
- DB 增加策略血缘字段。
|
||
- 推荐写入时保存 `strategy_code`、`strategy_signal_id`、`strategy_snapshot_json`、`factor_roles_json`。
|
||
- paper orders / paper trades 继承推荐里的策略字段。
|
||
- API 和页面展示策略来源。
|
||
- 复盘统计支持按策略聚合。
|
||
- 测试覆盖 recommendation -> paper order -> paper trade 的策略血缘传递。
|
||
|
||
### P1：第一个独立策略雏形
|
||
|
||
尽量完成。目标是让 `box_retest_4h_v1` 从因子变成独立策略候选。
|
||
|
||
- 新建 `app/strategies/box_retest_4h.py`。
|
||
- 复用统一交易宇宙和 `detect_box_breakout_pullback_4h()`。
|
||
- 输出标准策略信号。
|
||
- 当前先以 observe/paper-only 运行，避免直接影响真实同步。
|
||
|
||
### P2：最小策略编排与仲裁
|
||
|
||
只做最小闭环。目标是不让多策略重复乱写推荐。
|
||
|
||
- 新建简单策略注册表/编排函数。
|
||
- 同一币种同方向保留最高置信度策略。
|
||
- 不同方向先降级观察，不做自动对冲。
|
||
- 先不做复杂策略权重投票。
|
||
|
||
### P3：技术债清理与文档同步
|
||
|
||
必须完成最小项。目标是重构后代码结构清楚、后续可扩展。
|
||
|
||
- `AGENTS.md`、`OPTIMIZATION_TODO.md`、`MULTI_STRATEGY_ARCHITECTURE.md` 同步最终事实。
|
||
- 新增模块必须有单元测试。
|
||
- 任何未完成项必须写入 TODO，不能藏在代码注释里。
|
||
- 运行命令和验收结果写入最终交付说明。
|
||
|
||
## 2. 数据库改造
|
||
|
||
### 2.1 新增 migration
|
||
|
||
新增文件：
|
||
|
||
```text
|
||
app/db/migrations/00xx_multi_strategy.sql
|
||
```
|
||
|
||
建议字段：
|
||
|
||
```sql
|
||
ALTER TABLE recommendation
|
||
ADD COLUMN IF NOT EXISTS strategy_code TEXT DEFAULT '',
|
||
ADD COLUMN IF NOT EXISTS strategy_signal_id BIGINT DEFAULT 0,
|
||
ADD COLUMN IF NOT EXISTS strategy_snapshot_json TEXT DEFAULT '{}',
|
||
ADD COLUMN IF NOT EXISTS factor_roles_json TEXT DEFAULT '{}';
|
||
|
||
ALTER TABLE paper_trades
|
||
ADD COLUMN IF NOT EXISTS strategy_code TEXT DEFAULT '',
|
||
ADD COLUMN IF NOT EXISTS strategy_signal_id BIGINT DEFAULT 0,
|
||
ADD COLUMN IF NOT EXISTS strategy_snapshot_json TEXT DEFAULT '{}',
|
||
ADD COLUMN IF NOT EXISTS factor_roles_json TEXT DEFAULT '{}';
|
||
|
||
ALTER TABLE paper_orders
|
||
ADD COLUMN IF NOT EXISTS strategy_code TEXT DEFAULT '',
|
||
ADD COLUMN IF NOT EXISTS strategy_signal_id BIGINT DEFAULT 0,
|
||
ADD COLUMN IF NOT EXISTS strategy_snapshot_json TEXT DEFAULT '{}',
|
||
ADD COLUMN IF NOT EXISTS factor_roles_json TEXT DEFAULT '{}';
|
||
```
|
||
|
||
新增标准策略信号表：
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS strategy_signals (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
run_id TEXT DEFAULT '',
|
||
strategy_code TEXT NOT NULL,
|
||
strategy_version TEXT DEFAULT '',
|
||
symbol TEXT NOT NULL,
|
||
direction TEXT DEFAULT 'long',
|
||
signal_status TEXT DEFAULT 'candidate',
|
||
confidence DOUBLE PRECISION DEFAULT 0,
|
||
score DOUBLE PRECISION DEFAULT 0,
|
||
market_regime TEXT DEFAULT '',
|
||
trigger_json TEXT DEFAULT '{}',
|
||
factor_roles_json TEXT DEFAULT '{}',
|
||
entry_plan_json TEXT DEFAULT '{}',
|
||
risk_plan_json TEXT DEFAULT '{}',
|
||
decision_log_json TEXT DEFAULT '{}',
|
||
created_at TEXT NOT NULL
|
||
);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_strategy_signals_code_time
|
||
ON strategy_signals(strategy_code, created_at DESC);
|
||
|
||
CREATE INDEX IF NOT EXISTS idx_strategy_signals_symbol_time
|
||
ON strategy_signals(symbol, created_at DESC);
|
||
```
|
||
|
||
可选但建议同步新增策略目录表，避免策略中文名和启用状态散落在代码里：
|
||
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS strategy_catalog (
|
||
strategy_code TEXT PRIMARY KEY,
|
||
strategy_name TEXT NOT NULL,
|
||
strategy_version TEXT DEFAULT '',
|
||
status TEXT DEFAULT 'active',
|
||
mode TEXT DEFAULT 'paper_only',
|
||
description TEXT DEFAULT '',
|
||
config_json TEXT DEFAULT '{}',
|
||
created_at TEXT NOT NULL,
|
||
updated_at TEXT NOT NULL
|
||
);
|
||
```
|
||
|
||
如果今晚来不及完整管理页面，也应先提供 DB 表和默认种子。
|
||
|
||
### 2.2 兼容回填
|
||
|
||
旧数据没有策略来源时：
|
||
|
||
- `recommendation.strategy_code = 'main_composite_v1'`
|
||
- `paper_trades.strategy_code = COALESCE(recommendation.strategy_code, 'main_composite_v1')`
|
||
- `paper_orders.strategy_code = COALESCE(recommendation.strategy_code, 'main_composite_v1')`
|
||
|
||
回填只做一次，不改变收益数据。
|
||
|
||
回填后要加非空语义检查：
|
||
|
||
- 新推荐写入后 `strategy_code` 不得为空。
|
||
- 新 paper order 写入后 `strategy_code` 不得为空。
|
||
- 新 paper trade 写入后 `strategy_code` 不得为空。
|
||
|
||
### 2.3 migration 验收
|
||
|
||
必须验证：
|
||
|
||
```bash
|
||
docker compose run --rm alphax-web python scripts/postgres/run_migrations.py
|
||
docker compose exec alphax-web python - <<'PY'
|
||
from app.db.schema import get_conn
|
||
conn = get_conn()
|
||
for table in ["recommendation", "paper_trades", "paper_orders", "strategy_signals"]:
|
||
print(table, conn.execute("SELECT COUNT(*) FROM information_schema.columns WHERE table_name=%s", (table,)).fetchone()[0])
|
||
conn.close()
|
||
PY
|
||
```
|
||
|
||
## 3. 核心代码改造
|
||
|
||
### 3.1 新增 `app/core/factor_roles.py`
|
||
|
||
职责：
|
||
|
||
- 定义因子角色枚举。
|
||
- 维护默认因子角色映射。
|
||
- 提供 `factor_roles_for_codes(signal_codes)`。
|
||
- 提供 `validate_factor_roles()`，防止未知因子默认变成交易触发。
|
||
|
||
初始角色建议：
|
||
|
||
```text
|
||
box_breakout_pullback_4h -> trigger
|
||
vp_fly_1h_current -> trigger / confirmation
|
||
short_tf_15m_ignition -> trigger，但默认 observe-only
|
||
short_tf_5m_ignition -> prerequisite / early_watch
|
||
sector_rotation -> confirmation
|
||
sentiment_resonance -> confirmation
|
||
top_trader_long -> confirmation
|
||
exchange_outflow -> confirmation
|
||
false_breakout -> risk
|
||
trend_exhaustion -> risk
|
||
risk_reward_bad -> risk
|
||
entry_quality_gate -> risk
|
||
```
|
||
|
||
注意：同一因子在不同策略里可以有不同角色；默认映射只用于兼容综合确认策略。
|
||
|
||
该模块必须保持纯函数，不依赖 DB，不读运行时配置，避免策略基础设施反向依赖业务层。
|
||
|
||
### 3.2 新增 `app/core/strategy_contract.py`
|
||
|
||
职责：
|
||
|
||
- 定义 `StrategySignal` 数据结构。
|
||
- 定义 `StrategyDecision` / `StrategyRiskPlan` / `StrategyEntryPlan` 的最小字段。
|
||
- 提供 `signal_to_recommendation_context()`，让推荐写入时能统一保存策略快照。
|
||
|
||
最小字段：
|
||
|
||
```python
|
||
strategy_code: str
|
||
strategy_version: str
|
||
symbol: str
|
||
direction: str
|
||
status: str
|
||
confidence: float
|
||
score: float
|
||
trigger: dict
|
||
factor_roles: dict
|
||
entry_plan: dict
|
||
risk_plan: dict
|
||
decision_log: dict
|
||
```
|
||
|
||
要求：
|
||
|
||
- 提供 `to_json_dict()`，统一序列化。
|
||
- 提供 `from_confirm_result()`，兼容现有确认链路。
|
||
- 提供 `default_main_composite_signal()`，给旧综合确认策略生成标准策略快照。
|
||
- 不在这里调用数据库，不在这里拉行情。
|
||
|
||
### 3.2.1 新增 `app/db/strategy_signal_queries.py`
|
||
|
||
职责：
|
||
|
||
- 插入 `strategy_signals`。
|
||
- 查询最近策略信号。
|
||
- 按 `strategy_code` 聚合信号数量。
|
||
|
||
不要塞进 `altcoin_db.py`。
|
||
|
||
### 3.3 修改推荐写入
|
||
|
||
文件：
|
||
|
||
```text
|
||
app/db/recommendation_commands.py
|
||
```
|
||
|
||
改造点：
|
||
|
||
- `create_recommendation()` 增加参数：
|
||
- `strategy_code`
|
||
- `strategy_signal_id`
|
||
- `strategy_snapshot`
|
||
- `factor_roles`
|
||
- 未传时默认 `main_composite_v1`。
|
||
- duplicate merge 时保留更强策略信号，或者暂时用最新策略覆盖空字段。
|
||
- INSERT / UPDATE 同步写入新字段。
|
||
- 写入前通过 `normalize_strategy_context()` 统一清洗，避免空字符串、坏 JSON、重复逻辑散落。
|
||
|
||
### 3.4 修改 paper trading
|
||
|
||
文件：
|
||
|
||
```text
|
||
app/db/paper_trading.py
|
||
```
|
||
|
||
改造点：
|
||
|
||
- `_open_trade()` 插入 `paper_trades` 时继承：
|
||
- `strategy_code`
|
||
- `strategy_signal_id`
|
||
- `strategy_snapshot_json`
|
||
- `factor_roles_json`
|
||
- `_order_payload_from_rec()` 和 paper order 插入时继承同样字段。
|
||
- `_record_event()` 的 detail_json 加入策略来源，方便操作日志直接解释。
|
||
- list API 返回策略字段，前端不需要二次查 recommendation。
|
||
|
||
### 3.5 修改推荐读模型
|
||
|
||
文件：
|
||
|
||
```text
|
||
app/db/recommendation_state.py
|
||
app/db/recommendation_queries.py
|
||
app/db/analytics.py
|
||
```
|
||
|
||
改造点：
|
||
|
||
- API 输出 `strategy_code`、`strategy_signal_id`、`strategy_snapshot`、`factor_roles`。
|
||
- 推荐详情页能展示策略来源。
|
||
- 归档/复盘列表支持 strategy 过滤。
|
||
|
||
### 3.6 策略注册中心
|
||
|
||
新增：
|
||
|
||
```text
|
||
app/core/strategy_registry.py
|
||
```
|
||
|
||
职责：
|
||
|
||
- 集中维护策略代码、中文名、描述、默认模式。
|
||
- 提供 `strategy_label(strategy_code)`。
|
||
- 提供 `registered_strategy_codes()`。
|
||
|
||
初始策略：
|
||
|
||
```text
|
||
main_composite_v1 -> 综合确认策略
|
||
box_retest_4h_v1 -> 4H箱体突破回踩
|
||
```
|
||
|
||
前端展示中文名时优先用 registry/API 返回值，不硬编码。
|
||
|
||
## 4. 独立策略：`box_retest_4h_v1`
|
||
|
||
### 4.1 策略定位
|
||
|
||
不是“看到箱体突破回踩就买”，而是：
|
||
|
||
```text
|
||
底部箱体完成
|
||
-> 放量突破
|
||
-> 首次/二次回踩箱体上沿或 EMA
|
||
-> 回踩不破且承接
|
||
-> 当前价格距离入场区不过远
|
||
-> 市场环境允许
|
||
-> 盈亏比合格
|
||
-> 才进入观察/挂单/交易候选
|
||
```
|
||
|
||
### 4.2 新增文件
|
||
|
||
```text
|
||
app/strategies/__init__.py
|
||
app/strategies/box_retest_4h.py
|
||
app/strategies/orchestrator.py
|
||
```
|
||
|
||
### 4.3 第一版策略规则
|
||
|
||
先决条件：
|
||
|
||
- `market_regime.risk_level != critical`
|
||
- 交易宇宙通过。
|
||
- 4H 数据足够。
|
||
- 箱体宽度合理。
|
||
|
||
核心触发：
|
||
|
||
- `detect_box_breakout_pullback_4h().detected == True`
|
||
|
||
确认条件：
|
||
|
||
- `pullback_age_bars <= 4`
|
||
- `quality in 良好/优质`
|
||
- 没有明显 `trend_exhaustion`
|
||
- 不是已经远离 `entry_zone` 太多。
|
||
|
||
入场规则：
|
||
|
||
- 距离 `entry_zone` 小于配置阈值时允许挂单或买点确认。
|
||
- 如果已经大幅拉开，只进入观察，不追。
|
||
|
||
失效规则：
|
||
|
||
- 跌回箱体。
|
||
- 距离突破/回踩时间过久。
|
||
- 1H/15m 出现假突破或趋势衰竭。
|
||
|
||
输出：
|
||
|
||
- `StrategySignal(strategy_code='box_retest_4h_v1')`
|
||
|
||
### 4.4 与现有综合确认策略关系
|
||
|
||
第一阶段不能直接删除现有综合确认策略里的 `box_breakout_pullback_4h` 加分，否则会改变当前推荐行为过大。
|
||
|
||
处理方式：
|
||
|
||
- 综合确认策略继续把它作为结构因子参与确认，策略来源仍为 `main_composite_v1`。
|
||
- 独立策略并行生成 `box_retest_4h_v1` 信号。
|
||
- 如果同一 symbol 同时被综合确认策略和箱体策略命中，短期由仲裁器保留更明确的策略快照，或在推荐 `strategy_snapshot_json` 中记录 secondary strategies。
|
||
- 明早先观察是否出现重复推荐，再决定是否让箱体策略接管该类信号。
|
||
|
||
## 5. API 与 UI 改造
|
||
|
||
### 5.1 机会总览
|
||
|
||
文件：
|
||
|
||
```text
|
||
static/app.html
|
||
app/web/routes_recommendations.py
|
||
```
|
||
|
||
改造点：
|
||
|
||
- 卡片显示中文策略名，例如“4H箱体突破回踩策略”。
|
||
- 详情页展示：
|
||
- 策略来源
|
||
- 核心触发
|
||
- 确认因子
|
||
- 入场条件
|
||
- 风险/失效条件
|
||
- API 增加 `strategy_code`、`strategy_name`、`strategy_snapshot`、`factor_roles`。
|
||
|
||
### 5.2 策略交易页
|
||
|
||
文件：
|
||
|
||
```text
|
||
static/paper_trading.html
|
||
app/web/routes_paper_trading.py
|
||
```
|
||
|
||
改造点：
|
||
|
||
- 持仓中、挂单中、已完成、操作日志都显示策略列。
|
||
- 增加策略筛选器。
|
||
- 交易详情展示 strategy snapshot。
|
||
- 列表接口支持 `strategy_code` 参数过滤。
|
||
|
||
### 5.3 复盘中心
|
||
|
||
文件：
|
||
|
||
```text
|
||
app/db/review_center.py
|
||
app/db/strategy_insights.py
|
||
static/review_center.html
|
||
```
|
||
|
||
改造点：
|
||
|
||
- 增加“按策略”聚合。
|
||
- 指标：
|
||
- 推荐数
|
||
- 挂单数
|
||
- 成交数
|
||
- 平仓数
|
||
- 胜率
|
||
- 总收益
|
||
- 平均收益
|
||
- 最大回撤
|
||
- 平均持仓时长
|
||
- 适用 market regime
|
||
|
||
### 5.4 Pipeline / 日志中心
|
||
|
||
- pipeline 批次详情展示各策略产出的信号数量。
|
||
- 系统日志中策略运行错误要带 `strategy_code`。
|
||
- 不要求今晚完整 UI，但 API 返回结构要预留。
|
||
|
||
## 6. 测试计划
|
||
|
||
### 6.1 单元测试
|
||
|
||
新增/修改：
|
||
|
||
```text
|
||
tests/test_factor_roles.py
|
||
tests/test_strategy_contract.py
|
||
tests/test_strategy_lineage.py
|
||
tests/test_box_retest_strategy.py
|
||
tests/test_paper_trading.py
|
||
tests/test_strategy_insights.py
|
||
```
|
||
|
||
重点断言：
|
||
|
||
- 因子角色不会把未知因子默认当作 trigger。
|
||
- `box_breakout_pullback_4h` 只是 trigger，不是完整策略。
|
||
- `create_recommendation()` 默认写入 `main_composite_v1`。
|
||
- paper order / paper trade 继承 `strategy_code`。
|
||
- 复盘可以按 `strategy_code` 聚合。
|
||
- API 输出策略中文名。
|
||
|
||
### 6.1.1 必须新增的回归测试
|
||
|
||
- migration 后字段存在。
|
||
- `StrategySignal` 序列化稳定。
|
||
- `main_composite_v1` 默认策略上下文生成。
|
||
- recommendation merge 不会清空已有策略来源。
|
||
- paper order 创建继承策略来源。
|
||
- paper trade 开仓继承策略来源。
|
||
- strategy aggregation 不再只按 `strategy_version`。
|
||
|
||
### 6.2 容器验证
|
||
|
||
```bash
|
||
docker compose build alphax-web alphax-scheduler alphax-price-streamer
|
||
docker compose up -d alphax-web alphax-scheduler alphax-price-streamer
|
||
docker compose exec alphax-web python -m pytest -q tests/test_factor_roles.py tests/test_strategy_contract.py tests/test_strategy_lineage.py tests/test_box_retest_strategy.py
|
||
docker compose exec alphax-web python -m app.cli screener
|
||
docker compose exec alphax-web python -m app.cli confirm
|
||
docker compose exec alphax-web python -m app.cli paper-trader
|
||
```
|
||
|
||
## 7. 明早验收标准
|
||
|
||
明早交付至少要能做到：
|
||
|
||
- 数据库 migration 正常跑过。
|
||
- Docker 服务正常 up。
|
||
- 新推荐至少有 `strategy_code`。
|
||
- 新挂单/持仓至少有 `strategy_code`。
|
||
- paper trading 页面能看到策略来源。
|
||
- 复盘/策略归因能按策略聚合。
|
||
- `box_retest_4h_v1` 能独立输出策略信号或至少进入标准策略信号结构。
|
||
- `box_breakout_pullback_4h` 在代码和文档里没有被误当作完整策略。
|
||
- 不存在新增数据 `strategy_code=''` 的情况。
|
||
- 新增基础设施模块没有反向依赖 Web 或 DB 热路径。
|
||
- 未完成事项已明确写入 TODO，不留口头债。
|
||
|
||
## 8. 风险边界
|
||
|
||
今晚不做：
|
||
|
||
- 不把多策略直接同步真实交易。
|
||
- 不做复杂策略投票。
|
||
- 不做多空完整重构。
|
||
- 不做大规模 UI 重设计。
|
||
- 不删除现有综合确认策略。
|
||
|
||
今晚可以做：
|
||
|
||
- 保留综合确认策略运行。
|
||
- 补策略血缘。
|
||
- 补第一版策略标准结构。
|
||
- 让 `box_retest_4h_v1` 作为独立候选跑起来。
|
||
- 给明早提供能观察的数据和复盘口径。
|
||
|
||
## 9. 今晚执行顺序
|
||
|
||
为了降低基础设施重构风险，按下面顺序施工：
|
||
|
||
1. 新增 migration 和回填。
|
||
2. 新增 `strategy_registry`、`factor_roles`、`strategy_contract` 纯核心模块。
|
||
3. 新增 `strategy_signal_queries`，不要碰业务状态机。
|
||
4. 修改 `create_recommendation()` 写入策略血缘。
|
||
5. 修改 paper orders / paper trades 继承策略血缘。
|
||
6. 修改读模型/API，让前端能看到策略来源。
|
||
7. 修改 paper trading 页面最小展示策略列。
|
||
8. 新增 `box_retest_4h_v1` 策略模块和最小 orchestrator。
|
||
9. 补测试。
|
||
10. Docker build/up，跑容器内回归。
|
||
11. 写明早交付总结和剩余 TODO。
|