# Phase 2a 设计文档：WebSocket 实时通讯与联系人管理

> **状态：** 设计确认，开发中
> **分支：** `feature/phase2a-websocket-contacts`
> **实施计划：** `docs/plans/2026-03-02-phase2a-implementation.md`（独立文件）
> **前置依赖：** Phase 1 全部完成（用户认证 + 管理端用户管理）

---

## 一、设计目标

搭建 WebSocket 实时通讯基础设施，实现完整联系人/好友管理功能，为 Phase 2b 即时聊天奠定基础。

**核心交付物：**
- WebSocket 长连接（心跳、断线重连、Redis Pub/Sub 消息总线）
- 联系人完整功能（好友申请/分组/黑名单/搜索/推荐）
- 在线状态管理（混合推拉方案）
- 管理端：在线监控 + 好友关系管理

---

## 二、架构方案

### 2.1 消息总线：Redis Pub/Sub 全量路由

所有跨用户的实时消息经 Redis Pub/Sub 路由，每个用户拥有独立频道。

**消息投递链路：**

```
业务层（Service）
    ↓ PUBLISH echo:ws:channel:{targetUserID}
Redis Pub/Sub
    ↓ SUBSCRIBE
目标实例 Hub
    ↓ send chan
目标 Client WebSocket
```

**方案选定理由：**
- 天然支持多实例扩展（第三期微服务拆分无需重构）
- 消息路由标准化，所有模块统一使用 Pub/Sub
- 当前单实例阶段性能影响微乎其微（延迟增加 ~0.1-0.5ms）

### 2.2 WebSocket 连接管理

| 组件 | 职责 |
|------|------|
| `pkg/ws/hub.go` | Hub 连接管理（注册/注销/按 userID 查找） |
| `pkg/ws/client.go` | 客户端连接封装（readPump + writePump + 心跳） |
| `pkg/ws/message.go` | 统一消息协议（匹配设计文档 5.2 节） |
| `pkg/ws/pubsub.go` | Redis Pub/Sub 封装（Publish/Subscribe/Unsubscribe） |
| `app/ws/handler.go` | WebSocket 升级处理（JWT 认证） |

**连接生命周期：**
1. `GET /ws?token=xxx` → JWT 认证 → gorilla/websocket 升级
2. 创建 Client → 注册 Hub → Redis SADD + SET + SUBSCRIBE
3. 心跳保活 30s（ping/pong）+ Redis TTL 续期
4. 断线 → 注销 Hub → Redis SREM + DEL + UNSUBSCRIBE

**技术选型：** `gorilla/websocket`（社区最成熟，虽已归档但稳定可靠）

### 2.3 消息协议

复用系统设计文档 5.2 节：

```json
// 客户端 → 服务端
{ "event": "contact.request.send", "seq": 1001, "data": {...}, "time": "2026-03-02 10:30:00" }

// 服务端 → 客户端（推送）
{ "event": "notify.friend.request", "seq": 0, "data": {...}, "time": "..." }

// 服务端 → 客户端（ACK）
{ "event": "contact.request.send.ack", "seq": 1001, "code": 0, "message": "ok", "data": {...} }
```

事件命名规范：`{模块}.{对象}.{动作}`

---

## 三、联系人模块设计

### 3.1 数据模型

复用系统设计文档已有表：

- `contact_friendships` — 好友关系（双向存储，status: 0=待确认, 1=已接受, 2=已拒绝, 3=已拉黑）
- `contact_groups` — 好友分组

### 3.2 好友申请流程

```
A 搜索用户 B
    ↓ POST /contacts/request
创建 A→B 记录（status=0）
    ↓ Redis PUBLISH → B
B 收到 WebSocket 推送 notify.friend.request
    ↓ POST /contacts/accept
更新 A→B（status=1）+ 创建 B→A（status=1）
    ↓ Redis PUBLISH → A
A 收到 WebSocket 推送 contact.request.accepted
    → 双向好友关系建立
```

### 3.3 黑名单机制

复用 `contact_friendships.status=3`：
- 拉黑操作：双向删除好友记录 → 新建单向 status=3 记录
- 被拉黑方无法发送好友申请和消息
- 取消拉黑：删除 status=3 记录（不自动恢复好友关系）

### 3.4 REST API

```
# 好友关系
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         好友推荐
```

---

## 四、在线状态设计

### 4.1 混合方案

| 场景 | 方式 | 说明 |
|------|------|------|
| 打开联系人页 | REST 拉取 | `GET /api/v1/contacts/online` 批量查询好友在线状态 |
| 好友上/下线 | WS 推送 | 通过 Pub/Sub 推送 `user.status.online`/`offline` |
| 心跳续期 | Redis TTL | `EXPIRE echo:user:status:{userID} 60` |

### 4.2 Redis 键设计（匹配系统设计文档 4.2 节）

```
echo:user:online                    SET    所有在线用户 ID
echo:user:status:{user_id}          STRING 状态 JSON（TTL=60s 心跳续期）
echo:ws:user:{user_id}              STRING 连接实例信息
echo:ws:channel:{user_id}           Pub/Sub 频道（消息投递）
```

---

## 五、管理端扩展

### 5.1 新增功能

- 仪表盘：实时在线用户数统计卡片
- 在线用户列表页
- 好友关系管理页（查看/删除）

### 5.2 管理端 API

```
GET    /api/v1/admin/online/users    在线用户列表
GET    /api/v1/admin/online/count    在线用户数
GET    /api/v1/admin/contacts        所有好友关系（分页）
DELETE /api/v1/admin/contacts/:id    管理员解除好友关系
```

---

## 六、前台用户端变更

### 6.1 WebSocket 客户端

- 单例模式，`ws://host/ws?token=xxx`
- 心跳 30s，断线指数退避重连（1s → 2s → 4s → 8s → 30s max）
- 事件分发：`on(event, callback)` / `off(event, callback)`

### 6.2 新增页面

- 联系人列表（替换占位页）
- 好友申请列表
- 好友详情（备注/分组/删除/拉黑）
- 搜索添加好友
- 好友分组管理
- 黑名单

---

## 七、文档管理策略

Phase 2a 开始执行新的文档拆分规则：

- **每个 Phase 独立设计文档**（本文件）
- **每个 Phase 独立实施计划**
- **API 文档按模块 + 端拆分**（每文件对应一个功能模块）
- **WebSocket 事件协议独立为文档**
- **单文件控制在 300-500 行以内**

```
docs/
├── api/
│   ├── admin/
│   │   ├── user.md            已有
│   │   ├── online.md          新增：在线监控 API
│   │   └── contact.md         新增：好友关系管理 API
│   └── frontend/
│       ├── auth.md            已有
│       ├── contact.md         新增：联系人 API
│       └── websocket.md       新增：WebSocket 事件协议
├── plans/
│   ├── 2026-02-27-echochat-system-design.md    总设计（蓝图参考）
│   ├── 2026-02-27-phase1-foundation-and-auth.md Phase1（已完成）
│   └── 2026-03-02-phase2a-design.md            本文件
└── progress/
    └── CURRENT_STATUS.md
```