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

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

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

进度：100%

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

Problem Statement

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

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

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

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

10-business-semantics-spec.md 10 KB Bezpośredni odnośnik Historia Czysty