refactor(详情页+S8): 详情页减重(导航互斥/入口去重/i18n去重) + 品牌标识入库
Regression / regression (push) Canceled after 0s

本提交含两条并行工作线,因互相咬合(package.json scripts、regression.yml、
npm run build 链)无法按文件干净拆分,故合并为一次自洽提交。

## 详情页减重(本轮主任务:修复「AI 干太重」)

- 导航收敛:宽屏只用右侧目录、≤1200px 只用页内 sticky 导航,纯 CSS 媒体查询
  实现(不引入 JS 宽度监听)。此前两套导航同时可见,active 状态互相打架。
- 入口去重:标题区由「查看示例/在线测试/契约 JSON」三个减为「在线测试」一个;
  契约 JSON 归入实现资源;删除示例底部重复的「在线测试」。
- 示例工具栏:删除与目录锚点重复的示例下拉选择器;「全部展开代码」只在
  示例数 >1 时出现(103 个组件里 49 个仅 1 个示例,此前恒显示)。
- 重复文案:示例区两句同义导语合并为一句。
- 首页 CTA 由 5 个减为 2 个(浏览组件/快速开始),测试总览入口挂到已有的
  通过率统计卡上,不再另占 Hero 按钮。
- 统一详情取数:抽出 fetchDetail/loadDetail 作为 details/*.json 的唯一路径,
  FAQ 不再自行 fetch 一遍,与组件页共用缓存与失败兜底。

## i18n

- 删除 12 组重复键(含整段 FAQ 说明),字典 604 → 585 唯一键。
- 删除本次改动产生的 6 个死键。
- verify-i18n.mjs 新增 `unique dictionary keys` 断言:重复键在对象字面量里
  是静默的后值覆盖,此前无从发现;现由门禁拦住。

## 文档事实修正(实测为准)

- TESTING/CONTRIBUTING:79 → 103 组件;旧断言数改为回指 tests/report.json。
- PLATFORMS:移动端 108 文件/18 端 → 282 文件/47 端;契约 5 → 47;
  令牌 17 → 15;uni-app SFC 21 → 50。
- AGENTS:断言 1405/18 页 → 1464/103 页(PC)、807/47 页(移动端)。
- package.json:YOUR-ACCOUNT 占位 → gitea 实址与 kole-ui.mymoyu.top。

## 品牌标识(并行会话成果,一并入库)

- brand-mark.json 收归真源,build:brand 生成 favicon 与单色 SVG;
  PC 与移动端共用资产,verify:brand 24 条断言。
- regression.yml 增加 verify:brand 步骤。

## 门禁与验收

新增工具:verify-component-page.mjs(86 条真实浏览器断言,随详情页改造同步
更新为「只允许一套导航可见」)、verify-brand-mark.mjs、lib/i18n-dead-keys.mjs
(只读诊断)。

回归:PC 100%(1464/1464,103 页,N/A 50)· 移动端 100%(807/807,47 页)。
门禁:component-page 86 · i18n 17 · brand 24 · routes all · smoke all ·
theme OK · isolation 31 · nav all · examples 9 · api-docs 10 · mobile-docs 12。

已知未做:i18n 另有约 44 条历史死键(非本次产生),已记为 ROADMAP S8-P6;
顶栏与悬浮区的两个主题入口为刻意设计(verify-theme 断言其互斥),未删。
This commit is contained in:
aurora-admin
2026-09-22 23:56:05 +08:00
parent f1fbfc2ddb
commit 5ee5d829a4
92 changed files with 1320 additions and 463 deletions
+31
View File
@@ -1794,3 +1794,34 @@ PC 站控制台错误从 1(favicon 404)降为 **0**。
**过程中踩到的门禁(已修)**:A6「PC 面零移动端目录引用」被 `site/index.html` 的**注释**触发 ——
注释里写了 `site/m/` 字样。这与 AGENTS.md §七「静态门禁把注释当成违规代码」是同一类问题,
本次改写措辞规避(判据未放宽)。
**后续重构(2026-09-22)**:品牌几何已收归 `.design_library/kole-ui/brand/brand-mark.json`,由 `build:brand` 生成独立 favicon 与单色 SVG,两端顶栏复用资产。`verify:brand` 覆盖 24 条断言及 53 个移动文档页;PC 1464/1464、移动端 807/807 各连续 8 轮通过,0 超时。本次仅修改本地工作树,未提交、未部署。
### S8-P5 · 浏览器 theme-color 与手选主题同步 | 优先级 P2 | 待处理
**现状**:`site/index.html` 与 `tools/build-mobile.mjs` 仍输出按系统 `prefers-color-scheme` 选择的两条 `theme-color`。页面手选 `kole-mode` 只切换根元素主题,未同步浏览器 UI 的主题色。K-Node 图形已随页面主题正常变化,此项属于浏览器元信息的既有缺口,不在本次图标重构中顺手修改。
**范围**:PC 解析期主题脚本、`site/app.js` 主题应用入口、移动端 `THEME_BOOT` / `applyMode`,及对应主题门禁。保持三态与现有主题存储键兼容。
**验收**:系统浅色 + 手选深色、系统深色 + 手选浅色、自动模式下系统切换、刷新与跨站入口均断言最终有效的 `theme-color`;执行 `REG_BASE=http://127.0.0.1:<本地实际端口> npm run verify:theme`。反例:仅有根元素 `kole-dark` 正确而有效 meta 仍跟随系统,不得判通过。
### S8-P6 · i18n 字典历史死键清理 | 优先级 P3 | 待处理
**背景(2026-09-22 实测)**:本次「详情页减重」删除了由改动直接产生的 6 个死键(`先体验交互…`、`预览使用 H5 实现…`、`查看示例`、`选择示例`、`复制示例链接`、`测试总览`),字典从 604 条降到 585 个唯一键。用新增的只读诊断 `tools/lib/i18n-dead-keys.mjs` 做全仓库核对后,发现**另有约 44 条历史死键**;它们不是本次改动产生的,按 AGENTS.md「不在原任务里顺手修」留给本任务包:
- 79 组件时期的首页/指南文案(`自动聚合 79 个组件契约里…共 240 条。`、`79 个组件里有 78 个的样式引用…`)
- 已下线入口的文案(`组件 API 规范`、`该组件暂无契约 JSON,API 表由 5 端源码自动提炼`、`API 源码提炼`、`测试页 →`)
- 卡片 unknown/doNot 的历史说明句(`卡片 hover 交互规范` 等整组)
- 设计规范页分组键(`色彩 · 品牌色` 等)—— 这些疑似以 `T('色彩 · ') + name` 拼接消费,工具会单列为 REVIEW 档
**判据**:`node tools/lib/i18n-dead-keys.mjs` 的 DEAD 档清零,且 `verify:i18n` 17 条全过。REVIEW 档必须人工确认后处理,禁止按工具输出批量删。
**风险与反例(本任务实施中真的踩到两次)**:`示例链接`(`app.js` 的 `componentAnchor` 仍在消费)与 `场景示范`(`app.js` 场景列表消费)都曾被工具判为死键并已误删一次,靠复核才发现并恢复。**「键串是否为某个更长字符串的子串」这类启发式不可靠**,删前必须 `grep -F "T('<键>')" site/app.js` 精确核对消费点。反例:仅凭工具输出批量删除,上述两键会被删掉,中英切换后对应位置变空白。
**验收命令**:
```bash
node tools/lib/i18n-dead-keys.mjs # DEAD 档应为 0
npm run verify:i18n # 17 条全过,unique dictionary keys 通过
REG_BASE=http://127.0.0.1:<实际端口> npm run smoke:site
```