wanglei/EchoChat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4f55ef6de08ca0ea10500408f74718b0cd240cb4
EchoChat/docs/api/README.md
bujinyuan 19979da59e feat(phase2c): 群聊与已读回执功能完整实现 
Phase 2c 全部 14 个 Task 完成，包含：

后端（Go）：
- MinIO 文件存储服务集成（Docker + Go SDK + 通用上传 API）
- Group 模块完整实现（DAO + Service + Controller + Router + Wire）
  - 18 个群管理 REST API + 11 个 WS 群事件推送
  - 群创建/解散/邀请/踢人/退出/转让群主/设管理员/禁言/全体禁言/群公告/群昵称/免打扰/搜索
- IM Service 扩展（群消息发送/撤回 + @提醒 + 管理员无时限撤回）
- 已读回执后端（单聊会话级 last_read_msg_id + 群聊消息级 im_message_reads）
- 管理端群组管理（列表/详情/解散）
- 数据库迁移（3 张新表 + 2 张表字段扩展）

前端（uni-app）：
- 群聊 Store + API 封装 + 11 个 WS 事件监听
- 已读回执 UI（单聊已读/未读标记 + 群聊 X人已读 + 已读详情页）
- 7 个群聊页面（对话/创建/设置/成员/邀请/审批/搜索）
- 会话列表改造（全部/单聊/群聊 Tab + @标记 + 免打扰标识）

管理端（Vue 3 + Element Plus）：
- 群组列表页（搜索/分页/详情弹窗/解散群聊）
- 侧边栏群组管理入口

文档同步：进度/架构/设计/API/规范文档全部更新

Made-with: Cursor
2026-03-04 14:58:23 +08:00

213 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

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.

# EchoChat API 接口文档
> 本目录包含 EchoChat 系统所有接口定义，按**端 + 功能模块**两级目录组织，便于维护和查阅。
> 架构设计见 `docs/architecture/system-architecture.md`
> 完整设计方案见 `docs/plans/2026-02-27-echochat-system-design.md`
---
## 文档导航
### 前台用户端 (`frontend/`)
| 文档 | 模块 | 状态 | 说明 |
|------|------|------|------|
| [frontend/auth.md](frontend/auth.md) | 用户认证 | ✅ Phase 1 | 注册、登录、Token 刷新、个人信息管理 |
| [frontend/contact.md](frontend/contact.md) | 联系人 | ✅ Phase 2a | 17 个 API：好友申请/管理、好友分组、黑名单、搜索/推荐、在线状态 |
| [frontend/websocket.md](frontend/websocket.md) | WebSocket | ✅ Phase 2a | 前端 WebSocket 连接管理、事件协议、心跳、重连 |
| [frontend/im.md](frontend/im.md) | 即时通讯 | ✅ Phase 2b | 7 个 API：会话列表/置顶/删除/清空、历史消息、全局搜索、未读数 |
| [frontend/group.md](frontend/group.md) | 群聊管理 | ✅ Phase 2c | 16 个 API：建群/管理/成员/角色/禁言/公告/搜索/入群审批 |
| [frontend/meeting.md](frontend/meeting.md) | 会议 | 📋 后续 | 即时会议、预约会议、加入/离开、会议列表 |
| [frontend/notify.md](frontend/notify.md) | 通知 | 📋 后续 | 通知列表、标记已读 |
### 后台管理端 (`admin/`)
| 文档 | 模块 | 状态 | 说明 |
|------|------|------|------|
| [admin/auth.md](admin/auth.md) | 管理员认证 | ✅ Phase 1 | 管理员登录（验证 admin 角色） |
| [admin/user.md](admin/user.md) | 用户管理 | ✅ Phase 1 | 用户列表/详情、状态管理、角色分配、创建用户 |
| [admin/online.md](admin/online.md) | 在线监控 | ✅ Phase 2a | 在线用户列表、在线用户计数 |
| [admin/contact.md](admin/contact.md) | 好友关系管理 | ✅ Phase 2a | 好友关系列表（分页）、管理员解除好友关系 |
| [admin/group.md](admin/group.md) | 群聊管理 | ✅ Phase 2c | 群列表/详情、管理员解散群聊 |
| [admin/meeting.md](admin/meeting.md) | 会议管理 | 📋 后续 | 会议列表/详情、强制结束、会议统计 |
| [admin/system.md](admin/system.md) | 系统管理 | 📋 待定 | 仪表盘数据、操作日志、系统配置 |
### 跨端通用
| 文档 | 状态 | 说明 |
|------|------|------|
| [websocket.md](websocket.md) | ✅ Phase 2a/2b | WebSocket 实时事件协议（IM 消息收发/撤回/已读/输入、联系人通知、在线状态、心跳） |
---
## 通用规范
### 基础 URL
| 环境 | 地址 |
|------|------|
| 开发环境 | `http://localhost:8085` |
| 生产环境 | `https://api.echochat.com`（待定） |
### 认证方式
除登录/注册等公开接口外，所有接口均需在请求头中携带 JWT Token：
```
Authorization: Bearer <access_token>
```
### 时间格式规范
系统所有时间字段统一使用 **亚洲友好的日期时间字符串格式**：
```
yyyy-MM-dd HH:mm:ss
```
示例：`"2026-03-01 14:12:12"`
- 所有 API 响应中的时间字段（`created_at`、`updated_at`、`last_login_at`、`started_at` 等）均使用此格式
- 所有 API 请求中的时间参数（如预约会议时间）也使用此格式
- WebSocket 消息中的时间字段同样遵循此格式
- 时区统一采用 **Asia/Shanghai (UTC+8)**
### 统一响应格式
**成功响应：**
```json
{
"code": 0,
"message": "success",
"data": { ... },
"trace_id": "6478824e-2926-4d35-aa5f-047c8cfbb36b",
"time": "2026-02-27 18:00:00"
}
```
**错误响应：**
```json
{
"code": 1001,
"message": "参数错误：邮箱格式不正确",
"trace_id": "66564073-c0b7-4cf6-a200-5df94e1d01f3",
"time": "2026-02-27 18:00:00"
}
```
> **trace_id** 字段在所有响应中都返回，用于追踪同一请求在各层级日志中的关联。
### 错误码定义
#### 通用错误码（1000-1099）
| 错误码 | 含义 | 说明 |
|--------|------|------|
| 0 | 成功 | 请求处理成功 |
| 1001 | 参数错误 | 请求参数缺失或格式不正确 |
| 1002 | 未认证 | Token 缺失、过期或无效 |
| 1003 | 权限不足 | 当前用户角色无权执行此操作 |
| 1004 | 资源不存在 | 请求的目标资源不存在 |
| 1005 | 操作重复 | 如重复注册、重复添加好友等 |
#### 认证模块错误码（2000-2099）
| 错误码 | 含义 | 说明 |
|--------|------|------|
| 2001 | 用户名已存在 | 注册时用户名重复 |
| 2002 | 邮箱已注册 | 注册时邮箱重复 |
| 2003 | 账号或密码错误 | 登录失败 |
| 2004 | 账号已被禁用 | 用户状态为禁用 |
#### 联系人模块错误码（2100-2199）
| 错误码 | 含义 | 说明 |
|--------|------|------|
| 2101 | 不能添加自己 | 好友申请目标为自身 |
| 2102 | 已是好友关系 | 重复发送好友申请 |
| 2103 | 已被对方拉黑 | 被拉黑后无法发送申请 |
| 2104 | 申请不存在 | 待处理申请记录不存在或已处理 |
| 2105 | 好友关系不存在 | 尝试操作不存在的好友关系 |
| 2106 | 分组不存在 | 好友分组 ID 无效 |
#### IM 模块错误码（3000-3099）
| 错误码 | 含义 | 说明 |
|--------|------|------|
| 3001 | 会话不存在 | IM 会话 ID 无效 |
| 3002 | 非会话成员 | 用户不在该会话中 |
| 3003 | 已被禁言 | 用户在该群聊中被禁言 |
#### 会议模块错误码（4000-4099）
| 错误码 | 含义 | 说明 |
|--------|------|------|
| 4001 | 会议不存在 | 会议号无效 |
| 4002 | 会议密码错误 | 加入会议时密码不匹配 |
| 4003 | 会议已满 | 参会人数已达上限 |
| 4004 | 会议已结束 | 尝试加入已结束的会议 |
#### 系统错误码（5000-5099）
| 错误码 | 含义 | 说明 |
|--------|------|------|
| 5001 | 系统内部错误 | 服务端未知错误 |
| 5002 | 服务暂不可用 | 依赖服务不可用（数据库、Redis 等） |
### 分页规范
支持分页的接口统一使用以下查询参数：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| page | int | 1 | 页码，从 1 开始 |
| page_size | int | 20 | 每页数量，最大 100 |
分页响应格式：
```json
{
"code": 0,
"message": "ok",
"data": {
"list": [ ... ],
"total": 150,
"page": 1,
"page_size": 20
}
}
```
---
## 文档维护规则
1. **新增接口时**：在对应端+模块的文档中追加，保持格式一致
2. **接口变更时**：同步更新文档，必要时在接口描述中标注版本信息
3. **新增模块时**：在对应端目录下创建新文档，在本 README 导航表中添加链接
4. **新增端时**：创建新的端目录（如 `open/` 开放 API），在导航中添加新分区
5. **错误码新增时**：在本文档的错误码定义中追加，保持各模块错误码区间不重叠
### 目录结构
```
docs/api/
├── README.md # 通用规范（本文件）
├── frontend/ # 前台用户端 API
│ ├── auth.md # 用户认证 ✅ Phase 1
│ ├── contact.md # 联系人管理（17 个 API） ✅ Phase 2a
│ ├── websocket.md # WebSocket 事件协议 ✅ Phase 2a
│ ├── im.md # 即时通讯（8 个 API） ✅ Phase 2b/2c
│ ├── group.md # 群聊管理（16 个 API） ✅ Phase 2c
│ ├── meeting.md # 会议 📋 后续
│ └── notify.md # 通知 📋 后续
├── admin/ # 后台管理端 API
│ ├── auth.md # 管理员认证 ✅ Phase 1
│ ├── user.md # 用户管理 ✅ Phase 1
│ ├── online.md # 在线监控 ✅ Phase 2a
│ ├── contact.md # 好友关系管理 ✅ Phase 2a
│ ├── group.md # 群聊管理（3 个 API） ✅ Phase 2c
│ ├── meeting.md # 会议管理 📋 后续
│ └── system.md # 系统管理 📋 待定
└── websocket.md # WebSocket 全量事件协议 ✅ Phase 2a/2b/2c
```
Reference in New Issue View Git Blame Copy Permalink