NextEdu/docs/architecture/audit/announcements-messages-audit-report-v2.md

公告和消息模块审计报告 V2

审查日期：2026-06-22 审查范围：V1 改进后的 src/modules/announcements/**、src/modules/messaging/**、src/modules/notifications/**、对应路由层 前置文档：announcements-messages-audit-report.md（V1，14 项改进已全部完成或标记超出范围） 架构图参考：docs/architecture/004_architecture_impact_map.md §2.13 / §2.14 / §2.16

---

一、V1 完成情况复核

V1 编号	标题	状态
P0-1	i18n 全覆盖	✅ 已完成
P0-2	消除角色硬编码	✅ 已完成（COMMON_NAV_ITEMS 提取）
P0-3	补充错误边界	✅ 已完成（7 个 error.tsx）
P1-4	解耦 messaging 与 notifications	✅ 已完成（通知组件迁移）
P1-5	页面编排下沉	✅ 已完成（getAdminAnnouncementsPageData / getMessagesPageData）
P1-6	公告表单条件校验	✅ 已完成（superRefine）
P1-7	消息列表分页与搜索 hook	✅ 已完成（useMessageSearch + 分页 UI）
P1-8	通知实时推送	⚠️ 超出范围（需 SSE/WebSocket 基础设施）
P1-9	消息软删除事务化	✅ 已完成（db.transaction）
P2-10	a11y 改进	✅ 已完成（aria-label）
P2-11	监控埋点	✅ 已完成（trackEvent 接口）
P2-12	测试覆盖	⚠️ 超出范围（需独立测试计划）
P2-13	行业功能补齐	⚠️ 超出范围（需产品规划）
P2-14	架构图同步	✅ 已完成

V1 共 11 项已实施，3 项标记超出范围。

---

二、V2 新发现问题

2.1 通知 i18n 命名空间越界（P0）

位置	问题	违反规则
notifications/components/notification-list.tsx L29	useTranslations("messages") 通知组件使用 messages 命名空间	"模块标准结构" — notifications 模块应有独立 i18n 资源
notifications/components/notification-dropdown.tsx L39	同上	同上
src/shared/i18n/messages/	无 notifications.json 翻译文件	翻译文件结构不完整
i18n/request.ts	未加载 notifications 翻译文件	翻译文件未注册

后果：通知相关文案（notificationType.*、empty.noNotifications*、actions.markAllRead 等）散落在 messages 命名空间，模块边界混乱，维护困难。

2.2 通知标题硬编码（P0）

位置	代码	违反规则
announcements/actions.ts L75	title: \新公告：${announcement.title}``	"所有用户可见文本必须适配 i18n"
messaging/actions.ts L70-71	title: input.subject ? \New message: ${input.subject}` : "New message"`	同上

后果：通知标题语言固定（公告通知中文、消息通知英文），无法随 locale 切换。

2.3 AnnouncementList 过滤模式不一致（P1）

位置	问题
announcement-list.tsx L48-59	客户端 useMemo 过滤 + URL ?status= 更新混合模式

问题分析：

• L48-51：客户端 filtered 按 filter 状态过滤 announcements prop
• L53-59：handleFilterChange 同时更新 filter 状态和 URL ?status=
• 父页面 admin/announcements/page.tsx 根据 ?status= 服务端查询并传入 announcements prop

后果：数据被双重过滤（服务端 + 客户端），逻辑冗余；URL 刷新时客户端 filter 状态可能与服务端 initialStatus 不同步。

2.4 MessageList 客户端过滤冗余（P1）

位置	问题
message-list.tsx L50-53	filtered 在客户端再次过滤 displayMessages，但 getMessagesAction 已按 type 参数过滤

问题分析：

• useMessageSearch 调用 getMessagesAction({ type: tab, ... })，服务端已按 tab 过滤
• L50-53 又在客户端按 m.receiverId === currentUserId / m.senderId === currentUserId 过滤
• 当 tab === "inbox" 时，服务端返回 receiverId === userId 的消息，客户端再过滤一次相同条件

后果：逻辑冗余，且当服务端逻辑变化时客户端过滤可能不一致。

2.5 消息详情页编排未下沉（P1）

位置	问题
src/app/(dashboard)/messages/[id]/page.tsx	页面层直接调用 getMessageById 和 getMessageThread，未使用编排函数

后果：与 V1-P1-5 的编排下沉原则不一致；多个页面需要相同数据时无法复用。

2.6 表单未展示服务端校验错误（P1）

位置	问题
announcement-form.tsx L70-76	仅显示 res.message，未消费 res.errors 字段级错误
message-compose.tsx L57-63	同上

问题分析：

• Server Action 返回 { success: false, message, errors: { title: ["..."], content: ["..."] } }
• 表单仅 toast.error(res.message)，用户无法看到具体字段错误
• V1-P1-6 添加的 superRefine 条件校验错误无法有效传达给用户

后果：用户不知道哪个字段出错，体验差；Zod 校验形同虚设。

2.7 轮询间隔硬编码（P2）

位置	代码
notification-dropdown.tsx L71	30_000 硬编码
unread-message-badge.tsx	60_000 硬编码

后果：调整轮询频率需修改多个文件，无统一配置点。

2.8 架构图未记录 V2 新增内容（P2）

V2 新增的编排函数、i18n 文件、常量等需同步到架构图。

---

三、V2 改进优先级

V2-P0（紧急，影响 i18n 完整性）

1. 通知 i18n 命名空间独立：创建 notifications.json 翻译文件，将通知相关文案从 messages.json 迁移；更新 i18n/request.ts 加载新文件；通知组件改用 useTranslations("notifications")。
2. 通知标题 i18n 化：在 announcements/actions.ts 和 messaging/actions.ts 中使用 getTranslations 获取通知标题翻译。

V2-P1（重要，影响代码质量与体验）

3. AnnouncementList 过滤模式统一：移除客户端 useMemo 过滤，改为纯服务端过滤（通过 URL ?status= 触发 RSC 重新渲染）。
4. MessageList 过滤冗余移除：移除客户端 filtered 过滤，直接使用 displayMessages（服务端已按 type 过滤）。
5. 消息详情页编排下沉：新增 getMessageDetailPageData 编排函数。
6. 表单服务端校验错误展示：在 AnnouncementForm 和 MessageCompose 中展示 res.errors 字段级错误。

V2-P2（优化，提升可维护性）

7. 轮询间隔常量化：提取 NOTIFICATION_POLL_INTERVAL_MS 和 MESSAGE_POLL_INTERVAL_MS 常量。
8. 架构图同步：补充 V2 新增内容到 004/005 架构文档。

---

四、实施计划

编号	文件	变更类型
V2-P0-1	src/shared/i18n/messages/{zh-CN,en}/notifications.json	新建
V2-P0-1	src/i18n/request.ts	修改（加载 notifications）
V2-P0-1	src/shared/i18n/messages/{zh-CN,en}/messages.json	修改（移除通知相关键）
V2-P0-1	src/modules/notifications/components/notification-list.tsx	修改（useTranslations 命名空间）
V2-P0-1	src/modules/notifications/components/notification-dropdown.tsx	修改（同上）
V2-P0-2	src/modules/announcements/actions.ts	修改（getTranslations）
V2-P0-2	src/modules/messaging/actions.ts	修改（getTranslations）
V2-P1-1	src/modules/announcements/components/announcement-list.tsx	修改（移除客户端过滤）
V2-P1-2	src/modules/messaging/components/message-list.tsx	修改（移除 filtered）
V2-P1-3	src/modules/messaging/data-access.ts	修改（新增编排函数）
V2-P1-3	src/app/(dashboard)/messages/[id]/page.tsx	修改（使用编排函数）
V2-P1-4	src/modules/announcements/components/announcement-form.tsx	修改（展示 errors）
V2-P1-4	src/modules/messaging/components/message-compose.tsx	修改（展示 errors）
V2-P2-1	src/modules/notifications/components/notification-dropdown.tsx	修改（常量化）
V2-P2-1	src/modules/messaging/components/unread-message-badge.tsx	修改（常量化）
V2-P2-2	docs/architecture/004_architecture_impact_map.md	修改（同步）
V2-P2-2	docs/architecture/005_architecture_data.json	修改（同步）