diff --git a/docs/P1/F2-11消息中心报告.md b/docs/P1/F2-11消息中心报告.md new file mode 100644 index 0000000..7268b6f --- /dev/null +++ b/docs/P1/F2-11消息中心报告.md @@ -0,0 +1,105 @@ +# F2-11 消息中心与工作台通知报告 + +**日期**:2026-06-12 +**分支**:后端 `eip4-platform`,前端 `eip4-web` + +--- + +## 一、实现范围 + +### 后端(platform-metadata) + +新增 `NoticeController.java`,4 个端点: + +| 端点 | 方法 | 说明 | +|------|------|------| +| `GET /api/notice` | 消息分页列表 | 支持 `unreadOnly`/`page`/`perPage`;items 含 id/title/summary/type/createtime/isread | +| `GET /api/notice/unread-count` | 未读数计数 | 顶栏铃铛轮询专用,轻量 COUNT | +| `POST /api/notice/{id}/read` | 单条置已读 | 按 sys_message_id + sys_user_id UPDATE | +| `POST /api/notice/read-all` | 全部已读 | 当前用户批量 UPDATE | + +**数据源**:`eip3.sys_message`(58,456 行)+ `eip3.sys_messageuser`(279,951 行) +**身份识别**:`UserSession.get()` + `LoggedInUser.CURRENTUSER`(与 AdminWriteController 同口径,不依赖 platform-auth 模块) +**SQL 规范**:全参数化;`CAST(? AS character(36))` 保证索引可用;不对 `sys_user_id` 使用 TRIM + +### 前端(eip4-web) + +| 文件 | 变更 | +|------|------| +| `src/api/notice.ts` | 新增:fetchNotices / fetchUnreadCount / markNoticeRead / markAllNoticesRead | +| `src/shell/NoticeDrawer.tsx` | 新增:消息中心抽屉(标题/时间/未读蓝点/展开内容/全部已读) | +| `src/shell/Topbar.tsx` | 新增消息图标按钮(title="消息"),noticeBadge prop | +| `src/shell/AppShell.tsx` | 新增消息未读数轮询(60s)+ NoticeDrawer 状态管理 | +| `src/pages/WorkbenchPage.tsx` | 点亮通知卡片区域(原占位注释替换为真实卡片) | + +--- + +## 二、未读数性能口径(explain 实测) + +``` +EXPLAIN SELECT COUNT(*) FROM eip3.sys_messageuser +WHERE sys_user_id = CAST('ADMIN' AS character(36)) +AND isread = 0 AND isdel = 0; + + QUERY PLAN +────────────────────────────────────────────────────────────────── +Aggregate (cost=1016.68..1016.69 rows=1 width=8) + → Bitmap Heap Scan on sys_messageuser (cost=6.69..1016.02) + Recheck Cond: sys_user_id = 'ADMIN...'::character(36) + Filter: (isread = 0) AND (isdel = 0) + → Bitmap Index Scan on sys_messageuser_sys_user_id + Index Cond: sys_user_id = 'ADMIN...'::character(36) +``` + +**结论**:`sys_messageuser_sys_user_id` 索引已命中(Bitmap Index Scan),279,951 行表成本可控(cost=6.69 index scan)。 +**不擅自建索引**:现有索引足够当前量级。若未来需要优化可考虑复合索引: +```sql +-- 仅供参考,不上线 +CREATE INDEX CONCURRENTLY idx_msg_user_unread + ON eip3.sys_messageuser(sys_user_id, isread, isdel); +``` + +--- + +## 三、后端单测 + +文件:`platform-metadata/src/test/.../NoticeControllerTest.java` +mock 口径:`mockStatic(UserSession.class)`(与 AdminWriteControllerTest 同口径,不连库) + +``` +Tests run: 11, Failures: 0, Errors: 0, Skipped: 0 ✓ +``` + +覆盖:消息分页(全量/仅未读/perPage 截断)、未读数计数(有/零)、单条置已读、全部已读、未认证 401(共 11 个用例) + +--- + +## 四、E2E 证据 + +### 全套 e2e + +``` +50 passed (51.8s) 原基线 45 + 新增 5 +``` + +### notice.spec.ts 用例 + +| # | 用例 | 结果 | +|---|------|------| +| 1 | API: unread-count 返回 ≥1 | ✓ | +| 2 | API: 消息列表含 E2E 测试消息 | ✓ | +| 3 | API: 置已读后未读数减一 | ✓ | +| 4 | UI: 顶栏消息铃铛可见→点击弹 Drawer→截图 | ✓ | +| 5 | UI: Drawer 全部已读后 items 更新 | ✓ | + +### 截图存档 + +- `e2e/artifacts/f2-11/workbench-notice-card.png` — 工作台通知卡片 +- `e2e/artifacts/f2-11/topbar-notice-drawer.png` — 顶栏铃铛点击后 Drawer 展开 +- `e2e/artifacts/f2-11/drawer-after-readall.png` — 全部已读后状态 + +--- + +## 五、提交哈希 + +见各仓库 git log(F2-11 前缀)。 diff --git a/platform-metadata/src/main/java/com/eip4/platform/metadata/web/NoticeController.java b/platform-metadata/src/main/java/com/eip4/platform/metadata/web/NoticeController.java new file mode 100644 index 0000000..fe52c2a --- /dev/null +++ b/platform-metadata/src/main/java/com/eip4/platform/metadata/web/NoticeController.java @@ -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 消息中心端点(站内消息,不含公告)。 + * + *

数据源:{@code eip3.sys_message}(消息主体)+ {@code eip3.sys_messageuser}(按人已读态,279,951 行)。 + * 当前用户身份从 {@link UserSession} 取,与 AdminWriteController 同口径,不依赖 platform-auth 模块。 + * 全部 SQL 参数化,防 SQL 注入;不改 com.dsasp 代码。 + * + *

性能说明(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 建议见下方文档注释。 + * + *

索引现状说明(已有索引足够,不擅自建索引): + *

+ * + * + */ +@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 字符作摘要)。 + * + *

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 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> items = jdbcTemplate.queryForList(sql, userId, safePerPage, offset); + int total = jdbcTemplate.queryForObject(countSql, Integer.class, userId); + + return okList(items, total); + } + + // ---------------------------------------------------------------- 未读数计数 + + /** + * 当前用户未读消息数(轻量计数,顶栏铃铛轮询专用)。 + * + *

走 {@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 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 data = new LinkedHashMap<>(); + data.put("count", count == null ? 0 : count); + Map resp = new LinkedHashMap<>(); + resp.put("status", 0); + resp.put("msg", ""); + resp.put("data", data); + return resp; + } + + // ---------------------------------------------------------------- 单条置已读 + + /** + * 将指定消息对当前用户置为已读(UPDATE sys_messageuser.isread = 1)。 + * + *

按 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> 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 data = new LinkedHashMap<>(); + data.put("affected", affected); + Map 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> 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 data = new LinkedHashMap<>(); + data.put("affected", affected); + Map 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 okList(List> items, int total) { + Map data = new LinkedHashMap<>(); + data.put("items", items); + data.put("total", total); + Map resp = new LinkedHashMap<>(); + resp.put("status", 0); + resp.put("msg", ""); + resp.put("data", data); + return resp; + } +} diff --git a/platform-metadata/src/test/java/com/eip4/platform/metadata/web/NoticeControllerTest.java b/platform-metadata/src/test/java/com/eip4/platform/metadata/web/NoticeControllerTest.java new file mode 100644 index 0000000..88e4f49 --- /dev/null +++ b/platform-metadata/src/test/java/com/eip4/platform/metadata/web/NoticeControllerTest.java @@ -0,0 +1,221 @@ +package com.eip4.platform.metadata.web; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.mockito.ArgumentMatchers.anyString; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.mockStatic; +import static org.mockito.Mockito.when; + +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.Properties; + +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.mockito.MockedStatic; +import org.springframework.http.HttpStatus; +import org.springframework.http.ResponseEntity; +import org.springframework.jdbc.core.JdbcOperations; +import org.springframework.web.server.ResponseStatusException; + +import com.dsasp.server.common.user.service.LoggedInUser; +import com.dsasp.server.common.util.UserSession; + +/** + * F2-11 NoticeController 单测(mock JdbcTemplate + UserSession,不连库)。 + * + *

覆盖:消息分页(全量/仅未读/perPage 截断)、未读数计数、单条置已读、全部已读、未认证拒绝。 + * 响应格式统一校验 amis crud 约定 {status:0, data:{items, total}} 或 {status:0, data:{count:N}}。 + */ +@SuppressWarnings({"unchecked", "rawtypes"}) +class NoticeControllerTest { + + private JdbcOperations jdbc; + private NoticeController controller; + private MockedStatic userSessionMock; + + @BeforeEach + void setUp() { + jdbc = mock(JdbcOperations.class); + controller = new NoticeController(jdbc); + userSessionMock = mockStatic(UserSession.class); + } + + @AfterEach + void tearDown() { + userSessionMock.close(); + } + + // ---------------------------------------------------------------- 辅助 + + /** 模拟已登录用户,CURRENTUSER = userId */ + private void mockUser(String userId) { + Properties ctx = new Properties(); + ctx.setProperty(LoggedInUser.CURRENTUSER, userId); + userSessionMock.when(UserSession::get).thenReturn(ctx); + } + + /** 模拟未登录(UserSession.get() 返回 null) */ + private void mockNotLoggedIn() { + userSessionMock.when(UserSession::get).thenReturn(null); + } + + // ---------------------------------------------------------------- 消息分页列表 + + @Test + @DisplayName("1. 消息分页全量 → status=0, items+total 正常") + void listAllMessages() { + mockUser("user-001"); + List> fakeRows = List.of(fakeMsg("msg-001", "测试消息", "摘要", 1, 0L, 0)); + when(jdbc.queryForList(anyString(), eq("user-001"), eq(20), eq(0))).thenReturn(fakeRows); + when(jdbc.queryForObject(anyString(), eq(Integer.class), eq("user-001"))).thenReturn(1); + + Map resp = controller.list(false, 1, 20); + + assertEquals(0, resp.get("status")); + Map data = (Map) resp.get("data"); + assertNotNull(data); + assertEquals(1, ((List) data.get("items")).size()); + assertEquals(1, data.get("total")); + } + + @Test + @DisplayName("2. 消息分页仅未读 → status=0, 正常返回") + void listUnreadOnly() { + mockUser("user-002"); + List> fakeRows = List.of(fakeMsg("msg-002", "未读消息", "摘要", 2, 0L, 0)); + when(jdbc.queryForList(anyString(), eq("user-002"), eq(20), eq(0))).thenReturn(fakeRows); + when(jdbc.queryForObject(anyString(), eq(Integer.class), eq("user-002"))).thenReturn(1); + + Map resp = controller.list(true, 1, 20); + + assertEquals(0, resp.get("status")); + Map data = (Map) resp.get("data"); + assertEquals(1, ((List) data.get("items")).size()); + } + + @Test + @DisplayName("3. perPage 超上限 100 → 截断为 100") + void listPerPageCap() { + mockUser("user-003"); + when(jdbc.queryForList(anyString(), eq("user-003"), eq(100), eq(0))).thenReturn(List.of()); + when(jdbc.queryForObject(anyString(), eq(Integer.class), eq("user-003"))).thenReturn(0); + + Map resp = controller.list(false, 1, 9999); + + assertEquals(0, resp.get("status")); + Map data = (Map) resp.get("data"); + assertEquals(0, data.get("total")); + } + + @Test + @DisplayName("4. 未登录时 list → 抛 401 ResponseStatusException") + void listUnauthenticated() { + mockNotLoggedIn(); + ResponseStatusException ex = assertThrows(ResponseStatusException.class, + () -> controller.list(false, 1, 20)); + assertEquals(HttpStatus.UNAUTHORIZED, ex.getStatusCode()); + } + + // ---------------------------------------------------------------- 未读数计数 + + @Test + @DisplayName("5. 未读数计数 → status=0, data.count=5") + void unreadCount() { + mockUser("user-004"); + when(jdbc.queryForObject(anyString(), eq(Integer.class), eq("user-004"))).thenReturn(5); + + Map resp = controller.unreadCount(); + + assertEquals(0, resp.get("status")); + Map data = (Map) resp.get("data"); + assertEquals(5, data.get("count")); + } + + @Test + @DisplayName("6. 未读数为零时 → count=0") + void unreadCountZero() { + mockUser("user-005"); + when(jdbc.queryForObject(anyString(), eq(Integer.class), eq("user-005"))).thenReturn(0); + + Map resp = controller.unreadCount(); + + assertEquals(0, resp.get("status")); + assertEquals(0, ((Map) resp.get("data")).get("count")); + } + + @Test + @DisplayName("7. 未登录时 unreadCount → 抛 401 ResponseStatusException") + void unreadCountUnauthenticated() { + mockNotLoggedIn(); + assertThrows(ResponseStatusException.class, () -> controller.unreadCount()); + } + + // ---------------------------------------------------------------- 单条置已读 + + @Test + @DisplayName("8. 单条置已读 → HTTP 200, status=0, affected=1") + void markRead() { + mockUser("user-006"); + when(jdbc.update(anyString(), eq("msg-010"), eq("user-006"))).thenReturn(1); + + ResponseEntity> resp = controller.markRead("msg-010"); + + assertEquals(200, resp.getStatusCode().value()); + Map body = resp.getBody(); + assertNotNull(body); + assertEquals(0, body.get("status")); + assertEquals(1, ((Map) body.get("data")).get("affected")); + } + + @Test + @DisplayName("9. 未登录时 markRead → 抛 401 ResponseStatusException") + void markReadUnauthenticated() { + mockNotLoggedIn(); + assertThrows(ResponseStatusException.class, () -> controller.markRead("msg-010")); + } + + // ---------------------------------------------------------------- 全部已读 + + @Test + @DisplayName("10. 全部已读 → HTTP 200, status=0, affected=3") + void markAllRead() { + mockUser("user-007"); + when(jdbc.update(anyString(), eq("user-007"))).thenReturn(3); + + ResponseEntity> resp = controller.markAllRead(); + + assertEquals(200, resp.getStatusCode().value()); + Map body = resp.getBody(); + assertNotNull(body); + assertEquals(0, body.get("status")); + assertEquals(3, ((Map) body.get("data")).get("affected")); + } + + @Test + @DisplayName("11. 未登录时 markAllRead → 抛 401 ResponseStatusException") + void markAllReadUnauthenticated() { + mockNotLoggedIn(); + assertThrows(ResponseStatusException.class, () -> controller.markAllRead()); + } + + // ---------------------------------------------------------------- 测试数据构建 + + private Map fakeMsg(String id, String title, String summary, + int type, long createtime, int isread) { + Map m = new LinkedHashMap<>(); + m.put("id", id); + m.put("title", title); + m.put("summary", summary); + m.put("type", type); + m.put("createtime", createtime); + m.put("isread", isread); + return m; + } +}