# 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 池」三项后续动作。