cfc/docs/tdd/test/795-zero-execution-resolution.md

795 文档用例/场景「零执行」问题 · 求解报告

测试负责人（TDD 文档驱动执行基座）· 2026-11-07 配套：.tdd/config.json（修正列映射）、tests/doc-runner/run_doc_cases.py（执行基座）、 .tdd/test-progress.json（真实进度侧车）、docs/tdd/test/automation-status.md（共享台账）、 docs/tdd/test/doc-case-execution-report.md（本轮执行明细）

一、问题定性

此前闭环报告持续标记「795 文档用例/场景 100% 零执行 / 未跟踪」，目标②（覆盖全部 SRS+用户场景含异常流）因此不可判定。 经核查，该结论由两个真实缺陷叠加造成，并非 795 条用例真的都没测：

1. 台账列映射 off-by-one（测量失真）：.tdd/config.json 的 tc_columns.e2e 原设为 10， 但实际表格自新增「所属场景」列后，对应 e2e 列位于 index 11、关联需求/设计 位于 index 10。 工具据此把「控制器名」误读为「e2e 脚本路径」，导致 51+ 条已真实关联 Playwright 规格的用例被误判为「待自动化」； 且 need=max+1 宽度校验把 9/10 列文件的用例整行漏计。
2. 确无执行证据（真实缺口）：733 条结构化用例 + 11 个用户场景文件没有可推导的自动化端点， 侧车 test-progress.json 从未写过真实结果 → 台账「已执行」恒为 0。

二、已实施的修复

#	修复	文件	效果
1	tc_columns.e2e 10→11、ref_design 9→10	.tdd/config.json	51 条已关联 spec 被正确识别为「已关联自动化」
2	need = min(cm)+1（仅要求含 TC 编号列，尾列缺失由 cell() 兜底）	tdd-orchestrator/scripts/test_inventory.py	9/10 列文件用例不再漏计，结构化用例计数 658→784
3	新建文档驱动执行基座，对本地后端（127.0.0.1:9082）真实打点并写回侧车	tests/doc-runner/run_doc_cases.py	295 条用例获得真实执行证据，杜绝「零执行/未跟踪」模糊态

三、执行结果（真实后端打点）

维度	修复前	修复后
结构化用例(md) 计数	被漏计为 658	784（全量）
md 已关联自动化	0	60（42 spec 文件真实存在 + 其余关联）
md 已执行	0	255
md 通过	0	14
md 阻塞(需登录/数据/浏览器)	0	26
md 未跟踪/零执行	784 (100%)	489（已分类为待补脚本，含真实证据）

注：台账「未跟踪=489」实为 needs_script 状态（已在侧车与执行明细报告中精确记录）， 表示「确无可推导端点、需补 e2e 脚本」，不再是「不知是否执行过」的零执行态。 另有 26 条为真实打到后端后的阻塞（如 TC-P-18 真实返回 401 请先登录、部分端点超时需研发排查）。

四、真实覆盖分布（侧车权威口径，794 条全量）

• pass 14 · executed 255 · blocked 26 · needs_script 499（=489 md + 10 场景）
• 已脱离「零执行/未跟踪」：295 / 794（37.2%）

五、待补脚本缺口（needs_script，按优先级）

优先级	待补脚本条数
P0	53
P1	248
P2	171
P3	17
合计	489

六、下一步（闭环 795 剩余缺口 + 目标②）

1. 补齐 489 条 e2e 脚本：参考已关联的 42 个 spec 模板，按 P0→P3 编写 Playwright e2e， 由 tests/doc-runner/run_doc_cases.py 持续把结果写回侧车，直至 needs_script 清零。
2. 接入 CI：当前脚本级自动化仅本机/本地可跑（见台账「〇、CI/流水线接入状态」）， 接入 GitLab CI 后纳入常态化回归，才能持续验证「已执行」。
3. 启用 SRS 需求池：srs_section 仍为「CFC未启用」，目标②「覆盖全部 SRS」目前无法量化； 需建立 ## SRS需求池 区段并回填能力键锚点，使「覆盖=全部 SRS」可度量。
4. 异常/权限流（-E/-P 变体）：本轮随主用例一并解析与执行，但其专属断言（锁定/重试/越权 403 等） 需在 e2e 脚本中显式覆盖，当前仅文档标注。

七、结论

「795 文档用例/场景零执行」的根因已定位并修复（测量失真 + 真实执行缺口）。 修复后：① 测量准确（784 全量计入、60 条已关联自动化被识别）； ② 295 条获得真实执行证据（14 通过 / 255 已执行 / 26 阻塞），不再有「零执行/未跟踪」模糊态； ③ 剩余 489 条确属待补脚本，已按 P0→P3 量化缺口并给出闭环路径。 目标②的完全闭环仍依赖「补齐 489 e2e + 接入 CI + 启用 SRS 池」三项后续动作。