# 微信公众号AI助手服务技术文档

## 1. 概述
本服务是一个基于Flask的微信公众号后端服务，实现了与Dify AI平台的集成。主要功能包括：
- 验证微信服务器请求的合法性
- 接收用户消息并调用Dify AI服务获取智能回复
- 通过微信客服消息接口异步返回AI回复
- 维护用户会话状态，支持多轮对话

## 2. 功能描述
| 功能模块 | 描述 | 实现方式 |
|---------|------|---------|
| 微信服务器验证 | 验证微信服务器请求的合法性 | SHA1签名验证 |
| 消息接收与路由 | 接收并处理用户消息 | XML解析与路由 |
| AI服务调用 | 调用Dify AI服务获取智能回复 | HTTP POST请求 |
| 会话管理 | 维护用户对话上下文 | 内存映射(conv_map) |
| 客服消息发送 | 异步发送AI回复给用户 | 微信客服消息接口 |
| 被动回复 | 即时返回"正在查询"提示 | XML格式响应 |

## 3. 环境要求
- Python 3.7+
- Flask 2.0+
- Requests库
- 微信公众号（服务号或订阅号）
- Dify AI服务（本地或云端）

## 4. 配置说明
在代码全局配置区设置以下参数：

```python
# 微信相关配置
TOKEN = "your_wechat_token"  # 与微信公众号后台配置一致
APPID = "your_appid"         # 微信公众号APPID
APPSECRET = "your_appsecret" # 微信公众号APPSECRET

# Dify AI服务配置
DIFY_API_BASE = "http://your-dify-server/api"  # Dify API地址
DIFY_API_KEY = "your_dify_api_key"             # Dify API密钥（可选）
```

## 5. 核心模块说明

### 5.1 微信服务器验证 (`/wx` GET请求)
- 验证流程：
  1. 获取请求参数：signature, timestamp, nonce, echostr
  2. 对token、timestamp、nonce进行字典序排序
  3. 拼接字符串并进行SHA1加密
  4. 比较加密结果与signature是否一致
- 成功：返回echostr
- 失败：返回403错误

### 5.2 消息处理 (`/wx` POST请求)
- 支持的消息类型：文本消息(MsgType=text)
- 处理流程：
  1. 解析XML消息体
  2. 提取用户OpenID、公众号ID和消息内容
  3. 启动后台线程调用AI服务
  4. 立即返回"正在查询"的被动回复

### 5.3 Dify AI服务调用 (`async_reply`函数)
```mermaid
sequenceDiagram
    participant W as 微信用户
    participant S as 本服务
    participant D as Dify AI服务
    W->>S: 发送文本消息
    S->>S: 启动后台线程
    S->>W: 返回"正在查询"提示
    S->>D: 发送用户消息和会话ID
    D->>S: 返回AI回复和会话ID
    S->>S: 更新会话映射(conv_map)
    S->>W: 通过客服消息发送AI回复
```

### 5.4 客服消息发送 (`send_wechat_customer_message`函数)
- 使用微信客服消息接口发送文本消息
- 前提条件：
  - 公众号已完成认证
  - 用户在48小时内与公众号有过交互
- 消息格式：
  ```json
  {
    "touser": "OPENID",
    "msgtype": "text",
    "text": {"content": "消息内容"}
  }
  ```

### 5.5 会话管理
- 使用全局字典`conv_map`存储会话状态
- 数据结构：`{user_openid: conversation_id}`
- 会话保持：每次调用Dify时带上conversation_id
- 新会话：当用户首次交互时自动创建新会话

## 6. 部署与运行

### 6.1 安装依赖
```bash
pip install flask requests
```

### 6.2 运行服务
```bash
python wechat_kefu.py
```

### 6.3 微信公众号配置
1. 服务器地址(URL): `http://your-domain/wx`
2. Token: 与代码中TOKEN一致
3. 消息加解密方式: 明文模式

## 7. 注意事项

### 7.1 安全性
1. 验证所有来自微信服务器的请求
2. 保护APP_SECRET和API_KEY不被泄露
3. 生产环境禁用DEBUG模式
4. 使用HTTPS加密传输

### 7.2 性能优化
1. 实现access_token缓存（有效期7200秒）
2. 限制用户请求频率
3. 使用连接池管理HTTP连接
4. 监控conv_map内存使用情况

### 7.3 异常处理
1. Dify服务不可用：返回用户友好提示
2. 客服消息发送失败：记录日志并重试
3. 会话丢失：自动创建新会话
4. 非文本消息：忽略并返回success

### 7.4 扩展性
1. 支持其他消息类型（如图片、语音）
2. 添加用户身份验证
3. 集成多个AI服务提供商
4. 实现消息队列处理异步任务

## 8. 常见问题排查

| 问题现象 | 可能原因 | 解决方案 |
|----------|---------|----------|
| 微信验证失败 | TOKEN配置不一致 | 检查公众号后台配置 |
| 无法接收消息 | 服务器网络问题 | 检查服务器防火墙设置 |
| 客服消息发送失败 | access_token过期 | 实现token缓存机制 |
| AI回复乱码 | 编码问题 | 检查Unicode解码逻辑 |
| 会话不连续 | conv_map未持久化 | 使用数据库存储会话 |

## 9. 版本信息
- 初始版本：1.0
- 最后更新：2025-06-05
- 依赖版本：
  - Flask 2.1.2
  - Requests 2.28.1

> 注意：本服务需要微信公众号具备客服消息接口权限，开发前请确认公众号类型和权限设置。