wanglei/EchoChat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 同步全部项目文档至 Phase 2a 完成状态

Browse Source 
- 架构设计文档：更新模块职责表（ws/contact 标记已完成）、路由架构、分层图
- 总体系统设计：联系人 API 扩展至 17 个、管理端 API 补充在线监控和好友管理
- Phase 2a 设计文档：状态标记为已完成
- API README：导航表 + 目录结构 + 联系人模块错误码
- 开发规范：新增 WebSocket 事件联动规范（第 8 节）
- 项目规则：新增「文档自动同步规则」，每个 Task 完成后自动检查更新文档

Made-with: Cursor
This commit is contained in:
bujinyuan
2026-03-02 17:53:46 +08:00
parent a508a4cfbc
commit 8ec0261427
6 changed files with 218 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/api/README.md
View File

@@ -13,10 +13,11 @@
| 文档 | 模块 | 状态 | 说明 |
|------|------|------|------|
| [frontend/auth.md](frontend/auth.md) | 用户认证 | ✅ Phase 1 | 注册、登录、Token 刷新、个人信息管理 |
| [frontend/contact.md](frontend/contact.md) | 联系人 | 📋 Phase 2 | 好友申请/管理、好友分组 |
| [frontend/im.md](frontend/im.md) | 即时通讯 | 📋 Phase 2 | 会话列表、消息历史、群聊创建与管理 |
| [frontend/meeting.md](frontend/meeting.md) | 会议 | 📋 Phase 3 | 即时会议、预约会议、加入/离开、会议列表 |
| [frontend/notify.md](frontend/notify.md) | 通知 | 📋 Phase 2 | 通知列表、标记已读 |
| [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 | 会话列表、消息历史、群聊创建与管理 |
| [frontend/meeting.md](frontend/meeting.md) | 会议 | 📋 后续 | 即时会议、预约会议、加入/离开、会议列表 |
| [frontend/notify.md](frontend/notify.md) | 通知 | 📋 后续 | 通知列表、标记已读 |
### 后台管理端 (`admin/`)
@@ -24,14 +25,16 @@
|------|------|------|------|
| [admin/auth.md](admin/auth.md) | 管理员认证 | ✅ Phase 1 | 管理员登录（验证 admin 角色） |
| [admin/user.md](admin/user.md) | 用户管理 | ✅ Phase 1 | 用户列表/详情、状态管理、角色分配、创建用户 |
| [admin/meeting.md](admin/meeting.md) | 会议管理 | 📋 Phase 3 | 会议列表/详情、强制结束、会议统计 |
| [admin/online.md](admin/online.md) | 在线监控 | ✅ Phase 2a | 在线用户列表、在线用户计数 |
| [admin/contact.md](admin/contact.md) | 好友关系管理 | ✅ Phase 2a | 好友关系列表（分页）、管理员解除好友关系 |
| [admin/meeting.md](admin/meeting.md) | 会议管理 | 📋 后续 | 会议列表/详情、强制结束、会议统计 |
| [admin/system.md](admin/system.md) | 系统管理 | 📋 待定 | 仪表盘数据、操作日志、系统配置 |
### 跨端通用
| 文档 | 状态 | 说明 |
|------|------|------|
| [websocket.md](websocket.md) | 📋 Phase 2 | WebSocket 实时事件协议（IM 消息、会议信令、在线状态） |
| [websocket.md](websocket.md) | ✅ Phase 2a | WebSocket 实时事件协议（联系人通知、在线状态、心跳） |
---
@@ -114,6 +117,17 @@ yyyy-MM-dd HH:mm:ss
| 2003 | 账号或密码错误 | 登录失败 |
| 2004 | 账号已被禁用 | 用户状态为禁用 |
#### 联系人模块错误码（2100-2199）
| 错误码 | 含义 | 说明 |
|--------|------|------|
| 2101 | 不能添加自己 | 好友申请目标为自身 |
| 2102 | 已是好友关系 | 重复发送好友申请 |
| 2103 | 已被对方拉黑 | 被拉黑后无法发送申请 |
| 2104 | 申请不存在 | 待处理申请记录不存在或已处理 |
| 2105 | 好友关系不存在 | 尝试操作不存在的好友关系 |
| 2106 | 分组不存在 | 好友分组 ID 无效 |
#### IM 模块错误码（3000-3099）
| 错误码 | 含义 | 说明 |
@@ -177,15 +191,18 @@ yyyy-MM-dd HH:mm:ss
docs/api/
├── README.md # 通用规范（本文件）
├── frontend/ # 前台用户端 API
│ ├── auth.md # 用户认证
│ ├── contact.md # 联系人管理
│ ├── im.md # 即时通讯
│ ├── meeting.md # 会议
│ └── notify.md # 通知
│ ├── auth.md # 用户认证 ✅ Phase 1
│ ├── contact.md # 联系人管理（17 个 API） ✅ Phase 2a
│ ├── websocket.md # WebSocket 事件协议 ✅ Phase 2a
│ ├── im.md # 即时通讯 📋 Phase 2b
│ ├── meeting.md # 会议 📋 后续
│ └── notify.md # 通知 📋 后续
├── admin/ # 后台管理端 API
│ ├── auth.md # 管理员认证
│ ├── user.md # 用户管理
│ ├── meeting.md # 会议管理
│ └── system.md # 系统管理
└── websocket.md # WebSocket 事件协议
│ ├── auth.md # 管理员认证 ✅ Phase 1
│ ├── user.md # 用户管理 ✅ Phase 1
│ ├── online.md # 在线监控 ✅ Phase 2a
│ ├── contact.md # 好友关系管理 ✅ Phase 2a
│ ├── meeting.md # 会议管理 📋 后续
│ └── system.md # 系统管理 📋 待定
└── websocket.md # WebSocket 全量事件协议 ✅ Phase 2a
```

35
docs/architecture/system-architecture.md
View File

@@ -40,10 +40,10 @@ EchoChat 采用 **「精简单体 + 媒体微服务」** 架构，核心思想
│ │ auth │ │ im │ │ meeting │ │ admin │ │
│ │ 认证鉴权 │ │ 即时通讯 │ │ 会议控制 │ │ 后台管理 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
│ ┌──────────┐ ┌──────────┐ │
│ │ contact │ │ notify │ 每个模块: Controller → │
│ │ 联系人 │ │ 通知 │ Service → DAO → Model │
│ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ contact │ │ notify │ │ ws │ 每个模块: │
│ │ 联系人 │ │ 通知 │ │ WebSocket│ Controller → │
│ └──────────┘ └──────────┘ └──────────┘ Service → DAO │
│ │ │ │ │
│ ┌────┴──────────────┴──────────────┴──────┐ │
│ │ 公共基础设施层 (pkg/) │ │
@@ -86,14 +86,15 @@ EchoChat 采用 **「精简单体 + 媒体微服务」** 架构，核心思想
系统的 **"大脑"**，处理所有业务逻辑。
| 模块 | 职责 |
|------|------|
| auth | 用户注册/登录、有状态 JWT Token 管理（Redis 存储）、RBAC 角色权限（当前粗粒度 3 角色，预留细粒度权限点扩展） |
| im | 即时消息收发、会话管理、消息存储 |
| contact | 好友关系管理、好友分组 |
| meeting | 会议创建/管理、信令转发、mediasoup 资源编排 |
| notify | 通知推送、会议邀请、好友申请通知 |
| admin | 后台管理（用户管理、会议监控、系统配置） |
| 模块 | 职责 | 状态 |
|------|------|------|
| auth | 用户注册/登录、有状态 JWT Token 管理（Redis 存储 + client_type 隔离）、RBAC 角色权限（level 等级体系：1=超管, 10=管理员, 100=用户） | ✅ Phase 1 |
| ws | WebSocket 连接管理（Hub/Client/PubSub）、在线状态管理（Redis SET + TTL 心跳续期） | ✅ Phase 2a |
| contact | 好友关系管理（申请/接受/拒绝/删除/拉黑）、好友分组（CRUD + 移动）、用户搜索、好友推荐 | ✅ Phase 2a |
| im | 即时消息收发、会话管理、消息存储 | 🔜 Phase 2b |
| meeting | 会议创建/管理、信令转发、mediasoup 资源编排 | 📋 后续 |
| notify | 通知推送、会议邀请、好友申请通知 | 📋 后续 |
| admin | 后台管理（用户管理 + 角色权限管理 + 在线监控 + 好友关系管理、会议监控、系统配置） | ✅ Phase 1/2a |
**不负责的事情：** 不处理 RTP 媒体数据、不参与音视频转发、不做 WebRTC 协议协商。
@@ -109,8 +110,9 @@ router/
app/auth/router.go ← auth 模块的具体路由定义
app/admin/router.go ← admin 模块的具体路由定义
app/im/router.go ← im 模块的具体路由定义（后续阶段）
app/contact/router.go ← contact 模块的具体路由定义（后续阶段）
app/contact/router.go ← contact 模块的具体路由定义（Phase 2a 已实现）
app/ws/router.go ← WebSocket 模块的路由定义（Phase 2a 已实现）
app/im/router.go ← im 模块的具体路由定义（Phase 2b 实现）
app/meeting/router.go ← meeting 模块的具体路由定义（后续阶段）
```
@@ -122,8 +124,9 @@ main.go
├── engine.GET("/health", ...) // 健康检查
├── auth.RegisterRoutes(engine, ...) // /api/v1/auth/*
├── admin.RegisterRoutes(engine, ...) // /api/v1/admin/*
├── im.RegisterRoutes(engine, ...) // /api/v1/im/* （后续）
├── contact.RegisterRoutes(engine, ...) // /api/v1/contact/* （后续）
├── contact.RegisterRoutes(engine, ...) // /api/v1/contacts/* ✅ Phase 2a
├── ws.RegisterRoutes(engine, ...) // /ws ✅ Phase 2a
├── im.RegisterRoutes(engine, ...) // /api/v1/im/* （Phase 2b）
└── meeting.RegisterRoutes(engine, ...) // /api/v1/meeting/* （后续）
```

39
docs/conventions/frontend-backend-integration.md
View File

@@ -2,7 +2,7 @@
> **适用范围**：EchoChat 项目全端（Go 后端 + admin 管理端 + frontend 用户端）
> **创建日期**：2026-03-02
> **最后更新**：2026-03-02（新增前后台 Token 隔离规范）
> **最后更新**：2026-03-02（Phase 2a：新增 WebSocket 事件联动规范 + 联系人模块错误处理）
---
@@ -312,3 +312,40 @@ JWT Token 的 Claims 中包含 `client_type` 字段，用于：
- [ ] 权限不足时返回 403（`ErrInsufficientPermission`）
- [ ] 前端通过比较 `adminMaxLevel` 和 `targetMaxLevel` 控制 UI 可见性
- [ ] 角色分配使用全量覆盖模式（`SetUserRoles`），非追加模式
---
## 8. WebSocket 事件联动规范
### 8.1 适用范围
仅前台用户端（frontend）使用 WebSocket 实时通讯，管理端（admin）使用 REST 轮询。
### 8.2 连接管理
- WebSocket 地址：`ws(s)://host/ws?token=xxx`
- 认证方式：URL Query 参数传递 JWT Token（前台 frontend Token）
- 心跳间隔：30 秒 ping/pong
- 断线重连：指数退避（1s → 2s → 4s → 8s → 30s max）
### 8.3 事件命名规范
格式：`{模块}.{对象}.{动作}`
| 事件 | 方向 | 说明 |
|------|------|------|
| `heartbeat` | 双向 | 心跳保活 |
| `notify.friend.request` | 服务端 → 客户端 | 收到好友申请 |
| `contact.request.accepted` | 服务端 → 客户端 | 好友申请被接受 |
| `user.status.online` | 服务端 → 客户端 | 好友上线 |
| `user.status.offline` | 服务端 → 客户端 | 好友下线 |
### 8.4 前端事件处理原则
1. **WebSocket Store 统一管理**：连接状态、事件监听、消息发送由 `store/websocket.js` 管理
2. **业务 Store 订阅事件**：各模块 Store（如 `contact.js`）通过 WebSocket Store 注册事件回调
3. **避免页面直接操作 WebSocket**：页面组件通过 Store 间接与 WebSocket 交互
### 8.5 WebSocket 详细协议
> 完整事件协议见 `docs/api/frontend/websocket.md`

125
docs/plans/2026-02-27-echochat-system-design.md
View File

@@ -674,15 +674,33 @@ GET /api/v1/auth/profile
PUT /api/v1/auth/profile
PUT /api/v1/auth/password
# 联系人模块
GET /api/v1/contacts
POST /api/v1/contacts/request
POST /api/v1/contacts/accept
POST /api/v1/contacts/reject
DELETE /api/v1/contacts/:id
PUT /api/v1/contacts/:id/remark
GET /api/v1/contacts/groups
POST /api/v1/contacts/groups
# 联系人模块（Phase 2a 已实现）
GET /api/v1/contacts 好友列表（含在线状态）
POST /api/v1/contacts/request 发送好友申请
POST /api/v1/contacts/accept 接受申请
POST /api/v1/contacts/reject 拒绝申请
DELETE /api/v1/contacts/:id 删除好友
PUT /api/v1/contacts/:id/remark 设置备注
GET /api/v1/contacts/requests 待处理申请列表
# 好友分组
GET /api/v1/contacts/groups 分组列表
POST /api/v1/contacts/groups 创建分组
PUT /api/v1/contacts/groups/:id 修改分组
DELETE /api/v1/contacts/groups/:id 删除分组
PUT /api/v1/contacts/:id/group 移动好友到分组
# 黑名单
POST /api/v1/contacts/block 拉黑用户
DELETE /api/v1/contacts/block/:user_id 取消拉黑
GET /api/v1/contacts/block 黑名单列表
# 搜索与推荐
GET /api/v1/users/search 搜索用户
GET /api/v1/contacts/recommend 好友推荐
# 在线状态
GET /api/v1/contacts/online 批量查询好友在线状态
# 即时通讯模块
GET /api/v1/conversations
@@ -711,25 +729,33 @@ PUT /api/v1/notifications/read-all
### 5.4 后台管理 RESTful API
```
# 管理员认证
POST /api/v1/admin/auth/login
# 管理员认证（Phase 1 已实现）
POST /api/v1/admin/auth/login 管理员登录
# 用户管理
GET /api/v1/admin/users
GET /api/v1/admin/users/:id
PUT /api/v1/admin/users/:id/status
PUT /api/v1/admin/users/:id/roles
POST /api/v1/admin/users
GET /api/v1/admin/roles
GET /api/v1/admin/users/:id/meetings
# 用户管理（Phase 1 已实现）
GET /api/v1/admin/users 用户列表（分页）
GET /api/v1/admin/users/:id 用户详情
PUT /api/v1/admin/users/:id/status 启用/禁用用户（受 level 层级约束）
PUT /api/v1/admin/users/:id/roles 分配角色（多选，受 level 约束）
POST /api/v1/admin/users 创建用户
GET /api/v1/admin/roles 角色列表（受 level 过滤，仅显示可管理角色）
GET /api/v1/admin/users/:id/meetings 用户的会议记录
# 会议管理
# 在线监控（Phase 2a 已实现）
GET /api/v1/admin/online/users 在线用户列表
GET /api/v1/admin/online/count 在线用户数
# 好友关系管理（Phase 2a 已实现）
GET /api/v1/admin/contacts 所有好友关系（分页）
DELETE /api/v1/admin/contacts/:id 管理员解除好友关系
# 会议管理（后续阶段）
GET /api/v1/admin/meetings
GET /api/v1/admin/meetings/:id
PUT /api/v1/admin/meetings/:id/close
GET /api/v1/admin/meetings/stats
# 系统管理
# 系统管理（后续阶段）
GET /api/v1/admin/dashboard
GET /api/v1/admin/logs
GET /api/v1/admin/system/config
@@ -789,10 +815,12 @@ pages/
│ ├── conversation.vue # 聊天对话页
│ └── group-create.vue # 创建群聊
├── contact/
│ ├── index.vue # 联系人列表
│ ├── add-friend.vue # 添加好友
│ ├── friend-requests.vue # 好友申请列表
│ └── detail.vue # 好友资料页
│ ├── index.vue # 联系人列表（含搜索/在线状态） ✅ Phase 2a
│ ├── search.vue # 搜索添加好友 + 好友推荐 ✅ Phase 2a
│ ├── request.vue # 好友申请列表（接受/拒绝） ✅ Phase 2a
│ ├── detail.vue # 好友详情（备注/分组/拉黑/删除） ✅ Phase 2a
│ ├── groups.vue # 好友分组管理（CRUD） ✅ Phase 2a
│ └── blacklist.vue # 黑名单管理 ✅ Phase 2a
├── meeting/
│ ├── index.vue # 会议首页（即将开始 + 进行中 + 快速入口）
│ ├── create.vue # 创建即时会议
@@ -815,25 +843,27 @@ TabBar 导航（底部4标签）：消息 | 联系人 | 会议 | 我的
```
views/
├── login.vue # 管理员登录
├── dashboard/index.vue # 数据看板
├── login.vue # 管理员登录 ✅ Phase 1
├── dashboard/index.vue # 数据看板 📋 后续
├── user/
│ ├── list.vue # 用户列表
│ └── detail.vue # 用户详情（含会议记录Tab）
│ ├── list.vue # 用户列表 ✅ Phase 1
│ └── detail.vue # 用户详情（含会议记录Tab） 📋 后续
├── monitor/
│ └── online.vue # 在线用户监控 ✅ Phase 2a
├── contact/
│ └── list.vue # 好友关系管理 ✅ Phase 2a
├── meeting/
│ ├── list.vue # 会议列表
│ ├── detail.vue # 会议详情
│ └── monitor.vue # 实时监控
│ ├── list.vue # 会议列表 📋 后续
│ ├── detail.vue # 会议详情 📋 后续
│ └── monitor.vue # 实时监控 📋 后续
├── permission/
│ ├── role.vue # 角色管理
│ └── assign.vue # 权限分配
│ ├── role.vue # 角色管理 📋 后续
│ └── assign.vue # 权限分配 📋 后续
├── system/
│ ├── config.vue # 系统配置
│ └── logs.vue # 操作日志
│ ├── config.vue # 系统配置 📋 后续
│ └── logs.vue # 操作日志 📋 后续
└── layout/
├── index.vue # 布局框架
├── sidebar.vue # 侧边栏
└── header.vue # 顶部栏
├── index.vue # 布局框架（含侧边栏导航） ✅ Phase 1
```
---
@@ -893,9 +923,24 @@ services:
## 八、开发分期规划
### 第一期（MVP）
#### Phase 1：基础设施与用户认证 ✅ 已完成
- 用户注册/登录（邮箱+密码、用户名+密码）
- 有状态 JWT Token 管理（Redis 存储 + client_type 隔离）
- RBAC 角色权限（level 等级体系）
- 后台管理端基础框架 + 用户管理
- Docker Compose 开发环境
#### Phase 2a：WebSocket 实时通讯与联系人管理 ✅ 已完成
- WebSocket 长连接（心跳、断线重连、Redis Pub/Sub 消息总线）
- 联系人完整功能（好友申请/接受/拒绝/删除/分组/黑名单/搜索/推荐）
- 在线状态管理（混合推拉方案）
- 管理端扩展（在线监控 + 好友关系管理）
#### Phase 2b：即时通讯消息系统 🔜 待开发
- 即时聊天（单聊 + 群聊，文字/图片/文件）
- 联系人/好友管理
#### Phase 2c：会议与通知 📋 待规划
- 多人音视频会议（即时会议 + 预约会议）
- 消息通知系统

2
docs/plans/2026-03-02-phase2a-design.md
View File

@@ -1,6 +1,6 @@
# Phase 2a 设计文档：WebSocket 实时通讯与联系人管理
> **状态：** 设计确认，开发中
> **状态：** ✅ 已完成（全部 13 个 Task）
> **分支：** `feature/phase2a-websocket-contacts`
> **实施计划：** `docs/plans/2026-03-02-phase2a-implementation.md`（独立文件）
> **前置依赖：** Phase 1 全部完成（用户认证 + 管理端用户管理）