# 设备报警监控报警提示升级 Spec

## Why
现有报警提示仅「严重报警亮 10 秒指示灯 + 880Hz 三声 beep」，与派单状态无关联，提示不够醒目；需升级为悬浮立体警灯样式、警车警报声，并与派单联动：同线路报警派单完成后取消提示，未派单完成则每 3 分钟重复报警声。

## What Changes
- **后端**：新增**报警派单完成接口** `POST /api/worker-app/alarm-dispatches/:id/complete`（供共享电工 APP 确认完成报警派单）：校验派单归属当前电工、状态为未完成（status=0），更新 status→1 并写入 completed_at；已完成的重复调用幂等提示。
- **后端**：`GET /api/device-alarms` 的 summary 由 `severeIds`（全量 grade=1）改为 **`activeSevereIds`**：grade=1 且**无已完成派单（status=1）**的报警 id 集合（倒序取最近 100 条）。派单完成后报警自动移出集合即取消提示；未派单完成的严重报警始终在集合内持续触发。
- **前端**：替换现有顶部「严重报警」指示灯为**悬浮立体警灯**（红蓝双色旋转闪烁、CSS 3D 效果），固定悬浮页面右上角；存在未派单完成的严重报警时警灯旋转闪烁。
- **前端**：点击悬浮警灯时，若当前路由不是设备报警监控页（`/device/alarm`），直接 `router.push('/device/alarm')`。
- **前端**：报警声由 880Hz beep 改为 **Web Audio 合成警笛声**（高低音交替，如 700Hz↔900Hz，循环 2~3 轮）。
- **前端**：报警声触发策略改为「**即时响一次 + 每 3 分钟重复响一次**」：新严重报警即时响；之后只要存在未派单完成的严重报警，每 3 分钟重复响一次警笛，直到全部派单完成。新增独立 3 分钟定时器（现有 30 秒列表轮询保持不变）。
- **前端**：新增「重置报警提示」小按钮（悬浮警灯旁）：清空已通知集合，使当前所有未派单完成的严重报警重新触发一次灯/声音。

## 与派单联动的报警取消/重新触发语义（用户确认）
- **派单完成** = 管理端发起报警派单（status=0）→ 共享电工到现场处理完成派单任务 → 电工在共享电工 APP 点击确认完成（调用本系统新增的完成接口，status→1 + completed_at）。
- **派单完成后报警取消**：严重报警派单完成后移出 activeSevereIds → 不再触发灯/声音，3 分钟重复响（若无其他活跃严重报警）停止。
- **有遗留严重报警才重新触发**：派单完成时若该线路仍存在未派单完成的严重报警（遗留），该遗留报警持续（重新）触发灯/声音；其后同线路新严重报警正常触发。
- **手动重置**：保留「重置报警提示」按钮，清空已通知集合后当前所有未派单完成的严重报警重新触发一次。

## Impact
- Affected specs: 设备报警监控（ICC 报警事件订阅）、共享电工 APP
- Affected code:
  - [server/src/controller/device_alarm.controller.ts](file:///F:/NewProject/鑫潼Git/smart_grid_iot/server/src/controller/device_alarm.controller.ts)（summary `severeIds` → `activeSevereIds`）
  - [server/src/controller/worker_app.controller.ts](file:///F:/NewProject/鑫潼Git/smart_grid_iot/server/src/controller/worker_app.controller.ts) + [server/src/service/worker_app.service.ts](file:///F:/NewProject/鑫潼Git/smart_grid_iot/server/src/service/worker_app.service.ts)（报警派单完成接口）
  - [client/src/views/device/alarm/index.vue](file:///F:/NewProject/鑫潼Git/smart_grid_iot/client/src/views/device/alarm/index.vue)（警灯替换、警笛、activeSevereIds 驱动、3 分钟定时器、点击跳转、重置按钮）
  - [client/src/api/alarm.ts](file:///F:/NewProject/鑫潼Git/smart_grid_iot/client/src/api/alarm.ts)（`DeviceAlarmSummary` 的 `severeIds` → `activeSevereIds`）

## 明确假设（需用户知悉）
1. **「派单完成」业务链路与判定**：确认动作在共享电工 APP 发起，本系统后端新增完成接口承接（status→1 + completed_at）；`alarm_dispatch.status = 1` 即「派单完成」判定。共享电工 APP 端 UI 的确认按钮不在本次范围（由 APP 端对接本接口）。
2. **悬浮警灯位置** = 设备报警监控页面右上角固定悬浮（position: fixed），z-index 高于页面内容。
3. **警笛声**为合成警笛（高频交替），不受浏览器自动播放策略影响时正常发声；首次加载无用户交互仍遵循浏览器自动播放限制（静默降级只亮灯/旋转）。
4. **手动重置**作用于本地已通知集合（无后端持久化），刷新页面后自动重建。

## ADDED Requirements
### Requirement: 报警派单完成接口
系统 SHALL 提供共享电工 APP 确认完成报警派单的接口：校验派单归属当前电工且未完成，更新状态为已完成（status=1）并写入完成时间（completed_at）。

#### Scenario: 电工确认完成报警派单
- **WHEN** 共享电工 APP 调用 `POST /api/worker-app/alarm-dispatches/:id/complete`，且该派单归属当前电工、状态为未完成（status=0）
- **THEN** 派单 status 更新为 1、completed_at 写入当前时间，返回完成成功；管理端报警监控页轮询后该报警移出 activeSevereIds，不再触发灯/声音

#### Scenario: 归属校验与幂等
- **WHEN** 派单不归属当前电工，或派单不存在
- **THEN** 返回 403/404；派单已完成（status=1）时重复调用返回幂等提示（不重复计数、不报错）

### Requirement: 悬浮立体警灯
系统 SHALL 在设备报警监控页面右上角以固定悬浮方式展示立体警灯（红蓝双色旋转闪烁、CSS 3D 效果），替换现有「严重报警」指示灯；当存在未派单完成的严重报警时警灯旋转闪烁。

#### Scenario: 严重报警触发警灯
- **WHEN** activeSevereIds 非空（存在未派单完成的严重报警）
- **THEN** 悬浮警灯出现并旋转闪烁

#### Scenario: 点击警灯跳转页面
- **WHEN** 页面不在设备报警监控页时用户点击悬浮警灯
- **THEN** 跳转到 `/device/alarm` 并打开设备报警监控页面

### Requirement: 派单完成后报警取消与遗留重新触发
系统 SHALL 将「已完成派单（status=1）关联的报警」从触发集合中移除，实现报警取消；同线路未派单完成的严重报警持续触发，派单完成时若有遗留未派单严重报警则重新触发。

#### Scenario: 派单完成后报警取消
- **WHEN** 某严重报警的派单完成后（status=1）
- **THEN** 该报警移出 activeSevereIds，不再触发警灯旋转与警笛声；若无其他活跃严重报警，3 分钟重复响停止；KPI 统计不受影响（仅提示取消，列表记录保留）

#### Scenario: 遗留严重报警重新触发
- **WHEN** 派单完成时该线路仍存在未派单完成的严重报警
- **THEN** 遗留报警继续/重新触发灯与声音（新入库的遗留报警即时触发一次；已触发过的按 3 分钟重复响）

#### Scenario: 手动重置
- **WHEN** 用户点击「重置报警提示」按钮
- **THEN** 已通知集合清空，当前所有未派单完成的严重报警重新触发一次灯/声音

### Requirement: 警笛声与轮询策略
系统 SHALL 在出现未派单完成的严重报警时即时播放一次合成警笛声，并每 3 分钟重复播放一次（只要仍存在未派单完成的严重报警）；报警声为 Web Audio 合成警笛（高低音交替）。

#### Scenario: 即时响
- **WHEN** 新未派单完成的严重报警出现
- **THEN** 立即播放一次警笛声，同时警灯旋转闪烁

#### Scenario: 3 分钟重复响
- **WHEN** 存在未派单完成的严重报警，且距上次响声满 3 分钟
- **THEN** 重复播放一次警笛声

#### Scenario: 全部派单完成后停止
- **WHEN** 所有严重报警均派单完成（activeSevereIds 为空）
- **THEN** 不再触发警笛声，警灯停止旋转

## MODIFIED Requirements
### Requirement: 严重报警提示（原「严重报警指示灯 + 880Hz beep」）
原实现为顶部 `alarm-light` 指示灯点亮 10 秒 + 880Hz×3 次 beep，触发扫描基于后端 summary.severeIds 全量 grade=1 报警。现修改为：悬浮立体警灯（替换指示灯，存在未派单完成的严重报警时持续旋转闪烁）+ 合成警笛声（即时 + 每 3 分钟重复）；触发扫描改为 summary.activeSevereIds（过滤掉已派单完成的报警）。

## REMOVED Requirements
### Requirement: 880Hz beep、10 秒报警灯计时、全量 severeIds
**Reason**: 报警提示样式与声音升级为悬浮警灯与警笛声，10 秒指示灯逻辑不再适用；触发集合需排除已派单完成的报警，severeIds（全量 grade=1）语义不再满足。
**Migration**: 删除 `alarmLight` 10 秒 setTimeout 逻辑与 doBeep；保留 Web Audio 自动播放策略静默降级（resume 失败仅亮灯不发声）；summary 字段 `severeIds` 改为 `activeSevereIds`（前端唯一使用方为 device/alarm/index.vue，同步迁移）。