# 2026-09-16：监测报警 GIS 接入统一画布（Ticket #4）

## 目标

- 完成 Gogs Issue #4：将监测报警一张图接入统一 GIS 页壳和共享画布。
- 复核后端报警、工单状态和数据库契约，更新前端领域共识。

## 结论

- Issue #3 收尾提交已推送，当前分支在实现 #4 前与 `origin/master` 同步。
- 报警一张图继续复用 `WaterGisPageShell`、`GisMapCanvas`、彩色聚合图标和“报警集合：数量”文本。
- 报警点位状态统一调用共享监测点状态推导，不再维护报警页私有优先级；关联工单仅在未结束时显示蓝色，已结案/已取消不再误判为关联工单。
- 报警详情独立展示报警等级、报警类型、设备报警状态、报警记录状态、报警展示状态、设备当前状态、在线状态和关联工单状态；设备状态或记录状态缺失时显示“未获取”，不互相替代。
- 报警地图通过分页读取全部报警台账和设备点位补全状态；台账或设备接口失败时显示降级提醒，但保留点位列表和重试入口。
- 新增 `全图` 控件，并在地图 ready 后重新适配点位视野。

## 验证

- GIS、报警模型和报警页单文件测试：24/24 通过。
- 前端全量测试：103/103 通过。
- 生产构建：通过。
- `git diff --check`：通过。
- 真实登录态和 BMapGL 点位颜色仍需人工浏览器验收。

## 风险

- 后端 `AlarmMapPointOutDTO` 仍缺少设备报警状态、在线状态和关联工单字段；当前前端通过报警台账与设备 GIS 接口补全。后续若报警数据规模继续增长，建议后端在地图点位契约中直接返回这些字段。
- 报警台账分页设置 200 条/页、最多 50 页的安全上限；超过上限会进入加载失败状态，而不是静默丢失状态。

## 补充：三张 GIS 图一致性回归（Ticket #5）

- 共享页壳 `WaterGisPageShell` 新增统一的指标卡样式（图标框 + 文本块 + 数值单位）、地图错误态与空态定位样式；三张图不再各自维护重复的指标卡/错误态 CSS。
- 设施图与设备图移除了共享页壳内嵌套的 `.metric-grid`（此前为 2 列，与报警图单列结构冲突），统一由页壳提供网格；三张图的指标卡结构统一为 `metric-icon + metric-body + metric-value + small`。
- 设备图补齐地图空态；三张图的空态均按“未加载完成不显示空态”处理。
- 三张图的地图错误提示统一提供“重试”入口；刷新与“全图”按钮在三张图保持一致。
- 报警图详情抽屉按模式区分宽度：报警审核保持 720px，监测报警一张图与另外两图一致使用 420px 右侧抽屉。
- 新增契约测试 `tests/waterGisConsistency.test.mjs`：锁定共享指标网格、三图指标结构、刷新/空态/错误重试/抽屉契约、搜索结果卡片结构，以及“聚合后点位数之和等于有效点位总数”的数据完整性属性。
- 删除设备图遗留的未使用 `.map-container` 规则；`.gitignore` 增加 Vite 构建临时配置忽略规则。
- 验证：前端全量测试 112/112 通过；生产构建通过；`git diff --check` 通过。
- 仍需人工验收：真实登录态下三张图的点位数量、图标颜色、名称标签、左侧面板滚动、抽屉遮挡与门户/菜单路由。

## 补充：三图 UI 一致性人工验收修正

- 根因：`waterSupplyPageTheme.scss` 是全局样式，其中 `.metric-icon { position: absolute; top:16px; left:16px }` 与 `.metric { padding-left:48px }` 会泄漏到设施/设备 GIS 页，导致指标卡图标绝对定位并压住文字。共享页壳的指标卡规则现在显式声明 `position: static` 并覆盖内边距，已消除重叠。
- 整体排版参考监测报警一张图：设施图与设备图改为与报警图相同的“`el-card.water-panel.map-card` + `embedded` 页壳”结构，三图页壳、页头、指标卡、空态、错误态的承载方式一致。
- 右侧抽屉参考监测设备一张图：监测报警一张图新增独立的地图模式抽屉（420px、`detail-hero` + `detail-section` + `dl` 字段列表），报警审核/报警管理仍使用原有工作台抽屉（720px/420px + 审核表单 + 时间线）。
- 新增契约测试：指标卡定位回归、三图卡片与抽屉结构一致性。
- 验证：前端全量测试 114/114 通过；生产构建通过。
- 仍需人工验收：三图指标卡与抽屉的实际渲染效果、点位数量与颜色、左侧面板滚动。

## 补充：GIS 页面骨架对齐监测报警一张图

- 目标结构以「监测报警一张图」为准：页面标题区（图标 + 标题 + 副标题 + 刷新）→ 独立筛选卡片（卡片标题 + 关键字/类型 + 查询/重置）→ 地图卡片（内嵌统一页壳）。
- 设施图与设备图补齐页面标题区与筛选卡片；筛选控件与页壳内搜索框绑定同一组状态，保持行为一致。
- 新增共享样式 `src/views/subSystem/waterSupply/components/waterGisPageTheme.scss`，承载 `.gis-page` 页面骨架、标题区、筛选卡片、卡片标题与地图卡片样式；设施图与设备图通过非 scoped `@use` 引入，避免逐页复制。
- 报警图保持原样作为参照基准，其本地样式与共享骨架取值一致。
- 验证：前端全量测试 116/116 通过；生产构建通过。