feat(phase2a): 前台联系人页面 + 管理端在线监控/好友管理 + API 文档

前台联系人模块（ui-ux-pro-max 规范）： - contact/index.vue: 好友列表（搜索/在线状态/骨架屏） - contact/request.vue: 好友申请列表（接受/拒绝/防重复提交） - contact/detail.vue: 好友详情（备注/分组/拉黑/删除） - contact/search.vue: 搜索添加好友 + 好友推荐 - contact/groups.vue: 好友分组管理（CRUD） - contact/blacklist.vue: 黑名单管理管理端前端： - views/monitor/online.vue: 在线监控（统计卡片/用户表格/30s 自动刷新） - views/contact/list.vue: 好友关系管理（分页表格/强制删除） - api/monitor.js + api/contact.js: 管理端 API 封装 - 路由 + 侧边栏导航更新 API 文档（4 份）： - docs/api/frontend/contact.md: 17 个接口完整文档 - docs/api/frontend/websocket.md: 前端 WS 事件协议 - docs/api/admin/online.md: 在线监控 API - docs/api/admin/contact.md: 好友管理 API 进度文档更新至 Phase 2a 全部完成 Made-with: Cursor
2026-03-02 17:32:52 +08:00
parent 618c3f4409
commit a508a4cfbc
18 changed files with 3368 additions and 188 deletions
--- a/docs/progress/CURRENT_STATUS.md
+++ b/docs/progress/CURRENT_STATUS.md
@@ -1,187 +1,209 @@
 # EchoChat 项目开发进度

-> **最后更新**：2026-03-02（角色等级体系与权限管控实施）
-> **当前阶段**：Phase 1 - 基础设施与用户认证
-> **当前分支**：`feature/phase1-foundation-and-auth`
-> **实施计划**：`docs/plans/2026-02-27-phase1-foundation-and-auth.md`
+> **最后更新**：2026-03-02（Phase 2a 完成 - WebSocket 实时通讯与联系人管理）
+> **当前阶段**：Phase 2a - WebSocket 实时通讯与联系人管理
+> **当前分支**：`feature/phase2a-websocket-contacts`
+> **实施计划**：`phase_2a_实施计划_221003ce.plan.md`
+> **设计文档**：`docs/plans/2026-03-02-phase2a-design.md`

 ---

-## 一、Task 完成状态
+## 一、Phase 2a Task 完成状态

 | Task | 描述 | 状态 | 备注 |
 |------|------|------|------|
-| Task 1 | Docker Compose 开发环境搭建 | ✅ 完成 | PostgreSQL 17 + Redis 7 |
-| Task 2 | 数据库初始化脚本 | ✅ 完成 | users + user_roles + roles 表 |
-| Task 3 | Go 后端服务骨架 | ✅ 完成 | Gin + GORM + Wire + Zap |
-| Task 4 | Auth Service 层 | ✅ 完成 | 注册/登录/Token/Profile API |
-| Task 5 | Auth Controller & Router | ✅ 完成 | JWT + Redis 有状态校验 |
-| Task 6 | uniapp 前端骨架 | ✅ 完成 | request/storage/api/store/pages.json |
-| Task 7 | uniapp 登录/注册页面 | ✅ 完成 | 基于 ui-ux-pro-max 设计系统 |
-| Task 8 | 首页框架与 TabBar | ✅ 完成 | 自定义 TabBar + 路由分发 |
-| Task 9 | Vue 3 管理端项目搭建 | ✅ 完成 | Element Plus + Pinia 3.x |
-| Task 10 | 管理端用户管理模块 | ✅ 完成 | 后端 admin 模块 + 前端列表/详情页 |
-| Task 11 | 端到端集成测试与文档 | ✅ 完成 | Dockerfile + Docker Compose + README + 全流程 API 验证 + Playwright 页面验证 + 代码审查 |
+| Task 0 | 设计文档 + 新分支 | ✅ 完成 | 架构设计、Redis Pub/Sub、文档策略 |
+| Task 1 | 数据库表结构 | ✅ 完成 | contact_friendships + contact_groups |
+| Task 2 | WebSocket 核心模块 | ✅ 完成 | Hub + Client + PubSub + Handler |
+| Task 3 | Contact 模型与 DAO | ✅ 完成 | friendship + friend_group DAO |
+| Task 4 | Contact Service | ✅ 完成 | 好友申请/分组/黑名单/搜索/推荐 |
+| Task 5 | Contact Controller & Router | ✅ 完成 | 17 个 REST API + Wire 集成 |
+| Task 6 | 在线状态管理 | ✅ 完成 | Redis SET + TTL 心跳续期 |
+| Task 7 | 管理端后端 | ✅ 完成 | 在线监控 + 好友关系管理 API |
+| Task 8 | 前台 WS 客户端 + Store + API | ✅ 完成 | websocket.js + contact.js Store/API |
+| Task 9 | 前台联系人页面 | ✅ 完成 | 6 个页面（ui-ux-pro-max 规范） |
+| Task 10 | 管理端前端 | ✅ 完成 | 在线监控 + 好友管理页面 |
+| Task 11 | API 文档编写 | ✅ 完成 | 4 份独立文档 |
+| Task 12 | 集成测试 + 文档更新 + 代码审查 | ✅ 完成 | 三端编译通过 |

 ---

-## 二、关键技术决策记录
+## 二、Phase 2a 新增功能
+
+### WebSocket 实时通讯
+- **连接管理**：`gorilla/websocket` + JWT 认证 + 心跳（30s）
+- **消息架构**：Redis Pub/Sub 跨实例消息路由
+- **Hub**：本地连接管理（注册/注销/按用户发送）
+- **Client**：读写泵 + 断线回调 + 缓冲通道
+
+### 联系人管理（17 个 API）
+- 好友申请（发送/接受/拒绝）
+- 好友列表（按分组筛选 + 在线状态）
+- 好友详情（备注/分组移动）
+- 好友删除 + 拉黑/取消拉黑
+- 好友分组（CRUD + 排序）
+- 用户搜索 + 好友推荐（共同好友算法）
+
+### 在线状态管理
+- Redis SET `echo:user:online` 存储在线用户集合
+- Redis STRING `echo:user:status:{user_id}` + TTL 心跳续期
+- Pub/Sub 推送好友上下线通知
+
+### 管理端扩展
+- 在线监控页面（自动 30s 刷新 + 统计卡片）
+- 好友关系管理（分页列表 + 强制删除）
+
+---
+
+## 三、Phase 1 完成总结
+
+| Task | 描述 | 状态 |
+|------|------|------|
+| Task 1-11 | 基础设施 + 认证 + 用户管理 | ✅ 全部完成 |
+
+- Go 后端 15+ API、JWT 有状态认证、RBAC 角色权限（level 等级体系）
+- 前台 uni-app 登录/注册/TabBar/个人中心
+- 管理端 Vue 3 登录/仪表盘/用户列表/详情
+- Docker Compose 一键启动
+
+---
+
+## 四、关键技术决策记录

 ### 后端（Go）
 1. **框架组合**：Gin + GORM + Wire + Zap + Viper
-2. **JWT 策略**：有状态 JWT，Token 按 clientType 隔离存储在 Redis（`echo:auth:token:{frontend|admin}:{user_id}`）
-3. **密码加密**：bcrypt
-4. **数据库时间精度**：`TIMESTAMP(0)` 精确到秒
-5. **API 响应格式**：统一 `{ "code": 0, "message": "success", "data": ... }`
-6. **常量命名**：Go camelCase（`UserStatusActive`），非大写下划线
-7. **模块路由**：模块内自注册 + 中央 router 聚合
-8. **角色等级体系**：`auth_roles.level` 字段（值越小权限越高：1=超管, 10=管理员, 100=普通用户），所有管理操作强制执行"高等级管理低等级"规则
+2. **JWT 策略**：有状态 JWT，Token 按 clientType 隔离存储在 Redis
+3. **WebSocket**：`gorilla/websocket` + Redis Pub/Sub 跨实例路由
+4. **在线状态**：混合方案（Redis SET + STRING TTL + Pub/Sub 推送）
+5. **角色等级**：`auth_roles.level`（1=超管, 10=管理员, 100=普通用户）

 ### 前台用户端（frontend/）
-1. **框架**：uni-app 3.0（Vue 3.4.21 框架锁定）
+1. **框架**：uni-app 3.0（Vue 3.4.21）
 2. **状态管理**：Pinia 2.1.7 + pinia-plugin-persistedstate@3
-3. **npm 配置**：`.npmrc` 设置 `legacy-peer-deps=true`（uni-app 兼容性）
-4. **模块系统**：ESM（`export` / `import`），禁止 CommonJS
-5. **响应式单位**：`rpx`（750rpx = 屏幕宽度）
-6. **设计系统**：ui-ux-pro-max 生成，持久化在 `design-system/echochat/`
-7. **色板**：Primary `#2563EB` / BG `#F8FAFC` / Text `#1E293B`
-8. **开发端口**：`npm run dev:h5` → localhost:5173+
+3. **WebSocket**：`uni.connectSocket`（小程序）/ `WebSocket`（H5）
+4. **设计系统**：ui-ux-pro-max 规范

 ### 后台管理端（admin/）
-1. **框架**：Vue 3.5+ + Vite 7.x（独立项目，不受 uni-app 限制）
-2. **UI 组件**：Element Plus（中文语言包）
-3. **状态管理**：Pinia 3.x（最新版）
-4. **HTTP 客户端**：Axios
-5. **存储隔离**：localStorage key 前缀 `admin_`
-6. **主题色**：CSS 变量覆盖 Element Plus → `--el-color-primary: #2563EB`
-7. **开发端口**：`npm run dev` → localhost:3100（Vite proxy 代理后端）
+1. **框架**：Vue 3.5+ + Vite 7.x + Element Plus
+2. **HTTP 客户端**：Axios
+3. **存储隔离**：localStorage key 前缀 `admin_`

 ---

-## 三、目录结构概览
+## 五、目录结构概览

 ```
 EchoChat/
-├── backend/go-service/          # Go 后端服务
+├── backend/go-service/
 │   ├── app/
-│   │   ├── admin/               # 管理端模块（controller/service/dao/router/provider）
-│   │   ├── auth/                # 认证模块（controller/service/dao/model/router）
-│   │   ├── constants/           # 常量（role_code/user_status）
-│   │   ├── dto/                 # 数据传输对象（auth_dto + admin_dto）
-│   │   └── provider/            # Wire 依赖注入
-│   ├── cmd/server/main.go       # 入口
-│   ├── config/                  # 配置
-│   ├── pkg/                     # 公共包（db/logs/middleware/utils）
-│   └── router/router.go         # 中央路由聚合
-├── frontend/                    # 前台用户端（uni-app）
+│   │   ├── admin/               # 管理端（controller/service/provider）
+│   │   ├── auth/                # 认证模块
+│   │   ├── contact/             # [Phase 2a] 联系人模块
+│   │   │   ├── controller/
+│   │   │   ├── dao/
+│   │   │   ├── model/
+│   │   │   ├── service/
+│   │   │   ├── router.go
+│   │   │   └── provider.go
+│   │   ├── ws/                  # [Phase 2a] WebSocket 模块
+│   │   │   ├── handler.go
+│   │   │   ├── online_service.go
+│   │   │   ├── provider.go
+│   │   │   └── router.go
+│   │   ├── constants/
+│   │   ├── dto/
+│   │   └── provider/
+│   ├── pkg/
+│   │   ├── ws/                  # [Phase 2a] WebSocket 核心
+│   │   │   ├── hub.go
+│   │   │   ├── client.go
+│   │   │   ├── pubsub.go
+│   │   │   └── message.go
+│   │   ├── db/ logs/ middleware/ utils/
+│   └── router/router.go
+├── frontend/                    # 前台（uni-app）
 │   └── src/
-│       ├── api/auth.js
-│       ├── components/CustomTabBar.vue
-│       ├── pages/{auth,chat,contact,meeting,profile,index}/
-│       ├── store/user.js
-│       └── utils/{request,storage}.js
-├── admin/                       # 后台管理端（Vue 3 + Element Plus）
+│       ├── api/{auth,contact,user}.js
+│       ├── services/websocket.js     # [Phase 2a]
+│       ├── store/{user,websocket,contact}.js
+│       ├── pages/contact/            # [Phase 2a] 6 个页面
+│       │   ├── index.vue
+│       │   ├── request.vue
+│       │   ├── detail.vue
+│       │   ├── search.vue
+│       │   ├── groups.vue
+│       │   └── blacklist.vue
+│       └── components/CustomTabBar.vue
+├── admin/                       # 管理端（Vue 3 + Element Plus）
 │   └── src/
-│       ├── api/auth.js
-│       ├── router/index.js
-│       ├── store/user.js
-│       ├── utils/{request,storage}.js
-│       └── views/{layout,login,dashboard,user}/
+│       ├── api/{auth,user,monitor,contact}.js
+│       ├── views/
+│       │   ├── monitor/online.vue    # [Phase 2a]
+│       │   ├── contact/list.vue      # [Phase 2a]
+│       │   ├── layout/ login/ dashboard/ user/
+│       └── router/index.js
 ├── deploy/
-│   ├── docker-compose.dev.yml
-│   └── docker/postgres/init.sql
-├── design-system/echochat/      # ui-ux-pro-max 生成的设计系统
-│   ├── MASTER.md
-│   └── pages/{login,admin-login}.md
+├── design-system/
 └── docs/
-    ├── api/                     # API 接口文档
-    ├── architecture/            # 系统架构文档
-    ├── conventions/             # 开发规范文档
-    │   └── frontend-backend-integration.md  # 前后端集成规范
-    ├── plans/                   # 实施计划文档
-    └── progress/                # 进度文档（本文件）
+    ├── api/
+    │   ├── frontend/{auth,contact,websocket}.md
+    │   ├── admin/{auth,user,online,contact}.md
+    │   └── websocket.md
+    ├── plans/
+    ├── progress/CURRENT_STATUS.md
+    └── conventions/
 ```

 ---

-## 四、开发流程规范
+## 六、开发测试指南

-1. **工作流**：使用 superpowers 流程控制开发节奏
-2. **前端设计**：**必须**使用 ui-ux-pro-max 技能包，禁止手动设计
-3. **代码注释**：所有公开函数、组件、Store 必须有详细注释
-4. **文档同步**：代码变更后必须同步更新相关文档
-5. **Git 分支**：`feature/phase1-foundation-and-auth`
-6. **验证方式**：Playwright MCP 进行页面自动化验证
-7. **代码审查**：每个 Task 完成后，使用 `code-reviewer` 子代理进行结构化代码审查，对照实施计划和编码标准检查
-8. **完成验证**：使用 `verification-before-completion` 技能，在声称完成前必须运行验证命令并确认输出结果
-9. **前后端联动规范**：详见 `docs/conventions/frontend-backend-integration.md`，核心要求：前端错误提示必须优先使用后端 message，禁止硬编码覆盖；后端错误处理禁止忽略 error；登录安全统一返回 401
-
---
-
-## 五、开发测试指南
-
-### 启动命令（开发模式）
-
-前提：postgres 和 redis 已通过 Docker Compose 运行。
+### 启动命令

 ```bash
-# 启动 Go 后端（http://localhost:8085）
+# 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

-# 启动管理端（http://localhost:3100）
+# 3. 启动管理端（http://localhost:3100）
 cd admin && npm run dev

-# 启动前台 H5（http://localhost:5173+）
+# 4. 启动前台 H5（http://localhost:5173+）
 cd frontend && npm run dev:h5
 ```

-如需全容器启动（包括 Go 服务）：`cd deploy && docker compose -f docker-compose.dev.yml up -d`
-
 ### 测试账号

 | 账号 | 密码 | 角色 | 用途 |
 |------|------|------|------|
-| `admin_test` | `admin123456` | user + admin | **管理端登录推荐** |
+| `super_admin` | `admin123456` | super_admin | 系统预置唯一超管 |
+| `admin_test` | `admin123456` | user + admin | 管理端登录推荐 |
 | `testuser1` | `test123456` | user + admin | 前台登录测试 |
 | `testuser` | `test123456` | user | 前台登录测试 |
-| `testuser3` | `test123456` | user | 前台登录测试 |
-| `created_by_admin` | `pass123456` | user | 管理端创建的用户 |
-| `super_admin` | `admin123456` | super_admin | **系统预置唯一超管账号** |

-> 也可以通过注册接口或管理端"创建用户"功能创建新的测试账号。
+### Phase 2a 可测试功能

-### 可测试功能
-
- **管理端**：登录 → 仪表盘 → 用户列表 → 搜索/筛选 → 用户详情 → 禁用/启用（受角色等级约束） → 批量设置角色（Checkbox 多选 + 等级管控） → 创建用户
- **前台 H5**：注册 → 登录 → 个人中心 → 修改资料 → 退出登录
- **API**：`GET http://localhost:8085/health`（健康检查）
+- **前台联系人**：好友列表 → 搜索添加 → 好友申请 → 好友详情 → 备注/分组 → 拉黑/删除
+- **前台 WebSocket**：自动连接 → 心跳 → 在线状态实时更新 → 好友申请推送
+- **管理端在线监控**：在线用户数 → 在线用户列表 → 自动刷新
+- **管理端好友管理**：好友关系列表 → 强制删除关系

 ---

-## 六、已知问题与注意事项
+## 七、已知问题

-1. ~~前端工具模块使用了 CommonJS，已修复为 ESM~~（已解决）
-2. ~~前端登录失败时错误提示不正确（硬编码"登录已过期"覆盖后端消息）~~（已修复，详见 `docs/conventions/frontend-backend-integration.md`）
-3. ~~后端登录时用户不存在返回 404 暴露用户是否注册~~（已修复为统一返回 401）
-4. uni-app 的 `tabBar.custom: true` 配合自定义 TabBar 组件使用
-5. 管理端和前台的 localStorage key 通过前缀隔离（`admin_` vs `echo_`）
-6. Go 依赖版本需匹配 Go 1.23.12，不要随意升级 Go 工具链
-7. `.gitignore` 已配置忽略：`.cursor/`、`.vite/`、`node_modules/`、`dist/`、`*.png`（根目录截图）、`logs/` 等
+1. uni-app 的 `tabBar.custom: true` 配合自定义 TabBar 组件使用
+2. Go 依赖版本需匹配 Go 1.23.12
+3. 管理端 Element Plus 全量导入导致打包体积较大（后续可改为按需导入）

 ---

-## 六、Phase 1 完成总结
+## 八、下一阶段规划

-### Phase 1 阶段成果
- **11 个 Task 全部完成**，端到端验证通过
- **Go 后端**：15 个 API 端点，JWT 有状态认证，RBAC 角色权限
- **前台 uni-app**：登录/注册/TabBar/个人中心
- **管理端 Vue 3**：登录/仪表盘/用户列表/用户详情
- **基础设施**：Docker Compose 一键启动（PostgreSQL + Redis + Go 服务）
- **代码审查**：code-reviewer 审查通过，已修复 panic 风险、错误处理等问题
-
-### 下一阶段：Phase 2 - 即时通讯
- 待制定实施计划
- WebSocket 长连接 + 消息系统
- 联系人/好友管理
+### Phase 2b - 即时通讯消息系统
+- 会话管理（单聊/群聊）
+- 消息收发 + 离线消息
 - 消息通知
+- 已读回执