xiaozhang/zhibo
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
721d588971
zhibo/Zhibo/zhibo-h/消息转发模块快速参考.md

11 KiB
Raw Blame History

消息转发模块快速参考

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

📋 API接口清单

1. 转发消息给好友

POST /api/front/messages/forward/friend

需要登录: ✅ 是

请求参数:

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

响应示例:

{
  "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. 转发消息到群组

POST /api/front/messages/forward/group

需要登录: ✅ 是

请求参数:

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

响应示例:

{
  "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. 批量转发消息

POST /api/front/messages/forward/batch

需要登录: ✅ 是

请求参数:

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

请求示例:

{
  "targetIds": [101, 102, 103, 104, 105]
}

响应示例:

{
  "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. 获取转发历史记录

GET /api/front/messages/forward/history

需要登录: ✅ 是

请求参数:

参数名 类型 必填 默认值 说明
page Integer 否 1 页码
pageSize Integer 否 20 每页数量

响应示例:

{
  "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. 删除转发记录

DELETE /api/front/messages/forward/{forwardId}

需要登录: ✅ 是

路径参数:

参数名 类型 必填 说明
forwardId Long 是 转发记录ID

响应示例:

{
  "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: 转发私聊消息给好友

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

场景2: 转发群组消息到另一个群

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

场景3: 批量转发消息给多个好友

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

场景4: 查看转发历史

// 用户想查看自己的转发记录
GET /api/front/messages/forward/history?page=1&pageSize=20

场景5: 删除转发记录

// 用户想删除某条转发记录
DELETE /api/front/messages/forward/123

⚠️ 错误码说明

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

🔧 扩展字段使用示例

ext_field1: 转发来源/渠道

forward.setExtField1("from_private_chat"); // 从私聊转发
forward.setExtField1("from_group_chat");   // 从群聊转发
forward.setExtField1("from_live_room");    // 从直播间转发

ext_field2: 转发优先级/标记

forward.setExtField2(1); // 普通转发
forward.setExtField2(2); // 重要转发
forward.setExtField2(3); // 紧急转发

ext_field3: 转发状态/类型

forward.setExtField3("normal");    // 普通转发
forward.setExtField3("urgent");    // 紧急转发
forward.setExtField3("scheduled"); // 定时转发

ext_field4: 关联数据ID

forward.setExtField4(12345L); // 关联的活动ID
forward.setExtField4(67890L); // 关联的任务ID

ext_field5: JSON扩展数据

String jsonData = "{\"tags\":[\"工作\",\"重要\"],\"metadata\":{\"priority\":\"high\"}}";
forward.setExtField5(jsonData);

📝 注意事项

1. 权限验证

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

2. 消息内容

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

3. 逻辑删除

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

4. 批量转发

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

5. 性能优化

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

🚀 快速开始

1. 前端调用示例（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）

// 转发消息给好友
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日
维护状态: ✅ 活跃维护中