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

文档属性：技术真相源
同步规则：若 src/ 下的架构发生变更，此文档必须同步更新，否则将触发 CI 软预警。

1. 计算引擎防火墙¶

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

内存安全底线：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 级别日志，提示需关注数据源异常，但不强制中断流水线（避免因微小修正导致全链路不可用）。