Simon
200 lines
6.2 KiB
Markdown
200 lines
6.2 KiB
Markdown
# 技术方案-企微审批工单同步
|
||
|
||
> **文档编号**: 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) | 审批接口文档 |
|
||
|
||
---
|
||
|
||
> **文档状态**: 待评审
|