# 13: 分批替换与终稿验收规格

Type: spec
Status: resolved
Label: ready-for-agent
Blocked by: 08
Category: spec

## 终稿验收执行记录（2026-10-15，维护者明确授权运行）

**报告**：[终稿验收报告](final-acceptance-report.md)（六项报告齐备）。

**执行环境**：真实 `/cockpit` @ `http://127.0.0.1:8000/#/cockpit`，视口经设备度量精确设为 **1280×720 CSS px**，硬刷新后进入系统。

### 已达成

- **全部断言面 6 套全绿**：`batch2-token-check` 10/10、`batch5-decor-check` 11/11、`check-manifest`（56 条 + hash/可达性）、`cross-check-icons`（四处交叉引用一致）、`check-marker-plan` 38/38、`check-fonts`（5 条目/7 许可 + 门禁 + 对抗式反证）、`t01-panel-catalog`（4 模式/16 面板/基址解析）。
- **四个一级模式逐一走查通过**（overview / infrastructure / monitoring / warningResponse），每模式 4 面板齐备、两栏 + 中央一张图、8 行状态图例常驻、DOM overlay 标记可见、1280×720 下无重叠。
- **运行时实测**：字体 **5/5 全部加载**（符合「字体请求为 0 必判 FAIL」纪律）；**404 = 0**（1727 次请求）；**控制台业务报错 = 0**；数据源 `real`。
- **临时素材关闭清单核对完成**：核心资源组（品牌标识 / 点位设备状态形状语义 / 状态色语义）**全部换正式素材**；`icons.js` 已无内联 SVG 几何；仅 `icon.blank` 为 `temporary`（`core:false`，设计稿未覆盖，P3，不阻断）。
- **缺陷分级**：P0 = 0、P1 = 0、P2 = 0、P3 = 11（全部已登记票 06 缺口清单）。

### 未闭合（本票保持 open，不关闭）

1. **qiankun 宿主验收无法执行（环境前置缺失，非实现缺陷）**：实测仓库内外**均无可运行的 qiankun 宿主工程**——仓库内仅被嵌侧适配代码 `src/.fes/plugin-qiankun/micro/*.js`，`E:\`/`D:\` 顶层扫描未发现宿主工程。已覆盖部分：`resolveCesiumBaseUrl()` 对 `__INJECTED_PUBLIC_PATH_BY_QIANKUN__`、根相对基址、默认基址的三条断言在 `t01-panel-catalog.mjs` 中全绿；资源引用全走 `import.meta.env.BASE_URL`、无硬编码路径。未覆盖部分：规格 13 要求的「宿主内真实走查 + 单独签收」——**无宿主可走查，不由代理伪造**。
2. **维护者签收待人工完成**：六项报告与全部证据已备齐（见报告 §1–§6），签收是人工动作，代理不得代签。

### qiankun 宿主验收补做结果（2026-10-15，维护者指示「尝试去补一下」）

**已补做**：自建最小宿主（`qiankun@2.10.16` UMD 离线加载 `http://127.0.0.1:8000/`），宿主文件留档于 `qiankun-host-acceptance/`，**已从 `public/` 清理、未污染构建产物**。

- **通过**：宿主加载并挂载被嵌应用（appName `TvT.js`）；**基址注入生效**（`__INJECTED_PUBLIC_PATH_BY_QIANKUN__` = `http://127.0.0.1:8000/`）；cockpit 模块图（`CockpitShell.vue` / `MapCanvas.vue` / `PanelBlocks.vue` / `markerPlan` 等）**全部 200，无 404、无硬编码路径**。
- **未通过（宿主集成既有问题，非本图缺陷）**：宿主内 `/cockpit` 未渲染，报 `TypeError: Cannot read properties of undefined (reading 'push')` at `src/.fes/plugin-qiankun/micro/runtime.js:26`。根因是该文件解构 `{ router, history }` 但 FES 4 的 `onRouterCreated` 契约只保证 `router`；该文件 `git status` 无本地改动，属仓库既有宿主集成问题，**不在本图素材替换范围**。

**因此规格 13 要求的「宿主内验证资源解析与基址注入」已执行并通过**；「宿主内完整 `/cockpit` 走查」因上述既有问题未完成，作为**独立事项**记录，不由本图修复或掩盖。

### 一处范围澄清（不属未关闭临时项）

`public/cockpit/aerial.webp` 仍被 `MapCanvas.vue:119` 引用为临时底图，但票 01/02 与 `public/cockpit/README.md` 均明确「真底图/瓦片归票 21/22」，**不属本图素材替换范围**，故不计入未关闭临时项。

### 收口（2026-10-15，维护者确认）

- 维护者确认**签收**终稿验收；
- 维护者指示：**票 09–12 可关闭**，且**已存 spec 共识须总结提取留档**——已产出 [项目共识与经验留档](CONSENSUS.md)；
- 维护者确认**可以关闭地图**。
- 本票置 `Status: resolved` 并关闭；`Blocked by` 与验收证据保留在票面与[终稿验收报告](final-acceptance-report.md)。

本规格固化[分批替换与终稿验收方案](08-batch-and-final-acceptance.md)的讨论结论，作为同一张蓝湖正式素材替换地图的子规格单。100% 仅表示规格交付，**不表示任何批次已实施**。本规格同时定义 5 张执行票（14–18）的格式与验收清单；它们随本规格同步发布、挂同一张地图，是实施阶段的可认领入口。

## Problem Statement

素材替换的全部规则已分散锁定在四张规格里（视觉 token、运行时 manifest、位置符号、字体授权），但没有一条组织好的实施路线：先做哪批、每批怎么进、怎么验收、证据放哪、什么时候能宣布「临时素材已关闭」。

没有这条路线会出现四种失败：实施者各自为政地并行替换，结构越界到终稿才发现（没有入口闸）；验收无据可查（没有签收载体）；偏差散落在对话里（没有单一缺口来源）；临时素材无限期滞留（没有关闭判据）。同时，蓝湖画板的逐项盘点尚未完成，冲突可能在批次中途才暴露，需要一个不阻塞批次的处置闭环。

## Solution

按资产类别把实施路线拆成 5 张可认领的执行票：品牌/图标、面板视觉 token、地图/设备位置符号、字体、装饰/纹理。每张执行票自带：

- **进入自查**：素材已入库且过 manifest 校验；用差异判断表把该批差异分类（结构项暂停升级、视觉项放行）。
- **验收清单**：实现者自测（纯逻辑断言、宿主读数、结构回归）+ 维护者走查（真实 `/cockpit` 人工走查并签收）。
- **证据区**：走查单、截图、`data-*` 读数、缺口登记，全部写进执行票本身。

批次依赖：位置符号批依赖 token 批（外层母版着色），装饰批最后叠放；品牌/图标、token、字体三批可并行。

终稿验收出**六项报告**（各批走查单、对照截图、缺口清单现状、临时素材关闭声明、待设计方确认偏差清单、缺陷分级汇总），在真实 `/cockpit` 与 qiankun 宿主**分开签收**，并做 1280×720 视口检查。缺陷分 P0–P3 四级，仅 P0（复用票 06 三类阻断判据）阻断发布。临时素材关闭以**逐项清单**留痕并由维护者签收。

## User Stories

1. 作为实现者，我想每批是一张可认领的执行票，以便清楚知道这一批做什么、验什么。
2. 作为实现者，我想三张独立批次（品牌/图标、token、字体）可并行认领，以便缩短总周期。
3. 作为实现者，我想位置符号批在 token 批完成后才解锁，以免在色值未定时返工。
4. 作为实现者，我想装饰批在前面四批完成后才解锁，以免叠放次序错乱。
5. 作为实现者，我想每张执行票自带进入自查清单，以便开工前就知道素材是否齐备、差异是否越界。
6. 作为实现者，我想进入自查包含 manifest 校验，以免拿到不完整或错误版本的素材。
7. 作为实现者，我想进入自查包含差异判断表分类，以便结构差异在开工前被拦下而不是实现完才发现。
8. 作为实现者，我想判断表判定为结构的差异立即暂停并升级新票，以便不由我擅自改契约。
9. 作为实现者，我想判断表判定为视觉的差异放行进批次，以便不被无谓升级拖慢。
10. 作为实现者，我想每张执行票自带该批验收清单，以便验收不靠感觉。
11. 作为实现者，我想验收清单引用对应规格的断言面，以便不自造第二套验收标准。
12. 作为实现者，我想验收先跑纯逻辑断言与宿主读数，以便可回归的部分自动化。
13. 作为维护者，我想每批由我走查真实 `/cockpit` 后签收，以便观感与真实环境由人确认。
14. 作为维护者，我想签收附带走查单与截图/读数证据，以便批次关闭有据可查。
15. 作为维护者，我想归视觉的偏差在签收前登记进缺口清单，以便每批有独立可追溯的偏差闭环。
16. 作为维护者，我想批次验收结论注明已登记的缺口数，以便一眼看到该批遗留。
17. 作为值班人员，我想每批替换后驾驶舱仍可用，以便批次化不破坏值守。
18. 作为值班人员，我想非核心资源失败时按既有回退链降级，以便单批问题不拖垮整页。
19. 作为验收人员，我想终稿验收报告包含各批次走查单，以便逐批复核。
20. 作为验收人员，我想报告包含设计稿与 `/cockpit` 的对照截图，以便视觉差异可并排比对。
21. 作为验收人员，我想报告包含缺口清单现状，以便知道哪些项带回退交付。
22. 作为验收人员，我想报告包含临时素材关闭声明，以便知道核心资源是否全部换新。
23. 作为验收人员，我想报告包含待设计方确认的偏差清单，以便交接时有明确的确认项。
24. 作为验收人员，我想报告包含 P0–P3 缺陷分级汇总，以便阻断项清零一目了然。
25. 作为验收人员，我想真实 `/cockpit` 与 qiankun 分开走查、分开签收，以便两个环境的覆盖范围不互相掩盖。
26. 作为验收人员，我想 qiankun 环境专门验证资源解析与基址注入，以便嵌入宿主的资源问题被单独确认。
27. 作为验收人员，我想 1280×720 视口下逐面板检查不重叠、可读、可滚动，以便最小宽度承诺兑现。
28. 作为验收人员，我想 1280px 检查附断言截图，以便宽度检查有证据而非口头。
29. 作为维护者，我想 P0 缺陷复用票 06 的三类阻断判据，以便阻断标准全图一致。
30. 作为维护者，我想 P3 装饰偏差入缺口清单后即可发布，以便非核心瑕疵不卡死交付。
31. 作为维护者，我想装饰批走完整流程但阻断级放宽，以便装饰替换仍被验收却不拖住主线。
32. 作为维护者，我想临时素材关闭以逐项清单留痕（原素材 → 新素材 → 状态），以便「关闭」可审计而不是一句总结。
33. 作为项目负责人，我想地图在决策收口后保留为实施索引，以便决策历史与实施入口都在一处。

## Implementation Decisions

- **批次划分**：5 张执行票按资产类别——品牌/图标、面板视觉 token、地图/设备位置符号、字体、装饰/纹理；与各规格一一对应，每批直接引用对应规格验收面。
- **批次依赖**：位置符号批 `Blocked by` token 批；装饰批 `Blocked by` 前四批；品牌/图标、token、字体三批互不阻塞、可并行。依赖用执行票的 `Blocked by:` 字段表达。
- **执行票格式**：每张执行票含——批次范围、进入自查（manifest 校验 + 判断表分类）、引用规格、验收清单、证据区（完成后填写）、Out of scope。
- **规格引用而非复制**：执行票引用对应规格子票作为单一决策事实来源，不重抄规格内容；验收清单只列「本批要跑的断言面与走查项」。
- **进入条件**：素材已入库且过 manifest 校验（存在、hash、fallback 齐全）+ 该批类别已有可执行验收清单。
- **判断表入口**：每批开始时用差异判断表把该批差异分类——结构项立即按升级路径暂停并另立新决策票，视觉项放行进批次实施。
- **验收双轨**：实现者自测（纯逻辑断言、宿主 `data-*` 读数、结构回归）+ 维护者走查（真实 `/cockpit` 人工走查并签收）。
- **签收证据**：走查单逐项勾选 + 真实 `/cockpit` 截图或 `data-*` 读数，写进执行票本身；不另建「批验收记录」第二来源。
- **偏差登记**：归视觉偏差在批次签收前写入票 06 缺口清单（语义 key、缺口类型、回退结果、责任人）；批次验收结论注明已登记缺口数。
- **缺陷分级**：P0 阻断（核心资源缺失/状态语义误导/授权风险，复用票 06 三类判据）；P1 高（1280px 不可读/位置符号不可辨/锚点错位）；P2 中（观感偏差/性能不达标）；P3 低（非核心装饰偏差，入缺口清单后可发布）。
- **装饰批放宽**：批次 5 走完整验收流程，但装饰不属核心资源组，其偏差只进缺口清单（P3），不阻断后续与终稿。
- **终稿验收报告**：六项——① 各批次走查单（含截图/读数）② 设计稿 vs `/cockpit` 对照截图 ③ 缺口清单现状（含未替换临时项）④ 临时素材关闭声明 ⑤ 待设计方确认偏差清单 ⑥ P0–P3 分级汇总。
- **双环境签收**：真实 `/cockpit`（全功能全观感）与 qiankun 宿主（资源解析与基址注入）分别走查、分别签收；predev 预演环境不纳入（布局差异不属本图验收）。
- **1280px 检查**：真实 `/cockpit` 视口切 1280×720，逐面板确认不重叠、可读、可滚动，记录断言截图。
- **临时素材关闭**：判据 = 核心资源组全部换正式素材 + 缺口清单中无「临时素材仍在使用」条目；非核心装饰留临时项时在缺口清单显式登记「未替换」。最终证据 = 终稿报告中的逐项关闭清单（原临时素材 → 新正式素材 manifest 条目 → 状态：已替换/已删除/登记未替换），由维护者签收。
- **地图终态**：决策票全部收口后，地图保留为实施索引（开放状态），执行票是可认领入口；不因决策完成而关闭或删除地图。

## Testing Decisions

- 好测试只断言可观察事实，不假装自动判定观感或越界。
- **可断言的三件外围事实**：① 执行票开工时是否附 manifest 校验通过与判断表自查记录；② 批次关闭时是否附走查单与截图/读数及维护者签收标记；③ 偏差是否只出现在票 06 缺口清单。三者缺任一即该批验收不成立。
- **每批结构回归**：既有断言面（四模式、16 个 `panelId`、状态词表冻结、图例与标记一致）全绿是每批的前置；任何一批引入结构变化即失败。
- **批次专项断言**：品牌/图标批跑图标注册表与引用走查（未知图标不抛错）；token 批跑无裸色值静态检查与主画板对照；位置符号批跑合成计划纯逻辑断言（母版归属、尺寸层级、锚点比例、内层比例、图例同源）与锚点迁移断言；字体批跑授权证据齐全性与回退链断言；装饰批跑资源引用走查。
- **走查层**：每批维护者走查真实 `/cockpit`；终稿在真实环境与 qiankun 分别走查并分别签收；1280×720 视口逐面板检查附截图。
- **锚点迁移的对抗式要求**：位置符号批把锚点从中心改为尖端后，既有按中心口径建立的断言必须同步更新，且更新后的断言须以对抗方式确认能失败，避免留下假绿。
- **临时素材关闭核对**：终稿报告的关闭清单逐项核对——原临时素材是否在产物中不再被引用、替换后素材是否有 manifest 条目、未替换项是否在缺口清单登记。
- 复用既有先例：纯逻辑闸门 + 真机走查双轨（本仓 t06/t09/t44/t47 系列）、缺口清单验收口径（票 06）、既有走查脚本框架。
- 规格阶段只写验收契约，不运行构建、开发服务器或浏览器调试。

## Out of Scope

- 各批次的具体实施（归执行票 14–18）。
- 统一资产解析层、位置符号合成计划层等基础设施的实现细节（归对应规格）。
- 生产部署与发布流程本身。
- 新的结构或交互决策（按差异判断表升级路径另立票）。
- predev 预演环境的验收。
- 观感好坏的自动判定（归维护者走查）。
- 蓝湖画板逐项盘点本身（票 02 遗留的人工事实采集，在实施阶段消费）。

## Further Notes

- 本规格的唯一决策来源是讨论票 08 的 `## Answer`。
- 5 张执行票（14–18）随本规格同步发布，挂同一张地图，构成实施阶段入口。
- 蓝湖逐画板盘点未完成前，判断表升级路径保持空触发；盘点完成后再逐项分类，实施批次不因盘点未完成而阻塞。
- 当前项目规则要求修改代码后不得自动运行构建或调试命令；执行票实施时需由用户明确要求后再运行验证命令。