qiwe-common/docs/API接口文档.md

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

响应示例:

{
  "success": true,
  "data": { "status": "ok", "timestamp": "2026-06-16T10:30:00.000Z" },
  "error": null
}

---

2. QiWe 配置状态查询

GET /api/qiwe/status

响应示例:

{
  "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 平台发送）:

{
  "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，数据处理异步进行。

{ "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

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

{
  "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	每页消息数

响应:

{
  "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

响应:

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

同步流程:

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

---

统一错误响应格式

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

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