# 接口文档（REST API） — 聊天系统

> 统一响应格式（JSON）

```
{
  "code": 0,
  "message": "请求成功",
  "data": {}
}
```

- `code`：参照响应 Code 规范（0 成功，非 0 为错误）。
- `message`：提示文本。
- `data`：返回主体。

------

## 通用约定

- 所有需要登录的接口必须在 Header 中带 `Authorization: Bearer <token>`。
- 时间戳统一使用 Unix 秒。
- 分页统一采用 `page`（第几页，从1开始）与 `limit`（每页大小）或基于时间/消息ID的 `afterMessageId` / `beforeTimestamp`。
- 幂等性：对于可能重试的写操作，请求体中带 `requestId`。
- Content-Type: `application/json`（文件上传除外）。
- 返回错误码请参考前面的响应 Code 文档。

------

## 目录

1. 鉴权（Auth）
2. 用户（User）
3. 好友（Friend）
4. 会话（Conversation）
5. 消息（Message）
6. 文件/上传（File）
7. 群组（Group）
8. 通知（Notification）
9. 管理后台（Admin）
10. 常见错误与限流

------

## 1. 鉴权（Auth）

### 1.1 注册

- URL: `POST /api/v1/auth/register`
- 请求：

```
{
  "username": "alice",
  "password": "password123",
  "phone": "13800000000",
  "email":"admin@admin.com",
  "nickname":"测试用户",
  "avatar": "https://cdn.example.com/avatar/1001.png",
}
```

- 成功响应：

```
{
  "code": 0,
  "message": "注册成功",
  "data": { "userId": 1001 }
}
```

### 1.2 登录（返回 Token）

- URL: `POST /api/v1/auth/login`
- 请求：

```
{
  "username": "alice",
  "password": "password123",
  "deviceId": "uuid-device-001"
}
```

- 成功响应：

```
{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "eyJ....",
    "expires_in": 3600,
    "refreshToken": "rft-xxxx"
  }
}
```

### 1.3 刷新 Token

- URL: `POST /api/v1/auth/refresh`
- 请求：

```
{ "refreshToken": "rft-xxxx", "deviceId": "uuid-device-001" }
```

- 响应同登录（返回新 token）。

------

## 2. 用户（User）

### 2.1 获取当前用户信息

- URL: `GET /api/v1/user/me`
- Header: `Authorization: Bearer <token>`
- 响应 data 示例：

```
{
  "id": 1001,
  "username": "alice",
  "nickname": "Alice",
  "avatar": "https://cdn.example.com/avatar/1001.png",
  "status": 1
}
```

### 2.2 修改用户资料

- URL: `PUT /api/v1/user/profile`
- 请求：

```
{
  "nickname": "小艾",
  "olinestatus": "0",
  "avatar": "https://..."
}
```

### 2.3 根据 id 查询用户（用于搜索/加好友）

- URL: `GET /api/v1/user/{userId}`
- 响应含基本公开信息（不含敏感字段）。

------

## 3. 好友（Friend）

### 3.1 发送好友申请

- URL: `POST /api/v1/friend/request`
- 请求：

```
{
  "toUserId": 1002,
  "Description": "我们在项目中认识，申请加好友",
  "requestId": "uuid-req-001"  // 幂等字段
}
```

- 成功返回 `requestId` 或新记录 id。

### 3.2 列出好友申请（收/发）

- URL: `GET /api/v1/friend/requests?type=received|sent&page=1&limit=20`

### 3.3 处理好友申请（同意/拒绝）

- URL: `POST /api/v1/friend/request/{requestId}/handle`
- 请求：

```
{ "action": "accept" } // accept | reject
```

### 3.4 获取好友列表

- URL: `GET /api/v1/friend/list?page=1&limit=50`
- 返回：好友数组（id, nickname, avatar, remark）

### 3.5 删除好友 / 拉黑

- URL: `DELETE /api/v1/friend/{friendId}`
- URL: `POST /api/v1/friend/{friendId}/block` 

------

## 4. 会话（Conversation）

### 4.1 获取会话列表（聊天列表）

- URL: `GET /api/v1/conversations?page=1&limit=50`
- 返回每条会话示例：

```
{
  "targetId": 1002,
  "chatType": "single",
  "lastMessage": { "messageId": 50001, "contentType":"text", "content":"你好", "timestamp": 1700000000 },
  "unreadCount": 3,
  "updatedAt": 1700000000
}
```

### 4.2 删除会话（清空会话/历史）

- URL: `DELETE /api/v1/conversation/{chatType}/{targetId}`
- 注：chatType 为 `single` 或 `group`。删除会影响客户端显示/未读计数，历史消息视策略保留或软删除。

------

## 5. 消息（Message）

> 说明：即时消息优先通过 WebSocket 发送/接收；REST 接口用于历史消息读取、离线发送（备用）、ACK、撤回等。

### 5.1 发送消息（HTTP 版备用）

- URL: `POST /api/v1/message/send`
- 请求：

```
{
  "requestId": "uuid-msg-001",
  "from": 1001,
  "to": 1002,
  "chatType": "single",
  "contentType": "text",
  "content": "你好",
  "timestamp": 1700000000
}
```

- 响应：

```
{ "code": 0, "data": { "messageId": 50001, "status": "sent" } }
```

- 注意：若用户在线，后端可同时通过 WebSocket 推送到接收端。

### 5.2 拉取历史消息（分页或基于消息ID）

- URL: `GET /api/v1/messages/history?chatType=single&targetId=1002&beforeMessageId=50000&limit=50`
- 返回消息数组（按时间倒序或正序，双方约定）。

### 5.3 同步未读/离线消息（登录/重连时）

- URL: `GET /api/v1/messages/sync?since=1700000000` 或 `afterMessageId=xxxxx`
- 返回：所有未读/未同步消息（或给定时间段内消息）。

### 5.4 消息已读/送达回执（HTTP）

- URL: `POST /api/v1/message/ack`
- 请求：

```
{
  "messageId": 50001,
  "status": "read", // delivered | read
  "chatType": "single",
  "from": 1002, // ack 发送者（接收方）
  "to": 1001
}
```

### 5.5 撤回消息

- URL: `POST /api/v1/message/{messageId}/recall`
- 请求：

```
{ "requestId": "uuid-recall-001" }
```

- 响应成功后，服务器会向相关在线端推送 `MESSAGE_RECALL` 事件，更新 message.status。

### 5.6 删除单条消息（客户端侧删除/服务端删除）

- URL: `DELETE /api/v1/message/{messageId}`
- 注意区分“仅自己删除”与“全局删除（撤回）”。

------

## 6. 文件/上传（File）

### 6.1 上传文件（图片/语音/文档）

- URL: `POST /api/v1/file/upload`
- Content-Type: `multipart/form-data`
- 字段：`file`，可选 `type`、`attachedMessageRequestId`
- 成功响应：

```
{
  "code": 0,
  "data": {
    "fileId": 9001,
    "fileUrl": "https://oss.example.com/xxx.jpg",
    "fileName": "xxx.jpg",
    "fileSize": 12345
  }
}
```

- 建议：文件先上传到对象存储（OSS/S3/MinIO），返回 URL，消息发送时引用该 URL（message.content）。

### 6.2 下载文件

- 直接访问 `fileUrl` 或通过后端代理下载（带鉴权）。

------

## 7. 群组（Group）

### 7.1 创建群

- URL: `POST /api/v1/group/create`
- 请求：

```
{
  "name": "项目群",
  "ownerId": 1001,
  "memberIds": [1002,1003],
  "maxMembers": 500,
  "needApproval": true // 加群是否需要审批
}
```

- 响应返回 `groupId`。

### 7.2 获取群信息

- URL: `GET /api/v1/group/{groupId}`

### 7.3 邀请入群

- URL: `POST /api/v1/group/{groupId}/invite`
- 请求：

```
{ "inviter":1001, "invitees":[1004,1005], "message":"来加入我们吧" }
```

- 若群需要审批，发送 `group_join_request`；否则直接加入并更新 group_member。

### 7.4 加群申请（用户申请）

- URL: `POST /api/v1/group/{groupId}/join-request`
- 管理员/群主处理：`POST /api/v1/group/join-request/{requestId}/handle`

### 7.5 群成员管理（踢人/设管理员/退出群）

- 踢人：`POST /api/v1/group/{groupId}/kick`
- 退出：`POST /api/v1/group/{groupId}/leave`
- 设管理员：`POST /api/v1/group/{groupId}/role`

------

## 8. 通知（Notification）

### 8.1 获取通知列表

- URL: `GET /api/v1/notifications?page=1&limit=50`
- 类型包含：好友请求、群邀请、系统公告等。

### 8.2 标记通知为已读

- URL: `POST /api/v1/notification/{notificationId}/read`

------

## 9. 管理后台（Admin）

> 仅管理员或具备权限的账号访问（需在 token 中包含角色或额外权限校验）

### 9.1 管理员登录（同 auth）

- URL: `POST /api/v1/admin/login`

### 9.2 查询用户列表

- URL: `GET /api/v1/admin/users?page=1&limit=50&keyword=alice`

### 9.3 禁用/启用用户

- URL: `POST /api/v1/admin/user/{userId}/ban`
- 请求：

```
{ "action": "ban", "reason": "违规传播" } // action: ban | unban
```

### 9.4 查询操作日志

- URL: `GET /api/v1/admin/logs?page=1&limit=50`