# Server API 参考

XuqmGroup 的服务端能力分成两类：

- `IM 服务`：账号、消息、群组、好友、会话、黑名单、管理端、回调
- `Push 服务`：设备注册、离线推送、诊断、管理端

**Base URL**：`https://dev.xuqinmin.com`

所有接口都通过 Nginx 反代，无需关心内部端口。

---

## 认证

### IM 服务

- `POST /api/im/auth/login` 返回 `im_jwt`
- 客户端登录使用 `userId + userSig`
- `userSig` 由服务端或 IM 管理页生成，服务端 SDK 可本地生成和校验
- `GET /api/im/platform-events/token` 由 IM 服务返回平台事件账号 `platform` 的登录 token，用于租户平台实时刷新
- 服务端管理类调用使用具备管理员权限的 IM 账号登录后获得的 `im_jwt`
- 服务端如果不想先走 SDK，也可以直接调用 `/api/im/admin/users/{userId}/usersig` 生成 `userSig`，再用 `/api/im/auth/login?userSig=...` 换取 `im_jwt`
- 只有被标记为管理员的 IM 注册账号，才允许用于服务端 SDK / 管理端 REST API
- IM 管理页里的 `UserSig` 生成 / 校验工具也只对管理员账号开放

### Push / Update / Tenant 相关服务

- 业务侧调用通常使用 `appKey`
- 管理端接口需要租户或运营平台的 JWT
- 内部接口统一使用 `X-Internal-Token`

---

## IM 服务

### 账号与登录

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/im/auth/login` | IM 登录，返回 JWT Token；支持 `userSig` |
| `POST` | `/api/im/admin/users/{userId}/usersig` | 生成 UserSig |
| `POST` | `/api/im/admin/users/{userId}/usersig/verify` | 校验 UserSig |
| `GET` | `/api/im/accounts/{userId}` | 获取账号资料 |
| `PUT` | `/api/im/accounts/{userId}` | 更新账号资料 |
| `GET` | `/api/im/accounts/search` | 搜索账号 |
| `POST` | `/api/im/accounts/import` | 导入单个账号 |
| `POST` | `/api/im/accounts/import/batch` | 批量导入账号 |
| `DELETE` | `/api/im/accounts/{userId}` | 删除账号 |
| `GET` | `/api/im/accounts/{userId}/exists` | 检查账号是否存在 |

### 消息

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/im/messages/send` | 发送消息 |
| `POST` | `/api/im/messages/{id}/revoke` | 撤回消息 |
| `PUT` | `/api/im/messages/{id}` | 编辑消息 |
| `GET` | `/api/im/messages/history/{toId}` | 单聊历史 |
| `GET` | `/api/im/messages/group-history/{groupId}` | 群聊历史 |
| `GET` | `/api/im/messages/search` | 按关键字搜索消息 |
| `GET` | `/api/im/messages/offline/count` | 离线消息数 |
| `POST` | `/api/im/messages/offline` | 同步离线消息 |

### 会话

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/im/conversations` | 会话列表 |
| `PUT` | `/api/im/conversations/{targetId}/pinned` | 置顶会话 |
| `PUT` | `/api/im/conversations/{targetId}/muted` | 免打扰 |
| `PUT` | `/api/im/conversations/{targetId}/read` | 标记已读 |
| `PUT` | `/api/im/conversations/{targetId}/draft` | 设置草稿 |
| `PUT` | `/api/im/conversations/{targetId}/hidden` | 隐藏会话 |
| `PUT` | `/api/im/conversations/{targetId}/group` | 设置会话分组 |
| `GET` | `/api/im/conversation-groups` | 会话分组列表 |
| `GET` | `/api/im/conversation-groups/{groupName}` | 指定分组内容 |
| `DELETE` | `/api/im/conversations/{targetId}` | 删除会话 |

### 好友与黑名单

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/im/friends` | 好友列表 |
| `POST` | `/api/im/friends` | 添加好友 |
| `POST` | `/api/im/friends/batch` | 批量添加好友 |
| `DELETE` | `/api/im/friends/{friendId}` | 删除好友 |
| `DELETE` | `/api/im/friends` | 删除全部好友 |
| `POST` | `/api/im/friends/batch/remove` | 批量删除好友 |
| `PUT` | `/api/im/friends/{friendId}/group` | 设置好友分组 |
| `GET` | `/api/im/friends/groups` | 好友分组列表 |
| `GET` | `/api/im/friends/groups/{groupName}` | 指定分组好友 |
| `POST` | `/api/im/friends/check` | 校验好友关系 |
| `GET` | `/api/im/blacklist` | 黑名单列表 |
| `POST` | `/api/im/blacklist` | 添加黑名单 |
| `DELETE` | `/api/im/blacklist` | 删除黑名单 |
| `GET` | `/api/im/blacklist/check` | 校验黑名单关系 |

### 群组

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/im/groups` | 群列表 |
| `POST` | `/api/im/groups` | 创建群组 |
| `GET` | `/api/im/groups/public` | 公开群列表 |
| `GET` | `/api/im/groups/search` | 搜索群 |
| `GET` | `/api/im/groups/{groupId}` | 群详情 |
| `GET` | `/api/im/groups/{groupId}/members` | 群成员 |
| `GET` | `/api/im/groups/{groupId}/members/search` | 搜索群成员 |
| `PUT` | `/api/im/groups/{groupId}` | 更新群信息 |
| `POST` | `/api/im/groups/{groupId}/members` | 添加群成员 |
| `POST` | `/api/im/groups/{groupId}/members/batch` | 批量添加群成员 |
| `DELETE` | `/api/im/groups/{groupId}/members/{targetUserId}` | 删除群成员 |
| `POST` | `/api/im/groups/{groupId}/members/batch/remove` | 批量删除群成员 |
| `POST` | `/api/im/groups/{groupId}/roles` | 设置群角色 |
| `POST` | `/api/im/groups/{groupId}/owner` | 转让群主 |
| `PUT` | `/api/im/groups/{groupId}/attributes` | 更新群属性 |
| `POST` | `/api/im/groups/{groupId}/attributes/delete` | 删除群属性 |
| `POST` | `/api/im/groups/{groupId}/mute` | 群成员禁言 |
| `DELETE` | `/api/im/groups/{groupId}` | 解散群 |
| `POST` | `/api/im/groups/{groupId}/join-requests` | 发送加群申请 |
| `GET` | `/api/im/groups/{groupId}/join-requests` | 查询加群申请 |
| `POST` | `/api/im/groups/{groupId}/join-requests/{requestId}/accept` | 接受加群申请 |
| `POST` | `/api/im/groups/{groupId}/join-requests/{requestId}/reject` | 拒绝加群申请 |
| `POST` | `/api/im/groups/{groupId}/join-requests/batch/accept` | 批量接受加群申请 |
| `POST` | `/api/im/groups/{groupId}/join-requests/batch/reject` | 批量拒绝加群申请 |

### 管理端

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/im/admin/users/state` | 查询用户在线状态 |
| `POST` | `/api/im/admin/users/kick` | 踢下线用户 |
| `POST` | `/api/im/admin/messages/batch-send` | 批量发消息 |
| `POST` | `/api/im/admin/messages/read` | 管理端标记已读 |
| `POST` | `/api/im/admin/messages/import` | 导入消息 |
| `GET` | `/api/im/admin/groups/{groupId}/owner` | 查询群主 |
| `PUT` | `/api/im/admin/groups/{groupId}/owner` | 管理端转让群主 |
| `PUT` | `/api/im/admin/groups/{groupId}/attributes` | 管理端更新群属性 |
| `POST` | `/api/im/admin/groups/{groupId}/attributes/delete` | 管理端删除群属性 |
| `GET` | `/api/im/admin/groups/{groupId}/read-receipts` | 群已读统计 |
| `GET` | `/api/im/admin/webhooks` | Webhook 列表 |
| `POST` | `/api/im/admin/webhooks` | 创建 Webhook |
| `PUT` | `/api/im/admin/webhooks/{id}` | 更新 Webhook |
| `DELETE` | `/api/im/admin/webhooks/{id}` | 删除 Webhook |
| `GET` | `/api/im/admin/webhook-deliveries` | Webhook 投递记录 |
| `GET` | `/api/im/admin/webhook-alerts` | Webhook 告警 |
| `POST` | `/api/im/admin/webhook-alerts/{id}/acknowledge` | 告警确认 |
| `GET` | `/api/im/admin/webhooks/{id}/health` | Webhook 健康状态 |
| `GET` | `/api/im/admin/keyword-filters` | 敏感词列表 |
| `POST` | `/api/im/admin/keyword-filters` | 新增敏感词 |
| `PUT` | `/api/im/admin/keyword-filters/{id}` | 更新敏感词 |
| `DELETE` | `/api/im/admin/keyword-filters/{id}` | 删除敏感词 |
| `GET` | `/api/im/admin/global-mute` | 全局禁言状态 |
| `PUT` | `/api/im/admin/global-mute` | 更新全局禁言 |
| `GET` | `/api/im/admin/operation-logs` | IM 操作日志 |

### 内部接口

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/im/internal/presence/resolve-token` | 解析 IM Token |
| `GET` | `/api/im/internal/presence/users/{userId}` | 查询用户在线状态 |

---

## Push 服务

### 公开接口

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/push/register` | 设备注册推送 token |
| `DELETE` | `/api/push/unregister` | 设备取消注册 |
| `POST` | `/api/push/send` | 发送推送 |
| `POST` | `/api/push/receive-push` | 推送回执/接收 |

### 管理端

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/push/admin/user-status` | 查询用户推送状态 |
| `GET` | `/api/push/admin/device-logs` | 设备日志 |
| `POST` | `/api/push/admin/test-offline` | 离线推送测试 |

> Push 服务不使用 UserSig；公开接口面向业务服务，管理端接口继续使用平台登录态或服务端管理态。
> Push SDK 与 REST API 的公开调用面向业务系统，管理员诊断能力通过平台 JWT 或服务端管理态访问。

### 内部接口

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/push/internal/notify` | 内部通知转发 |
| `GET` | `/api/push/internal/diagnostics/search` | 按 token 查询诊断 |
| `GET` | `/api/push/internal/device-logs` | 内部设备日志 |
| `POST` | `/api/push/internal/test-offline` | 内部离线测试 |

---

## 数据模型约定

### 应用标识

- 所有业务侧判断应用身份使用 `appKey`
- `appId` 仅保留在第三方厂商账号字段里，不作为应用身份

### 常见响应

```json
{
  "code": 200,
  "status": "0",
  "data": { },
  "message": "success"
}
```

### 错误码

| HTTP 状态 | code | 含义 |
|-----------|------|------|
| `400` | `400` | 参数错误 |
| `401` | `401` | 鉴权失败 |
| `403` | `403` | 无权限 |
| `404` | `404` | 资源不存在 |
| `500` | `500` | 服务端内部错误 |

---

## 集成建议

- 服务端业务代码统一使用 Java / Go / Python Server SDK 调用上述 REST 接口
- 客户端统一使用 `appKey` 作为应用上下文
- 实时刷新场景建议使用 IM SDK 订阅服务端事件
- Push、IM 的后台能力可以独立接入，也可以组合使用