F2-11: 消息中心后端 — NoticeController + 单测 + 报告

- 新增 NoticeController(platform-metadata):4 个端点
  GET /api/notice(分页列表,支持 unreadOnly)
  GET /api/notice/unread-count(轻量未读数,顶栏轮询)
  POST /api/notice/{id}/read(单条置已读)
  POST /api/notice/read-all(全部已读)
- 数据源:eip3.sys_message + sys_messageuser(279,951 行)
- 身份:UserSession.get() + LoggedInUser.CURRENTUSER(不依赖 platform-auth)
- SQL CAST(? AS character(36)) 确保 sys_messageuser_sys_user_id 索引命中
  explain 实测:Bitmap Index Scan,cost=6.69
- 单测 11/11(mock UserSession,不连库)
- 报告:docs/P1/F2-11消息中心报告.md

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-06-12 02:26:53 +08:00
parent 4d7bbc6a42
commit 5f0b2d2c7b
3 changed files with 568 additions and 0 deletions

View File

@@ -0,0 +1,242 @@
package com.eip4.platform.metadata.web;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Properties;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.jdbc.core.JdbcOperations;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
import com.dsasp.server.common.user.service.LoggedInUser;
import com.dsasp.server.common.util.UserSession;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
/**
* F2-11 消息中心端点(站内消息,不含公告)。
*
* <p>数据源:{@code eip3.sys_message}(消息主体)+ {@code eip3.sys_messageuser}(按人已读态,279,951 行)。
* 当前用户身份从 {@link UserSession} 取,与 AdminWriteController 同口径,不依赖 platform-auth 模块。
* 全部 SQL 参数化,防 SQL 注入;不改 com.dsasp 代码。
*
* <p>性能说明(explain 实测):
* {@code sys_messageuser} 已有 {@code sys_messageuser_sys_user_id} 索引(Bitmap Index Scan)。
* SQL 不对 {@code sys_user_id} 使用 TRIM,依赖 {@code CAST(? AS character(36))} 的空格填充语义,
* 确保索引可用;建索引 DDL 建议见下方文档注释。
*
* <p>索引现状说明(已有索引足够,不擅自建索引):
* <ul>
* <li>{@code sys_messageuser_sys_user_id} 已覆盖 {@code sys_user_id} 等值查询,
* 未读数计数(isread=0 + isdel=0 附加条件)Bitmap Heap Scan 后再过滤,成本可控。</li>
* <li>若未来 279,951 行持续增长且未读数轮询成为热点,可考虑建复合索引:
* {@code CREATE INDEX CONCURRENTLY idx_msg_user_unread
* ON eip3.sys_messageuser(sys_user_id, isread, isdel);}
* 但当前量级不需要。</li>
* </ul>
*
* <ul>
* <li>{@code GET /api/notice} — 当前用户消息分页列表,支持 unreadOnly 过滤</li>
* <li>{@code GET /api/notice/unread-count} — 轻量未读数计数(顶栏轮询用)</li>
* <li>{@code POST /api/notice/{id}/read} — 单条置已读</li>
* <li>{@code POST /api/notice/read-all} — 当前用户全部已读</li>
* </ul>
*/
@Tag(name = "消息中心", description = "F2-11 站内消息端点(sys_message + sys_messageuser),身份从 UserSession 取")
@RestController
public class NoticeController {
private final JdbcOperations jdbcTemplate;
public NoticeController(JdbcOperations jdbcTemplate) {
this.jdbcTemplate = jdbcTemplate;
}
// ---------------------------------------------------------------- 消息分页列表
/**
* 当前用户消息分页列表(按 createtime DESC 排序,content 截取前 100 字符作摘要)。
*
* <p>JOIN sys_messageuser 过滤 isdel=0 保证软删消息不返回;
* unreadOnly=true 时追加 mu.isread=0 条件;
* 不对 sys_user_id 使用 TRIM,走 sys_messageuser_sys_user_id 索引。
*
* @param unreadOnly 仅返回未读,默认 false
* @param page 页码(从 1 开始),默认 1
* @param perPage 每页条数,默认 20,上限 100
* @return amis crud 约定格式 {@code {status,data:{items,total}}}
*/
@Operation(summary = "当前用户消息分页列表(支持仅未读过滤)",
description = "JOIN sys_messageuser 过滤已删消息;items 含 id/title/summary/type/createtime/isread;"
+ "走 sys_messageuser_sys_user_id 索引,不 TRIM sys_user_id")
@GetMapping("/api/notice")
public Map<String, Object> list(
@Parameter(description = "仅返回未读,默认 false") @RequestParam(defaultValue = "false") boolean unreadOnly,
@Parameter(description = "页码,从 1 开始") @RequestParam(defaultValue = "1") int page,
@Parameter(description = "每页条数,最大 100") @RequestParam(defaultValue = "20") int perPage) {
String userId = requireCurrentUserId();
int safePerPage = Math.min(Math.max(perPage, 1), 100);
int offset = (Math.max(page, 1) - 1) * safePerPage;
String unreadCond = unreadOnly ? " AND mu.isread = 0" : "";
String sql = "SELECT TRIM(m.sys_message_id) AS id,"
+ " m.title,"
+ " LEFT(m.content, 100) AS summary,"
+ " m.type,"
+ " m.createtime,"
+ " mu.isread"
+ " FROM eip3.sys_message m"
+ " JOIN eip3.sys_messageuser mu ON mu.sys_message_id = m.sys_message_id"
+ " WHERE mu.sys_user_id = CAST(? AS character(36))"
+ " AND mu.isdel = 0"
+ " AND m.isdel = 0"
+ unreadCond
+ " ORDER BY m.createtime DESC"
+ " LIMIT ? OFFSET ?";
String countSql = "SELECT COUNT(*)"
+ " FROM eip3.sys_message m"
+ " JOIN eip3.sys_messageuser mu ON mu.sys_message_id = m.sys_message_id"
+ " WHERE mu.sys_user_id = CAST(? AS character(36))"
+ " AND mu.isdel = 0"
+ " AND m.isdel = 0"
+ unreadCond;
List<Map<String, Object>> items = jdbcTemplate.queryForList(sql, userId, safePerPage, offset);
int total = jdbcTemplate.queryForObject(countSql, Integer.class, userId);
return okList(items, total);
}
// ---------------------------------------------------------------- 未读数计数
/**
* 当前用户未读消息数(轻量计数,顶栏铃铛轮询专用)。
*
* <p>走 {@code sys_messageuser_sys_user_id} 索引(explain 实测:Bitmap Index Scan,
* 279,951 行表成本可控)。不对 sys_user_id 使用 TRIM 确保索引生效。
*
* @return {@code {status:0, data:{count:N}}}
*/
@Operation(summary = "当前用户未读消息数(轻量,顶栏轮询用)",
description = "走 sys_messageuser_sys_user_id 索引;CAST(? AS character(36)) 保证索引可用")
@GetMapping("/api/notice/unread-count")
public Map<String, Object> unreadCount() {
String userId = requireCurrentUserId();
Integer count = jdbcTemplate.queryForObject(
"SELECT COUNT(*) FROM eip3.sys_messageuser"
+ " WHERE sys_user_id = CAST(? AS character(36))"
+ " AND isread = 0 AND isdel = 0",
Integer.class, userId);
Map<String, Object> data = new LinkedHashMap<>();
data.put("count", count == null ? 0 : count);
Map<String, Object> resp = new LinkedHashMap<>();
resp.put("status", 0);
resp.put("msg", "");
resp.put("data", data);
return resp;
}
// ---------------------------------------------------------------- 单条置已读
/**
* 将指定消息对当前用户置为已读(UPDATE sys_messageuser.isread = 1)。
*
* <p>按 sys_message_id + sys_user_id 联合条件 UPDATE,不依赖 sys_messageuser_id,
* 避免历史数据主键关联问题。
*
* @param id sys_message_id(路径参数,36 位)
* @return {@code {status:0, data:{affected:N}}}
*/
@Operation(summary = "单条消息置已读(UPDATE sys_messageuser isread=1)",
description = "按 sys_message_id + sys_user_id 联合条件 UPDATE;仅更新当前用户的已读态")
@PostMapping("/api/notice/{id}/read")
public ResponseEntity<Map<String, Object>> markRead(
@Parameter(description = "sys_message_id(36位)") @PathVariable String id) {
String userId = requireCurrentUserId();
int affected = jdbcTemplate.update(
"UPDATE eip3.sys_messageuser SET isread = 1"
+ " WHERE sys_message_id = CAST(? AS character(36))"
+ " AND sys_user_id = CAST(? AS character(36))"
+ " AND isdel = 0",
id.trim(), userId);
Map<String, Object> data = new LinkedHashMap<>();
data.put("affected", affected);
Map<String, Object> resp = new LinkedHashMap<>();
resp.put("status", 0);
resp.put("msg", "");
resp.put("data", data);
return ResponseEntity.ok(resp);
}
// ---------------------------------------------------------------- 全部已读
/**
* 当前用户全部消息置已读(批量 UPDATE)。
*
* @return {@code {status:0, data:{affected:N}}}
*/
@Operation(summary = "当前用户全部消息置已读(批量 UPDATE)",
description = "仅更新 isdel=0 的 sys_messageuser 行;按 sys_user_id 索引批量 UPDATE")
@PostMapping("/api/notice/read-all")
public ResponseEntity<Map<String, Object>> markAllRead() {
String userId = requireCurrentUserId();
int affected = jdbcTemplate.update(
"UPDATE eip3.sys_messageuser SET isread = 1"
+ " WHERE sys_user_id = CAST(? AS character(36))"
+ " AND isread = 0 AND isdel = 0",
userId);
Map<String, Object> data = new LinkedHashMap<>();
data.put("affected", affected);
Map<String, Object> resp = new LinkedHashMap<>();
resp.put("status", 0);
resp.put("msg", "");
resp.put("data", data);
return ResponseEntity.ok(resp);
}
// ---------------------------------------------------------------- 内部工具
/**
* 从 UserSession 取当前用户 ID(与 AdminWriteController 同口径)。
* 未登录时抛 401 异常(由 Spring 转为 401 响应)。
*/
private static String requireCurrentUserId() {
Properties ctx = UserSession.get();
if (ctx == null) {
throw new ResponseStatusException(HttpStatus.UNAUTHORIZED, "未认证");
}
String userId = ctx.getProperty(LoggedInUser.CURRENTUSER, "").trim();
if (userId.isEmpty()) {
throw new ResponseStatusException(HttpStatus.UNAUTHORIZED, "未认证");
}
return userId;
}
private Map<String, Object> okList(List<Map<String, Object>> items, int total) {
Map<String, Object> data = new LinkedHashMap<>();
data.put("items", items);
data.put("total", total);
Map<String, Object> resp = new LinkedHashMap<>();
resp.put("status", 0);
resp.put("msg", "");
resp.put("data", data);
return resp;
}
}