simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
364e68838242f885a787c3787fe98c6f0bdd2f60
wecom_it_smart_desk/docs/调试验证指南_2026-06-13.md
T
Simon 364e688382 chore(release): v0.5.0-beta 发版准备 
主要改动:

backend 业务:
- feat(error-codes): 统一错误码表 E1011/E1012 拆码
  - E1011 AUTH_PASSWORD_WRONG: 本地密码错误
  - E1012 AUTH_FIRST_LOGIN_PASSWORD_REQUIRED: 首次登录请先设置密码
  - E1015 AUTH_OLD_PASSWORD_REQUIRED: 改密需要旧密码
  - E1016 AUTH_OLD_PASSWORD_WRONG: 旧密码错误
- fix(agents): P0 降级放行时,如坐席已注册但未设密码,正确 raise 1012
  (修复前会撞 1011 本地密码错误,与场景不符)
- feat(approval): 审批模块 (T审批/A审批)
- feat(config): approval_template_resource / approval_template_device 配置
- feat(main): /ready, /metrics, /version 端点(K8s 友好)

backend 测试:
- test(agents): 新增 test_agents.py — 3 个 Fix-4 降级登录测试
  - 错误密码拒绝
  - 缺密码拒绝
  - 正确密码通过
  pytest tests/test_agents.py → 3/3 通过
- test(conftest): 模块级 mock + slowapi 限流重置 + UTF-8 patch
  解决 Windows pytest GBK 读 .env 失败 + 降级路径无法测试

仓库治理:
- chore(gitignore): 排除 .workbuddy/memory/(workbuddy 本地记忆)
- chore(docs): 重命名两份 IT 文档(前缀加智能区分版本)

部署与文档:
- docs: RELEASE_NOTES_v0.5.0-beta.md / dashboard.html / 需求-发版预览页面
- docs: 部署、架构、PRD、安全、评审报告等同步 v0.5.0-beta
- deploy-server: 打包脚本、nginx、docker-compose 版本号 bump

前端 (frontend-h5 / frontend-agent / frontend-admin / frontend-portal):
- index.html / package.json 版本号与构建号 bump

自动验收(RELEASE_NOTES L100-104):
- [x] pytest tests/test_agents.py -v → 3 passed
- [x] grep Bs7ucT backend frontend-h5 frontend-agent → 无输出
- [x] grep AppException(101[123]) backend → 仅 1 处(登录场景 1012)
- [ ] npm run build (frontend-h5 / frontend-agent) → 合并后跑

后续: 合并 feature/t-1-t4-merge → main,tag v0.5.0-beta
2026-06-15 14:14:58 +08:00

11 KiB
Raw Blame History

智能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. 登录 企微管理后台
  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 文件中配置：

# 企微配置（测试应用）
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
  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 View Git Blame Copy Permalink