wanglei/EchoChat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
前台联系人模块（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
This commit is contained in:
bujinyuan
2026-03-02 17:32:52 +08:00
parent 618c3f4409
commit a508a4cfbc
18 changed files with 3368 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
docs/api/frontend/contact.md
View File

@@ -12,10 +12,19 @@
| POST | /api/v1/contacts/request | 需认证 | 发送好友申请 |
| POST | /api/v1/contacts/accept | 需认证 | 接受好友申请 |
| POST | /api/v1/contacts/reject | 需认证 | 拒绝好友申请 |
| GET | /api/v1/contacts/requests | 需认证 | 获取待处理的好友申请列表 |
| DELETE | /api/v1/contacts/:id | 需认证 | 删除好友 |
| PUT | /api/v1/contacts/:id/remark | 需认证 | 修改好友备注 |
| PUT | /api/v1/contacts/:id/group | 需认证 | 移动好友到分组 |
| POST | /api/v1/contacts/block | 需认证 | 拉黑用户 |
| DELETE | /api/v1/contacts/block/:id | 需认证 | 取消拉黑 |
| GET | /api/v1/contacts/block | 需认证 | 获取黑名单 |
| GET | /api/v1/contacts/groups | 需认证 | 获取好友分组列表 |
| POST | /api/v1/contacts/groups | 需认证 | 创建好友分组 |
| PUT | /api/v1/contacts/groups/:id | 需认证 | 修改好友分组 |
| DELETE | /api/v1/contacts/groups/:id | 需认证 | 删除好友分组 |
| GET | /api/v1/contacts/recommend | 需认证 | 好友推荐 |
| GET | /api/v1/users/search | 需认证 | 搜索用户 |
---
@@ -23,13 +32,11 @@
`GET /api/v1/contacts`
**权限：** 需认证
**查询参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| group_id | int | 否 | 按分组筛选 |
| group_id | int | 否 | 按分组筛选，不传则返回全部 |
**成功响应：**
```json
@@ -38,15 +45,13 @@
"message": "ok",
"data": [
{
"id": 1,
"friend_id": 2,
"user_id": 2,
"username": "lisi",
"nickname": "李四",
"avatar": "",
"remark": "我的同事",
"avatar": "https://cdn.echochat.com/avatar/2.jpg",
"online": true,
"group_id": 1,
"group_name": "同事"
"is_online": true
}
]
}
@@ -58,16 +63,18 @@
`POST /api/v1/contacts/request`
**权限：** 需认证
**请求参数：**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| target_id | int | 是 | 目标用户 ID |
| message | string | 否 | 申请附言，如"我是张三的同事" |
| message | string | 否 | 申请附言 |
**可能的错误码：** 1004（用户不存在），1005（已是好友或已发送过申请）
**错误场景：**
- 400: 不能添加自己为好友
- 400: 已是好友
- 400: 已有待处理的申请
- 403: 对方已将你拉黑
---
@@ -75,15 +82,13 @@
`POST /api/v1/contacts/accept`
**权限：** 需认证
**请求参数：**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| friendship_id | int | 是 | 好友关系记录 ID |
| request_id | int | 是 | 好友申请记录 ID |
**说明：** 接受后系统自动创建双向好友关系，并发送通知给对方。
**说明：** 接受后系统自动创建双向好友关系，并通过 WebSocket 推送 `contact.request.accepted` 事件给对方。
---
@@ -91,35 +96,54 @@
`POST /api/v1/contacts/reject`
**权限：** 需认证
**请求参数：**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| friendship_id | int | 是 | 好友关系记录 ID |
| request_id | int | 是 | 好友申请记录 ID |
---
## 5. 删除好友
## 5. 获取待处理的好友申请
`GET /api/v1/contacts/requests`
**成功响应：**
```json
{
"code": 0,
"message": "ok",
"data": [
{
"id": 5,
"user_id": 3,
"username": "wangwu",
"nickname": "王五",
"avatar": "",
"message": "我是你的同学",
"created_at": "2026-03-01T10:30:00Z"
}
]
}
```
---
## 6. 删除好友
`DELETE /api/v1/contacts/:id`
**权限：** 需认证
**路径参数：** `id` — 好友的用户 ID
**路径参数：** `id` — 好友关系记录 ID
**说明：** 删除后双向关系均解除，关联的单聊会话不会删除（消息记录保留）。
**说明：** 删除后双向关系均解除。
---
## 6. 修改好友备注
## 7. 修改好友备注
`PUT /api/v1/contacts/:id/remark`
**权限：** 需认证
**路径参数：** `id` — 好友关系记录 ID
**路径参数：** `id` — 好友的用户 ID
**请求参数：**
@@ -129,11 +153,45 @@
---
## 7. 获取好友分组列表
## 8. 移动好友到分组
`GET /api/v1/contacts/groups`
`PUT /api/v1/contacts/:id/group`
**权限：** 需认证
**路径参数：** `id` — 好友的用户 ID
**请求参数：**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| group_id | int | 是 | 目标分组 ID，0 为默认分组 |
---
## 9. 拉黑用户
`POST /api/v1/contacts/block`
**请求参数：**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| target_id | int | 是 | 目标用户 ID |
**说明：** 拉黑后自动解除好友关系（如果存在），对方无法向你发送好友申请和消息。
---
## 10. 取消拉黑
`DELETE /api/v1/contacts/block/:id`
**路径参数：** `id` — 被拉黑用户的 ID
---
## 11. 获取黑名单
`GET /api/v1/contacts/block`
**成功响应：**
```json
@@ -141,24 +199,123 @@
"code": 0,
"message": "ok",
"data": [
{ "id": 1, "name": "同事", "sort_order": 0, "count": 15 },
{ "id": 2, "name": "朋友", "sort_order": 1, "count": 8 }
{
"user_id": 5,
"username": "blocked_user",
"nickname": "某用户",
"avatar": ""
}
]
}
```
---
## 8. 创建好友分组
## 12. 获取好友分组列表
`GET /api/v1/contacts/groups`
**成功响应：**
```json
{
"code": 0,
"message": "ok",
"data": [
{ "id": 1, "name": "同事", "sort_order": 0, "friend_count": 15 },
{ "id": 2, "name": "朋友", "sort_order": 1, "friend_count": 8 }
]
}
```
---
## 13. 创建好友分组
`POST /api/v1/contacts/groups`
**权限：** 需认证
**请求参数：**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 分组名称，最多 50 字符 |
**可能的错误码：** 1005（同名分组已存在）
---
## 14. 修改好友分组
`PUT /api/v1/contacts/groups/:id`
**路径参数：** `id` — 分组 ID
**请求参数：**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 新分组名称 |
| sort_order | int | 否 | 排序序号 |
---
## 15. 删除好友分组
`DELETE /api/v1/contacts/groups/:id`
**路径参数：** `id` — 分组 ID
**说明：** 删除分组后，该分组内的好友自动移至默认分组（group_id = 0）。
---
## 16. 好友推荐
`GET /api/v1/contacts/recommend`
**说明：** 基于共同好友算法推荐可能认识的人。
**成功响应：**
```json
{
"code": 0,
"message": "ok",
"data": [
{
"user_id": 8,
"username": "zhaoliu",
"nickname": "赵六",
"avatar": "",
"common_count": 3
}
]
}
```
---
## 17. 搜索用户
`GET /api/v1/users/search`
**查询参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| keyword | string | 是 | 搜索关键词（用户名/昵称模糊匹配） |
| page | int | 否 | 页码，默认 1 |
| page_size | int | 否 | 每页数量，默认 20 |
**成功响应：**
```json
{
"code": 0,
"message": "ok",
"data": [
{
"user_id": 10,
"username": "newuser",
"nickname": "新用户",
"avatar": "",
"is_friend": false
}
]
}
```