This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

接口文档（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）

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

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

通用约定

目录

1. 鉴权（Auth）

1.1 注册

1.2 登录（返回 Token）

1.3 刷新 Token

2. 用户（User）

2.1 获取当前用户信息

2.2 修改用户资料

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

3. 好友（Friend）

3.1 发送好友申请

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

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

3.4 获取好友列表

3.5 删除好友 / 拉黑

4. 会话（Conversation）

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

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

5. 消息（Message）

5.1 发送消息（HTTP 版备用）

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

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

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

5.5 撤回消息

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

6. 文件/上传（File）

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

6.2 下载文件

7. 群组（Group）

7.1 创建群

7.2 获取群信息

7.3 邀请入群

7.4 加群申请（用户申请）

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

8. 通知（Notification）

8.1 获取通知列表

8.2 标记通知为已读

9. 管理后台（Admin）

9.1 管理员登录（同 auth）

9.2 查询用户列表

9.3 禁用/启用用户

9.4 查询操作日志