Simon
bea288e414
== 已部署上线 (9项) == - 代办事项真实数据源集成 (企微审批API 8bug修复链) - H5/坐席端 Logo样式统一+绿色背景 - 视频引导页修复 (localStorage key v2) - 坐席端 v9 Vue版本修复 (ElMessage._context) - 截图按钮 v10 修复 (getDisplayMedia user gesture) - 扫码样式恢复+H5扫码登录跳转修复 - H5截图快捷键提示 == 代码完成待部署 (3项) == - 知识迭代3Bug修复 (#8 POST端点/#7 MERGE幂等/#6 过期检查) - 会议室预定-小鱼易联终端 (40文件, 40/40测试通过) - IT资产升级审批推送 (asset_service.py) == 需求文档 (2项) == - 坐席端AI辅助消息框-PRD (4项新功能确认) - 坐席端布局优化建议 v2.0 (7天计划) == 新增文档 == - 日报-2026-07-11.md - 知识迭代Bug修复报告-20260711.md - 会议室预定-部署指南.md - CHANGELOG.md 更新 == 测试 == - test_todo_integration.py: 40/40 - test_meetingroom.py: 40/40 - test_bugfix_ki_suggestions.py: 21/21
280 lines
12 KiB
Markdown
280 lines
12 KiB
Markdown
# 任务说明书 — 审批流程系统
|
||
|
||
> **版本**: 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`：
|
||
|
||
```typescript
|
||
// 改动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` |
|