City-Lifeline-Cockpit/.scratch/cockpit-real-data-wayfinding/issues/02-map-status-filter-and-unassociated-devices.md

02: 地图摘要状态筛选与未关联设备语义

Type: grilling Status: resolved Labels: wayfinder:grilling Blocked by: 01

Question

锁定 map-snapshot 的 pointStatus 过滤契约，以及未关联设备在状态筛选、分页、快照和坐标汇总中的处理方式。讨论中进一步扩展为全局状态筛选入口与自动渐进加载行为。

Answer

一、筛选语义总则

1. 行业/范围/类型筛选（Q7）：设备级匹配、点位级 OR 归并。监测点是设备聚合点；任一设备命中 industry/region/deviceType 条件 → 其所属监测点进入结果。未关联设备按自身 industry/region/deviceType 直接匹配。map-snapshot 与 /monitoring/distribution 两端同一语义、点位集合一致。
2. 状态筛选（Q22/Q23）：对两类对象都生效，各自使用各自的状态来源：
   • 监测点按后端聚合 pointStatus（六态：ALARM/WARNING/WORK_ORDER/NORMAL/OFFLINE/EMPTY）匹配。不做设备级 OR 归并——一个点位只有一个聚合状态，选 ALARM 只显示聚合状态为 ALARM 的点位，点位不会跨状态重复出现，与「点位状态分布」六态计数严格一致。
   • 未关联设备按设备状态词表（domain/deviceStatus.js 五态：报警/预警/工单处置/正常/离线 + 状态未发布 UNKNOWN）匹配。EMPTY（无设备）只适用于监测点，不适用于设备自身。
3. 「无关联设备」桶（Q11/Q16）：是对象类别筛选（「只看未关联设备」），与状态筛选正交：
   • 选了状态 ALARM 但未选「无关联设备」桶 → 显示聚合状态为 ALARM 的监测点 + 设备状态为 ALARM 的未关联设备（状态筛选本身作用到未关联设备，不需要额外勾选类别桶）。
   • 只选「无关联设备」桶 → 只看符合其它筛选条件的未关联设备。

二、展开点位时的设备子集（Q8/Q14/Q15/Q20）

• 点开命中筛选的监测点：只显示命中设备 + 一行可展开的「另有 N 台」（显示全部未命中设备）。
• 未命中设备展开后可完全交互（hover/选中/定位/进详情），仅视觉弱化。
• 设备总数 X = 该点位全部关联设备；已上图 Y = 命中且上图的子集（不撒谎）。
• map-snapshot 点位响应带命中设备子集（deviceCodes/设备明细按当前筛选裁剪；未筛＝全部），前端展开直接用，不额外 N+1。

三、全局状态筛选入口（Q9/Q10/Q12/Q13/Q18/Q19/Q21）

• 地图顶部状态栏 = 全局组合筛选入口：八桶（报警/预警/工单处置/正常/离线/无设备/状态未发布/无关联设备）多选 OR。
• 状态栏计数 = 全局未筛全集（后端全量、不分页）；筛选只改选中高亮、不改计数。
• 状态栏与监测分布饼图共用同一份全局未筛分布；饼图显示全局分布并高亮当前选中。
• 数据源：后端在未筛时给出八桶全局计数（六态 + UNKNOWN + UNASSOCIATED）；筛选时计数不变。
• 监测分布面板不再自带筛选，只显示当前全局筛选下的分布（状态统计用饼图）。
• 死胡同根治（Q12）：筛选控件常驻可操作；结果为空只是结果区一句说明，不吞掉筛选入口（修复「选中 0 数据状态后无法再筛选」的现状缺陷）。

四、pointStatus 多值契约（Q10/Q16）

• 单参数多值：pointStatus=ALARM,WARNING,UNKNOWN,UNASSOCIATED（逗号分隔或重复参数，OR 语义）。
• UNKNOWN＝点位上状态缺失或不在六态词典（对未关联设备＝设备状态未发布）。
• UNASSOCIATED＝只筛未关联设备（类别筛选）。
• 认不出的值 400 INVALID_REQUEST；mapFilter 回显整套生效值。
• 不传＝全部（监测点 + 未关联设备都返回，默认行为）。

五、坐标汇总与组合筛选（Q5/Q6）

• 坐标汇总 = 筛选后口径：默认不筛时是全局，筛了就是筛选集内全局（避免「地图上点少了而摘要说已上图 N 个不变」）。
• 组合筛选 = AND（行业 ∧ 范围 ∧ 类型 ∧ 状态桶）；mapFilter 回显全部生效维度；结果为空走既有 EMPTY，前端不猜原因。

六、自动渐进加载与刷新（Q24/Q25）

• 移除「加载下一页」按钮：进入系统/筛选变化后，系统自动连续分批加载到完成（批次间留帧间隔防卡顿）；调度失败/被新筛选打断按现有 token 纪律处理。
• 移除「刷新快照」按钮，改为右上角保留一个小刷新图标（🔄）作为手动刷新快照入口。
• 自动刷新时机：①筛选变化 → 换新快照从第 1 页重载（既有规则）；②新鲜度周期到点（freshness tick）→ 自动 refresh；③收到相关 WS 状态增量 → 按需 refresh。
• 归属：装载器自动化（自动分批、自动刷新时机）属 #02 决策；real 模式下与 freshness/WS 的接线细节归 #04 引用本票结论，不重复决定。

七、后端契约改动清单（供执行票）

• map-snapshot：
  • 入参增加多值 pointStatus（含 UNKNOWN/UNASSOCIATED）。
  • 点位响应带命中设备子集（未筛＝全部）。
  • 未筛时提供八桶全局计数。
  • 筛选后坐标汇总按筛选口径。
• /monitoring/distribution：
  • 入参多值化（同 map-snapshot 语义）。
  • pointStatusDistribution 未筛时含八桶。
  • 与 map-snapshot 的筛选语义一致（行业/范围/类型设备级匹配 + 状态按聚合/设备各自匹配）。
• 两端点对「认不出的值 400」与 mapFilter 回显的约定统一。

八、边界（与 #01/#06）

• 本票不定义「异常统计」的状态词汇（归 #06）；不改工单状态/报警工单（归 #01/#06）。
• 设备级状态词表（deviceStatus.js）本身不在本票范围；本票只引用它来定义未关联设备参与状态筛选的匹配取值。

状态

已解决。 全局状态筛选入口、未关联设备参与状态筛选的设备级语义、多值 pointStatus 契约、命中设备子集、展开交互、坐标汇总口径、死胡同修复与自动渐进加载/手动刷新入口均已确认。后端契约改动清单待进入执行票；#04 引用本票的自动刷新时机结论。