wecom_it_smart_desk/docs/E2E-CHECKLIST-v0.7.0.md

E2E 验收清单 v0.7.0(扫码登录 + MFA)

部署完 v0.7.0 后,逐项打勾。任何一项 ❌ 立即回滚。 每项给出预期结果 + 验证方法 + 失败处理。

---

0. 部署完成(用户跑过 DEPLOY-LOGIN-MIGRATION-v0.7.0.md 全部步骤)

• 后端 alembic upgrade head 跑通(head = 025_messages_id_uuid)
• 4 端 dist 已上传到宿主机 /opt/wecom-it-desk/frontend-*/dist/
• nginx nginx -t 通过 + nginx -s reload 完成
• docker restart wecom_it_backend 成功
• 容器状态 docker ps 显示 backend/redis/postgres 全部 Up

---

1. 扫码登录(Phase 1.1 / 1.2 / 1.3)

1.1 门户页面加载

• 浏览器打开 https://<生产域名>/itportal/
• 看到 QrcodeLogin 页面(二维码 + 倒计时)
• 不再显示旧的"账号密码"登录

1.2 二维码生成

• 倒计时从 120 秒开始
• 刷新按钮可用
• DevTools Network: POST /api/auth_qrcode/create 返回 200 + ticket

1.3 扫码

• 用企微扫 → 企微 OAuth2 跳回 callback
• 门户页面状态从 waiting → scanned(显示"已扫码,等待确认")
• DevTools Network: POST /api/auth_qrcode/scan 成功

1.4 坐席确认

• 已登录坐席在 /itagent/ 收到确认弹窗
• 点"确认"→ 门户 waiting → confirmed → 跳转 /itagent/
• localStorage 有 agent_token / portal_token

1.5 角色分发

• 双角色坐席(admin+agent)→ 跳 /itportal/select
• 仅 admin → 跳 /itadmin/
• 仅 agent → 跳 /itagent/
• 仅 user → 跳 /itdesk/

1.6 过期处理

• 120 秒不扫 → 状态变 expired + 提示"二维码已过期,请刷新"

---

2. MFA 绑定(Phase 2.4)

2.1 绑定入口

• 坐席登录后 → 顶栏头像 → "绑定 MFA"
• 进 /itagent/mfa-bind 页面

2.2 扫码绑定

• 看到 TOTP 二维码(otpauth://totp/...)
• 用 Google Authenticator / 微软 Authenticator 扫
• 输入 6 位 OTP → 点"验证" → 成功
• 页面显示"已绑定" + 备份信息

2.3 API 验证

• GET /api/mfa/status 返回 bound: true, enabled: true
• GET /api/mfa/users (admin) 看到该坐席 bound=true

---

3. MFA 验证(高危操作守卫)

3.1 30 分钟有效期

• 坐席 admin 角色登录 → 绑 MFA → 调 /api/admin/high-risk/demo/role_change
• 未先调 /api/mfa/verify → 返回 2001 需要 OTP
• 调 POST /api/mfa/verify {otp_code: "123456"} → 成功
• 再调 高危端点 → 200 通过
• 等 31 分钟 → 再次调 → 又返回 2001(TTL 失效)

3.2 5 类高危操作

• POST /api/admin/high-risk/demo/role_change → 200
• POST /api/admin/high-risk/demo/config_change → 200
• POST /api/admin/high-risk/demo/data_export → 200
• POST /api/admin/high-risk/demo/account_disable → 200
• POST /api/admin/high-risk/demo/account_create_reset → 200

3.3 角色拒绝

• 非 admin 角色调高危端点 → 4003 仅管理员

3.4 白名单查询

• GET /api/admin/high-risk/whitelist 返回 5 类元数据

---

4. P0/P1 合规验证

4.1 WebSocket 连接

• H5 员工端开 DevTools → Network → WS
• WS 连接建立,没有 1006 / missing argument 错误
• 坐席发消息 → H5 端 100ms 内收到(无轮询 3-5s 延迟)

4.2 消息 ID 类型

• psql -d wecom_it -c 'SELECT id FROM messages LIMIT 1;' 返回 UUID 格式
• 前端消息轮询不再偶发 500
• 跨会话消息不再串号

4.3 nginx access_log

• docker exec wecom_it_nginx tail /var/log/nginx/access.log | head -3
• 不包含 Authorization: / Cookie: 字样
• 只剩 IP / method / path / status

4.4 Gitea token

• cat .git/config | grep 5ad83d 返回空(token 已撤销)
• git push 试一下:应该失败(无 push 权限,符合预期)

---

5. 端到端业务流(回归)

5.1 H5 → 坐席 完整流程

• H5 员工发起会话 → 排队
• 坐席收到分配 → WS 推送
• 坐席发消息 → 员工 < 100ms 收到
• 转人工、邀请、满意度流程无 regression

5.2 管理员后台

• 仪表盘加载正常
• 坐席管理 CRUD 正常
• 功能开关可切换
• 集成配置 6 个系统显示完整
• MFA 管理页 /mfa-manage 表格可搜索/过滤/分页
• 重置 MFA 按钮可弹 ElMessageBox 二次确认

5.3 端点路径(临时 4 xfail)

• POST /api/conversations/{id}/messages 仍 404 — pre-existing,不影响生产
• 实际走 H5 的 /api/h5/conversations/current/messages 路径

---

6. 性能与稳定性

• 长时间压测(可选): wrk -t4 -c100 -d60s https://<域>/api/auth_qrcode/create
• 无 5xx 错误
• Redis 连接稳定(无 timeout)
• PG CPU < 50%

---

7. 回滚预案

如果任意 ❌ 项:

# 1. 停止后端
sudo docker stop wecom_it_backend

# 2. 恢复 4 端 dist
sudo cp -r /opt/wecom-it-desk/dist-backup-*/* /opt/wecom-it-desk/frontend-*/dist/

# 3. 回滚 alembic(只回 025,022/023 保留)
sudo docker start wecom_it_backend
sudo docker exec wecom_it_backend alembic downgrade 024

# 4. nginx 回滚
sudo docker exec wecom_it_nginx nginx -s reload

详见 DEPLOY-LOGIN-MIGRATION-v0.7.0.md 末尾"回滚预案"。

---

✅ 验收人签字

角色	姓名	日期	结果
部署
验收
复核