系列目录：/carver/
上一篇：全景蓝图 | 下一篇：实现手册

说明：本文发布自个人研究笔记；文中出现的 docs/...、sys... 等文件名仅用于定位概念/实现位置，公开站点不提供对应仓库链接。

状态：stable
读者：开发 / 研究
定位：作为 carver-quick-reference.md、carver-blueprint.md、carver-implementation-guide.md 的数据侧补充，聚焦 Phase 0 数据工厂（roll calendars / multiple prices / adjusted prices / FX / costs）以及它如何喂给回测与生产系统。

安全约定：本文仅描述流程与接口，不会触发任何真实交易；涉及 production 的命令仅作为索引，需读者自行确认与执行。

前置知识：术语速查

完整术语表见 glossary.csv；本节只覆盖 Phase 0 / 数据侧最常用词。

📖 阅读导航

本文按 跟随数据流 组织：

如需“一张表看清要什么数据 / 从哪来 / 落到哪”，直接跳到 附录 B。

0. 坐标系：Layer / Phase / Level 别混用

注：Level 0–3 是横向分层，不参与 Phase 0–3 / Layer 1–4 的纵向流水线；本文只把它作为“策略分级语境”的背景信息。

本文关注 Phase 0：把原始素材加工成系统可消费的数据资产。

1. 端到端总览：从素材到订单

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

flowchart TD
  %% ===== Sources =====
  subgraph S[Sources 原始素材]
    S1[Individual futures contract prices<br/>per-contract daily close, optional intraday]
    S2[Spot FX prices]
    S3[Instrument config / contract spec<br/>multiplier, currency, region, etc.]
    S4[Roll parameters<br/>priced/hold cycle, offsets, carry offset]
    S5[Spread costs / fees model]
  end

  %% ===== Phase 0 =====
  subgraph D[Phase 0 Data Factory 数据工厂]
    D1[Roll calendars CSV<br/>readable, editable, checks]
    D2[Multiple prices<br/>PRICE/FORWARD/CARRY and contracts]
    D3[Adjusted prices<br/>single continuous back-adjusted series]
    D4[Derived features - optional<br/>returns/vol]
  end

  %% ===== Layer 1 =====
  subgraph R[Layer 1 Risk and Capital]
    R0[Capital / account value<br/>production: broker; backtest: sim]
    R1[InstValVol<br/>price vol × multiplier × FX]
    R2[DailyCashRisk<br/>capital × target vol / √256]
  end

  %% ===== Phase 1-3 =====
  subgraph F[Phase 1 Forecast Factory]
    F1[Trend / Carry signals]
    F2[Forecast scaling and cap]
  end

  subgraph P[Phase 2 Portfolio]
    P1[Weights and IDM]
    P2[Continuous target positions]
  end

  subgraph X[Phase 3 Execution]
    X1[Risk overlay and buffer]
    X2[S25 optimize to integer positions]
    X3[Orders and stack handler]
  end

  R0 --> R2
  S --> D
  D --> F
  D --> R
  R --> P
  F --> P
  P --> X

上图展示了从原始素材（Sources）到订单执行（Phase 3）的完整流程。本文聚焦 Phase 0 Data Factory 部分。

2. 原材料准备：Phase 0 需要什么输入

1
2
3
4
5
6
7

flowchart LR
  S1[Per-contract prices]:::active --> D[Phase 0 Data Factory]
  S2[Spot FX]:::active --> D
  S3[Instrument config]:::active --> D
  S4[Roll parameters]:::active --> D
  S5[Spread costs]:::active --> D
  classDef active fill:#4CAF50,stroke:#333,color:#fff

注：端到端总览图将 Capital / account value（production: broker; backtest: sim）画在 Layer 1 Risk and Capital，因为它属于 Layer 1 的输入，不属于 Phase 0 数据工厂输入。

口径说明：本文将 Phase 0 Data Factory 视为“系统可消费数据资产的落盘与 QA 总称”。其中 roll calendars → multiple → adjusted 是核心三道工序；Spot FX / spread costs / instrument config 等属于 side stream：它们不参与三道工序，但需要在 Phase 0 阶段完成更新、校验与落盘，供 Layer 1 / 回测 / 生产消费。

Phase 0 的输入主要分为两类：静态配置与市场数据；此外本节补充 Spot FX 的命名约定与 base_currency。

2.1 静态配置（低频更新）

补充：rollconfig.csv 的 ExpiryOffset（代码里常见叫 approx_expiry_offset）与 RollOffsetDays 用于粗略估算“合约名义到期日”与“理想 roll 日期”（详见 docs/data.md）：

• Bund 示例：ExpiryOffset=6、RollOffsetDays=-5 ⇒ 名义到期日为当月第 1+6=7 天，理想 roll 日为第 1+6-5=2 天
• SOFR 示例：ExpiryOffset=18、RollOffsetDays=-1000 ⇒ 距离名义到期约 1000 天 roll（极端但真实存在）

2.2 市场数据（日更）

2.3 Spot FX：命名约定与 base_currency

• FX code 格式：GBPUSD 这种 6 字符形式（CCY1CCY2），CSV 文件名同 code（如 GBPUSD.csv），常见列为 DATETIME / PRICE（见 sysdata/csv/csv_spot_fx.py）。
• 数学语义：CCY1CCY2 的 PRICE 表示 1 CCY1 = PRICE CCY2；将 CCY1 金额换算到 CCY2 用乘法，反向用倒数（例如 V_USD = V_GBP × GBPUSD）。
• 默认货币与交叉汇率：PST 的 spot FX 默认基准货币为 USD（可通过 config.base_currency 配置）；通常准备各币种对默认基准货币的序列（如 GBPUSD）。当需要 cross 时，系统会推导；USDXXX 会做反向。
• 基准货币：回测与生产都会用 config.base_currency 作为 PnL/风险汇总的基准货币。

2.4 ⚠️ Baseline vs SSOT（生产必需）

提醒：PST 仓库自带的 data/futures/*_csv（multiple/adjusted/roll calendars/FX）通常只适合 demo/backtest baseline，用于“先跑通”。进入 paper/sim/live 前，应建立自己的 SSOT 数据集（建议 Parquet + Mongo），并具备日更/回补路径；展期事件由 roll status 驱动（需要登记/自动化），否则增量更新会报错或写入不一致数据。

3. 数据工厂：把单合约变成连续序列

Phase 0 的核心任务是通过三道工序，把离散的单合约价格加工成系统可消费的连续序列：

3.1 工序 1：确立切换时间轴（Roll Calendars）

1
2
3
4
5
6

flowchart LR
  S1[Roll params] --> D1[Roll Calendars]:::active
  S2[Per-contract prices] --> D1
  D1 --> D2[Multiple prices]
  D2 --> D3[Adjusted prices]
  classDef active fill:#f96,stroke:#333

Roll calendars 的本质：一张表，记录每次从 current_contract 切换到 next_contract 的日期。

PST 官方文档的定位非常明确：只存 CSV、可读可手改、并且需要检查。见 docs/data.md。

注：官方也指出 roll calendars 在生成 multiple prices 后通常不会在日常运行中继续使用（主要用于冷启动/重建/修复）；生产日更主要依赖 roll status + existing multiple/adjusted（见 §4.2）。

三种生成路径（从严谨到省事）：

CSV 典型列：DATE_TIME, current_contract, next_contract, carry_contract

关键断言（QA gate）：

• ✅ 单调性与有效性检查无异常（monotonicity / validity）
• ✅ roll 日必须能找到 current_contract 与 next_contract 同日有价的匹配点
• ✅ 节假日/缺失交易日：允许自动寻找最近可交易日，但需记录可人工复核

本仓约定：除非明确要求，不覆盖根目录 data/ 的上游 baseline；roll calendars 的 SSOT 放在 private/ 下。

3.2 工序 2：对齐三合约价格（Multiple Prices）

1
2
3
4
5

flowchart LR
  S[Per-contract prices] --> D1[Roll Calendars]
  D1 --> D2[Multiple prices]:::active
  D2 --> D3[Adjusted prices]
  classDef active fill:#f96,stroke:#333

Multiple prices 的本质：每个交易日保存三条价格序列及其对应合约：

注：构建阶段通常只用 per-contract prices 的 FINAL（收盘/结算；不使用完整 OHLC），细节见 docs/data.md 的 multiple prices / adjusted prices 说明。

常见失败模式（应在 Phase 0 解决，而不是带病进 Phase 1）：

• ❌ roll calendar 指向了不存在的合约代码
• ❌ roll 日没有价格，或 current/next 缺少重叠
• ❌ 合约切换导致的价格跳变与预期不一致

3.3 工序 3：缝合连续序列（Adjusted Prices）

1
2
3
4
5

flowchart LR
  S[Per-contract prices] --> D1[Roll Calendars]
  D1 --> D2[Multiple prices]
  D2 --> D3[Adjusted prices]:::active
  classDef active fill:#f96,stroke:#333

Adjusted prices 的本质：一条“假想的连续 K 线”，通过 back-adjustment 消除合约切换的价格跳变。

趋势类策略（例如 EWMAC）通常在这条连续序列上计算。其正确性强依赖于：

• ✅ roll calendar 的合理性（切换点是否可交易、是否有重叠）
• ✅ multiple prices 的一致性（同日合约映射是否稳定）

3.4 Derived features：哪些落盘，哪些运行时计算

目标：避免读者在“到底存不存/存哪”上卡住；下表给出建议口径（可按性能与可追溯需求调整）。

4. 下游对接：回测与生产如何消费

Phase 0 产出的数据资产，分别被回测和生产两条链路消费：

4.1 回测如何消费（csvFuturesSimData）

sysdata/sim/csv_futures_sim_data.py 的 csvFuturesSimData 会组装以下数据类：

• csvFuturesAdjustedPricesData
• csvFuturesMultiplePricesData
• csvFuturesInstrumentData
• csvFxPricesData
• csvRollParametersData
• csvSpreadCostData

官方回测入口与 CSV 目录约束见 docs/backtesting.md。

CSV 目录约束：PST 的 CSV 命名习惯通常以 INSTRUMENT_CODE.csv 为文件名；因此不同类型的数据必须放在不同目录，否则会发生文件名冲突。

Carry data 的来源：在 simData 接口里，carry data 是从 multiple prices 的 CARRY / CARRY_CONTRACT 列切出来的子集（Just-in-Time 提取），因此不需要维护独立的 carry 数据目录。

4.2 生产如何消费（日更 DAG）

PST production 的主干思想是：夜间跑一次带真实资本的 system run 产出 buffers/optimal positions，白天交易引擎按 buffers 执行；详见 docs/production.md。

数据存储范式：

• 状态/元数据：MongoDB
• 时间序列：Parquet
• roll calendars：CSV（可读可手改）

本仓本地落盘与目录约定见 local_data_management.md；IB 数据冷启动与日更 SOP 见 production_daily_data.md。

典型日更步骤：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

sequenceDiagram
  autonumber
  participant Sch as Scheduler/Cron
  participant Upd as Data Updates - Phase 0
  participant DS as Data Store
  participant Sys as System Runner - Phase 1-2
  participant Exec as Execution - Phase 3

  Sch->>Upd: update_fx_prices / update_sampled_contracts / update_historical_prices
  Upd->>DS: write FX, per-contract prices
  Sch->>Upd: update_multiple_adjusted_prices
  Upd->>DS: write multiple, adjusted

  Sch->>Sys: run nightly system run
  Sys->>DS: write optimal positions, buffers, state

  Sch->>Exec: generate orders, stack handler
  Exec->>DS: write trades / positions / logs

顺序不可交换的原因（最小因果）：

• update_sampled_contracts 决定本次需要更新哪些品种/合约范围，直接影响 update_historical_prices 的更新集
• update_historical_prices 是 update_multiple_adjusted_prices 的上游（没有最新 per-contract 就无法正确增量 multiple/adjusted）
• update_fx_prices 需要在 nightly system run 前完成，否则 Layer 1 的换汇/风险与 PnL 汇总会使用旧汇率

冷启动/重建 vs 生产日更（官方口径）

• 冷启动/重建：按 docs/data.md 从 per-contract prices + roll parameters 构建/校正 roll calendars，再生成 multiple/adjusted（这也是 roll calendars 最常用的场景）。
• 生产日更：按 docs/production.md 运行 update_fx_prices → update_sampled_contracts → update_historical_prices → update_multiple_adjusted_prices 做增量更新；是否发生展期由 roll status 控制，需要通过 interactive_update_roll_status（见 sysproduction/interactive_update_roll_status.py；或自动流程）登记，否则 update_multiple_adjusted_prices 会报 “roll has occurred but not registered properly”（见 sysproduction/update_multiple_adjusted_prices.py）。

本仓约定：涉及 paper/sim/live 的任何实盘调度与券商连接，默认只在 runbook 中给出命令与说明，不在架构文档里固化可直接执行的 live 操作。

5. 扩展话题

5.1 Universe 管理

PST 官方文档强调，instrument list 在不同阶段会被分层筛选：见 docs/instruments.md。工程上建议把 Universe 视为一级数据资产（可版本化、可审计），并与资金/成本约束联动：

• 官方 instrument sets 的最小总结（建议牢记）：

  • Superset：由 data/futures/csvconfig/instrumentconfig.csv 定义所有“可能交易”的品种全集（通常包含很多你不会立刻交易的品种）。
  • Sampling instruments（production）：用于抓取/更新合约价格的品种集合，官方默认“以 multiple prices 已存在的品种为准”（这会影响 update_sampled_contracts / update_historical_prices）。
  • Instruments with adjusted prices：用于回测与 production system backtest rawdata 的品种集合（常见入口 system.data.get_instrument_list()）。
  • System instrument list：从 “有 adjusted prices 的品种集合” 出发，再叠加 config.instruments 与各种 exclude lists（duplicate/ignore/bad_markets/trading_restrictions 等）得到最终用于计算与优化的集合。

• CN 链路参考：./cn_universe_and_capital_pipeline.md、./cn_futures_data_flow.md

• 全局链路参考：./global_universe_and_capital_pipeline.md

• 分组机制参考：./instrument_groups.md

5.2 可追溯与可复现

建议最小做到：

• 每次 system run 产出可回放的快照：config snapshot + 数据版本号 + buffers/positions 输出
• Phase 0 的派生数据可追溯：adjusted/multiple -> roll calendar -> per-contract prices
• 对数据异常采取“宁可停更也不写坏”的策略（spike checks / 人工复核门）

5.3 MVP 路线

建议按 Carver 的“先基准后叠加”：

1. 先跑 Level 0 基准（S04），确认 Phase 0 数据资产闭环可用
   验收标准：目标交易品种均具备 adjusted/multiple/roll calendars，核心 QA gate 通过；Spot FX 覆盖 config.base_currency 与品种币种的换汇需求
2. 上线 Core Engine（S09 Trend + S10 Carry），确保 forecast 标准化与 IDM 上限受控
   验收标准：forecast scaling/cap 生效；IDM 上限生效；回测与 nightly system run 可稳定产出 buffers/optimal positions
3. 再逐步增加 Satellites / Research，并接入 Speed&Size 的横向约束
   验收标准：成本/容量/执行约束能触发 throttle/kill（或等价的风控降档），并在日志/监控中可观测

6. 参考入口

Carver 三件套（本仓）：

• carver-quick-reference.md
• carver-blueprint.md
• carver-implementation-guide.md

PST 官方文档（根 docs/）：

• docs/data.md（futures data objects、roll calendars、multiple/adjusted、存储范式）
• docs/backtesting.md（csvFuturesSimData、CSV paths 约束）
• docs/production.md（daily updates、夜间 backtest-style run、数据存储与备份）
• docs/instruments.md（instrument list 的分层筛选逻辑）

相关源码：

• sysdata/sim/csv_futures_sim_data.py

附录 A：数据资产速查表

本节为参考手册，供开发时查阅字段定义和依赖关系。

A.1 最小可用数据资产（可回测 + 可生产的共同底座）

A.2 依赖链

1
2
3
4

roll parameters + per-contract prices -> roll calendars
roll calendars + per-contract prices  -> multiple prices
multiple prices                       -> adjusted prices
instrument config + spread costs + adjusted/multiple + FX -> backtest / production inputs

A.3 Phase 0 工序断言汇总

附录 B：数据流向总表（要什么数据 / 从哪来 / 落到哪）

目标：用一张表串起“要准备什么数据、可能从哪获取、与系统的关系、建议落盘位置”，避免为此反复翻 docs/production.md。

B.1 一页流向（从原始到消费）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

flowchart TD
  %% ===== Inputs =====
  subgraph IN[Inputs 你需要准备/维护]
    C1[instrument config<br/>instrumentconfig.csv]
    C2[roll parameters<br/>rollconfig.csv]
    C3[spread costs<br/>spreadcosts.csv / mongo]
    M1[per-contract prices<br/>每合约日线/日内（OHLCV）]
    M2[spot FX<br/>GBPUSD, EURUSD...]
    A1[capital/account value<br/>production only]
  end

  %% ===== Phase 0 =====
  subgraph P0[Phase 0 Data Factory]
    R0[roll calendars<br/>CSV 可读可手改]
    MP[multiple prices]
    AP[adjusted prices]
    AUX[side stream assets<br/>FX / costs / config]
  end

  %% ===== Stores =====
  subgraph S[Stores（推荐 SSOT）]
    SCSV[CSV（配置/roll calendars）]
    SPQ[Parquet（时间序列：prices/FX/multiple/adjusted...）]
    SMG[MongoDB（状态/元数据：contracts/roll state/orders/spread costs...）]
  end

  %% ===== Consumers =====
  subgraph CON[Consumers]
    BT[csvFuturesSimData / dbFuturesSimData<br/>Backtest]
    PROD[sysproduction + sysexecution<br/>Paper/Sim/Live]
  end

  C1 --> AUX
  C2 --> R0
  C3 --> AUX
  M1 --> R0
  M1 --> MP
  M2 --> AUX

  R0 --> MP --> AP --> CON
  AUX --> CON
  A1 --> PROD

  C1 --> SCSV
  C2 --> SCSV
  R0 --> SCSV
  M1 --> SPQ
  M2 --> SPQ
  MP --> SPQ
  AP --> SPQ
  C3 --> SMG
  PROD --> SMG

提醒：PST baseline CSV 通常只适合 demo/backtest baseline；进入 paper/sim/live 前需建立自己的 SSOT（同 §2.4）。

备注：PST 早期版本曾使用 Arctic 替代 Parquet 存储时间序列（现已弃用；见 docs/production.md）。本仓统一使用 Parquet。

注：生产日更通常不会从 roll calendars 重新生成 multiple/adjusted，而是在已有 multiple/adjusted 上做增量更新；发生展期由 roll status 驱动。

B.2 数据资产总表（要什么 / 从哪来 / 落到哪）

B.2.1 静态配置（低频更新）

B.2.2 原始市场数据（必须外部获取）

B.2.3 Phase 0 派生资产（你生成/维护）

B.2.4 运行产物（系统运行生成）

本仓的数据/产物目录建议遵循 local_data_management.md：配置进 Git、数据与产物出 Git。

B.3 典型问题：如何“更新 multiple prices”？

以 data/futures/multiple_prices_csv/ 为例：

1. **生成/重建 multiple prices（从无到有）**通常依赖两样：
   • roll calendars（告诉系统某天 current/next/carry 是哪个合约）
   • per-contract prices（这些合约在这天的价格；PST 通常用 FINAL）
2. **生产日更的增量更新（无展期）**通常依赖：
   • existing multiple prices + per-contract prices（官方入口为 update_multiple_adjusted_prices，见 sysproduction/update_multiple_adjusted_prices.py；会对现有 multiple/adjusted 做增量更新）
3. 发生展期（roll）时：需要先更新 roll status（例如 interactive_update_roll_status），再写入新的 multiple/adjusted；否则 update_multiple_adjusted_prices 会拒绝更新。
4. 是否需要写回 data/futures/multiple_prices_csv/？
   • 一般不需要：该目录更适合作为上游 baseline 对照。
   • 若你确实需要 CSV（例如纯 CSV 回测），建议写到 private/ 的数据目录，并在配置中指向它，而不是覆盖 data/。

B.4 相关入口（进一步深挖时再点）

• Phase 0 细节与断言：carver-data-pipeline.md
• 数据/产物目录规范：local_data_management.md
• PST 官方数据对象与生成脚本索引：docs/data.md
• PST 生产调度全貌（详细但庞大）：docs/production.md