站内消息功能设计文档

本文档遵循《03-API设计规范》《06-日志和错误处理规范》《07-数据库规范》《08-安全规范》《Swagger泛型返回类型字段信息不显示问题解决方案》《前端ID精度丢失问题解决方案》等项目规范。

概述

为提升用户互动体验，系统需支持站内消息功能，包括医生向患者/家属发送提醒、系统自动检测异常数据并发送通知。消息采用文本格式，支持已读/未读状态管理，集成推送通知，仅依赖MySQL+Spring Boot。

背景和目标

背景：当前APP缺乏实时消息通知功能，用户无法及时收到医生提醒或异常数据警告。
目标：实现消息的发送、管理和浏览功能，支持推送通知、状态管理，接口风格与现有API统一。

需求与约束

认证：接口需走Token认证（AuthInterceptor），依赖currentUserId，未认证返回401。
存储：消息内容存储于MySQL，无附件支持。
数据库：新增消息相关表，存储发送者、接收者、内容、状态等。
访问控制：医生可发送消息，患者和家属可接收和管理消息。
API兼容：接口风格与现有API一致，所有响应均为R<T>格式，状态码、错误码、消息体与规范一致。
日志审计：所有操作需用SLF4J记录info级日志，异常需error级，内容含userId、操作等。
Swagger文档：所有接口需用@ApiResponse+@Content+@Schema标注，确保泛型返回类型文档化。
ID精度：所有响应中的ID字段在VO层转为String，避免前端精度丢失。

设计要点（高层）

Controller层新增接口：
- 医生发送消息：POST /messages/send，参数包含接收者、内容等。
- 系统发送日常消息：POST /messages/system-daily-send。
- 系统发送异常通知：POST /messages/system-anomaly-send。
- 获取消息列表：GET /messages/list，支持分页、状态筛选。
- 获取消息详情：GET /messages/{id}。
- 标记已读：PUT /messages/{id}/read。
- 删除消息：DELETE /messages/{id}。
- 获取未读数量：GET /messages/unread-count。
Service层实现消息CRUD、状态管理、推送逻辑、数据库操作、异常处理、日志记录等逻辑。异常检测集成到健康数据上传流程。
推送集成参考现有微信集成，使用订阅消息。

接口清单

API设计示例

医生发送消息接口

@Operation(summary = "医生发送消息", description = "医生向患者/家属发送站内消息")
@ApiResponses(value = {
  @ApiResponse(responseCode = "200", description = "发送成功",
    content = @Content(mediaType = "application/json",
      schema = @Schema(implementation = R.class))),
  @ApiResponse(responseCode = "400", description = "参数错误",
    content = @Content(mediaType = "application/json",
      schema = @Schema(implementation = R.class))),
  @ApiResponse(responseCode = "401", description = "未认证",
    content = @Content(mediaType = "application/json",
      schema = @Schema(implementation = R.class)))
})
@PostMapping("/messages/send")
public R<String> sendMessage(@RequestBody SendMessageRequest request) {
  // 校验参数、保存消息、触发推送、返回ID（String格式）
}

获取消息列表接口

@Operation(summary = "获取消息列表", description = "分页获取用户消息列表")
@ApiResponses(value = {
  @ApiResponse(responseCode = "200", description = "获取成功",
    content = @Content(mediaType = "application/json",
      schema = @Schema(implementation = R.class)))
})
@GetMapping("/messages/list")
public R<Page<MessageVO>> getMessageList(@RequestParam(defaultValue = "1") int page,
                                         @RequestParam(defaultValue = "10") int size,
                                         @RequestParam(required = false) Integer status) {
  // 返回分页列表，ID转为String
}

配置示例（application.yml）

# 无特定配置，复用现有推送和数据库配置

数据库字段设计与兼容性

消息表 (t_messages)

id: BIGINT PRIMARY KEY AUTO_INCREMENT（雪花算法生成，响应时转为String）
sender_id: BIGINT NOT NULL, 发送者ID（系统消息为0）
receiver_id: BIGINT NOT NULL, 接收者ID
content: TEXT NOT NULL, 消息内容
content_format: VARCHAR(20) DEFAULT 'PLAIN', 内容格式
type: VARCHAR(50) NOT NULL, 消息类型
notify_popup: TINYINT DEFAULT 0, 是否弹窗
notify_subscribe: TINYINT DEFAULT 0, 是否订阅推送
status: TINYINT DEFAULT 0, 状态（0未读1已读2已删除）
read_time: DATETIME, 阅读时间
is_deleted: TINYINT DEFAULT 0, 软删除标志
create_time: DATETIME DEFAULT CURRENT_TIMESTAMP（BaseEntity字段）
update_time: DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP（BaseEntity字段）
create_user: BIGINT（BaseEntity字段，创建者ID，转为String）
update_user: BIGINT（BaseEntity字段，更新者ID，转为String）
version: INT DEFAULT 0（BaseEntity字段，乐观锁版本号）
remark: VARCHAR(255)（BaseEntity字段，可选备注）

注：实体类继承BaseEntity，自动包含上述公共字段。id、create_user、update_user在JSON响应中通过ToStringSerializer转为String。

数据传输对象设计

请求VO

SendMessageRequest（医生发送消息请求）

@Schema(description = "医生发送消息请求")
public class SendMessageRequest {
    @Schema(description = "接收者ID列表", required = true)
    @NotEmpty(message = "接收者不能为空")
    private List<Long> receiverIds;

    @Schema(description = "消息内容", required = true)
    @NotBlank(message = "内容不能为空")
    private String content;

    @Schema(description = "内容格式", example = "PLAIN")
    private String contentFormat = "PLAIN";

    @Schema(description = "消息类型", required = true, example = "DOCTOR")
    @NotBlank(message = "类型不能为空")
    private String type;

    @Schema(description = "是否通知家属")
    private Boolean notifyFamily = false;

    @Schema(description = "是否弹窗")
    private Boolean notifyPopup;

    @Schema(description = "是否订阅推送")
    private Boolean notifySubscribe;
}

SystemDailySendRequest（系统发送日常消息请求）

@Schema(description = "系统发送日常消息请求")
public class SystemDailySendRequest {
    @Schema(description = "接收者ID列表", required = true)
    @NotEmpty(message = "接收者不能为空")
    private List<Long> receiverIds;

    @Schema(description = "消息标题")
    private String title;

    @Schema(description = "消息内容", required = true)
    @NotBlank(message = "内容不能为空")
    private String content;

    @Schema(description = "消息类型", required = true, example = "SYSTEM_DAILY")
    @NotBlank(message = "类型不能为空")
    private String type = "SYSTEM_DAILY";
}

SystemAnomalySendRequest（系统发送异常通知请求）

@Schema(description = "系统发送异常通知请求")
public class SystemAnomalySendRequest {
    @Schema(description = "患者ID", required = true)
    @NotNull(message = "患者ID不能为空")
    private Long patientId;

    @Schema(description = "异常数据详情")
    private Object anomalyData;

    @Schema(description = "消息类型", required = true, example = "SYSTEM_ANOMALY")
    @NotBlank(message = "类型不能为空")
    private String type = "SYSTEM_ANOMALY";
}

响应VO

MessageVO（消息信息响应）

@Schema(description = "消息信息")
public class MessageVO {
    @Schema(description = "消息ID", example = "1234567890123456789")
    private String id;

    @Schema(description = "发送者ID", example = "1234567890123456789")
    private String senderId;

    @Schema(description = "发送者姓名")
    private String senderName;

    @Schema(description = "接收者ID", example = "1234567890123456789")
    private String receiverId;

    @Schema(description = "消息内容")
    private String content;

    @Schema(description = "内容格式", example = "PLAIN")
    private String contentFormat;

    @Schema(description = "消息类型", example = "DOCTOR")
    private String type;

    @Schema(description = "是否弹窗")
    private Boolean notifyPopup;

    @Schema(description = "是否订阅推送")
    private Boolean notifySubscribe;

    @Schema(description = "状态", example = "0")
    private Byte status;

    @Schema(description = "阅读时间", example = "2023-12-01 10:00:00")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime readTime;

    @Schema(description = "创建时间", example = "2023-12-01 10:00:00")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;
}

注：所有ID字段在VO中定义为String类型，避免前端精度丢失。时间字段使用@JsonFormat格式化。senderName通过注入UserInfoMapper查询UserInfo.nickname填充。

联动查询设计

消息模块涉及跨表查询用户信息，为填充MessageVO中的senderName字段：

注入依赖：MessageServiceImpl注入UserInfoMapper。
查询逻辑：查询消息列表或详情时，根据message.sender_id调用userInfoMapper.selectById(senderId)，获取UserInfo对象。
字段映射：将userInfo.getNickname()赋值给messageVO.setSenderName()。
异常处理：若用户信息不存在，senderName设为空字符串或默认值，避免查询失败。
性能优化：对于列表查询，可批量查询用户信息，或使用缓存减少数据库访问。

权限与安全

发送接口仅医生/管理员角色可操作。
接收接口公开，但需认证。

日志与审计

操作日志：[MessageOperation] userId={}, action={}, messageId={}
异常日志：[MessageError] userId={}, error={}
使用SLF4J，日志级别INFO/ERROR。
ID在日志中以字符串记录。

测试建议

单元测试：CRUD逻辑、状态管理。
集成测试：接口联调、推送触发。
性能测试：列表分页、状态更新。

兼容性与前端要求

前端需支持消息列表、详情、状态管理。
响应中ID字段为String。

迁移/变更管理

先实现后端接口，测试通过后前端接入。

接口路径	方法	描述	权限要求	请求体/参数	响应
`/messages/send`	POST	医生发送消息	医生	SendMessageRequest (receiverIds, content, etc.)	R (消息ID)
`/messages/system-daily-send`	POST	系统发送日常消息	管理员	SystemDailySendRequest (receiverIds, title, content)	R (消息ID)
`/messages/system-anomaly-send`	POST	系统发送异常通知	系统/管理员	SystemAnomalySendRequest (patientId, anomalyData)	R (消息ID)
`/messages/list`	GET	获取消息列表（分页）	患者/家属	查询参数: page, size, status	R>
`/messages/{id}`	GET	获取消息详情	患者/家属	路径参数: id	R
`/messages/{id}/read`	PUT	标记消息已读	患者/家属	路径参数: id	R
`/messages/{id}`	DELETE	删除消息	患者/家属	路径参数: id	R
`/messages/unread-count`	GET	获取未读消息数量	患者/家属	无	R

站内消息功能设计文档.md 11 KB Vēsture Neapstrādāts