root/aurora-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
eb25feedaff9a13f3f8753fb94611ff468b6abe6
aurora-admin/PLAN.md
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

8.5 KiB
Raw Blame History

Aurora Admin 组件文档体系 — 规划 / 路线图

项目：C:\Users\12914\Desktop\组件规范第一套 当前版本：1.0.0 · 品牌：Aurora Admin（主色 #2F54EB） 规划目标：在已有 79 个组件 × 5 端实现 的基础上，补齐「完整内容模块 / 日志 / 搜索 / 测试 / 路线图」五大体系，让这套组件库成为可对外交付、可被审计、可被检索、可被回归的产品级文档。

1. 现状盘点（2026-09-07 评估）

模块 已存在 评价 是否需要补
README.md / SKILL.md ✅ 品牌叙事 + Agent 入口齐备 否
colors_and_type.css / css.json / components.css ✅ 设计令牌 100% 覆盖 否
components/index.json + 6 个核心契约 ✅ 79 项实现已登记，6 核心含契约 否（扩展契约待补）
frameworks/ × 5 端 ✅ 79×5=395 文件 否
site/index.html + style.css + app.js ✅ Element 风格三栏 + Ctrl+K 搜索 + 主题定制 搜索增强、错误日志待补
site/dev-server.js ✅ 单文件 75 行 HTTP 服务 否
build-site.ps1 ✅ 生成 site/data.js 日志开关待补
组件测试页 ❌ 仅 6 个核心组件有 preview/*.html；73 个扩展无独立测试 必补
变更日志 CHANGELOG.md ❌ 没有 必补
路线图 / 计划 ❌ 没有（本文档填补） 必补
测试入口 / 测试计划 ❌ 没有 必补
贡献指南 CONTRIBUTING.md ❌ 没有 必补
系统日志（构建/搜索/渲染） ❌ console 散落 必补

2. 内容模块（Content Modules）— 完整组件文档应包含的 10 项

# 模块 落地位置 内容要点 状态
1 品牌与原则 .design_library/aurora-admin/README.md 品牌叙事 / 设计原则 / Content Fundamentals ✅
2 设计令牌 colors_and_type.css + css.json 色彩/字体/间距/圆角/阴影/控件高度 ✅
3 核心组件契约 .design_library/aurora-admin/components/*.json 变体维度 / 代表变体 / 使用要点 / 结构 / 解剖 / 不发明 / 未明示 ✅ 6 项；73 项扩展契约待补（计划 1.1）
4 规格批次映射 .design_library/aurora-admin/components/index.json slug ↔ 规范文件 ↔ 实现前缀 ✅
5 全量预览 frameworks/<Name>.html 5 端展示 ✅
6 文档站首页/总览/快速开始/设计规范 site/app.js + site/style.css Element 风格布局 + 锚点目录 ✅
7 全局搜索 Ctrl+K 弹窗 (bindSearch) 中/英/slug 模糊匹配 ✅；搜索日志待补（计划 2.1）
8 主题定制器 悬浮工具 (theme-panel) 4 键覆盖 + 复制 CSS ✅
9 每个组件的测试页 tests/<slug>.html 交互断言 / 键盘可达 / 焦点环 / 状态矩阵 ❌ → 本轮补齐
10 变更日志 / Roadmap CHANGELOG.md / PLAN.md 版本化记录 + 计划 ❌ → 本轮补齐

3. 日志系统（Logging）— 应收集的四类事件

类别 来源 落盘 用途
构建日志 build-site.ps1 site/data.js 首行 + logs/build.log 缺失文件 / 无分类组件告警
渲染日志 site/app.js localStorage[aa-render-log] + 可选下载 首页/总览/详情/搜索加载耗时、缺失 iframe、脚本错误
搜索日志 bindSearch() localStorage[aa-search-log] 关键词、命中数、点击目标
测试日志 tests/<slug>.html（本轮新增） localStorage[aa-test-log] 每组件测试结果、失败项、堆栈

所有日志默认本地落盘（避免隐私问题），提供「导出」按钮 → 复制 JSON，方便提交 issue。

4. 搜索系统（Search）— 现有 + 增强

4.1 现有

  • 触发：Ctrl+K / 顶栏按钮
  • 字段：组件中文名 / 英文名 / slug
  • 上限：20 条
  • 排序：原顺序

4.2 本轮增强

能力 描述
分类过滤 Ctrl+K 弹窗内 chip 行，可只看某一类（如只看「反馈」类）
关键词高亮 命中字符 <mark> 包裹
模糊容错 子串匹配 + 大小写不敏感；支持中英文混输
搜索日志 记录每次 query、点击目标、毫秒级耗时
全局快捷键 Ctrl+/ 在页面内任意位置直接聚焦搜索（已 Ctrl+K 仍可用）

5. 测试系统（Per-Component Tests）— 范围与原则

5.1 原则

  • 零依赖：纯 HTML + 原生 JS + design tokens，可直接在浏览器打开
  • 可视化：每个组件独立 tests/<slug>.html，含三段：① 渲染快照 ② 交互用例 ③ 断言结果表
  • 可机器读取：每条断言在 DOM 上加 data-assert="<id>" 与 data-status="pass|fail"，便于 Playwright/Selenium 回归

5.2 通用测试矩阵（每个组件都跑这 8 项）

  1. 默认态渲染 —— 快照含核心节点
  2. 尺寸/类型变体 —— 大/中/小 / 主/次/危险…
  3. 状态覆盖 —— hover / active / focus / disabled / loading
  4. 键盘可达 —— Tab 进入、Space/Enter 触发、Esc 关闭
  5. 焦点环可视 —— focus-visible 不被覆盖
  6. ARIA 属性正确 —— role / aria-disabled / aria-expanded
  7. 对比度 ≥ 4.5:1（正文） / 3:1（大字号）
  8. token 一致性 —— 所有颜色取自 --au-*，不硬编码

5.3 本轮落地

  • 79 个组件全部生成 tests/<slug>.html（脚本批量）
  • 顶部总入口 tests/index.html —— 79 个测试页的导航 + 通过率
  • run-tests.ps1 —— 本地一键构建测试目录（可扩展到 headless 跑通）

6. 路线图（Roadmap）

6.1 v1.0.0（当前）— 文档骨架就绪

  • ✅ 79 个组件 × 5 端实现
  • ✅ 设计令牌 100%
  • ✅ Element 风格文档站
  • ✅ Ctrl+K 搜索

6.2 v1.1.0（本轮）— 文档可被审计、可被回归

  • 🆕 tests/<slug>.html × 79
  • 🆕 tests/index.html 总览
  • 🆕 CHANGELOG.md v1.1.0
  • 🆕 CONTRIBUTING.md
  • 🆕 TESTING.md
  • 🆕 site/logger.js（构建/搜索/渲染日志）
  • 🆕 site/test-logger.js（测试日志）
  • 🆕 搜索增强：分类过滤 / 高亮 / 模糊容错
  • 🆕 run-tests.ps1 构建脚本

6.3 v1.2.0（未来）— 进阶能力

  • 给 73 个扩展组件补齐 components/<slug>.json 契约
  • 提供 site/data.json（无 JS 注入的纯 JSON，供爬虫/SSR）
  • 接入 Playwright headless 跑测试，输出 JUnit XML
  • 国际化 i18n：EN/JP 双语
  • 暗色主题 dark variant
  • 接入 Storybook 作为开发环境（可选）

7. 验收标准（本轮完成定义）

  • ✅ 每个组件有 tests/<slug>.html
  • ✅ tests/index.html 能列出全部 79 项并给出通过率
  • ✅ 文档站支持 Ctrl+K 搜索 + 分类过滤 + 高亮
  • ✅ CHANGELOG.md 记录 v1.1.0
  • ✅ PLAN.md（本文件）记录路线图
  • ✅ CONTRIBUTING.md 写明如何加新组件
  • ✅ TESTING.md 写明测试矩阵与执行方式
  • ✅ site/app.js 内置日志收集，可在控制台 aaLogger.export() 导出
  • ⚠️ 规划修正（2026-09-19 实测）：原「现有 site/dev-server.js 不破坏，原样保留」已不成立——该服务单个 GET /site/%00 即触发 ERR_INVALID_ARG_VALUE 未捕获异常并退出进程，已修复（NUL 双重拦截 + readFile try/catch + AA_PORT 开关）。见 tools/verify-dev-server.mjs。
  • ✅ 不修改 site/data.js（自动生成物）、不改 build-site.ps1 主流程

8. 不在本轮范围（显式排除）

  • ❌ 不写 React 单元测试（Jest/Vitest），保持零依赖
  • ❌ 不引入 npm 依赖
  • ❌ 不改 git
  • ⚠️ 规划修正（2026-09-19 实测）：原「不改 site/dev-server.js（已工作良好）」的立论被实测推翻（见 §7 同条），该文件已按缺陷修复；此后对其改动仍需跑全量回归。
  • ❌ 不动 frameworks/ 下的源码（只读引用）
  • ❌ 不重构 site/app.js 主体，只追加新文件 / 追加 hook
  • ❌ 不改 DSH harness settings / memory

9. 风险与对策

风险 对策
79 个测试页太大、构建慢 生成器脚本一次写完；后续增删组件只需重跑
测试页与展示页视觉脱节 复用 colors_and_type.css + components.css，保持同源
文档站日志带来隐私顾虑 仅落 localStorage，提供导出按钮，不发任何远程
搜索增强改动影响现有 Ctrl+K 走增量 hook，老逻辑保留
与 build-site.ps1 冲突 新增独立脚本 run-tests.ps1，不动 build 流程
Reference in New Issue View Git Blame Copy Permalink