wecom_it_smart_desk/docs/10-任务说明/P1-06-待办集成企微审批.md

P1-06: 待办事项集成企微审批工单

任务概述

项目	内容
需求ID	#74
优先级	P1
状态	需企微审批API权限
预估工时	2-3天

背景

将企微审批工单同步到坐席待办事项，坐席可在系统内直接处理企微提交的审批请求。

前置条件

• 需开通企微审批应用 API 权限
• 获取 corp_id, corp_secret, agent_id
• 配置审批模板 ID 映射

技术方案

1. 企微审批 API

# 企微审批相关 API
# 参考文档: https://developer.work.weixin.qq.com/document/16467

# 获取审批模板列表
GET https://qyapi.weixin.qq.com/cgi-bin/oa/gettemplate_list?access_token=TOKEN

# 获取审批详情
GET https://qyapi.weixin.qq.com/cgi-bin/oa/getdetail?access_token=TOKEN&sp_no=XXX

2. 同步逻辑

class ApprovalSyncService:
    """审批工单同步服务"""

    async def sync_approvals(self):
        """定时同步企微审批到本地待办"""
        # 1. 获取待审批列表
        approvals = await self.get_pending_approvals()

        # 2. 转换格式
        for approval in approvals:
            todo = self.convert_to_todo(approval)
            await self.save_todo(todo)

        # 3. 更新同步状态
        await self.update_sync_timestamp()

    async def get_pending_approvals(self):
        """获取用户待审批的工单"""
        # 调用企微 API
        pass

3. 数据模型

# 新增或复用现有 TodoItem 模型
class TodoItem:
    source_type: str  # "approval" / "ticket" / "manual"
    source_id: str    # 企微审批单号
    source_url: str   # 企微审批详情链接
    metadata: dict    # 审批类型、申请人、申请时间等

4. 前端展示

• 坐席待办事项显示审批工单
• 点击跳转到企微审批详情页（或 iframe 内嵌）

验收标准

• 企微审批 API 配置完成
• 定时同步任务正常运行
• 坐席端可看到待审批工单
• 点击可跳转到审批详情
• 审批完成后状态同步

文件清单

文件	操作
backend/app/services/approval_sync.py	新增
backend/app/api/todos.py	修改
backend/app/models/todo_item.py	修改
backend/app/scheduler/tasks.py	新增
frontend-agent/src/views/todo/*.vue	修改

实施步骤

1. 申请企微审批 API 权限
2. 配置企微应用参数
3. 开发同步服务
4. 开发前端展示
5. 定时任务配置
6. 测试联调