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

---

二、项目结构

chatbot/
├── main.py            # 回调主流程、关键词逻辑、B同步、PB写库、调试接口
├── crypto_utils.py    # AES加解密、签名
├── config.py          # 应用配置（A/B/PB）
├── run.py             # 启动入口（8001）
├── requirements.txt   # 依赖
└── README.md

---

三、快速启动

1) 安装依赖

pip install -r requirements.txt

2) 启动

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

---

十、后续优化建议

• 将关键词规则做成数据库配置化
• 增加持久化幂等（避免服务重启后重复处理）
• 增加结构化日志和告警
• 将敏感配置迁移到环境变量统一管理