基金量化定投选基系统

# Sprint 1 规划会议纪要：工程脚手架与架构护栏落地

**会议日期**：2026-04-11

**项目名称**：基金量化定投选基系统 (2026-04-11-01)

**会议目标**：锁定 M1 交付标准，对齐 NFRs 与跨团队依赖，输出首版架构决策记录（ADR），确立“规约即代码”的零偏移基线。

**参会角色**：项目经理（Henry Lin）、算法/研发工程师、基础架构/运维工程师、数据资产管理员。

---

## 一、 会议确认项

1. **CONF-01 结构化日志 Schema 强制约束**：`logging.py` 必须强制输出包含 `timestamp`, `level`, `module`, `step`, `message` 的 JSON 格式日志，作为后续全链路审计唯一合法格式。

2. **CONF-02 凭证与敏感信息架构隔离**：`config.yaml` 永远仅存放非敏感业务参数。任何敏感信息必须通过环境变量注入，Pydantic 加载器将此作为校验阻断铁律。

3. **CONF-03 依赖源连通性契约**：PyPI 强制锁定清华大学镜像源 `https://pypi.tuna.tsinghua.edu.cn/simple`；Dockerfile 基础镜像及构建阶段强拉内部私有镜像服务 `private-docker-repo:20706`。

4. **CONF-04 Pandas 依赖防御边界划定**：采用“环境容忍、代码绝对禁止”策略。允许 Pandas 作为第三方库隐式依赖存在于运行环境，但 CI 的 AST 脚本仅硬拦截扫描 `src/` 目录下的手写 `import pandas` 及其变体，不折腾依赖树排除机制。

5. **CONF-05 配置中心可序列化演进约束**：`config.py` 的 `Settings` 类必须提供专用的序列化接口（如 `dump_for_mlflow()`），在输出字典时自动剔除标记为敏感的字段，确保输出物可直接无缝对接 Step 5 的 `mlflow.log_params()`。

6. **CONF-06 规约拦截器配置化策略**：AST 拦截器（`lint_ast.py`）的“魔法数字黑名单”严禁硬编码，必须抽离为独立文本配置文件（如 `.magic_numbers.blacklist`），拦截器运行时动态读取，实现规约变更与拦截代码解耦。

7. **CONF-07 Sprint 1 工具类单测覆盖基线**：拒绝积压单测技术债。M1 阶段必须为 `config.py`（环境覆盖与剔除逻辑）和 `hash.py`（流式计算）编写真实运行的单测，CI 阶段由 `--collect-only` 升级为实际执行验证。

8. **CONF-08 双轨制 CI 软预警首次执行尺度**：从 Sprint 1 第一个 PR 起，严格执行“改 `src/` 必改 `docs/`”的软预警规则，初始化阶段不申请豁免，确立双轨制协作零妥协基线。

---

## 二、 会议待办项

| 编号 | 责任人 | 任务描述 | 截止时间 | 验收标准 |

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

| **TODO-01** | 基础架构 | CI/CD 资源隔离配置 | 本周三 | 完成 Gitea Action Runner Docker 执行环境的 `memory=50g` cgroup 硬限制，配置截图上传至 Redmine S1-04 任务附件。 |

| **TODO-02** | 数据资产/PM | 上游数据源 SLA 契约签署 | 本周五 | 输出《四核心字段稳定性承诺函》并推动上游团队完成签署。 |

| **TODO-03** | 研发工程师 | 上游核心字段强校验逻辑 | Sprint 1 交付 | 在 `data_loader.py` 入口对 `fund_id, fund_name, fund_type, create_date` 做存在性与类型强校验，缺失即抛异常阻断，写入单元测试覆盖。 |

---

## 三、 会议风险项

| 编号 | 风险描述 | 应对策略/演进路线 | 跟踪机制 |

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

| **RISK-01** | 当前依赖清华公共 PyPI 源，存在供应链不可控及合规隐患。 | 短期可接受；长期企业级治理路线图必须纳入“自建内部 PyPI 服务（如 devpi）”评估。 | 作为架构治理储备项录入 Redmine 资产库，每季度 Review 一次基建规划。 |

---

## 四、 会议架构决策记录（ADR）产出要求

基于本次会议确认的 CONF-04 至 CONF-06，要求研发工程师在会后首个 PR 中，于 Gitea 仓库 `/docs/adr/` 目录下提交 `001-scaffolding-guardrails-decisions.md`，必须固化以下三点技术选型理由：

1. 为何选择 AST 级 `src/` 扫描而非依赖树剥离来防御 Pandas。

2. 为何将魔法数字黑名单外置为配置文件。

3. 配置中心剥离敏感字段的序列化设计对 MLflow 追踪的复用价值。

---

## 五、 Sprint 1 交付物全景清单（已对齐）

以下为本次会议最终锁定需新增的文件及核心约束简述（供 Redmine 录入与 PR 检查点对齐）：

| 分类 | 文件路径 | 核心约束简述 |

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

| **工程配置** | `pyproject.toml` | 声明核心依赖，**禁显式 pandas**，PyPI 源指向清华源。 |

| **工程配置** | `.pre-commit-config.yaml` | 引入 ruff 与本地 AST 拦截钩子。 |

| **工程配置** | `.gitea/workflows/ci.yml` | PR 触发，包含 AST Lint、src/docs 变更一致性软预警检查。 |

| **工程配置** | `Dockerfile` | 基于 Ubuntu 24，镜像源走 `private-docker-repo:20706`，非 root 用户运行。 |

| **业务参数** | `config/config.yaml` | 与规约 7.2 节 100% 吻合，零魔法数字。 |

| **规约拦截** | `scripts/lint_ast.py` | 扫描 `src/`，拦截 pandas 与 `.magic_numbers.blacklist` 中的数字。 |

| **规约拦截** | `.magic_numbers.blacklist` | 独立维护规约锁定数值（如 150, 0.20 等）。 |

| **核心源码** | `src/utils/config.py` | Pydantic 强类型单例，支持环境变量覆盖，实现 `dump_for_mlflow()` 自动脱敏。 |

| **核心源码** | `src/utils/logging.py` | JSON Handler，强制注入 `step`, `module` 等标准字段。 |

| **核心源码** | `src/utils/hash.py` | 流式读取计算 SHA-256，防 OOM。 |

| **质量保障** | `tests/test_config.py` | 覆盖环境变量覆盖与脱敏序列化逻辑。 |

| **质量保障** | `tests/test_hash.py` | 覆盖临时大文件流式计算正确性。 |

| **技术真相** | `docs/architecture_baseline.md` | 落地架构基线全文。 |

| **技术真相** | `docs/adr/001-scaffolding-guardrails-decisions.md` | 记录本次会议核心工程选型。 |

| **目录占位** | `data/*/.gitkeep` 等 | 保证空目录结构受 Git 版本控制。 |

---

**会议闭环状态**：✅ 全部议程结束，无遗留阻塞项。研发团队可依据本纪要启动 Sprint 1 实施。