XuqmGroup-Web/docs-site/docs/server/api.md

# Server API 参考

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

- `IM 服务`：账号、消息、群组、好友、会话、黑名单、管理端、回调
- `Push 服务`：设备注册、离线推送、诊断、管理端
- `Update 服务`：应用版本、RN Bundle、应用商店提审、发布配置、操作日志

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

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

---

## 认证

### IM 服务

- `POST /api/im/auth/login` 之前的所有请求，客户端和服务端均需携带 `Authorization: Bearer <im_jwt>`
- `im_jwt` 通过 `POST /api/im/auth/login` 颁发
- 登录请求需要 `X-App-Timestamp`、`X-App-Nonce`、`X-App-Signature`

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

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

---

## IM 服务

### 账号与登录

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/im/auth/login` | IM 登录，返回 JWT Token |
| `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` | 离线推送测试 |

### 内部接口

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

---

## Update 服务

### 应用版本

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/updates/app/check` | 检查应用更新 |
| `POST` | `/api/v1/updates/app/upload` | 上传应用版本 |
| `GET|POST` | `/api/v1/updates/app/inspect` | 检查上传内容 |
| `POST` | `/api/v1/updates/app/{id}/publish` | 发布应用版本 |
| `POST` | `/api/v1/updates/app/{id}/unpublish` | 取消发布 |
| `POST` | `/api/v1/updates/app/{id}/gray` | 灰度发布 |
| `GET` | `/api/v1/updates/app/list` | 版本列表 |

### RN Bundle

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/rn/update/check` | 检查 RN 更新 |
| `POST` | `/api/v1/rn/upload` | 上传 RN Bundle |
| `GET|POST` | `/api/v1/rn/inspect` | 检查 RN 上传内容 |
| `GET` | `/api/v1/rn/list` | RN 列表 |
| `POST` | `/api/v1/rn/{id}/publish` | 发布 RN Bundle |
| `POST` | `/api/v1/rn/{id}/unpublish` | 取消发布 RN Bundle |
| `POST` | `/api/v1/rn/{id}/gray` | RN 灰度 |

### 应用商店提审

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/updates/publish/config` | 获取发布配置 |
| `PUT` | `/api/v1/updates/publish/config` | 更新发布配置 |
| `GET` | `/api/v1/updates/gray/members` | 灰度成员列表 |
| `POST` | `/api/v1/updates/gray/members/sync` | 同步灰度成员 |
| `POST` | `/api/v1/updates/gray/members/import` | 导入灰度成员 |
| `GET` | `/api/v1/updates/store/configs` | 获取应用市场配置 |
| `PUT` | `/api/v1/updates/store/configs/{storeType}` | 更新应用市场配置 |
| `DELETE` | `/api/v1/updates/store/configs/{storeType}` | 删除应用市场配置 |
| `GET` | `/api/v1/updates/store/credentials` | 获取市场凭据摘要 |
| `POST` | `/api/v1/updates/store/app/{versionId}/submit` | 预提交应用市场 |
| `POST` | `/api/v1/updates/store/app/{versionId}/execute-submit` | 执行提审 |
| `POST` | `/api/v1/updates/store/app/{versionId}/review` | 回写审核结果 |

### 运营日志与文件

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/updates/ops/logs` | 更新操作日志 |
| `GET` | `/api/v1/updates/files/apk/{filename}` | APK 文件访问 |
| `GET` | `/api/v1/rn/files/{appKey}/{platform}/{moduleId}` | RN Bundle 文件访问 |
| `POST` | `/api/v1/updates/unified/upload` | 统一发布包上传 |

---

## 数据模型约定

### 应用标识

- 所有业务侧判断应用身份使用 `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 的后台能力可以独立接入，也可以组合使用