ai-exchange/docs/AI_ICT_PostgreSQL_Migration_Split_Plan_v1.md

AI ICT PostgreSQL Migration 拆分执行方案 v1

1. 文档目标

本文档把 AI_ICT_PostgreSQL_Schema_v1.md 中定义的数据库设计拆分为可执行的 migration 批次，确保：

• 按依赖顺序落地
• 每一批都可单独验证
• 出问题时可以局部回滚
• 不让 migration 任务停留在“已开始但不可执行”的状态

适用范围：AI ICT 项目第一阶段 MVP。

关联文档：

1. AI_ICT_总体设计文档_v1.md
2. AI_ICT_PostgreSQL_Schema_v1.md
3. AI_ICT_MVP_规则规格书_v1.md
4. AI_ICT_开发路线图_v1.md
5. AI_ICT_执行检查清单_v1.md

---

2. 拆分原则

1. 先基础字典，再时间序列，再结构事件，再信号执行，再回测分析
2. 每个 batch 只处理一个明确依赖层级，避免一次 migration 混入过多对象
3. 高数据量对象优先独立拆分，尤其是 candles
4. 每个 batch 都要配套验证 SQL / 回滚说明 / 必要 seed 数据
5. 第一版优先可落地，不对全部事件表过早分区

---

3. 总体依赖顺序

B0 基础约定/公共函数
  -> B1 venues
  -> B2 instruments
  -> B3 candles
  -> B4 market_sessions
  -> B5 swings
  -> B6 dealing_ranges + liquidity_pools
  -> B7 displacement_events
  -> B8 structure_events + fvg_zones
  -> B9 bias_snapshots
  -> B10 trade_signals
  -> B11 trade_executions
  -> B12 backtest_runs
  -> B13 backtest_results

依赖说明：

• instruments 依赖 venues
• candles、market_sessions、swings 依赖 instruments
• dealing_ranges 依赖 instruments，并引用 swings
• structure_events 引用 swings 与 displacement_events
• fvg_zones 引用 displacement_events
• bias_snapshots 引用 dealing_ranges
• trade_signals 引用 bias_snapshots
• trade_executions 引用 trade_signals
• backtest_runs 依赖 instruments
• backtest_results 依赖 backtest_runs，并可引用 trade_signals

---

4. migration 批次拆分

B0. 基础约定与公共函数

目标

建立后续所有 migration 共享的数据库前置条件。

内容

• 若项目决定使用非 public，先建立目标 schema
• 建立 updated_at 自动更新时间的公共 trigger function（若采用）
• 明确第一版统一使用 text + check constraint 替代数据库 enum
• 明确所有时间字段使用 timestamptz

验证检查点

• 公共函数可创建成功
• 后续表可以复用这些函数/约定
• 时区约定已在 migration 注释中写明

回滚说明

• 删除本批次新增函数、trigger 模板和非业务 schema
• 本批不涉及业务数据，回滚成本最低

---

B1. venues

目标

建立交易所字典表。

内容

• 创建 venues
• 主键 id
• 唯一键 code
• 默认状态 status = 'active'
• 可插入初始 seed：OKX、LMAX

依赖

• B0

验证检查点

• 表可成功创建
• code 唯一约束生效
• 基础 seed 可查询

回滚说明

• 若无下游依赖，可先删 seed 再 drop 表
• 若 instruments 已创建，必须先回退下游表

---

B2. instruments

目标

建立统一交易品种表。

内容

• 创建 instruments
• 外键 venue_id references venues(id)
• 唯一键 unique (venue_id, symbol)
• meta jsonb default '{}'
• 插入 BTC / ETH / XAU 的基础 instrument seed

依赖

• B1

验证检查点

• venue + symbol 可唯一查询
• 不存在的 venue_id 无法插入
• meta 默认值生效

回滚说明

• 若无下游表，可删 seed 后 drop
• 若已有 candles、market_sessions、swings 等表，需先逆序回滚下游

---

B3. candles

目标

建立时间序列主表与首批月分区。

内容

• 创建 candles 主表
• 唯一键 unique (instrument_id, timeframe, ts_open)
• 索引：
  • (instrument_id, timeframe, ts_open desc)
  • (instrument_id, timeframe, ts_close desc)
• 按 ts_open 建月分区
• 至少预建当前月、下月分区

为什么单独拆批

• 数据量最大
• 分区和唯一键策略最关键
• 后续行情入库直接依赖这一批

依赖

• B2

验证检查点

• 可插入样例 K 线
• 重复 (instrument_id, timeframe, ts_open) 会被拒绝
• 数据能正确进入对应月分区
• 关键查询能命中索引

回滚说明

• 先删测试数据
• 先 drop 子分区，再 drop 主表
• 若已有采集任务写入，生产环境不应直接回滚，应停写后重建

---

B4. market_sessions

目标

建立 session 切分与 pivot 数据表。

内容

• 创建 market_sessions
• 唯一键 unique (instrument_id, session_date, session_code, timezone)
• meta jsonb default '{}'
• 约定 session code：ASIA、LONDON、NY_AM、NY_LUNCH、NY_PM

依赖

• B2

验证检查点

• 同一 instrument/date/session/timezone 不能重复写入
• 可查询 high / low / midpoint
• 时区与会话区间表达一致

回滚说明

• 若未被上游程序依赖，可直接删测试数据并 drop
• 若已有 session 生成器运行，先停任务再回滚

---

B5. swings

目标

建立结构高低点表。

内容

• 创建 swings
• check constraint：
  • kind in ('swing_high', 'swing_low')
  • strength in ('ST', 'IT', 'LT')
• 索引：
  • (instrument_id, timeframe, ts desc)
  • (instrument_id, timeframe, kind, ts desc)
  • (instrument_id, timeframe, strength, ts desc)

依赖

• B2

验证检查点

• kind / strength 约束生效
• 能按 timeframe 查询最近 swing
• 非法枚举值会被拒绝

回滚说明

• 若 dealing_ranges / structure_events 尚未创建，可直接回滚
• 否则需先回滚依赖表

---

B6. dealing_ranges + liquidity_pools

目标

建立基础规则层中最核心的两个结果表。

合并原因

• 同属基础规则层
• 通常在同一轮规则计算中产出和消费
• 依赖层级接近

内容

dealing_ranges

• 创建表
• 引用 swings(id)
• 索引：
  • (instrument_id, timeframe, ts_start desc)
  • (instrument_id, timeframe, state, ts_start desc)

liquidity_pools

• 创建表
• check constraint：
  • side in ('buy_side', 'sell_side')
  • status in ('untouched', 'swept', 'consumed')
• 索引：
  • (instrument_id, timeframe, status, created_ts desc)
  • (instrument_id, timeframe, side, created_ts desc)

依赖

• B5

验证检查点

• dealing_ranges.high_swing_id / low_swing_id 能关联 swings
• liquidity_pools 状态和方向约束生效
• 可查询当前有效 range
• 可查询当前流动性池

回滚说明

• 先停基础规则重算任务
• 再按 liquidity_pools -> dealing_ranges 顺序回滚
• 若 bias_snapshots 已存在，先回退下游

---

B7. displacement_events

目标

建立有效位移事件表。

内容

• 创建 displacement_events
• 添加 direction、has_fvg、is_valid
• 索引：
  • (instrument_id, timeframe, end_ts desc)
  • (instrument_id, timeframe, direction, end_ts desc)

依赖

• B2

验证检查点

• 可查询最近 displacement
• 默认值正常
• 可被 structure_events 与 fvg_zones 引用

回滚说明

• 若 B8 尚未执行，可直接回滚
• 否则先回滚 B8

---

B8. structure_events + fvg_zones

目标

建立核心信号链路中的结构事件与 FVG 区域表。

合并原因

• 都属于信号上游对象
• 都依赖 displacement_events
• 一般同一轮规则识别会一起生成

内容

structure_events

• 创建表
• check constraint：
  • event_type in ('MSB', 'MSS')
  • direction in ('bullish', 'bearish')
• 引用 swings(id) 与 displacement_events(id)

fvg_zones

• 创建表
• check constraint：
  • direction in ('bullish', 'bearish')
  • status in ('open', 'touched', 'mitigated', 'invalidated')
• 引用 displacement_events(id)

依赖

• B5、B7

验证检查点

• structure_events 能关联 swing 与 displacement
• fvg_zones 能关联 displacement
• 状态与方向约束生效
• 可查询最近 MSS/MSB 与 open FVG

回滚说明

• 先删测试事件
• 先回退信号层依赖，再回滚本批次

---

B9. bias_snapshots

目标

建立 bias 快照表。

内容

• 创建 bias_snapshots
• check constraint：
  • daily_bias in ('bullish', 'bearish', 'neutral')
  • execution_intensity in ('low', 'medium', 'high')
• 引用 dealing_ranges(id)
• 索引：
  • (instrument_id, snapshot_ts desc)
  • (instrument_id, daily_bias, snapshot_ts desc)

依赖

• B6

验证检查点

• 能关联有效 range_id
• reason_codes / meta 默认值正常
• 可按 instrument 查询最近 bias

回滚说明

• 若 trade_signals 尚未创建，可直接回滚
• 否则先回滚 B10

---

B10. trade_signals

目标

建立候选交易信号主表。

内容

• 创建 trade_signals
• 引用 bias_snapshots(id)
• 索引：
  • (instrument_id, created_ts desc)
  • (instrument_id, status, created_ts desc)
  • (instrument_id, model_code, created_ts desc)
• 保留 invalidations jsonb、evidence jsonb
• 核心字段显式建列：entry/stop/tp/rr/status/side

依赖

• B9

验证检查点

• 信号可关联 bias snapshot
• 能按 status 查询待确认/active 信号
• evidence 可承载结构化引用

回滚说明

• 若 trade_executions 与 backtest_results 尚未创建，可直接回滚
• 否则先回退下游依赖

---

B11. trade_executions

目标

建立半自动执行记录表。

内容

• 创建 trade_executions
• 引用 trade_signals(id)
• check constraint：
  • execution_mode in ('paper', 'semi_auto', 'live')
  • status in ('pending', 'open', 'partially_closed', 'closed', 'cancelled', 'rejected')
• 索引：
  • (signal_id)
  • (status, created_at desc)
  • (execution_mode, created_at desc)

依赖

• B10

验证检查点

• execution 必须关联有效 signal
• 可查询 open / closed / cancelled 状态
• entry、stop、tp、size、risk_pct 可完整记录

回滚说明

• 先停执行写入流程
• 删测试执行记录
• 再回滚结构

---

B12. backtest_runs

目标

建立回测任务元数据与结果摘要表。

内容

• 创建 backtest_runs
• 引用 instruments(id)
• 索引：
  • (model_code, started_ts desc)
  • (instrument_id, started_ts desc)
• config、summary 使用 jsonb

依赖

• B2
• 执行顺序上建议放在 B11 之后，以便阶段验收统一

验证检查点

• 可记录一次回测启动/结束
• 可按 model 查询最近回测
• summary 可保存聚合统计

回滚说明

• 若 backtest_results 尚未创建，可直接回滚
• 否则先回滚 B13

---

B13. backtest_results

目标

建立回测明细结果表。

内容

• 创建 backtest_results
• 引用 backtest_runs(id)
• 可空引用 trade_signals(id)
• check constraint：
  • outcome in ('win', 'loss', 'breakeven', 'missed')
• 索引：
  • (backtest_run_id)
  • (outcome)

依赖

• B12
• 若引用真实 signal，还依赖 B10

验证检查点

• 可按 backtest_run_id 查询所有结果
• outcome 约束生效
• tp1_hit、tp2_hit、invalidated_before_entry 可正确记录

回滚说明

• 先删除明细结果
• 再回滚 backtest_runs
• 生产环境优先逻辑废弃而非直接物理删除历史

---

5. 建议的 migration 文件命名

001_base_conventions.sql
002_create_venues.sql
003_create_instruments.sql
004_create_candles.sql
005_create_candles_partitions.sql
006_create_market_sessions.sql
007_create_swings.sql
008_create_dealing_ranges.sql
009_create_liquidity_pools.sql
010_create_displacement_events.sql
011_create_structure_events.sql
012_create_fvg_zones.sql
013_create_bias_snapshots.sql
014_create_trade_signals.sql
015_create_trade_executions.sql
016_create_backtest_runs.sql
017_create_backtest_results.sql

说明：

• 文档按 batch 归类
• 实际文件可在同一 batch 内继续细拆
• candles 主表和分区建议拆成两个 migration 文件

---

6. 每批次统一验证模板

每个 batch 执行后至少完成以下检查：

1. 表是否创建成功
2. 主键/唯一键/外键是否生效
3. check constraint 是否生效
4. 默认值是否符合设计
5. 一条合法样例插入是否成功
6. 一条非法样例插入是否被拒绝
7. 关键查询是否命中预期索引
8. 验证结果是否记录到执行检查清单

建议每批配套文件：

• verify_XXX.sql
• rollback_XXX.sql
• seed_XXX.sql（如需要）

---

7. 回滚策略总则

1. 严格按依赖逆序回滚
2. 有真实业务数据后，先停写、备份、评估，再做物理回滚
3. seed 与测试数据分开管理
4. 分区表先回滚子分区，再回滚主表
5. 代码已依赖该 migration 时，回滚前必须同步停用相关任务或服务

推荐逆序：

B13 -> B12 -> B11 -> B10 -> B9 -> B8 -> B7 -> B6 -> B5 -> B4 -> B3 -> B2 -> B1 -> B0

---

8. 与开发阶段的对应关系

阶段 0：项目基础设施初始化

• B0
• B1
• B2

阶段 1：基础数据层

• B3
• B4

阶段 2：基础规则层

• B5
• B6

阶段 3：核心信号层

• B7
• B8
• B9
• B10

阶段 4：回测与验证层

• B12
• B13

阶段 5：半自动执行层

• B11

说明：

• 从纯数据库依赖上，backtest_runs 可更早建
• 从交付节奏和验收上，按上面顺序更清晰

---

9. 最小可用落地顺序

若当前目标是尽快启动 MVP，可先完成：

1. B0
2. B1
3. B2
4. B3
5. B4
6. B5
7. B6

完成后即可支撑：

• 行情入库
• session 生成
• swing 识别
• dealing range 识别
• liquidity pool 识别

之后继续：

8. B7
9. B8
10. B9
11. B10
12. B11
13. B12
14. B13

---

10. 任务关闭标准

本 migration 拆分文档完成后，应满足：

• 已写入本地 .md
• 路径存在且可读取
• 批次顺序与 schema 依赖一致
• 每个批次都包含验证检查点
• 每个批次都包含回滚说明
• 能直接作为后续 migration 编写参考