simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
wecom_it_smart_desk/docs/调试验证指南_2026-06-13.md
T

297 lines
11 KiB
Markdown
Raw Permalink Normal View History

chore: initial baseline with P0-safety .gitignore
2026-06-14 16:49:18 +08:00
# 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
Reference in New Issue Copy Permalink