472 lines
11 KiB
Markdown
472 lines
11 KiB
Markdown
# 消息转发模块快速参考
|
||
|
||
> **模块**: 消息转发模块（模块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日
|
||
**维护状态**: ✅ 活跃维护中
|