Aurora Admin v1.2.0: 79 components x 5 ends, doc site, contracts batch 1, playground, regression, deploy ready

PLAN.md

@@ -0,0 +1,166 @@
+# 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 流程 |