wecom_it_smart_desk/docs/10-项目管理/任务说明书/任务说明书-78-审批流程系统.md

任务说明书 — 审批流程系统

版本: v1.0 | 日期: 2026-07-10

---

📋 基本信息

项目	内容
任务名称	审批类型扩展 + 卡片URL直跳 + 同窗口导航 + 免登录研究
任务ID	#113-115
优先级	🟡 P2
类型	功能开发
状态	✅ 已完成并部署
负责人	开发团队（software-approval-expand / software-approval-nav 团队）
创建日期	2026-07-10
完成日期	2026-07-10

---

📥 输入项来源

产品需求

来源文档	相关章节	说明
02-产品需求/IT智能服务台-产品需求文档PRD-v2.md	§v2.2 增量需求 P2-07~P2-11	审批类型扩展、卡片URL关联、导航方式、免登录研究
02-产品需求/approval_templates.json	全文	18个审批流程的结构化数据源
02-产品需求/dify_approval_system_prompt_v2.md	全文	Dify意图识别System Prompt v2
02-产品需求/外来资料/IT审批与运维流程清单.xlsx	全文	原始审批流程清单（18行）

技术架构

来源文档	相关章节	说明
03-技术架构/IT智能服务台-系统架构设计文档v2.md	§15.4.3~15.4.8	审批模板扩展、意图识别链路、前端卡片架构、导航方案选型、跨应用免登录、后端API

---

📝 任务详情

子任务 #113：审批类型扩展与卡片URL直跳

背景

原系统仅支持 5 种审批类型（设备申请、账号权限、软件服务、资产处置、办公用品），Dify 意图识别也仅覆盖这 5 类。根据 IT审批与运维流程清单.xlsx，实际需要覆盖 12 种审批类型 / 18 个审批流程（企微审批 12 个 + 运维平台 6 个）。

实现内容

后端 (backend/app/api/approval.py)：

• APPROVAL_TEMPLATES 从 5 个扩展到 18 个（静态硬编码，含完整 URL、keywords、location）
• APPROVAL_PREFILTER_KEYWORDS 从 5 类扩展到 12 类关键词
• KEYWORD_TO_APPROVAL_TYPE 扩展为 12 类映射
• 新增 7 种类型：会议室故障报修、企业应用管理、资产变更确认、终端设备网络准入、活动与会议技术支持、员工IT支持与故障报修、公共邮箱账号申请
• 意图识别三级链路保持不变：关键词预过滤 → Dify原生API → 关键词降级兜底

前端 (frontend-h5/src/components/chat/ApprovalCardModal.vue)：

• ApprovalOption 接口新增 url?: string 字段
• APPROVAL_OPTIONS 从 5 类扩展到 12 类 / 17 个选项，每个选项携带完整审批 URL
• handleSelect 优先检查 option.url，有则直接跳转；无则 fallback 到后端模板匹配

Dify：

• System Prompt v2 覆盖全部 12 种审批类型，含示例、匹配规则、置信度评分指南
• 已由管理员手动粘贴发布到 Dify 后台

数据文件：

• approval_templates.json — 18 个审批流程的结构化数据（id, name, category, location, template_id, url, keywords, icon, desc）
• dify_approval_system_prompt_v2.md — Dify 应用的完整 System Prompt 文本

审批流程清单（18个）

#	审批类型	流程名称	平台
1	设备申请	IT设备领用申请	企微审批
2	设备申请	IT设备外修申请	企微审批
3	账号权限申请	VPN权限申请	企微审批
4	账号权限申请	企微外联权限申请	企微审批
5	软件服务申请	商业软件服务申请	企微审批
6	资产处置申请	IT资产报废申请	企微审批
7	资产处置申请	IT资产退还申请	企微审批
8	办公用品申请	办公用品超额领用审批	企微审批
9	会议室故障报修	会议室故障报修	企微审批
10	企业应用管理	企业应用管理	企微审批
11	资产变更确认	资产变更确认	企微审批
12	员工IT支持与故障报修	员工IT支持与故障报修	企微审批
13	终端设备网络准入	终端设备网络准入申请	运维平台
14	终端设备网络准入	终端设备网络准入-会议室设备	运维平台
15	活动与会议技术支持	大型活动技术保障申请	运维平台
16	活动与会议技术支持	会议技术支持申请	运维平台
17	公共邮箱账号申请	公共邮箱账号申请	运维平台
18	员工IT支持与故障报修	故障报修工单	运维平台

---

子任务 #114：审批卡片同窗口导航改造

背景

初始实现使用 window.open(url, '_blank') 在新标签页打开审批页面。在企微 H5 webview 内，新标签页体验不佳（用户需手动切换标签页）。改为同窗口导航 window.location.href = url，由企微原生提供顶部返回按钮。

安全头分析

生产环境 H5 页面设置了以下安全头，阻止跨域 iframe 嵌入：

安全头	当前值	影响
CSP default-src	'self'（无 frame-src）	只允许同域 iframe
COEP	require-corp	跨域资源必须带 CORP 头
CORP	same-origin	H5 自身资源仅同域可加载

结论：不改安全头的情况下，同窗口导航（方案 A）是最佳选择。企微审批 URL 本身未设 X-Frame-Options，但 COEP 这一层仍会拦截 iframe。

方案选型

方案	说明	改动量	风险	选型
A. 同窗口导航	location.href = url，企微原生返回	1行	零	✅ 已采用
B. iframe嵌入	自定义返回/关闭覆盖层	需改COEP/CSP	降低安全级别	待评估
C. 同源代理	后端代理iframe	复杂度高	可能破坏JS/cookie	不推荐

代码改动

文件 frontend-h5/src/components/chat/ApprovalCardModal.vue：

// 改动1：handleSelect 中 option.url 分支
// Before: window.open(option.url, '_blank'); showToast('已打开审批页面');
// After:  window.location.href = option.url;

// 改动2：handleSelect 中 fallback 匹配分支
// Before: window.open(result.url, '_blank'); showToast('已打开审批页面');
// After:  window.location.href = result.url;

移除两处 showToast 调用（页面立即跳转，toast 不可见）。

---

子任务 #115：企微跨应用免登录可行性研究

背景

IT智能服务台 H5 与一站式运维平台同为税友集团企微下的自建应用（同一 corpid）。用户从 IT 服务台 H5 点击运维平台审批链接时，是否需要重新登录？

结论

可行。同一 corpid 下的自建应用各自独立走 OAuth2 snsapi_base 静默授权：

1. 用户从 IT 服务台 H5 点击运维平台链接
2. 运维平台检测到未登录 → 自动发起 OAuth2 snsapi_base 静默授权
3. 企微 webview 自动带上 corpid 凭证 → 运维平台后端拿到 userid
4. 用户无感知完成登录

前提条件：

• 运维平台已配置企微可信域名
• 运维平台已实现 OAuth2 回调后端逻辑
• 两个应用在同一企微 corpid 下

企微审批 URL (app.work.weixin.qq.com)：企微内置浏览器打开时自动登录，无需额外配置。

---

🔧 技术方案

后端 API 端点

端点	方法	说明	认证
/approval/templates	GET	返回全部18个审批模板	需要
/approval/keywords	GET	返回12类审批关键词映射	需要
/approval/detect	POST	意图识别（关键词预过滤 → Dify → 降级兜底）	需要
/approval/jump/{template_id}	POST	创建审批跳转	需要

意图识别三级链路

用户消息
  ↓
1. 关键词预过滤 (_keyword_prefilter)
   命中 → 返回模板
   未命中 ↓
2. Dify 原生 API (app-7jkRkAzvX4QM9v9SM3P8mMEO)
   返回 is_approval_request + approval_type
   置信度 ≥ 0.7 → 匹配模板
   未命中 ↓
3. 关键词降级兜底 (_fallback_detect)
   模糊匹配 → 返回模板或 None

前端组件架构

ApprovalCardModal.vue
├── ApprovalOption 接口 { name, icon, desc, url? }
├── APPROVAL_OPTIONS (12类 / 17选项，每个带 url)
├── handleSelect(option)
│   ├── option.url 存在 → window.location.href = option.url
│   └── fallback → 调后端 /approval/detect → /approval/jump
├── loadKeywords() → 从后端加载关键词列表
└── onMounted → 初始化

---

📦 交付物清单

代码文件

文件	改动类型	说明
backend/app/api/approval.py	修改	18个模板+12类关键词+映射表
frontend-h5/src/components/chat/ApprovalCardModal.vue	修改	12类卡片+URL直跳+同窗口导航

数据文件

文件	说明
docs/02-产品需求/approval_templates.json	18个审批流程结构化数据
docs/02-产品需求/dify_approval_system_prompt_v2.md	Dify System Prompt v2全文
docs/02-产品需求/外来资料/IT审批与运维流程清单.xlsx	原始数据源

文档更新

文档	更新内容
docs/02-产品需求/IT智能服务台-产品需求文档PRD-v2.md	新增 v2.2 增量需求（P2-07~P2-11）
docs/03-技术架构/IT智能服务台-系统架构设计文档v2.md	§15.4.3~15.4.8 扩展
docs/10-项目管理/任务说明书/IT智能服务台-项目管理主文档.md	新增 #113-115 任务

---

✅ 验证结果

验证项	方法	结果
后端 API 模板列表	docker exec wecom_it_backend curl -s http://localhost:8000/approval/templates	✅ 返回18个模板
后端 API 关键词	docker exec wecom_it_backend curl -s http://localhost:8000/approval/keywords	✅ 12类关键词映射正确
前端 H5 页面可访问	docker exec wecom_it_nginx curl -s -o /dev/null -w '%{http_code}' http://localhost/h5/	✅ HTTP 301（正常重定向）
nginx 容器文件	docker exec wecom_it_nginx ls /usr/share/nginx/html/h5/	✅ assets/ + index.html 齐全
浏览器渲染	agent-browser 打开 H5 URL	✅ 登录页正常渲染，无JS报错
生产容器状态	docker ps	✅ backend healthy / nginx running
企微内实测	用户手动测试	✅ 企微审批+运维平台审批均通过
Dify 意图识别	用户手动测试	✅ Dify v2 已发布，识别新增7种类型

---

📌 已知非阻塞项

项	说明	影响
import os 未使用	approval.py 中 os.getenv 调用被移除后，import os 变为未使用	Linter警告，不影响运行
it_device_repair 模板	后端模板中有 it_device_repair 但前端"设备申请"下无对应选项	不影响功能，该模板通过意图识别仍可触发

---

🚀 部署记录

步骤	操作	时间
后端文件上传	jms_ops.py upload → /tmp/approval_v2.py	2026-07-10
后端替换+重启	cp /tmp/approval_v2.py + docker compose restart backend	2026-07-10
前端构建	npm run build（465 modules, 3.18s）	2026-07-10
前端打包上传	tar -czf → jms_ops.py upload	2026-07-10
前端解压+重启	tar -xzf + docker compose restart nginx	2026-07-10
导航改造部署	同上流程（第二次部署）	2026-07-10
临时文件清理	/tmp/approval_v2.py + /tmp/frontend-h5-dist*.tar.gz	2026-07-10
Dify System Prompt	用户手动粘贴发布	2026-07-10

---

📎 关联文档

文档	位置
PRD v2	docs/02-产品需求/IT智能服务台-产品需求文档PRD-v2.md
架构设计 v2	docs/03-技术架构/IT智能服务台-系统架构设计文档v2.md
审批模板数据	docs/02-产品需求/approval_templates.json
Dify Prompt v2	docs/02-产品需求/dify_approval_system_prompt_v2.md
原始清单	docs/02-产品需求/外来资料/IT审批与运维流程清单.xlsx