# 任务完成说明 · 图标系统（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`，已证明非本任务引入）