200 lines
4.0 KiB
Markdown
200 lines
4.0 KiB
Markdown
# chatbot（微信对话回调服务）
|
||
|
||
本项目是一个基于 FastAPI 的微信对话开放平台回调服务，核心目标是：
|
||
|
||
- 接收并解密公众号私信回调（接口 A）
|
||
- 根据关键词回复用户（支持 H5 卡片）
|
||
- 后台触发抓包接口 B 获取会话列表
|
||
- 将用户资料同步到 PocketBase
|
||
|
||
---
|
||
|
||
## 一、当前实现状态
|
||
|
||
### 1) 回调入口（接口 A）
|
||
|
||
- 支持 `POST /`
|
||
- 支持 `POST /wechat/thirdapi`
|
||
- 支持加密请求体解析
|
||
- 支持解密后明文为 JSON / XML 两种格式
|
||
|
||
### 2) 关键词回复
|
||
|
||
内置规则：
|
||
|
||
- 包含 `电子书`：返回“数字游民”H5 内容
|
||
- 包含 `群`：返回“异度星球”H5 内容
|
||
- 其他内容：返回默认引导文案
|
||
|
||
### 3) 接口 B（抓包）
|
||
|
||
用于拉取会话列表（数据同步用途）：
|
||
|
||
- `https://chatbot.weixin.qq.com/miniopenai/manualservice/getaccessstautuslist`
|
||
|
||
### 4) PocketBase 同步
|
||
|
||
将用户资料写入 `wechat_private_users`，字段包含：
|
||
|
||
- `userid`
|
||
- `channel_id`
|
||
- `nick`
|
||
- `avatar`
|
||
- `source_query`
|
||
- `source_message_id`
|
||
- `source_message_time`
|
||
- `matched_last_msg`
|
||
- `matched_last_msg_id`
|
||
- `matched_last_msg_time`
|
||
- `raw_contact`
|
||
|
||
---
|
||
|
||
## 二、项目结构
|
||
|
||
```text
|
||
chatbot/
|
||
├── main.py # 回调主流程、关键词逻辑、B同步、PB写库、调试接口
|
||
├── crypto_utils.py # AES加解密、签名
|
||
├── config.py # 应用配置（A/B/PB）
|
||
├── run.py # 启动入口（8001）
|
||
├── requirements.txt # 依赖
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 三、快速启动
|
||
|
||
### 1) 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2) 启动
|
||
|
||
```bash
|
||
python run.py
|
||
```
|
||
|
||
默认端口：
|
||
|
||
- `http://0.0.0.0:8001`
|
||
|
||
---
|
||
|
||
## 四、配置说明（config.py）
|
||
|
||
### 1) 接口 A 配置
|
||
|
||
- `APP_ID`
|
||
- `TOKEN`
|
||
- `ENCODING_AES_KEY`
|
||
|
||
这些值必须与微信对话平台后台一致。
|
||
|
||
### 2) PocketBase 配置
|
||
|
||
- `PB_URL`
|
||
- `PB_ADMIN_EMAIL`
|
||
- `PB_ADMIN_PASSWORD`
|
||
- `PB_COLLECTION`
|
||
|
||
当前策略：
|
||
|
||
- Windows 本地调试默认使用 `PB_DOMAIN_URL`
|
||
- 非 Windows 默认使用 `PB_INTERNAL_URL`
|
||
- 若设置环境变量 `PB_URL`，优先使用环境变量
|
||
|
||
### 3) 接口 B 配置
|
||
|
||
- `PM_SYNC_AUTHTOKEN`
|
||
- `PM_SYNC_DEFAULT_WXBOT_BID`
|
||
|
||
说明：B 是后台同步数据源，不影响 A 主回复链路。
|
||
|
||
---
|
||
|
||
## 五、回调处理流程
|
||
|
||
1. 微信平台回调到 A（`/` 或 `/wechat/thirdapi`）
|
||
2. 服务端读取 body 并解密
|
||
3. 解析为统一字段（`UserId`、`Query`、`Timestamp` 等）
|
||
4. 关键词命中后生成回复内容
|
||
5. 主流程优先返回（保证用户体验）
|
||
6. 后台异步触发 B 接口
|
||
7. 匹配用户并同步到 PocketBase
|
||
|
||
---
|
||
|
||
## 六、接口清单
|
||
|
||
### 1) 业务接口
|
||
|
||
- `POST /`
|
||
- `POST /wechat/thirdapi`
|
||
|
||
### 2) 调试接口
|
||
|
||
- `GET /health`
|
||
- `GET /debug/echo`
|
||
- `POST /debug/sync-test`
|
||
|
||
### 3) 调试页面
|
||
|
||
- `GET /private-message`
|
||
|
||
用于测试 B 查询、Token 分析、用户列表展示。
|
||
|
||
---
|
||
|
||
## 七、PocketBase 集合建议
|
||
|
||
集合名：`wechat_private_users`
|
||
|
||
建议索引：
|
||
|
||
- `userid + channel_id` 组合索引
|
||
- 或 `source_message_id` 唯一索引（若来源稳定唯一）
|
||
|
||
---
|
||
|
||
## 八、常见问题排查
|
||
|
||
### Q1：回调收到了但用户没看到回复
|
||
|
||
- 检查 `APP_ID/TOKEN/ENCODING_AES_KEY` 是否和后台一致
|
||
- 检查回调 URL 是否为当前服务地址
|
||
- 查看日志中是否有解密失败/解析失败
|
||
|
||
### Q2：B 接口正常，PB 失败
|
||
|
||
通常是 PB 地址或认证路径问题：
|
||
|
||
- 已兼容 `/api/admins/auth-with-password`
|
||
- 已兼容 `/api/collections/_superusers/auth-with-password`
|
||
|
||
### Q3：B 或 PB 失败会不会影响用户回复
|
||
|
||
不会。当前设计是：
|
||
|
||
- 关键词回复优先
|
||
- B/PB 为后台任务，失败只记日志
|
||
|
||
---
|
||
|
||
## 九、参考文档
|
||
|
||
- 微信开放文档（发送客服消息）：
|
||
<https://developers.weixin.qq.com/doc/aispeech/confapi/thirdkefu/sendmsg.html>
|
||
|
||
---
|
||
|
||
## 十、后续优化建议
|
||
|
||
- 将关键词规则做成数据库配置化
|
||
- 增加持久化幂等（避免服务重启后重复处理）
|
||
- 增加结构化日志和告警
|
||
- 将敏感配置迁移到环境变量统一管理
|