Files

bujinyuan 86f371cc5c docs: Phase 2c 设计文档 + 实施计划 + 项目进度更新

- 新增 Phase 2c 设计文档（群聊与已读回执）
- 新增 Phase 2c 实施计划（14 个 Task）
- 更新 CURRENT_STATUS.md 反映 Phase 2c 规划
- 更新 project-context.mdc 新增 Phase 2c 进度和模块信息

Made-with: Cursor

2026-03-04 10:34:35 +08:00

12 KiB

Raw Blame History

EchoChat 项目开发进度

最后更新：2026-03-04（Phase 2c 设计完成，待实施） 当前阶段：Phase 2c 设计完成，准备开始实施 当前分支：feature/phase2b-instant-messaging（Phase 2c 分支待创建） 实施计划：docs/plans/2026-03-04-phase2c-implementation.plan.md 设计文档：docs/plans/2026-03-04-phase2c-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 + 设计规范文件
代码审查修复	后端 7 项修复	✅ 完成	P0×2 + P1×3 + 推送补全×2
用户测试修复	8 项 Bug 修复	✅ 完成	好友申请/接受、在线状态、UI 布局等

代码审查修复详情

#	优先级	修复内容
Fix 1	P0	ClearHistory 改为个人视图操作（ClearBeforeMsgID），不再删除双方消息
Fix 2	P0	Redis 未读数负数保护（Lua 脚本原子递减，下限为 0）
Fix 3	P1	GetConversationList N+1 查询优化（LEFT JOIN 一次获取 peerID）
Fix 4	P1	消息搜索改用 GIN 全文索引（to_tsvector/plainto_tsquery 替代 LIKE）
Fix 5	P1	撤回消息后更新会话预览（last_msg_content = "XX 撤回了一条消息"）
Fix 6	-	im.message.new 推送补充 sender_name、sender_avatar
Fix 7	-	im.message.recalled 推送补充 sender_id

用户测试修复详情

#	修复内容
Fix 8	好友申请拒绝后重新申请失败 — FriendshipDAO 新增 ReactivateRejectedRequest 方法
Fix 9	好友接受申请失败（反向记录 UNIQUE 冲突）— AcceptRequest 先查后改，避免重复插入
Fix 10	Redis 在线状态残留 — OnlineService 启动时清理旧在线数据（cleanStaleOnlineData）
Fix 11	WS 断开时在线状态未清理 — 修正 onDisconnect 判断条件（closedByHub && isOnline）
Fix 12	前端 WS 连接未全局初始化 — App.vue onLaunch/onShow + login.vue 登录后建立连接
Fix 13	后台管理端好友关系页用户 A 列名称错误 — 修正字段绑定 row.user_username
Fix 14	前台好友在线状态初始值缺失 — ContactService 注入 OnlineChecker，GetFriendList 返回 is_online
Fix 15	聊天页消息过多时输入框被挤出 — scroll-view 添加 height:0 + min-height:0 约束

二、Phase 2b 新增功能

即时通讯（IM）

消息收发：WebSocket 全双工通讯，im.message.send → ACK + 推送
三态确认：sending → sent/ACK → failed
消息撤回：2 分钟内可撤回，推送 im.message.recalled
正在输入：im.typing 事件，3 秒超时自动清除
离线消息：WebSocket 重连后服务端主动推送未读会话摘要

会话管理

自动创建：首次发消息时自动创建单聊会话
会话列表：置顶优先 → 最后消息时间降序，LEFT JOIN 一次获取 peerID（N+1 优化）
会话操作：置顶/取消、软删除（不影响对方）、清空聊天记录（个人视图 ClearBeforeMsgID）
未读管理：DB unread_count + Redis STRING 全局未读数（Lua 脚本负数保护），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）

框架组合：Gin + GORM + Wire + Zap + Viper
JWT 策略：有状态 JWT，Token 按 clientType 隔离存储在 Redis
WebSocket：gorilla/websocket + Redis Pub/Sub 跨实例路由
WS 事件路由：Hub.eventHandlers map[string]EventHandler + RegisterEvent/DispatchEvent
IM 跨模块：FriendChecker + UserInfoGetter 接口注入（contact → im）
IM 推送：OfflineMessagePusher 接口注入（im → ws）
在线状态：混合方案（Redis SET + STRING TTL + Pub/Sub 推送）
角色等级：auth_roles.level（1=超管, 10=管理员, 100=普通用户）

前台用户端（frontend/）

框架：uni-app 3.0（Vue 3.4.21）
状态管理：Pinia 2.1.7 + pinia-plugin-persistedstate@3
WebSocket：uni.connectSocket（小程序）/ WebSocket（H5）
IM Store：chat.js（会话列表 + 消息缓存 + 三态确认 + 全局未读）
设计系统：ui-ux-pro-max 规范，MASTER.md + 页面覆盖规范
图标方案：@dcloudio/uni-ui uni-icons（easycom 自动引入，跨平台兼容）
预处理器：sass（uni-icons SCSS 依赖）

后台管理端（admin/）

框架：Vue 3.5+ + Vite 7.x + Element Plus
HTTP 客户端：Axios
存储隔离：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/

七、开发测试指南

启动命令

# 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 — 群聊与已读回执

状态： 设计完成，待实施 设计文档： docs/plans/2026-03-04-phase2c-design.md 实施计划： docs/plans/2026-03-04-phase2c-implementation.plan.md 分支： feature/phase2c-group-read-receipt（待创建，从 phase2b 拉出）

功能范围

模块	内容
群聊管理	建群/加入/退出/解散/搜索/三级角色/禁言/全体禁言/群公告/群昵称/免打扰
群消息	复用 im.message.* 事件 + @某人/@所有人 + 管理员撤回（无时限）+ 系统消息
已读回执	单聊会话级（last_read_msg_id）+ 群聊消息级（im_message_reads 表）+ 实时推送
MinIO	Docker 容器 + Go SDK + 通用上传 API（群头像）
管理端	群列表/群详情/解散群/移除成员
前端	9 个新页面 + 群聊 Store + 会话列表 Tab 改造

Task 概览（14 个）

Task	描述	状态
Task 0	MinIO Docker + SDK + 通用上传 API	📋
Task 1	数据库迁移 + Model + 常量	📋
Task 2	Group DAO 层	📋
Task 3	Group Service 业务逻辑	📋
Task 4	Group Controller + Router + Wire	📋
Task 5	WS 群管理事件处理器	📋
Task 6	IM Service 扩展（群消息/@提醒/管理员撤回）	📋
Task 7	已读回执后端	📋
Task 8	前端已读回执 UI	📋
Task 9	前端群聊 Store + API + WS 监听	📋
Task 10	群聊核心页面（Tab + 对话 + 创建）	📋
Task 11	群聊管理页面（设置 + 成员 + 邀请 + @选择器）	📋
Task 12	群聊辅助功能（审批 + 搜索 + 免打扰 + 公告）	📋
Task 13	管理端 + 文档更新 + 代码审查	📋

留待后续阶段

消息类型扩展（图片/语音/文件）
管理端消息管理功能

12 KiB Raw Blame History Unescape Escape

EchoChat 项目开发进度

一、Phase 2b Task 完成状态

代码审查修复详情

用户测试修复详情

二、Phase 2b 新增功能

即时通讯（IM）

会话管理

WebSocket 事件路由表

REST API（7 个）

前端页面（4 个）

数据库表（3 张）

三、Phase 2a 完成总结

四、Phase 1 完成总结

五、关键技术决策记录

后端（Go）

前台用户端（frontend/）

后台管理端（admin/）

六、目录结构概览

七、开发测试指南

启动命令

测试账号

Phase 2b 可测试功能

八、下一阶段：Phase 2c — 群聊与已读回执

功能范围

Task 概览（14 个）

留待后续阶段

12 KiB

Raw Blame History