zhibo/模块文档/05-好友管理模块.md

# 好友管理模块接口文档

## 模块概述
好友管理模块提供好友搜索、添加、删除、拉黑等功能。

---

## 接口列表

### 1. 搜索用户

**接口路径**: `GET /api/front/users/search`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```
keyword: 搜索关键词 (昵称或手机号)
page: 页码 (默认1)
pageSize: 每页数量 (默认20)
```

**返回参数**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 用户ID,
        "nickname": "昵称",
        "phone": "手机号",
        "avatarUrl": "头像URL",
        "friendStatus": 0
      }
    ],
    "total": 总数,
    "page": 当前页,
    "limit": 每页数量
  }
}
```

**friendStatus说明**:
- 0: 未添加
- 1: 已是好友
- 2: 已申请

---

### 2. 发送好友申请

**接口路径**: `POST /api/front/friends/request`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "targetUserId": 目标用户ID,
  "message": "申请消息(可选)"
}
```

**返回参数**:
```json
{
  "code": 200,
  "msg": "success",
  "data": true
}
```

---

### 3. 获取好友申请列表

**接口路径**: `GET /api/front/friends/requests`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```
page: 页码 (默认1)
pageSize: 每页数量 (默认20)
```

**返回参数**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 请求ID,
        "from_user_id": 发送者ID,
        "nickname": "发送者昵称",
        "avatarUrl": "头像URL",
        "message": "申请消息",
        "create_time": "创建时间"
      }
    ],
    "total": 总数
  }
}
```

---

### 4. 处理好友请求

**接口路径**: `POST /api/front/friends/requests/{requestId}/handle`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "accept": true
}
```

**accept说明**:
- true: 接受
- false: 拒绝

**返回参数**:
```json
{
  "code": 200,
  "msg": "success",
  "data": true
}
```

**说明**: 接受后自动创建双向好友关系和私聊会话

---

### 5. 获取好友列表

**接口路径**: `GET /api/front/friends`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```
page: 页码 (默认1)
pageSize: 每页数量 (默认20)
```

**返回参数**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 好友ID,
        "name": "昵称",
        "avatarUrl": "头像URL",
        "phone": "手机号",
        "isOnline": 1,
        "lastOnlineTime": "最后在线时间"
      }
    ],
    "total": 总数
  }
}
```

**isOnline说明**:
- 1: 在线
- 0: 离线

---

### 6. 删除好友

**接口路径**: `DELETE /api/front/friends/{friendId}`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```
friendId: 好友ID (路径参数)
```

**返回参数**:
```json
{
  "code": 200,
  "msg": "success",
  "data": true
}
```

**说明**: 删除双向好友关系

---

### 7. 拉黑好友

**接口路径**: `POST /api/front/friends/block/{friendId}`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```
friendId: 好友ID (路径参数)
```

**返回参数**:
```json
{
  "code": 200,
  "msg": "success",
  "data": true
}
```

**说明**: 拉黑后自动删除好友关系，被拉黑用户无法再发送好友申请

---

### 8. 取消拉黑

**接口路径**: `POST /api/front/friends/unblock/{friendId}`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```
friendId: 好友ID (路径参数)
```

**返回参数**:
```json
{
  "code": 200,
  "msg": "success",
  "data": true
}
```

---

### 9. 获取黑名单列表

**接口路径**: `GET /api/front/friends/blocked`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```
page: 页码 (默认1)
pageSize: 每页数量 (默认20)
```

**返回参数**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 用户ID,
        "name": "昵称",
        "avatarUrl": "头像URL",
        "phone": "手机号",
        "blockedTime": "拉黑时间"
      }
    ],
    "total": 总数
  }
}
```