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

# Server API 参考

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

所有 API 通过 Nginx 反代，无需区分内部端口。

## 认证

除 `/api/im/auth/login` 外，所有 IM 接口需在请求头携带 JWT Token：

```
Authorization: Bearer <token>
```

Token 由 `/api/im/auth/login` 接口签发。当前 IM 登录不做过期功能，只校验 `userId + UserSig` 是否匹配。

---

## IM 服务（/api/im/）

### 登录 · 获取 Token

```
POST /api/im/auth/login
```

**Query 参数**

| 参数 | 必填 | 说明 |
|------|------|------|
| `appId` | 是 | 应用 ID |
| `userId` | 是 | 用户 ID |

**请求头**

| 头 | 必填 | 说明 |
|----|------|------|
| `X-App-Timestamp` | 是 | 当前时间戳（毫秒） |
| `X-App-Nonce` | 是 | 随机字符串 |
| `X-App-Signature` | 是 | HmacSHA256 签名 |

**签名 Payload**（已简化，不再包含 nickname/avatar）：
```
{appId}\n{userId}\n{timestamp}\n{nonce}
```

**响应**

```json
{ "token": "eyJ..." }
```

> 重复登录会覆盖当前会话；SDK 侧不做生命周期检测或旧登录兼容。

---

### 发送消息

```
POST /api/im/messages/send
Authorization: Bearer <token>
Content-Type: application/json
```

**请求体**

```json
{
  "toId":     "user_002",
  "chatType": "SINGLE",
  "msgType":  "TEXT",
  "content":  "Hello!"
}
```

`chatType`：`SINGLE` | `GROUP`

`msgType`：`TEXT` | `IMAGE` | `VIDEO` | `AUDIO` | `FILE` | `CUSTOM` | `LOCATION` | `NOTIFY` | `RICH_TEXT` | `CALL_AUDIO` | `CALL_VIDEO` | `FORWARD`

**响应**：`ImMessage` 对象

---

### 撤回消息

```
PUT /api/im/messages/{messageId}/revoke
Authorization: Bearer <token>
```

**响应**：更新后的 `ImMessage`（`status: "REVOKED"`，`msgType: "REVOKED"`）

---

### 消息历史（单聊）

```
GET /api/im/messages/history?appId=&userId=&toId=&page=0&size=50
Authorization: Bearer <token>
```

**响应**：分页 `ImMessage` 列表

---

### 创建群组

```
POST /api/im/groups
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
  "appId":     "ak_demo_chat",
  "name":      "开发群",
  "memberIds": ["user_001", "user_002"]
}
```

**响应**：`ImGroup` 对象

---

### 获取群列表

```
GET /api/im/groups?appId=ak_demo_chat
Authorization: Bearer <token>
```

---

### 添加群成员

```
POST /api/im/groups/{groupId}/members
Authorization: Bearer <token>
Content-Type: application/json

{ "userId": "user_003" }
```

---

### 移除群成员

```
DELETE /api/im/groups/{groupId}/members/{targetUserId}
Authorization: Bearer <token>
```

---

### 会话扩展

```
PUT /api/im/conversations/{targetId}/hidden?appId=&chatType=SINGLE&hidden=true
PUT /api/im/conversations/{targetId}/group?appId=&chatType=SINGLE&groupName=重要客户
GET /api/im/conversation-groups?appId=
GET /api/im/conversation-groups/{groupName}?appId=
```

### 好友扩展

```
DELETE /api/im/friends?appId=
PUT /api/im/friends/{friendId}/group?appId=&groupName=同事
GET /api/im/friends/groups?appId=
GET /api/im/friends/groups/{groupName}?appId=
```

### 黑名单校验

```
GET /api/im/blacklist/check?appId=&targetUserId=user_002
```

### 群扩展

```
POST /api/im/groups/{groupId}/owner
PUT /api/im/groups/{groupId}/attributes
POST /api/im/groups/{groupId}/attributes/delete
```

管理端补充：

```
POST /api/im/admin/groups/{groupId}/owner?appId=
PUT /api/im/admin/groups/{groupId}/attributes?appId=
POST /api/im/admin/groups/{groupId}/attributes/delete?appId=
POST /api/im/admin/groups/{groupId}/read-receipts?appId=
```

---

## 数据模型

### ImMessage

```json
{
  "id":               "uuid",
  "appId":            "ak_demo_chat",
  "fromUserId":       "user_001",
  "toId":             "user_002",
  "chatType":         "SINGLE",
  "msgType":          "TEXT",
  "content":          "Hello!",
  "status":           "SENT",
  "mentionedUserIds": [],
  "createdAt":        "2026-04-24T10:00:00"
}
```

### ImGroup

```json
{
  "id":        "group_uuid",
  "appId":     "ak_demo_chat",
  "name":      "开发群",
  "creatorId": "user_001",
  "memberIds": ["user_001", "user_002"],
  "adminIds":  ["user_001"],
  "extAttributes": "{\"department\":\"sales\"}",
  "createdAt": "2026-04-24T10:00:00"
}
```

---

## 错误码

| HTTP 状态 | code | 说明 |
|-----------|------|------|
| 400 | 400 | 请求参数错误 |
| 401 | 401 | Token 无效或签名验证失败 |
| 403 | 403 | 无权限操作（如撤回他人消息）|
| 404 | 404 | 资源不存在 |
| 500 | 500 | 服务器内部错误 |

错误响应格式：

```json
{ "code": 403, "message": "只能撤回自己发送的消息" }
```