05-测试-时点快照报告不整体重生成与增量升版法

一、适用场景

测评/评估类报告（评分报告、整改方案、复测报告、目录结构报告）在某个时点产出后，
后续又发生了新闭环，需要让文档反映新状态，但文档里的原始数据是当时实测得来的。

触发条件举例：
- 某维度扣分主因已被解除，要不要把报告改一遍？
- 整改方案里写「待授权/未实施」，实际已实施，要不要同步？
- 系统改名/口径调整后，历史报告里的旧称呼要不要改？

核心判据：历史报告是「时点快照」，不是「内容失效」——它记录的是当时测出来的事实，
后续变化应当用「升版 + 增量改写」承接，而不是重跑一遍把它覆盖掉。

二、操作步骤

1. 先给文档定性：看文件名是否带时点（如 _v1.2_20261013）、内容是否为「某日实测」。
   是 → 归为时点快照，走本流程；不是（如操作手册、安装手册这类活文档）→ 直接全文修订。
   锚点：系统操作手册/05 测试/HFMS满分提升整改方案_v1.2_20261013.docx。
2. 列「影响范围清单」再动手：逐条点名被本次结论影响的对象（哪几节、哪几张表、哪几个单元格、
   哪几张图），并显式写明「不改动」的部分。
   锚点：2026-10-13.md L159（改动清单精确到 overview 表/detail 表项4项5/roadmap 阶段2-3/首段与一、二、四、五节）。
3. 改生成器，不改产物：报告由脚本生成的，一律改生成器叙事后重出，
   禁止拿 python-docx 直接把落地的 docx 打开乱改——否则下次重跑生成器又回退。
   锚点：.workbuddy/gen_remediation_plan.py、.workbuddy/gen_qa_report.py。
4. 数值一律读复算实值，禁止沿用/硬编码：评分类数字改从实值来源读取，
   不得把上一版的数字抄进新版。锚点：.workbuddy/compile_scores_20261013.py——
   overview 表性能/稳定由硬编码 93.4 / 95.4 改为读 scorecard 实值（已=100，缺口=0）。
5. 段落级整行替换 + 文末升版说明：按 02-技术-docx图文手册纯标准库增量改写法 做段落级替换，
   并在文末加【报告升版 vX.X】说明本次改了什么、为什么改。
   锚点：2026-10-13.md L82（HFMS操作流畅度全维度复测报告 v1.3→v1.4：仅更新 ④ 相关四处，③ 与全部测评数据保持不变，文末加升版说明）。
6. 旧版归档，不删除：旧版移 系统操作手册/05 测试/_备份/ 保留，回溯链不能断。
   锚点：2026-10-10.md L97（v1.0 已移 05 测试/_备份/ 保留）。
7. 状态同步必须先拿到用户点头：把「旧状态已被新闭环覆盖」这一判断先向用户标明，
   由用户决定是否同步；用户说「同步」才算授权。
   锚点：2026-10-13.md L153（遗留·已向用户标明未处理）→ L156-158（用户「同步其状态」＝批准）→ L159-161 才动手。
8. 升版后跑一次体检器：见 scripts/report_version_check.py（PASS 才收工）。

三、注意边界

• 改动半径只限被点名对象：本次只改结论相关的段/表，其余数据一律不动，包括已经「不好看」的旧数据。
• 「不整体重生成」≠「永远不改」：活文档（手册、SOP、安装说明）该全改还得全改，本纪律只管时点快照。
• 报告里的原始测评数据不可回填修改，即使是瞬时尖峰——已在别处说明偏差即可，不要回头改表。
• 升版说明里要写清「本次上调/下调的依据」，能追溯到具体事件与日期。
• 全程零产品代码改动：升版动的是叙述与状态，不是被测对象本身。

四、反例避雷

• ✗ 整体重生成：把 v1.2 拿新数据重跑一遍 → 当时实测的原始分布全部丢失，时点快照意义尽毁。
  本例 2026-10-08 L27/L136 明确按「历史报告为时点快照、非内容失效、不整体重生成」处理，
  连 tools/ 下含旧称呼的历史 .html 快照都原样保留。
• ✗ 数值沿用旧值：硬编码 93.4 / 95.4 不改 → 报告正文与 scorecard 打架，读者不知道信哪个。
  解法：改读复算实值（compile_scores_20261013.py）。
• ✗ 未获批准就同步状态：把「待授权/未实施」自行改成「已完成」→ 越权替用户做决定。
  正解：先标明、等指令（2026-10-13 §十四⑥ → §十五）。
• ✗ 删旧版：直接删除旧文件 → 无法回溯当时口径。正解：移 _备份/。
• ✗ 改落地 docx 而不改生成器：下次重跑生成器，改动被静默冲掉（曾反复踩）。
• ✗ 无影响范围清单就动手：改完说不清改了什么、没改什么，复核成本陡增。

五、代码锚点 / 实战战绩

锚点：
- .workbuddy/gen_remediation_plan.py（整改方案生成器：overview/detail/roadmap 三处叙事）
- .workbuddy/compile_scores_20261013.py（复算实值，供报告读取）
- .workbuddy/gen_qa_report.py（评分报告生成器）
- 系统操作手册/05 测试/_备份/（旧版归档区）
- 日志：2026-10-08.md L27、L136｜2026-10-13.md L153、L156-L161、L82｜2026-10-15.md L184-L187

战绩：
- 2026-10-13 一次会话内连做两次升版：整改方案 v1.2→v1.3（用户批准后同步状态）、
流畅度复测报告 v1.3→v1.4（仅改 ④ 相关四处，其余数据零改动）——两次均按本流程，无返工。
- 2026-10-08 #13 手册存档：明确「其余各阶段历史报告为时点快照，非内容失效，不整体重生成，仅对受影响文档升版+存档」。
- 2026-10-15 PC 服务端改名同步：只改受影响手册，软件目录结构报告_v1.1（时点报告）按纪律原样保留。
- 本批体检器实测：正例（10-13 真实升版说明）PASS；构造反例（全文重生成 + 沿用数值 + 删旧版 + 无授权）FAIL×5。

六、关联笔记

• 02-技术-docx图文手册纯标准库增量改写法：技术层的段落级改写手法，本技能是治理层的改不改/改哪些/谁批准。
• 06-成品-制度体系版本升版SOP：升的是制度文档版本（不改文件名），与之互补。
• 00-总纲-版本纪律规则、00-总纲-前序结论证伪与产物连锁订正法：结论被推翻时的连锁订正，常与本技能连用。
• 04-开发-技术路线方案图文制作流程SOP：从零出图文报告的管线（本技能管的是已有图文的升版）。

七、版本记录

• v1.0（2026-10-22）：首版。据 2026-10-08 / 10-13 / 10-15 三次实战定型；附只读体检器 scripts/report_version_check.py（正反例已实测）。