smart_grid_iot/.trae/specs/upgrade-alarm-monitor-alert/spec.md

设备报警监控报警提示升级 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（summary severeIds → activeSevereIds）
  • server/src/controller/worker_app.controller.ts + server/src/service/worker_app.service.ts（报警派单完成接口）
  • client/src/views/device/alarm/index.vue（警灯替换、警笛、activeSevereIds 驱动、3 分钟定时器、点击跳转、重置按钮）
  • 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，同步迁移）。