# 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 引用本票的自动刷新时机结论。

## 修订记录（2026-10-08，按决策票 06）

- **范围维度修订**：原「`region` 是自由串、取值由 `regionMap` 配置声明、未配置就不下发」的立场**作废**。范围条件正式改为**片区**（`district` 编码 `0/1/2 → 城南/城北/太常`；空值/乱码统一「未分区」），后端统一按 `district` 过滤与回显；脏 `region` 值（实测 `UNKNOWN`/`123`/`2323`）不参与筛选、如实显示未分区。
- `regionMap` 配置降级为过渡方案或删除；`map.filters.regionMap` 相关缺口说明（`REGION_MAP_GAP`）随本修订失效。
- 本票其余结论（多值 `pointStatus`、设备级匹配、点位 OR 归并、八桶计数、自动分批加载等）不变。