wecom_it_smart_desk/docs/09-部署运维/troubleshooting-故障排查/通讯链路诊断方案.md

通讯链路诊断方案

日期：2026-07-03 目标：诊断当前系统通讯问题，无论结果启动重构方案

---

一、通讯链路架构

┌─────────────────────────────────────────────────────────────────────────┐
│                          完整通讯链路                                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  【用户 → 坐席】                                                        │
│  ┌──────────┐    企微回调      ┌──────────┐    路由       ┌─────────┐ │
│  │ 用户发送  │ ──────────────→ │ 后端API  │ ──────────→ │ Message │ │
│  │ 消息     │    /wecom/      │ 回调入口  │             │ Router  │ │
│  └──────────┘    callback      └──────────┘             └────┬────┘ │
│        │                                                │         │
│        │                                                ▼         │
│        │                                         ┌───────────┐   │
│        │                                         │  消息入库  │   │
│        │                                         │ (DB存储)  │   │
│        │                                         └───────────┘   │
│        │                                                │         │
│        │                              ┌────────────────┘         │
│        │                              ▼                          │
│        │                       ┌──────────┐                     │
│        │                       │ 坐席收到  │                     │
│        │                       │(WS/轮询) │                     │
│        │                       └──────────┘                     │
│        │                                                         │
│  【坐席 → 用户】                                                        │
│  ┌──────────┐    API调用      ┌──────────┐    企微API   ┌────────┐ │
│  │ 坐席发送 │ ──────────────→ │ 后端API  │ ──────────→ │企微    │ │
│  │ 消息     │   POST         │ 发送消息  │  /message  │服务器  │ │
│  └──────────┘   /conversations└──────────┘   /send    └────┬───┘ │
│        │         /{id}/messages    │                    │       │
│        │                        ▼                    ▼       │
│        │                 ┌──────────┐            ┌────────┐   │
│        │                 │ 消息入库  │            │用户收到 │   │
│        │                 │(DB存储)  │            │消息    │   │
│        │                 └──────────┘            └────────┘   │
│        │                                                         │
└─────────────────────────────────────────────────────────────────┘

---

二、诊断检查点

2.1 企微回调链路（用户 → 系统）

检查点	文件位置	检查内容	预期结果
C-01	wecom_callback.py GET /wecom/callback	企微URL验证	返回解密后的echostr
C-02	wecom_callback.py POST /wecom/callback	消息解密	正确解析XML并解密
C-03	message_router.py	消息路由	正确分配会话/坐席
C-04	数据库 messages 表	消息存储	消息正确写入

2.2 坐席发送链路（系统 → 用户）

检查点	文件位置	检查内容	预期结果
C-05	messages.py POST /conversations/{id}/messages	API入口	正确接收坐席消息
C-06	wecom_service.py send_text_message()	企微API调用	errcode=0
C-07	企微客户端	用户收到消息	正常展示

2.3 H5 实时推送

检查点	文件位置	检查内容	预期结果
C-08	ws_manager.py	WS连接管理	坐席WS连接
C-09	frontend-agent	WS接收	消息实时展示
C-10	frontend-h5	轮询/WebSocket	新消息实时更新

---

三、已发现的问题

问题1：非文本消息不推送（messages.py:210-233）

# 只有 text 类型消息才调用企微 API 推送给员工
if body.msg_type == "text":
    # 调用企微API

影响：图片、文件等消息无法推送到用户微信端

问题2：dev_mode 短路（messages.py:215-216）

if getattr(settings, 'dev_mode', False):
    logger.debug(f"[DEV] 跳过企微推送: msg_id={message.id}")

影响：测试环境下消息不会推送到用户

问题3：企微API错误处理（messages.py:231-233）

except Exception as e:
    # 企微 API 调用失败不阻塞消息存储
    logger.warning(f"企微消息发送失败（消息已存储）: {e}")

影响：企微API失败时仅记录日志，用户实际未收到消息

---

四、诊断执行记录

时间	检查项	结果	说明
2026-07-03	代码审查	✅	完成链路分析
-	C-01 企微回调	⏳	待部署环境验证
-	C-05 坐席发送	⏳	待部署环境验证
-	C-07 用户收到	⏳	待实际测试

---

五、结论

当前系统通讯链路代码完整，但存在以下已知风险：

1. 非文本消息（图片/文件）无法推送
2. dev_mode 会跳过企微推送
3. 企微API失败时静默失败

这些问题可通过系统重构进一步优化消息通讯能力。

---

六、下一步

下一步：根据诊断结果优化现有通讯链路