Simon
139 lines
6.7 KiB
Markdown
139 lines
6.7 KiB
Markdown
# 通讯链路诊断方案
|
||
|
||
> 日期：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）
|
||
|
||
```python
|
||
# 只有 text 类型消息才调用企微 API 推送给员工
|
||
if body.msg_type == "text":
|
||
# 调用企微API
|
||
```
|
||
|
||
**影响**：图片、文件等消息无法推送到用户微信端
|
||
|
||
### 问题2：dev_mode 短路（messages.py:215-216）
|
||
|
||
```python
|
||
if getattr(settings, 'dev_mode', False):
|
||
logger.debug(f"[DEV] 跳过企微推送: msg_id={message.id}")
|
||
```
|
||
|
||
**影响**：测试环境下消息不会推送到用户
|
||
|
||
### 问题3：企微API错误处理（messages.py:231-233）
|
||
|
||
```python
|
||
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失败时静默失败
|
||
|
||
这些问题可通过系统重构进一步优化消息通讯能力。
|
||
|
||
---
|
||
|
||
## 六、下一步
|
||
|
||
**下一步**：根据诊断结果优化现有通讯链路
|