zhibo/android-app/接口文档.md

# 直播APP接口文档

> 后端服务地址: `http://localhost:8081`  
> 所有接口需要在Header中携带 `Authori-zation: {token}` (登录后获取)

---

## 一、用户认证

### 1.1 账号密码登录
- **POST** `/api/front/login`
- **请求体**:
```json
{
  "account": "手机号",
  "password": "密码"
}
```
- **响应**: `token`, `uid`, `nikeName`, `phone`

### 1.2 用户注册
- **POST** `/api/front/register`
- **请求体**:
```json
{
  "phone": "手机号",
  "password": "密码",
  "verificationCode": "验证码",
  "nickname": "昵称"
}
```

### 1.3 发送验证码
- **POST** `/api/front/sendCode`
- **参数**: `phone` (表单)

### 1.4 退出登录
- **GET** `/api/front/logout`

---

## 二、用户信息

### 2.1 获取用户信息
- **GET** `/api/front/user`
- **响应**: `nickname`, `avatar`, `phone`, `nowMoney`, `integral`, `level`, `vip` 等

### 2.2 修改用户资料
- **POST** `/api/front/user/edit`
- **请求体**:
```json
{
  "nickname": "昵称",
  "avatar": "头像URL"
}
```

---

## 三、直播间

### 3.1 获取直播间列表
- **GET** `/api/front/live/public/rooms`
- **响应**: 直播中的房间列表

### 3.2 创建直播间
- **POST** `/api/front/live/rooms`
- **请求体**:
```json
{
  "title": "直播标题",
  "streamerName": "主播名称"
}
```
- **响应**: 房间信息 + 推流地址

### 3.3 获取直播间详情
- **GET** `/api/front/live/public/rooms/{id}`

### 3.4 删除直播间
- **DELETE** `/api/front/live/rooms/{id}`

### 3.5 获取观看人数
- **GET** `/api/front/live/public/rooms/{roomId}/viewers/count`

### 3.6 关注/取消关注主播
- **POST** `/api/front/live/follow`
- **请求体**:
```json
{
  "streamerId": 123,
  "action": "follow"
}
```
> action 可选值: "follow" 或 "unfollow"

---

## 四、直播弹幕

### 4.1 获取弹幕消息
- **GET** `/api/front/live/public/rooms/{roomId}/messages`
- **参数**: `limit` (数量限制)

### 4.2 发送弹幕
- **POST** `/api/front/live/public/rooms/{roomId}/messages`
- **请求体**:
```json
{
  "message": "弹幕内容",
  "visitorId": "访客ID",
  "nickname": "昵称"
}
```

---

## 五、礼物打赏

### 5.1 获取礼物列表
- **GET** `/api/front/gift/list`
- **响应**: `id`, `name`, `price`, `iconUrl`, `description`, `level`

### 5.2 获取用户余额
- **GET** `/api/front/gift/balance`
- **响应**: `coinBalance`

### 5.3 赠送礼物
- **POST** `/api/front/gift/send`
- **请求体**:
```json
{
  "giftId": 1,
  "streamerId": 123,
  "count": 1
}
```
- **响应**: `success`, `newBalance`, `message`

### 5.4 获取充值选项
- **GET** `/api/front/gift/recharge/options`
- **响应**: `id`, `coinAmount`, `price`, `discountLabel`

### 5.5 创建充值订单
- **POST** `/api/front/gift/recharge/create`
- **请求体**:
```json
{
  "optionId": 1,
  "coinAmount": 100,
  "price": 10.00
}
```
- **响应**: `orderId`, `paymentUrl`

---

## 六、私聊会话

### 6.1 获取会话列表
- **GET** `/api/front/conversations`
- **响应**: `id`, `title`, `lastMessage`, `timeText`, `unreadCount`, `avatarUrl`, `otherUserId`

### 6.2 搜索会话
- **GET** `/api/front/conversations/search`
- **参数**: `keyword`

### 6.3 获取/创建会话
- **POST** `/api/front/conversations/with/{otherUserId}`
- **响应**: `conversationId`

### 6.4 标记会话已读
- **POST** `/api/front/conversations/{id}/read`

### 6.5 删除会话
- **DELETE** `/api/front/conversations/{id}`

### 6.6 获取消息列表
- **GET** `/api/front/conversations/{id}/messages`
- **参数**: `page`, `pageSize`
- **响应**: `messageId`, `userId`, `username`, `avatarUrl`, `message`, `timestamp`, `status`

### 6.7 发送私信
- **POST** `/api/front/conversations/{id}/messages`
- **请求体**:
```json
{
  "message": "消息内容",
  "messageType": "text"
}
```

### 6.8 删除消息
- **DELETE** `/api/front/conversations/messages/{id}`

---

## 七、好友管理

### 7.1 获取好友列表
- **GET** `/api/front/friends`
- **参数**: `page`, `pageSize`
- **响应**: `id`, `name`, `avatarUrl`, `phone`, `isOnline`, `lastOnlineTime`

### 7.2 删除好友
- **DELETE** `/api/front/friends/{friendId}`

### 7.3 搜索用户
- **GET** `/api/front/users/search`
- **参数**: `keyword`, `page`, `pageSize`
- **响应**: `id`, `nickname`, `phone`, `avatarUrl`, `friendStatus` (0=未添加, 1=已是好友, 2=已申请)

### 7.4 发送好友请求
- **POST** `/api/front/friends/request`
- **请求体**:
```json
{
  "targetUserId": 123,
  "message": "请求消息"
}
```

### 7.5 获取好友请求列表
- **GET** `/api/front/friends/requests`
- **参数**: `page`, `pageSize`

### 7.6 处理好友请求
- **POST** `/api/front/friends/requests/{requestId}/handle`
- **请求体**:
```json
{
  "accept": true
}
```

---

## 八、文件上传

### 8.1 上传图片
- **POST** `/api/front/user/upload/image`
- **参数**: 
  - `multipart` - 图片文件
  - `model` - 模块 (user/product/wechat/news)
  - `pid` - 分类ID (7=前台用户头像)
- **响应**: `url`, `fileName`, `type`

---

## 九、在线状态

### 9.1 检查用户在线状态
- **GET** `/api/front/online/status/{userId}`
- **响应**: `userId`, `online`, `lastActiveTime`

### 9.2 批量检查在线状态
- **POST** `/api/front/online/status/batch`
- **请求体**: `[userId1, userId2, ...]`
- **响应**: `total`, `onlineCount`, `onlineUsers`

### 9.3 获取直播间在线人数
- **GET** `/api/front/online/room/{roomId}/count`
- **响应**: `roomId`, `count`

### 9.4 获取直播间在线用户列表
- **GET** `/api/front/online/room/{roomId}/users`
- **响应**: `roomId`, `count`, `users`

### 9.5 获取WebSocket连接统计
- **GET** `/api/front/online/stats`
- **响应**: `activeConnections`, `timestamp`

---

## 十、离线消息

### 10.1 获取离线消息数量
- **GET** `/api/front/online/offline/count/{userId}`
- **响应**: `userId`, `count`

### 10.2 获取离线消息列表
- **GET** `/api/front/online/offline/messages/{userId}`
- **参数**: `limit` (默认50)
- **响应**: `userId`, `messages`, `count`, `totalCount`

### 10.3 清除离线消息
- **DELETE** `/api/front/online/offline/messages/{userId}`

---

## 接口统计

| 模块 | 接口数量 |
|------|----------|
| 用户认证 | 4 |
| 用户信息 | 2 |
| 直播间 | 6 |
| 直播弹幕 | 2 |
| 礼物打赏 | 5 |
| 私聊会话 | 8 |
| 好友管理 | 6 |
| 文件上传 | 1 |
| 在线状态 | 5 |
| 离线消息 | 3 |
| **总计** | **42** |