docs(aiot): 添加告警时间字段语义说明和迁移脚本

添加 alarm_event 表字段语义说明文档

字段说明:
- event_time: 告警触发时间
- first_frame_time: 离开ROI时间
- last_frame_time: 回岗时间 (NULL = still away)
- duration_ms: 持续时长 (NULL = still away)

包含验证SQL查询和部署说明

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

数据库/aiot/迁移-调整告警时间字段语义.sql

@@ -0,0 +1,138 @@
+-- ============================================================================
+-- 迁移脚本：调整告警时间字段语义说明
+-- ============================================================================
+--
+-- 背景：
+--   离岗告警采用两阶段模型：
+--   1. 告警触发时：duration_ms=NULL, last_frame_time=NULL（人员仍在离岗）
+--   2. 人员回岗后：填充 duration_ms 和 last_frame_time（告警完整闭环）
+--
+-- 本迁移脚本说明：
+--   此脚本仅包含字段语义说明，无需执行DDL变更。
+--   alarm_event 表的字段语义已在原始schema中正确定义，
+--   此脚本用于明确字段在两阶段模型中的含义。
+--
+-- ============================================================================
+
+-- 字段语义说明
+-- ----------------------------------------------------------------------------
+
+-- alarm_event 表字段定义：
+
+-- 1. event_time (DateTime, NOT NULL)
+--    含义：告警事件发生时间
+--    离岗场景：倒计时结束触发告警的时刻
+--    示例：2026-02-13 14:05:00（倒计时结束时间）
+
+-- 2. first_frame_time (DateTime, NULLABLE)
+--    含义：人员离开ROI的时间（离岗开始时间）
+--    离岗场景：人员首次离开监控区域的时刻
+--    示例：2026-02-13 14:00:00（离开时间）
+--    注意：在告警触发时由 Edge 端填充
+
+-- 3. last_frame_time (DateTime, NULLABLE)
+--    含义：人员回岗时间（离岗结束时间）
+--    离岗场景：人员返回监控区域的时刻
+--    初始值：NULL（告警触发时人员未回岗）
+--    填充时机：收到 resolve 事件后更新
+--    示例：2026-02-13 14:15:00（回岗时间）
+
+-- 4. duration_ms (Integer, NULLABLE)
+--    含义：告警持续时长（毫秒）
+--    计算公式：last_frame_time - first_frame_time
+--    初始值：NULL（告警触发时持续时长未知）
+--    填充时机：收到 resolve 事件后计算并更新
+--    示例：900000（15分钟 = 900秒 × 1000毫秒）
+
+-- ============================================================================
+
+-- 两阶段告警模型流程示例
+-- ----------------------------------------------------------------------------
+
+-- 阶段1：告警触发
+-- INSERT INTO alarm_event (
+--     alarm_id, alarm_type, event_time, first_frame_time,
+--     last_frame_time, duration_ms, alarm_status
+-- ) VALUES (
+--     'ALM20260213140500ABCD',     -- 告警ID
+--     'leave_post',                 -- 告警类型
+--     '2026-02-13 14:05:00',       -- 告警触发时间
+--     '2026-02-13 14:00:00',       -- 离开时间
+--     NULL,                         -- 回岗时间（未回岗）
+--     NULL,                         -- 持续时长（未知）
+--     'NEW'                         -- 告警状态
+-- );
+
+-- 阶段2：人员回岗（resolve）
+-- UPDATE alarm_event SET
+--     last_frame_time = '2026-02-13 14:15:00',  -- 回岗时间
+--     duration_ms = 900000,                     -- 持续时长（15分钟）
+--     alarm_status = 'CLOSED',                  -- 状态：已关闭
+--     handle_status = 'DONE',                   -- 处理状态：完成
+--     handle_remark = '人员回岗自动关闭',        -- 处理备注
+--     handled_at = NOW()                        -- 处理时间
+-- WHERE alarm_id = 'ALM20260213140500ABCD';
+
+-- ============================================================================
+
+-- 验证查询：检查表结构
+-- ----------------------------------------------------------------------------
+
+SELECT
+    COLUMN_NAME AS '字段名',
+    DATA_TYPE AS '数据类型',
+    IS_NULLABLE AS '可空',
+    COLUMN_COMMENT AS '字段注释'
+FROM INFORMATION_SCHEMA.COLUMNS
+WHERE TABLE_SCHEMA = DATABASE()
+  AND TABLE_NAME = 'alarm_event'
+  AND COLUMN_NAME IN ('event_time', 'first_frame_time', 'last_frame_time', 'duration_ms')
+ORDER BY ORDINAL_POSITION;
+
+-- 预期结果：
+-- +------------------+-----------+-----------+------------------------+
+-- | 字段名           | 数据类型  | 可空      | 字段注释               |
+-- +------------------+-----------+-----------+------------------------+
+-- | event_time       | datetime  | NO        | 事件发生时间           |
+-- | first_frame_time | datetime  | YES       | 首帧时间               |
+-- | last_frame_time  | datetime  | YES       | 末帧时间               |
+-- | duration_ms      | int       | YES       | 持续时长(毫秒)         |
+-- +------------------+-----------+-----------+------------------------+
+
+-- ============================================================================
+
+-- 验证查询：查看未回岗的告警（duration_ms=NULL）
+-- ----------------------------------------------------------------------------
+
+SELECT
+    alarm_id AS '告警ID',
+    alarm_type AS '告警类型',
+    event_time AS '告警时间',
+    first_frame_time AS '离开时间',
+    last_frame_time AS '回岗时间',
+    duration_ms AS '持续时长(ms)',
+    alarm_status AS '告警状态',
+    CASE
+        WHEN last_frame_time IS NULL AND duration_ms IS NULL
+        THEN '人员未回岗'
+        ELSE '已完成'
+    END AS '状态说明'
+FROM alarm_event
+WHERE alarm_type = 'leave_post'
+  AND alarm_status IN ('NEW', 'CONFIRMED')
+ORDER BY event_time DESC
+LIMIT 10;
+
+-- ============================================================================
+
+-- 部署说明
+-- ----------------------------------------------------------------------------
+-- 1. 此脚本无需执行DDL变更
+-- 2. 字段语义已在原始schema中正确定义
+-- 3. 代码层面已按两阶段模型实现：
+--    - 算法层：告警触发时不发送 duration_minutes
+--    - 服务层：告警创建时 duration_ms=NULL
+--    - 服务层：resolve_alarm 填充 duration_ms 和 last_frame_time
+-- 4. 数据库现有字段支持两阶段模型，无需迁移
+--
+-- ============================================================================