# Aurora Admin 现状问题分析与改造清单

> **修复进度（2026-09-10 v1.3.0）**：v1.1.1 完成 A1 搜索增强、A2 For Agents + llms.txt、A3 站内 Changelog + 版本同步、B2 暗色令牌映射、B4 主题预设库；v1.2.0 完成 B1 契约第一批（21/79）、B3 Playground、C1 交叉引用、C3 headless 回归骨架、C4 静态薄壳 + sitemap。
>
> v1.3.0（本次）修复**验收链路**并推进契约第二批：测试页此前把演示页快照抽成静态 HTML（剥离 `<script>`）且未加载组件 CSS，而 79 个演示页 DOM 全靠内联脚本渲染——断言跑在空 DOM 上，v1.2.0 的 75.1% 属结构性误报，现改为 iframe 直载真实演示页 + 跨帧断言，基线 **960 断言 / 85.1%**；基座补 `:focus-visible` 统一焦点环（消除 66 页失败）；契约第二批 15 个展示类组件落地（**36/79**）。剩余见下。
>
> 依据：《竞品网站检查报告.md》（2026-09-08）+ 对当前代码的逐文件核实（site/app.js 1671 行、site/style.css、components/index.json、data.json、tests/）
> 性质：问题分析 + 可执行改造清单。本文只做分析与方案，未改动任何文件。
> 版本基准：data.json meta v1.0.0（79 组件 = 10 核心 + 69 扩展），CHANGELOG v1.1.0，6 大分类（通用 4 / 导航 10 / 录入 24 / 展示 20 / 反馈 15 / 系统 6）

---

## 〇、先修正竞品报告中的三处误判（代码核实后）

竞品报告基于 PLAN.md 的描述做对比，逐文件核实后有三处需要修正——**当前代码比报告假设的更强**，后续改造重点也因此不同：

| 报告原判断 | 代码核实结果 | 修正后的问题定性 |
|---|---|---|
| ❌ 暗色模式缺失（v1.2 计划） | ✅ 已实现：`index.html` 深浅切换 FAB + `app.js:1534-1545` `aa-mode` 持久化 + `style.css:973-991` `html.aa-dark` 令牌覆盖 | 不是"有没有"，而是**覆盖不完整**（见问题 2） |
| ❌ 每组件 API 表未上网 | ✅ 已实现：`app.js:637 extractComponentAPI()` 从 frameworks 源码自动提炼，详情页渲染 Props / Events / Slots 三表（`app.js:805 buildApiSection`） | 不是"有没有"，而是**69 个扩展组件无契约保障、提炼靠启发式扫描**（见问题 1） |
| ❌ 测试体系未在站点露出 | ✅ 首页 Hero 已有「测试总览」按钮（`app.js:213`），`tests/index.html` 存在（82 个文件） | 问题只剩**无 headless 回归 + 断言未接入 CI**（见问题 8） |

---

## 一、当前问题清单（按严重度）

### P0 — 影响专业度与可信度

**问题 1：承诺了但没实现的搜索增强（文档与实现不符）**
- `PLAN.md` §4.2 与 §7 验收标准声称 v1.1 已含「分类过滤 chip、关键词 `<mark>` 高亮、模糊容错」；`CHANGELOG.md` v1.1.0 同口径。
- 实际 `app.js:1581 doSearch()` 只有 zh/en/slug 三字段 `indexOf` 子串匹配，无分类 chip 行、无高亮包裹、无模糊容错（拼音/编辑距离）。
- 风险：审计视角下这是"验收标准声称 ✅ 但代码没有"——对一个以「可被审计」为卖点的文档体系是硬伤。竞品全部有即时搜索体验（Element Plus / Ant Design 均含分类过滤与高亮）。

**问题 2：暗色模式是半成品**
- `style.css` 仅有 5 条 `html.aa-dark` 规则（974-991 行：页面背景、topbar、demo-stage、demo-code）；`.design_library/aurora-admin/components.css` 暗色规则 **0 条**；`colors_and_type.css` 未提供暗色令牌组。
- 深色模式下只有站点骨架变色，正文卡片、表格、侧栏、搜索弹窗等大量表面仍按浅色令牌渲染；演示 iframe 保持浅色是有意设计（`style.css:990` 注释），但**这一策略没有写进设计规范页**，使用者会误以为未完成。
- 竞品对照：7 家中 6 家有完整暗色（Ant Design 甚至有整套暗色主题预设）。

**问题 3：契约覆盖 36/79，扩展组件 API 靠源码启发式扫描**
- `components/` 目录已有 36 份契约 JSON（6 核心 + 15 输入类第一批 + 15 展示类第二批）；其余 43 个扩展组件的 Props/Events/Slots 表由 `extractComponentAPI()` 扫描 `.css/.jsx/.vue` 源码正则提取。
- 风险：跨 4 端命名差异（H5 class、React camelCase、Vue kebab-case）极易漏提/错提；竞品的 API 表全部由类型化源码（TS d.ts / props 定义）生成，可靠性不在一个量级。这直接削弱「可被审计」的核心卖点。

**问题 4：AI 消费入口未公开（竞品已全员押注的方向）**
- 本地 `.design_library/aurora-admin/SKILL.md`、`metadata.json`、`library-consumption.json` 已具备 Agent 就绪底座，但文档站没有 For Agents 页、没有 `llms.txt`、无 MCP 描述文件。
- 竞品对照：Ant Design 有 `docs/react/for-agents-cn.md` + 官方 CLI/MCP；Semi 首页横幅「MCP & Skills」；TDesign 2025-08 已上线 MCP 工具。这是 2026 年设计系统的标配入口，而 Aurora 的实现成本极低。

**问题 5：维护信号不上网**
- `CHANGELOG.md` 只是仓库文件，文档站内无更新日志页、组件条目无版本徽章；首页 Hero 版本号停在 data.json 的 v1.0.0（实际已 v1.1.0，两处不同步——`build-site.ps1` 未从 CHANGELOG 取版本）。
- 竞品对照：Element Plus / Ant Design / Naive UI 每个组件标注引入版本；DevUI 的教训是"更新停滞感"本身就是负资产。

### P1 — 高价值补齐

**问题 6：无 Playground（在线编辑/试玩）**
- 详情页 demo 是只读 iframe（`buildDemoCard`），代码可展开不可改。竞品标配：Element Plus.run、Semi Live Code、Arco CodeSandbox。
- Aurora 的组件是零依赖纯 HTML，反而是 7 家竞品中**最容易做 Playground 的**（iframe srcdoc 即可，无需打包器）。

**问题 7：主题定制器缺预设与令牌分组**
- `theme-panel` 仅 4 个颜色键 + 复制覆盖代码；无预设主题一键切换（Ant Design 13 套 / Semi DSM 主题商店 / Naive UI 换主题演示）。
- 令牌文件里 au-* 令牌是分组注释的（品牌/中性/语义），面板未按组呈现，也没有「只改语义色不改品牌色」的分层能力。

**问题 8：测试断言未接入自动回归**（v1.3.0 已修链路，剩余为真实缺口）
- `tests/*.html` 已带 `data-assert` / `data-status` 机器可读标记，`tools/run-regression.mjs` 与 `tests/_collect.html` 两种 runner 均可批量执行并产出 `tests/report.json`。
- **v1.3.0 修正**：此前测试页把演示页 body 抽成静态快照（剥离 `<script>`）且未引入组件 CSS，而演示页 DOM 全靠内联脚本渲染，导致断言在空 DOM 上大面积失败——原 75.1% 不是真实质量数据。现改为 iframe 直载真实演示页 + 跨帧断言，基线 960 断言 / 85.1%（N/A 27）。
- 剩余失败项是演示页的真实缺口：状态覆盖 45、对比度 35、ARIA 33、键盘可达 15、硬编码 hex 9、变体 2。
- Semi 宣称"单测+E2E+视觉对比 90% 覆盖"并作为首页卖点；Aurora 现已有可复现证据链，但覆盖率仍待补齐。

### P2 — 增强项

**问题 9：无组件交叉引用** — 无「相似组件 / 搭配使用 / 推荐·慎用」（TDesign Button 页特色栏目）。契约 JSON 已有「不发明 / 未明示 / 使用要点」字段，具备映射条件。
**问题 10：无 i18n** — CAT_LABELS 等常量硬编码中文，无 EN 切换（7 家竞品全有双语，3 家还有 RTL）。
**问题 11：无设计资源下载** — css.json 已是结构化令牌，但没有导出 Figma Tokens / 设计资源包入口（竞品标配 Figma/Sketch 资源）。
**问题 12：可爬取性弱** — hash 路由 SPA 全靠 JS 渲染；`data.json` 已生成（2026-09-07）但无 sitemap、无每组件静态入口，搜索引擎与 LLM 爬虫拿不到组件页内容。
**问题 13：组件页无 FAQ**（Ant Design 每组件 FAQ 模式，高频问题沉淀）。

---

## 二、可改造项目清单（11 张项目卡）

> 工作量：S ≤ 1 天，M = 2-4 天，L ≥ 1 周（单人）。均不改 `site/dev-server.js` 主流程、不动 frameworks 源码，遵守 PLAN §8 约束。

### A1 · 搜索增强「补票」（P0，S）
- **做法**：`doSearch()` 结果行加分类 chip 过滤行 + 命中字段 `<mark>` 包裹 + 匹配不到时回退单字拆分匹配（中文模糊容错的最小实现）。
- **落点**：`site/app.js` doSearch/bindSearch + `site/style.css` 搜索弹窗样式。
- **对标**：Element Plus Ctrl+K、Ant Design 搜索。
- **理由**：把"声称已做"变成"真的做了"，消除审计硬伤，成本半天。

### A2 · For Agents 页 + llms.txt（P0，S）
- **做法**：新增 `#/agents` 页（渲染 SKILL.md 内容：令牌约定、契约 schema、5 端文件命名规则、消费方式），站点根放 `llms.txt` 指向 `data.json` / `components/index.json` / 各契约 JSON；可选附 MCP tool 描述 JSON。
- **落点**：`site/app.js` 新 render 函数 + `site/llms.txt`。
- **对标**：Ant Design For Agents、TDesign MCP、Semi MCP & Skills。
- **理由**：Aurora 的 JSON 化令牌 + 契约 + data.json 天然适合 Agent 消费，这是性价比最高的差异化项目。

### A3 · 站内更新日志页 + 组件版本徽章（P0，S/M）
- **做法**：CHANGELOG.md 构建时解析进 data.js，新增 `#/changelog` 页；组件条目按 specBatch + 契约登记版本渲染小徽章（如 `1.1.0`）；`build-site.ps1` 从 CHANGELOG 提取当前版本写入 data.js meta，消除 v1.0.0/v1.1.0 不同步。
- **落点**：`build-site.ps1`、`site/app.js` renderChangelog、总览/详情页徽章样式。
- **对标**：Element Plus 版本徽章、Ant Design 更新日志页。

### B1 · 扩展组件契约补齐 69 个（P0，L，分批）
- **做法**：按使用频次分三批补契约 JSON（第一批：输入类高频 15 个——表单场景是 B 端核心；第二批：展示类 15 个；第三批：其余）。每份契约补全 variants/props/events/a11y/使用要点/不发明/未明示 字段；`extractComponentAPI()` 改为**契约优先、源码扫描兜底**，两者 diff 时以契约为准并在页面标注「契约化 ✓」（现有 `app.js:985` 契约 chip 已有此交互）。
- **落点**：`.design_library/aurora-admin/components/<slug>.json`（新增 69 个）+ `build-site.ps1` 注入 data.js。
- **对标**：Ant Design 组件级 Design Token 双层表、Semi 类型化 API。
- **理由**：这是「可被审计」从口号变事实的关键工程，也是 B1/A1/A3 之外所有内容模块的数据地基。

### B2 · 暗色模式令牌映射补全（P1，M）
- **做法**：`colors_and_type.css` 增加 `html.aa-dark` 下的语义令牌映射组（页面/卡片/边框/四级文字/五种语义色的暗色值），`components.css` 改用令牌引用后自动生效；「演示 iframe 保持浅色」策略作为显式规则写进设计规范页与组件页说明。
- **落点**：`colors_and_type.css`、`components.css`（仅令牌引用方式，不改组件视觉）、`app.js` renderDesign 增补说明。
- **对标**：Ant Design 暗色算法、Naive UI 内置深色。

### B3 · Playground（P1，M）
- **做法**：demo 卡片加「在线编辑」模式——代码区变 textarea，iframe 用 `srcdoc` 实时重渲染，提供「复位 / 复制 / 全屏」；零依赖，不引入任何编辑器库（textarea + 等宽字体即可起步）。
- **落点**：`site/app.js` buildDemoCard/buildCodeArea 扩展。
- **对标**：Semi Live Code、Element Plus Playground。
- **理由**：5 端纯 HTML 源码使 Aurora 成为最容易实现真·Playground 的竞品，反而可以后发先至。

### B4 · 主题预设库（P1，S/M）
- **做法**：theme-panel 增加 6 套预设（科技蓝/暗夜/暖橙/极简灰/高对比无障碍/森林绿），点击即整组覆盖 au-* 令牌并持久化到现有 `aa-theme` 机制；预设数据外置为 JSON，可继续扩充。
- **落点**：`site/app.js` theme-panel、`site/presets.json`（新增）。
- **对标**：Ant Design 13 套主题预设、Semi DSM 主题商店（Aurora 的"主题商店"雏形）。

### C1 · 组件交叉引用（P2，S）
- **做法**：详情页底部渲染「相似组件 / 常与 XX 搭配 / 推荐·慎用」卡，数据来源：同分类组件 + 契约 JSON 的使用要点/不发明字段（规则生成，无需人工全量维护）。
- **落点**：`site/app.js` renderComponent 尾部 + 契约 schema 扩展字段。
- **对标**：TDesign「相似组件」「组件搭配使用」「推荐/慎用示例」。

### C2 · i18n 英文版（P2，M）
- **做法**：CAT_LABELS/导航/首页文案字典化为 `site/i18n.js`（zh/en），顶栏加语言切换并持久化；组件名本身双语已具备（splitName）。
- **对标**：全部 7 家竞品均有中英双语。

### C3 · headless 回归（P2，M）— v1.3.0 已完成
- **做法**：用 Playwright 批量加载 tests/*.html，读取 `data-assert`/`data-status` 汇总通过率，输出 JUnit XML；文档站首页展示最近一次回归结果。
- **落地**：`tools/run-regression.mjs`（Playwright + JUnit XML）+ `tests/_collect.html`（零依赖浏览器收集器，同口径）；首页 Hero 读 `tests/report.json` 显示通过率。
- **关键修正**：测试页原先把演示页 body 抽成静态 DOM，剥离 `<script>` 后内容为空（演示页 DOM 全靠内联脚本渲染）且缺组件 CSS —— 断言在空 DOM 上跑出的 75.1% 是结构性误报。v1.3.0 改为 iframe 直载真实演示页 + 跨帧断言，基线 960 断言 / 85.1%。
- **落点**：`run_tests.py` 扩展或新增 `run_e2e.py`。
- **对标**：Semi「三种测试 + 90% 覆盖率」的公开证据链。

### C4 · 令牌资源下载 + 静态化 SEO（P2，M）
- **做法**：①设计规范页加「下载令牌包」：css.json → Figma Tokens JSON / W3C Design Tokens 格式 / CSS 变量文件三选一；②`build-site.ps1` 为 79 个组件生成静态 `site/components/<slug>.html` 薄壳（SEO 可爬）+ `sitemap.xml`。
- **对标**：竞品 Figma/Sketch 资源标配；静态化解决 SPA 可爬取性。

---

## 三、内容模块盘点与新增建议

### 现有 10 模块状态（PLAN §2 修订版）

| # | 模块 | 状态 | 备注 |
|---|---|---|---|
| 1 | 品牌与原则 | ✅ | README + 首页 Hero |
| 2 | 设计令牌 | ✅ | 设计规范页 + css.json，缺暗色组与导出 |
| 3 | 组件契约 | ⚠️ 36/79 | 详见问题 3（核心 6 + 输入类 15 + 展示类 15） |
| 4 | 批次映射 | ✅ | index.json schemaVersion 3 |
| 5 | 全量预览 | ✅ | 总览 iframe + 分类/关键词过滤 |
| 6 | 首页/总览/快速开始/设计规范 | ✅ | 四页 + 详情页 |
| 7 | 全局搜索 | ⚠️ | 基础可用，增强未落地（问题 1） |
| 8 | 主题定制器 | ⚠️ | 有，缺预设（问题 7） |
| 9 | 每组件测试页 | ✅ | 79 页 + index + 批量收集器；iframe 真实渲染，基线 85.1%（问题 8） |
| 10 | Changelog/Roadmap | ⚠️ | 仓库文件，未上网（问题 5） |

### 建议新增 6 个内容模块

| # | 新模块 | 落点 | 支撑项目 |
|---|---|---|---|
| 11 | **For Agents / AI 消费入口**（含 llms.txt、契约 schema 说明） | `#/agents` 页 + `site/llms.txt` | A2 |
| 12 | **Playground 在线试玩** | 组件详情页内嵌 | B3 |
| 13 | **站内更新日志 + 组件版本徽章** | `#/changelog` 页 + 组件条目 | A3 |
| 14 | **主题预设库**（主题商店雏形） | theme-panel + presets.json | B4 |
| 15 | **资源下载中心**（令牌包三格式导出） | 设计规范页内嵌 | C4 |
| 16 | **组件交叉引用**（相似/搭配/慎用）+ **FAQ** | 详情页内嵌 | C1、问题 13 |

---

## 四、改造路线图（映射版本）

| 版本 | 内容 | 项目 | 直接效果 |
|---|---|---|---|
| **v1.1.1**（1-2 天，hotfix 性质） | 搜索增强补票 / For Agents + llms.txt / 站内 Changelog + 版本同步 | A1、A2、A3(S) | 消除"声称≠实现"审计硬伤；补上 2026 年竞品标配的 AI 入口与维护信号 |
| **v1.2.0**（1-2 周） | 契约分批补齐（第一批 15 个）/ 暗色令牌映射 / Playground / 主题预设 | B1(批1)、B2、B3、B4 | API 可信度、暗色完整性、可试玩、可换肤四项对齐竞品一线水平 |
| **v1.3.0**（本次） | 验收链路修复（iframe 真实渲染 + 跨帧断言）/ 基座焦点环 / 契约第二批 15 个（展示类） | C3 修正、B1(批2) | 回归数字从误报变可信（85.1% / 960 断言）；契约 36/79；焦点环一次性修 66 页 |
| **v1.4.0**（后续） | 契约第三批（剩余 43 个）、i18n、令牌导出、组件 FAQ、C2 | B1(批3)、C2、C4 剩余 | 形成完整证据链与双语能力，可对外交付 |

### 判断依据（一句话版）
- **先补票再做新功能**：搜索增强是 PLAN/CHANGELOG 声称已交付的，最优先修复。
- **AI 入口是 2026 年的"国际化"**：所有竞品已就位，Aurora 底座现成，半天工作量换一个差异化标签。
- **契约是所有内容模块的地基**：交叉引用、版本徽章、Agent 消费、API 可信度全部依赖它，值得投入最大块时间。
- **Aurora 的零依赖纯 HTML 是劣势也是王牌**：竞品的 Playground 需要打包器，Aurora 用 iframe srcdoc 就能做，B3 的完成度有机会反超。

---

## 五、显式不做（本轮）

- 不引入 npm 依赖 / 不接 Storybook（保持零依赖，PLAN §8 原则）
- 不改 `frameworks/` 源码与 5 端实现
- 不重构 app.js 主体（新功能全部走新增函数/新增数据文件）
- 不做 Figma 源文件（无设计源文件，用令牌导出代替）