iot-device-management-service/docs/plans/2026-03-23-work-order-v2-design.md

# 工单引擎对接 + H5 工单详情页 实施计划（v2）

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 打通 告警→IoT工单→企微卡片→保安处理→H5提交→IoT结单→告警状态同步 的完整闭环。

**Architecture:** vsp-service 作为企微通知网关，IoT 平台作为工单状态权威源。告警触发后 vsp-service 调 IoT 创建工单，IoT 派单后回调 vsp-service 发企微卡片。保安通过卡片按钮做简单操作（确认/误报），通过 H5 详情页做复杂操作（描述+图片）。所有状态变更走 IoT → 回调 vsp-service 同步告警+卡片。

**Tech Stack:** Python/FastAPI, Vue 3/Ant Design Vue, 企微 JS-SDK/OAuth2, work_order_client (SHA256签名)

---

## IoT 平台开放接口（vsp-service 调用）

| 接口 | 路径 | 必填参数 | 可选参数 |
|------|------|---------|---------|
| 创建工单 | `POST /open-api/.../create` | title, areaId | description, priority, alarmId, alarmType, cameraId, roiId, imageUrl, sourceType |
| 确认工单 | `POST /open-api/.../confirm` | orderId | |
| 工单提交 | `POST /open-api/.../submit` | orderId, result | resultImgUrls |
| 误报标记 | `POST /open-api/.../false-alarm` | orderId | |
| 自动完单 | `POST /open-api/.../auto-complete` | orderId | remark |

## vsp-service 提供给 IoT 的接口

| 接口 | 入参 | 用途 |
|------|------|------|
| `POST /api/wechat/notify/send-card` | alarmId, orderId, userIds[], title, areaName, cameraName, eventTime, level, snapshotUrl | IoT 派单后调用，发企微工单卡片 |
| `POST /api/wechat/notify/sync-status` | alarmId, orderId, status(confirmed/completed/false_alarm/auto_resolved), operator, remark | IoT 状态变更后调用，同步告警+卡片 |

## 完整流程

```
边缘告警 → vsp-service VLM复核 → 调IoT /create（拿到orderId）
  → IoT自动派单 → IoT调 vsp-service /send-card → 发企微卡片

卡片按钮：[确认处理] [误报忽略]  |  点击卡片整体 → H5详情页

点[确认处理]：
  → vsp-service 调 IoT /confirm
  → IoT 回调 /sync-status(status=confirmed)
  → 更新告警CONFIRMED + 卡片重绘"已接单，请点击卡片提交处理结果"

点[误报忽略]：
  → vsp-service 调 IoT /false-alarm
  → IoT 回调 /sync-status(status=false_alarm)
  → 更新告警FALSE + 卡片终态"已忽略"

H5提交处理结果：
  → 上传图片到COS → 调 vsp-service → vsp-service 调 IoT /submit
  → IoT 回调 /sync-status(status=completed)
  → 更新告警CLOSED + 卡片终态"已处理"

边缘端告警自动解除：
  → vsp-service 调 IoT /auto-complete
  → IoT 回调 /sync-status(status=auto_resolved)
  → 更新告警 + 卡片终态"系统自动结单"
```

---

### Task 1: work_order_client 补充 3 个新方法

**Files:**
- Modify: `iot-device-management-service/app/services/work_order_client.py`

在现有 `create_order` 和 `auto_complete_order` 基础上，新增：
- `confirm_order(orderId)` → `POST /confirm`
- `submit_order(orderId, result, resultImgUrls=[])` → `POST /submit`
- `false_alarm(orderId)` → `POST /false-alarm`

签名逻辑复用现有的 `_sign` 和 `_build_headers`。

---

### Task 2: work_order_client 初始化启用

**Files:**
- Modify: `iot-device-management-service/app/main.py`

取消 `work_order_client` 初始化的注释，从 `.env` 读取配置。

---

### Task 3: notify_dispatch 启用工单创建

**Files:**
- Modify: `iot-device-management-service/app/services/notify_dispatch.py`

VLM 复核通过后：
1. 调 `wo_client.create_order()` 创建工单
2. 存 orderId 到 `alarm_event_ext`（ext_type=WORK_ORDER）
3. 企微通知正常发送（后续改为由 IoT 回调触发）

---

### Task 4: 新增 IoT 回调接口（send-card + sync-status）

**Files:**
- Create: `iot-device-management-service/app/routers/wechat_notify_api.py`
- Modify: `iot-device-management-service/app/main.py`（注册路由）

```
POST /api/wechat/notify/send-card
  → 接收 IoT 派单通知 → 发企微工单卡片给指定 userIds

POST /api/wechat/notify/sync-status
  → 接收 IoT 状态变更 → 更新告警状态 + 更新企微卡片
  → status 映射：
    confirmed → 告警CONFIRMED + 卡片重绘"已接单，请点击卡片提交处理结果"
    completed → 告警CLOSED + 卡片终态"已处理"
    false_alarm → 告警FALSE + 卡片终态"已忽略"
    auto_resolved → 告警CLOSED + 卡片终态"系统自动结单"
```

---

### Task 5: 卡片按钮回调改造（调 IoT 而非直接更新）

**Files:**
- Modify: `iot-device-management-service/app/routers/wechat_callback.py`

方案A严格模式：
- 点[确认处理] → 调 IoT /confirm → 等 IoT 回调 sync-status 再更新
- 点[误报忽略] → 调 IoT /false-alarm → 等 IoT 回调 sync-status 再更新

卡片按钮简化为一步（去掉 step2 的第二轮按钮）。

---

### Task 6: 卡片样式调整 + card_action.url

**Files:**
- Modify: `iot-device-management-service/app/services/wechat_service.py`

1. `_alarm_detail_url` 改为 H5 工单页：`/work-order?alarmId={alarm_id}`
2. 卡片按钮只保留 [确认处理] [误报忽略]
3. 确认后卡片重绘提示："已接单，请点击卡片提交处理结果"
4. 去掉 `update_alarm_card_step2` 中的第二轮交互按钮

---

### Task 7: 后端 — H5 工单处理 API

**Files:**
- Create: `iot-device-management-service/app/routers/work_order_api.py`
- Modify: `iot-device-management-service/app/main.py`（注册路由）

```
GET /api/work-order/detail?alarmId={alarmId}
  → 返回告警信息 + orderId + 工单状态 + 截图URL

POST /api/work-order/submit
  Body: {alarmId, result, resultImgUrls?}
  → 查 orderId → 调 IoT /submit → 等 IoT 回调同步状态

POST /api/work-order/upload-image
  Body: multipart/form-data
  → 上传到 COS → 返回永久 URL
```

---

### Task 8: 前端 — H5 工单详情页

**Files:**
- Create: `iot-device-management-frontend/apps/web-antd/src/views/work-order/index.vue`

页面逻辑：
1. 从 URL 参数获取 alarmId
2. 调 `/api/work-order/detail` 获取信息
3. 根据状态展示：
   - 待处理/处理中：告警截图 + 处理表单（文字输入+拍照+提交）
   - 已完成：告警截图 + 处理后照片 + 描述（只读）
   - 误报：显示"已标记误报"

拍照使用 `<input type="file" accept="image/*" capture="environment">`。

---

### Task 9: 前端 — 路由配置

**Files:**
- 添加 `/work-order` 路由，使用空布局（无侧边栏无顶栏）
- 不需要登录（通过企微 OAuth2 或 alarmId 鉴权）

---

## 验证清单

- [ ] 边缘告警 → VLM复核 → IoT工单创建成功
- [ ] IoT 回调 send-card → 企微卡片正确发送
- [ ] 点[确认处理] → 调IoT confirm → 回调更新告警+卡片
- [ ] 点[误报忽略] → 调IoT false-alarm → 回调更新告警+卡片终态
- [ ] H5 详情页展示告警信息和工单状态
- [ ] H5 提交描述+图片 → 调IoT submit → 回调更新告警+卡片终态
- [ ] 边缘端告警解除 → 调IoT auto-complete → 回调更新告警+卡片终态
- [ ] 所有配置通过 .env 控制，无硬编码密钥