# 消息服务 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. 错误重试机制