# 技术方案：消息推送策略优化与超时提醒

> **需求来源**：2026-07-05 产品讨论
> **版本**：v1.0
> **状态**：✅ 已开发完成

---

## 一、需求概述

### 1.1 业务背景

当前坐席回复用户消息时，会同时走两个通道：
1. **WebSocket** → 推送到 H5 页面
2. **企微应用消息** → 推送到"IT支持服务"应用的消息列表

这导致两种场景混在一起：
- 场景A：员工找坐席（一对一私密对话）→ 期望只走 H5
- 场景B：IT支持组群发通知 → 期望走企微消息

### 1.2 产品需求

| 需求 | 描述 |
|------|------|
| R1 | 正常对话：坐席回复仅推送到 H5 页面（WebSocket） |
| R2 | 坐席回复后员工 3 分钟（可配置）未回复，发送企微提醒消息 |
| R3 | 提醒消息只发 1 次 |
| R4 | 10 分钟后自动标记会话为"待关闭"状态 |
| R5 | 提醒文案固定（见 1.3） |

### 1.3 提醒文案

```
IT服务提醒：您有新的消息未查看，咨询将在10分钟后标记为待关闭，请尽快点击处理 👉 https://itsupport.servyou.com.cn/itdesk/
```

---

## 二、技术方案

### 2.1 架构设计

```
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  坐席发送   │────▶│   WebSocket  │────▶│   H5页面       │
│  消息       │     │  (仅推送H5)  │     │  (实时可见)    │
└─────────────┘     └──────────────┘     └─────────────────┘
       │
       ▼ (触发条件)
┌─────────────────────────────────────────┐
│        后台定时任务 (每30秒)            │
│  • 检查超时未回复会话                  │
│  • 发送企微提醒消息                    │
│  • 标记会话状态                        │
└─────────────────────────────────────────┘
```

### 2.2 数据库改动

#### 2.2.1 conversations 表新增字段

```sql
ALTER TABLE conversations
ADD COLUMN IF NOT EXISTS last_agent_reply_at TIMESTAMP DEFAULT NULL,
ADD COLUMN IF NOT EXISTS reminder_sent BOOLEAN DEFAULT FALSE,
ADD COLUMN IF NOT EXISTS reminder_sent_at TIMESTAMP DEFAULT NULL,
ADD COLUMN IF NOT EXISTS pending_close_at TIMESTAMP DEFAULT NULL;
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `last_agent_reply_at` | TIMESTAMP | 坐席最后回复时间 |
| `reminder_sent` | BOOLEAN | 是否已发送提醒 |
| `reminder_sent_at` | TIMESTAMP | 提醒发送时间 |
| `pending_close_at` | TIMESTAMP | 待关闭时间（最后回复+10分钟） |

#### 2.2.2 配置表（可选）

在系统配置表中添加：

| key | default | 说明 |
|-----|---------|-----|
| `reminder.timeout_minutes` | 3 | 未回复超时时间（分钟） |
| `reminder.close_minutes` | 10 | 自动待关闭时间（分钟） |
| `reminder.enabled` | true | 是否启用提醒功能 |

### 2.3 后端改动

#### 2.3.1 消息发送逻辑修改

**文件**：`backend/app/api/messages.py`

```python
# 坐席发送消息时
async def send_message(...):
    # 1. 仅通过 WebSocket 推送到 H5（不再调用企微 API）
    await manager.send_to_employee(conversation.employee_id, ws_event)

    # 2. 更新会话的最后坐席回复时间
    conversation.last_agent_reply_at = datetime.now()
    conversation.reminder_sent = False  # 重置提醒标记
    conversation.pending_close_at = datetime.now() + timedelta(minutes=10)
```

#### 2.3.2 新增定时任务

**文件**：`backend/app/tasks/reminder_task.py`（新建）

```python
# 每 30 秒执行一次
@scheduler.scheduled_job('interval', seconds=30)
async def check_unreplied_sessions():
    """检查超时未回复的会话，发送提醒"""

    # 1. 查找需要处理的会话
    sessions = await db.execute(select(Conversation).where(
        Conversation.status == 'active',
        Conversation.last_agent_reply_at.isnot(None),
        Conversation.reminder_sent == False,
        Conversation.last_agent_reply_at < (datetime.now() - timedelta(minutes=3))
    ))

    for session in sessions:
        # 2. 发送企微提醒消息
        await send_reminder_message(session)

        # 3. 标记已发送
        session.reminder_sent = True
        session.reminder_sent_at = datetime.now()

    # 4. 处理待关闭会话
    pending = await db.execute(select(Conversation).where(
        Conversation.status == 'active',
        Conversation.pending_close_at < datetime.now()
    ))

    for session in pending:
        session.status = 'pending_close'  # 待关闭状态

    await db.commit()
```

#### 2.3.3 提醒消息发送函数

**文件**：`backend/app/services/reminder_service.py`（新建）

```python
async def send_reminder_message(conversation: Conversation):
    """发送超时提醒企微消息"""

    message = "IT服务提醒：您有新的消息未查看，咨询将在10分钟后标记为待关闭，请尽快点击处理 👉 https://itsupport.servyou.com.cn/itdesk/"

    redis_client = settings.create_redis_client()
    wecom_service = WecomService(redis_client)

    try:
        await wecom_service.send_text_message(
            conversation.employee_id,
            message
        )
    finally:
        await wecom_service.close()
        await redis_client.close()
```

### 2.4 前端改动

#### 2.4.1 坐席端（无需改动）

当前坐席发送消息功能保持不变，后端会自动处理推送逻辑。

#### 2.4.2 H5 端（无需改动）

WebSocket 接收消息逻辑保持不变。

### 2.5 部署配置

#### 2.5.1 后端定时任务启动

在 `backend/app/main.py` 中注册定时任务：

```python
from apscheduler.schedulers.asyncio import AsyncIOScheduler

scheduler = AsyncIOScheduler()
scheduler.add_job(check_unreplied_sessions, 'interval', seconds=30)
scheduler.start()
```

---

## 三、实现情况

| 任务 | 状态 | 文件位置 |
|------|------|----------|
| 数据库迁移 | ✅ 已完成 | `backend/migrations/versions/001_add_reminder_fields.sql` |
| 数据模型更新 | ✅ 已完成 | `backend/app/models/conversation.py` |
| 消息发送逻辑修改 | ✅ 已完成 | `backend/app/api/messages.py` |
| 新建提醒服务 | ✅ 已完成 | `backend/app/services/reminder_service.py` |
| 新建定时任务 | ✅ 已完成 | `backend/app/tasks/reminder_task.py` |
| 定时任务注册 | ✅ 已完成 | `backend/app/main.py` |

---

## 四、上线前置条件

1. 在生产数据库执行迁移脚本 `001_add_reminder_fields.sql`
2. 重启后端服务以加载定时任务

---

## 五、风险与注意事项

1. **定时任务并发**：多实例部署时需确保任务不重复执行（建议加分布式锁）
2. **历史数据**：已存在的会话不受影响，新逻辑仅对新增会话生效
3. **配置灵活性**：当前为固定值，后续可扩展为可配置

---

## 六、相关文件清单

| 文件 | 操作 |
|------|------|
| `backend/app/api/messages.py` | 修改 |
| `backend/app/services/reminder_service.py` | 已存在 |
| `backend/app/tasks/reminder_task.py` | 已存在 |
| `backend/app/main.py` | 修改 |
| `docs/03-技术架构/02-技术方案/技术方案-消息推送策略优化与超时提醒.md` | 本文档 |

---

*最后更新：2026-07-05 18:20*