# 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()` 导出
- ✅ 现有 `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 流程 |