wecom_it_smart_desk/docs/03-技术架构/02-技术方案/02-技术方案-企微审批工单同步.md

# 技术方案-企微审批工单同步

> **文档编号**: 02-技术方案-企微审批工单同步
> **版本**: v1.1
> **创建日期**: 2026-07-04
> **状态**: 待评审

---

## 1. 需求概述

### 1.1 背景

将企微审批工单同步到坐席待办事项，实现IT服务台与企微审批系统的集成。

### 1.2 需求描述

| 需求项 | 说明 |
|--------|------|
| 需求来源 | PRD v0.7.2 Backlog #74 |
| 需求类型 | P1（待办事项集成） |
| 目标 | 将企微审批工单同步到坐席待办事项 |

---

## 2. 技术方案

### 2.1 整体架构

```
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  企微审批系统    │ ───▶ │  IT服务台后端    │ ───▶ │  坐席待办事项   │
│  (外部API)       │      │  (同步服务)      │      │  (todo_items)  │
└─────────────────┘      └─────────────────┘      └─────────────────┘
        │                        │                        │
        ▼                        ▼                        ▼
  审批工单数据            定时轮询/回调              待办面板展示
  (get_approval_list)     转换+存储
```

### 2.2 数据同步方式

| 方式 | 说明 | 优点 | 缺点 |
|------|------|------|------|
| **定时轮询** | 每5分钟调用企微API拉取审批列表 | 实现简单，稳定可靠 | 有延迟（最大5分钟） |
| **企微回调** | 审批通过时企微主动推送 | 实时性高 | 需要企微开通回调权限 |
| **混合模式** | 回调为主 + 定时兜底 | 实时+兜底 | 实现复杂 |

**推荐方案**：定时轮询（简单可靠） + 回调模式（实时性）

### 2.3 企微API接口

使用企微 OA 审批接口：

| 接口 | 说明 |
|------|------|
| `GET /cgi-bin/oa/approvallist` | 获取审批列表 |
| `GET /cgi-bin/oa/approvalinfo` | 获取审批详情 |

### 2.4 数据映射

| 企微审批字段 | todo_item 字段 | 说明 |
|-------------|----------------|------|
| `sp_no` | `id` | 审批单号 |
| `sp_name` | `title` | 审批名称 |
| `apply_name` | `description.applicant` | 申请人 |
| `apply_time` | `created_at` | 申请时间 |
| `status` | `status` | 审批状态 |
| `sp_status` | `priority` | 审批类型 |

### 2.5 待办事项字段扩展

```python
class TodoItem(Base):
    # 现有字段...
    type: Mapped[str] = "approval"  # 固定为 approval

    # 新增字段（审批专用）
    approval_id: Mapped[str] = mapped_column(String(64))  # 企微审批单ID
    approval_type: Mapped[str] = mapped_column(String(64))  # 审批模板名称
    applicant: Mapped[str] = mapped_column(String(100))  # 申请人
    applicant_dept: Mapped[str] = mapped_column(String(100))  # 申请人部门
    apply_time: Mapped[datetime]  # 申请时间
    approval_url: Mapped[str] = mapped_column(String(512))  # 审批详情链接
```

---

## 3. 审批模板（IT相关）

根据需求，明确需要同步的审批模板：

| 序号 | 审批模板名称 | 说明 |
|------|-------------|------|
| 1 | IT资产升级申请 | 硬件升级审批 |
| 2 | IT资产报废申请 | 资产报废审批 |
| 3 | 商业软件服务申请 | 软件采购审批 |
| 4 | 企微外联权限申请 | 外网权限审批 |
| 5 | 离职人员企微微盘&文档空间异常移交 | 离职资产移交 |
| 6 | 会议室故障报修 | 设备报修审批 |

---

## 4. 企微API权限确认

### 4.1 如何确认是否已开通权限

**方法一：企微管理后台查看**

1. 登录企微管理后台：https://work.weixin.qq.com/
2. 进入「应用管理」→「自建应用」→ 选择IT服务台应用
3. 查看「API权限」中是否包含：
   - 通讯录同步
   - 审批相关接口

**方法二：调用接口测试**

使用已有 access_token 调用以下接口测试：

```bash
curl "https://qyapi.weixin.qq.com/cgi-bin/oa/approvallist?access_token=xxx&start_time=0&end_time=9999999999"
```

如果返回 `{"errcode":0, ...}` 表示已开通权限。

**方法三：联系企微管理员**

确认是否在「审批」应用中开通了API调用权限。

### 4.2 回调模式说明

| 对比项 | 定时轮询 | 企微回调 |
|--------|----------|----------|
| 实时性 | 5分钟延迟 | 秒级实时 |
| 实现复杂度 | 简单 | 稍复杂 |
| 可靠性 | 稳定 | 依赖回调通道 |
| 资源消耗 | 每次全量/增量拉取 | 按需推送 |

**回调模式优势**：
1. 实时性高 - 审批提交/通过后立即同步
2. 节省资源 - 只需处理变更，无需轮询
3. 体验更好 - 坐席几乎实时看到新待办

**回调模式限制**：
1. 需要企微开通审批回调权限
2. 回调地址需公网可访问（可通过nginx反向代理）
3. 需要处理回调签名验证

---

## 5. 实施计划

### 5.1 任务拆分

| 任务 | 说明 | 优先级 |
|------|------|--------|
| T1 | 扩展 todo_item 模型，新增审批专用字段 | P0 |
| T2 | 创建企微审批同步服务 `ApprovalSyncService` | P0 |
| T3 | 实现定时轮询逻辑（每5分钟） | P0 |
| T4 | 坐席端待办面板接入审批数据 | P1 |
| T5 | 审批状态变更同步 | P1 |
| T6 | 企微审批回调接入（可选） | P2 |

### 5.2 数据库变更

```sql
ALTER TABLE todo_items
ADD COLUMN approval_id VARCHAR(64),
ADD COLUMN approval_type VARCHAR(64),
ADD COLUMN applicant VARCHAR(100),
ADD COLUMN applicant_dept VARCHAR(100),
ADD COLUMN apply_time TIMESTAMP,
ADD COLUMN approval_url VARCHAR(512);
```

---

## 6. 待确认事项

| 事项 | 状态 | 备注 |
|------|------|------|
| 企微API权限 | 待确认 | 需按4.1方法确认 |
| 审批模板 | ✅ 已明确 | 6个IT相关模板 |
| 同步频率 | ✅ 已确认 | 5分钟可接受 |
| 回调模式 | ✅ 确认开通 | 实时性优先 |

---

## 7. 相关文档

| 文档 | 说明 |
|------|------|
| [PRD v0.7.2 Backlog](./02-产品需求/product-产品/v0.7.2-backlog-candidate-2026-06-24.md) | 需求来源 |
| [todo_item 模型](../../backend/app/models/todo_item.py) | 现有模型定义 |
| [企微API文档](https://developer.work.weixin.qq.com/document/14567) | 审批接口文档 |

---

> **文档状态**: 待评审