项目

一般

简介

行为
历史记录

Wiki » 0003-执行阶段 » 0001-Sprint1 » 0001-Sprint1规划会议 »

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

会议日期：2026-04-13
项目名称：基金量化定投选基系统 (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 实施。

由 Huarui Lin 更新于 4 天 之前 · 3 修订