# 10: 业务语义规格（异常统计、工单处置率、片区/行业与管理字段 — 来自决策票 06）

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

本规格固化[决策票 06](06-cross-mode-business-semantics.md)的维护者确认结果，作为[同一张 map](../map.md)的子规格单。它是「异常统计、工单处置率、片区/行业统一语义、管理信息面板片区化」的实施输入；不覆盖 `.scratch/cockpit-shell-panel-layout/spec.md`。

## 进度：100%

规格文档已发布为 `ready-for-agent` 并挂到同一决策 map；100% 仅指规格交付，**不表示异常桶、处置率或片区契约已实现**。后端契约改动（`district` 字段、`basis` 改名、管理信息字段删除）需进入后端执行票；前端接线边界在本规格内。

## Problem Statement

跨模式业务口径当前不统一，真实接线时会沿用旧 mock 语义、产生自相矛盾的读数：

1. **异常统计口径混乱**：监测点、监测设备/指标、预警处置地图各有状态词汇，但没有一套明确的"异常桶"定义，容易把点位数与设备数相加、把离线/过期误当业务异常。
2. **处置率口径错误**：后端 `basis` 仍为 `CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS`（已结案 ÷ 事件总数），与已确认的「状态 5 ÷ 状态 0–6」不符；分母为 0 时若显示 0% 会把"无样本"误报成"结案率 0"。
3. **空间/行业维度不统一**：后端 `region` 是自由文本（实测脏值：`UNKNOWN/123/2323`）；`district` 编码存在但未透出；管理信息 `organizations` 是片区名与公司名混合。当前无法按"片区"这一唯一空间维度一致筛选与展示。
4. **管理/权属/维护关系语义在本项目无实际意义**：旧面板展示「管理单位 / 权属构成 / 责任区域」，但这些不是本项目业务维度，且责任区域在后端契约里不存在。

## Solution

从值班人员与维护者视角：本项目分析维度只有**片区**（`district 0/1/2 → 城南/城北/太常`，空值/乱码＝未分区）与**行业**（供水/排水/燃气/窨井）；异常统计按对象分别计数；处置率按「状态 5 ÷ 状态 0–6」且分母为 0 显示不适用；管理信息面板展示片区×行业的设施/设备计数。

核心语义（详见决策票 06 的 Answer）：

- **监测点异常桶**：`ALARM / WARNING / OFFLINE / EMPTY`；`WORK_ORDER` 不入。
- **设备/指标异常桶**：`WARNING / ALARM / EXPIRED / OFFLINE / UNKNOWN`；按对象分别计数、不相加。
- **异常点（预警处置地图）**：只由设备 `WARNING / ALARM` 回联（宽清单窄地图；`abnormalEquipment` 清单可含 EXPIRED/OFFLINE，地图可见性只认 WARNING/ALARM）。
- **处置率**：分子＝状态 5；分母＝状态 0–6 工单数（状态 7 排除）；范围＝当前行业/片区/时间范围内全部工单；分母 0 → 显示"不适用"；`basis` 改为工单分母语义（如 `CLOSED_WORK_ORDERS_OVER_ELIGIBLE_WORK_ORDERS`）。
- **片区**：`district 0/1/2 → 城南/城北/太常`；空值/乱码/未识别 → `未分区`；唯一权威来源＝`district`（取代 organization 与 regionMap）；统计保留数字、展示层映射中文。
- **行业**：供水/排水/燃气/**窨井**（`窨井` 为界面显示词，MANHOLE 映射不变）。
- **管理信息面板**：保留面板位置，改片区×行业设施/设备计数；后端删除 `organizations/ownershipDistribution/unmaintained`。
- **设备档案**：`ownershipUnit / maintainer / maintainerPhone` 保留为静态档案信息，不参与筛选/统计。
- **责任区域**＝片区的展示别名（非独立概念，无独立字段）。

## User Stories

1. 作为值班人员，我想在运行监测中看到监测点异常统计（报警/预警/离线/无设备），以便快速掌握有多少监测点处于异常状态。
2. 作为值班人员，我想知道监测点异常数只统计监测点、设备异常数只统计设备，不会把两类相加成一个无意义总数，以便口径不被误解。
3. 作为值班人员，我想预警处置地图只显示处于报警/预警的设备回联出来的异常点，以便离线/过期设备不会被当成待处置的报警。
4. 作为值班人员，我想在运行概况看到异常设备清单（可含离线/过期），以便了解异常设备事实，而不被地图窄口径限制。
5. 作为值班人员，我想处置率按"已结案工单数 / 状态 0–6 工单数"计算，以便知道真实结案比例。
6. 作为值班人员，我想筛选范围内没有可计入工单时处置率显示"不适用"而不是 0%，以便不会把无样本误读成结案率 0。
7. 作为值班人员，我想按片区（城南/城北/太常/未分区）筛选与展示，以便空间维度一致可对照。
8. 作为值班人员，我想空值/乱码范围显示为"未分区"，以便数据脏值不被猜成某个片区。
9. 作为值班人员，我想行业选择里有"窨井"（而不是"井盖"）作为第四行业，以便术语与业务一致。
10. 作为值班人员，我想管理信息面板展示片区×行业的设施/设备计数，以便了解空间与行业维度的设施分布。
11. 作为维护者，我想后端响应删除管理单位/权属构成/无管理关系字段，以便不再维护本项目不需要的业务关系。
12. 作为维护者，我想设备档案仍保留产权单位/维护单位/维护电话作为静态信息，以便档案完整。
13. 作为维护者，我想"责任区域"不再作为独立概念新增字段或选项，以便不与片区重复建模。
14. 作为维护者，我想处置率的 `basis` 字段名与分母语义一致且不展示原始码给值班人员，以便可审计口径不误导。
15. 作为维护者，我想统计展示保留数字事实（district 编码），页面层才映射中文，以便排序/比较不被中文干扰。

## Implementation Decisions

### 后端（供后端执行票 11–13）

- **处置率（执行票 11）**：
  - 分子＝状态 5；分母＝状态 0–6 工单数（状态 7 排除）；范围＝当前筛选（行业/片区/时间）内全部工单。
  - `basis` 改为工单分母语义（如 `CLOSED_WORK_ORDERS_OVER_ELIGIBLE_WORK_ORDERS`）；契约测试覆盖分母含 6、状态 7 排除、分母 0 → `state=EMPTY`。
  - 旧 `CLOSED_WORK_ORDERS_OVER_TOTAL_EVENTS` 与"状态 6 / 事件总数"口径废止。
- **district 片区契约（执行票 12）**：
  - 相关响应族（地图摘要、运行监测、基础设施、事件/预警分析）统一按 `district`（`0/1/2`）过滤与回显；空值/乱码/未识别 → `未分区`。
  - 旧自由串 `region` 不再作为正式范围契约；`regionMap` 过渡方案失效。
  - 删除管理信息响应的 `organizations / ownershipDistribution / unmaintained` 字段。
  - `abnormalEquipment` 清单语义文档化：可含 `WARNING/ALARM/EXPIRED/OFFLINE`（宽清单）；前端另行按 `WARNING/ALARM` 做地图回联。
- **实时同步（执行票 13）**：沿用决策 04/09 的连接生命周期；增量帧字段语义按 #01 执行票定义，不在此重复。

### 前端

- `domain` 纯函数：
  - 异常桶表（监测点桶、设备/指标桶各一张白名单，`WORK_ORDER` 不入监测点桶）。
  - 处置率视图：分母 0 / `state=EMPTY` → 显示"不适用"，不显示 0%（叠加既有 `handlingRateView` 纪律，文案改为「当前范围没有可计入工单，处置率不适用」）。
  - 片区映射：`district 0/1/2 → 城南/城北/太常`，未识别 → `未分区`；统计保留数字，展示层映射中文。
- `filterOptions`：行业显示词「井盖」→「窨井」（MANHOLE 映射不变）；范围默认值保留 城南/城北/太常/未分区。
- 管理信息面板：保留 panelId/布局，视图改为片区×行业的设施/设备计数；移除管理单位/权属构成/责任区域内容。
- 设备档案：`ownershipUnit / maintainer / maintainerPhone` 保留为静态行，不参与筛选/统计。
- 异常点地图计划（`modeLayerPlan` 域）：只用 `WARNING/ALARM` 设备回联为异常点；`OFFLINE/EXPIRED` 只进运行概况清单，不冒充异常点。

## Testing Decisions

- **好测试的定义**：只测外部行为与契约语义——异常桶白名单、处置率分母 0 不适用、`district` 映射未识别→未分区、管理面板不再显示管理单位/权属/责任区域、地图异常点只认 WARNING/ALARM；不测组件内部实现。
- **主接缝**：`domain` 纯函数（异常桶表、处置率视图、district 映射）+ 服务层守卫（basis 不泄漏、异常白名单、`filterOptions` 词汇）。沿用仓库既有的零依赖逻辑闸门模式（`.scratch/cockpit-shell-panel-layout/verify/tNN-*.mjs`，先例 `t18-monitoring-panels.mjs`、`t19-warning-response.mjs`）。
- **浏览器走查**（`-walkthrough.mjs` + `data-*`）：管理信息面板片区×行业计数、处置率不适用提示、行业选择含窨井、地图异常点不含离线、片区筛选项与未分区。
- **变异测试**：对异常桶白名单、处置率"分母 0 不适用"、district 未识别归一做变异确认有牙（先例 t18/t19）。

## Out of Scope

- 工单创建/处置等写操作（外部业务系统承担，驾驶舱只读）。
- 报警—工单闭环的增量帧字段解析（归执行票 13 与 #01）。
- `sampledAt`（采样时刻）与 `createdAt`（数据时间）字段语义（归决策 03 / 规格 08）。
- `pointStatus` 多值筛选、状态栏入口、自动加载（归决策 02 / 规格 07）。
- real 生命周期接线（归决策 04 / 规格 09）。
- 后端实现与真实联调（后端执行票 11–13 按联调基线推进）。
- 移动端、UE5、Docker、国产化认证及非驾驶舱领域。

## Further Notes

- 本规格依赖决策票 06（已 resolved）；执行票 11–16 以此为输入。
- 领域词汇已同步 `CONTEXT.md`：新增「片区」「责任区域（=片区别名）」「窨井」词条。
- 已同步修订：决策 02 与规格 07（`regionMap` → `district`）；票 25（E1 out-of-scope、处置率/异常口径冻结）。
- 未运行 build/debug 验证（遵循仓库 AGENTS.md 规则）；本规格只交付实施输入。