security-ai-edge/docs/garbage_algorithm_backend_frontend_plan.md

# 垃圾检测算法 - WVP 后端 / 前端改动方案（未实施，预留参考）

## 背景

Edge 端的 `GarbageDetectionAlgorithm` 已实现（commit xxx）。本文档列出 WVP 后端和前端需要做的配套改动，等后续需要在 ROI 编辑器创建垃圾检测绑定时再实施。

---

## 一、WVP 后端改动

### 1.1 算法注册（数据库）

**文件：** `wvp-platform/数据库/版本号/SQL 脚本`

**新增算法记录：**
```sql
INSERT INTO wvp_ai_algorithm (
    algo_code, algo_name, algo_description,
    is_active, param_schema, global_params
) VALUES (
    'garbage',
    '垃圾检测',
    '检测监控区域内散落垃圾的持续存在，清洁后自动解除告警',
    1,
    '{"confirm_garbage_sec": {"type": "int", "default": 60, "min": 10, "max": 600, "label": "垃圾确认时间(秒)"},
      "confirm_clear_sec": {"type": "int", "default": 60, "min": 10, "max": 600, "label": "清理确认时间(秒)"},
      "cooldown_sec": {"type": "int", "default": 1800, "min": 300, "max": 7200, "label": "告警冷却时间(秒)"},
      "alarm_level": {"type": "int", "default": 2, "min": 0, "max": 3, "label": "告警等级"}
     }',
    '{}'
);
```

### 1.2 Java 算法服务

**文件：** `wvp-platform/src/main/java/com/genersoft/iot/vmp/aiot/service/impl/AiAlgorithmServiceImpl.java`

**改动：** 算法代码白名单（约 line 42-54），添加 `"garbage"`：

```java
private static final Set<String> SUPPORTED_ALGO_CODES = Set.of(
    "leave_post", "intrusion", "illegal_parking",
    "vehicle_congestion", "non_motor_vehicle_parking",
    "garbage"  // 新增
);
```

### 1.3 配置下发

不需要改动。现有 `AiRedisConfigServiceImpl` 和 `global_params` 机制已通用。

---

## 二、iot-device-management-service 改动

**文件：** `app/constants.py`

检查 `AlarmType` 枚举是否已有 `GARBAGE`：
- 已有 → 无需改动
- 未有 → 添加：

```python
class AlarmType(str, Enum):
    LEAVE_POST = "leave_post"
    INTRUSION = "intrusion"
    ILLEGAL_PARKING = "illegal_parking"
    VEHICLE_CONGESTION = "vehicle_congestion"
    NON_MOTOR_VEHICLE_PARKING = "non_motor_vehicle_parking"
    GARBAGE = "garbage"  # 新增

ALARM_TYPE_NAMES: Dict[str, str] = {
    ...
    AlarmType.GARBAGE: "垃圾检测",
}
```

**文件：** `app/services/vlm_service.py`（VLM 复核提示词）

添加 garbage 的提示词模板：
```python
"garbage": """你是安防监控AI复核员。算法类型：垃圾检测，监控区域：{roi_name}。
截图显示时间：{timestamp}。
任务：判断图中是否真的存在散落的垃圾、包装袋、废弃物等需要清理的物品。
分析要点：
1. 是否存在明显的垃圾（垃圾袋、纸屑、瓶罐、食品包装等）
2. 区分垃圾与正常物品（整齐放置的物品、装饰品不算垃圾）
3. 垃圾是否在通道/地面等不该出现的位置
4. 排除阴影、污渍、地砖花纹等误检
仅输出JSON：{{"confirmed":true,"description":"..."}}""",
```

---

## 三、前端改动（iot-device-management-frontend）

### 3.1 告警列表类型筛选

**文件：** `apps/web-antd/src/views/aiot/alarm/list/data.ts`

```typescript
export const ALERT_TYPE_OPTIONS = [
  { label: '人员离岗', value: 'leave_post' },
  { label: '周界入侵', value: 'intrusion' },
  { label: '车辆违停', value: 'illegal_parking' },
  { label: '车辆拥堵', value: 'vehicle_congestion' },
  { label: '非机动车违停', value: 'non_motor_vehicle_parking' },
  { label: '垃圾检测', value: 'garbage' },  // 新增
];
```

### 3.2 告警标签颜色

**文件：** `apps/web-antd/src/views/aiot/alarm/list/index.vue`

```typescript
const colorMap: Record<string, string> = {
  leave_post: 'orange',
  intrusion: 'red',
  illegal_parking: 'blue',
  vehicle_congestion: 'geekblue',
  non_motor_vehicle_parking: 'green',
  garbage: 'gold',  // 新增 — 建议金色表达清洁主题
};
```

### 3.3 ROI 编辑器参数配置

**文件：** `apps/web-antd/src/views/aiot/device/roi/components/AlgorithmParamEditor.vue`

参数字段已通用（读自 `algo.paramSchema`），无需改动。**但需要添加参数名中文映射：**

**文件：** `AlgorithmParamEditor.vue` 的 `paramNameMap` 和 `paramDescMap`

```typescript
const paramNameMap: Record<string, string> = {
  // ... 已有
  confirm_garbage_sec: '垃圾确认时间(秒)',
};

const paramDescMap: Record<string, string> = {
  // ... 已有
  confirm_garbage_sec: '持续检测到垃圾的时间，超过该时间触发告警（建议 60-120 秒）',
};
```

### 3.4 全局参数配置页

**文件：** `apps/web-antd/src/views/aiot/device/algorithm/index.vue`

`paramNameMap` 和 `paramDescMap` 同样需要添加 `confirm_garbage_sec` 条目（参见 3.3）。

---

## 四、验证顺序（将来实施时）

1. **后端数据库注册算法记录**
2. **WVP 后端重启** — 白名单生效
3. **Service 端** constants.py 添加（如需要）
4. **前端重启** — 下拉选项和颜色生效
5. **ROI 编辑器创建一个 garbage 绑定，参数用默认值**
6. **前端触发配置推送** — 验证 Edge 端收到并注册算法
7. **Edge 日志验证：** 应看到 `已从Redis加载垃圾检测算法: roi_xxx_bind_xxx`
8. **模拟测试：** 放个垃圾在摄像头前，60 秒后应触发告警
9. **清理测试：** 移除垃圾 30 秒后应收到 resolve 事件
10. **企微卡片收到告警 + 创建工单全流程**

---

## 五、TensorRT 引擎部署（最后一步）

当确定用微调模型替换 COCO 预训练模型时：

1. **导出 engine：**
   ```bash
   yolo export model=yolo11s_v1_20260417.pt format=engine imgsz=480 half=True device=0
   ```

2. **替换 Edge 端模型：**
   ```bash
   cp yolo11s_v1_20260417.engine /opt/edge/models/yolo11n.engine  # 注意文件名
   ```

3. **修改 `config/settings.py` 的 COCO_CLASS_NAMES：**
   ```python
   COCO_CLASS_NAMES = ['garbage', 'person', 'car', 'bicycle', 'motorcycle']
   ```

4. **修改 `core/postprocessor.py` 的输出解析：**
   - YOLO 输出从 `[84, 8400]`（4+80类）变为 `[9, 8400]`（4+5类）
   - 类别分数范围从 `output[4:84]` 改为 `output[4:9]`

5. **重启 Edge 服务**

这一步涉及模型 + 推理管线，需要单独在生产环境测试。