zhibo/模块文档/12-私聊会话模块.md

# 私聊会话模块

## 模块概述
私聊会话模块负责处理用户之间的一对一聊天功能，包括会话管理、消息发送、消息历史等。

## 相关文件
- `MessagesActivity.java` - 会话列表界面
- `ConversationActivity.java` - 聊天界面
- `ConversationsAdapter.java` - 会话列表适配器
- `ConversationMessagesAdapter.java` - 消息列表适配器
- `ConversationResponse.java` - 会话响应模型
- `PrivateMessageResponse.java` - 私聊消息响应模型

---

## 接口列表

### 1. 获取会话列表
**接口地址**: `GET /api/front/conversations`

**请求参数**: 无

**返回数据**:
```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": "long",                    // 会话ID
      "otherUserId": "integer",        // 对方用户ID
      "otherUserNickname": "string",   // 对方昵称
      "otherUserAvatar": "string",     // 对方头像URL
      "lastMessage": "string",         // 最后一条消息内容
      "lastMessageTime": "long",       // 最后消息时间戳
      "unreadCount": "integer",        // 未读消息数
      "isOnline": "boolean"            // 对方是否在线
    }
  ]
}
```

---

### 2. 搜索会话
**接口地址**: `GET /api/front/conversations/search`

**请求参数**:
```
keyword: string    // 搜索关键词（昵称）
```

**返回数据**: 同获取会话列表

---

### 3. 获取或创建会话
**接口地址**: `POST /api/front/conversations/with/{otherUserId}`

**路径参数**:
```
otherUserId: integer    // 对方用户ID
```

**请求参数**: 无

**返回数据**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "conversationId": "long",    // 会话ID
    "created": "boolean"         // 是否新创建
  }
}
```

---

### 4. 标记会话已读
**接口地址**: `POST /api/front/conversations/{id}/read`

**路径参数**:
```
id: long    // 会话ID
```

**请求参数**: 无

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

---

### 5. 删除会话
**接口地址**: `DELETE /api/front/conversations/{id}`

**路径参数**:
```
id: long    // 会话ID
```

**请求参数**: 无

**返回数据**:
```json
{
  "code": 200,
  "msg": "删除成功",
  "data": true
}
```

---

### 6. 获取会话消息列表
**接口地址**: `GET /api/front/conversations/{id}/messages`

**路径参数**:
```
id: long    // 会话ID
```

**请求参数**:
```
page: integer        // 页码，默认1
pageSize: integer    // 每页数量，默认20
```

**返回数据**:
```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": "long",              // 消息ID
      "conversationId": "long",  // 会话ID
      "senderId": "integer",     // 发送者ID
      "senderNickname": "string",// 发送者昵称
      "senderAvatar": "string",  // 发送者头像
      "content": "string",       // 消息内容
      "messageType": "string",   // 消息类型: text/image/voice
      "mediaUrl": "string",      // 媒体文件URL（图片/语音）
      "duration": "integer",     // 语音时长（秒）
      "isRead": "boolean",       // 是否已读
      "createTime": "long"       // 发送时间戳
    }
  ]
}
```

---

### 7. 发送私聊消息
**接口地址**: `POST /api/front/conversations/{id}/messages`

**路径参数**:
```
id: long    // 会话ID
```

**请求参数** (SendMessageRequest):
```json
{
  "content": "string",       // 消息内容
  "messageType": "string",   // 消息类型: text/image/voice
  "mediaUrl": "string",      // 媒体文件URL（可选）
  "duration": "integer"      // 语音时长（可选）
}
```

**返回数据** (PrivateMessageResponse):
```json
{
  "code": 200,
  "msg": "发送成功",
  "data": {
    "id": "long",              // 消息ID
    "conversationId": "long",  // 会话ID
    "senderId": "integer",     // 发送者ID
    "senderNickname": "string",// 发送者昵称
    "senderAvatar": "string",  // 发送者头像
    "content": "string",       // 消息内容
    "messageType": "string",   // 消息类型
    "mediaUrl": "string",      // 媒体文件URL
    "duration": "integer",     // 语音时长
    "isRead": "boolean",       // 是否已读
    "createTime": "long"       // 发送时间戳
  }
}
```

---

### 8. 删除消息
**接口地址**: `DELETE /api/front/conversations/messages/{id}`

**路径参数**:
```
id: long    // 消息ID
```

**请求参数**: 无

**返回数据**:
```json
{
  "code": 200,
  "msg": "删除成功",
  "data": true
}
```

---

## 功能说明

### 会话管理
- 会话列表按最后消息时间倒序排列
- 显示未读消息数量
- 支持搜索会话（按对方昵称）
- 支持删除会话

### 消息发送
- 支持文本消息
- 支持图片消息（需先上传图片获取URL）
- 支持语音消息（需先上传语音获取URL）
- 消息实时推送（通过WebSocket）

### 消息状态
- 已读/未读状态
- 消息发送时间
- 消息类型标识

---

## 消息类型说明

| 类型 | 值 | 说明 |
|------|-----|------|
| 文本消息 | text | 普通文字消息 |
| 图片消息 | image | 图片消息，需要mediaUrl |
| 语音消息 | voice | 语音消息，需要mediaUrl和duration |

---

## 使用流程

### 发送文本消息
1. 进入会话界面
2. 输入文本内容
3. 调用发送消息接口
4. 消息通过WebSocket实时推送给对方

### 发送图片消息
1. 选择图片
2. 调用文件上传接口获取URL
3. 调用发送消息接口，messageType为image，mediaUrl为上传返回的URL
4. 消息通过WebSocket实时推送给对方

### 发送语音消息
1. 录制语音
2. 调用文件上传接口获取URL
3. 调用发送消息接口，messageType为voice，mediaUrl为上传返回的URL，duration为语音时长
4. 消息通过WebSocket实时推送给对方

---

## 注意事项
1. 所有接口都需要登录认证
2. 图片和语音消息需要先上传文件获取URL
3. 消息列表支持分页加载
4. 建议配合WebSocket实现实时消息推送
5. 删除会话不会删除消息记录，只是隐藏会话