跳转至

每版本沉淀检查表

触发场景：每次 pnpm build 通过、准备 git commit 前，按本清单逐项自查。 起因：v0.10.97~v0.10.106 这 10 个版本中有 4 个真 bug 修复（v0.10.101 / v0.10.103 #1-#4）漏建 ISSUE，只在 commit message + 开发日志记录，导致历史回溯困难、audit_grep 防退化机制缺失。 目标：让"沉淀"从"应该做"变成"必做"。

决策树（每版本完成时跑一遍）

本版改动是什么类型？
├─ 修 bug（包括 UX 误导 / 命名混淆 / 数据正确性）
│   ├─ 用户可见？ ──> ✅ 必建 ISSUE-XXXX（含病灶/修/元教训 + audit_grep）
│   ├─ code review / agent 找到？ ──> ✅ 必建 ISSUE-XXXX
│   ├─ 历史回归（命中旧坑）? ──> ✅ 必建 + related 链回原始 ISSUE/注释
│   └─ 内部隐含 bug（没人能察觉）? ──> ⚠️ 建议建（防再犯）
│
├─ 新功能 / 大重构
│   ├─ ≥ SPEC 级（数据模型/API/UI 流程）? ──> ✅ SPEC active → 实施 → 移 done/
│   ├─ 涉及架构概念？ ──> ✅ 同步更新 wiki/
│   └─ 仅是 settings / UI 字段？ ──> 可省（但应更新 wiki/settings-field-semantics.md）
│
├─ 优化（性能 / 体验 / DX）
│   ├─ 修代码风格 / refactor? ──> 可省
│   ├─ 引入新 helper / 模式? ──> ✅ 建议更新 wiki 或 rules
│   └─ 加 audit_grep / scan?  ──> ✅ 写到 ISSUE / rule 的 audit_grep 字段
│
├─ 元改进（文档治理 / CI / 脚本）
│   └─ ──> 可省（开发日志 + commit 够）
│
└─ Settings UI 调整
    └─ ──> ✅ 必更新 wiki/settings-field-semantics.md

各类型必做项详表

修 bug 必做项

项 必/选 文件 / 位置
ISSUE-XXXX.md 含 frontmatter 必 docs/issues/
frontmatter fixed_version 必 yaml 字段
frontmatter related 反向链 必 关联 SPEC / 早期 ISSUE / wiki
病灶 段（症状 + 根因） 必 body
修 段（diff 或前后对比） 必 body
元教训 段（下次怎么不犯） 必 body
audit_grep 字段 强烈建议 yaml — 防退化扫描
development-log.md 追加条目 必 repo 根
CHANGELOG 自动重生（pnpm docs:changelog） 必 自动

新功能 SPEC 必做项

项 必/选 文件
SPEC 文档（含 §1-§8） 必 docs/specs/active/ → done/
frontmatter target_version 必 yaml
frontmatter approved_decisions 必 拍板的关键决策记录
wiki 更新（架构 / 字段语义 / 数据模型） 必 docs/wiki/
开发日志详细说明 必 repo 根
Settings UI 用户提示 视情况 helperText

Settings UI 改动必做项

项 必
docs/wiki/settings-field-semantics.md 更新 ✅
docs/rules/settings-change-pre-check.md 跑一遍 ✅
默认值兼容老用户行为 ✅

UI 列 / 表格渲染改动必做项（v0.10.115 ISSUE-0075 沉淀）

项 必
列数据源是 row 字段 OR 跨维度（URL Map / 聚合）？跨维度时列名/tooltip 明示了吗？ ✅
同一行各列对比：会不会出现视觉矛盾（"状态=X + HTTP=反 X"）？ ✅
去重视图按 group key 取代表 — 用 score 选还是"取第一个"？ ✅
跑过 ui-change-pre-check.md 4 步自查？ ✅
参考 ui-column-dimension-consistency + group-by-best-representative ✅

反例（本会话漏建的）

补建在 v0.10.107：

版本 应建 实际 后果
v0.10.101 ISSUE-0070（孤儿窗口） 只在开发日志 用户反复报同款问题风险，无 audit_grep 防退化
v0.10.103 #1 ISSUE-0071（where:taskId 回归） 只在开发日志 极易再犯（v0.10.2 ISSUE-0008 → v0.10.102 重蹈）
v0.10.103 #2 ISSUE-0072（cleanupOrphan 误杀） 只在开发日志 严重 UX bug 无独立溯源
v0.10.103 #3+#4 ISSUE-0073（导出隐私） 只在开发日志 隐私问题无单点关注

自查 1 分钟流程

build 通过 → 准备 commit → 1 分钟自查：

1. 看 git diff src/：改了什么？
   - 修 bug → 是否有 ISSUE-XXXX？没就建
   - 新 SPEC → done/ 移了吗？wiki 更新了吗？
   - settings 改 → wiki/settings-field-semantics.md 改了吗？

2. 看开发日志：本版条目写了吗？包含：
   - 本次改动（diff 摘要）
   - 元教训（下次怎么不犯）
   - 注意点

3. 跑 pnpm docs:check + pnpm docs:changelog
   - 0 broken link
   - CHANGELOG 自动新增本版

4. commit message 含 ISSUE-XXXX 或 SPEC-XXX 关键词
   （pre-commit hook 会强制 — 见 docs/rules/pre-commit-hook配置.md）

工具支持

  • pnpm docs:check — link 检查 + frontmatter 必填字段校验
  • pnpm docs:rebuild — 自动重建 INDEX / _todo / _topics
  • pnpm docs:changelog — 自动生成 CHANGELOG
  • scan:issue-coverage — 防漏修姊妹文件（audit_grep 扫描）
  • pre-commit hook — 强制 commit 含 ISSUE/SPEC 关键词（v0.10.107 起）

相关