# 消息转发模块快速参考

> **模块**: 消息转发模块（模块13）  
> **状态**: ✅ 已完成  
> **更新时间**: 2024年12月26日

---

## 📋 API接口清单

### 1. 转发消息给好友
```http
POST /api/front/messages/forward/friend
```

**需要登录**: ✅ 是

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| originalMessageId | Long | 是 | 原始消息ID |
| originalMessageType | String | 是 | 原始消息类型（private/group）|
| targetUserId | Integer | 是 | 目标好友ID |
| forwardComment | String | 否 | 转发时的附加消息 |

**响应示例**:
```json
{
  "code": 200,
  "message": "转发成功",
  "data": {
    "id": 1,
    "userId": 123,
    "originalMessageId": 456,
    "originalMessageType": "private",
    "targetType": "friend",
    "targetId": 789,
    "newMessageId": 1001,
    "forwardComment": "分享给你看看",
    "isDeleted": false,
    "createTime": "2024-12-26 10:00:00",
    "updateTime": "2024-12-26 10:00:00"
  }
}
```

---

### 2. 转发消息到群组
```http
POST /api/front/messages/forward/group
```

**需要登录**: ✅ 是

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| originalMessageId | Long | 是 | 原始消息ID |
| originalMessageType | String | 是 | 原始消息类型（private/group）|
| targetGroupId | Long | 是 | 目标群组ID |
| forwardComment | String | 否 | 转发时的附加消息 |

**响应示例**:
```json
{
  "code": 200,
  "message": "转发成功",
  "data": {
    "id": 2,
    "userId": 123,
    "originalMessageId": 456,
    "originalMessageType": "private",
    "targetType": "group",
    "targetId": 888,
    "newMessageId": 1002,
    "forwardComment": "大家看看这个",
    "isDeleted": false,
    "createTime": "2024-12-26 10:05:00",
    "updateTime": "2024-12-26 10:05:00"
  }
}
```

---

### 3. 批量转发消息
```http
POST /api/front/messages/forward/batch
```

**需要登录**: ✅ 是

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| originalMessageId | Long | 是 | 原始消息ID |
| originalMessageType | String | 是 | 原始消息类型（private/group）|
| targetType | String | 是 | 目标类型（friend/group）|
| targetIds | List<Long> | 是 | 目标ID列表（Body JSON）|
| forwardComment | String | 否 | 转发时的附加消息 |

**请求示例**:
```json
{
  "targetIds": [101, 102, 103, 104, 105]
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "批量转发完成，成功：5，失败：0",
  "data": [
    {
      "id": 3,
      "userId": 123,
      "targetType": "friend",
      "targetId": 101,
      "newMessageId": 1003
    },
    {
      "id": 4,
      "userId": 123,
      "targetType": "friend",
      "targetId": 102,
      "newMessageId": 1004
    }
    // ... 更多记录
  ]
}
```

---

### 4. 获取转发历史记录
```http
GET /api/front/messages/forward/history
```

**需要登录**: ✅ 是

**请求参数**:
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| page | Integer | 否 | 1 | 页码 |
| pageSize | Integer | 否 | 20 | 每页数量 |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "userId": 123,
      "originalMessageId": 456,
      "originalMessageType": "private",
      "targetType": "friend",
      "targetId": 789,
      "newMessageId": 1001,
      "forwardComment": "分享给你看看",
      "isDeleted": false,
      "createTime": "2024-12-26 10:00:00",
      "updateTime": "2024-12-26 10:00:00"
    }
    // ... 更多记录
  ]
}
```

---

### 5. 删除转发记录
```http
DELETE /api/front/messages/forward/{forwardId}
```

**需要登录**: ✅ 是

**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| forwardId | Long | 是 | 转发记录ID |

**响应示例**:
```json
{
  "code": 200,
  "message": "删除成功",
  "data": true
}
```

---

## 🔐 权限验证规则

### 转发消息给好友
- ✅ 必须登录
- ✅ 必须是原始消息的发送者或接收者
- ✅ 目标用户必须是好友

### 转发消息到群组
- ✅ 必须登录
- ✅ 必须是原始消息的发送者或接收者
- ✅ 必须是目标群组的成员

### 批量转发
- ✅ 必须登录
- ✅ 必须是原始消息的发送者或接收者
- ✅ 每个目标都需要满足相应的权限要求

### 查看转发历史
- ✅ 必须登录
- ✅ 只能查看自己的转发记录

### 删除转发记录
- ✅ 必须登录
- ✅ 只能删除自己的转发记录

---

## 💾 数据库表结构

### 表名: eb_message_forward

| 字段名 | 类型 | 说明 | 索引 |
|--------|------|------|------|
| id | BIGINT | 转发记录ID（主键）| PRIMARY |
| user_id | INT | 转发用户ID | idx_user_id |
| original_message_id | BIGINT | 原始消息ID | idx_original_message_id |
| original_message_type | VARCHAR(20) | 原始消息类型 | idx_target_type |
| target_type | VARCHAR(20) | 转发目标类型 | - |
| target_id | BIGINT | 转发目标ID | idx_target_id |
| new_message_id | BIGINT | 新消息ID | - |
| forward_comment | VARCHAR(500) | 转发时的附加消息 | - |
| is_deleted | TINYINT(1) | 是否删除 | idx_deleted |
| create_time | DATETIME | 创建时间 | idx_create_time |
| update_time | DATETIME | 更新时间 | - |
| ext_field1 | VARCHAR(100) | 扩展字段1 | - |
| ext_field2 | INT | 扩展字段2 | - |
| ext_field3 | VARCHAR(50) | 扩展字段3 | - |
| ext_field4 | BIGINT | 扩展字段4 | - |
| ext_field5 | TEXT | 扩展字段5 | - |

---

## 🎯 使用场景

### 场景1: 转发私聊消息给好友
```java
// 用户A收到用户B的消息，想转发给用户C
POST /api/front/messages/forward/friend
{
  "originalMessageId": 123,
  "originalMessageType": "private",
  "targetUserId": 456,
  "forwardComment": "这个消息很重要，分享给你"
}
```

### 场景2: 转发群组消息到另一个群
```java
// 用户在群A看到一条消息，想转发到群B
POST /api/front/messages/forward/group
{
  "originalMessageId": 789,
  "originalMessageType": "group",
  "targetGroupId": 999,
  "forwardComment": "大家看看这个"
}
```

### 场景3: 批量转发消息给多个好友
```java
// 用户想把一条消息同时转发给多个好友
POST /api/front/messages/forward/batch
{
  "originalMessageId": 123,
  "originalMessageType": "private",
  "targetType": "friend",
  "targetIds": [101, 102, 103, 104, 105],
  "forwardComment": "分享给大家"
}
```

### 场景4: 查看转发历史
```java
// 用户想查看自己的转发记录
GET /api/front/messages/forward/history?page=1&pageSize=20
```

### 场景5: 删除转发记录
```java
// 用户想删除某条转发记录
DELETE /api/front/messages/forward/123
```

---

## ⚠️ 错误码说明

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 401 | 用户未登录 | 需要先登录 |
| 403 | 对方不是您的好友 | 转发目标不是好友 |
| 403 | 您不是该群组成员 | 不是目标群组成员 |
| 404 | 原始消息不存在或无权访问 | 消息不存在或无权限 |
| 403 | 无权删除此转发记录 | 只能删除自己的记录 |
| 404 | 转发记录不存在 | 记录已被删除或不存在 |

---

## 🔧 扩展字段使用示例

### ext_field1: 转发来源/渠道
```java
forward.setExtField1("from_private_chat"); // 从私聊转发
forward.setExtField1("from_group_chat");   // 从群聊转发
forward.setExtField1("from_live_room");    // 从直播间转发
```

### ext_field2: 转发优先级/标记
```java
forward.setExtField2(1); // 普通转发
forward.setExtField2(2); // 重要转发
forward.setExtField2(3); // 紧急转发
```

### ext_field3: 转发状态/类型
```java
forward.setExtField3("normal");    // 普通转发
forward.setExtField3("urgent");    // 紧急转发
forward.setExtField3("scheduled"); // 定时转发
```

### ext_field4: 关联数据ID
```java
forward.setExtField4(12345L); // 关联的活动ID
forward.setExtField4(67890L); // 关联的任务ID
```

### ext_field5: JSON扩展数据
```java
String jsonData = "{\"tags\":[\"工作\",\"重要\"],\"metadata\":{\"priority\":\"high\"}}";
forward.setExtField5(jsonData);
```

---

## 📝 注意事项

### 1. 权限验证
- 转发消息前会验证用户是否有权访问原始消息
- 转发给好友前会验证好友关系
- 转发到群组前会验证群组成员身份

### 2. 消息内容
- 转发的消息会自动添加`[转发消息]`标记
- 如果提供了`forwardComment`，会添加在消息前面
- 转发后的消息类型与原始消息类型相同

### 3. 逻辑删除
- 删除转发记录使用逻辑删除（is_deleted=1）
- 已删除的记录不会在查询中返回
- 数据不会真正从数据库中删除，可以恢复

### 4. 批量转发
- 批量转发时，部分失败不会影响其他转发
- 返回结果中包含成功和失败的数量
- 失败的转发会记录日志，但不会抛出异常

### 5. 性能优化
- 转发历史记录支持分页查询
- 数据库表添加了索引，提升查询性能
- 批量转发建议一次不超过50个目标

---

## 🚀 快速开始

### 1. 前端调用示例（JavaScript）
```javascript
// 转发消息给好友
async function forwardToFriend(messageId, messageType, targetUserId, comment) {
  const response = await fetch('/api/front/messages/forward/friend', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': 'Bearer ' + token
    },
    body: new URLSearchParams({
      originalMessageId: messageId,
      originalMessageType: messageType,
      targetUserId: targetUserId,
      forwardComment: comment || ''
    })
  });
  return await response.json();
}

// 批量转发
async function batchForward(messageId, messageType, targetType, targetIds, comment) {
  const response = await fetch('/api/front/messages/forward/batch', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + token
    },
    body: JSON.stringify({
      originalMessageId: messageId,
      originalMessageType: messageType,
      targetType: targetType,
      targetIds: targetIds,
      forwardComment: comment || ''
    })
  });
  return await response.json();
}
```

### 2. Android调用示例（Kotlin）
```kotlin
// 转发消息给好友
suspend fun forwardToFriend(
    messageId: Long,
    messageType: String,
    targetUserId: Int,
    comment: String?
): Result<MessageForward> {
    return apiService.forwardToFriend(
        originalMessageId = messageId,
        originalMessageType = messageType,
        targetUserId = targetUserId,
        forwardComment = comment
    )
}

// 批量转发
suspend fun batchForward(
    messageId: Long,
    messageType: String,
    targetType: String,
    targetIds: List<Long>,
    comment: String?
): Result<List<MessageForward>> {
    return apiService.batchForward(
        originalMessageId = messageId,
        originalMessageType = messageType,
        targetType = targetType,
        targetIds = targetIds,
        forwardComment = comment
    )
}
```

---

## 📚 相关文档

- **开发指南**: `直播IM系统开发指南.md` - 模块13
- **完善总结**: `消息转发模块完善总结.md`
- **API文档**: Swagger UI - `/api/front/messages/forward/**`

---

**更新时间**: 2024年12月26日  
**维护状态**: ✅ 活跃维护中