基金量化定投选基系统

# 系统架构与工程规范基线

> **文档属性**：技术真相源

> **同步规则**：若 `src/` 下的架构发生变更，此文档必须同步更新，否则将触发 CI 软预警。

## 1. 计算引擎防火墙

系统数据处理严格遵循 `DuckDB ↔ Polars` 职责防火墙，这是防止 OOM 和性能劣化的核心铁律：

| 引擎 | 职责边界 | 严禁事项 |

| :--- | :--- | :--- |

| **DuckDB** | Parquet 读写、跨表 JOIN（如关联 fund_basic_info）、行列过滤、COUNT/SUM 审计 | **严禁**执行任何滚动窗口函数（如 `rolling`、`window` 子句） |

| **Polars** | 滚动窗口计算、EWM 指数加权、截面 Z-Score、标签向量化生成、共线性筛选 | 严禁直接读取多年份大表，必须按年份串行提取 Arrow |

**内存安全底线**：DuckDB → Polars 的数据交割，单次 Arrow 转换必须 ≤ 单年数据量（约 300 万行）。

## 2. 全局工程约束

- **依赖隔离**：全局严禁显式 `import pandas`（仅允许 LightGBM `.fit()` 内部隐式调用）。CI 层已部署 AST 级拦截红线。

- **消除魔法数字**：所有涉及业务逻辑的参数（如 150周、20%止盈、0.90共线性阈值）必须声明于 `config/config.yaml`。代码中仅允许存在 `0, 1, -1` 等基础索引数字。CI 层已部署 AST 扫描红线。

- **类型约束**：所有自定义函数必须具备完整的 Python Type Hints（参数类型 + 返回值类型）。

## 3. 双轨制协作体系

本项目采用 Redmine（管理中枢） + Gitea（技术真相）双轨制，杜绝文档与代码脱节：

- **Gitea (技术侧)**：所有架构设计、数据流向、特征字典必须以 Markdown 形式沉淀在仓库根目录的 `/docs` 下，与代码同版本回溯。

- **Redmine (管理侧)**：任务的拆解以交付物为导向。规约条款被拆解为 Redmine 任务的【自定义字段-验收标准】，开发人员不得自行降低验收标准。

- **联动规则**：若 Gitea PR 检测到仅修改了 `src/` 而未修改 `docs/`，CI 将输出 Warning，PM 视情况有权在 Redmine 打回任务。

## 4. 数据血缘与质量追溯

为保证每周“全量刷盘重训”的可追溯性：

- 任何步骤产出 Parquet 文件时，必须计算其 SHA-256 并追加至 `data/metadata/*.json`。

- Pipeline 启动时比对 Hash：若上游原始数据 Hash 变更，将触发 WARNING 级别日志，提示需关注数据源异常，但不强制中断流水线（避免因微小修正导致全链路不可用）。