220 lines
8.9 KiB
Markdown
220 lines
8.9 KiB
Markdown
# EchoChat 项目开发进度
|
||
|
||
> **最后更新**：2026-03-03（Phase 2b 即时通讯核心 + ui-ux-pro-max 规范改造完成）
|
||
> **当前阶段**：Phase 2b 已完成
|
||
> **当前分支**：`feature/phase2b-instant-messaging`
|
||
> **实施计划**：`docs/plans/2026-03-03-phase2b-implementation.plan.md`
|
||
> **设计文档**：`docs/plans/2026-03-03-phase2b-design.md`
|
||
|
||
---
|
||
|
||
## 一、Phase 2b Task 完成状态
|
||
|
||
| Task | 描述 | 状态 | 备注 |
|
||
|------|------|------|------|
|
||
| Task 0 | IM Model + 数据库迁移 + 常量 | ✅ 完成 | 3 张表 + init.sql + AutoMigrate |
|
||
| Task 1 | WS 事件路由表机制 | ✅ 完成 | Hub.RegisterEvent/DispatchEvent |
|
||
| Task 2 | IM DAO 层 | ✅ 完成 | ConversationDAO + MessageDAO |
|
||
| Task 3 | IM Service 核心业务 + DTO | ✅ 完成 | 9 个业务方法 + 接口注入 |
|
||
| Task 4 | WS 事件处理器 + 离线推送 | ✅ 完成 | 4 个事件 + OfflinePusher |
|
||
| Task 5 | REST Controller + Router + Wire | ✅ 完成 | 7 个 REST API + 完整 Wire 集成 |
|
||
| Task 6 | 前台 Store + API + WS 事件 | ✅ 完成 | chat.js Store + API + TabBar badge |
|
||
| Task 7 | 会话列表页 + 聊天对话页 | ✅ 完成 | 2 个核心页面 |
|
||
| Task 8 | 设置页 + 搜索页 + 联系人改造 | ✅ 完成 | 2 个辅助页面 + 发消息跳转 |
|
||
| Task 9 | 文档更新 + 代码审查 | ✅ 完成 | 进度/架构文档同步 |
|
||
| UI 改造 | ui-ux-pro-max 规范改造 | ✅ 完成 | uni-icons 替换 emoji + 设计规范文件 |
|
||
|
||
---
|
||
|
||
## 二、Phase 2b 新增功能
|
||
|
||
### 即时通讯（IM）
|
||
- **消息收发**：WebSocket 全双工通讯，im.message.send → ACK + 推送
|
||
- **三态确认**：sending → sent/ACK → failed
|
||
- **消息撤回**：2 分钟内可撤回，推送 im.message.recalled
|
||
- **正在输入**：im.typing 事件，3 秒超时自动清除
|
||
- **离线消息**：WebSocket 重连后服务端主动推送未读会话摘要
|
||
|
||
### 会话管理
|
||
- **自动创建**：首次发消息时自动创建单聊会话
|
||
- **会话列表**：置顶优先 → 最后消息时间降序，冗余 last_msg_* 避免 JOIN
|
||
- **会话操作**：置顶/取消、软删除（不影响对方）、清空聊天记录
|
||
- **未读管理**：DB unread_count + Redis 全局未读数，TabBar badge 显示
|
||
|
||
### WebSocket 事件路由表
|
||
- **Hub.RegisterEvent**：业务模块注册事件处理器
|
||
- **Hub.DispatchEvent**：消息分发到匹配的处理器
|
||
- **事件清单**：im.message.send / im.message.recall / im.conversation.read / im.typing
|
||
|
||
### REST API（7 个）
|
||
| 方法 | 路径 | 描述 |
|
||
|------|------|------|
|
||
| GET | /api/v1/im/conversations | 会话列表 |
|
||
| GET | /api/v1/im/messages | 历史消息（游标分页） |
|
||
| PUT | /api/v1/im/conversations/:id/pin | 置顶/取消 |
|
||
| DELETE | /api/v1/im/conversations/:id | 删除会话 |
|
||
| DELETE | /api/v1/im/conversations/:id/messages | 清空记录 |
|
||
| GET | /api/v1/im/messages/search | 全局搜索 |
|
||
| GET | /api/v1/im/unread | 全局未读数 |
|
||
|
||
### 前端页面（4 个）
|
||
- `pages/chat/index.vue` — 会话列表（TabBar 页面）
|
||
- `pages/chat/conversation.vue` — 聊天对话页
|
||
- `pages/chat/settings.vue` — 聊天设置页
|
||
- `pages/chat/search.vue` — 消息搜索页
|
||
|
||
### 数据库表（3 张）
|
||
- `im_conversations` — 会话表（含冗余 last_msg_* 字段）
|
||
- `im_conversation_members` — 会话成员表（个人视图：置顶/未读/软删除）
|
||
- `im_messages` — 消息表（游标分页索引 + GIN 全文搜索索引）
|
||
|
||
---
|
||
|
||
## 三、Phase 2a 完成总结
|
||
|
||
| Task | 描述 | 状态 | 备注 |
|
||
|------|------|------|------|
|
||
| Task 0-12 | WebSocket + 联系人 + 管理端 | ✅ 全部完成 | 13 个 Task + 8 项 Bug 修复 |
|
||
|
||
- WebSocket 实时通讯（Hub + Client + PubSub）
|
||
- 联系人管理 17 个 API
|
||
- 在线状态管理（Redis SET + TTL）
|
||
- 管理端扩展（在线监控 + 好友管理）
|
||
|
||
---
|
||
|
||
## 四、Phase 1 完成总结
|
||
|
||
| Task | 描述 | 状态 |
|
||
|------|------|------|
|
||
| Task 1-11 | 基础设施 + 认证 + 用户管理 | ✅ 全部完成 |
|
||
|
||
- Go 后端 15+ API、JWT 有状态认证、RBAC 角色权限
|
||
- 前台 uni-app 登录/注册/TabBar/个人中心
|
||
- 管理端 Vue 3 登录/仪表盘/用户列表/详情
|
||
- Docker Compose 一键启动
|
||
|
||
---
|
||
|
||
## 五、关键技术决策记录
|
||
|
||
### 后端（Go）
|
||
1. **框架组合**：Gin + GORM + Wire + Zap + Viper
|
||
2. **JWT 策略**：有状态 JWT，Token 按 clientType 隔离存储在 Redis
|
||
3. **WebSocket**：`gorilla/websocket` + Redis Pub/Sub 跨实例路由
|
||
4. **WS 事件路由**：Hub.eventHandlers map[string]EventHandler + RegisterEvent/DispatchEvent
|
||
5. **IM 跨模块**：FriendChecker + UserInfoGetter 接口注入（contact → im）
|
||
6. **IM 推送**：OfflineMessagePusher 接口注入（im → ws）
|
||
7. **在线状态**：混合方案（Redis SET + STRING TTL + Pub/Sub 推送）
|
||
8. **角色等级**：`auth_roles.level`（1=超管, 10=管理员, 100=普通用户）
|
||
|
||
### 前台用户端（frontend/）
|
||
1. **框架**：uni-app 3.0（Vue 3.4.21）
|
||
2. **状态管理**：Pinia 2.1.7 + pinia-plugin-persistedstate@3
|
||
3. **WebSocket**：`uni.connectSocket`（小程序）/ `WebSocket`（H5）
|
||
4. **IM Store**：chat.js（会话列表 + 消息缓存 + 三态确认 + 全局未读）
|
||
5. **设计系统**：ui-ux-pro-max 规范，MASTER.md + 页面覆盖规范
|
||
6. **图标方案**：@dcloudio/uni-ui uni-icons（easycom 自动引入，跨平台兼容）
|
||
7. **预处理器**：sass（uni-icons SCSS 依赖）
|
||
|
||
### 后台管理端（admin/）
|
||
1. **框架**：Vue 3.5+ + Vite 7.x + Element Plus
|
||
2. **HTTP 客户端**：Axios
|
||
3. **存储隔离**：localStorage key 前缀 `admin_`
|
||
|
||
---
|
||
|
||
## 六、目录结构概览
|
||
|
||
```
|
||
EchoChat/
|
||
├── backend/go-service/
|
||
│ ├── app/
|
||
│ │ ├── admin/ # 管理端
|
||
│ │ ├── auth/ # 认证模块
|
||
│ │ ├── contact/ # [Phase 2a] 联系人模块
|
||
│ │ ├── im/ # [Phase 2b] 即时通讯模块
|
||
│ │ │ ├── controller/ # REST API 控制器
|
||
│ │ │ ├── dao/ # 数据访问（ConversationDAO + MessageDAO）
|
||
│ │ │ ├── handler/ # WS 事件处理器 + 离线推送
|
||
│ │ │ ├── model/ # 数据库模型
|
||
│ │ │ ├── service/ # 核心业务 + 接口定义
|
||
│ │ │ ├── router.go
|
||
│ │ │ └── provider.go
|
||
│ │ ├── ws/ # [Phase 2a] WebSocket 模块
|
||
│ │ ├── constants/ # 含 im.go 常量
|
||
│ │ ├── dto/ # 含 im_dto.go
|
||
│ │ └── provider/
|
||
│ ├── pkg/
|
||
│ │ ├── ws/ # WS 核心（Hub 含事件路由表）
|
||
│ │ ├── db/ logs/ middleware/ utils/
|
||
│ └── router/router.go
|
||
├── frontend/ # 前台（uni-app）
|
||
│ └── src/
|
||
│ ├── api/{auth,contact,user,im}.js
|
||
│ ├── services/websocket.js
|
||
│ ├── store/{user,websocket,contact,chat}.js
|
||
│ ├── pages/chat/ # [Phase 2b] 4 个页面
|
||
│ │ ├── index.vue # 会话列表
|
||
│ │ ├── conversation.vue # 聊天对话
|
||
│ │ ├── settings.vue # 聊天设置
|
||
│ │ └── search.vue # 消息搜索
|
||
│ ├── pages/contact/ # [Phase 2a] 6 个页面
|
||
│ └── components/CustomTabBar.vue（含 badge）
|
||
├── admin/ # 管理端（Vue 3 + Element Plus）
|
||
├── deploy/
|
||
├── design-system/
|
||
└── docs/
|
||
├── api/
|
||
├── plans/
|
||
├── progress/CURRENT_STATUS.md
|
||
└── conventions/
|
||
```
|
||
|
||
---
|
||
|
||
## 七、开发测试指南
|
||
|
||
### 启动命令
|
||
|
||
```bash
|
||
# 1. 启动 PostgreSQL + Redis
|
||
cd deploy && docker compose -f docker-compose.dev.yml up -d postgres redis
|
||
|
||
# 2. 启动 Go 后端（http://localhost:8085）
|
||
cd backend/go-service && go run cmd/server/main.go
|
||
|
||
# 3. 启动管理端（http://localhost:3100）
|
||
cd admin && npm run dev
|
||
|
||
# 4. 启动前台 H5（http://localhost:5173+）
|
||
cd frontend && npm run dev:h5
|
||
```
|
||
|
||
### 测试账号
|
||
|
||
| 账号 | 密码 | 角色 | 用途 |
|
||
|------|------|------|------|
|
||
| `super_admin` | `admin123456` | super_admin | 系统预置唯一超管 |
|
||
| `admin_test` | `admin123456` | user + admin | 管理端登录推荐 |
|
||
| `testuser1` | `test123456` | user + admin | 前台登录测试 |
|
||
| `testuser` | `test123456` | user | 前台登录测试 |
|
||
|
||
### Phase 2b 可测试功能
|
||
|
||
- **会话列表**：发消息自动创建会话 → 列表排序 → 置顶 → 长按删除
|
||
- **聊天**：发送文本 → 三态确认 → 撤回（2分钟内）→ 正在输入提示
|
||
- **离线消息**：断开重连 → 自动推送未读摘要 → TabBar badge 更新
|
||
- **消息搜索**：全局关键词搜索 → 跳转到对应会话
|
||
- **联系人入口**：好友详情页 → 发消息 → 跳转聊天页
|
||
|
||
---
|
||
|
||
## 八、下一阶段规划
|
||
|
||
### Phase 2c - 群聊与增强
|
||
- 群聊会话（建群/加入/退出）
|
||
- 群消息收发
|
||
- 已读回执
|
||
- 消息类型扩展（图片/语音/文件）
|