# 任务说明书 - 零信任VPN账号申请卡片免登录修复

> **版本**: v2.0 | **日期**: 2026-07-17

---

## 📋 基本信息

| 项目 | 内容 |
|------|------|
| **任务名称** | 零信任VPN账号申请卡片免登录修复 |
| **任务ID** | #76 |
| **优先级** | 🟠P1 |
| **类型** | Bug修复 |
| **状态** | ✅ 已完成（保留扫码登录作为人机校验） |
| **负责人** | 宋献 |
| **创建日期** | 2026-07-17 |
| **计划完成日期** | 2026-07-17 |

---

## 📥 输入项来源

### 产品需求
| 来源文档 | 相关章节 | 说明 |
|----------|----------|------|
| `01-产品文档/IT智能服务台-产品需求文档PRD-v2.md` | §3.2 智能推荐卡片 | 员工通过AI推荐卡片直接跳转到ITSM审批 |
| `02-技术文档/实现配置/dify_main_chat_prompt_v1.1.md` | - | Dify返回的approval_type为中文分类名"账号权限申请" |

### 技术架构
| 来源文档 | 相关章节 | 说明 |
|----------|----------|------|
| 本次用户提供的认证配置信息 | - | 一站式运维平台的OAuth2.0配置域名 |

### 用户提供的认证配置信息
| 配置项 | 域名 |
|--------|------|
| 应用主页域名 | itsm.servyou.com.cn |
| OAuth2.0网页授权回调域名 | biz.17win.com |
| JS-SDK可信域名 | itsm.shuiyou.com.cn |
| 跳转小程序可信域名 | itsm.shuiyou.com.cn |
| Web网页扫码登录回调域名 | devops.dc.servyou-it.com |

**关键发现**：
1. 从 `itsm.servyou.com.cn`（企微应用主页）打开时，可实现免登录认证。
2. **重要约束**：`itsm.servyou.com.cn` 是移动端 SPA（`/itsm-miniapp-mobile/`），服务器**未配置 SPA fallback**，所有子路由（如 `/pages/login/index`、`/createTicket/:name`）直接 URL 访问均返回 404。仅应用首页 `/itsm-miniapp-mobile/` 返回 200 且免登录。
3. 因此**无法深链到具体工单创建表单**，卡片只能落到 ITSM 移动端首页（免登录），由用户点选创建工单。

---

## 📤 输出成果要求

### 交付物清单

| # | 交付物 | 类型 | 说明 |
|---|--------|------|------|
| 1 | 后端修改 | 代码 | 修改 `approval.py` 中ITSM跳转URL域名 |
| 2 | 前端修改 | 代码 | 修改 `RecommendCard.vue` 中URL映射 |
| 3 | 部署验证 | 验证 | 企微H5实际测试通过 |

### 代码要求
- 遵循项目代码规范

---

## 🔧 验证方式

### 功能验证
| 验证项 | 验证方法 | 预期结果 |
|--------|----------|-----------|
| 跳转URL域名变更 | 代码检查 | URL从devops改为itsm.servyou.com.cn |
| 按钮点击跳转 | 企微H5实际测试 | 点击按钮直接跳转ITSM工单页面 |
| 免登录验证 | 跳转后检查 | 无需扫码直接显示ITSM工单创建表单 |

---

## ✅ 完成标准

### 验收条件

- [x] 问题分析完成
- [x] 代码修改完成
- [x] 部署验证通过
- [x] 用户测试通过（扫码登录保留为人机校验，用户确认接受）

### 产出确认

- [x] 代码已提交
- [x] 部署验证已完成
- [x] 任务说明书已更新

---

## 📊 工作分解

### 子任务

| 子任务 | 负责人 | 预估工时 | 状态 |
|--------|--------|----------|------|
| 修改后端approval.py中ITSM URL域名 | 宋献 | 0.5h | ✅ 已完成 |
| 修改前端RecommendCard.vue中URL映射 | 宋献 | 0.5h | ✅ 已完成 |
| 部署验证 | 宋献 | 0.5h | ✅ 已完成 |
| 用户测试确认 | 宋献 | 0.5h | ✅ 已完成 |

---

## 📞 依赖与阻塞

### 前置依赖
| 依赖任务 | 依赖说明 | 状态 |
|----------|----------|------|
| 无 | 独立任务 | - |

### 阻塞因素
| 阻塞项 | 影响范围 | 解决方案 |
|--------|----------|----------|
| 无 | - | - |

---

## 📈 变更记录

| 日期 | 变更内容 | 变更人 | 说明 |
|------|----------|--------|------|
| 2026-07-17 | 创建任务 | 宋献 | 初始版本v1.0 |
| 2026-07-17 | 更新方案 | 宋献 | v2.0：改用itsm.servyou.com.cn域名实现免登录 |
| 2026-07-17 | 终态决策 | 宋献 | v3.0：保留桥接页现状，扫码登录定为人机校验；技术限制同步写入 PRD §v2.3 与架构 §15.4.9 |

---

## 📎 附件

### 修复方案说明

**问题现象**：用户点击零信任VPN账号申请卡片后，跳转到 Web ITSM 工单深链需要扫码登录（非免登录）。

**演进过程**：

| 版本 | 方案 | 结果 |
|------|------|------|
| v1.0（初版） | 深链直跳 `devops.dc.servyou-it.com/ITSM/...` | ❌ 弹扫码 |
| v2.0（回退） | 统一改为 ITSM 移动端首页 `https://itsm.servyou.com.cn/itsm-miniapp-mobile/`（免登录，但需手动点选工单，不符合"一步直达"） | ⚠️ 免登录但需二次点击 |
| v2.1（再试） | 改回 Web 工单深链 `createTicket?name=XXX` 一步直达 | ❌ 仍弹扫码 |
| v2.2（桥接） | 新增桥接页 `itsm-bridge.html`（隐式加载首页预热会话 + 2.5s 自动跳深链），3 个源文件 31 处 URL 改为桥接页 | ❌ 企微内实测仍弹扫码（跨域 iframe 预热被 ITSM 拒绝） |
| v3.0（终态决策） | **保持桥接页现状**，将扫码登录定为人机校验（Human-Machine Verification），企业安全合规可接受，不视为缺陷 | ✅ 已决策 |

**根因**：Web ITSM 不支持静默企微 OAuth；移动端首页静默 OAuth 仅在其自身域 (`itsm.servyou.com.cn`) 生效；跨域 iframe 预热被拒。三步流缺一环即冷 hit 弹扫码。

**修改文件（v2.2）**：
| 文件 | 说明 |
|------|------|
| `frontend-h5/public/itsm-bridge.html` | 新增桥接页（静态资源） |
| `backend/app/api/approval.py` | 8 个运维平台模板 URL → 桥接页 |
| `frontend-h5/src/components/assistant/RecommendCard.vue` | 15 处 URL → 桥接页 |
| `frontend-h5/src/components/chat/ApprovalCardModal.vue` | 8 处 URL → 桥接页 |

**未改动（2 个企微审批模板）**：IT资产领用 (asset_receive)、IT资产借用 (asset_borrow) 属企微审批流程，非 ITSM，不在本改造范围，按 `approval_templates.json` 数据源定义保持。

**部署验证**：桥接页经 nginx `curl` → `HTTP/1.1 200 OK`；部署的 `approval.py` 含桥接 URL 8 处；H5 构建 JS 含桥接 URL；两个 tar 包远端 MD5 与本地完全一致；5 容器全 healthy。技术限制已写入 PRD §v2.3 与架构文档 §15.4.9。