3.8 KiB
3.8 KiB
id, title, phase, deps, status, created
| id | title | phase | deps | status | created |
|---|---|---|---|---|---|
| T-551 | 脚本从 docs/tasks/ frontmatter 生成任务看板 | 8 | DONE | 2026-07-08 |
问题 / 背景
采用"一任务一文件 docs/tasks/T-<编号>.md"后（见 docs/tasks/README.md），docs/current-state.md 已改为"不逐任务手动覆盖"，当前状态以各任务文件的 frontmatter 为准。但目前还没有一个汇总视图——要看"有哪些任务、各自 status/phase/依赖、下一个可领取的是哪个"，得手动 ls + 逐个翻文件。
需要一个脚本把 docs/tasks/ 的 frontmatter 汇总成只读的看板视图，agent/人都从生成结果查询，不手改 → 不引入新的共享写入抢占点。
说明：若后续改用 Gitea/GitHub Issues 管任务（见相关讨论），本脚本的数据源改为 issue API，但"生成只读看板、不手改"的目标不变；本任务先服务当前
docs/tasks/方案。
方案
新增脚本（如 scripts/gen_task_board.py）：
- 扫描
docs/tasks/T-*.md（排除_template.md和README.md），解析每个文件的 YAML frontmatter（id/title/phase/deps/status/created）。 - 用极简手写解析读取这段简单 frontmatter（不新增 PyYAML 依赖）；字段缺失/格式错要跳过并提示，不崩。
- 生成一张看板表写入专用生成文件
docs/tasks-board.md（文件顶部标注"本文件由脚本生成，请勿手改"）：按phase分组，列出id / title / deps / status；可附一段汇总（各 status 计数、"下一个可领取"=status=TODO 且 deps 全 DONE 的最靠前 id）。 - 只读输出，agent 不手改；需要刷新时重跑脚本。
- 归档
docs/06-tasks.md（T-000~T-549）不纳入生成范围，保持冻结。
验收要点
- 跑
python scripts/gen_task_board.py生成/更新docs/tasks-board.md，内容与docs/tasks/现有任务文件一致（含 T-550/T-551）。 - frontmatter 缺字段/格式异常的文件不导致脚本崩溃，只跳过并提示。
- 生成文件顶部有"勿手改、由脚本生成"标注。
- 不依赖第三方库（用标准库 + 手写 frontmatter 解析）。
tests/加脚本单测：给一个临时tasks/目录，断言生成的看板包含各任务的 id/status、"下一个可领取"计算正确。
边界（不改什么）
只加生成脚本 + 生成的 docs/tasks-board.md + 脚本单测；不改任务文件内容、不改 06-tasks.md 归档、不改业务代码、DB、CDP/Shopee。
执行记录
- 2026-07-08：完成 T-551。
- 代码：新增
scripts/gen_task_board.py，用标准库扫描docs/tasks/T-*.md，手写解析 frontmatter；字段缺失、格式错误、非法 status/phase/deps 的任务文件会跳过并通过 stderr 提示，不让脚本崩溃；按 phase 分组输出id / title / deps / status，并计算状态统计和“下一个可领取”。 - 文档产物：运行
python scripts/gen_task_board.py生成docs/tasks-board.md，文件顶部标注由脚本生成、请勿手改；数据源仅包含docs/tasks/T-*.md，不纳入冻结归档docs/06-tasks.md。 - 测试：新增
tests/test_task_board.py，用临时任务目录覆盖正常任务、依赖已完成的下一个可领取任务、依赖未完成任务、进行中任务，以及缺字段 frontmatter 被跳过。 - 验证：
py -3.10 -m unittest discover -s tests -p "test_task_board.py"通过（1 test）；python scripts/gen_task_board.py通过并生成 2 个任务；python -m ruff check app tests main.py通过；python -m ruff check scripts\gen_task_board.py tests\test_task_board.py通过；py -3.10 -m compileall app main.py通过；py -3.10 -m py_compile scripts/gen_task_board.py通过；git diff --check通过；py -3.10 -m unittest discover -s tests通过（254 tests）。