wecom_it_smart_desk/docs/01-产品文档/06-审批与待办/prd_todo_integration.md

PRD: 代办事项系统集成真实数据源

实现状态（2026-07-11 更新）：

• ✅ P0 REQ-001 企微审批待处理列表 — 已实现并验证（getapprovalinfo API + TokenManager）
• ✅ P0 REQ-003 统一代办列表 API — 已实现（todo_aggregator_service.py，Redis 缓存 45s）
• ✅ P0 REQ-004 前端移除 mock fallback — 已实现
• ✅ P0 REQ-005 移除 device 类型 — 已实现
• ✅ P1 REQ-006 按类型筛选 — 已实现
• ✅ P1 REQ-008 手动刷新 — 已实现（_force=1 跳过缓存）
• ⏳ P0 REQ-002 ITSM 代办工单列表 — 待 ITSM API 抓包 + app_id/app_secret 申请
• ⏳ P1 REQ-007 点击代办条目展示详情 — 待 ITSM 部分完成
• ⏳ P2 REQ-009/010 自动刷新/跳转 — 待后续迭代

项目信息

• Language: 中文
• Programming Language: 后端 FastAPI + SQLAlchemy + PostgreSQL + Redis | 前端 Vue3 + Element Plus + Pinia
• Project Name: todo_integration_real_data
• 原始需求复述: 将坐席端"代办事项"面板从 mock 数据切换为真实数据源。数据来源包括企微审批待处理审批单（getapprovalinfo API）和 ITSM 运维平台"我的代办"工单（ITSM API + 企微 SSO 免登录）。移除所有 mock 数据和 device 类型，不保留 mock fallback。
• API 变更说明: 原始需求引用的 getapprovaldata（/cgi-bin/oa/getapprovaldata）已于 2019 年废弃返回 404，实际使用新接口 getapprovalinfo（/cgi-bin/oa/getapprovalinfo），分页参数从 cursor(int) 变为 new_cursor(string)，返回从 data 数组变为 sp_no_list 字符串数组。
• Token 变更说明: 原始设计使用 ApprovalTokenManager（审批应用 Secret），但服务器出口 IP 218.75.34.87 未在审批应用可信 IP 白名单中（errcode=60020）。实际改用 TokenManager（IT 支持应用 Secret，IP 已在白名单）。

---

1. 产品目标

1. 数据真实性：将坐席端代办面板从 20 条硬编码 mock 数据切换为两个真实数据源（企微审批 + ITSM 工单），确保坐席看到的是真实待处理工作。
2. 统一聚合：后端聚合企微审批和 ITSM 工单两个异构数据源为统一代办列表 API，保持前端交互体验不变。
3. 彻底去 mock：移除所有 mock 数据（后端 MOCK_TODO_ITEMS、前端 mockTodoListData）和 device 类型相关代码，确保系统数据真实性，不留 fallback。

---

2. 用户故事

1. 作为坐席，我希望在代办面板看到我真实的待处理企微审批单和 ITSM 工单，而不是 mock 数据，以便我了解真实的工作待办。
2. 作为坐席，我希望点击代办条目能查看对应的审批单/工单详情，以便快速了解任务内容并决定处理优先级。
3. 作为坐席，我希望代办列表能按类型（全部/审批/工单）筛选，以便高效分类处理不同来源的待办。
4. 作为坐席，我希望代办列表能反映最新的待处理状态（支持手动刷新），以便不遗漏新分配的审批和工单。
5. 作为坐席，我希望代办条目中能清晰区分审批单和工单的类型标签和优先级，以便快速识别紧急事项。

---

3. 需求池

P0 — Must Have

ID	需求描述	验收标准
REQ-001 ✅	后端实现企微审批待处理列表查询：集成企微 getapprovalinfo API（POST https://qyapi.weixin.qq.com/cgi-bin/oa/getapprovalinfo），查询当前登录坐席的待处理审批单列表。使用 TokenManager（IT 支持应用 Secret）获取 access_token，通过 filters 参数按审批状态（sp_status=1 审批中）过滤，返回 sp_no_list 后调用 getapprovaldetail 补充详情，在代码层按 18 个模板 ID 过滤，再通过 _extract_current_approver 按当前审批人过滤。	① 调用 getapprovalinfo 成功返回审批单号列表；② 仅返回 sp_status=1（审批中）的审批单；③ 支持分页（new_cursor + new_next_cursor）；④ token 获取复用 Redis 缓存机制（wecom:access_token）；⑤ 异常时记日志并返回空列表（不阻塞另一个数据源）
REQ-002 ⏳	后端实现 ITSM 代办工单列表查询：集成 ITSM 平台 API（https://devops.dc.servyou-it.com/ITSM/workflow/allTickets/umiAllticketsTodo），通过企微 SSO 免登录认证查询当前坐席的代办工单列表。待办：需抓包获取 API 接口规范 + 申请 app_id/app_secret。	① 成功调用 ITSM API 返回代办工单列表；② SSO 认证无需坐席手动登录；③ 返回工单包含标题、优先级、状态、创建时间等关键字段；④ 网络异常时记日志并返回空列表（不阻塞另一个数据源）
REQ-003 ✅	后端聚合两个数据源为统一代办列表 API：重写 GET /api/todo-items 端点，并行查询企微审批和 ITSM 工单两个数据源，将结果映射为统一的 TodoItemResponse 格式返回。移除 MOCK_TODO_ITEMS 硬编码数据。	① API 返回的 items 仅包含 type=approval 和 type=ticket 两种类型；② 两个数据源并行查询（asyncio.gather），任一失败不影响另一个返回；③ 返回数据按优先级排序（urgent→high→normal）；④ 响应时间 < 3 秒（两个外部 API 并行）；⑤ 不再返回任何 mock 数据
REQ-004 ✅	前端移除 mock fallback 逻辑：修改 stores/todo.ts，移除 import { mockTodoListData } from '@/mock/data' 和 catch 块中的 mock fallback 逻辑。API 调用失败时显示空列表 + 错误提示，不回退 mock。	① 代码中不再 import mockTodoListData；② API 失败时 todoList 为空数组；③ 控制台输出错误日志；④ 开发环境和生产环境行为一致（无 DEV 特殊分支）
REQ-005 ✅	移除 device 类型相关代码：后端从 VALID_TODO_TYPES 移除 "device"（schema/model）；前端从 typeLabel、typeLabelMap、TaskDetailView 的 DeviceDetail 分支、TodoPanel 的 type-device 样式中移除 device 相关代码。DeviceDetail.vue 组件可保留文件但不再被引用。	① 后端 VALID_TODO_TYPES 不再包含 "device"；② 前端 typeLabel 不再包含 device 映射；③ TaskDetailView.vue 不再渲染 DeviceDetail 分支；④ TodoPanel 中无 type-device 样式或该样式不生效；⑤ API 返回数据中无 type=device 的条目

P1 — Should Have

ID	需求描述	验收标准
REQ-006 ✅	代办列表支持按类型筛选：在 TodoPanel.vue 标题行增加"全部 / 审批 / 工单"三个筛选 Tab，点击后过滤展示对应类型的代办条目。后端 API 增加 type 查询参数支持服务端过滤。	① 默认显示"全部"；② 点击"审批"仅显示 type=approval 的条目；③ 点击"工单"仅显示 type=ticket 的条目；④ 筛选状态有视觉高亮
REQ-007 ⏳	点击代办条目展示对应详情：复用现有 TaskDetailView → TicketDetail / ApprovalDetail 子视图。点击审批条目展示审批详情，点击工单条目展示工单详情。详情数据来自后端 GET /api/todo-items/{id} 端点（需支持按 ID 查询单条代办详情，可能需要缓存或重新查询外部 API）。	① 点击审批条目 → 中间栏切换为 task 视图，展示 ApprovalDetail；② 点击工单条目 → 展示 TicketDetail；③ 详情数据正确展示标题、优先级、描述等字段；④ 返回按钮正常回到会话视图
REQ-008 ✅	代办列表支持手动刷新：在 TodoPanel 标题行增加刷新按钮，点击后重新调用 fetchTodoList() 获取最新数据。	① 刷新按钮可见且有刷新图标；② 点击后触发 API 重新查询；③ 刷新过程中按钮显示 loading 状态；④ 刷新完成后列表更新

P2 — Nice to Have

ID	需求描述	验收标准
REQ-009 ⏳	代办列表自动定时刷新：TodoPanel 挂载后每 60 秒自动刷新一次代办列表，组件卸载时清除定时器。	① 每 60 秒自动调用 fetchTodoList；② 组件卸载时 clearInterval；③ 不与手动刷新冲突
REQ-010 ⏳	代办条目支持跳转到原系统操作：在详情页底部增加"在企微审批中打开" / "在 ITSM 中打开"按钮，点击后在新窗口打开对应的审批单/工单原始页面。	① 审批详情页有"在企微审批中打开"按钮，跳转到企微审批 URL；② 工单详情页有"在 ITSM 中打开"按钮，跳转到 ITSM 工单 URL

---

4. UI 设计稿描述

4.1 TodoPanel（左栏待办面板）变化

标题行变化：

• 现有：📋 待办事项 + 紧急数量徽章
• 变更后：📋 待办事项 + 紧急数量徽章 + 类型筛选 Tab（全部/审批/工单）+ 刷新按钮（🔄 图标）
• 布局：标题文字左对齐，筛选 Tab 紧跟其后，刷新按钮最右侧

待办条目变化：

• 每条代办仍保持现有布局：优先级圆点 + 标题文本 + 类型标签 + 时间 + 上报人头像
• 类型标签仅保留两种：工单（蓝色，type=ticket）、审批（紫色，type=approval）
• 移除 设备（橙色，type=device）标签
• 数据来源从 mock 变为真实 API 返回

空状态变化：

• 现有：暂无待办
• 变更后：API 加载中显示 loading 动画；加载完成无数据时显示暂无待办；API 失败时显示加载失败，点击重试

底部坐席统计：

• 保持不变（仍使用 getAgentStats() mock 数据，不在本次改造范围内）

4.2 TaskDetailView（中间栏任务详情）变化

顶部标题栏：

• 类型标签映射移除 device：📋 运维工单 / 📝 审批单（移除 🖥 设备异常）
• 优先级标签保持不变

内容区：

• type=ticket → 渲染 TicketDetail 子视图（保持不变，但数据来自 ITSM 真实工单）
• type=approval → 渲染 ApprovalDetail 子视图（保持不变，但数据来自企微真实审批单）
• 移除 type=device → DeviceDetail 分支
• 未知类型 fallback 保持不变

4.3 ApprovalDetail / TicketDetail 子视图

• 整体布局保持不变（卡片式信息展示 + 操作按钮区）
• 数据字段需适配真实 API 返回结构：
  • 审批详情：description 字段需映射企微审批返回的申请人、审批类型、表单内容等
  • 工单详情：description 字段需映射 ITSM 返回的工单标题、类型、上报人、描述等
• 操作按钮（审批通过/拒绝、接单/结单等）的具体行为取决于待确认问题 #4 的决策

---

5. 待确认问题

5.1 ITSM API 相关（阻塞 REQ-002）— ⏳ 待申请授权

#	问题	说明	状态
Q1	ITSM API 的完整接口规范	需抓包获取请求方法/参数/返回格式	⏳ 待 agent-browser 抓包
Q2	ITSM SSO 认证的具体方式	后端调用 ITSM API 的认证链路待确认	⏳ 待抓包确认
Q2.1	ITSM app_id/app_secret 申请	openapi 签名认证需要 app_id 和 app_secret（签名：params 按 key 升序 → 拼接 value → quote_plus → SHA1 → 大写 hex）	⏳ 待向 ITSM 平台申请

5.2 企微审批相关（影响 REQ-001）— ✅ 已确认

#	问题	确认结果
Q3	过滤条件与时间范围	✅ API 层只传 sp_status=1（每个 filter key 只能一次），代码层按 18 个模板 ID 过滤。时间范围 7 天（企微 API 最大 31 天，建议改为 30 天）
Q4	"待处理"定义	✅ sp_status=1=审批中，需二次过滤当前审批人。企微 API 实际字段：sp_record[].sp_status（非 status）、审批人在 sp_record[].details[].approver.userid（非 approver[].userid）

5.3 交互与数据策略相关（影响 REQ-007、REQ-003）

#	问题	说明	状态
Q5	代办状态更新的交互方式	现有 ApprovalDetail 有"审批通过/拒绝/转交"按钮，TicketDetail 有"接单/处理/结单/转派"按钮。如需在服务台内操作，需对接企微审批 API 和 ITSM 工单 API 的状态变更接口	✅ 已确认：仅展示+跳转，不在服务台内操作
Q6	代办详情查询策略	列表查询时是否缓存每条代办的详情数据（Redis）？还是点击时实时查询外部 API？	✅ 已确认：Redis 缓存 45s，手动刷新跳过缓存
Q7	数据刷新策略	每次打开/刷新代办面板都实时查询两个外部 API？还是后端缓存？	✅ 已确认：初始+60s自动=用缓存，手动刷新=_force=1跳过缓存
Q8	ITSM 工单优先级映射	ITSM 返回的优先级字段如何映射到 urgent/high/normal？	⏳ 待 ITSM API 返回结构确认

---

附录：现有代码资产清单

可复用资产

资产	位置	复用方式
TokenManager	backend/app/utils/token_manager.py	✅ 已复用，获取企微 access_token（IT 支持应用 Secret）
get_approval_detail()	backend/app/api/approval.py	✅ 已复用，获取审批单详情
_extract_current_approver()	backend/app/api/approval.py	✅ 已复用，过滤当前审批人（字段名已修正）
_APPROVAL_TEMPLATE_IDS	backend/app/services/todo_source_service.py	✅ 已实现，18 个模板 ID 代码层过滤
TodoItem Model	backend/app/models/todo_item.py	可选复用（如需持久化缓存代办数据）
TodoItemResponse Schema	backend/app/schemas/todo_item.py	✅ 已复用，已移除 device 类型
前端 TodoPanel.vue	frontend-agent/src/components/conversation/TodoPanel.vue	✅ 已改造
前端 TaskDetailView.vue	frontend-agent/src/components/chat/TaskDetailView.vue	✅ 已改造
前端 TicketDetail.vue / ApprovalDetail.vue	frontend-agent/src/components/chat/task/	✅ 已改造

需删除/废弃资产

资产	位置	处理方式
MOCK_TODO_ITEMS	backend/app/api/todo_items.py	✅ 已删除
mockTodoListData	frontend-agent/src/mock/data.ts	✅ 已删除
mock fallback 逻辑	frontend-agent/src/stores/todo.ts L66-72	✅ 已删除
DeviceDetail.vue	frontend-agent/src/components/chat/task/DeviceDetail.vue	保留文件但不再被引用
device 类型样式	TodoPanel.vue L299-304	✅ 已删除
device 类型映射	TodoPanel.vue L110, TaskDetailView.vue L105	✅ 已删除