aurora-admin
6fec4ba6f8
回归通过率此前不可信：run-tests.ps1 抽取演示页 body 时剥离全部 <script>， 而 79 个 H5 演示页的 DOM 全由内联脚本渲染，且测试页从未引用 frameworks/<组件>.css —— 断言跑在空 DOM + 无组件样式上，v1.2.0 的 75.1% 属结构性误报。 Fixed — 验收链路 - 测试页改为 iframe 加载真实演示页（_template.html），_runtime.js 跨帧在真实 渲染结果上断言：帧内 getComputedStyle/styleSheets/outerHTML，用例自动标注 + 帧内描边，结果 postMessage 上报 - 标注改为容器下钻（.row/.demo-block → 首个含 ≥2 有效子元素的容器，最多 6 层） - 新增 N/A 语义：静态组件键盘/ARIA 记 skip 而非失败；对比度与 token 检查限定 在被测组件区，页头文档文字不计 - 通过率分母改为 pass/(pass+fail)，tools/run-regression.mjs 与收集器同口径 Added — 设计系统 - 基座 :focus-visible 统一焦点环（colors_and_type.css）。--au-color-focus-ring 此前只定义未消费，79 个组件样式仅 20 个自带 focus 规则 —— 一次性消除 66 页失败 - tests/_collect.html：零依赖浏览器批量回归收集器（并发 iframe + 汇总） - tests/_index_template.html：测试总览页模板外置，读数来自 data.json Added — 契约第二批（展示类 15 个） - tree/collapse/calendar/carousel/imagepreview/qrcode/countdown/watermark/ cardlist/treetable/timelinelist/steplist/chartpanel/dashboardcard/employeecard - 逐份从规格原文（组件2/4/7/9.txt）提炼，含 dims/variants/anatomy/structure/ usageHints/doNotInvent/unknowns；契约化 21 → 36/79 Changed - run-tests.ps1 重写：删除失效的快照抽取（占位符替换早已不匹配模板），改生成 iframe 版测试页；输出 WriteAllText 无 BOM；保持 ASCII-only，中文移入 UTF-8 模板 - 回归基线：960 断言 / 794 通过 / 85.1% / 11 页全通过 / N/A 27 - CHANGELOG/TESTING/改造清单同步；测试总览页与首页通过率联动 验证：浏览器全量 79 页收集器跑通两次，基线一致；详情页契约章节 （含 doNotInvent/unknowns）、chip、首页「通过率 85.1%」、changelog v1.3.0 实测通过
84 lines
5.7 KiB
Markdown
84 lines
5.7 KiB
Markdown
# 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 修好的回归（否则新契约没有任何真实断言兜底）。
|