aurora-admin
f1fbfc2ddb
Regression / regression (push) Canceled after 0s
## 品牌标识（本次会话） 起因：品牌此前没有任何图形标识 —— 唯一 favicon 是内联 data-URI 里的字母「A」， 那是 v2.0.0「Aurora Admin → Kole UI」改名漏掉的一处（PC 顶栏也是「A」， 移动端站已是「K」；移动端文档站则完全没有 favicon）。 - 几何：24 网格三个互不接触的笔画（竖 + 两斜），圆头描边； 描边 2.25 → 16px 标签页尺寸下正好 1.5px = 规范原文「描边1.5px」 - 取色分两套（刻意）：favicon 硬编码品牌蓝/白（渲染在浏览器标签栏，不继承 kole-dark）； 顶栏标记走 currentColor（实测暗色下自动转 rgb(20,22,28)） - 新增 theme-color 双条（light #FFFFFF / dark #1C1F26，取 --kole-color-card-bg） - 修 site/app.js hero 标语 KOLE ADMIN → KOLE UI（改名变形残留） - 移动端 7 个模板补 favicon（此前计数 0） 验收：门禁 9 条全 OK（site-routing/site-routes/mobile-docs/mobile-site/isolation/ theme/nav/i18n/icons）；PC 回归 1464/1464 · 移动端 807/807，各连跑 8 次一致； 两端 favicon 405 字节逐字节一致；PC 站控制台错误 1→0。 ## 并行会话成果（本次一并入库） - 图标系统：2576 图标（TDesign/Element Plus，MIT）+ 11 端注入 + 5 个构建门禁工具 + IconPreview 预览页 + ICON-SPEC.md 冻结规格 - 移动端平台：47 组件 × 6 端 + 文档站 53 页 + 隔离门禁 - PC 组件：103 个大后台组件 / 组件11 批次 - uni-app：PC 端试点 + 移动端端实现 + 真实编译验证 ## 工程 - .gitignore 补 .scratch/ 与 .zcode-preexisting-*.txt（会话中间产物，实测 9.1MB，不入库） - CHANGELOG 补品牌标识条目 - ROADMAP 登 S8-P4（品牌标识任务包 + og:image/apple-touch-icon 未做部分）
183 lines
9.6 KiB
Markdown
183 lines
9.6 KiB
Markdown
# 任务完成说明 · 图标系统（IconSpec v1）
|
||
|
||
> 冻结规格：`.design_library/kole-ui/icons/ICON-SPEC.md`
|
||
> 完成日期：2026-09-20 ｜ 面向：Kole UI 设计系统（PC 103 组件 / 移动端 47 组件）
|
||
|
||
---
|
||
|
||
## 一 · 验收输出（原样粘贴命令输出，非转述）
|
||
|
||
### 1. 图标系统门禁（11 条断言）
|
||
|
||
```
|
||
$ node tools/verify-icons.mjs
|
||
图标系统静态门禁（ICON-SPEC.md §八）
|
||
真源：registry 2576 · manifest 2576 · 别名 241 · core 151
|
||
PASS V1a manifest 内名字无重复 — 2576 个
|
||
PASS V1b manifest ↔ registry 双向一致 — 2576 个双向对齐
|
||
PASS V1c viewBox 例外表与 manifest 逐条一致 — 253 条例外
|
||
PASS V2 无 view-box 无效拼写残留（§二 修正 1） — 扫描 5 个产物文件
|
||
PASS V3 描边宽度全部 1.5（§二 修正 2）
|
||
PASS V4 core 层图标可渲染出非空 SVG — 151 个
|
||
PASS V4b core 计数自洽 — coreCount=151 / 实际 151
|
||
PASS V5 别名全部指向真实图标且不遮蔽（§三 3.2） — 241 条
|
||
PASS V6 各端 name 查找均能落到 registry（9 个端已注入）
|
||
PASS V7 分组覆盖率 ≥ 75%（§八 第 7 条） — 82.2% · 12 个分组 · 未分组 459
|
||
PASS V8 路径数字与源逐值一致（防隐式分隔粘连） — 比对 2576 个同源同名图标
|
||
|
||
未执行：把 core.js / aliases.json 重新从上游拉取核对（需联网，见 tools/fetch-icon-sources.mjs）
|
||
|
||
────────────────────────────
|
||
[OK] 图标系统门禁全部通过（11 条断言 · registry 2576 图标）
|
||
EXIT=0
|
||
```
|
||
|
||
### 2. 回归（八次连跑一致，铁律 §六）
|
||
|
||
```
|
||
$ REG_BASE=http://127.0.0.1:3401 node tools/run-regression.mjs # ×8
|
||
run 1..8: passRate 100% | pages 103 (all-pass 103) | assertions 1464/1464 | N/A 50
|
||
|
||
$ REG_BASE=http://127.0.0.1:3401 node tools/run-mobile-regression.mjs # ×8
|
||
run 1..8: passRate 100% | pages 47 (all-pass 47) | assertions 807/807 | N/A 10
|
||
```
|
||
|
||
### 3. 全部门禁（17 个脚本直接调用，exit code 实测）
|
||
|
||
```
|
||
verify-icons exit=0 verify-cross-platform exit=0
|
||
verify-mobile-isolation exit=0 verify-families exit=0
|
||
verify-uniapp exit=0 verify-versions exit=0
|
||
verify-uniapp-build exit=0 verify-runtime-e2e exit=0
|
||
verify-mobile-docs exit=0 verify-theme exit=0
|
||
verify-mobile-site exit=0 verify-nav-responsive exit=0
|
||
verify-playground exit=0 verify-dark exit=0
|
||
verify-examples exit=0 verify-api-docs exit=0
|
||
verify-i18n exit=0
|
||
```
|
||
|
||
### 4. 浏览器实测（Chromium，真实渲染）
|
||
|
||
```
|
||
PC frameworks/Icon.html : 48 个 SVG 全部有 path，0 空；stroke-width 集合 = ['1.5']；view-box 残留 0；控制台错误 0
|
||
Mobile frameworks-mobile/Icon.html : 344 个 SVG 全部有 path，0 空；stroke-width = ['1.5']；类名全部 kole-m-* 前缀；控制台错误 0
|
||
全部 2576 个图标逐个渲染 : 产生控制台错误的图标 = 0
|
||
icon-preview.html : cells 2576 / rendered 2576；搜索 "search" → 24 个；控制台错误 0
|
||
```
|
||
|
||
### 5. 兼容性实测
|
||
|
||
```
|
||
移动端历史 9 名字形表：check/close/star/plus/minus/more → 命中 canonical；warn→warning、info→info-circle、arrow→chevron-right
|
||
Element UI 282 个历史图标名 : 280 可解析（余 2 个 `-left`/`-right` 是解析碎片，显式标记忽略）
|
||
PC 历史 icon prop（字形字符 '★'） : 保留，name 优先
|
||
```
|
||
|
||
### 6. 离线可复现（移走缓存后重建）
|
||
|
||
```
|
||
$ mv .cache-icons /tmp/cache-backup && node tools/build-icons.mjs && node tools/verify-icons.mjs
|
||
图标总数 2576 ... OK
|
||
[OK] 图标系统门禁全部通过（11 条断言 · registry 2576 图标）
|
||
```
|
||
|
||
---
|
||
|
||
## 二 · 覆盖度（对用户点名的参考库）
|
||
|
||
| 参考库 | 图标数 | 本仓库覆盖 | 结果 |
|
||
|---|---|---|---|
|
||
| TDesign Icons（线性 + 面性） | 2356 | 2356 | **100%** |
|
||
| Element Plus Icons | 293 | 293 | **100%** |
|
||
| Element UI Icons（历史名，字体图标） | 282 | 280 | 99.3%（余 2 个是解析碎片名） |
|
||
| **合计入库** | | **2576** | |
|
||
|
||
参考组件的图标功能对齐（用户点名）：
|
||
|
||
| 上游组件 | 图标相关能力 | 本仓库 |
|
||
|---|---|---|
|
||
| TDesign `TabBar` / `TabBarItem` | `icon`、`badgeProps`（图标角标）、`subTabBar` | 图标提供 `name`；角标由既有 `Badge` 承担（既有设计，未改） |
|
||
| Element UI `PageHeader` | 返回箭头、标题/副标题、`extra` | 图标提供 `back`/`chevron-left`/`arrow-left` 三个语义名 |
|
||
| TDesign `Icon` | `size` 支持关键字**与任意 CSS 值**、`onClick`、class/style 透传 | `size` 双模式；`onClick` 由端上事件承担 |
|
||
|
||
---
|
||
|
||
## 三 · 改动文件
|
||
|
||
### 新增（构建/门禁工具 5 个）
|
||
- `tools/fetch-icon-sources.mjs` — 上游拉取 + 归一化（sha256 钉死；纯函数可无副作用 import）
|
||
- `tools/build-icons.mjs` — 编译 manifest / registry / viewbox / core.js / ATTRIBUTION.md
|
||
- `tools/build-icon-aliases.mjs` — 别名层（Element UI 282 名 + 移动端 9 名）
|
||
- `tools/inject-icon-table.mjs` — 把 core 表注入 11 个端（支持 `--check` 幂等校验）
|
||
- `tools/verify-icons.mjs` — 11 条静态断言
|
||
|
||
### 新增（数据产物，全部入库）
|
||
- `.design_library/kole-ui/icons/`（`ICON-SPEC.md` / `ATTRIBUTION.md` / `manifest.json` /
|
||
`registry.json` / `sources.json` / `core.js` / `viewbox.js` / `aliases.json` / `element-ui-names.txt`）
|
||
- `site/icons.json`（文档站轻量索引）、`site/icon-preview.html`（图标预览页）
|
||
|
||
### 修改（端实现 11 个）
|
||
- `frameworks/Icon.{html,jsx,vue2.vue,vue3.vue,css}`
|
||
- `frameworks-mobile/Icon.{html,jsx,vue2.vue,vue3.vue,uniapp.vue,css}`
|
||
|
||
### 修改（站点与文档）
|
||
- `site/app.js`（图标组件页挂「图标预览」入口）、`site/i18n.js`（+2 条双语）、
|
||
`package.json`（+3 个 script）、`CHANGELOG.md`、`ROADMAP.md`（+3 个衍生任务包）、`.gitignore`（忽略 `.cache-icons/`）
|
||
|
||
---
|
||
|
||
## 四 · 规划偏差
|
||
|
||
| ROADMAP/任务书写的 | 实际的 | 原因 |
|
||
|---|---|---|
|
||
| 「覆盖他们全部拥有的 icon」预期一次性实现 | 分两层：**全部 2576 个入库**，其中 **151 个 core 内联**、其余按需加载（standard 1993 / extended 432） | 实测全量路径数据 670KB；全内联等于每页 +670KB，违背性能预算。分层是缩量不缩覆盖 —— 2576 个全部可渲染 |
|
||
| `frameworks/Icon.css` 作样式端应含图标表数据 | 数据端是 4 个（html/jsx/vue2/vue3），css 不含数据 | 注入器的 `FILES` 表不含样式文件；样式来源是 CSS 令牌而非图标表 |
|
||
| 计划用「11 个端各抄一份表」 | 改为单一真源 + 注入标记块 | 11 份手抄必然漂移，且漂移**不报错**（表现为某端图标空白） |
|
||
|
||
---
|
||
|
||
## 五 · 发现的新问题
|
||
|
||
### 已在本任务内修复（自测发现，非外部报告）
|
||
|
||
1. **构建期把坐标改错（数据损坏，静默）**
|
||
`q-13.005.48-22.5` 是三个数（`-13.005`、`.48`、`-22.5`，SVG 允许隐式分隔）。
|
||
把 `-13.005` 舍成 `-13` 后，后面的 `.48` 粘成 `-13.48` —— 另一个坐标，图形画错且不报错。
|
||
实测踩到 Element Plus 的 `quartz-watch`。
|
||
**修法**：有小数位的数输出至少留 1 位小数；`optimizePath` 内复核数字序列。
|
||
**防复发**：新增门禁 **V8**，并做**变异测试**（重新注入该 bug → V8 FAIL `数字个数 461 ≠ 源 462`）。
|
||
|
||
2. **非 `<path>` 图形被静默丢弃**
|
||
解析器只认 `<path d>`，而上游 36 个文件用 `<circle>` / `<ellipse>`（TDesign 的
|
||
`circle` / `round` / `brightness` / `image` 等）。这些图形被丢弃，图标"渲染成功"却是空的。
|
||
**修法**：解析 circle/ellipse 并换算成 path arc。
|
||
**结果**：2574 → 2576 个图标，TDesign 覆盖升至 100%。
|
||
是**覆盖率审计**（对三家参考库逐名比对）发现的，不是回归 —— 回归测不出"少了一个图标"。
|
||
|
||
### 登记为 ROADMAP 衍生任务包（不在本任务顺手修，遵守 §三「禁止范围蔓延」）
|
||
|
||
- **`S8-P1`** `verify-emits-parse.mjs` 的文件数期望值陈旧（硬编码 158 = 79×2，实际 103×2=206）。
|
||
**本次之前就存在**（`git show HEAD:` 确认该文件 HEAD 上就是 158，本任务未触碰）。
|
||
- **`S8-P2`** `verify-cross-platform.mjs` 把注入的图标数据表误判为组件类名（540 条 diff 里 533 条是噪声）。
|
||
是冻结规格「数据内联进端文件」的必然结果 —— 修法是让门禁学会跳过数据块，**判据不放宽**。
|
||
- **`S8-P3`** `组件5.txt` 声明的 47 个工具/模板组件里 **46 个从未实现**（本次只补了 IconPreview）。
|
||
含一个需要用户拍板的决策点：**这批组件走 `frameworks/` 正式组件（103 → 149，全部门禁基线跟着动）
|
||
还是 `site/` 工具页**（本次 IconPreview 走的是后者）。
|
||
|
||
---
|
||
|
||
## 六 · 遗留阻塞（不隐瞒）
|
||
|
||
| 项 | 状态 | 说明 |
|
||
|---|---|---|
|
||
| mp-weixin / app-plus 的**遮罩渲染** | **未验证** | uni-app 端用 CSS mask 承载字形（小程序无 DOM/内联 SVG）。H5 目标已实测（着墨率 0.052 vs 无遮罩 1.000）；小程序端需真机或开发者工具复核，仓库门禁只覆盖静态与编译。已登记进契约 `unknowns` |
|
||
| `verify-emits-parse` | 1 条既存 FAIL | 见 `S8-P1`，非本任务引入 |
|
||
| 组件5 的 46 个组件 | 未实现 | 见 `S8-P3`，需先定第 5 节那个决策点 |
|
||
|
||
---
|
||
|
||
## 七 · 回归结论
|
||
|
||
**PC 100%（1464/1464，103 页）· 移动端 100%（807/807，47 页）· 八次连跑一致 · 0 超时**
|
||
**17 个门禁脚本全部 exit=0**（唯一 FAIL 是既存的 `verify-emits-parse`，已证明非本任务引入）
|