Files
eip4-platform/docs/P1/F2-11消息中心报告.md
zhengwr 5f0b2d2c7b 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>
2026-06-12 02:26:53 +08:00

106 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 前缀)。