f1853f125d
后端（notify 模块） - 新增 notify 模块：DAO/Service/Pusher 接口/Controller/Router/CleanupTask - 数据库 DDL：notify_notifications 表 + 3 索引（user+created/user+is_read/user+category） - 11 种 type 枚举（好友/群聊 9 种 + meeting_* 2 种预留）+ 4 种 category - 跨模块集成：contact 3 处 Pusher（friend_request/accepted/rejected） - 跨模块集成：group 6 处 Pusher（invite/join_request/approved/rejected/kicked/role_changed） - WS handler 断线补偿：连接建立即推送 notify.unread.total - 5 REST API（4 用户 + 1 管理员广播）+ 2 WS 事件（notify.new / notify.unread.total） - 30 天已读通知定时清理（未读永久保留） - Provider/Wire 依赖注入（NotifyPusher、NotifyConnectHook、UserInfoResolver 接口） 前端 - 新增 notify 模块：API/Pinia Store（5 分类分页缓存 + 未读数 + WS 事件）/NotifyItem/通知中心主页 - profile 入口：铃铛 badge + 菜单项 badge + 数字显示 - App.vue/login 初始化 notifyStore WS 监听；logout 调用 notifyStore.reset() 清缓存 - 清理 contact.js/group.js 中散落 toast 与冗余 notify.friend.request/group.join.request 处理 - CustomTabBar 新增 hasDot() 聚合指示器：我的 Tab 显示纯红点（无数字）， 当前聚合 notifyStore.unreadTotal，未来可扩展「资料待完善/安全提醒/新版本」等 文档 - 新增 Phase 2e 整体路线图 docs/plans/2026-04-20-phase2e-design.md - 新增 Phase 2e-1 专用设计 docs/plans/2026-04-20-phase2e-1-design.md（§6.4 TabBar 聚合红点） - 新增 Phase 2e-1 实施计划 docs/plans/2026-04-20-phase2e-1-implementation.plan.md - 新增 E2E 验证报告 test-report-phase2e-1-notification.md（含 Playwright MCP 2 个现场 Bug 修复记录） - 更新 docs/progress/CURRENT_STATUS.md、docs/api/README.md、docs/api/frontend/notify.md - 更新 .cursor/rules/project-context.mdc、docs/plans/2026-02-27-echochat-system-design.md 其他 - .gitignore 排除 .playwright-mcp/ MCP 临时快照 架构决策 - 单端 WS 连接：沿用现有 ws.Hub，多端已读同步推迟到 Phase 2f/二期 - 跨模块依赖：contact/group → notify 严格单向（接口注入模式） - 降级策略：Pusher 先入库后推送；WS 失败不回滚入库；入库失败仅 Warn 不影响业务 Playwright MCP 回归（4 类场景全通） - 实时推送（admin 广播 → 1s 内前端自动插入 + 角标 +1） - Deep-link 跳转（好友申请通知 → contact/request 页） - 批量清零（全部已读按钮） - TabBar 聚合红点（有未读亮/全部已读灭）与 notifyStore.unreadTotal 三层同步 Made-with: Cursor
215 lines
8.5 KiB
Markdown
215 lines
8.5 KiB
Markdown
# 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) | 通知中心 | ✅ Phase 2e-1 | 5 个 API：通知列表（游标分页）/未读数/标记已读/全部已读/管理员广播 + 2 个 WS 事件（notify.new/notify.unread.total） |
|
||
|
||
### 后台管理端 (`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/message.md](admin/message.md) | 消息管理 | ✅ Phase 2d | 消息列表/详情/撤回/删除、消息统计（5 个 API） |
|
||
| [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
|
||
│ ├── message.md # 消息管理（5 个 API） ✅ Phase 2d
|
||
│ ├── meeting.md # 会议管理 📋 后续
|
||
│ └── system.md # 系统管理 📋 待定
|
||
└── websocket.md # WebSocket 全量事件协议 ✅ Phase 2a/2b/2c
|
||
```
|