quant-os/IMPLEMENTATION_PLAN.md

# Quant OS implementation plan

Quant OS 是项目名；`quant60` 是第一版 A 股 Baseline 内核、CLI namespace
和 artifact 协议前缀。终态不是“仓库里有若干 adapter”，而是本地研究证据链
可无人值守重放、聚宽登录后可直接回测、QMT 授权环境就绪后无需改源码即可完成
回测/影子验证，并且所有 G1—G10 都由版本绑定的真实证据支持。

当前结论仍为 `NOT_BASELINE_60`。标准库全量测试证明代码合同，不证明真实
平台、券商或合规 Gate；测试总数随合同补充会变化，不作为 Gate 分数。

## Stage 1: 独立仓库与确定性执行

**目标**：Quant OS 代码独立于 Obsidian 文档，并有一条可重复的本地验证入口。

**已实现**：

- `quant-os/` 是独立项目目录，Obsidian 只保留项目说明和验证文档；
- `make local` / `scripts/validate_all.sh` 串联测试、bundle、execution smoke、
  research smoke、manifest verifier、mock parity、capability probe 和 Colab
  notebook 执行；
- 聚宽与 QMT 内置策略由同一个 Python 3.6-compatible portable core 生成；
- Gitea CI 定义和 Colab notebook 已提供。

**状态**：本地功能实现完成；CI 首次远端运行记录仍需随提交保存。Stage 1
完成不等于任一 Gate 自动通过。

## Stage 2: 数据快照、研究与目标生成

**目标**：把 PIT 数据、Universe、透明特征、时间有序验证、风险/成本和约束
组合连接成可审计的 research-to-target 链。

**已实现**：

- PIT `effective_time` / `available_time`、修订版本和未来值 fail-closed；
- openable / hold-only / sell-only / frozen / excluded 状态与原因码；
- 透明价量特征、可执行时钟标签、train-only 预处理；
- purged walk-forward、deterministic Ridge challenger、IC/RankIC 报告；
- Ridge train-only 预处理、系数、标签、训练截止日与 lineage 的冻结 model
  bundle；
- 一条真实可达的 synthetic vertical slice：Universe → Ridge Alpha →
  60 日对角风险与日期化成本参与的 deterministic Portfolio → post-risk →
  reference Execution，并输出五层 hash trace；
- 无账户股数的 `TargetPackageV1`，绑定 model/data/feature/risk/cost/
  optimizer/config/source hash 与 T-close/T+1 双时钟；
- 独立组件仍包括透明因子风险、CVXPY optimizer 与 guarded TWAP/POV；
- JQData adapter 通过 `get_bars` 获取 raw OHLCV/money、factor、`pre_close`、
  每日涨跌停/停牌字段，通过 `get_extras` 获取 PIT `is_st`，并逐交易日
  获取 PIT 指数成员；区间 `get_trade_days` 必须与 `get_all_trade_days`
  一致，并冻结唯一下一交易日；当日未到 24:00 的日线和任何覆盖缺口均
  fail closed；
- snapshot verifier 会重建领域对象、重算质量汇总和 `data_version`；
- 已验证 snapshot 可直接进入 `snapshot-backtest` 和
  `snapshot-decision`，后者支持 canonical broker snapshot 的
  fail-closed 账户状态输入；
- synthetic research artifacts 和 snapshot decision artifacts 都有精确
  manifest verifier。
- 每层部署状态由 reachability contract 分开记录 implemented、unit tested、
  local/JQ/QMT entrypoint reachable 与 real-platform observed。

**仍缺**：

- 授权 JQData 账户上的真实快照、长样本质量报告和许可记录；
- 完整 Security Master、基本面公告时点、公司行动与退市链；
- 真实样本风险/冲击/容量校准；
- 授权真实数据训练的 model bundle、真实 OOS 报告与跨引擎 TargetPackage
  执行验证；
- 把 factor risk/CVXPY/TWAP-POV 从组件级测试提升到经过取舍的候选主链。

**状态**：synthetic 五层 vertical slice 与交换合同完成；provider-data
Baseline candidate、真实校准和生产证据未完成。Ridge 仍是 research
challenger，不是已部署模型。

## Stage 3: 平台回测与跨引擎证据

**目标**：在相同冻结信息集和策略版本上保存本地、聚宽、QMT 与 Qlib 的
逐层结果，而不是只比较净值。

**已验证**：

- 本地 deterministic execution/research 与 manifest 重放；
- JoinQuant/QMT fake wrapper 合同和 mock parity exporter；
- JoinQuant/QMT 的 TargetPackage 消费模式：本地上游四层保持唯一权威，
  平台只做严格包验证、双时钟命中、账户/价格绑定与 execution；不存在
  momentum fallback；
- 2026-07-26 使用生成 bundle 完成 2024 全年真实 JoinQuant hosted
  backtest，可见完成日志无 ERROR；该运行还促成 hosted namespace、
  科创板保护价与 200 股最小申报的真实修复；
- CPython 3.12 + `pyqlib==0.9.7` native momentum fixture smoke，
  实际生成 24 条 signal，并保存 signal/report hash、表边界和重算指标；
- Qlib Alpha158 + LightGBM + Recorder fixture smoke 已真实成功，
  runner 会为本地 MLflow file store 设置
  `MLFLOW_ALLOW_FILE_STORE=true`，并保存 model、SignalRecord、
  SigAnaRecord 和 PortAnaRecord，同时读取 portfolio report 保存 hash、
  表边界、重算指标与 artifact path。

Qlib 两次 smoke 使用的是确定性两股票 synthetic fixture，性能没有投资意义，
也不证明 A 股逐日涨跌停/T+1/目标订单语义。mock parity 的
`evidence_class=mock_contract_only`、`real_platform_pass=false`，
因此不能计入 G9。

**仍缺**：

- 同一个 TargetPackage 的聚宽完整 package/plan/orders/fills 导出和本地 peer；
- 同一个 TargetPackage 的授权 QMT built-in 与 qmttools 回测导出；
- Baseline 60 至少 20 个交易日、Production 80 同一冻结候选至少 60 个交易日
  的真实 QMT/broker shadow；
- 同一 canonical 输入的 L1—L5 差异报告。

**状态**：部分完成；JoinQuant runtime smoke 已执行，但 strict comparison、
真实 QMT 和 broker 运行仍未完成，G9 保持 `not_passed`。

## Stage 4: Broker-safe shadow operation

**目标**：完成查询、callback replay、重启恢复、持续对账、
guarded TWAP/POV 和影子证据。

**已有基础**：

- XtTrader adapter 默认禁止 live mutation；
- operator CLI 严格只读，能生成 HMAC 账户绑定的 broker
  observation/snapshot、target-diff shadow plan 与 exact manifest；
- T 日完整 Signal 只能与冻结 provider calendar 的唯一下一交易日
  Asia/Shanghai `[09:00,09:30)` broker observation 显式绑定，保留两个
  时钟；同日、周末近似、错窗、错误 session 和迟到补查均失败关闭；
- 严格类型、提交前幂等 reservation、单调状态回调、fresh
  account-bound guard 和审计记录；
- hash-chain ledger、重复/乱序重放和完整 broker snapshot 对账合同。

**仍缺**：

- 券商实际状态码映射与脱敏回调；
- 实际 QMT query API 的失败/空列表合同探针；
- durable scheduler/recovery daemon；
- Baseline 60 的 20 个交易日 shadow（Production 80 为同一冻结候选 60 日）、
  日终零未知账差和故障恢复演练；
- 券商权限、频率、软件和程序化交易报告确认。

**状态**：仅有未认证的安全边界；不可视为 live-ready。

## Stage 5: Baseline-60 evidence

**目标**：证据评分至少 60，且 G1—G10 十道硬门全部 `passed`。

**状态**：未开始计分。当前 [`gate_scorecard.json`](gate_scorecard.json)
中 G1—G10 全部 `not_passed`。源文件、单测、synthetic、fixture、fake
harness 和成功的 Qlib smoke 都不能替代真实数据、平台、券商和合规证据。

## 当前验证入口

```bash
# 核心、本地两条 synthetic 链、bundle、mock parity、Colab
make local

# JQData 授权后：快照 -> 语义校验 -> PIT 回测/决策
python3.12 -m venv .venv-jqdata
source .venv-jqdata/bin/activate
python -m pip install -r requirements/jqdata.txt
PYTHONPATH=src:. python tools/jqdata_snapshot.py \
  --index 000905.XSHG --start 2024-01-02 --end 2024-12-31 \
  --output data/snapshots/csi500-2024
PYTHONPATH=src:. python -c \
  "from quant60.data_snapshot import verify_data_snapshot; verify_data_snapshot('data/snapshots/csi500-2024/manifest.json')"
PYTHONPATH=src:. python -m quant60 snapshot-backtest \
  --snapshot data/snapshots/csi500-2024/manifest.json \
  --config configs/baseline.json --output artifacts/csi500-2024-backtest
PYTHONPATH=src:. python -m quant60 snapshot-decision \
  --snapshot data/snapshots/csi500-2024/manifest.json \
  --config configs/baseline.json --as-of 2024-12-31 \
  --equity 1000000 --output artifacts/csi500-2024-decision

# Qlib 0.9.7 独立环境
python3.12 -m venv .venv-qlib312
source .venv-qlib312/bin/activate
python -m pip install -r requirements/research-py312.txt
python tools/build_qlib_tiny_fixture.py artifacts/qlib-fixture --days 400
```

平台真实运行和证据保存步骤见
[`runbooks/PLATFORM_DEPLOYMENT.md`](runbooks/PLATFORM_DEPLOYMENT.md)。