47 lines
3.8 KiB
Markdown
47 lines
3.8 KiB
Markdown
---
|
||
id: T-551
|
||
title: 脚本从 docs/tasks/ frontmatter 生成任务看板
|
||
phase: 8
|
||
deps: []
|
||
status: DONE
|
||
created: 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）。
|