root/aurora-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f0e0d7ad1affc1fcda54adccc874c8b67ba60cb8
aurora-admin/现状问题分析与改造清单.md
T
aurora-admin 382ca79b66 v1.4.0: 组件层全面令牌化（设计系统根基修复） 
问题
- 79 个组件的 844 个颜色属性里，只有 2 个（0.2%）引用令牌，
  788 个（93.4%）硬编码 hex
- 后果：改令牌组件不跟着变、主题定制器对组件无效、For Agents 页写的
  「所有色值必须取自 au-* 变量」形同虚设
- 这是本项目第五次「声称≠实现」，且动摇了设计系统的根本

两层令牌化（此前只改了从未被加载的文件，走了弯路）
- 组件样式表 frameworks/*.css：915 处 / 78 文件
- 演示页内嵌 <style>（实际生效的样式层）：287 处 / 51 文件
- 内嵌样式层是决定性的：演示页只 link colors_and_type.css + 自己的 CSS，
  而多数页面把关键样式写在 <style> 块里 —— 只改 CSS 文件不生效

安全策略
- 只替换颜色属性值位置的 hex（color/background*/border*/outline*/fill/stroke）
- 跳过 rgba()/渐变/url() 复合值；不动 SVG 属性与 JS 数据（色板数组）
- 歧义色值按属性语义消解（#FFFFFF 作 color→text-inverse，作 background→card-bg）
- 幂等，可重复运行

补齐令牌语义（71 → 74）
- --au-color-text-tertiary #595959（规范未定义、实现补齐，7.00:1）
- --au-color-text-disabled #BFBFBF（规范定义于组件1/2.txt；WCAG 1.4.3 豁免）
- --au-color-border-strong #F0F0F0（规范未定义、实现补齐）
- 同步 legacy 别名；修复 colors_and_type.css 一处重复注释起始行

修复
- Countdown 首帧空白：setInterval(render, 1000) 首次执行要等 1 秒，
  期间容器为空。改为定义函数后立即执行一次再挂 interval

验证（本轮核心验收）
- 逐组件验证「改令牌 → 元素是否跟着变」：79/79 全部响应
- 过程中修正两处测量方法缺陷（初测 40/79 是误报）：
  ① 选择器 .demo * 在无 .demo 容器的页面抓不到元素
  ② 探针令牌选错 —— Breadcrumb 用 text-tertiary 而只改了 text-body
- CSS 结构完整：158 个文件括号平衡、var(--*) 引用全部有定义
- 回归保持 100%：961 断言 / 0 失败 / 79 页全通过，三次连跑一致
2026-09-11 17:29:30 +08:00

202 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.4.0（本次）**：**组件层全面令牌化** —— 修复「93.4% 颜色硬编码、改令牌组件不变」的根基问题。两层共替换 1202 处（组件样式表 915 + 演示页内嵌样式 287），令牌 71→74；浏览器逐组件验证 **79/79 可换肤**；顺带修复 Countdown 首帧空白。
>
> **v1.3.3**：中英双语落地（`site/i18n.js` 330 条字典 + 顶栏切换 + 偏好持久化），覆盖全部页面；回归时序根治（DensitySwitcher 偶发失败 → 就绪轮询，四次连跑 100%）。
>
> **v1.3.2**：契约第三批 43 份落地，**79/79 全量契约化**；新增令牌导出三格式（CSS / W3C DTCG / Figma Tokens）；规格原文色彩系统同步至 AA 达标值。
>
> 前序：v1.3.0 修复验收链路（测试页原以静态快照断言、剥离 script 后 DOM 为空，75.1% 属结构性误报 → 改 iframe 真实渲染 + 跨帧断言）；v1.3.1 完成无障碍与令牌合规，回归达 **100%**（961 断言 / 0 失败 / 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：契约覆盖 79/79（已闭环）**
- `components/` 目录现有 **79 份契约 JSON**（v1.3.2 补齐第三批 43 份），79 个组件全部契约化，不再依赖 `extractComponentAPI()` 的源码正则启发式。
- 已消除的风险：此前跨 4 端命名差异（H5 class、React camelCase、Vue kebab-case）导致的漏提/错提，现由契约为准、源码扫描兜底。
**问题 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 双语（v1.3.3 已闭环）** — `site/i18n.js` 330 条字典，中文源串作键（未收录自动回退），顶栏 `中/EN` 切换 + `aa-lang` 持久化，覆盖 9 个路由与全部组件详情页。
**问题 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 | 组件契约 | ✅ 79/79 | 全量契约化（核心 6 + 输入类 15 + 展示类 15 + 第三批 43） |
| 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.3.2**（本次） | 契约第三批 43 份（全量 79/79）/ 令牌导出三格式 / 规格色彩同步 | B1(批3)、C4 | 「可被审计」从口号变事实；令牌可被设计工具与其它工程直接消费 |
| **v1.4.0**（后续） | i18n 双语、组件 FAQ、契约 usageHints 驱动的交叉引用增强 | C2、问题 13 | 形成完整证据链与双语能力，可对外交付 |
### 判断依据（一句话版）
- **先补票再做新功能**：搜索增强是 PLAN/CHANGELOG 声称已交付的，最优先修复。
- **AI 入口是 2026 年的"国际化"**：所有竞品已就位，Aurora 底座现成，半天工作量换一个差异化标签。
- **契约是所有内容模块的地基**：交叉引用、版本徽章、Agent 消费、API 可信度全部依赖它，值得投入最大块时间。
- **Aurora 的零依赖纯 HTML 是劣势也是王牌**：竞品的 Playground 需要打包器，Aurora 用 iframe srcdoc 就能做，B3 的完成度有机会反超。
---
## 五、显式不做（本轮）
- 不引入 npm 依赖 / 不接 Storybook（保持零依赖，PLAN §8 原则）
- 不改 `frameworks/` 源码与 5 端实现
- 不重构 app.js 主体（新功能全部走新增函数/新增数据文件）
- 不做 Figma 源文件（无设计源文件，用令牌导出代替）
Reference in New Issue View Git Blame Copy Permalink