From c813112a8508d7023a34aacf49212d2a78dfe293 Mon Sep 17 00:00:00 2001
From: 16337 <1633794139@qq.com>
Date: Mon, 23 Mar 2026 11:08:09 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E5=B7=A5=E5=8D=95?=
 =?UTF-8?q?=E5=A4=84=E7=90=86H5=E9=A1=B5=E9=9D=A2+=E5=B7=A5=E5=8D=95?=
 =?UTF-8?q?=E5=BC=95=E6=93=8E=E5=AF=B9=E6=8E=A5=E5=AE=9E=E6=96=BD=E8=AE=A1?=
 =?UTF-8?q?=E5=88=92?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/plans/2026-03-23-work-order-h5-design.md | 175 ++++++++++++++++++
 1 file changed, 175 insertions(+)
 create mode 100644 docs/plans/2026-03-23-work-order-h5-design.md

diff --git a/docs/plans/2026-03-23-work-order-h5-design.md b/docs/plans/2026-03-23-work-order-h5-design.md
new file mode 100644
index 0000000..efcf19b
--- /dev/null
+++ b/docs/plans/2026-03-23-work-order-h5-design.md
@@ -0,0 +1,175 @@
+# 工单处理 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 页面显示处理结果（只读）