feat: establish Quant OS production-80 architecture
This commit is contained in:
@@ -0,0 +1,167 @@
|
||||
# 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、凭据轮换、券商程序化交易确认。
|
||||
Reference in New Issue
Block a user