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 项）
- 默认态渲染 —— 快照含核心节点
- 尺寸/类型变体 —— 大/中/小 / 主/次/危险…
- 状态覆盖 —— hover / active / focus / disabled / loading
- 键盘可达 —— Tab 进入、Space/Enter 触发、Esc 关闭
- 焦点环可视 —— focus-visible 不被覆盖
- ARIA 属性正确 —— role / aria-disabled / aria-expanded
- 对比度 ≥ 4.5:1（正文） / 3:1（大字号）
- 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() 导出
- ✅ 现有
site/dev-server.js 不破坏，原样保留
- ✅ 不修改
site/data.js（自动生成物）、不改 build-site.ps1 主流程
8. 不在本轮范围（显式排除）
- ❌ 不写 React 单元测试（Jest/Vitest），保持零依赖
- ❌ 不引入 npm 依赖
- ❌ 不改 git
- ❌ 不改
site/dev-server.js（已工作良好）
- ❌ 不动
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 流程 |
