simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

WIP-CHECKPOINT[auth-refactor]: 固化工程师崩溃前部分成果 + 同树其他未提交WIP（仅源码，不含密钥/二进制）-- 待重激活工程师续作

Browse Source
This commit is contained in:
Simon
2026-07-07 21:52:11 +08:00
parent 242c1967ff
commit fab75760e0
203 changed files with 21504 additions and 3345 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/06-测试质量/03-调试验证指南-20260613.md
-296
View File
@@ -1,296 +0,0 @@
# 智能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
docs/06-测试质量/testing-测试/登录功能测试用例-20260706.md
+91
View File
@@ -0,0 +1,91 @@
# 登录功能测试用例
> **版本**: v1.0 | **日期**: 2026-07-06 | **状态**: 待执行
> **依据文档**: PRD v1.2 §4.5 身份认证与统一入口
> **测试环境**: 本地开发环境
---
## 1. 测试范围
| 模块 | 接口 | 说明 |
|------|------|------|
| 企微免密登录 | `/api/auth_wecom/jsdk-login` | 企微JS-SDK免认证登录 |
| 账号密码登录 | `/api/agents/login` | 坐席/管理员账号密码+OTP登录 |
| MFA验证 | `/api/mfa/verify` | OTP验证码验证 |
---
## 2. 前置条件
### 2.1 测试账号
| 角色 | user_id | 密码 | MFA状态 | 说明 |
|------|---------|------|---------|------|
| 坐席 | `sxn` | `admin123` | 已绑定 | IT支持组组长 |
| 管理员 | `sxn` | `admin123` | 已绑定 | 同上，具有admin权限 |
| 普通员工 | `test_user` | - | 未绑定 | 仅user角色 |
### 2.2 环境要求
- 后端服务运行在 `http://127.0.0.1:8000`
- 前端服务：坐席端 `http://127.0.0.1:5177`，管理后台 `http://127.0.0.1:5178`
- Redis 服务正常运行
- PostgreSQL/SQLite 数据库正常运行
---
## 3. 测试用例
### 3.1 企微免密登录 (/jsdk-login)
| TC_ID | 测试场景 | 前置条件 | 测试步骤 | 预期结果 | 实际结果 | 状态 |
|-------|----------|----------|----------|----------|----------|------|
| JSDK-01 | 企微用户具有坐席角色，免密登录 | user_id 具有 agent 角色 | 1. 前端调用 jsdk-login 传入 userid<br>2. 后端查询角色列表 | 返回 token 和 roles=["agent"] | | 待测试 |
| JSDK-02 | 企微用户具有管理员角色，免密登录 | user_id 具有 admin 角色 | 同上 | 返回 token 和 roles=["admin"] | | 待测试 |
| JSDK-03 | 企微用户具有坐席+管理员角色 | user_id 同时具有 agent 和 admin | 同上 | 返回 token 和 roles=["admin","agent"] | | 待测试 |
| JSDK-04 | 企微用户仅具有user角色 | user_id 只有 user 角色 | 同上 | 返回 403 错误："您没有坐席或管理员权限" | | 待测试 |
| JSDK-05 | 企微用户无任何角色 | user_id 不在 user_roles 表 | 同上 | 返回 403 错误 | | 待测试 |
### 3.2 账号密码登录 (/agents/login)
| TC_ID | 测试场景 | 前置条件 | 测试步骤 | 预期结果 | 实际结果 | 状态 |
|-------|----------|----------|----------|----------|----------|------|
| PWD-01 | 正确账号密码+OTP登录 | 坐席账号、已绑定MFA | 1. 输入正确账号密码<br>2. 点击登录<br>3. 输入正确OTP | 返回 token，进入工作台 | | 待测试 |
| PWD-02 | 正确账号密码+错误OTP | 坐席账号、已绑定MFA | 1. 输入正确账号密码<br>2. 点击登录<br>3. 输入错误OTP | 返回错误："OTP验证码错误" | | 待测试 |
| PWD-03 | 正确账号密码+无OTP | 坐席账号、已绑定MFA | 1. 输入正确账号密码<br>2. 点击登录（不输入OTP） | 返回 require_otp: true，提示输入OTP | | 待测试 |
| PWD-04 | 错误账号 | 不存在的账号 | 输入错误的user_id | 返回错误："用户不存在" | | 待测试 |
| PWD-05 | 错误密码 | 正确的user_id，错误密码 | 输入错误的password | 返回错误："本地密码错误" | | 待测试 |
| PWD-06 | 账号密码登录（未绑定MFA） | 坐席账号、未绑定MFA | 输入正确的账号密码 | 直接返回 token，无需OTP | | 待测试 |
### 3.3 MFA 验证
| TC_ID | 测试场景 | 前置条件 | 测试步骤 | 预期结果 | 实际结果 | 状态 |
|-------|----------|----------|----------|----------|----------|------|
| MFA-01 | 正确OTP验证码 | 已绑定MFA的坐席 | 调用 /api/mfa/verify | 返回验证成功 | | 待测试 |
| MFA-02 | 错误OTP验证码 | 已绑定MFA的坐席 | 输入错误的OTP | 返回验证失败 | | 待测试 |
| MFA-03 | 已验证状态（30分钟内） | 之前已通过OTP验证 | 再次调用需要MFA的接口 | 无需再次OTP | | 待测试 |
---
## 4. 执行记录
| 执行日期 | 测试人员 | 环境 | 备注 |
|----------|----------|------|------|
| 2026-07-06 | | 本地开发环境 | 首轮测试 |
---
## 5. 缺陷记录
| 缺陷ID | 对应TC | 描述 | 严重程度 | 状态 |
|--------|--------|------|----------|------|
| | | | | |
---
## 6. 修订历史
| 版本 | 日期 | 变更内容 | 修改人 |
|------|------|----------|--------|
| v1.0 | 2026-07-06 | 初始版本 | Claude |