EchoChat/docs/api/README.md

EchoChat API 接口文档

本目录包含 EchoChat 系统所有接口定义，按功能模块拆分为独立文档，便于维护和查阅。 架构设计见 docs/architecture/system-architecture.md 完整设计方案见 docs/plans/2026-02-27-echochat-system-design.md

---

文档导航

文档	模块	说明
auth.md	认证模块	用户注册、登录、Token 管理、个人信息
contact.md	联系人模块	好友管理、好友分组
im.md	即时通讯模块	会话管理、消息历史、群聊管理
meeting.md	会议模块	即时会议、预约会议、加入/离开会议
notify.md	通知模块	通知列表、已读管理
admin.md	后台管理模块	用户管理、会议监控、系统配置、操作日志
websocket.md	WebSocket 协议	实时消息、会议信令、在线状态事件

---

通用规范

基础 URL

环境	地址
开发环境	http://localhost:8080
生产环境	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": "ok",
    "data": { ... },
    "time": "2026-02-27 18:00:00"
}

错误响应：

{
    "code": 1001,
    "message": "参数错误：邮箱格式不正确",
    "data": null,
    "time": "2026-02-27 18:00:00"
}

错误码定义

通用错误码（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. 错误码新增时：在本文档的错误码定义中追加，保持各模块错误码区间不重叠