security-ai-edge/docs/garbage_algorithm_backend_frontend_plan.md

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

背景

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

---

一、WVP 后端改动

1.1 算法注册（数据库）

文件： wvp-platform/数据库/版本号/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"：

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：

• 已有 → 无需改动
• 未有 → 添加：

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 的提示词模板：

"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

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

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

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：

   yolo export model=yolo11s_v1_20260417.pt format=engine imgsz=480 half=True device=0
   

2. 替换 Edge 端模型：

   cp yolo11s_v1_20260417.engine /opt/edge/models/yolo11n.engine  # 注意文件名
   

3. 修改 config/settings.py 的 COCO_CLASS_NAMES：

   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 服务

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