添加用户消息记录接口;
This commit is contained in:
karlcarlo
170
backend/API_USAGE.md
Normal file
170
backend/API_USAGE.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 消息服务 API 使用文档
|
||||
|
||||
基于 `backend/scripts/load_chat_data.py` 实现的消息服务 API，提供加载会话存档、解密、保存到数据库的整合功能。
|
||||
|
||||
## 新增 API 接口
|
||||
|
||||
### 1. 加载会话存档到数据库
|
||||
**接口**: `POST /api/messages/load`
|
||||
|
||||
**功能**: 完整流程：拉取 → 解密 → 保存
|
||||
- 从企业微信拉取会话存档
|
||||
- 自动解密所有加密消息
|
||||
- 自动保存到数据库（去重处理）
|
||||
|
||||
**参数**:
|
||||
- `seq`: 起始seq值，首次使用0（默认: 0）
|
||||
- `limit`: 拉取数量限制，最大1000（默认: 100）
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
# 首次加载，从seq=0开始，拉取100条消息
|
||||
curl -X POST "http://localhost:8000/api/messages/load?seq=0&limit=100"
|
||||
|
||||
# 继续加载，使用上次返回的max_seq
|
||||
curl -X POST "http://localhost:8000/api/messages/load?seq=12345&limit=500"
|
||||
```
|
||||
|
||||
**响应示例** (成功):
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "消息加载完成",
|
||||
"data": {
|
||||
"total_fetched": 150,
|
||||
"encrypted_count": 120,
|
||||
"decrypted_success": 115,
|
||||
"decrypted_failed": 5,
|
||||
"saved_count": 145,
|
||||
"duplicates_skipped": 5,
|
||||
"failed_to_save": 0,
|
||||
"max_seq": 12345,
|
||||
"next_seq": 12346
|
||||
},
|
||||
"execution_time": "0:00:02.345678",
|
||||
"timestamp": "2025-12-10T16:44:22.123456"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例** (没有新消息):
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "没有新的聊天记录",
|
||||
"data": {
|
||||
"total_fetched": 0,
|
||||
"encrypted_count": 0,
|
||||
"decrypted_success": 0,
|
||||
"decrypted_failed": 0,
|
||||
"saved_count": 0,
|
||||
"duplicates_skipped": 0,
|
||||
"max_seq": 0,
|
||||
"next_seq": 0
|
||||
},
|
||||
"execution_time": "0:00:00.123456"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 查询消息列表
|
||||
**接口**: `GET /api/messages/`
|
||||
|
||||
**功能**: 查询已保存的消息列表，支持分页和过滤
|
||||
|
||||
**参数**:
|
||||
- `page`: 页码（默认: 1）
|
||||
- `page_size`: 每页数量（默认: 20，最大: 100）
|
||||
- `msgtype`: 消息类型过滤（可选）
|
||||
- `roomid`: 群聊ID过滤（可选）
|
||||
- `from_user`: 发送者过滤（可选）
|
||||
|
||||
### 3. 获取消息统计
|
||||
**接口**: `GET /api/messages/stats`
|
||||
|
||||
**功能**: 获取数据库中消息的统计信息
|
||||
|
||||
### 4. 获取单个消息详情
|
||||
**接口**: `GET /api/messages/{msgid}`
|
||||
|
||||
**功能**: 根据消息ID获取单个消息详情
|
||||
|
||||
## 环境变量配置
|
||||
|
||||
新增的环境变量（在 `.env` 文件中）:
|
||||
|
||||
```bash
|
||||
# 消息服务配置
|
||||
WEWORK_PROXY= # 代理地址，如: http://proxy.example.com:8080
|
||||
WEWORK_PROXY_PASSWD= # 代理密码
|
||||
WEWORK_TIMEOUT=10 # 超时时间（秒）
|
||||
```
|
||||
|
||||
## 技术实现
|
||||
|
||||
### 服务架构
|
||||
1. **MessageService**: 核心服务类，整合了以下功能：
|
||||
- 从企业微信拉取会话数据
|
||||
- RSA 解密加密消息
|
||||
- 批量保存到 MongoDB 数据库
|
||||
- 去重处理（基于 msgid）
|
||||
|
||||
2. **消息处理流程**:
|
||||
```
|
||||
拉取数据 → 检查加密 → RSA解密 → 解析JSON → 去重检查 → 批量保存
|
||||
```
|
||||
|
||||
### 重用现有代码
|
||||
- 重用 `load_chat_data.py` 中的解密逻辑
|
||||
- 重用现有的 `Message` 数据模型
|
||||
- 重用企业微信 SDK 配置
|
||||
|
||||
### 错误处理
|
||||
- 完善的异常捕获和日志记录
|
||||
- 友好的错误响应格式
|
||||
- 执行时间统计
|
||||
|
||||
## 使用建议
|
||||
|
||||
### 1. 首次使用
|
||||
```bash
|
||||
# 从seq=0开始加载
|
||||
curl -X POST "http://localhost:8000/api/messages/load?seq=0&limit=1000"
|
||||
```
|
||||
|
||||
### 2. 增量加载
|
||||
使用上次响应中的 `max_seq` 或 `next_seq` 作为下一次的 `seq` 参数：
|
||||
```bash
|
||||
# 假设上次返回的 max_seq=12345
|
||||
curl -X POST "http://localhost:8000/api/messages/load?seq=12345&limit=1000"
|
||||
```
|
||||
|
||||
### 3. 监控进度
|
||||
通过响应中的统计信息监控加载进度：
|
||||
- `total_fetched`: 总共拉取的消息数
|
||||
- `saved_count`: 成功保存到数据库的消息数
|
||||
- `duplicates_skipped`: 跳过的重复消息数
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **私钥文件**: 确保 `cert/1_rsa.key` 文件存在，用于 RSA 解密
|
||||
2. **数据库连接**: 确保 MongoDB 服务正常运行
|
||||
3. **网络代理**: 如果需要代理，在 `.env` 中配置 `WEWORK_PROXY`
|
||||
4. **性能考虑**: 大量数据加载时建议分批进行（limit=100-500）
|
||||
|
||||
## 与原有脚本对比
|
||||
|
||||
| 功能 | 原有脚本 (`load_chat_data.py`) | 新API (`/api/messages/load`) |
|
||||
|------|--------------------------------|-------------------------------|
|
||||
| 执行方式 | 命令行 | HTTP API |
|
||||
| 参数传递 | 命令行参数 | URL 查询参数 |
|
||||
| 结果输出 | 控制台 + JSON 文件 | JSON 响应 |
|
||||
| 集成性 | 独立脚本 | 集成到 FastAPI 应用 |
|
||||
| 自动化 | 需要脚本调度 | 可直接通过 HTTP 调用 |
|
||||
|
||||
## 扩展性
|
||||
|
||||
当前实现为最小可行产品（MVP），可扩展的功能包括：
|
||||
1. 后台异步任务处理
|
||||
2. 更丰富的查询过滤条件
|
||||
3. 消息导出功能
|
||||
4. 实时进度通知
|
||||
5. 错误重试机制
|
||||
Reference in New Issue
Block a user