Files

T

aurora-admin eb25feedaf feat(S6-P21): 组件族参数化(13族/44成员/导航族15文件同源/79→48概念组件)

【本次核心 · S6-P21】
- 族层数据：families.json + 44 份契约注入 family/familyRole/familyParams；
  data.json / data.js / site/details 同步。13 族 / 44 成员 / 35 独立 → 概念组件 79→48。
- 79 个 slug 全保留、集合逐一不变（铁律 5 对外承诺未破）；frameworks 仍 395 文件、薄壳仍 79。
- 归族判据为契约中可核对字段（semanticTypeCandidates 重叠 / anatomy 为同一骨架子集 /
  变体维度同构 / doNotInvent 显式从属声明），每族 mergeBasis 写明依据，不按名字猜。
- 实现层合并（导航族端到端切片）：tools/gen-family-impl.mjs 从 5 端模板生成
  TopMenu / SideMenu / MixedNavigation 共 15 文件，参数 direction=top|side|mixed；
  三份 CSS md5 完全相同 = 一份样式表服务三个组件。
- 新增 tools/gen-families.mjs、tools/gen-family-impl.mjs、tools/verify-families.mjs、
  tools/lib/family-model.mjs、tools/lib/family-impl/nav-menu/*.tpl。

【同时清掉此前已完成但未提交的批次】
生成物（data.json / data.js / site/sources / site/components 薄壳 / sitemap.xml / tests 报告）
跨阶段交织，无法拆成互相自洽的多个提交，故按既有批量风格合并提交：
- Package：三端可 import（S5-P18）+ 发布到私有 npm 源
- Docs site：导航语言改下拉（S5-P19）、详情页代码块默认展开、中英切换完整性
- Security：生产部署链审计修复（2026-09-19）+ 线上部署
- Theme modes 日间/夜间/自动；S1-P4 data.js 瘦身；S2-P5 暗色；S2-P6 跨端一致性；
  S2-P7 行为断言；S2-P9 FAQ；S3-P8 RTL；S3-P9 契约缺口解释层；S4-P12 发布流程
- 补入 tools/pack-deploy.mjs、run-site-smoke.mjs、verify-*.mjs，.dockerignore、
  安全审计修复与待决策项.md

【验收】
- node tools/verify-families.mjs → OK: 族层端到端一致（13 族 / 44 成员 / 79 组件不变 / 395 文件不变）
- node tools/verify-cross-platform.mjs → 79/79 identical（HEAD 基线 high 44）
- node tools/run-regression.mjs → 100%（79/79 页，1017/1017 断言，N/A 34），连跑 8 次一致，0 超时
- 逐页实测：topmenu / sidemenu / mixednavigation 各 13/13，帧内 direction 参数正确，0 JS 错误
- 零运行时依赖 OK；build-site.ps1 ASCII-only OK

【未纳入】site/components/<slug>/ 平台薄壳 316 个 —— 历史从未跟踪且属构建产物，保持现状。

2026-09-20 03:32:31 +08:00

5.1 KiB

Raw Blame History

测试说明

Aurora Admin 的测试设计：零运行时依赖、可视化、可机读。设计系统包含 79 个全量组件契约，每个组件对应 4 个运行端（H5 / React / Vue 2 / Vue 3）以及 CSS 资产；tests/<slug>.html 是 H5 回归测试页。

环境与安装

需要 Node 20+。package.json 的 dependencies 必须为空；Playwright 属于 CI/本地验证用 devDependency。

npm ci

Headless 回归

node site/dev-server.js          # 先起站，监听 127.0.0.1:3311
node tools/verify-dev-server.mjs # 本地服务的畸形请求/穿越防护（含 3 条反例断言）
node tools/verify-emits-parse.mjs # defineEmits 字面量解析：运行时与构建期双实现等价
node tools/verify-i18n.mjs
node tools/verify-site-routing.mjs
node tools/verify-cross-platform.mjs
node tools/run-regression.mjs    # 输出 tests/report.json + report-junit.xml
npm run smoke:site

tools/verify-dev-server.mjs 会用 AA_PORT（默认 13311）另起一份服务，因此不会与手工起的 3311 实例抢端口；tools/run-regression.mjs 支持 REG_BASE 指向别的端口。

CI 使用 Node 20、严格 npm ci 和 npx --no-install，并缓存 Playwright 浏览器。站点服务已启动后，smoke:site 会验证文档站语言、路由、详情、目录、主题面板、框架保持和刷新恢复。

无 Playwright 的机器可以打开 tests/_collect.html，它把 79 个测试页装入同源 iframe，汇总结果到 window.__aaCollectResult；这条浏览器路径适合人工取证，不替代 CI headless 回归。

当前基线

所有数字以当前 tests/report.json 为准。当前报告（v1.4.1，2026-09-19 实测）为：79/79 页面通过，1017 通过、0 失败、34 N/A，共 1051 条断言；通过率 100%。N/A 不计入通过率分母。

口径说明：此前记录的 1009 / 35 / 1044 是更早工作树状态下的数字。当前数字来自本仓库工作树连续 10 次回归（9 次连跑 + 1 次独立复跑）的一致结果。

tests/report.json 是文档站首页测试摘要的数据源。不要手工修改报告数字，必须修复实际问题后重跑生成。

自动化断言将 A11y 作为结构基线，覆盖键盘可达、焦点环、ARIA、文本/图形对比度和 token 使用等规则。通过率不等同于完整 WCAG 2.1 AA 合规声明。以下内容仍需人工或辅助技术实测：

屏幕阅读器朗读顺序与播报质量（NVDA / VoiceOver）
焦点顺序、焦点陷阱以及弹窗内 Tab 循环
动态内容变更与 aria-live 播报时机
表单错误提示和 aria-describedby 关联
200% 缩放时的布局可用性

RTL 现状与限制

RTL 已纳入样式迁移与验证范围，部分组件使用 CSS 逻辑属性（如 margin-inline-*、padding-inline-*、border-inline-*）。可在宿主页面或场景页设置 dir="rtl" 做定向验收。当前仓库没有把 RTL 宣称为 79 个组件全量完成的视觉验收；图标方向、复杂组合布局、溢出和交互顺序仍需逐组件人工复核。

跨端结构验证

node tools/verify-cross-platform.mjs

脚本从 site/data.json.meta.version 记录版本，检查 79 个组件的 H5 / React / Vue 2 / Vue 3 结构和 class 集合，并输出 tests/cross-platform-report.json。当前报告有 77 个历史差异；差异本身是信息项，不会导致命令失败。总数不是 79 或读取文件失败会阻断命令。

断言为什么跑在 iframe 里

79 个 H5 演示页的 DOM 由内联脚本渲染，测试页通过 iframe 直载真实演示页，CSS 与脚本真实执行，_runtime.js 跨帧读取 contentDocument 执行断言。用例节点在帧内自动标注 data-assert 和 data-status，结果通过 postMessage 汇总。

断言协议与矩阵

<button class="btn btn-primary" data-assert="variant-1" data-status="pass">主按钮</button>
<button class="btn btn-primary" data-assert="variant-2" data-status="skip" disabled>禁用态</button>

每个测试页覆盖以下结构规则：

#	维度	说明
1	默认态渲染	核心节点齐全
2	尺寸/类型变体	代表性尺寸、类型和状态
3	状态覆盖	状态类或状态选择器存在
4	可见用例	至少一个默认态可见用例
5	键盘可达	原生可聚焦元素或 tabindex
6	焦点环可视	存在 `:focus-visible` 描边规则
7	ARIA 属性	交互节点具备 role / aria-*
8	对比度	文本及图形对比度基线
9	token 一致性	用例区不硬编码颜色

重新生成测试目录

powershell -File run-tests.ps1

按 .design_library/aurora-admin/components/index.json 的 79 项生成测试页。修改测试结构时改 tests/_template.html 或 tests/_index_template.html 后重跑，不要手改生成的组件页。

文档站冒烟

node site/dev-server.js
npm run verify:i18n
npm run smoke:site

冒烟覆盖默认中文、英语切换、html[lang]、document.title、导航/详情页/目录、主题面板、aa-lang 持久化、框架保持、路由切换、刷新恢复和切回中文。

5.1 KiB Raw Blame History Unescape Escape