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

docs/api/frontend/websocket.md

@@ -0,0 +1,141 @@
+# 前端 WebSocket 事件协议
+
+> 完整的 WebSocket 协议文档见 [websocket.md](../websocket.md)
+> 本文档补充前端联系人模块使用的 WebSocket 事件及对接说明
+
+---
+
+## 连接管理
+
+### 连接地址
+
+| 环境 | 地址 |
+|------|------|
+| 开发环境 | `ws://localhost:8085/ws?token=<access_token>` |
+| 生产环境 | `wss://api.echochat.com/ws?token=<access_token>` |
+
+### 前端实现
+
+- **连接服务：** `frontend/src/services/websocket.js`（WebSocketService 单例）
+- **状态管理：** `frontend/src/store/websocket.js`（Pinia Store）
+- **联系人监听：** `frontend/src/store/contact.js`（initWsListeners）
+
+### 心跳与重连
+
+- 心跳间隔：30 秒
+- 重连策略：指数退避 1s → 2s → 4s → 8s → 16s → 最大 30s
+- 连接时自动发送 heartbeat 事件
+
+---
+
+## 联系人相关事件
+
+### heartbeat
+
+**方向：** 客户端 → 服务端
+
+**说明：** 心跳消息，服务端收到后续期在线状态 TTL
+
+**发送格式：**
+```json
+{
+    "event": "heartbeat",
+    "data": {}
+}
+```
+
+---
+
+### notify.friend.request
+
+**方向：** 服务端 → 客户端
+
+**说明：** 收到新的好友申请推送
+
+**data 内容：**
+```json
+{
+    "friendship_id": 5,
+    "from_user_id": 2,
+    "from_nickname": "李四",
+    "from_avatar": "",
+    "message": "我是你的同事"
+}
+```
+
+**前端处理：** `contactStore.initWsListeners` 监听此事件，自动刷新待处理申请列表
+
+---
+
+### contact.request.accepted
+
+**方向：** 服务端 → 客户端
+
+**说明：** 好友申请被对方接受的通知
+
+**data 内容：**
+```json
+{
+    "friendship_id": 5,
+    "user_id": 1,
+    "username": "zhangsan",
+    "nickname": "张三"
+}
+```
+
+**前端处理：** `contactStore.initWsListeners` 监听此事件，自动刷新好友列表
+
+---
+
+### user.status.online
+
+**方向：** 服务端 → 客户端
+
+**说明：** 好友上线通知
+
+**data 内容：**
+```json
+{
+    "user_id": 2,
+    "nickname": "李四"
+}
+```
+
+**前端处理：** 更新 `contactStore.onlineMap` 和好友列表中对应用户的 `is_online` 状态
+
+---
+
+### user.status.offline
+
+**方向：** 服务端 → 客户端
+
+**说明：** 好友离线通知
+
+**data 内容：**
+```json
+{
+    "user_id": 2
+}
+```
+
+**前端处理：** 更新 `contactStore.onlineMap` 和好友列表中对应用户的 `is_online` 状态
+
+---
+
+## 事件监听代码示例
+
+```javascript
+import { useContactStore } from '@/store/contact'
+import { useWebSocketStore } from '@/store/websocket'
+
+const contactStore = useContactStore()
+const wsStore = useWebSocketStore()
+
+// 建立 WebSocket 连接
+wsStore.connect()
+
+// 初始化联系人事件监听
+contactStore.initWsListeners()
+```
+
+以上代码会自动监听 `notify.friend.request`、`contact.request.accepted`、`user.status.online`、`user.status.offline` 四个事件。