# 05: Mock 领域适配层

**What to build:** 建立驾驶舱领域适配层，让 mock 数据与真实接口使用同一契约。页面组件只消费领域对象，不直接依赖后端字段。

Blocked by: 04

Status: resolved
Labels: ready-for-agent

- [x] 存在可切换的 mock 数据源；默认 mock，真实接口由部署配置显式开启。
- [x] 真实模式下适配层统一附加部署层注入的 `Authorization` 请求头。
- [x] 接口字段到领域对象的转换集中在适配层。
- [x] 页面和 store 不直接处理后端裸字段。
- [x] mock 数据覆盖成功、空数据、字段缺失、失败和过期样例。
- [x] 401 或凭据类失败只把受影响分区标为数据不可用，保留已成功分区与地图骨架。
- [x] 有适配器转换单测。

## 进度：100%

**已完成并关闭（2026-09-18）。** 逻辑闸门 **178/178**、真机走查 **10/10**，维护者已开启服务并要求跑测（当时撞上沙箱 `spawn EPERM`，经批准后放行执行）。

### 交付边界（与维护者确认，2026-09-18）

Q1 裁定 **(B) 接缝 + 共享详情域**：票 05 交出「领域词汇 + 转换机制 + common 详情域适配器」，16 个**面板级**聚合留给 17–20（它们各自的验收原句就写着「有面板数据适配和联动单测」）。
其余裁定：Q2 分区状态词汇照搬后端四态 + 前端特有 `unavailable`；Q3 mock 照抄后端真实字段名；Q4 做「纯逻辑 + 最小可演示」；Q5 不新开 ADR。

### 改动

**领域词汇与工具**（`domain/`，纯函数、可脱浏览器断言，不 import service）

- `sectionState.js`：分区状态词汇。后端 `CockpitSectionState` 四态（`SUCCESS`/`EMPTY`/`STALE`/`FAILED`）**1:1** 映射，另加前端特有 `UNAVAILABLE`（凭据/链路类失败，对应票 04 的 `isCredentialFailure()` 与统一文案）。`STALE`（有值但过期，`retained:true`）与 `EMPTY`（确实没有值）严格分开 —— 这是票 16 两条验收原句的落点。`sectionFromResult()` 是唯一收口，`sectionView()` 给色键与文案，`overallState()` 让 `partial` 可与全坏区分。
- `requestReason.js`：`REQUEST_REASON` 从 `services/cockpitApi.js` 提到 domain。原因：`sectionState` 要按失败原因判「数据不可用」还是「加载失败」，而 domain 反向 import service 会层次倒挂。`cockpitApi.js` 仍转出该常量，**票 04 的脚本与调用点零改动**。
- `fields.js`：字段读取器。核心是区分「本该有却没有」（记 `missing`，界面显示占位符）与「本来就允许为空」（静默 `null`）；缺失一律回 `null`，**绝不用 0 冒充**，而后端真给的 0 是有效数据。
- `mapSummary.js`（票 07/08 的输入）、`pointDetail.js`（票 09/10）、`equipmentDetail.js`（票 11）、`workOrder.js`（票 11/12）、`events.js`（票 13/14/19）、`freshness.js`（票 16）：逐字段转换，字段名以 `E:\pipe-ner-server\docs\cockpit\*.html` 与 `research/panel-field-coverage.md` 为准。

**服务层**（ADR 0005 的领域拆分）

- `domainRequest.js`：三个领域模块共用的「拼查询串 → 走票 04 的 `requestCockpitJson` → 收成一个分区」。
- `mapApi.js` / `detailApi.js` / `runtimeApi.js`：领域接口。**每个分区各自成败**，调用方拿到的是一组并列 `section()` 而不是共用成败的详情对象。
- `cockpitApi.js`（改）：新增 `findMockTransport()` 通配匹配，让带路径参数的接口（`/equipments/*/detail-aggregate`）也能 mock；mock 处理器可在异常时声明失败原因，但只认白名单取值。
- `mocks/contractMocks.js` + `mocks/index.js`：契约化 mock。字段名与嵌套形状**照抄后端演示载荷**，值用边界值构造（坐标 VALID/UNVERIFIED/INVALID/ZERO、指标真 0、未结案 `null`）。场景开关走宿主全局键，**不改代码不重新构建**即可演示五类样例与 401。

**最小可演示**（Q4=B）

- `components/SectionStateTag.vue` + `stores/detailStore.js`（ADR 0004 的 `detailStore`）+ `CockpitShell.vue` 筛选条右侧的分区状态板：三条共享分区各带 `data-section-state` / `data-section-name` / `data-section-tone` / `data-section-retained`，走查可直接断言。**只有 mock 模式才自动取数**：real 模式后端未就位，自动取数只会刷 404（沿用票 04「没有显式配置就不发请求」的立场）。

### 验证证据

- **纯逻辑**：`node .scratch/cockpit-shell-panel-layout/verify/t05-adapter.mjs` → **178/178 通过**。四段：A 分区状态（四态映射、401 归类、过期 vs 空、部分可用、视图映射、**界面文案零原因码泄漏**）；B 领域转换（用后端演示载荷的真实字段名喂入，含 0 值/缺失/null-time/超范围坐标/七态/回退动作/阈值只在报警/未知配色）；C 契约化 mock（五类样例逐一取数、401 与前缀隔离、real 分支同一适配层且带凭据、假 401、坏载荷、查询串、缺编码不发请求、WS 增量帧两个字段名、注册幂等）；D 静态守卫（10 个页面/store 文件零后端裸字段、零凭据、零登录跳转；8 个领域模块不自己发请求、不 import service）。
- **真机走查**：`node .scratch/cockpit-shell-panel-layout/verify/t05-adapter-walkthrough.mjs` → **10/10 通过**（`yarn dev` @ localhost:8000，维护者开启并要求跑测）。逐条：默认三条分区 `success`+`lv4`、引擎 `ready`、宿主唯一、四面板齐全、零页面级报错；空数据样例显示「无数据」中性色且不误报失败；过期样例 `stale`+`lv2`+`retained=true` 且文案含「已过期」；失败样例三分区 `failed` 而外壳/四面板/地图骨架全保留；**401 只标受影响分区**（设备详情 `unavailable`+`lv1`+「数据不可用」+「凭据未通过校验（由部署层注入）」，地图摘要与新鲜度仍 `success`）、地图骨架未被牵连、不跳登录页、零页面级报错。截图归档在 `verify/walkthrough/t05-sections-{success,401}.png`（走查产物，gitignore）。
- **回归**：`t01-panel-catalog` / `t03-camera-contract` / `t04-config` / `t06-assets` / `t21-terrain` / `t29-basemap` **全部通过（exit 0）**（票 04 的凭据守卫与既有断言未受影响）。
- **布局**：分区板接入后实测筛选条仍为 34px 行高、`scrollWidth === clientWidth`（无横向溢出）、文档无横向滚动。
- **编译**：`@vue/compiler-sfc` 对 `CockpitShell.vue` 与 `SectionStateTag.vue` 的 template 与 `<script setup>` 均解析通过，绑定无悬空。
- **单测直接证到的关键行为**：档案分区失败时指标分区仍是成功（票 11 验收第 3 条）；401 只打掉被选中的那一个分区，同一次加载里地图摘要与新鲜度照常成功、`overallState` 为 `partial`；过期分区 `retained:true` 且保留旧值；空分区 `data:null`；未注册接口回 `mock-handler-missing` 而不是静默成功。

### 真机走查抓到的两个真 bug（第一轮 7/10 → 修复后 10/10）

这正是「渲染侧不能只靠纯逻辑」的实证——两条逻辑闸门全绿时它们照样存在：

1. **分区标签把状态词顶掉了（真 UI bug）**：`SectionStateTag` 原先用 `labelOverride` 让分区名**替换**状态文案，结果过期分区只显示「显示最后一次成功数据，不是实时值」、不可用分区只显示「凭据未通过校验」——**肉眼与断言都读不出「已过期 / 数据不可用」**，而成功态与失败态长得几乎一样。修法：分区名与状态词**两者都渲染**（`label` + `sectionView().label`），状态词永不被顶掉。修在组件里，所有分区同享。
2. **界面漏出内部原因码**：失败分区的 `detail` 直接回传 `reason`，截图上出现「数据加载失败**unavailable**」。修法：`sectionState.js` 新增 `reasonDetail()` 字典，六种原因各有中文说明、**认不出的原因回空串**（宁可只说「数据加载失败」，也不把接口代号甩给值班人员），并补 `A9-no-reason-code-in-ui` 静态断言防回归。

另有一条**属走查脚本自身的时序问题**（非产品缺陷）：`A1-map-skeleton-alive` 在引擎仍 `booting` 时就读断言（`engine=booting` → 误判红）。修法与 `t04`/`t29` 一致——先等 `dataset.mapEngine` 落到终态再断言。

### 边界与遗留

- `runtimeApi.js` 只交 REST 侧与**增量帧→领域事件**的转换；连接、重连、按 `serverUpdatedAt` 丢弃旧消息归票 15（其票面原句），本票不持有连接。
- 事件的地理位置仍是契约缺口（后端只有文本 `location`，无经纬度）：转换层已留 `longitude`/`latitude` 位并如实回 `null`，补契约见票 25。
- 面板级（16 个二级面板）领域适配按 Q1=B 留给 17–20；本票只交共享详情域。
- `PanelPlaceholder` 仍是各面板体内占位 —— 面板内容归 17–20，本票只把**共享分区状态**接上界面。
- 本票改动**未提交**（工作区另有票 03/30 会话的在途改动）。