# 通讯链路诊断方案

> 日期：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失败时静默失败

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

---

## 六、下一步

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