wecom_it_smart_desk/overview.md

邀请链接企微打开报错 Bug 修复 - 交付总结

TL;DR

修复了被邀请员工点击企微卡片邀请链接报错的 3 个关联 Bug，后端和前端均已部署到生产环境并验证通过。

交付概览

• 交付状态: ✅ 全部完成并部署
• 测试通过率: 12/12 新增测试 + 35/35 回归测试 = 47/47 (100%)
• 已知问题数: 0

修复的 3 个关联 Bug

Bug 1 — 邀请 URL 为相对路径（后端）

• 文件: backend/app/services/session_service.py 第 1187-1191 行
• 问题: getattr(self, '_h5_base_url', '') 返回空字符串，邀请 URL 为 /h5/?invite=...（无域名），企微卡片无法跳转
• 修复: 使用 settings.wecom_sso_callback_base.rstrip('/') 构建绝对路径 https://itsupport.servyou.com.cn/h5/?invite=...

Bug 2 — join_conversation 状态校验过严（后端）

• 文件: backend/app/services/session_service.py 第 1242-1244 行
• 问题: 只允许 serving 状态加入会话，ai_handling 状态被拒
• 修复: not in ("serving", "ai_handling")

Bug 3 — OAuth2 重定向 + 视频引导丢失邀请参数（前端）

• 3a: frontend-h5/src/stores/employee.ts 第 300-310 行 — redirectToOAuth() 保存 invite/eid 到 sessionStorage
• 3b: frontend-h5/src/router/index.ts 第 230-244 行 — OAuth2 回调后从 sessionStorage 恢复参数
• 3c: frontend-h5/src/router/index.ts 第 195-208 行 — 有 invite 参数时跳过视频引导页

部署验证

后端

• settings.wecom_sso_callback_base = https://itsupport.servyou.com.cn ✅
• session_service.py 第 1143/1243 行状态校验含 ai_handling ✅
• 后端容器 healthy ✅

前端

• H5 页面 HTTP 200 ✅
• JS 含 h5_invite_conv_id (2处) ✅
• JS 含 h5_invite_eid (2处) ✅
• JS 含 h5_video_intro_watched_v2 (1处) ✅
• nginx 容器 healthy ✅

文件清单

文件	修改类型	部署状态
backend/app/services/session_service.py	修改 2 处	✅ 已部署
frontend-h5/src/stores/employee.ts	修改 1 处	✅ 已部署
frontend-h5/src/router/index.ts	修改 2 处	✅ 已部署
backend/tests/test_invite_link.py	新增	N/A（测试文件）

用户下一步建议

1. 企微端实际测试：在企微中发起一个会话，邀请其他员工，让被邀请员工点击企微卡片中的邀请链接验证完整流程
2. ai_handling 状态测试：在 AI 处理中的会话发起邀请，验证被邀请人能成功加入
3. 未登录场景测试：让未登录企微的员工打开邀请链接，验证 OAuth2 登录后邀请参数不丢失
4. 如遇到问题，可检查后端日志：docker logs wecom_it_backend --tail 50