# 周界入侵算法 - 自动告警处理机制

## 功能说明

当周界入侵告警触发后,如果入侵者离开ROI区域,系统会自动进入"入侵消失确认"流程。
连续 `confirm_seconds` 秒(默认5秒)检测无人后,自动将告警标记为"已处理"。

这个机制可以减轻人工处理负担,对于暂时性入侵或误触发的告警,系统能够自动识别并完成处理流程。

## 参数说明

### confirm_seconds(确认时间)

**双重用途**:
1. **入侵确认**: 持续检测到人达到该时间后,触发告警
2. **消失确认**: 告警后持续无人达到该时间后,自动结束告警

**默认值**: 5秒

**建议值**:
- 快速响应场景: 3秒
- 标准场景: 5秒
- 避免误报场景: 10秒

**注意事项**:
- 时间设置过短可能导致误报增加
- 时间设置过长可能延迟告警响应
- 入侵确认和消失确认使用相同的时间参数,确保逻辑对称

### cooldown_seconds(告警冷却期)

**用途**: 防止重复告警

**默认值**: 300秒(5分钟)

**说明**:
- 告警自动处理后,进入冷却期
- 冷却期内即使再次检测到入侵,也不会立即触发新告警
- 冷却期结束后,系统恢复正常监控状态

**建议值**:
- 高频活动区域: 60-120秒
- 标准场景: 300秒
- 重要安保区域: 600秒或更长

## 状态机流程

系统采用状态机模型管理告警生命周期:

```
IDLE (空闲)
  ↓ 检测到人
CONFIRMING_INTRUSION (入侵确认中,5秒)
  ↓ 确认成功
ALARMED (已告警,等待入侵消失)
  ↓ 检测到无人
CONFIRMING_CLEAR (消失确认中,5秒)
  ↓ 确认成功
IDLE (自动resolve,告警标记为已处理)
```

**状态说明**:

1. **IDLE (空闲)**: 初始状态,正常监控中
2. **CONFIRMING_INTRUSION (入侵确认中)**: 检测到人,开始计时确认
3. **ALARMED (已告警)**: 告警已触发,等待入侵者离开
4. **CONFIRMING_CLEAR (消失确认中)**: 检测到无人,开始计时确认自动处理
5. **回到IDLE**: 自动处理完成,进入冷却期

## 示例场景

### 场景1: 正常入侵和自动处理

```
时间轴:
00:00 - 人进入ROI
00:05 - 触发告警(持续5秒有人)
00:10 - 人离开ROI
00:15 - 自动resolve(持续5秒无人)
```

**系统行为**:
- 00:00-00:05: 状态为CONFIRMING_INTRUSION,持续检测到人
- 00:05: 触发告警,状态转为ALARMED,发送告警消息到平台
- 00:10: 检测到无人,状态转为CONFIRMING_CLEAR
- 00:15: 自动resolve,告警标记为已处理,进入300秒冷却期

### 场景2: 中途返回

```
时间轴:
00:00 - 人进入ROI
00:05 - 触发告警
00:10 - 人离开ROI
00:13 - 人又回来(消失确认中断)
00:20 - 人再次离开
00:25 - 自动resolve
```

**系统行为**:
- 00:00-00:05: 入侵确认中
- 00:05: 触发告警
- 00:10-00:13: 消失确认中(已计时3秒)
- 00:13: 检测到人返回,消失确认中断,返回ALARMED状态
- 00:20: 人再次离开,重新开始消失确认
- 00:25: 自动resolve成功

### 场景3: 持续入侵

```
时间轴:
00:00 - 人进入ROI
00:05 - 触发告警
... - 人持续在ROI内活动
05:00 - 人仍在ROI内
```

**系统行为**:
- 00:05: 触发告警后,持续保持ALARMED状态
- 告警不会自动resolve,需要人工处理
- 只有当检测到持续5秒无人后,才会自动resolve

### 场景4: 冷却期内再次入侵

```
时间轴:
00:00 - 第一次入侵,触发告警
00:15 - 自动resolve,进入冷却期
02:00 - 冷却期内再次检测到人(已过120秒)
```

**系统行为**:
- 00:15: 自动resolve后进入300秒冷却期
- 02:00: 仍在冷却期内(还剩180秒)
- 检测到人但不触发新告警
- 05:15: 冷却期结束,恢复正常监控

## 配置方法

### 方法1: 通过平台界面配置

1. 登录AIoT平台
2. 进入"设备管理" → "摄像头ROI配置"
3. 选择对应的周界入侵ROI
4. 修改参数:
   - **确认秒数**: 设置 `confirm_seconds` 值
   - **冷却秒数**: 设置 `cooldown_seconds` 值
5. 保存配置,系统自动下发到边缘端

### 方法2: 通过配置文件

编辑边缘端配置文件(如果支持本地配置):

```yaml
roi_config:
  - roi_id: "roi_001"
    algorithm: "intrusion"
    confirm_seconds: 5
    cooldown_seconds: 300
```

**注意**: 优先使用平台界面配置,确保配置统一管理。

## 监控与日志

### 日志示例

系统会记录关键状态转换:

```
[INFO] ROI roi_001: State transition: IDLE -> CONFIRMING_INTRUSION
[INFO] ROI roi_001: Intrusion confirmed after 5.0s, triggering alarm
[INFO] ROI roi_001: State transition: CONFIRMING_INTRUSION -> ALARMED
[INFO] ROI roi_001: Alarm sent: alarm_id_12345
[INFO] ROI roi_001: Person disappeared, starting clear confirmation
[INFO] ROI roi_001: State transition: ALARMED -> CONFIRMING_CLEAR
[INFO] ROI roi_001: Clear confirmed after 5.0s, auto-resolving alarm
[INFO] ROI roi_001: Alarm auto-resolved: alarm_id_12345
[INFO] ROI roi_001: State transition: CONFIRMING_CLEAR -> IDLE
[INFO] ROI roi_001: Entering cooldown for 300s
```

### 关键指标监控

建议监控以下指标:
- 告警触发频率
- 自动resolve比例
- 平均告警持续时间
- 冷却期触发频率

## 常见问题

### Q1: 为什么告警后很久才自动处理?

**可能原因**:
- 入侵者未完全离开ROI区域
- ROI区域划分过大,包含了正常通行区域
- confirm_seconds 参数设置过长

**解决方法**:
- 检查ROI区域划分是否合理
- 适当缩小ROI范围
- 调整 confirm_seconds 参数

### Q2: 为什么刚处理完又触发告警?

**可能原因**:
- 冷却期设置过短
- 该区域确实有持续的入侵活动

**解决方法**:
- 增加 cooldown_seconds 参数值
- 如果是正常活动区域,考虑取消周界入侵监控

### Q3: 自动处理机制会影响真实入侵的告警吗?

**不会**。自动处理仅在以下条件同时满足时触发:
1. 已触发告警
2. 持续检测无人达到 confirm_seconds
3. 未经人工处理

如果是真实持续入侵,入侵者不会离开,系统会持续保持告警状态,不会自动处理。

### Q4: 可以关闭自动处理功能吗?

目前自动处理功能是内置的,无法关闭。但您可以:
- 将 confirm_seconds 设置为较大值(如30秒),降低自动处理频率
- 重要区域的告警建议人工确认处理

### Q5: 自动处理后的告警记录会保留吗?

**会保留**。自动处理的告警记录会标记为"已处理(自动)",可以在告警历史中查询,包括:
- 告警触发时间
- 自动处理时间
- 告警持续时间
- 相关视频录像

## 最佳实践

### 1. 参数调优建议

**测试期**:
- confirm_seconds: 3秒(快速验证)
- cooldown_seconds: 60秒(观察频率)

**生产环境**:
- confirm_seconds: 5秒(平衡准确性和响应速度)
- cooldown_seconds: 300秒(标准值)

**重要安保区域**:
- confirm_seconds: 10秒(减少误报)
- cooldown_seconds: 600秒(人工确认为主)

### 2. ROI区域划分

- 避免包含正常通行路径
- 边界清晰,避免模糊地带
- 考虑摄像头视角和遮挡物
- 定期复核ROI区域合理性

### 3. 告警处理流程

1. 收到告警通知后,立即查看实时视频
2. 确认是否为真实入侵
3. 如需人工处理,及时标记
4. 定期分析自动resolve的告警,优化ROI配置

### 4. 系统维护

- 定期检查日志,识别异常模式
- 监控自动resolve比例(建议<70%)
- 如果自动resolve比例过高,考虑优化ROI或参数
- 定期清理历史告警数据

## 技术支持

如需帮助,请联系技术支持团队:
- 提供详细的告警时间和ROI ID
- 附带相关日志片段
- 说明当前配置参数

---

**文档版本**: v1.0
**最后更新**: 2025-02
**适用系统**: AIoT边缘智能分析系统