chore: docs 结构整改 + compose 双目录对齐（合并重建提交）

本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。一、docs 结构整改（整改 #14）根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录树并存于 docs/，共 791 文件、双分类体系冲突。修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回，与线上一致，分叉隐患消除（已 docker compose config 校验通过）防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
2026-08-07 22:31:32 +08:00
parent 5a77a89ab1
commit facc04aa65
573 changed files with 129347 additions and 909 deletions
@@ -0,0 +1,279 @@
+# 任务说明书 — 审批流程系统
+
+> **版本**: v1.0 | **日期**: 2026-07-10
+
+---
+
+## 📋 基本信息
+
+| 项目 | 内容 |
+|------|------|
+| **任务名称** | 审批类型扩展 + 卡片URL直跳 + 同窗口导航 + 免登录研究 |
+| **任务ID** | #113-115 |
+| **优先级** | 🟡 P2 |
+| **类型** | 功能开发 |
+| **状态** | ✅ 已完成并部署 |
+| **负责人** | 开发团队（software-approval-expand / software-approval-nav 团队） |
+| **创建日期** | 2026-07-10 |
+| **完成日期** | 2026-07-10 |
+
+---
+
+## 📥 输入项来源
+
+### 产品需求
+
+| 来源文档 | 相关章节 | 说明 |
+|----------|----------|------|
+| `01-产品文档/IT智能服务台-产品需求文档PRD-v2.md` | §v2.2 增量需求 P2-07~P2-11 | 审批类型扩展、卡片URL关联、导航方式、免登录研究 |
+| `02-技术文档/实现配置/approval_templates.json` | 全文 | 18个审批流程的结构化数据源 |
+| `02-技术文档/实现配置/dify_approval_system_prompt_v2.0.md` | 全文 | Dify意图识别System Prompt v2 |
+| `01-产品文档/外来资料-IT审批与运维流程清单.xlsx` | 全文 | 原始审批流程清单（18行） |
+
+### 技术架构
+
+| 来源文档 | 相关章节 | 说明 |
+|----------|----------|------|
+| `02-技术文档/技术架构/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直跳+同窗口导航 |
+
+### 数据文件
+
+| 文件 | 说明 |
+|------|------|
+| `02-技术文档/实现配置/approval_templates.json` | 18个审批流程结构化数据 |
+| `02-技术文档/实现配置/dify_approval_system_prompt_v2.md` | Dify System Prompt v2全文 |
+| `02-技术文档/实现配置/IT审批与运维流程清单.xlsx` | 原始数据源 |
+
+### 文档更新
+
+| 文档 | 更新内容 |
+|------|---------|
+| `01-产品文档/` | IT智能服务台产品需求文档 |
+| `docs/02-技术文档/技术架构/IT智能服务台-系统架构设计文档v2.md` | §15.4.3~15.4.8 扩展 |
+| `docs/07-项目管理/任务说明书/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` 但前端"设备申请"下无对应选项 | 不影响功能，该模板通过意图识别仍可触发 |
+
+---
+
+## 🚀 部署记录
+
+| 步骤 | 操作 | 时间 |
+|------|------|------|
+| 后端文件上传 | `v2_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` → `v2_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 | `01-产品文档/` |
+| 架构设计 v2 | `02-技术文档/技术架构/IT智能服务台-系统架构设计文档v2.md` |
+| 审批模板数据 | `02-技术文档/实现配置/approval_templates.json` |
+| Dify Prompt v2 | `02-技术文档/实现配置/dify_approval_system_prompt_v2.md` |
+| 原始清单 | `02-技术文档/实现配置/` |