基金量化定投选基系统

### 一、 Step 1 敏捷 Story 拆分与双轨制映射

| Story ID | Story 描述 | 规约硬性映射 (Redmine自定义字段) | 验收标准 |

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

| **S1-01** | **工程根目录与 Poetry 依赖隔离**<br>建立标准项目目录树，配置 Poetry 2.3.3 与 Python 3.12 运行时，配置阿里云镜像加速。 | 规约 7.1 节目录结构；章程 OB-7 (禁Pandas) | 1. 目录树与规约 7.1 完全一致（含 `.gitkeep`）；<br>2. `pyproject.toml` 声明核心依赖，**严禁显式声明 pandas**；<br>3. `poetry install` 在本地与 Docker 均可无报错闭环。 |

| **S1-02** | **核心业务参数中心与环境隔离**<br>沉淀规约参数至 YAML，实现基于 Pydantic 的强类型加载与环境变量覆盖。 | 规约 7.2 节；规约 7.4 节（消除魔法数字） | 1. `config.yaml` 参数与规约 7.2 节 100% 吻合；<br>2. `config.py` 返回强类型单例，所有参数具备 Type Hints；<br>3. 验证环境变量覆盖生效（单测覆盖）。 |

| **S1-03** | **数据血缘与结构化日志基建**<br>实现流式 SHA-256 计算工具与带上下文注入的结构化日志。 | 规约 7.3 节（数据血缘）；FW-5 | 1. `hash.py` 采用流式读取计算 Hash，防 OOM；<br>2. `logging.py` 输出含 `time, level, module, step` 的 JSON 格式日志。 |

| **S1-04** | **CI 空跑红线与 AST 拦截机制**<br>配置 Gitea Action Runner 流水线框架，编写 AST 级 Pre-commit 钩子拦截规约违反。 | 章程 G-2 (CI强阻断率=0)；架构基线 2 & 3 | 1. 提交空代码至 `main` 分支被拒，必须走 PR；<br>2. PR 触发 CI 空跑（`pytest --collect-only`）并成功；<br>3. 本地 `git commit` 触发 pre-commit，若写入 `import pandas` 或 `150` 等魔法数字直接失败。 |

| **S1-05** | **双轨制技术真相源初始化**<br>将架构基线转化为 Gitea 仓库 `/docs` 下的 Markdown 文件。 | 架构基线 3（双轨制协作体系） | 1. `docs/architecture_baseline.md` 内容与规约一致；<br>2. 防止后续修改 `src/` 触发 CI 软预警。 |

---

### 二、 一周内需同步推进的管理侧工作（防遗漏）

除了代码 Story，作为 PM 提醒您本周必须落实以下管理动作，否则 M1 里程碑无法关闭：

1. **Redmine 权限配置**：将上述 Story 录入 Redmine 后，请运维配合配置 Gitea 的 Branch Protection（保护 `main` 分支，勾选 PR 检查项）。

2. **Gitea Action Runner 挂载**：确保 64GB 实体机上已注册并运行 Gitea Action Runner，且为其分配的 Docker 执行环境配置了 `memory=50g` 的 cgroup 限制（对应章程风险 R-1 防御）。

---

### 三、 涉及的新增/修改文件清单与简介

| 操作 | 文件路径 | 简介与企业级约束说明 |

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

| **新增** | `pyproject.toml` | 基于 Poetry 2.3.3 格式。声明 `polars`, `duckdb`, `lightgbm`, `optuna`, `mlflow`, `pydantic-settings`。**注意：不可出现 pandas 依赖**。 |

| **新增** | `poetry.lock` | 由 Poetry 自动生成，锁定全量依赖树版本，保证跨环境绝对一致。 |

| **新增** | `config/config.yaml` | **唯一业务真相源**。层级严格遵循规约 7.2 节（label, filter, feature, standardization 等），禁止包含任何运行时动态产生的参数。 |

| **新增** | `src/utils/config.py` | 基于 `pydantic-settings` 的配置单例。实现 `Settings` 类，支持 `os.environ` 覆盖 YAML 值（如 `model.optuna_timeout_hours`）。对外暴露 `settings = Settings()` 实例。 |

| **新增** | `src/utils/logging.py` | 日志门面。使用 Python 标准 `logging` 配置 JSON Handler，注入 `step` 占位符，为后续 DuckDB/Polars 审计提供标准化输出。 |

| **新增** | `src/utils/hash.py` | 数据血缘引擎。提供 `calculate_file_hash(path: Path, chunk_size: int = 8192) -> str`，严格采用流式读取，防止 920MB 原始文件撑爆内存。 |

| **新增** | `scripts/lint_ast.py` | **规约级自定义 AST 拦截器**。使用 Python `ast` 模块扫描源码，硬拦截：① `import pandas` 语句；② 赋值语句中存在规约锁定数值（如 `150`, `0.20`, `0.90` 等），允许 `0, 1, -1`。 |

| **新增** | `.pre-commit-config.yaml` | Pre-commit 配置。引入 `ruff`（基础格式）与本地钩子 `scripts/lint_ast.py`（规约红线），作用于 `git commit` 阶段。 |

| **新增** | `.gitea/workflows/ci.yml` | Gitea Action 流水线。触发条件：PR 至 `main`。步骤：① 配置阿里云镜像源；② Poetry 安装依赖；③ 执行 Lint 检查；④ 执行 `pytest --collect-only`（当前仅收集不执行）。 |

| **新增** | `Dockerfile` | Ubuntu 24 基础镜像。配置阿里云 Ubuntu/Python apt 源与 pip 源。安装 Poetry 2.3.3，创建非 root 用户运行，防权限污染。 |

| **新增** | `docs/architecture_baseline.md` | 落地《系统架构与工程规范基线》全文，作为技术文档的根节点。 |

| **新增** | `.gitignore` | 保护原始数据(`data/raw/`)、大文件(`*.parquet`)、模型产物(`mlruns/`)、本地环境(`.venv/`)不误提交。 |

| **新增** | `src/__init__.py` 等 | 各级包初始化文件，保持 Python 包导入合法。 |

| **新增** | 各空目录下的 `.gitkeep` | 确保 `data/processed/`、`data/features/` 等空目录能被 Git 追踪并提交。 |