# 结构化用例脚本化产物

> 由 `tests/scripts/scriptize_tc.py` 自动生成。**唯一数据源是 `cases.json`**；
> 修改用例请改 `tests/test-cases/*.md` 后重跑生成器，不要手改本目录文件。

## 规模

- 文档用例：**784 条**（11 个 md 文件，含正常流 / 异常流 / 权限流 / 非功能）
- 生成 test()：**784 个**（1:1，无丢弃、无合并）
- 可真实执行（active-api + active-probe）：**344 条**；设计态/锚点：**440 条**

## 运行

```bash
# 1) 静态校验：离线列出全部用例，不打任何网络请求
cd tests
npx playwright test e2e/api/generated/tc-scripted.spec.js -c playwright.config.api.js --list

# 2) 默认空跑：所有用例为 fixme，零副作用
npx playwright test e2e/api/generated/tc-scripted.spec.js -c playwright.config.api.js --project=desktop

# 3) 真实执行（需测试负责人显式授权联网 + 确认目标环境可写）
TC_LIVE=1 npx playwright test e2e/api/generated/tc-scripted.spec.js -c playwright.config.api.js --project=desktop
```

## 分级口径（诚实边界）

| 分级 | 含义 | 是否打远程 | 闭环条件 |
|---|---|---|---|
| `active-api` | 有 `/api` 路径 + 可判定状态码 → 断言 code 落在预期集合 | 仅 `TC_LIVE=1` | 授权联网并确认目标环境 |
| `active-probe` | 有 `/api` 路径但预期无状态码 → 只断言「不应 5xx」弱契约 | 仅 `TC_LIVE=1` | 补状态码契约后升级为 active-api |
| `auth-probe` | 权限流派生用例：不带 token 访问受保护接口，断言 401/403 | 仅 `TC_LIVE=1` | 若要覆盖「低权限 token 越权他人资源」需补夹具 |
| `linked-e2e` | 文档已关联既有 spec（文件确实存在） | 否 | 执行原 spec，本条仅作文档锚点 |
| `design-contract` | 预期写了状态码但步骤没给接口路径 | 否 | 补 API 映射后重跑生成器 |
| `design-ui` | 依赖前端 SPA/DOM 与浏览器 | 否 | 部署前端 + 安装 Playwright 浏览器 |
| `design-env` | 性能/兼容类，需压测授权或多端环境 | 否 | 单独授权 execute 档 |
| `design-fixture` | 需业务夹具/种子数据/人工编排 | 否 | 补夹具与数据构造 |

> ⚠️ `active-api` / `active-probe` 只是「接口契约探针」：body 为空对象，不构造业务数据。
> 步骤中若含 UI 操作（`ui_mixed=true`），该用例只覆盖接口层，不等于完整业务流已测。
> 设计态用例用 `test.fixme(true, reason)` 明确阻断，**不会**被计入通过。

## 路由证据（本轮新增）

原本 392 条「写了状态码但没接口路径」的用例，按四路证据补出真实路径：

| 级别 | 依据 | 可信度 |
|---|---|---|
| `inline` | 用例步骤/预期里原文写出的 `/api` 路径 | 最高 |
| `inherit` | 派生自正常流基用例的路径 | 高 |
| `controller` | 「关联需求/设计」列的 Controller 名 → 源码 `file:line` | 高 |
| `doc-fuzzy` | `API_REFERENCE.md` 章节名与模块中文词关联 → 源码真实路由 | 中，模块级关联**需人工复核** |
| `linked-spec` | 既有 spec 中实际调用过的路径 | 中 |

`cases.json` 每条都带 `route_level` / `route_evidence`；**无可靠证据的用例保持设计态**，不硬猜路径。
另已排除免鉴权公开端点（login/register/send-code 等），避免未授权探针产生假失败。

## 本机已知限制（实测）

- `npx playwright test --list` 可用且已验证：**Total: 784 tests in 1 file**。
- 本机直接跑 runner 会被 `safe-delete` 守卫拦截（Playwright 清理 `outputDir` 时
  `genie-trash` 二进制 ETIMEDOUT）。因此本目录**未做真实执行**，请在 CI 或已授权的
  runner 上运行；`.tdd/verify-scripted.cjs` 提供不启动 runner 的离线加载式验证。

离线验证结论（`node .tdd/verify-scripted.cjs`）：

```
默认(无授权) | tests=784 fixme=784 apiCalls=0（零联网）
TC_LIVE=1    | tests=784 fixme=440 apiCalls=344（auth-probe 209 条 + 游客用例不带 token）
```

## 台账

- `docs/tdd/test/scriptization-map.md`：分级汇总与统计
- `docs/tdd/test/scriptization-map.csv`：784 行 TC → 脚本定位 → 状态 → 原因映射

## 与 automation-status.md 的关系

本产物把「脚本级已自动化」由 0 提升到 784，但**执行状态仍全部为 0**（已执行/通过/失败均未伪造）。
执行回写需在真实运行后由测试负责人按结果更新侧车 `test-progress.json`。