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 待办事项字段扩展

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 调用以下接口测试：

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 数据库变更

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	需求来源
todo_item 模型	现有模型定义
企微API文档	审批接口文档

---

文档状态: 待评审