EchoChat/docs/api/README.md

EchoChat API 接口文档

本目录包含 EchoChat 系统所有接口定义，按端 + 功能模块两级目录组织，便于维护和查阅。 架构设计见 docs/architecture/system-architecture.md 完整设计方案见 docs/plans/2026-02-27-echochat-system-design.md

---

文档导航

前台用户端 (frontend/)

文档	模块	状态	说明
frontend/auth.md	用户认证	✅ Phase 1	注册、登录、Token 刷新、个人信息管理
frontend/contact.md	联系人	📋 Phase 2	好友申请/管理、好友分组
frontend/im.md	即时通讯	📋 Phase 2	会话列表、消息历史、群聊创建与管理
frontend/meeting.md	会议	📋 Phase 3	即时会议、预约会议、加入/离开、会议列表
frontend/notify.md	通知	📋 Phase 2	通知列表、标记已读

后台管理端 (admin/)

文档	模块	状态	说明
admin/auth.md	管理员认证	✅ Phase 1	管理员登录（验证 admin 角色）
admin/user.md	用户管理	✅ Phase 1	用户列表/详情、状态管理、角色分配、创建用户
admin/meeting.md	会议管理	📋 Phase 3	会议列表/详情、强制结束、会议统计
admin/system.md	系统管理	📋 待定	仪表盘数据、操作日志、系统配置

跨端通用

文档	状态	说明
websocket.md	📋 Phase 2	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)

统一响应格式

成功响应：

{
    "code": 0,
    "message": "success",
    "data": { ... },
    "trace_id": "6478824e-2926-4d35-aa5f-047c8cfbb36b",
    "time": "2026-02-27 18:00:00"
}

错误响应：

{
    "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	账号已被禁用	用户状态为禁用

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

分页响应格式：

{
    "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            # 用户认证
│   ├── contact.md         # 联系人管理
│   ├── im.md              # 即时通讯
│   ├── meeting.md         # 会议
│   └── notify.md          # 通知
├── admin/                 # 后台管理端 API
│   ├── auth.md            # 管理员认证
│   ├── user.md            # 用户管理
│   ├── meeting.md         # 会议管理
│   └── system.md          # 系统管理
└── websocket.md           # WebSocket 事件协议