zhibo/android-app/后端接口TODO清单-快速参考.md

# 后端接口 TODO 清单 - 快速参考

## 📊 接口统计

| 模块 | 接口数量 | 优先级 | 状态 |
|------|---------|--------|------|
| 用户认证 | 3 | ⭐⭐⭐⭐⭐ | 待开发 |
| 用户资料 | 4 | ⭐⭐⭐⭐⭐ | 待开发 |
| 用户头像 | 3 | ⭐⭐⭐⭐ | 待开发 |
| 直播间 | 5 | ⭐⭐⭐⭐⭐ | 待开发 |
| 消息聊天 | 8 | ⭐⭐⭐⭐ | 待开发 |
| 消息发送 | 3 | ⭐⭐⭐⭐ | 待开发 |
| 直播间弹幕 | 3 | ⭐⭐⭐⭐ | 待开发 |
| 礼物打赏 | 5 | ⭐⭐⭐ | 待开发 |
| 作品管理 | 10 | ⭐⭐⭐ | 待开发 |
| 评论功能 | 4 | ⭐⭐⭐ | 待开发 |
| 社交功能 | 8 | ⭐⭐⭐⭐ | 待开发 |
| 搜索功能 | 6 | ⭐⭐⭐ | 待开发 |
| 分类管理 | 3 | ⭐⭐⭐⭐ | 待开发 |
| 图片上传 | 5 | ⭐⭐⭐⭐ | 待开发 |
| 通知推送 | 4 | ⭐⭐⭐ | 待开发 |
| 支付集成 | 4 | ⭐⭐⭐ | 待开发 |
| 其他功能 | 10 | ⭐⭐ | 待开发 |

**总计**: 88 个接口

## 🚀 核心接口（必须优先实现）

### 1. 用户系统（7个接口）
- `POST /api/front/login` - 用户登录
- `POST /api/front/register` - 用户注册
- `POST /api/sms/send` - 发送验证码
- `GET /api/users/{userId}/profile` - 获取用户资料
- `PUT /api/users/{userId}/profile` - 更新用户资料
- `POST /api/upload/avatar` - 上传头像
- `GET /api/users/{userId}/avatar` - 获取用户头像

### 2. 直播间系统（8个接口）
- `GET /api/rooms` - 获取直播间列表
- `GET /api/rooms/{roomId}` - 获取直播间详情
- `POST /api/rooms` - 创建直播间
- `DELETE /api/rooms/{roomId}` - 删除直播间
- `GET /api/rooms/{roomId}/viewers/count` - 获取观看人数
- `GET /api/rooms/categories` - 获取分类列表
- `GET /api/rooms?category={categoryId}` - 按分类获取房间
- `POST /api/watch/history` - 记录观看历史

### 3. 消息系统（11个接口）
- `GET /api/conversations` - 获取会话列表
- `GET /api/conversations/{conversationId}/messages` - 获取消息列表
- `POST /api/conversations/{conversationId}/messages` - 发送消息
- `POST /api/conversations/{conversationId}/read` - 标记已读
- `DELETE /api/conversations/{conversationId}` - 删除会话
- `DELETE /api/messages/{messageId}` - 删除消息
- `GET /api/messages/unread/count` - 获取未读数量
- `POST /api/messages/send` - 发送文本消息
- `POST /api/messages/send/image` - 发送图片消息
- `POST /api/messages/send/voice` - 发送语音消息
- `GET /api/conversations/search` - 搜索会话

### 4. 直播间弹幕（3个接口 + WebSocket）
- `POST /api/rooms/{roomId}/messages` - 发送弹幕
- `GET /api/rooms/{roomId}/messages` - 获取历史弹幕
- `WebSocket: ws://api.example.com/rooms/{roomId}/chat` - 实时弹幕

## 📝 WebSocket 连接清单

| 功能 | WebSocket URL | 用途 |
|------|--------------|------|
| 直播间弹幕 | `ws://api/rooms/{roomId}/chat` | 实时接收弹幕消息 |
| 私信消息 | `ws://api/conversations/{conversationId}` | 实时接收私信和已读状态 |
| 通知推送 | `ws://api/notifications` | 实时接收通知 |

## 📤 文件上传接口清单

| 接口 | 用途 | 文件类型 | 大小限制 |
|------|------|---------|---------|
| `POST /api/upload/avatar` | 上传头像 | JPG/PNG | 5MB |
| `POST /api/upload/work/image` | 上传作品图片 | JPG/PNG/GIF | 10MB |
| `POST /api/upload/work/video` | 上传作品视频 | MP4/MOV | 500MB |
| `POST /api/upload/chat/image` | 上传聊天图片 | JPG/PNG | 10MB |
| `POST /api/upload/chat/voice` | 上传语音消息 | MP3/AAC | 10MB |

## 🔐 需要登录的接口

以下接口需要在请求头中携带 token：
```
Authorization: Bearer {token}
```

### 必须登录
- 所有 `POST/PUT/DELETE` 接口
- 个人资料相关接口
- 消息相关接口
- 作品管理接口
- 关注/粉丝接口
- 礼物打赏接口

### 可选登录（登录后返回个性化内容）
- `GET /api/rooms` - 直播间列表
- `GET /api/search` - 搜索
- `GET /api/recommend` - 推荐内容

## 💰 支付相关接口

| 接口 | 用途 | 说明 |
|------|------|------|
| `POST /api/payment/create` | 创建支付订单 | 返回支付参数 |
| `GET /api/payment/status/{orderId}` | 查询支付状态 | 轮询确认支付 |
| `POST /api/payment/callback/wechat` | 微信支付回调 | 由微信服务器调用 |
| `POST /api/payment/callback/alipay` | 支付宝支付回调 | 由支付宝服务器调用 |

## 📱 需要集成的第三方SDK

### 1. 支付SDK
- 微信支付 SDK: `com.tencent.mm.opensdk:wechat-sdk-android:6.8.0`
- 支付宝 SDK: `com.alipay.sdk:alipaysdk-android:15.8.11`

### 2. 推送SDK
- Firebase Cloud Messaging (FCM)
- 或其他推送服务（极光推送、个推等）

### 3. 直播推流SDK（可选）
- 如果需要从手机推流，需要集成推流SDK
- 推荐: yasea, LiveVideoBroadcaster

## ⚠️ 重要提示

### 数据格式统一
所有接口返回格式：
```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

### 分页参数统一
- `page`: 页码（从1开始）
- `pageSize`: 每页数量（默认20）

### 错误码统一
- 200: 成功
- 400: 请求参数错误
- 401: 未登录或token过期
- 403: 无权限
- 404: 资源不存在
- 500: 服务器错误

### 时间戳格式
- 统一使用毫秒级时间戳（13位）
- 例如: `1703145600000`

### 图片URL格式
- 返回完整的URL地址
- 例如: `https://cdn.example.com/images/avatar.jpg`
- 支持HTTPS协议

## 📋 开发检查清单

### 第一阶段（核心功能）
- [ ] 用户登录/注册
- [ ] 获取直播间列表
- [ ] 获取直播间详情
- [ ] 创建直播间
- [ ] 获取用户资料
- [ ] 更新用户资料
- [ ] 上传头像

### 第二阶段（社交功能）
- [ ] 获取会话列表
- [ ] 发送私信消息
- [ ] 发送直播间弹幕
- [ ] WebSocket 实时消息
- [ ] 关注/取消关注
- [ ] 获取关注/粉丝列表

### 第三阶段（增值功能）
- [ ] 礼物列表
- [ ] 赠送礼物
- [ ] 充值接口
- [ ] 支付集成
- [ ] 发布作品
- [ ] 作品列表

### 第四阶段（辅助功能）
- [ ] 搜索功能
- [ ] 通知列表
- [ ] 推送集成
- [ ] 观看历史
- [ ] 分类管理

## 🔗 相关文档

- [总览文档](./后端接口TODO清单-总览.md)
- [用户认证模块](./后端接口TODO清单-用户认证.md)
- [直播间模块](./后端接口TODO清单-直播间.md)
- [消息聊天模块](./后端接口TODO清单-消息聊天.md)
- [支付集成模块](./后端接口TODO清单-支付集成.md)

---

**最后更新**: 2024年12月24日