wecom_it_smart_desk/docs/调试验证指南_2026-06-13.md

# IT智能服务台 — 调试验证指南

**创建时间**: 2026-06-13  
**适用环境**: 正式服务器 10.90.5.10 (itsupport.servyou.com.cn)

---

## 一、端到端验证清单

### 1.1 H5用户端验证

#### 验证项1：H5登录流程
| 步骤 | 操作 | 预期结果 |
|------|------|---------|
| 1 | 在企微桌面端打开 `https://itsupport.servyou.com.cn/itdesk/` | 自动跳转企微OAuth2授权页 |
| 2 | 确认授权 | 跳回H5聊天页面，显示欢迎消息 |
| 3 | 刷新页面 | 保持登录状态，无需重新授权 |
| 4 | 在浏览器（非企微）直接访问 | 显示"请在企业微信中打开"拦截页 |

**验证要点**：
- JWT Token 过期检查是否生效（60秒安全余量）
- Portal Token 传递是否正常（从Portal跳转时）
- 401 处理是否正确（Token过期后自动重新授权）

#### 验证项2：消息收发
| 步骤 | 操作 | 预期结果 |
|------|------|---------|
| 1 | 在H5端发送文本消息 | 消息显示在对话框，坐席端同步收到 |
| 2 | 粘贴图片到输入框 | 图片预览显示，发送后坐席端可见 |
| 3 | 上传文件（<10MB） | 文件上传成功，坐席端可下载 |
| 4 | 使用表情面板发送表情 | 表情正确显示 |
| 5 | 发送截图（系统截图+粘贴） | 截图编辑器弹出，确认后发送成功 |

#### 验证项3：排查步骤功能
| 步骤 | 操作 | 预期结果 |
|------|------|---------|
| 1 | 点击右侧"排查步骤"标签 | 显示交互式排查流程 |
| 2 | 选择一个问题类型 | 显示对应的排查步骤 |
| 3 | 按步骤操作并点击"已解决" | 状态更新，记录解决时间 |

---

### 1.2 坐席工作台验证

#### 验证项4：坐席登录与接单
| 步骤 | 操作 | 预期结果 |
|------|------|---------|
| 1 | 在企微桌面端打开 `https://itsupport.servyou.com.cn/itagent/` | 自动登录，显示坐席工作台 |
| 2 | 查看待办列表 | 显示当前待处理会话 |
| 3 | 点击一个会话 | 右侧显示对话内容和用户信息 |

#### 验证项5：消息收发（坐席端）
| 步骤 | 操作 | 预期结果 |
|------|------|---------|
| 1 | 在坐席端回复文本消息 | H5端同步收到 |
| 2 | 发送图片/文件 | H5端可查看/下载 |
| 3 | 使用快捷回复 | 快速插入预设回复 |
| 4 | 使用表情面板 | 表情正确显示 |

#### 验证项6：会话管理
| 步骤 | 操作 | 预期结果 |
|------|------|---------|
| 1 | 标记会话为"已解决" | 会话状态更新，H5端显示满意度评价 |
| 2 | 转接会话给其他坐席 | 其他坐席收到通知，可接手 |
| 3 | 查看会话历史 | 历史消息完整显示 |

---

### 1.3 邀请功能验证

#### 验证项7：邀请流程
| 步骤 | 操作 | 预期结果 |
|------|------|---------|
| 1 | 坐席端点击"邀请"按钮 | 弹出邀请对话框 |
| 2 | 选择要邀请的员工/部门 | 显示选中的员工列表 |
| 3 | 确认邀请 | 发送邀请通知，参与者列表更新 |
| 4 | 被邀请员工在H5端收到通知 | 显示"XXX邀请您加入会话" |
| 5 | 员工点击"加入" | 成功加入会话，可查看历史消息 |

#### 验证项8：参与者管理
| 步骤 | 操作 | 预期结果 |
|------|------|---------|
| 1 | 坐席端查看参与者列表 | 显示所有参与者（发起人/坐席/被邀请人） |
| 2 | 坐席端移除某参与者 | 该参与者被移除，收到通知 |
| 3 | 被邀请人主动退出 | 参与者列表更新，坐席端收到通知 |

---

### 1.4 管理后台验证

#### 验证项9：管理后台登录
| 步骤 | 操作 | 预期结果 |
|------|------|---------|
| 1 | 在企微桌面端打开 `https://itsupport.servyou.com.cn/itadmin/` | 自动登录（需admin角色） |
| 2 | 非admin角色访问 | 显示"无权限"提示 |

#### 验证项10：功能开关
| 步骤 | 操作 | 预期结果 |
|------|------|---------|
| 1 | 进入"功能开关"页面 | 显示所有功能开关列表 |
| 2 | 切换某个功能开关 | 状态保存成功 |
| 3 | 在H5/坐席端验证功能是否生效 | 功能按开关状态启用/禁用 |

#### 验证项11：仪表盘
| 步骤 | 操作 | 预期结果 |
|------|------|---------|
| 1 | 进入"仪表盘"页面 | 显示今日会话数/在线坐席/平均响应时间 |
| 2 | 切换日期范围 | 数据按日期刷新 |

---

## 二、测试企微应用创建指南

### 2.1 为什么需要测试企微应用？

| 问题 | 说明 |
|------|------|
| **企微域名限制** | 每个企微应用只能配置1个可信域名 |
| **OAuth2回调** | 回调URL只能指向一个服务器 |
| **消息推送** | 接收消息回调只能配置1个URL |
| **结论** | 同一个企微应用无法同时指向两个服务器 |

### 2.2 双企微应用方案

```
┌─────────────────────────────────────────────────────────┐
│                    企微管理后台                           │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────────┐      ┌─────────────────┐          │
│  │ IT智能服务台(正式) │      │ IT智能服务台-测试 │          │
│  │                  │      │                  │          │
│  │ 可信域名:        │      │ 可信域名:        │          │
│  │ itsupport.xxx    │      │ itdesk.amanzac   │          │
│  │                  │      │                  │          │
│  │ 应用主页:        │      │ 应用主页:        │          │
│  │ /itdesk/         │      │ /itdesk/         │          │
│  └─────────────────┘      └─────────────────┘          │
│           │                        │                    │
│           ▼                        ▼                    │
│  ┌─────────────────┐      ┌─────────────────┐          │
│  │   正式环境       │      │   测试环境       │          │
│  │  10.90.5.10     │      │  NAS            │          │
│  └─────────────────┘      └─────────────────┘          │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

### 2.3 创建步骤

#### 第一步：创建测试应用

1. 登录 [企微管理后台](https://work.weixin.qq.com/wework_admin/frame)
2. **应用管理** → **自建** → **创建应用**
3. 填写信息：
   - **应用名称**: `IT智能服务台-测试`
   - **应用logo**: 使用不同颜色（如橙色）区分正式应用
   - **应用介绍**: "仅供IT部门测试使用"
   - **可见范围**: 选择IT部门 + 测试人员

#### 第二步：配置测试应用

| 配置项 | 填写 | 说明 |
|--------|------|------|
| **可信域名** | `itdesk.amanzac.com` | OAuth2回调域名 |
| **应用主页** | `https://itdesk.amanzac.com/itdesk/` | 员工点击入口 |
| **接收消息** | `https://itdesk.amanzac.com/api/wecom/callback` | 企微消息推送 |

#### 第三步：验证域名

1. 在企微管理后台点击"可信域名"旁边的"验证"
2. 下载验证文件（如 `WW_verify_xxxxx.txt`）
3. 将文件放到 `frontend-h5/dist/` 目录
4. 重新构建前端并部署
5. 点击"验证"按钮

#### 第四步：配置OAuth2

1. 在企微管理后台找到"企业微信授权登录"
2. 配置 **Web网页** 授权回调域: `itdesk.amanzac.com`
3. 记录 **CorpID** 和 **Secret**

#### 第五步：配置后端环境变量

在测试环境的 `.env` 文件中配置：

```env
# 企微配置（测试应用）
WECOM_CORP_ID=ww_test_xxxxx
WECOM_SECRET=xxxxx
WECOM_AGENT_ID=xxxxx
WECOM_TOKEN=xxxxx
WECOM_ENCODING_AES_KEY=xxxxx

# 前端配置
VITE_WECOM_CORP_ID=ww_test_xxxxx
```

#### 第六步：配置NAS Cloudflare Tunnel

1. 登录 [Cloudflare Zero Trust](https://one.dash.cloudflare.com/)
2. **Networks** → **Tunnels** → 找到 `itdesk-nas` Tunnel
3. **Configure** → **Public Hostname**
4. 确认 `itdesk.amanzac.com` 指向 NAS 的 Docker 网关

---

### 2.4 验证测试应用

| 步骤 | 操作 | 预期结果 |
|------|------|---------|
| 1 | 在企微中找到"IT智能服务台-测试"应用 | 应用显示在工作台 |
| 2 | 点击应用 | 跳转到 `https://itdesk.amanzac.com/itdesk/` |
| 3 | 首次访问 | 跳转企微OAuth2授权页 |
| 4 | 确认授权 | 跳回H5聊天页面 |
| 5 | 发送测试消息 | 坐席端（NAS环境）收到消息 |

---

## 三、环境切换方案

### 正式上线前 → 正式上线后

```
切换前：
  正式应用 → itsupport.servyou.com.cn → 10.90.5.10
  测试应用 → itdesk.amanzac.com → NAS

切换后：
  正式应用 → itsupport.servyou.com.cn → 高可用架构
  测试应用 → itdesk.amanzac.com → 10.90.5.10
```

### 切换步骤

1. 将正式应用的 `itsupport.servyou.com.cn` DNS 指向高可用架构
2. 将测试应用的 `itdesk.amanzac.com` DNS 指向 10.90.5.10
3. 更新测试应用的 OAuth2 回调配置（如需要）
4. 验证两端都能正常访问

---

## 四、常见问题排查

### 4.1 OAuth2授权失败

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| redirect_uri参数非法 | 回调URL未配置或域名不匹配 | 检查企微管理后台的回调域配置 |
| 40029 code无效 | code已过期或重复使用 | 重新发起授权流程 |
| 40163 code已使用 | code只能使用一次 | 确保后端正确处理code换取token |

### 4.2 消息推送失败

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 回调URL验证失败 | Token或EncodingAESKey不匹配 | 检查后端.env配置 |
| 消息未送达 | 企微消息推送有延迟 | 等待1-2秒，或检查WebSocket连接 |

### 4.3 H5端401错误

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| Token过期 | JWT Token有效期已到 | 自动重新授权（已实现） |
| 循环重定向 | OAuth2回调处理异常 | 检查防循环计数器（最大3次） |

---

## 五、验证完成标准

### P0 验证项（必须通过）

- [ ] H5登录流程正常
- [ ] 坐席登录流程正常
- [ ] 消息收发双向正常
- [ ] 邀请功能完整闭环
- [ ] 管理后台可访问

### P1 验证项（建议通过）

- [ ] 文件上传/下载正常
- [ ] 表情发送正常
- [ ] 截图功能正常
- [ ] 排查步骤功能正常
- [ ] 功能开关生效

### P2 验证项（可选）

- [ ] 深浅色切换正常
- [ ] 会话历史完整
- [ ] 满意度评价流程

---

**文档维护**: 齐活林（Qi）· 交付总监  
**最后更新**: 2026-06-13