security-ai-edge/docs/code_review_report.md

# algorithms.py 代码审查报告

> 审查日期: 2026-04-02
> 审查文件: algorithms.py (1733行)
> 审查范围: LeavePostAlgorithm, IntrusionAlgorithm, IllegalParkingAlgorithm, VehicleCongestionAlgorithm, AlgorithmManager

---

## 1. 功能基线清单

### 1.1 LeavePostAlgorithm (离岗检测)

**状态定义 (7个):**

| 状态 | 常量 | 含义 |
|------|------|------|
| INIT | `STATE_INIT` | 初始化，等待检测到人 |
| CONFIRMING_ON_DUTY | `STATE_CONFIRMING_ON_DUTY` | 上岗确认中（需持续检测到人） |
| ON_DUTY | `STATE_ON_DUTY` | 已确认在岗 |
| CONFIRMING_OFF_DUTY | `STATE_CONFIRMING_OFF_DUTY` | 离岗确认中（持续未检测到人） |
| OFF_DUTY_COUNTDOWN | `STATE_OFF_DUTY_COUNTDOWN` | 离岗倒计时（确认离岗后等待告警） |
| ALARMED | `STATE_ALARMED` | 已告警（等待回岗） |
| NON_WORK_TIME | `STATE_NON_WORK_TIME` | 非工作时间 |

**状态转换矩阵:**

| 从 \ 到 | INIT | CONFIRMING_ON_DUTY | ON_DUTY | CONFIRMING_OFF_DUTY | OFF_DUTY_COUNTDOWN | ALARMED | NON_WORK_TIME |
|---------|------|--------------------|---------|--------------------|-------------------|---------|--------------|
| INIT | - | roi_has_person==True | - | - | - | - | not in_working_hours |
| CONFIRMING_ON_DUTY | detection_ratio==0 | - | elapsed>=confirm_on_duty_sec AND ratio>=0.6 | - | - | - | not in_working_hours |
| ON_DUTY | - | - | - | detection_ratio<0.2 | - | - | not in_working_hours |
| CONFIRMING_OFF_DUTY | - | - | detection_ratio>=0.5 | - | elapsed>=confirm_off_duty_sec AND ratio<0.2 | - | not in_working_hours |
| OFF_DUTY_COUNTDOWN | - | - | roi_has_person==True | - | - | elapsed>=leave_countdown_sec AND cooldown ok | not in_working_hours |
| ALARMED | - | roi_has_person==True | - | - | - | - | not in_working_hours |
| NON_WORK_TIME | in_working_hours | - | - | - | - | - | - |

**关键行为:**
- 使用滑动窗口（10秒）平滑检测结果，计算 detection_ratio
- ALARMED -> CONFIRMING_ON_DUTY 复用上岗确认状态（不是独立的回岗确认状态）
- 进入 ON_DUTY 状态时，若存在 `_last_alarm_id`，自动发送 `alarm_resolve` 事件
- 进入 NON_WORK_TIME 时，若有未结束告警，发送 resolve_type="non_work_time" 的 resolve 事件
- 冷却期检查使用 `cooldown_key = f"{camera_id}_{roi_id}"`
- `_last_alarm_id` 由外部 main.py 通过 `set_last_alarm_id()` 回填
- `_leave_start_time` 在进入 OFF_DUTY_COUNTDOWN 时记录（值等于 state_start_time）

**构造函数参数:**
- `confirm_on_duty_sec`: int = 10 (上岗确认窗口)
- `confirm_off_duty_sec`: int = 30 (离岗确认窗口)
- `confirm_return_sec`: int = 10 (回岗确认窗口 -- 注意: 代码中实际未使用此参数)
- `leave_countdown_sec`: int = 300 (离岗倒计时)
- `cooldown_sec`: int = 600 (告警冷却期)
- `working_hours`: Optional[List[Dict]] = None
- `target_class`: Optional[str] = "person"
- `alarm_level`: Optional[int] = None (默认2)
- `confirm_leave_sec`: Optional[int] = None (向后兼容旧参数名)

### 1.2 IntrusionAlgorithm (周界入侵)

**状态定义 (4个):**

| 状态 | 常量 | 含义 |
|------|------|------|
| IDLE | `STATE_IDLE` | 空闲，无入侵 |
| CONFIRMING_INTRUSION | `STATE_CONFIRMING_INTRUSION` | 入侵确认中 |
| ALARMED | `STATE_ALARMED` | 已告警（等待入侵消失） |
| CONFIRMING_CLEAR | `STATE_CONFIRMING_CLEAR` | 入侵消失确认中 |

**状态转换矩阵:**

| 从 \ 到 | IDLE | CONFIRMING_INTRUSION | ALARMED | CONFIRMING_CLEAR |
|---------|------|---------------------|---------|-----------------|
| IDLE | - | roi_has_person==True | - | - |
| CONFIRMING_INTRUSION | not roi_has_person OR cooldown内 OR state_start_time==None | - | elapsed>=confirm_intrusion_seconds AND cooldown ok | - |
| ALARMED | - | - | - | not roi_has_person |
| CONFIRMING_CLEAR | elapsed>=confirm_clear_seconds AND no person | - | person_elapsed>=confirm_intrusion_seconds (持续有人) OR state_start_time==None | - |

**关键行为:**
- 不使用滑动窗口，直接使用当前帧的 `roi_has_person` 判断
- CONFIRMING_CLEAR 有子状态追踪: `_person_detected_in_clear_time` 用于判断短暂有人 vs 持续有人
- 冷却期内入侵确认直接回到 IDLE（不触发告警）
- 包含防御性编程: state_start_time==None 时重置到 IDLE
- `_check_target_class` 允许 target_class 为 None（匹配所有类别）

**构造函数参数:**
- `cooldown_seconds`: int = 300
- `confirm_seconds`: int = 5 (向后兼容)
- `confirm_intrusion_seconds`: Optional[int] = None (默认使用 confirm_seconds)
- `confirm_clear_seconds`: Optional[int] = None (默认180)
- `target_class`: Optional[str] = None
- `alarm_level`: Optional[int] = None (默认1)

### 1.3 IllegalParkingAlgorithm (车辆违停)

**状态定义 (5个):**

| 状态 | 常量 | 含义 |
|------|------|------|
| IDLE | `STATE_IDLE` | 空闲 |
| CONFIRMING_VEHICLE | `STATE_CONFIRMING_VEHICLE` | 车辆确认中 |
| PARKED_COUNTDOWN | `STATE_PARKED_COUNTDOWN` | 违停倒计时 |
| ALARMED | `STATE_ALARMED` | 已告警 |
| CONFIRMING_CLEAR | `STATE_CONFIRMING_CLEAR` | 消失确认中 |

**状态转换矩阵:**

| 从 \ 到 | IDLE | CONFIRMING_VEHICLE | PARKED_COUNTDOWN | ALARMED | CONFIRMING_CLEAR |
|---------|------|-------------------|-----------------|---------|-----------------|
| IDLE | - | roi_has_vehicle | - | - | - |
| CONFIRMING_VEHICLE | ratio<0.3 OR state_start_time==None | - | elapsed>=confirm_vehicle_sec AND ratio>=0.6 | - | - |
| PARKED_COUNTDOWN | ratio<0.2 (车离开) OR cooldown内 OR state_start_time==None | - | - | elapsed>=parking_countdown_sec AND cooldown ok | - |
| ALARMED | - | - | - | - | ratio<0.15 |
| CONFIRMING_CLEAR | elapsed>=confirm_clear_sec AND ratio<0.2 OR state_start_time==None | - | - | ratio>=0.5 | - |

**关键行为:**
- 使用滑动窗口（WINDOW_SIZE_SEC=10秒）
- 支持多类车辆: target_classes 默认 ["car", "truck", "bus", "motorcycle"]
- 告警字段包含 `confidence` 和 `duration_minutes`
- CONFIRMING_CLEAR -> IDLE 时清除 alert_cooldowns（新车违停可正常告警）
- ALARMED 进入 CONFIRMING_CLEAR 的阈值(0.15)比其他算法更严格

**构造函数参数:**
- `confirm_vehicle_sec`: int = 15
- `parking_countdown_sec`: int = 300
- `confirm_clear_sec`: int = 120
- `cooldown_sec`: int = 1800
- `target_classes`: Optional[List[str]] = None (默认 ["car", "truck", "bus", "motorcycle"])
- `alarm_level`: Optional[int] = None (默认1)

### 1.4 VehicleCongestionAlgorithm (车辆拥堵)

**状态定义 (4个):**

| 状态 | 常量 | 含义 |
|------|------|------|
| NORMAL | `STATE_NORMAL` | 正常 |
| CONFIRMING_CONGESTION | `STATE_CONFIRMING_CONGESTION` | 拥堵确认中 |
| CONGESTED | `STATE_CONGESTED` | 拥堵中 |
| CONFIRMING_CLEAR | `STATE_CONFIRMING_CLEAR` | 消散确认中 |

**状态转换矩阵:**

| 从 \ 到 | NORMAL | CONFIRMING_CONGESTION | CONGESTED | CONFIRMING_CLEAR |
|---------|--------|----------------------|-----------|-----------------|
| NORMAL | - | avg_count >= count_threshold | - | - |
| CONFIRMING_CONGESTION | avg_count < count_threshold OR cooldown内 OR state_start_time==None | - | elapsed >= confirm_congestion_sec AND cooldown ok | - |
| CONGESTED | - | - | - | avg_count < count_threshold * 0.5 |
| CONFIRMING_CLEAR | elapsed >= confirm_clear_sec OR state_start_time==None | - | avg_count >= count_threshold | - |

**关键行为:**
- 使用滑动窗口（WINDOW_SIZE_SEC=10秒）存储车辆计数，取平均值判断
- 消散需车辆数降到阈值的 **50%** 以下才开始确认（避免抖动）
- CONFIRMING_CLEAR -> NORMAL 时清除 alert_cooldowns
- 告警字段包含 `vehicle_count` 和 `confidence`

**构造函数参数:**
- `count_threshold`: int = 5
- `confirm_congestion_sec`: int = 60
- `confirm_clear_sec`: int = 180
- `cooldown_sec`: int = 1800
- `target_classes`: Optional[List[str]] = None (默认 ["car", "truck", "bus", "motorcycle"])
- `alarm_level`: Optional[int] = None (默认2)

### 1.5 AlgorithmManager

**数据结构:**
```
self.algorithms: Dict[str, Dict[str, Dict[str, Algorithm]]]
  结构: { roi_id: { "{roi_id}_{bind_id}": { algo_type: algo_instance } } }
```

**公开方法:**
- `start_config_subscription()` - 启动 Redis 配置订阅
- `stop_config_subscription()` - 停止配置订阅
- `load_bind_from_redis(bind_id)` - 从 Redis 加载单个绑定配置
- `reload_bind_algorithm(bind_id)` - 重载单个绑定
- `reload_algorithm(roi_id)` - 重载单个 ROI 的所有算法
- `update_algorithm_params(roi_id, bind_id, bind_config)` - 仅更新参数，保留状态
- `reload_all_algorithms(preserve_state=True)` - 重载全部算法
- `register_algorithm(roi_id, bind_id, algorithm_type, params)` - 注册算法（带缓存）
- `process(roi_id, bind_id, camera_id, algorithm_type, tracks, current_time)` - 处理检测结果
- `update_roi_params(roi_id, bind_id, algorithm_type, params)` - 更新参数
- `reset_algorithm(roi_id, bind_id=None)` - 重置算法状态
- `reset_all()` - 重置所有算法
- `remove_roi(roi_id)` - 移除 ROI
- `remove_bind(roi_id, bind_id)` - 移除绑定
- `get_status(roi_id)` - 获取状态

---

## 2. 接口契约清单

### 2.1 process() 方法统一签名

所有四个算法的 `process()` 方法具有相同签名:

```python
def process(
    self,
    roi_id: str,
    camera_id: str,
    tracks: List[Dict],
    current_time: Optional[datetime] = None,
) -> List[Dict]
```

**tracks 输入格式 (每个元素):**
```python
{
    "track_id": str,           # 跟踪ID
    "class": str,              # 检测类别 ("person", "car", "truck", ...)
    "confidence": float,       # 置信度
    "bbox": List[float],       # 边界框 [x1, y1, x2, y2]
    "matched_rois": [          # 匹配的ROI列表
        {"roi_id": str}
    ],
}
```

### 2.2 告警输出格式

#### LeavePostAlgorithm 告警:
```python
{
    "track_id": str,           # 等于 roi_id
    "camera_id": str,
    "bbox": List[float],       # 可能为空 []
    "alert_type": "leave_post",
    "alarm_level": int,        # 默认 2
    "message": "人员离岗告警",
    "first_frame_time": str,   # 格式: '%Y-%m-%d %H:%M:%S'
}
```
注意: leave_post 告警使用 `track_id` 而非 `roi_id` 字段名（与其他算法不同）。

#### IntrusionAlgorithm 告警:
```python
{
    "roi_id": str,
    "camera_id": str,
    "bbox": List[float],
    "alert_type": "intrusion",
    "alarm_level": int,        # 默认 1
    "message": "检测到周界入侵",
    "first_frame_time": str,   # 格式: '%Y-%m-%d %H:%M:%S'
}
```

#### IllegalParkingAlgorithm 告警:
```python
{
    "roi_id": str,
    "camera_id": str,
    "bbox": List[float],
    "alert_type": "illegal_parking",
    "alarm_level": int,        # 默认 1
    "confidence": float,
    "message": str,            # 动态生成，包含停留分钟数
    "first_frame_time": str,   # 格式: '%Y-%m-%d %H:%M:%S'，可能为 None
    "duration_minutes": float,
}
```

#### VehicleCongestionAlgorithm 告警:
```python
{
    "roi_id": str,
    "camera_id": str,
    "bbox": List[float],
    "alert_type": "vehicle_congestion",
    "alarm_level": int,        # 默认 2
    "confidence": float,
    "message": str,            # 动态生成，包含平均车辆数和持续秒数
    "first_frame_time": str,   # 格式: '%Y-%m-%d %H:%M:%S'，可能为 None
    "vehicle_count": int,
}
```

#### alarm_resolve 事件 (所有算法统一格式):
```python
{
    "alert_type": "alarm_resolve",
    "resolve_alarm_id": str,
    "duration_ms": int,
    "last_frame_time": str,    # 格式: '%Y-%m-%d %H:%M:%S'
    "resolve_type": str,       # "person_returned" | "non_work_time" | "intrusion_cleared" | "vehicle_left" | "congestion_cleared"
}
```

### 2.3 AlgorithmManager.process() 签名

```python
def process(
    self,
    roi_id: str,
    bind_id: str,
    camera_id: str,
    algorithm_type: str,
    tracks: List[Dict],
    current_time: Optional[datetime] = None,
) -> List[Dict]
```

### 2.4 AlgorithmManager.register_algorithm() 签名

```python
def register_algorithm(
    self,
    roi_id: str,
    bind_id: str,
    algorithm_type: str,                 # "leave_post" | "intrusion" | "illegal_parking" | "vehicle_congestion"
    params: Optional[Dict[str, Any]] = None,
)
```

---

## 3. 已发现的潜在问题

### 3.1 Critical (必须修复)

**[C1] LeavePostAlgorithm: `confirm_return_sec` 参数声明但从未使用**
- 位置: 第53行声明，但状态机中 ALARMED -> CONFIRMING_ON_DUTY -> ON_DUTY 的转换直接复用 `confirm_on_duty_sec`
- 影响: 使用者设置 `confirm_return_sec` 以为可以独立控制回岗确认时长，但实际无效
- 建议: 文档中声明此参数复用 `confirm_on_duty_sec`，或实现独立的回岗确认逻辑

**[C2] LeavePostAlgorithm: resolve 事件的 duration_ms 计算依赖 `_leave_start_time`，但该值可能为 None**
- 位置: 第325行 `duration_ms = int((current_time - self._leave_start_time).total_seconds() * 1000)`
- 场景: 如果算法在 OFF_DUTY_COUNTDOWN 之前（即 _leave_start_time 赋值之前）因某种异常跳到 ON_DUTY 且 _last_alarm_id 非空，会抛出 TypeError
- 风险: 低概率但会导致该帧整个 process 调用抛异常

**[C3] LeavePostAlgorithm: `_leave_start_time` 赋值时机问题**
- 位置: 第277行 `self._leave_start_time = self.state_start_time`
- `state_start_time` 此时是 CONFIRMING_OFF_DUTY 的开始时间（非 OFF_DUTY_COUNTDOWN 的开始时间，因为 state_start_time 在下一行第276行才被更新为 current_time）
- 实际效果: `_leave_start_time` 记录的是**离岗确认开始时间**，不是**倒计时开始时间**
- 审查结论: 这是有意设计，离开时间应该从人离开被确认开始计算，但代码注释"记录离开时间"可能造成误解

### 3.2 Important (应该修复)

**[I1] LeavePostAlgorithm 告警字典使用 `track_id` 而非 `roi_id`**
- 位置: 第299行 `"track_id": roi_id`
- 其他三个算法统一使用 `"roi_id": roi_id`
- 影响: main.py 中的 `_handle_detections` 不直接使用此字段（它有自己的 roi_id），所以不影响功能，但接口不一致

**[I2] AlgorithmManager 缺乏线程安全**
- `process()` 方法未加锁（第1637-1651行），而 `register_algorithm()` 也未加锁
- `_update_lock` 仅在 `load_bind_from_redis` 和 `reload_all_algorithms` 中使用
- 风险: 如果 config_update_worker 线程调用 `reload_all_algorithms` 同时主线程调用 `process`，可能读到不一致的 `self.algorithms` 字典
- 缓解: Python GIL 在字典读操作上提供了一定程度的原子性保护，实际崩溃概率很低

**[I3] AlgorithmManager.default_params 中 illegal_parking 的 confirm_clear_sec 默认值(30) 与 IllegalParkingAlgorithm 构造函数默认值(120) 不一致**
- 位置: 第1233行 vs 第751行
- 影响: 通过 AlgorithmManager 创建的 illegal_parking 算法 confirm_clear_sec 为 30，直接创建为 120

**[I4] AlgorithmManager.default_params 中 vehicle_congestion 的 count_threshold 默认值(3) 与 VehicleCongestionAlgorithm 构造函数默认值(5) 不一致**
- 位置: 第1237行 vs 第1004行
- 影响: 通过 AlgorithmManager 创建的算法阈值为 3，直接创建为 5

**[I5] `update_algorithm_params` 仅支持 leave_post 和 intrusion**
- 位置: 第1461-1496行
- 缺少 illegal_parking 和 vehicle_congestion 的参数更新逻辑（第1494行注释 "其他算法类型可以在此添加"）
- 影响: `reload_all_algorithms(preserve_state=True)` 对 illegal_parking/vehicle_congestion 会回退到 `load_bind_from_redis`，会重置算法状态

**[I6] `load_bind_from_redis` 仅支持 leave_post 和 intrusion**
- 位置: 第1322-1403行
- 缺少 illegal_parking 和 vehicle_congestion 的 Redis 加载逻辑
- 影响: 从 Redis 热更新配置时，这两种算法无法被加载

**[I7] IntrusionAlgorithm: `_get_latest_bbox` 不检查 target_class**
- 位置: 第456-460行
- 与 LeavePostAlgorithm 不同（第139-142行会检查 target_class）
- 影响: 可能返回非目标类别的 bbox

**[I8] `_is_in_working_hours` 不支持跨午夜时间段**
- 位置: 第112行 `if start_minutes <= current_minutes < end_minutes`
- 如果 working_hours 配置为 `{"start": "22:00", "end": "06:00"}`，则无法正确判断
- 影响: 夜班场景可能不工作

### 3.3 Suggestions (建议改进)

**[S1] 滑动窗口的 window_size_sec 硬编码为 10 秒**
- LeavePostAlgorithm 第80行: `self.window_size_sec = 10`
- IllegalParkingAlgorithm 第744行: `WINDOW_SIZE_SEC = 10`
- VehicleCongestionAlgorithm 第1000行: `WINDOW_SIZE_SEC = 10`
- 建议: 提取为可配置参数

**[S2] LeavePostAlgorithm._update_detection_window 与 IllegalParkingAlgorithm._update_window 实现逻辑相同但代码重复**
- 可提取为基类方法或工具函数

**[S3] LeavePostAlgorithm.get_state() 使用 datetime.now() 而非参数传入的 current_time**
- 位置: 第367-372行
- 在测试场景中会导致状态信息不准确（不影响核心逻辑，仅影响监控展示）

**[S4] AlgorithmManager.get_status() 中 leave_post 分支访问 `alarm_sent` 属性**
- 位置: 第1724行
- LeavePostAlgorithm 实际上没有 `alarm_sent` 属性，getattr 返回 False
- 这是旧版本残留代码

**[S5] AlgorithmManager.remove_roi() 中 bind_id 解析逻辑脆弱**
- 位置: 第1703行 `key.split("_")[-1]`
- 如果 bind_id 本身包含下划线，解析会出错
- key 格式为 `"{roi_id}_{bind_id}"`，应该用 `key[len(roi_id)+1:]` 提取 bind_id

**[S6] `_is_in_working_hours` 中的 bare `except:` (第99行, 第124行)**
- 应该至少 except Exception 或更具体的异常类型

---

## 4. 测试覆盖分析

### 4.1 test_leave_post_full_workflow.py 覆盖的场景

| 场景 | 状态路径 | 覆盖 |
|------|----------|------|
| 上岗确认成功 | INIT -> CONFIRMING_ON_DUTY -> ON_DUTY | YES |
| 离岗确认 | ON_DUTY -> CONFIRMING_OFF_DUTY -> OFF_DUTY_COUNTDOWN | YES |
| 倒计时触发告警 | OFF_DUTY_COUNTDOWN -> ALARMED | YES |
| 回岗 resolve | ALARMED -> CONFIRMING_ON_DUTY -> ON_DUTY (+ resolve) | YES |
| 告警字段验证 | 无 duration_minutes, 有 first_frame_time | YES |
| resolve 字段验证 | duration_ms, resolve_alarm_id, resolve_type | YES |
| set_last_alarm_id 回填 | - | YES |

### 4.2 test_vehicle_algorithms.py 覆盖的场景

**IllegalParkingAlgorithm:**
| 场景 | 覆盖 |
|------|------|
| 完整生命周期 IDLE->CONFIRMING->COUNTDOWN->ALARMED->CLEAR->IDLE | YES |
| 车辆短暂路过不触发 | YES |
| 多类车辆检测 (truck, bus) | YES |
| person 不触发违停 | YES |
| 冷却期内不重复告警 | YES |
| resolve 事件发送 | YES |

**VehicleCongestionAlgorithm:**
| 场景 | 覆盖 |
|------|------|
| 完整生命周期 NORMAL->CONFIRMING->CONGESTED->CLEAR->NORMAL | YES |
| 少于阈值不触发 | YES |
| 短暂拥堵不触发 | YES |
| resolve 事件发送 | YES |

**AlgorithmManager:**
| 场景 | 覆盖 |
|------|------|
| 注册 illegal_parking | YES |
| 注册 vehicle_congestion | YES |
| process 调用 | YES |
| get_status 调用 | YES |
| 重复注册走缓存 | YES |
| reset_algorithm | YES |

### 4.3 测试覆盖缺口

**LeavePostAlgorithm 未覆盖:**
- [ ] CONFIRMING_ON_DUTY -> INIT (人消失)
- [ ] CONFIRMING_OFF_DUTY -> ON_DUTY (人回来，ratio>=0.5)
- [ ] OFF_DUTY_COUNTDOWN -> ON_DUTY (倒计时期间回来)
- [ ] 非工作时间自动 resolve
- [ ] NON_WORK_TIME -> INIT (工作时间恢复)
- [ ] 冷却期内不重复告警
- [ ] 空 tracks 输入
- [ ] working_hours 配置解析（字符串格式）

**IntrusionAlgorithm 完全未测试:**
- [ ] 完整生命周期 IDLE->CONFIRMING->ALARMED->CLEAR->IDLE
- [ ] 入侵确认中人消失
- [ ] CONFIRMING_CLEAR 中短暂有人 vs 持续有人
- [ ] 冷却期
- [ ] resolve 事件
- [ ] target_class=None 匹配所有类别
- [ ] state_start_time==None 的防御性代码分支

**IllegalParkingAlgorithm 未覆盖:**
- [ ] state_start_time==None 的防御性代码分支 (CONFIRMING_VEHICLE, PARKED_COUNTDOWN, CONFIRMING_CLEAR)
- [ ] CONFIRMING_CLEAR -> ALARMED (车辆又出现, ratio>=0.5)
- [ ] ALARMED 状态下 ratio 在 0.15-0.5 之间（维持 ALARMED）

**VehicleCongestionAlgorithm 未覆盖:**
- [ ] state_start_time==None 的防御性代码分支
- [ ] CONFIRMING_CLEAR -> CONGESTED (又拥堵了)
- [ ] 消散阈值 0.5*count_threshold 的边界值
- [ ] 冷却期测试

**AlgorithmManager 未覆盖:**
- [ ] start_config_subscription / stop_config_subscription
- [ ] load_bind_from_redis
- [ ] reload_all_algorithms (含孤立实例清理)
- [ ] update_algorithm_params
- [ ] remove_roi / remove_bind
- [ ] 并发调用安全性
- [ ] register_algorithm 的 leave_post 和 intrusion 类型

---

## 5. 优化安全边界

### 5.1 不可修改区域 (功能合约)

以下代码是外部依赖的契约，修改会破坏 main.py 或其他模块：

1. **所有算法的 `process()` 方法签名** -- main.py 的 `_handle_detections` 直接调用
2. **告警字典的字段名和类型** -- main.py 的 `_handle_detections` 依赖 `alert_type`, `alarm_level`, `confidence`, `bbox`, `message`, `first_frame_time`, `duration_minutes`, `vehicle_count`
3. **`alarm_resolve` 事件格式** -- main.py 的 resolve 逻辑依赖 `resolve_alarm_id`, `duration_ms`, `last_frame_time`, `resolve_type`
4. **`set_last_alarm_id(alarm_id)` 方法** -- main.py 回填 alarm_id
5. **`reset()` 方法** -- AlgorithmManager 调用
6. **`get_state()` 方法** -- AlgorithmManager.get_status() 调用
7. **AlgorithmManager.process() 签名和返回值** -- main.py 直接调用
8. **AlgorithmManager.register_algorithm() 签名** -- main.py 直接调用
9. **AlgorithmManager.algorithms 的三层字典结构** -- main.py 直接访问内部实例来获取 `_leave_start_time` 等属性 (第905-911行)

### 5.2 可安全优化区域

以下代码修改不会影响外部行为：

1. **滑动窗口实现** -- `_update_detection_window`, `_update_window`, `_update_count_window` 的内部实现可以优化，只要 `_get_detection_ratio()`, `_get_window_ratio()`, `_get_avg_count()` 的语义不变
2. **`_check_detection_in_roi` / `_check_target_class` / `_check_target_classes`** -- 内部实现可优化，接口不变即可
3. **`_get_latest_bbox` / `_get_max_confidence`** -- 辅助方法，内部实现可优化
4. **`_is_in_working_hours` / `_parse_time_to_minutes`** -- 内部实现可优化（建议修复跨午夜问题）
5. **AlgorithmManager 的 Redis 相关方法** -- `load_bind_from_redis`, `reload_*`, `_config_update_worker` 可以修改，不影响算法核心逻辑
6. **日志输出** -- 所有 logger.* 调用可以调整
7. **`default_params` 字典** -- 可以修正默认值不一致的问题

### 5.3 高风险修改区域 (需要完整回归测试)

1. **状态转换条件 (ratio 阈值)** -- 任何 detection_ratio, window_ratio 的阈值变更都可能影响告警灵敏度
   - LeavePostAlgorithm: 0.6 (上岗), 0.2 (离岗开始), 0.5 (离岗恢复), 0.2 (离岗确认)
   - IllegalParkingAlgorithm: 0.3 (放弃确认), 0.6 (确认有车), 0.2 (车离开), 0.15 (开始消失确认), 0.5 (车又来), 0.2 (消失确认)
   - VehicleCongestionAlgorithm: count_threshold (开始确认), 0.5*count_threshold (开始消散)

2. **时间比较逻辑** -- `elapsed >= xxx_sec` 的方向（大于等于 vs 大于）
3. **冷却期检查** -- `cooldown_key` 的构造方式和比较逻辑
4. **resolve 事件触发逻辑** -- LeavePostAlgorithm 的 "进入 ON_DUTY 且 _last_alarm_id 存在" 的检查

### 5.4 重复代码可提取区域

以下方法在多个算法中重复实现，可以提取为基类或 mixin：

| 方法 | 出现在 | 可提取 |
|------|--------|--------|
| `_check_detection_in_roi` | 全部4个 | YES |
| `_check_target_class` | LeavePost, Intrusion | YES |
| `_check_target_classes` | IllegalParking, VehicleCongestion | YES |
| `_get_latest_bbox` | 全部4个 | YES (注意 Intrusion 不检查 target_class) |
| `_get_max_confidence` | IllegalParking, VehicleCongestion | YES |
| `set_last_alarm_id` | 全部4个 | YES |
| 滑动窗口逻辑 | LeavePost, IllegalParking, VehicleCongestion | YES |

---

## 6. config_models.py 与 algorithms.py 的一致性

### 6.1 AlgorithmType 枚举缺失

`config_models.py` 中的 `AlgorithmType` 枚举:
```python
LEAVE_POST = "leave_post"
INTRUSION = "intrusion"
CROWD_DETECTION = "crowd_detection"   # 已在 algorithms.py 中注释掉
FACE_RECOGNITION = "face_recognition" # algorithms.py 中不存在
```

缺失:
- `ILLEGAL_PARKING = "illegal_parking"` -- algorithms.py 已实现但枚举未添加
- `VEHICLE_CONGESTION = "vehicle_congestion"` -- algorithms.py 已实现但枚举未添加

### 6.2 ROIInfo 默认值

`config_models.py` 的 `ROIInfo.confirm_leave_sec` 默认值为 **10**，而 `AlgorithmManager.default_params["leave_post"]["confirm_leave_sec"]` 为 **30**，`LeavePostAlgorithm.confirm_off_duty_sec` 默认为 **30**。

---

## 7. main.py 集成要点

### 7.1 main.py 对 algorithms.py 的依赖

1. **直接访问算法内部属性** (第905-911行):
   ```python
   for attr in ('_leave_start_time', '_parking_start_time', '_congestion_start_time', '_intrusion_start_time'):
       val = getattr(algo, attr, None)
   ```
   这是紧耦合，如果内部属性名变更会导致 first_frame_time 丢失。

2. **alarm_id 回填** (第943-945行):
   ```python
   algo.set_last_alarm_id(alarm_info.alarm_id)
   ```

3. **两层去重机制**:
   - ROI级别: `_active_alarms[f"{roi_id}_{alert_type}"]`
   - 摄像头级别: `_camera_alert_cooldown[f"{camera_id}_{alert_type}"]` (30秒冷却)

4. **duration_ms 在 ext_data 中的计算** (第925行):
   ```python
   "duration_ms": int(alert.get("duration_minutes", 0) * 60 * 1000) if alert.get("duration_minutes") else None,
   ```
   仅 IllegalParkingAlgorithm 的告警包含 `duration_minutes`，其他算法的 ext_data.duration_ms 为 None。

---

## 附录: 状态机可视化

### LeavePostAlgorithm
```
         +--> NON_WORK_TIME --+
         |  (any state)       |  (in_working_hours)
         |                    v
  INIT --+--> CONFIRMING_ON_DUTY ---> ON_DUTY ---> CONFIRMING_OFF_DUTY
    ^          |        ^                              |
    +----------+        |                              v
   (ratio==0)           |                    OFF_DUTY_COUNTDOWN
                        |                       |          |
                        |     (roi_has_person)  |          v
                        |       +---------------+       ALARMED
                        |       |                          |
                        +-------+  (roi_has_person)        |
                              ON_DUTY <-- (if _last_alarm_id, send resolve)
```

### IntrusionAlgorithm
```
  IDLE ---> CONFIRMING_INTRUSION ---> ALARMED ---> CONFIRMING_CLEAR ---> IDLE
    ^            |                                     |        |
    +------------+                                     +--------+
   (person gone)                                  (person back >= confirm_intrusion_sec)
                                                  -> ALARMED
```

### IllegalParkingAlgorithm
```
  IDLE --> CONFIRMING_VEHICLE --> PARKED_COUNTDOWN --> ALARMED --> CONFIRMING_CLEAR --> IDLE
    ^          |                       |                              |
    +----------+                       |                              v
  (ratio<0.3)              (ratio<0.2) |                           ALARMED
    ^                          |       |                          (ratio>=0.5)
    +--------------------------+       v
                                    ALARMED
```

### VehicleCongestionAlgorithm
```
  NORMAL --> CONFIRMING_CONGESTION --> CONGESTED --> CONFIRMING_CLEAR --> NORMAL
    ^              |                                      |
    +--------------+                                      v
  (avg<threshold)                                      CONGESTED
                                                    (avg>=threshold)
```