urbanLifeline/urbanLifelineServ/apis/api-message/消息系统设计说明.md

消息系统设计说明

📊 数据表结构

1. tb_message - 消息主表

存储消息的基本信息

主要字段：

• message_id - 消息ID（主键）
• title - 消息标题
• content - 消息内容
• type - 消息类型
• status - 消息状态

2. tb_message_range - 消息发送范围定义表

定义消息要发送给哪些对象，通过什么渠道

主要字段：

• message_id - 消息ID
• target_type - 目标类型（user/dept/role/all）
• target_id - 目标ID（用户、部门、角色ID等）
• channel - 发送渠道（app/sms/email/wechat等）
• 唯一约束： (message_id, target_type, target_id, channel)

使用示例：

• 发送给部门001，通过app：{target_type: 'dept', target_id: 'D001', channel: 'app'}
• 发送给部门001，通过sms：{target_type: 'dept', target_id: 'D001', channel: 'sms'}
• 发送给全员，通过app：{target_type: 'all', target_id: null, channel: 'app'}

3. tb_message_receiver - 用户消息接收记录表

记录每个用户实际收到的消息及处理状态

主要字段：

• message_id - 消息ID
• user_id - 用户ID
• channel - 接收渠道
• status - 消息状态（unread/read/handled/deleted）
• read_time - 阅读时间
• handle_time - 处理时间
• 唯一约束： (message_id, user_id, channel)

索引：

• idx_message_user_user_status - 快速查询用户消息列表
• idx_message_user_message - 快速查询消息的接收情况

4. tb_message_channel - 消息渠道配置表

管理各种消息发送渠道的配置

主要字段：

• channel_id - 渠道ID（主键）
• channel_code - 渠道编码（app/sms/email/wechat/dingtalk）
• channel_name - 渠道名称
• config - 渠道配置（JSON格式，存储API密钥等）
• status - 渠道状态（enabled/disabled/maintenance）
• priority - 优先级

预置渠道：

• app - 应用内消息（已启用）
• sms - 短信通知（已禁用）
• email - 邮件通知（已禁用）
• wechat - 微信通知（已禁用）
• dingtalk - 钉钉通知（已禁用）

📦 DTO/VO 结构

TbMessageDTO

消息基本信息DTO

字段：

• messageId
• title
• content
• type
• status

TbMessageRangeDTO

消息发送范围DTO

字段：

• messageId
• targetType - 目标类型
• targetId - 目标ID
• channel - 发送渠道

TbMessageReceiverDTO

用户消息接收记录DTO

字段：

• messageId
• userId
• channel
• status
• readTime
• handleTime

TbMessageChannelDTO

消息渠道配置DTO

字段：

• channelId
• channelCode
• channelName
• channelDesc
• config
• status
• priority

MessageVO

消息视图对象（用于创建和查看消息）

字段：

• messageId
• title
• content
• type
• status
• createTime
• creator
• messageRanges - 消息发送范围列表
• messageReceivers - 消息接收记录列表（管理员查看时使用）

🔄 业务流程

1. 创建并发送消息

// 创建消息
MessageVO messageVO = new MessageVO();
messageVO.setTitle("系统维护通知");
messageVO.setContent("系统将于今晚22:00进行维护");
messageVO.setType("notice");

// 定义发送范围（发给IT部门，通过app和email）
List<TbMessageRangeDTO> ranges = new ArrayList<>();
ranges.add(new TbMessageRangeDTO() {{
    setTargetType("dept");
    setTargetId("DEPT_IT");
    setChannel("app");
}});
ranges.add(new TbMessageRangeDTO() {{
    setTargetType("dept");
    setTargetId("DEPT_IT");
    setChannel("email");
}});
messageVO.setMessageRanges(ranges);

// 发送消息
messageService.sendMessage(messageVO);

系统处理：

1. 在 tb_message 中创建消息记录
2. 在 tb_message_range 中保存发送范围
3. 根据 target_type 和 target_id 查询具体用户列表
4. 在 tb_message_receiver 中为每个用户创建接收记录
5. 根据 channel 调用相应的渠道服务发送消息

2. 用户查看消息列表

-- 查询用户未读消息
SELECT m.*, r.status, r.read_time, r.channel
FROM message.tb_message m
JOIN message.tb_message_receiver r ON m.message_id = r.message_id
WHERE r.user_id = 'USER_001' 
  AND r.status = 'unread'
  AND r.deleted = false
ORDER BY m.create_time DESC;

3. 用户处理消息

// 标记消息为已读
messageService.handleMessage(messageId, "read");

// 标记消息为已处理
messageService.handleMessage(messageId, "handled");

系统处理：

• 更新 tb_message_receiver 表的 status 字段
• 根据状态更新 read_time 或 handle_time

4. 管理员查看消息统计

-- 查询某条消息的发送统计
SELECT 
    r.channel,
    r.status,
    COUNT(*) as count
FROM message.tb_message_receiver r
WHERE r.message_id = 'MSG_001'
  AND r.deleted = false
GROUP BY r.channel, r.status;

🎯 设计优势

1. 职责分离

   • tb_message_range - 定义发送规则
   • tb_message_receiver - 记录实际接收情况

2. 多渠道支持

   • 同一消息可通过多个渠道发送
   • 渠道配置独立管理
   • 易于扩展新渠道

3. 灵活的目标定义

   • 支持按用户、部门、角色、全员发送
   • 同一目标可使用不同渠道

4. 完整的状态跟踪

   • 记录阅读时间、处理时间
   • 支持已读/未读/已处理/已删除等状态

5. 性能优化

   • 合理的索引设计
   • 支持高效的用户消息查询

📝 注意事项

1. 数据一致性

   • 发送消息时，确保 tb_message_range 和 tb_message_receiver 的事务一致性

2. 渠道验证

   • 发送前检查 tb_message_channel 中渠道是否启用
   • 根据 priority 选择备用渠道

3. 性能考虑

   • 全员消息（target_type='all'）需要异步处理
   • 大量用户时分批创建 tb_message_receiver 记录

4. 软删除

   • 所有表都使用软删除（deleted字段）
   • 查询时注意添加 WHERE deleted = false 条件