# 工单处理 H5 页面 + 工单引擎对接 实施计划

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

**Goal:** 在前端项目中新增 H5 工单详情页（支持文字描述+拍照上传+提交完成），同时启用 IoT 工单引擎对接，实现告警→工单→企微通知→处理→结单的完整闭环。

**Architecture:** 企微卡片简单操作（确认/误报）直接回调处理，复杂操作（填描述+上传图片）通过 card_action.url 跳转 H5 详情页。H5 页面通过企微 OAuth2 获取用户身份做权限控制。后端新增工单处理 API，每次操作同步更新告警状态 + IoT 工单 + 企微卡片三方状态。

**Tech Stack:** Vue 3, Ant Design Vue, 企微 JS-SDK/OAuth2, FastAPI, work_order_client

---

## 整体流程

```
边缘告警 → vsp-service → VLM复核
  → 调IoT创建工单（拿到orderId）
  → 存 alarm_event_ext（alarm_id ↔ orderId）
  → 企微发工单卡片：
      按钮：[确认处理] [误报忽略]
      card_action.url → H5详情页

保安操作路径A（简单）：
  点[误报忽略] → 回调 → 更新告警+调IoT结单+卡片终态

保安操作路径B（复杂）：
  点[确认处理] → 回调 → 更新告警为处理中+卡片显示"处理中"
  → 去现场处理 → 点卡片进入H5详情页
  → 填描述+拍照 → 提交
  → 更新告警+调IoT结单+卡片终态
```

---

### Task 1: 后端 — 启用工单创建（notify_dispatch）

**Files:**
- Modify: `iot-device-management-service/app/services/notify_dispatch.py`
- Modify: `iot-device-management-service/app/main.py`（初始化 work_order_client）

取消工单创建代码的注释，VLM 复核通过后：
1. 调 `wo_client.create_order()` 创建工单
2. 存 orderId 到 `alarm_event_ext`（ext_type=WORK_ORDER）
3. 企微卡片和群聊通知正常发送

---

### Task 2: 后端 — 卡片按钮回调启用工单结单

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

取消工单结单代码的注释：
- `ignore`（误报忽略）→ 调 `wo_client.auto_complete_order(orderId, "误报忽略")`
- `complete`（已处理）→ 调 `wo_client.auto_complete_order(orderId, "已处理完成")`
- `false`（标记误报）→ 调 `wo_client.auto_complete_order(orderId, "标记误报")`

---

### Task 3: 后端 — 卡片 card_action.url 改为 H5 工单页

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

`_alarm_detail_url` 方法改为指向 H5 工单详情页：
```python
def _alarm_detail_url(self, alarm_id: str) -> str:
    if self._service_base_url:
        return f"{self._service_base_url}/work-order?alarmId={alarm_id}"
    return ""
```

同时卡片按钮从两步改为一步：
- [确认处理] — 回调更新状态为处理中
- [误报忽略] — 回调直接结单

去掉 `update_alarm_card_step2`（不再需要第二步卡片）。

---

### Task 4: 后端 — 新增工单处理 API

**Files:**
- Create: `iot-device-management-service/app/routers/work_order_api.py`

新增 3 个接口（H5 页面调用）：

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

POST /api/work-order/complete
  Body: {alarmId, remark, imageUrl?}
  → 更新告警状态CLOSED + 调IoT结单 + 更新企微卡片

POST /api/work-order/reject
  Body: {alarmId, remark?}
  → 更新告警状态FALSE + 调IoT结单 + 更新企微卡片
```

权限验证：通过企微 OAuth2 获取的 userid 校验是否为工单指派人。

---

### Task 5: 后端 — 图片上传接口

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

```
POST /api/work-order/upload-image
  Body: multipart/form-data（图片文件）
  → 上传到 COS → 返回图片 URL
```

供 H5 页面拍照上传使用。

---

### Task 6: 前端 — 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. 根据工单状态展示不同界面：
   - 待处理：显示告警截图 + [确认处理] [误报忽略]
   - 处理中：显示告警截图 + 处理表单（文字输入+拍照上传+提交）
   - 已完成：显示告警截图 + 处理后照片 + 处理描述

页面组件：
- Ant Design：Card, Button, Input.TextArea, Upload, Image, Tag, Steps
- 拍照：`<input type="file" accept="image/*" capture="environment">`（调手机摄像头）

---

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

**Files:**
- 前端路由添加 `/work-order` 路径（无需登录，通过企微 OAuth2 鉴权）

H5 页面不需要侧边栏和顶部导航，是独立的全屏页面。
可使用空布局（blank layout）或直接在路由中标记 `meta: { layout: 'blank' }`。

---

### Task 8: 后端 — work_order_client 初始化启用

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

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

服务器 `.env` 新增：
```
WORK_ORDER_ENABLED=true
WORK_ORDER_BASE_URL=http://192.168.0.104:48080
WORK_ORDER_APP_ID=alarm-system
WORK_ORDER_APP_SECRET=tQ3v5q1z2ZLu7hrU1yseaHwg1wJUcmF1
```

---

## 验证清单

- [ ] 边缘告警触发后自动创建 IoT 工单
- [ ] 企微卡片显示工单信息，点击跳转 H5 详情页
- [ ] 点"误报忽略"按钮 → 告警状态+IoT工单+卡片三方同步更新
- [ ] H5 页面能展示告警详情和工单状态
- [ ] H5 页面能填写描述+拍照上传+提交完成
- [ ] 提交后告警状态+IoT工单+卡片三方同步更新
- [ ] 非指派人打开 H5 页面显示无权限
- [ ] 工单已完成后 H5 页面显示处理结果（只读）