# API 接口文档

> 基地址: `http://localhost:3101`
> 所有响应统一格式: `{ success: boolean, data: any, error: { message, code } | null }`

---

## 接口列表

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 健康检查 |
| GET | `/api/qiwe/status` | QiWe 配置状态查询 |
| POST | `/api/qiwe/webhook` | QiWe 平台 Webhook 回调 |
| POST | `/api/qiwe/sync-groups` | 触发全量群同步 |
| POST | `/api/qiwe/sync-messages` | 触发增量消息同步 |
| POST | `/api/qiwe/sync-contacts` | 触发全量联系人同步 |

---

## 1. 健康检查

```
GET /api/health
```

**响应示例:**
```json
{
  "success": true,
  "data": { "status": "ok", "timestamp": "2026-06-16T10:30:00.000Z" },
  "error": null
}
```

---

## 2. QiWe 配置状态查询

```
GET /api/qiwe/status
```

**响应示例:**
```json
{
  "success": true,
  "data": {
    "configured": true,
    "apiBase": "https://manager.qiweapi.com/qiwe",
    "guid": "B8591A9D...",
    "token": "146708f9...",
    "parseServer": "https://server.sh-lami.com/parse"
  },
  "error": null
}
```

---

## 3. Webhook 回调接收

> 该接口由 QiWe 平台主动调用，需配置到 QiWe 控制台的回调地址。

```
POST /api/qiwe/webhook
Content-Type: application/json
```

**请求体（QiWe 平台发送）:**
```json
{
  "code": 0,
  "data": [
    {
      "guid": "B8591A9D-B540-44F9-9D74-B2EF5B419EAA",
      "userId": "1688857912458394",
      "cmd": 15000,
      "msgType": 0,
      "msgServerId": 123456,
      "msgUniqueIdentifier": "abc123def456",
      "senderId": 1688857912458394,
      "fromRoomId": 12345678901234,
      "senderName": "张三",
      "timestamp": 1718523000,
      "msgData": {
        "content": "你好",
        "atList": []
      }
    }
  ],
  "msg": "成功"
}
```

**响应:** 立即返回 200，数据处理异步进行。

```json
{ "success": true, "data": null, "error": null }
```

### Webhook 事件处理规则

| cmd | msgType | 事件 | 处理 |
|-----|---------|------|------|
| 15000 | 1006 | 群创建 | 创建 GroupChat（含 memberCount/ownerPhone）+ 批量创建 GroupMember |
| 15000 | 1001 | 群改名 | 更新 GroupChat.roomName |
| 15000 | 1002 | 成员加入 | 成员 status→active，更新 memberCount |
| 15000 | 1003 | 成员移除 | 成员 status→left，更新 memberCount |
| 15000 | 1005 | 成员退群 | 退群者 status→left，更新 memberCount |
| 15000 | 1022 | 群主转让 | 更新 GroupChat.ownerId + 角色互换 |
| 15000 | 1023 | 群解散 | GroupChat.status→dismissed |
| 15000 | 1043 | 管理员变动 | 日志 |
| 15000 | 2002 | 删除聊天 | 日志 |
| 15000 | 2055 | 清空聊天 | 日志 |
| 15000 | 0,1,2... | 消息 | 去重 → Message 入库 → 更新群计数器（messageCountTotal/Today/lastActivityAt） |
| 15500 | * | 系统消息 | 入库 WebhookLog |
| 11016 | * | 账号状态 | 入库 WebhookLog |
| 20000 | * | API异步 | 入库 WebhookLog |

---

## 4. 触发全量群同步

```
POST /api/qiwe/sync-groups
```

**响应:** 立即返回，三阶段同步异步执行。

```json
{
  "success": true,
  "data": {
    "status": "syncing",
    "message": "群同步 + 会话发现 + 成员同步已启动"
  },
  "error": null
}
```

**同步流程:**
1. `getRoomList` → 机器人创建的群入库 GroupChat（含 memberCount）
2. `getSessionList` → 会话列表发现补充新群
3. `batchGetRoomDetail` → 补全群名 + ownerId + ownerPhone 回填（通过 _User）+ memberCount 更新
4. 成员批量同步：新成员创建（无昵称等消息补全）/ 已有成员更新昵称和状态
5. `backfillOwnerNames`（随定时任务）→ 对缺少 ownerName 的群批量回填

> 注意：`batchGetRoomDetail` 不返回成员昵称（官方文档明确说明），成员创建时 nickname 可能为空，后续由消息中的 senderName 补全。

---

## 5. 触发增量消息同步

```
POST /api/qiwe/sync-messages?maxPages=10&limit=100
```

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `maxPages` | number | 10 | 最大同步页数 |
| `limit` | number | 100 | 每页消息数 |

**响应:**
```json
{
  "success": true,
  "data": {
    "status": "syncing",
    "message": "增量消息同步已启动 (maxPages=10, limit=100)"
  },
  "error": null
}
```

**同步流程:**
1. 读取 MessageSyncCursor 获取上次游标
2. 从游标位置分页拉取新消息
3. msgUniqueIdentifier 去重 → 入库 Message
4. 提取 senderName → 更新 GroupMember 昵称
5. 发现未知群 → 尝试获取详情并创建
6. 更新群消息计数器（messageCountTotal/Today/lastActivityAt）
7. 更新游标到最新位置

---

## 6. 触发全量联系人同步

```
POST /api/qiwe/sync-contacts
```

**响应:**
```json
{
  "success": true,
  "data": {
    "status": "syncing",
    "message": "联系人全量同步已启动"
  },
  "error": null
}
```

**同步流程:**
1. 分页拉取所有外部联系人 → upsert Contact
2. 分页拉取所有内部联系人 → upsert Contact
3. 逻辑删除恢复: 之前 inactive 的联系人如有新数据自动恢复 active

---

## 统一错误响应格式

```json
{
  "success": false,
  "data": null,
  "error": {
    "message": "请在 .env 中配置 QIWE_TOKEN 和 QIWE_GUID",
    "code": "MISSING_CONFIG"
  }
}
```

错误码说明:
| 错误码 | 说明 |
|--------|------|
| `MISSING_CONFIG` | QiWe 配置不完整 |
| `INVALID_BODY` | 请求体格式错误（webhook 接口） |
| `INTERNAL_ERROR` | 服务器内部错误 |