# v1.3.0 执行计划（验收链路修复 / 契约第二批 / 文档同步）

> 依据：《现状问题分析与改造清单》v1.3.0 路线图（契约第二批/第三批、C1-C4 收口）+ 本轮对 v1.2.0 交付物的**实测核实**。
> 原则不变：零运行时依赖、build 脚本产物全部可重跑、每步完成即验证、改完文档与实现同步。

---

## 〇 · 前置核实结论（2026-09-10 实测，非文档声称）

| 项 | 文档声称 | 实测结果 | 判定 |
|---|---|---|---|
| 契约覆盖 | 21/79 | `index.json` 带 `contract` 字段 21 条，契约 JSON 22 个文件（含 index.json） | ✅ 一致 |
| 79 静态薄壳 + sitemap | 已生成 | `site/components/*.html`、`sitemap.xml` 存在 | ✅ 一致 |
| 回归通过率 | 75.1%（812 断言） | `tests/report.json` 数值一致，但**报告 version=1.1.1，早于 v1.2.0** | ⚠️ 数据过期 |
| 回归失败项定性 | "演示页真实缺口（states/aria/keyboard），不是 runner 误报" | **定性错误**：根因是测试页快照为空壳（见下） | ❌ 需修正 |

### 回归通过率低的真实根因（本轮定位）

1. `run-tests.ps1` 的 `Get-Snapshot()` 从 `frameworks/<Prefix>.html` 抽取 body 时：**删除全部 `<script>` 与 `<style>`**，并截断到 1200 字符。
2. 79 个 H5 演示页的 DOM **全部由内联 JS 渲染**（body 只有 `<div id="app"></div>` + `<script>render()</script>`）——script 一剥，快照就没内容。
3. 测试页只引用 `colors_and_type.css` + `site/style.css`，**从未引用 `frameworks/<Prefix>.css`**，组件样式根本没加载。
4. 后果：`matrix:states>=1`（52 失败）、`matrix:aria-or-role`（51）、`matrix:variants>=2`（40）、`matrix:keyboard-reachable`（35）在空 DOM 上必然全灭；`contrast>=4.5`（9）在无组件样式下按测试页默认色误判。

**结论：75.1% 是结构性误报，不是实现质量。** 修好链路后通过率才有资格作为对外证据链（Semi「90% 覆盖」那一档的可信度基础）。

---

## WS-1 · 验收链路修复（P0，先做，其他工作的地基）

**做法**：测试页快照区改为 **iframe 加载真实 `frameworks/<Prefix>.html`**，断言运行时**跨帧在同源 frame document 内执行**。

- `tests/_template.html`：`<div id="snapshot">` → `<iframe id="snapshot-frame" src="../frameworks/<Prefix>.html">` + 「新窗口打开演示页」链接。
- `tests/_runtime.js`：
  - 新增 `frameDoc()`（取 `contentDocument`，同源可直读；失败回退 `document`）；
  - `collect()/annotate()/matrix()` 的目标文档、`getComputedStyle` 所属 window、`styleSheets` 来源、`outerHTML` 均切到 frame；
  - 向 frame 注入 `[data-assert]` 状态描边样式，保留可视化；
  - iframe `load` 后自动跑一次断言，并把结果 `postMessage` 给父页（供批量收集器汇总）。
- `run-tests.ps1`：`Get-Snapshot()` 删除，改为产出 iframe 标记；`Set-Content -Encoding UTF8` 改 `WriteAllText`（无 BOM，与 v1.2.0 的 data.js 修复口径一致）。

**新增** `tests/_collect.html`：把 79 个测试页顺序装入 iframe，监听 `postMessage` 汇总，输出可机读 JSON（供浏览器 `browser_evaluate` 取回写 `tests/report.json`，零 npm 依赖）。

**验收**：
- 任取测试页（button / modal / breadcrumb）浏览器打开：iframe 内组件真实渲染、有样式、`运行断言` 后 matrix 8 项通过率显著上升；
- 79 页全量收集产出新版 `tests/report.json`（version=1.2.0），并通过 `tools/run-regression.mjs` 口径校核（同字段结构）；
- 剩余失败项逐条定性为**真实缺口**（保留为改进 backlog，不再有"空 DOM 全灭"这类假失败）。

## WS-2 · 契约第二批：15 个展示类组件（P0，沿用第一批 schema）

选件规则：`category=display` 高频优先，排除已有契约的 table/card。

| slug | 中文 | slug | 中文 | slug | 中文 |
|---|---|---|---|---|---|
| tree | 树形控件 | collapse | 折叠面板 | carousel | 走马灯 |
| calendar | 日历 | timelinelist | 时间轴 | steplist | 步骤列表 |
| cardlist | 卡片列表 | imagepreview | 图片预览 | qrcode | 二维码 |
| countdown | 倒计时 | watermark | 水印 | employeecard | 员工卡片 |
| chartpanel | 图表面板 | dashboardcard | 指标卡 | treetable | 树形表格 |

**字段**（与现有 21 份同 schema）：`variantDimensions` / `representativeVariants` / `usageHints` / `structurePatterns` / `anatomy` / `doNotInvent` / `unknowns`。

**流程**：读规格原文（`组件*.txt` 对应章节）→ 写 `.design_library/aurora-admin/components/<slug>.json` → `index.json` 注册 `contract` → 重跑 `build-site.ps1` → 浏览器验证详情页「设计契约」章节与 chip。

**硬规则**：只从规格原文提炼，**不发明**；规格未明示的进 `unknowns`，规格明确排除的进 `doNotInvent`。

**验收**：`data.json` 中这 15 个组件 `contractRef` 非空、`contract` 对象完整；契约化覆盖 21 → 36/79。

## WS-3 · 收尾

- `CHANGELOG.md` 增 `[1.3.0]` 条目（回归链路修复 + 契约第二批 + 回归数据更新）。
- `TESTING.md`：修正"失败项是演示页真实缺口"的错误定性，写清 iframe 快照机制与两种回归跑法（浏览器收集器 / Playwright runner）。
- `现状问题分析与改造清单.md`：进度标注同步（问题 8 的定性修正、B1 进度 21→36）。
- `TESTING.md` 中"§ 重新生成测试目录"补 iframe 说明。
- `git commit`（不推送，推送仍需用户凭证）。

---

## 执行顺序

```
WS-1（链路修复 → 重生成 → 全量回归）→ WS-2（契约第二批 → 重建 → 验证）→ WS-3（文档 + 提交）
```

依赖：WS-2 的验收依赖 WS-1 修好的回归（否则新契约没有任何真实断言兜底）。