# XuqmGroup Server 联调接口文档

> 最后更新：2026-04-28

## 线上入口

| 服务 | 地址 | 说明 |
|------|------|------|
| 租户服务 | `https://dev.xuqinmin.com/api/` | 认证、应用、子账号、运营平台 |
| IM HTTP | `https://dev.xuqinmin.com/api/im/` | IM 登录、消息发送、撤回、历史消息 |
| IM WebSocket | `wss://dev.xuqinmin.com/ws/im` | 实时消息 |
| 文件服务 | `https://file.dev.xuqinmin.com/api/file/` | 文件上传、下载、缩略图 |
| App 更新 | `https://dev.xuqinmin.com/api/v1/updates/` | 原生版本管理 |
| RN 热更新 | `https://dev.xuqinmin.com/api/v1/rn/` | Bundle 热更新 |

## 初始化管理员账号

| 字段 | 值 |
|------|----|
| 用户名 | `admin` |
| 初始密码 | `Admin@123456` |
| 登录接口 | `POST /api/auth/ops/login` |

## 统一响应

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

## 常见错误码

| `code` | `status` | 说明 |
|--------|----------|------|
| `200` | `"0"` | 成功 |
| `400` | `"1"` | 参数校验失败或请求不合法 |
| `401` | `"1"` | 未登录、Token 无效或已过期 |
| `403` | `"1"` | 无权限访问 |
| `500` | `"1"` | 服务端内部错误 |

## 鉴权规则

| 场景 | 鉴权方式 |
|------|----------|
| 租户平台接口 | `Authorization: Bearer <tenant_jwt>` |
| 运营平台接口 | `Authorization: Bearer <ops_jwt>` |
| IM HTTP 接口 | `Authorization: Bearer <im_jwt>` |
| IM WebSocket | `?token=<im_jwt>` |
| App 更新检查 | 无需登录 |
| RN 更新检查 | 无需登录 |
| Bundle 下载 | 无需登录 |

## 核心接口清单

### tenant-service

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| GET | `/api/auth/captcha` | 否 | 获取图形验证码 |
| POST | `/api/auth/send-email-code` | 否 | 发送邮箱验证码 |
| POST | `/api/auth/register` | 否 | 注册主账号 |
| POST | `/api/auth/login` | 否 | 租户登录 |
| POST | `/api/auth/forgot-password` | 否 | 发送找回密码邮件 |
| POST | `/api/auth/reset-password` | 否 | 重置密码 |
| GET | `/api/apps` | 是 | 应用列表 |
| GET | `/api/apps/{id}` | 是 | 应用详情 |
| POST | `/api/apps` | 是 | 创建应用 |
| PUT | `/api/apps/{id}` | 是 | 更新应用 |
| DELETE | `/api/apps/{id}` | 是 | 删除应用 |
| GET | `/api/apps/{appId}/services` | 是 | 服务列表 |
| POST | `/api/apps/{appId}/services/toggle` | 是 | 开关服务 |
| POST | `/api/apps/{appId}/services/{id}/regenerate-key` | 是 | 重新生成服务密钥 |
| GET | `/api/sub-accounts` | 是 | 子账号列表 |
| POST | `/api/sub-accounts/send-verify-code` | 是 | 子账号邮箱验证码 |
| POST | `/api/sub-accounts/verify-email` | 是 | 校验子账号邮箱 |
| POST | `/api/sub-accounts` | 是 | 创建子账号 |
| DELETE | `/api/sub-accounts/{id}` | 是 | 禁用子账号 |
| POST | `/api/auth/ops/login` | 否 | 运营管理员登录 |
| GET | `/api/ops/tenants` | 是 | 运营租户列表 |
| POST | `/api/ops/tenants/{id}/toggle-status` | 是 | 租户启停 |
| GET | `/api/ops/statistics` | 是 | 统计面板 |

### im-service

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| POST | `/api/im/auth/login` | 否 | 获取 IM Token；需要 `X-App-Timestamp` / `X-App-Nonce` / `X-App-Signature` |
| POST | `/api/im/messages/send` | 是 | 发送消息（TEXT / IMAGE / AUDIO / VIDEO / FILE / LOCATION / CUSTOM / NOTIFY / RICH_TEXT / CALL_AUDIO / CALL_VIDEO / FORWARD / QUOTE / MERGE） |
| POST | `/api/im/messages/{id}/revoke` | 是 | 撤回消息 |
| GET | `/api/im/messages/history/{toId}` | 是 | 查询历史消息 |
| WS | `/ws/im` | IM Token | 建立实时连接 |

### push-service

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| POST | `/api/push/register` | 是 | 注册设备 token |
| POST | `/api/push/send` | 是 | 发送推送通知 |

### file-service

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| POST | `/api/file/upload` | 是 | 文件上传，按 SHA-256 去重 |
| GET | `/api/file/{hash}` | 否 | 按 hash 获取文件 |
| GET | `/api/file/{hash}/thumbnail` | 否 | 按 hash 获取缩略图 |

### update-service

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|------|------|
| GET | `/api/v1/updates/app/check` | 否 | 检查 App 更新 |
| POST | `/api/v1/updates/app/upload` | 是 | 上传 App 版本 |
| POST | `/api/v1/updates/app/{id}/publish` | 是 | 发布 App 版本 |
| GET | `/api/v1/updates/app/list` | 是 | App 版本列表 |
| GET | `/api/v1/updates/files/apk/{filename}` | 否 | 下载 APK |
| GET | `/api/v1/rn/update/check` | 否 | 检查 RN 热更新 |
| POST | `/api/v1/rn/upload` | 是 | 上传 Bundle |
| POST | `/api/v1/rn/{id}/publish` | 是 | 发布 Bundle |
| GET | `/api/v1/rn/files/{appId}/{platform}/{moduleId}` | 否 | 下载 Bundle |

说明：这里的 `appId` 按 `appKey` 解析。当前 demo 默认使用 `ak_demo_chat`，`tenant-service` 会优先复用数据库里已有的应用；如果没有，会自动补一条默认 demo 应用和基础服务配置。`POST /api/im/auth/login` 还要求 demo-service 通过 AppSecret 生成签名头再转发给 IM 服务。

## curl 示例

### 运营平台登录

```bash
curl -X POST 'https://dev.xuqinmin.com/api/auth/ops/login' \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"Admin@123456"}'
```

### App 更新检查

```bash
curl 'https://dev.xuqinmin.com/api/v1/updates/app/check?appId=ak_demo_chat&platform=ANDROID&currentVersionCode=1'
```

### RN 热更新检查

```bash
curl 'https://dev.xuqinmin.com/api/v1/rn/update/check?appId=ak_demo_chat&platform=ANDROID&moduleId=chat-home&currentVersion=1.0.0'
```

### IM 登录

```bash
curl -X POST 'https://dev.xuqinmin.com/api/im/auth/login?appId=ak_demo_chat&userId=demo_alice'
```

返回示例中的 `data` 会同时包含 `token` 和 `expiresAt`，用于客户端提前做静默续签。

### Demo IM 刷新

```bash
curl -X POST 'https://dev.xuqinmin.com/api/demo/auth/refresh-im?appId=ak_demo_chat' \
  -H 'Authorization: Bearer <demo_jwt>'
```

该接口会基于 demo 登录态重新签发 IM token，并返回新的 `expiresAt`。

### IM 会话与关系链

```bash
curl 'https://dev.xuqinmin.com/api/im/conversations?appId=ak_demo_chat'
curl -X PUT 'https://dev.xuqinmin.com/api/im/conversations/user_002/pinned?appId=ak_demo_chat&chatType=SINGLE&pinned=true'
curl -X PUT 'https://dev.xuqinmin.com/api/im/conversations/user_002/draft?appId=ak_demo_chat&chatType=SINGLE&draft=hello'
curl -X DELETE 'https://dev.xuqinmin.com/api/im/conversations/user_002?appId=ak_demo_chat&chatType=SINGLE'
curl 'https://dev.xuqinmin.com/api/im/groups?appId=ak_demo_chat'
curl 'https://dev.xuqinmin.com/api/im/groups/public?appId=ak_demo_chat&keyword=demo'
curl -X POST 'https://dev.xuqinmin.com/api/im/groups/group_001/join-requests?appId=ak_demo_chat&remark=申请加入'
curl 'https://dev.xuqinmin.com/api/im/groups/group_001/join-requests?appId=ak_demo_chat'
curl -X POST 'https://dev.xuqinmin.com/api/im/groups/group_001/join-requests/req_001/accept?appId=ak_demo_chat'
curl -X POST 'https://dev.xuqinmin.com/api/im/groups/group_001/join-requests/req_001/reject?appId=ak_demo_chat'
curl 'https://dev.xuqinmin.com/api/im/blacklist?appId=ak_demo_chat'
curl 'https://dev.xuqinmin.com/api/im/friend-requests?appId=ak_demo_chat&direction=incoming'
```

### IM 管理后台接口

```bash
curl 'https://dev.xuqinmin.com/api/im/admin/users?appId=ak_demo_chat&page=0&size=20'
curl 'https://dev.xuqinmin.com/api/im/admin/groups?appId=ak_demo_chat'
curl 'https://dev.xuqinmin.com/api/im/admin/messages?appId=ak_demo_chat&userA=user_001&userB=user_002&page=0&size=20'
curl -X POST 'https://dev.xuqinmin.com/api/im/admin/messages/msg_001/revoke?appId=ak_demo_chat'
curl -X DELETE 'https://dev.xuqinmin.com/api/im/admin/groups/group_001'
```

### 好友申请 / 黑名单

```bash
curl -X POST 'https://dev.xuqinmin.com/api/im/friend-requests?appId=ak_demo_chat&toUserId=user_002&remark=hi'
curl -X POST 'https://dev.xuqinmin.com/api/im/friend-requests/req_001/accept?appId=ak_demo_chat'
curl -X POST 'https://dev.xuqinmin.com/api/im/friend-requests/req_001/reject?appId=ak_demo_chat'
curl -X POST 'https://dev.xuqinmin.com/api/im/blacklist?appId=ak_demo_chat&blockedUserId=user_002'
curl -X DELETE 'https://dev.xuqinmin.com/api/im/blacklist?appId=ak_demo_chat&blockedUserId=user_002'
```

### IM 历史过滤查询

```bash
curl 'https://dev.xuqinmin.com/api/im/messages/history/user_002?appId=ak_demo_chat&page=0&size=20&keyword=hello&msgType=TEXT'
curl 'https://dev.xuqinmin.com/api/im/messages/group-history/group_001?appId=ak_demo_chat&page=0&size=20&keyword=user_002&startTime=2026-04-27T00:00:00&endTime=2026-04-27T23:59:59'
```

支持的筛选参数：`keyword`、`msgType`、`startTime`、`endTime`。

### IM 媒体消息

```bash
curl -X POST 'https://file.dev.xuqinmin.com/api/file/upload' \
  -H 'Authorization: Bearer <im_jwt>' \
  -F 'file=@image.jpg'

curl -X POST 'https://im.dev.xuqinmin.com/api/im/messages/send?appId=ak_demo_chat' \
  -H 'Authorization: Bearer <im_jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"toId":"user_002","chatType":"SINGLE","msgType":"IMAGE","content":"{\"url\":\"https://file.dev.xuqinmin.com/api/file/abc\"}"}'
```

当前 `im-service` 的消息发送接口已经支持 `AUDIO`、`LOCATION`、`CUSTOM`、`RICH_TEXT`、`FORWARD`、`QUOTE`、`MERGE`、`CALL_AUDIO`、`CALL_VIDEO` 这些通用类型，客户端只需按协议传入对应 JSON 内容即可。

群聊消息在历史查询和实时推送里会携带 `groupReadCount`，用于展示 `N 人已读`。