alphax/docs/MULTI_STRATEGY_IMPLEMENTATION_PLAN.md

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

新增文件：

app/db/migrations/00xx_multi_strategy.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 '{}';

新增标准策略信号表：

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);

可选但建议同步新增策略目录表，避免策略中文名和启用状态散落在代码里：

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 验收

必须验证：

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()，防止未知因子默认变成交易触发。

初始角色建议：

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()，让推荐写入时能统一保存策略快照。

最小字段：

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 修改推荐写入

文件：

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

文件：

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 修改推荐读模型

文件：

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 策略注册中心

新增：

app/core/strategy_registry.py

职责：

• 集中维护策略代码、中文名、描述、默认模式。
• 提供 strategy_label(strategy_code)。
• 提供 registered_strategy_codes()。

初始策略：

main_composite_v1 -> 综合确认策略
box_retest_4h_v1 -> 4H箱体突破回踩

前端展示中文名时优先用 registry/API 返回值，不硬编码。

4. 独立策略：box_retest_4h_v1

4.1 策略定位

不是“看到箱体突破回踩就买”，而是：

底部箱体完成
  -> 放量突破
  -> 首次/二次回踩箱体上沿或 EMA
  -> 回踩不破且承接
  -> 当前价格距离入场区不过远
  -> 市场环境允许
  -> 盈亏比合格
  -> 才进入观察/挂单/交易候选

4.2 新增文件

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 机会总览

文件：

static/app.html
app/web/routes_recommendations.py

改造点：

• 卡片显示中文策略名，例如“4H箱体突破回踩策略”。
• 详情页展示：
  • 策略来源
  • 核心触发
  • 确认因子
  • 入场条件
  • 风险/失效条件
• API 增加 strategy_code、strategy_name、strategy_snapshot、factor_roles。

5.2 策略交易页

文件：

static/paper_trading.html
app/web/routes_paper_trading.py

改造点：

• 持仓中、挂单中、已完成、操作日志都显示策略列。
• 增加策略筛选器。
• 交易详情展示 strategy snapshot。
• 列表接口支持 strategy_code 参数过滤。

5.3 复盘中心

文件：

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 单元测试

新增/修改：

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 容器验证

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。