# 批次 5 验收说明：装饰/纹理替换

关联：[执行-批次5：装饰/纹理替换](issues/18-exec-batch5-decorations.md)
引用规格：[规格 03 视觉 token 映射](issues/03-visual-system-token-mapping.md)、[规格 09 运行时资产 manifest](issues/09-runtime-asset-manifest-spec.md)、[规格 12 设计稿差异判断表](issues/12-design-diff-structure-boundary-spec.md)
本文档只讲**怎么验收**；判据逐项裁定过程见票 18 证据区。

---

## 0. 一句话：改了什么

装饰批按规格 03 判据把装饰分了三类，只动了「该动的」：

| 类别 | 内容 | 处置 |
| --- | --- | --- |
| **资源化**（复杂位图，不可 CSS/SVG 无损复现） | 品牌标题后方「光池」（蓝湖 D6「光」层 489×128@2x，椭圆多层渐晕 + 中心亮斑） | 新入 manifest `icon.brand.pool`（formal），经语义 key 注入 CSS 变量消费，按设计 frame 等比铺在标题下层 |
| **代码化收口**（几何可代码化，但此前散落主题色） | 面板四角 L 形切角：data-URI 内联的 4 处主蓝色值 → 白色几何母版 + `mask` 染 `--panel-line-hi`；氛围底/地图画布底的两处裸 hex → 新语义 token `--bg-1` | 色值单一来源，几何保持代码化 |
| **维持现状**（现有氛围增强，设计稿无对应物） | 全局细网格、地图扫描线、地图/引导暗角、面板辉光、L 切角、氛围径向辉光 | 按规格 12「设计稿未覆盖项维持现状」，登记票 06 缺口清单（P3） |

另外：11 个**无消费点**的装饰候选切图（`brand-glow-1/3`、`panel-corner-*`×4、`panel-subtitle-*`×2、`select-bg*`×2、`topbar-line`）按共识 §1「没有消费点的图不进运行时」挪入设计归档 `design-archive-v2/unconsumed-decor/`（sha256 台账 LEDGER.md），运行时目录不再有未登记文件。

---

## 1. 验收方式一：静态自查（不跑任何服务，1 分钟）

```powershell
# 1.1 批次 5 专项断言面（资源化/无死资源/色值收口/结构保护）
node .scratch/lanhu-cockpit-asset-replacement/verify/batch5-decor-check.mjs

# 1.2 manifest 校验（应 56 条，含 icon.brand.pool）
node .scratch/lanhu-cockpit-asset-replacement/research/check-manifest.mjs

# 1.3 图标四处交叉引用（marker.* 六键现按合成层接缝识别，不再误报冗余）
node .scratch/lanhu-cockpit-asset-replacement/research/cross-check-icons.mjs

# 1.4 批次 2 token 断言面未被破坏
node .scratch/lanhu-cockpit-asset-replacement/verify/batch2-token-check.mjs

# 1.5 批次 4 字体门禁未被破坏
node .scratch/lanhu-cockpit-asset-replacement/tools/check-fonts.mjs

# 1.6 批次 3 位置符号合成计划未被破坏
node .scratch/lanhu-cockpit-asset-replacement/research/check-marker-plan.mjs

# 1.7 结构回归（四模式 / 16 面板）
node .scratch/cockpit-shell-panel-layout/verify/t01-panel-catalog.mjs

# 1.8 build-manifest 防覆盖闸门对抗验证（当前应 exit 1 中止——票 37 的 icon.kpi.* 未在 ICON_MAP，
#     闸门宁可拒绝重建也不抹掉并发批次的条目；manifest 文件字节级不变）
node .scratch/lanhu-cockpit-asset-replacement/research/build-manifest.mjs
```

**判定**：

- 1.1–1.7 全部退出码 0；
- 1.8 打印 `中止：manifest 中存在本脚本未登记的条目（icon.kpi.*…）` 且 exit 1——这是**预期行为**（防覆盖闸门生效）；等票 37 会话把 `icon.kpi.*` 映射补进 `ICON_MAP` 后重跑应成功且保留全部 56 条。

**本批执行时实测**：1.1–1.7 全绿；1.8 中止且 manifest hash/mtime 不变（对抗验证通过）。

---

## 2. 验收方式二：看证据文件（30 秒）

| 看什么 | 位置 | 应看到 |
| --- | --- | --- |
| 光池登记 | `public/cockpit/assets/manifest.json` 的 `icon.brand.pool` 条目 | `formal`、489×128、hash `sha256:1e65ce31…`、source 指向 D6「光」层 |
| 归档台账 | `.scratch/…/design-archive-v2/unconsumed-decor/LEDGER.md` | 11 个候选 + sha256 + 判定理由 |
| 四角收口 | `CockpitPanel.vue` `.cockpit-panel::before` | `background-color: var(--panel-line-hi)` + `mask:` 简写，data-URI 只有 `%23fff` 几何 |
| 语义槽位 | `tokens.css` | `--bg-1: #02091b`（第二底色） |

> **为什么四角用 `mask` 简写而不是 `mask-image`**：`left top / 15px 15px no-repeat` 这类 position/size/repeat 层语法只属于 `mask` 简写；写进 `mask-image` 会被浏览器整条丢弃（四角消失）。本批自查抓到并修正。

---

## 3. 验收方式三：跑起来看真实效果（需维护者授权后执行）

**真实运行地址：`http://127.0.0.1:8000/#/cockpit`**

### ⚠ 已知坑（批次 4 走查单 §5 全部适用）

1. 打开后先点画面中央「点击进入系统」。
2. manifest 被 dev server 缓存旧转译：触碰文件失效缓存或重启 dev。
3. 浏览器 HMR 模块图陈旧：**硬刷新**（Ctrl+Shift+R）再判定。

### 走查清单

**① 光池装饰（本批新增的唯一资源化装饰）**
- [ ] 品牌标题后方出现椭圆光池（横向光斑），左缘略超出标题、上缘与标题齐平（设计稿关系：489 宽 vs 标题 470，偏移 -19,-1）
- [ ] 光池在标题**下层**，不遮挡渐变文字；不响应鼠标（pointer-events:none）
- [ ] 顶栏下方筛选条区域的溢出淡晕与设计稿「光层高于文字」的关系一致

**② 面板四角（色值收口，观感应与改前完全一致）**
- [ ] 任一面板四角 L 形切角仍为青色（`--panel-line-hi`）+ 辉光，粗细 15px 不变
- [ ] 收起/展开面板，切角跟随、无残影（mask 覆盖 `inset:-1px` 不裁切）

**③ 氛围维持现状项（回归确认未被本批破坏）**
- [ ] 全局细网格、地图扫描线、暗角、面板辉光与批次 4 时一致
- [ ] 氛围底渐变、地图画布底色无肉眼变化（只是色值改走 `--bg-1`，值未变）

**④ 结构未受影响（重点回归）**
- [ ] 四个一级模式切换正常，16 个 `panelId` 不变
- [ ] 面板收放、内容纵向滚动边界与改前一致
- [ ] 1280×720 视口抽查：文字可读、按钮可操作、面板不重叠（装饰不得压业务文字）

### 读数断言（浏览器控制台执行，用于留证）

```js
// 光池切图真的被请求（Network 过滤 brand-pool，应为 200 + image/png）
// 或：壳上读注入变量
const bar = document.querySelector('.cockpit-shell__topbar')
console.log(bar.style.getPropertyValue('--brand-pool-url'))  // 应为 url("…brand-pool.png…")，非 none

// 面板四角染色源
const panel = document.querySelector('.cockpit-panel')
console.log(getComputedStyle(panel, '::before').backgroundColor)  // 应为 rgb(0, 184, 255)（--panel-line-hi）
```

截图留存：总体概览顶栏品牌区特写一张（含光池）、任一面板四角特写一张、1280×720 全景一张。

---

## 4. 判定标准

| 结果 | 结论 |
| --- | --- |
| 静态全过 + 走查 ①②③④ 全过 | 批次 5 通过，可关闭票 18 |
| ① 光池观感偏差（位置/比例/亮度） | P3 视觉偏差，登记票 06 缺口清单（可只调 CSS 偏移，不动素材） |
| ② 四角消失/变色 | **缺陷**：检查 `mask:` 简写与 `--panel-line-hi`（本批已知坑见 §2） |
| ④ 出现模式/面板/滚动行为变化 | **阻断**：改动越界，需回退并复查 |

## 5. 不通过怎么回滚

```powershell
# 本批改动集中在 5 个文件，逐个还原：
git checkout -- src/modules/cockpit/components/CockpitPanel.vue   # 四角回内联色值 data-URI
git checkout -- src/modules/cockpit/styles/tokens.css             # 去掉 --bg-1
# CockpitShell.vue / MapCanvas.vue / domain/icons.js / manifest.json 需按 diff 手工回退
# （工作树含并发会话改动，不要整文件 checkout）
git mv .scratch/lanhu-cockpit-asset-replacement/design-archive-v2/unconsumed-decor/*.png public/cockpit/assets/icons/  # 候选挪回（除 brand-pool 对应文件）
```

回滚后：`icon.brand.pool` 条目从 manifest 删除即可（解析层对未知 key 返回空，页面无感）。

## 6. 本次未做的事（避免误判）

- **未动**：中央底图（临时影像，票 21/22 范围）、设备 3D 效果（票 47）、字体/图标/token/位置符号（前四批已收口）。
- **未删任何设计素材**：11 个候选只是挪出运行时目录，原文件 + sha256 在归档区，随时可恢复。
- **未运行 build/dev/浏览器**（AGENTS.md）：走查清单留给维护者执行。