跳转至

📋 PR 自查清单 v1.1

使用方式

提交任何文档或代码 PR 前，复制本清单到 PR 描述里逐项打勾。 至少 8 项通过才允许合并，否则 reviewer 有权打回。 v1.1 新增：§11 文档-代码同步速查卡（配合《文档-代码同步规范 v1.0》使用）。

v1.1 更新说明（2026-05-06）

  • 新增 §11 文档-代码同步速查卡（代码 PR 必看）
  • 新增 §12 ADR 触发检查（对齐《ADR 模板》）
  • PR 描述模板新增"D4 同步文档清单"字段
  • Reviewer 打回规则新增"代码改动未同步 D4 文档"项

✅ 必做 10 项

1. Frontmatter 完整

  • title / description / level / category / status / author / date 七个字段都有
  • level 小写（l1a / l1b / l2 / l3），不能写 L1A
  • date 是最近一次实质更新日期（不是创建日期）

2. 文档分级正确

  • level 与内容厚度匹配（参考 md-writing-spec.md §3）
  • 不滥用 L1A（站点首页才用）
  • L1B 限主题级重磅文档（产品矩阵、白皮书、规范类）

3. 标题规范

  • H1 全文唯一（或由 frontmatter.title 替代）
  • 标题不跳级（## → #### 违规）
  • H2/H3 带编号（## 1. XXX / ### 1.1 XXX）
  • 标题内不含 emoji（Hero label 和 admonition 可用）

4. 表格合规

  • 所有表格不含 <br> / <img> / <span> 等 HTML
  • 对齐标记统一（|:---|:---:|---:|）
  • 表头一句话概括

5. 代码块合规

  • 所有代码块带语言标签（```c / ```python 等）
  • 行号/高亮用 linenums="1" / hl_lines="2 4" 语法
  • 不在代码块内嵌入 HTML

6. 图片规范

  • 所有图片是 Mermaid 或 ./images/ 本地文件
  • alt 文字必填
  • 文件名格式 产品名-场景-版本.png（小写 + 连字符）
  • 图片路径相对化（./images/xxx.png）

7. Mermaid 规范

  • 不使用 ASCII 框图（╔═╗ ┌─┐）
  • 不把架构图做成截图后贴 png
  • 节点 class 只用 xyL0~xyL5 或 xySuccess/xyWarn/xyError/xyEnd
  • 不手写 fill:#xxx / stroke:#xxx hex 值
  • 整图不同时出现 3 个以上强饱和层级色

8. 产品命名

  • 产品名拼写符合 md-writing-spec.md §11（XiStudio / XiDSP / XiAlgo-FX 等）
  • 第一次出现时标注中文：XiStudio（羲音工坊）
  • 型号写法：XiDSP-D2 / XiAmp Pro-12

9. 链接与路径

  • 内部链接用相对路径（../00-vision/product-matrix.md）
  • 不引用 AlgoDepartment/... 等绝对路径
  • 外部链接用完整 URL（https://...）
  • 死链接（404）数为 0（可用 mkdocs build 检查）

10. 色彩合规（v1.1 新增）

  • MD 正文不含手写 <span style="color"> / <font color> 等内联色
  • Mermaid 节点不手写 fill:# / stroke:#
  • Admonition 不强改颜色（统一极光青）
  • 若有 CSS 自定义，仅引用 brand-color-system.md 的 CSS 变量

11. 🔄 文档-代码同步速查卡（v1.1 新增 · 代码 PR 必看）

强制规则（对齐《文档-代码同步规范》§3.6）

改代码必须同步改对应 D4 实现级文档，否则 CI job docs-sync-check 将阻断合并。

11.1 代码 → 文档映射速查表

改了什么代码 必须同步哪份文档
04_development/backend_csharp/Controllers/*.cs D4-implementation/backend-csharp/controllers/*.md
04_development/backend_csharp/Services/*.cs D4-implementation/backend-csharp/services/*.md
04_development/frontend_vue3/src/components/*.vue D4-implementation/frontend-vue3/components/*.md
04_development/frontend_vue3/src/stores/*.ts D4-implementation/frontend-vue3/stores/*.md
04_development/dsp_algo/**/*.c D4-implementation/dsp-algo/**/*.md
04_development/pysidecar/**/*.py D4-implementation/pysidecar/**/*.md
03_algorithms/**/*.{m,py,c} D4-implementation/algorithms/**/*.md
07_web/xisound-website/src/**/*.astro D4-implementation/web-astro/**/*.md
公开 API 签名（任何栈） 上述 D4 路径 + D2-products/Pxx-xxx/api.md
配置文件 schema（appsettings.json / vite.config 等） D4-implementation/<stack>/config.md
依赖版本（*.csproj / package.json 等） D4-implementation/<stack>/dependencies.md

11.2 豁免清单（不强制同步）

以下情况 可以不改文档（但仍建议补 PR 描述说明）：

  • 仅修 typo / 注释 / 格式化
  • 仅改测试文件（**/*.spec.* / **/tests/**）
  • 纯依赖锁文件（package-lock.json / *.csproj.lock.json）
  • 纯 refactor（不改接口 · 不改行为）

11.3 豁免申请流程

若确认修改在豁免清单外但确实不需要改文档：

  1. PR 描述加 [skip-docs-sync] 标签
  2. 需要 Tech Lead + Doc Engineer 双 approve
  3. 事后在 ADR 记录该特例

11.4 代码 PR 自查清单

提交代码 PR 前勾选：

  • 改动的代码路径已按 §11.1 表格找到对应 D4 文档
  • 已同步更新 D4 文档（frontmatter date 更新为今天）
  • D4 文档的 version 已递增（小改 patch / 大改 minor）
  • 若涉及架构变更 → 已开 ADR（见 §12）
  • 若涉及对外 API → 已同步 D2-products/Pxx-xxx/api.md
  • 若改依赖 → 已更新 dependencies.md
  • 本地跑 mkdocs build 无 WARNING

12. 🏛️ ADR 触发检查（v1.1 新增）

何时必须开 ADR

根据《ADR 模板》§1.1，以下情形必须写 ADR：

  • 代码偏离 D3 架构设计
  • 技术栈首次选型（新语言 / 新框架）
  • 协议 / 数据模型重大变更
  • 依赖升级有破坏性影响（major 版本跳跃）
  • 废弃某功能或模块
  • 安全 / 合规决策
  • 性能 / 成本关键权衡

12.1 ADR 提交流程

  1. 复制 D3-execution/adr-tmpl.md §2 的模板
  2. 命名为 adr-<4位数字>-<kebab-case-标题>.md
  3. 初始状态 proposed
  4. 异步评审 ≥ 3 天 · Tech Lead / Architect approve 后改 accepted
  5. ADR 和本 PR 关联链接（双向）

12.2 ADR 自查清单

  • ADR 文件命名规范 adr-NNNN-kebab-title.md
  • §1-§6 六大必填章节完整
  • §2 至少列 2 个备选方案
  • §3 决策有 3-5 条理由
  • §4.3 文档联动表填写
  • §4.4 代码落地范围明确

🧪 构建验证

在本地跑一次构建 + 抽检：

# 1. 构建站点
python -m mkdocs build --clean -f AlgoDepartment/06_docs/site-build/mkdocs.yml

# 2. 预期无 error、无黄色 warning
#    INFO -  Documentation built in X.XX seconds

如有黄色 warning（not_found / omitted_files 等），要么修复，要么在 PR 描述里说明原因。

📝 PR 描述模板（v1.1 升级）

## 变更摘要
- [ ] 新增文档：路径 + 一句话说明
- [ ] 修改文档：路径 + 改动要点
- [ ] 删除文档：路径 + 删除原因
- [ ] 修改代码：路径 + 改动要点（代码 PR 必填）

## 10 项自查清单
（复制上面的 10 项清单，逐项打勾）

## 文档-代码同步（v1.1 新增 · 代码 PR 必填）
- [ ] 已按 §11.1 映射表找到对应 D4 文档
- [ ] D4 文档已同步更新：<文档路径>
- [ ] 若豁免，申请标签：[skip-docs-sync]（需双 approve）

## ADR 触发（v1.1 新增 · 如适用）
- [ ] 本 PR 涉及 §12 中任一触发场景 → 已开 ADR-XXXX：<ADR 链接>
- [ ] 本 PR 不涉及架构决策

## 截图 / Mermaid 示例
（如有视觉变更，附本地构建后的截图）

## 影响范围
- [ ] 仅文档内容（不影响主题）
- [ ] 涉及 CSS/JS 主题（需要更多 reviewer）
- [ ] 影响跨部门（请通知受影响部门）
- [ ] 代码 + 文档同步（CI 会校验 · 见 §11）

🚨 Reviewer 打回规则（v1.1 扩充）

Reviewer 在以下情况必须打回 PR：

  1. 有任何违反 md-writing-spec.md 强制约束的项
  2. 10 项自查清单少于 8 项通过
  3. MD 正文含手写 hex / 内联 style
  4. 产品命名拼错
  5. ASCII 框图 / 截图架构图
  6. 代码改动未同步对应 D4 文档（v1.1 新增 · CI 强制）
  7. 架构变更未开 ADR（v1.1 新增）
  8. 公开 API 签名改动未同步 D2 产品 api.md（v1.1 新增）

💡 Tip · 高频易错点

这些最常被打回

  1. level: L1A （应该是 l1a 小写）
  2. hero_show 忘写（Hero 不渲染）
  3. 表格单元内用 <br> 强制换行
  4. Mermaid 图手写 classDef fill:#xxx
  5. 内部链接用 /AlgoDepartment/... 绝对路径

附录 · 相关文档

版本历史

版本 日期 变更
v1.0 2026-05-05 首次发布 · 10 项文档自查 + 构建验证 + PR 模板
v1.1 2026-05-06 新增 §11 文档-代码同步速查卡 + §12 ADR 触发检查 · 扩充 reviewer 打回规则到 8 项 · PR 模板对齐同步规范

checklist.md · v1.1 · 2026-05-06 · Xisound AlgoDepartment