项目

一般

简介

行为
历史记录

Wiki » 0002-规划阶段 »

0001-工程脚手架 » 历史记录 » 修订 2

« 上一页 | 修订 2/5 (差异) | 下一页 »
Huarui Lin, 2026-04-12 18:02

一、 Step 1 敏捷 Story 拆分与双轨制映射（Redmine 可直接录入）

Story ID Story 描述 规约硬性映射 (Redmine自定义字段) 验收标准
S1-01 工程根目录与 Poetry 依赖隔离
建立标准项目目录树，配置 Poetry 2.3.3 与 Python 3.12 运行时，配置阿里云镜像加速。		 规约 7.1 节目录结构；章程 OB-7 (禁Pandas) 1. 目录树与规约 7.1 完全一致（含 .gitkeep）；
2. pyproject.toml 声明核心依赖，严禁显式声明 pandas；
3. poetry install 在本地与 Docker 均可无报错闭环。
S1-02 核心业务参数中心与环境隔离
沉淀规约参数至 YAML，实现基于 Pydantic 的强类型加载与环境变量覆盖。		 规约 7.2 节；规约 7.4 节（消除魔法数字） 1. config.yaml 参数与规约 7.2 节 100% 吻合；
2. config.py 返回强类型单例，所有参数具备 Type Hints；
3. 验证环境变量覆盖生效（单测覆盖）。
S1-03 数据血缘与结构化日志基建
实现流式 SHA-256 计算工具与带上下文注入的结构化日志。		 规约 7.3 节（数据血缘）；FW-5 1. hash.py 采用流式读取计算 Hash，防 OOM；
2. logging.py 输出含 time, level, module, step 的 JSON 格式日志。
S1-04 CI 空跑红线与 AST 拦截机制
配置 Gitea Action Runner 流水线框架，编写 AST 级 Pre-commit 钩子拦截规约违反。		 章程 G-2 (CI强阻断率=0)；架构基线 2 & 3 1. 提交空代码至 main 分支被拒，必须走 PR；
2. PR 触发 CI 空跑（pytest --collect-only）并成功；
3. 本地 git commit 触发 pre-commit，若写入 import pandas 或 150 等魔法数字直接失败。
S1-05 双轨制技术真相源初始化
将架构基线转化为 Gitea 仓库 /docs 下的 Markdown 文件。		 架构基线 3（双轨制协作体系） 1. docs/architecture_baseline.md 内容与规约一致；
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 追踪并提交。

由 Huarui Lin 更新于 5 天 之前 · 2 修订