[ZhaoXingPeng]

关联 Issue

Closes #118

背景（Situation）

现有仓库只校验提交和 PR 标题，Issue 表单与 PR 正文缺少统一的可执行结构。历史条目里已经出现连续 ? 的 UTF-8 损坏，且阶段性 PR 回帖没有对结论、证据和未验证边界作一致约束，导致协作记录难以复查。

任务（Task）

建立中文优先、UTF-8 安全的 Issue / PR / 提交标题与正文规范，提供可直接使用的表单和模板，并让 CI 在 PR 上检查标题、提交标题和正文结构。规范必须要求回帖以已执行的命令、输入、结果和边界为依据，而不是以评论数量或推测代替证据。

行动（Action）

• 扩展 docs/engineering-standards.md：明确 Gitmoji 与类型映射、必填 scope、UTF-8 检查、Issue 字段、PR 固定章节、合并门禁和里程碑回帖模板。
• 补强 Bug 与功能 Issue 表单：要求模块、验收标准、非目标、风险与测试计划，并提醒不得提交凭据或编码损坏内容。
• 将 PR 模板收敛为 关联 Issue、Situation、Task、Action、Verification、Evidence、兼容性/风险/回滚七个固定章节。
• 扩展 scripts/validate_commit_title.py：除标题外，验证 PR 关联、全部必填章节和连续 ? 编码信号；CI 从 GitHub 事件 JSON 的 UTF-8 正文读取输入，避免 shell 转义改变内容。
• 为正文验证补充单元测试，并在文档中心增加工程规范入口。
• 没有做什么：不修改运行时代码、不重写已合并提交历史、不把既有全库格式化债务混入本 PR。

验证（Verification）

$env:PYTHONPATH='src'; python -m pytest tests/unit -q
660 passed in 6.86s

python -m ruff check src/ tests/ scripts/
All checks passed!

python -m ruff format --check scripts/validate_commit_title.py tests/unit/test_commit_metadata.py
2 files already formatted

python -c "import yaml, pathlib; ..."
YAML OK

git diff --check
通过

完整仓库的 ruff format --check src/ tests/ scripts/ 报告 64 个既有文件会被重排；本次修改的两个 Python 文件格式已通过，未为刷绿重排无关文件。

实验与证据（Evidence）

• 使用完整 PR 正文 fixture 验证 Closes #118 和七个固定章节会通过；缺失章节且包含连续问号的损坏输入会同时触发结构与 UTF-8 错误。对应测试：tests/unit/test_commit_metadata.py。
• 解析 Issue 表单和 CI workflow YAML，确认新增字段与 workflow 语法可加载。
• 本 PR 不涉及数据库、模板渲染或性能改动；没有性能实验，也不作性能提升结论。

兼容性、风险与回滚

• 公共 API / 数据格式 / 迁移：无运行时 API、数据格式或数据库迁移。新的 PR 正文结构会影响之后从此分支合入 main 的 PR；既有 PR 不会被追溯性拒绝。
• 风险与已知限制：自动检查只能识别标题、章节、关联和明显的连续问号，无法证明测试结果或性能结论本身真实；审查者仍需核对证据。全库仍有 64 个历史格式化差异。
• 回滚：还原提交 3c3fe9b 可撤销模板和 CI 门禁；历史 Issue/PR 的元数据修复可独立回滚编辑。
• 后续 Issue：历史乱码条目和主页旧文件提交标题在各自独立维护工作中处理。

[ZhaoXingPeng]

设计与门禁范围（2026-09-08）

当前结论

本 PR 将协作记录从“建议性模板”推进为可检查的契约：新 PR 必须关联 Issue、具有统一标题，并包含背景、任务、行动、验证、证据和风险回滚信息。它不试图让静态脚本判断测试结论是否真实，证据真实性仍由审查者核对。

变更与设计取舍

• 提交：3c3fe9b
• 将规范放在既有 docs/engineering-standards.md，而不是建立第二份平行治理文档，保持现有文档入口不分叉。
• CI 使用 GITHUB_EVENT_PATH 的 JSON 读取 PR 正文，而不是把多行中文正文放进 shell 参数；这一选择避开了 shell 转义和编码转换带来的再次损坏风险。
• validate_pr_body 只检查 Closes / Refs、七个固定章节和连续 ?。它有意不检查测试数量、性能数字或评论篇数，因为这些都无法仅从 Markdown 结构证明。
• Bug 与功能表单分别要求复现和验收、方案/替代方案、架构兼容与测试计划；安全凭据继续禁止出现在公开内容。

验证与证据

• tests/unit/test_commit_metadata.py 新增完整 PR 正文通过用例，以及缺失章节与 连续问号的损坏输入 同时失败的回归用例。
• python -c "import yaml, pathlib; ..." 已加载两个 Issue 表单、表单配置和 CI workflow，结果为 YAML OK。
• 尚未运行数据库集成测试、Docker smoke test 或性能基准，因为本 PR 不改变运行时代码、数据库访问或模板行为。

兼容性与下一步

• 风险：新正文门禁会拒绝结构不完整的后续 PR；已合并历史不会被此 CI 追溯检查。
• 回滚：还原 3c3fe9b 即可撤销模板、文档和 CI 校验；没有数据迁移或运行时状态需要恢复。
• 下一步：完成本地全量验证后，单独编辑历史乱码 Issue/PR 元数据，不把历史文本修复混入这条分支。

[ZhaoXingPeng]

本地验证记录（2026-09-08）

当前结论

本地单元测试、静态检查、改动文件格式检查、YAML 解析和 diff 检查均已完成；新增正文规则已经被可执行测试覆盖。没有依据不足的性能或真实数据库结论。

变更与设计取舍

• 提交：3c3fe9b
• 测试基线从当前 main 的 658 项增至 660 项，新增的两项只覆盖 PR 元数据校验逻辑，没有修改业务测试预期。
• 全库格式检查发现历史格式化债务，未用大范围重排掩盖这条小型治理改动。

验证与证据

• $env:PYTHONPATH='src'; python -m pytest tests/unit -q：660 passed in 6.86s，环境为 Windows、Python 3.10.1、pytest 9.0.3。
• python -m ruff check src/ tests/ scripts/：All checks passed!。
• python -m ruff format --check scripts/validate_commit_title.py tests/unit/test_commit_metadata.py：2 files already formatted。
• git diff --check：通过。
• python scripts/validate_commit_title.py --title ':books: docs(governance): 固化协作内容与编码门禁'：通过。
• python -c "import yaml, pathlib; ..."：YAML OK。
• python -m ruff format --check src/ tests/ scripts/：报告 64 个既有文件会被重排；这些文件未在 3c3fe9b 的变更范围内，因此结果记录为现有质量债务，不标记为本 PR 已通过。

兼容性与下一步

• 已知限制：CI 的完整矩阵（3 个 Python 版本、Testcontainers、Docker、打包和模板渲染）须等待 GitHub Actions 执行；本地没有将其替代为“通过”声明。
• 审查重点：确认 PR 事件正文读取仅在 pull_request 分支执行，并确认固定章节名称与模板完全一致。
• 回滚：如门禁导致不可接受的工作流摩擦，可先还原 3c3fe9b，再在新 Issue 中调整规则与迁移策略。

[ZhaoXingPeng]

CI 收口与编码负向验证（2026-09-08）

当前结论

#119 的完整 GitHub Actions 矩阵已通过。首次元数据作业的失败不是实现或测试失败，而是 PR 正文中为解释负向测试而直接写入连续问号，规则按设计拒绝了该正文；把说明改为自然语言后，通过重写未合并提交重新触发 CI，第二次运行全绿。

变更与设计取舍

• 最终提交：3c3fe9b。
• 首次失败运行：34204471016，失败作业为 Commit and PR policy；日志明确显示唯一错误为 PR body contains consecutive '?' characters。
• 修复：PR 正文改为“包含连续问号的损坏输入”，不放入触发器本身；没有放宽检测规则，也没有删除编码负向测试。
• 重写同一未合并提交而非新增空提交，使新工作流事件读取已修正的 PR 正文；评论内提交引用同步更新。

验证与证据

• 第二次运行：34204939651，Commit and PR policy、Python 3.11/3.12/3.13 质量、changed-file format、Testcontainers integration、template rendering、Docker smoke、package build 和 Required CI status 全部为 SUCCESS。
• 新门禁因此实际验证了 PR 标题、分支提交标题、Closes #118、七个正文段落和没有连续问号的正文。
• 此 CI 运行的输入是当前 PR 内容；它没有把文档检查替代成性能或生产环境结论。

兼容性与下一步

• 这次失败是预期规则在真实 PR 数据上的有效负向样本，已保留为公开可审计记录。
• 已知限制不变：结构检查不能证明命令输出和性能结论真实，维护者评审仍需核对证据。
• PR 合并后，后续 PR 会从 main 继承该门禁；历史 PR 不会被追溯性执行新的 workflow。