XuqmGroup-Server/docs/API_ACCESS.md

# XuqmGroup Server 联调接口文档

> 最后更新：2026-04-24

## 线上入口

| 服务 | 地址 | 说明 |
|------|------|------|
| 租户服务 | `https://dev.xuqinmin.com/api/` | 认证、应用、子账号、运营平台 |
| IM HTTP | `https://dev.xuqinmin.com/api/im/` | IM 登录、消息发送、撤回、历史消息 |
| IM WebSocket | `wss://dev.xuqinmin.com/ws/im` | 实时消息 |
| 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` | 是 | 发送消息 |
| 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` | 是 | 发送推送通知 |

### 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'
```

### 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/blacklist?appId=ak_demo_chat'
curl 'https://dev.xuqinmin.com/api/im/friend-requests?appId=ak_demo_chat&direction=incoming'
```