# channel-service 与 mci-server 双向集成设计

> **需求来源**：继续完成 pywechat 客户端功能，打通 Python 渠道服务与 Java 消息中台的双向通信。  
> **日期**：2026-07-10  
> **状态**：待实现  
> **关联文档**：`docs/architecture/2026-07-06-message-customer-interaction-design.md`

---

## 1. 目标与范围

### 1.1 目标

让 `channel-service`（Python FastAPI）与 `mci-server`（Java Spring Boot）完成双向 HTTP 集成：

- **下行（mci-server → channel-service）**：mci-server 继续通过现有 REST API 调用 channel-service 的发送、登录控制等指令。
- **上行（channel-service → mci-server）**：channel-service 把心跳、登录/在线状态变更、发送结果、异常事件持久化到本地 SQLite，并由后台 worker 可靠地推送到 mci-server。
- **可靠性**：服务重启不丢事件；网络异常按指数退避重试；超次进死信；本地事件保留 10 天后自动清理。

### 1.2 范围

- **channel-service**：新增事件模型、SQLite 持久化、后台事件发布 worker、mci-server HTTP 客户端、配置项扩展、API 行为调整。
- **mci-server**：新增 `/api/v1/channel-account/event` 接收端点，处理心跳/状态/发送结果事件并更新 `mci_channel_account`、`mci_send_record`。
- **不在本期范围**：
  - 真实 pywechat/pywinauto 接入（仍为 mock）。
  - RabbitMQ/MQ 等外部消息总线。
  - 入站消息从 channel-service 回传（本期只传运行态事件和发送结果）。

---

## 2. 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                        mci-server                            │
│  Java 21 + Spring Boot 4.1.x                                │
│  POST /api/v1/channel-account/event                         │
└───────────────────────┬─────────────────────────────────────┘
                        │  HTTP 上行事件
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                     channel-service                          │
│  Python 3.11 + FastAPI                                       │
│                                                              │
│  ┌─────────────┐    ┌──────────────────┐    ┌────────────┐ │
│  │  HTTP API   │───►│  业务操作 + 事件   │───►│ outbound_  │ │
│  │             │    │  写入 SQLite      │    │ events     │ │
│  └─────────────┘    └──────────────────┘    └─────┬──────┘ │
│                                                   │         │
│                              ┌────────────────────┘         │
│                              ▼                              │
│                     ┌─────────────────┐                     │
│                     │ EventPublisher  │                     │
│                     │ 单线程 worker   │                     │
│                     └────────┬────────┘                     │
│                              │                              │
│                              ▼                              │
│                     ┌─────────────────┐                     │
│                     │ mci_server_client│                    │
│                     │ HTTP POST        │                    │
│                     └─────────────────┘                     │
└─────────────────────────────────────────────────────────────┘
```

核心原则：**状态变更/发送操作与事件写入在同一个 SQLite 事务内完成**，保证原子性。

---

## 3. channel-service 设计

### 3.1 新增模块

| 模块 | 路径 | 职责 |
|------|------|------|
| 事件模型 | `app/models/event.py` | `OutboundEvent` 数据类、事件类型枚举、payload schema |
| 事件存储 | `app/repositories/event_store.py` | SQLite 建表、CRUD、事务、清理 |
| 事件发布 | `app/services/event_publisher.py` | 后台单线程 worker、重试、死信 |
| mci-server 客户端 | `app/clients/mci_server_client.py` | HTTP POST 到 mci-server |
| 配置扩展 | `app/config.py` | 新增事件存储、重试、清理相关配置 |

### 3.2 SQLite 事件表 `outbound_events`

```sql
CREATE TABLE IF NOT EXISTS outbound_events (
    id TEXT PRIMARY KEY,
    event_type TEXT NOT NULL,
    payload TEXT NOT NULL,
    status TEXT NOT NULL DEFAULT 'pending',
    attempt_count INTEGER NOT NULL DEFAULT 0,
    next_retry_at TIMESTAMP NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    last_error TEXT
);

CREATE INDEX IF NOT EXISTS idx_status_next_retry
    ON outbound_events(status, next_retry_at);

CREATE INDEX IF NOT EXISTS idx_created_at
    ON outbound_events(created_at);
```

字段说明：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | TEXT PK | UUID v4，即 `event_id` |
| `event_type` | TEXT | `heartbeat` / `login_status_changed` / `online_status_changed` / `send_result` / `error` |
| `payload` | TEXT | JSON 字符串，见第 3.3 节 |
| `status` | TEXT | `pending` / `retrying` / `delivered` / `dead_letter` |
| `attempt_count` | INTEGER | 已尝试次数，上限 `max_retry` |
| `next_retry_at` | TIMESTAMP | 下次重试时间；`pending` 事件为创建时间 |
| `created_at` | TIMESTAMP | 创建时间，用于 10 天清理 |
| `updated_at` | TIMESTAMP | 更新时间 |
| `last_error` | TEXT | 最近一次失败摘要 |

### 3.3 事件 payload 统一结构

所有事件统一外层：

```json
{
  "event_id": "evt_20260710_xxx",
  "event_type": "heartbeat",
  "account_id": "wx-bot-01",
  "tenant_code": "rescue",
  "timestamp": "2026-07-10T10:00:00Z",
  "data": { }
}
```

`data` 按事件类型定义：

#### heartbeat

```json
{
  "login_status": "success",
  "online_status": "online",
  "risk_level": 10,
  "sent_count_today": 5,
  "server_host": "win-svr-01"
}
```

#### login_status_changed

```json
{
  "previous": "pending",
  "current": "success",
  "qr_code_url": "https://mock.pywechat.qrcode/...",
  "error_message": null
}
```

#### online_status_changed

```json
{
  "previous": "offline",
  "current": "online"
}
```

#### send_result

```json
{
  "task_id": "task_001",
  "record_id": 1001,
  "conversation_id": "room-001",
  "success": true,
  "message_id": "msg-123",
  "channel_result": {},
  "error": null
}
```

> 说明：`record_id` 由 mci-server 在调用 send API 时传入；channel-service 原样回传，用于 mci-server 更新 `mci_send_record`。

#### error

```json
{
  "operation": "send_text",
  "error_code": "ACCOUNT_OFFLINE",
  "error_message": "account wx-bot-01 not online"
}
```

### 3.4 API 行为变更

| API | 变更 |
|------|------|
| `POST /v1/wechat-personal/login/start` | 创建/更新账号、生成二维码，并在同一事务写入 `login_status_changed` 事件 |
| `POST /v1/wechat-personal/login/{id}/confirm` | 确认登录后，在同一事务写入 `login_status_changed` + `online_status_changed` |
| `POST /v1/wechat-personal/login/{id}/expire` | 二维码过期后，写入 `login_status_changed` 事件 |
| `POST /v1/wechat-personal/send/text` | 改为**异步受理**：立即返回 `{"accepted": true, "message_id": "..."}`；真实发送完成后写入 `send_result` 事件 |
| `POST /v1/wechat-personal/send/image` | 同上 |
| `POST /v1/heartbeat` | 更新本地状态，并在同一事务写入 `heartbeat` 事件 |
| `POST /v1/admin/retry-dead-letter`（新增） | 手动把 `dead_letter` 状态重置为 `retrying`，用于人工恢复 |

### 3.5 发送异步化与风控

当前仍为 mock 客户端，但接口行为需与真实 pywechat 一致：

1. `send_text` / `send_image` 收到请求后，先校验账号在线、风控等级。
2. 校验通过后返回 `accepted=true`，并立即写入 `send_result` 事件。
3. mock 场景下该事件直接表示成功；真实 pywechat 场景下，发送完成后用同一 `event_id` 更新 `send_result` 事件内容，或删除旧事件后写入最终结果事件。

**风控处理**：

- 风控等级 `risk_level >= 80` 的账号，发送请求直接返回失败，不进入重试。
- 因微信风控导致的发送失败（如 `error_code` 为 `RISK_CONTROL_BLOCKED`、`ACCOUNT_BANNED`），事件直接标记为 `dead_letter`，不再重试。
- 因网络超时、mci-server 不可达等**临时错误**，才进入指数退避重试。
- `sent_count_today` 每日重置，channel-service 在心跳中上报，mci-server 可据此做策略判断。

### 3.6 EventPublisher 后台 worker

- **单线程执行**：使用一个 `asyncio` 任务循环消费，避免并发导致 SQLite 锁竞争或事件乱序。
- **扫描频率**：每 5 秒一次。
- **每次拉取**：最多 100 条 `status IN ('pending','retrying') AND next_retry_at <= now()`，按 `next_retry_at` 升序。
- **推送目标**：`{mci_server_url}/api/v1/channel-account/event`。
- **成功**：`status='delivered'`，`attempt_count` 不变。
- **失败**：
  - `attempt_count += 1`
  - `next_retry_at = now + base_delay * 2^(attempt_count - 1)`（首次重试为 `base_delay`，第二次为 `2*base_delay`，依此类推）
  - `status='retrying'`
  - `last_error` 记录 HTTP 状态码或异常摘要
  - 若 `attempt_count >= max_retry`，则 `status='dead_letter'`
- **最大重试次数**：由配置 `max_retry` 控制，默认 `5`，上限 `10`（代码中硬上限，防止配置错误）。
- **服务启动**：从 `main.py` 启动时创建 worker；启动后自动恢复 `pending` / `retrying` 事件。
- **服务关闭**：优雅关闭时等待当前批次处理完成（超时 5 秒）。

### 3.7 数据清理

- 每天凌晨 3:00 启动清理任务（或每次 worker 循环顺带清理）。
- 删除 `status IN ('delivered','dead_letter')` 且 `created_at < CURRENT_TIMESTAMP - INTERVAL '10 days'` 的事件。
- 保留 `pending` / `retrying` 事件，无论创建时间。

### 3.8 配置项

```env
# mci-server 地址
MCI_SERVER_URL=http://localhost:8080/msg-platform

# SQLite 事件库路径
EVENT_STORE_PATH=./data/events.db

# 心跳间隔（秒）
HEARTBEAT_INTERVAL_SECONDS=30

# 最大重试次数（代码硬上限 10）
MAX_RETRY=5

# 基础重试延迟（秒）
BASE_RETRY_DELAY_SECONDS=5

# 事件保留天数
EVENT_RETENTION_DAYS=10

# 后台 worker 扫描间隔（秒）
EVENT_PUBLISH_INTERVAL_SECONDS=5
```

---

## 4. mci-server 设计

### 4.1 新增端点

#### POST `/api/v1/channel-account/event`

接收 channel-service 推送的统一事件。

**请求头**：

```http
Content-Type: application/json
```

**请求体**：见第 3.3 节统一 payload。

**处理逻辑**：

| event_type | 处理 |
|------------|------|
| `heartbeat` | 根据 `account_id` 查询 `mci_channel_account`；更新 `login_status`、`online_status`、`last_heartbeat`、`risk_level`、`sent_count_today` |
| `login_status_changed` | 更新 `mci_channel_account.login_status`；如果 `current=success` 则同时更新 `online_status=1` |
| `online_status_changed` | 更新 `mci_channel_account.online_status` |
| `send_result` | 根据 `record_id` 查询 `mci_send_record`；更新 `send_status`（`success=true` 则为 2，否则 3）、`finish_time`、`channel_result`；成功后调用 `SendCallbackService.sendCallback()` 向业务系统回调 |
| `error` | 记录告警日志，可扩展发送告警通知 |

**状态字段映射**（channel-service 字符串 → mci-server 整数）：

| channel-service 字段 | mci-server 字段 | 映射关系 |
|----------------------|-----------------|----------|
| `login_status` | `mci_channel_account.login_status` | `pending=0`, `scanning=0`, `success=1`, `expired=2`, `failed=3` |
| `online_status` | `mci_channel_account.online_status` | `offline=0`, `online=1`, `error=2` |

账号定位：使用 `tenant_code` + `account_id` 联合查询 `mci_channel_account`，确保租户隔离。

**幂等**：

- 使用 `event_id` 作为幂等键。
- 第一次收到时写入 `mci_channel_event` 去重表；重复事件直接返回 200。

**响应**：

```json
{
  "code": 0,
  "message": "ok",
  "data": null,
  "request_id": "..."
}
```

### 4.2 保持现有端点

- `POST /api/v1/channel-account/heartbeat`：保持兼容，但建议新接入走 `/event`。
- `POST /api/v1/channel-account/init`：继续调用 `WechatPersonalChannelAdapter`，由 adapter 调用 channel-service `/v1/wechat-personal/login/start`。

### 4.3 发送流程补齐

为了让 `send_result` 能回写到正确的 `mci_send_record`，需要在 mci-server 调用 channel-service 发送时传入 `record_id`：

1. `SendService.dispatchRecord(record)` 调用 `ChannelAdapter.sendMessage(request)`。
2. `SendMessageRequest.extra` 中带上 `record_id`。
3. `WechatPersonalChannelAdapter.sendMessage()` 把 `record_id` 放入 body，调用 channel-service `/v1/wechat-personal/send/text` 或 `/send/image`。
4. channel-service 异步完成后，通过 `/event` 回传 `send_result` 并携带 `record_id`。

### 4.4 数据库表扩展

#### 4.4.1 新增幂等表 `mci_channel_event`

用于防止 channel-service 重试导致重复处理。

| 字段 | 类型 | 说明 |
|------|------|------|
| `event_id` | VARCHAR PK | channel-service 事件 ID |
| `account_id` | VARCHAR | 账号 ID |
| `event_type` | VARCHAR | 事件类型 |
| `create_time` | DATETIME | 接收时间 |

索引：`CREATE INDEX idx_account_time ON mci_channel_event(account_id, create_time);`

清理策略：保留 30 天后删除（可配置）。

---

## 5. 错误处理与边界

| 场景 | 处理 |
|------|------|
| mci-server 不可达 | 事件留在 SQLite，worker 按指数退避重试 |
| 服务重启 | 启动时恢复 worker，继续推送 `pending` / `retrying` 事件 |
| payload 序列化失败 | 直接标记 `dead_letter`，不阻塞其他事件 |
| mci-server 返回业务错误（如账号不存在） | 视为失败重试；若连续失败达到上限，进 `dead_letter` |
| 微信风控/账号被封 | 对应 `error_code` 直接标记 `dead_letter`，不重试 |
| SQLite 磁盘满/损坏 | worker 记录错误并停止推送；监控告警 |
| 单条事件推送超时 | 使用 `httpx` timeout（默认 10s），超时即失败进入重试 |
| 重试次数达到上限 | `status='dead_letter'`，记录 `last_error`，等待人工处理或手动重试 |
| 事件堆积 | worker 每批最多 100 条；如果持续堆积，考虑后续改为批量 POST 或引入 MQ |

---

## 6. 测试策略

### 6.1 channel-service 单元测试

- `test_event_store.py`：验证 SQLite CRUD、事务、状态流转、清理。
- `test_event_publisher.py`：mock mci-server HTTP，验证重试、死信、幂等。
- `test_send_async.py`：验证 send API 改为异步受理后，事件正确写入 `outbound_events`。
- `test_heartbeat_event.py`：验证心跳接口产生事件。

### 6.2 mci-server 单元测试

- `ChannelAccountEventControllerTest`：使用 MockWebServer 或 `MockMvc` 接收 channel-service 事件，验证：
  - heartbeat 更新 `mci_channel_account`
  - send_result 更新 `mci_send_record`
  - event_id 幂等

### 6.3 联调测试

- docker-compose 启动 mci-server + channel-service。
- 调用 mci-server 发送 API。
- 验证 channel-service 收到指令、产生 send_result 事件、推回 mci-server。
- 验证 mci-server 更新 SendRecord 并向业务系统 callback_url 回调。

---

## 7. 部署与配置

### 7.1 channel-service 新增环境变量

```yaml
environment:
  MCI_SERVER_URL: http://mci-server:8080/msg-platform
  EVENT_STORE_PATH: /app/data/events.db
  HEARTBEAT_INTERVAL_SECONDS: "30"
  MAX_RETRY: "5"
  BASE_RETRY_DELAY_SECONDS: "5"
  EVENT_RETENTION_DAYS: "10"
  EVENT_PUBLISH_INTERVAL_SECONDS: "5"
```

### 7.2 数据卷

```yaml
volumes:
  - channel-service-data:/app/data
```

---

## 8. 后续扩展

- 入站消息从 channel-service 回传 mci-server（复用 `/event` 新增 `message_received` 类型）。
- 批量事件上报：把多条事件打包为一个 HTTP 请求，降低 mci-server 压力。
- 当事件量增大时，可考虑用 RabbitMQ 替代 SQLite + HTTP worker。
- 真实 pywechat 接入时，把 mock 客户端替换为 `pywechat`/`pywinauto` 驱动，事件模型保持不变。

---

*设计完成，待评审。*