# Quant OS 面向 80 分的目标架构

状态：本轮已建立边界、长期 namespace、机器标准和兼容入口；大模块拆分按
vertical slice 继续进行，不声称已经完成 26k 行重写。

## 1. 架构选择

采用**严格边界的模块化单体 + 专有 runtime 代理**，不是微服务。

原因：

- 个人系统不需要承担微服务的网络、部署和分布式一致性成本；
- QMT、聚宽、Qlib、JQData 有互不兼容的 Python/SDK 运行时，必须物理隔离；
- 决策身份、证据链和本地重放需要单一仓库和明确的事务边界；
- 模块边界可以先在进程内强制，达到真实吞吐或隔离需求后再拆服务。

## 2. 三平面

```mermaid
flowchart LR
  B["Composition root<br/>CLI · runtime wiring"] --> C
  B --> X
  C["Control plane<br/>RunSpec · orchestration · release policy"] --> A["Application use cases"]
  A --> D["Data plane<br/>PIT → research → portfolio → execution"]
  D --> P["Ports"]
  X["Adapters / proprietary runtimes<br/>JQData · Qlib · JoinQuant · QMT · XtTrader"] --> P
  D --> E["EvidenceSink port"]
  C --> E
  X --> E
  E --> V["Evidence plane<br/>manifest · parity · scorecard · claims"]
```

硬规则：

- Control plane 只编排 RunSpec、状态和发布，不计算信号，不直接调用券商 SDK。
- Data plane 只消费不可变输入，产生 model、weight 和 execution intent；它不读
  网页状态或 Gate。
- Evidence plane 只记录已经发生的事实，不得修改 target、order 或 broker fact。
- Adapter 向内实现 port；core 永远不 import `jqdatasdk`、`qlib`、`xtquant`
  或 hosted 平台全局 API。
- `ReadBrokerPort` 与 `TradeBrokerPort` 分离。拥有查询权不等于拥有下单权。
- `composition` 是唯一同时依赖 application/control 与 adapters 的受检装配根；
  adapter 只实现 port，不反向 import application。

## 3. 依赖方向

```text
foundation
    ↑
contracts / ports
    ↑
data | research | portfolio | execution
    ↑
application
    ↑
control
    ↑
composition / CLI

adapters ──implements──> ports
evidence <── consumes immutable envelopes
composition ──wires──> application + control + adapters
```

新 namespace 的边界由 `quant_os.architecture.validate_architecture` 扫描 AST
执行。CI 会拒绝例如 `research -> execution`、`data -> control` 的倒置依赖，
也会拒绝新层绕回根级 `quant60`、`adapters`、`platforms` 或 `tools`。
只有 `composition` 可以临时调用 compatibility 内核；每个 vertical slice
迁完后继续收窄。

## 4. 目录

```text
src/quant_os/
  foundation/    # ID、双时钟、symbol、money
  contracts/     # DTO、schema registry、版本迁移
  ports/         # Data/Engine/ReadBroker/TradeBroker/EvidenceSink
  data/          # PIT snapshot、catalog、quality
  research/      # feature、split、model、evaluate
  portfolio/     # risk、cost、capacity、optimizer
  execution/     # intent、OMS、reconcile、kill switch
  application/   # ingest/train/backtest/publish/shadow use cases
  control/       # RunSpec、orchestrator、release policy
  evidence/      # manifest、claim、parity、maturity
  adapters/      # provider/platform/broker implementations
  composition/   # 唯一受检进程装配根

runtimes/        # portable36、JoinQuant、QMT built-in、Colab
profiles/        # baseline-60、production-80
examples/        # 永不晋级为候选的 smoke 策略
status/          # 可发布静态验收快照
```

`quant_os` 是长期产品 namespace；成熟度只存在于 profile。当前 AST checker
只覆盖新 namespace（现为迁移壳层与新增控制代码），不会把约 26k 行 legacy
自动宣称为已分层。`quant60` 保留两个
兼容发布周期，继续读取/写入现有 V1 artifact，避免历史证据失效。

## 5. 当前代码如何迁移

| 当前模块 | 问题 | 目标位置 | 迁移条件 |
| --- | --- | --- | --- |
| `portable_core.py` | symbol、TargetPackage、动量、sizing、delta 混合 | foundation/contracts/portfolio/execution + example | golden vectors 先行 |
| `experiment.py` | fixture、研究、编排、证据混合 | research + application + evidence | real snapshot Ridge slice 接通 |
| `qmt_shadow.py` | 规划、签名、落盘、重放 3595 行 | execution/application/evidence | 真 QMT contract probe 后冻结 |
| `snapshot_pipeline.py` | 数据、决策、broker clock 混合并依赖 backtest 私有函数 | data + application + execution | 先建立公共合同 |
| `backtest.py` | engine 与 artifact publisher 混合 | local adapter + evidence | V1 manifest reader 保持兼容 |
| 平台 wrapper | JoinQuant/QMT 重复执行逻辑 | shared portable36 consumer + thin mapping | Python 3.6 golden test |
| status builder | 解析 Markdown 形成机器状态 | 只读 machine claims index | 标准/assessment 已先机器化 |

## 6. 唯一决策权威

当前最大结构问题不是文件太大，而是存在两个上游决策权威：

1. 真实 provider snapshot 仍走 `portable-momentum-v1`；
2. Ridge 五层链只在 synthetic research 中产生 TargetPackage。

目标必须统一为：

```text
authorized immutable PIT snapshot
  -> frozen feature/model
  -> portfolio + independent post-risk
  -> TargetPackage (weights, no account quantities)
  -> JoinQuant/QMT thin execution consumer
```

hosted runtime 不再现场重算 Alpha。`portable-momentum` 永远留在 example/smoke，
不能被默认 bundler 静默提升成生产候选。

跨引擎 strict peer 是 local、JoinQuant 与 QMT 的 L1—L5。Qlib 只比较其声明
参与的层级；只有显式导出同一冻结模型和组合实现时，才可提升比较范围。
Alpha158/LightGBM 研究工作流不能冒充 portable candidate 的 L3/L4 peer。

## 7. 分阶段路线

### 已在本轮落地

- 独立仓历史分支；
- `quant_os` 长期 CLI/import，`quant60` 兼容；
- 七维 80 分 machine profile 和 fail-closed evaluator；
- standard/profile canonical hash、可信 Baseline 前置、不可跳过的 77→canary→80
  授权链及 `TEST_ONLY` 信任隔离；
- 新 namespace 层级和依赖检查；
- composition root 与 adapter 单向依赖；
- ReadBroker/TradeBroker/EvidenceSink port；
- 独立根 CI；
- 独立仓 clean-clone 测试修复；
- 架构、标准、迁移和上手文档。

### 下一阶段

1. 建立 golden vectors 和 V1/V2 schema registry；
2. 把真实 snapshot 接入 Ridge 主链，消除双决策权威；
3. 先拆一个完整 vertical slice，而不是按文件批量搬家；
4. 平台 wrapper 收敛为同一个 portable consumer；
5. status builder 改读统一 claims index，不再解析 Markdown；
6. 取得真实 QMT 后接通 read-only contract probe、shadow 和对账。

### 依赖外部环境的阶段

- 完整授权 JQData/OOS；
- 多期真实聚宽导出；
- 真 QMT/qmttools/XtTrader；
- 60 个交易日 shadow；
- 10 个交易日受限资金 canary；
- 生产 SLO、RPO/RTO、凭据轮换、券商程序化交易确认。