refactor(announcements,messaging,notifications): V1+V2 审计重构 — i18n 命名空间独立 + 通知标题 i18n 化 + 服务端过滤 + 编排下沉 + 表单错误展示 + 架构图同步
V1 改进（已完成）: - P0-4/P1-4/P1-5: 通知组件和 CRUD Action 从 messaging 迁移至 notifications 模块 - P1-5: 新增 getMessagesPageData / getAdminAnnouncementsPageData 编排函数 - P1-6: announcements schema 添加 superRefine 条件校验 - P1-7: 新增 useMessageSearch hook（防抖 + 请求竞态取消）+ 客户端分页 UI - P1-9: deleteMessage 事务化 - P2-11: 全模块 trackEvent 埋点 - 全模块 i18n 接入 + Error Boundary + a11y 改进 V2 改进（本次完成）: - V2-P0-1: 通知 i18n 命名空间独立（notifications.json），useTranslations 从 "messages" 切换到 "notifications" - V2-P0-2: 公告/消息通知标题 i18n 化，Server Action 中使用 getTranslations 生成通知标题 - V2-P1-1: AnnouncementList 纯服务端过滤，移除客户端 useState/useMemo - V2-P1-2: MessageList 客户端过滤仅在初始数据时执行，搜索结果由服务端按 tab 过滤 - V2-P1-3: 消息详情页编排下沉，新增 getMessageDetailPageData 编排函数 - V2-P1-4: 表单服务端校验错误展示（fieldErrors + aria-invalid） - V2-P2-1: 轮询间隔常量化（POLL_INTERVAL_MS） - V2-P2-2: 架构图同步（004 + 005）
This commit is contained in:
SpecialX
@@ -636,39 +636,50 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
**职责**：教材与知识体系管理（教材/章节树形结构、知识点 CRUD、Markdown 内容编辑、知识图谱）。
|
||||
|
||||
**导出函数**：
|
||||
- Actions（10 个，均为写操作；读操作由 RSC 页面直接调用 data-access）：`createTextbookAction` / `updateTextbookAction` / `deleteTextbookAction` / `createChapterAction` / `updateChapterContentAction` / `deleteChapterAction` / `reorderChaptersAction` / `createKnowledgePointAction` / `updateKnowledgePointAction` / `deleteKnowledgePointAction`
|
||||
- Data-access：`getTextbooks` / `getTextbookById` / `getChaptersByTextbookId` / `getKnowledgePointsByChapterId` / `getKnowledgePointsByTextbookId` / `createTextbook` / `updateTextbook` / `deleteTextbook` / `createChapter` / `updateChapterContent` / `deleteChapter` / `createKnowledgePoint` / `updateKnowledgePoint` / `deleteKnowledgePoint` / `reorderChapters` / `getTextbooksDashboardStats` / `getKnowledgePointOptions`（跨模块接口，供 questions 调用）
|
||||
- Actions（11 个，均为写操作；读操作由 RSC 页面直接调用 data-access）：`createTextbookAction` / `updateTextbookAction` / `deleteTextbookAction` / `createChapterAction` / `updateChapterContentAction` / `deleteChapterAction` / `reorderChaptersAction` / `createKnowledgePointAction` / `updateKnowledgePointAction` / `deleteKnowledgePointAction` / `getKnowledgePointsByChapterAction`
|
||||
- Data-access：`getTextbooks` / `getTextbookById` / `getChaptersByTextbookId` / `getKnowledgePointsByChapterId` / `getKnowledgePointsByTextbookId` / `createTextbook` / `updateTextbook` / `deleteTextbook` / `createChapter` / `updateChapterContent` / `deleteChapter` / `createKnowledgePoint` / `updateKnowledgePoint` / `deleteKnowledgePoint` / `reorderChapters` / `getTextbooksDashboardStats` / `getKnowledgePointOptions`（跨模块接口，供 questions 调用）/ `getTextbooksWithScope`（P1-1 新增：按数据范围获取教材列表，学生端强制按年级过滤）/ `verifyChapterBelongsToTextbook`（P0-4 新增：资源归属校验）/ `verifyKnowledgePointBelongsToTextbook`（P0-4 新增：资源归属校验）/ `getSubjectLabelKey` / `getGradeLabelKey`（i18n 标签键）
|
||||
- Constants（✅ 新增）：`SUBJECTS` / `GRADES` / `SUBJECT_COLORS` / `getSubjectColor` / `getSubjectLabelKey` / `getGradeLabelKey`
|
||||
- Utils（✅ 新增，纯函数 + 单测）：`sortChapters` / `buildChapterTree` / `buildChapterIndex` / `findChapterParent` / `filterKnowledgePointsByChapter` / `normalizeOptional` / `highlightKnowledgePoints`
|
||||
- Graph-layout（✅ 新增，纯函数 + 单测）：`computeGraphLayout`
|
||||
- Analytics（✅ 新增）：`TextbookAnalytics` / `TextbookAnalyticsProvider` / `useTextbookAnalytics`
|
||||
|
||||
**依赖关系**：
|
||||
- 依赖：`shared/*`、`@/auth`
|
||||
- 被依赖：`questions`（✅ P1-1 已修复：通过 textbooks data-access）、`exams`（通过类型）、`dashboard`（通过 data-access，P0-4 已修复）
|
||||
- ⚠️ UI 层跨模块依赖：`textbooks/components/knowledge-point-dialogs.tsx` 直接 import `questions/components/create-question-dialog`（P0 待解耦，详见 [textbooks-audit-report.md](audit/textbooks-audit-report.md)）
|
||||
- ✅ UI 层跨模块依赖已解耦：`textbooks/components/knowledge-point-dialogs.tsx` 不再直接 import questions 模块，改为通过 render prop 注入创建题目入口
|
||||
|
||||
**已知问题**：
|
||||
- ✅ 无跨模块 DB 访问（data-access 层）
|
||||
- ✅ actions 层编排模式标杆（权限校验 → 调用 data-access → revalidatePath）
|
||||
- ✅ data-access 层职责单一
|
||||
- ✅ P2 已修复：`data-access.ts` 中 `byId.get(pid)!.children.push` 非空断言清理为安全守卫；`or(...)!` 非空断言清理为条件 push
|
||||
- ⚠️ P0 跨模块 UI 依赖：`knowledge-point-dialogs.tsx` 直接 import questions 模块组件
|
||||
- ⚠️ P0 前端权限硬编码：`canEdit={true}` 按路由写死，未用 `usePermission().hasPermission()`
|
||||
- ⚠️ P0 全模块零 i18n：中英文文案硬编码，未接入 next-intl
|
||||
- ⚠️ P1 Server Action 未校验资源归属（chapterId 是否属于 textbookId）
|
||||
- ⚠️ P1 data-access 缺数据范围过滤（学生端未按年级过滤）
|
||||
- ⚠️ P1 缺 Error Boundary（无 error.tsx）
|
||||
- ⚠️ P1 知识点列表/弹窗存在重复实现（knowledge-point-panel.tsx 无调用方）
|
||||
- ⚠️ P1 学科/年级选项硬编码三处且彼此不一致
|
||||
- ⚠️ P1 纯逻辑未导出，零单测
|
||||
- ✅ P0 跨模块 UI 依赖已修复：`knowledge-point-dialogs.tsx` 通过 render prop 解耦，不再直接 import questions 模块
|
||||
- ✅ P0 前端权限硬编码已修复：改用 `usePermission().hasPermission()`
|
||||
- ✅ P0 i18n 已基本接入：`chapter-sidebar-list.tsx` / `actions.ts` / `section-error-boundary.tsx`（默认值改英文）均已接入 next-intl
|
||||
- ✅ P1 Server Action 资源归属校验已修复：新增 `verifyChapterBelongsToTextbook` / `verifyKnowledgePointBelongsToTextbook`
|
||||
- ✅ P1 data-access 数据范围过滤已修复：新增 `getTextbooksWithScope`，学生端强制按年级过滤
|
||||
- ✅ P1 Error Boundary 已补齐：新增 `section-error-boundary.tsx`
|
||||
- ✅ P1 知识点列表/弹窗重复实现已清理：移除无调用方的 `knowledge-point-panel.tsx`
|
||||
- ✅ P1 学科/年级选项统一：抽取到 `constants.ts`（`SUBJECTS` / `GRADES` / `SUBJECT_COLORS`）
|
||||
- ✅ P1 纯逻辑已导出并补单测：新增 `utils.ts` / `graph-layout.ts` 及对应 `.test.ts`
|
||||
- ⚠️ i18n 覆盖率约 95%（`chapter-sidebar-list` 已接入，`actions.ts` 已接入，`section-error-boundary` 默认值已改英文）
|
||||
- ⚠️ 类型断言残留 3 处 `as string`
|
||||
- ⚠️ P2 图谱方向键导航未实现
|
||||
|
||||
**文件清单**：
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `actions.ts` | 317 | 10 个 Server Action（写操作） |
|
||||
| `data-access.ts` | 514 | 教材/章节/知识点 CRUD + 跨模块查询接口 |
|
||||
| `actions.ts` | 377 | 11 个 Server Action（写操作，含 Zod 校验 + 资源归属校验） |
|
||||
| `data-access.ts` | 619 | 教材/章节/知识点 CRUD + 跨模块查询接口 + 资源归属校验 + 数据范围过滤 |
|
||||
| `types.ts` | 45 | 类型定义 |
|
||||
| `schema.ts` | 64 | Zod 校验 |
|
||||
| `constants.ts` | 91 | 学科/年级常量与颜色映射（✅ 新增） |
|
||||
| `utils.ts` | 181 | 章节树构建/排序/查找等纯函数（✅ 新增，含单测） |
|
||||
| `graph-layout.ts` | 141 | 知识图谱布局计算纯函数（✅ 新增，含单测） |
|
||||
| `analytics.tsx` | 43 | 教材分析 Context/Provider/Hook（✅ 新增） |
|
||||
| `hooks/use-knowledge-point-actions.ts` | 121 | 知识点操作 Hook |
|
||||
| `hooks/use-text-selection.ts` | 57 | 文本选区捕获 Hook |
|
||||
| `components/*` | 11 文件 | 教材编辑/知识图谱组件 |
|
||||
| `components/*` | 12 文件 | 教材编辑/知识图谱组件（新增 `section-error-boundary.tsx`） |
|
||||
|
||||
---
|
||||
|
||||
@@ -775,6 +786,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
- ⚠️ P0-2（2026-06-22 审计发现）：年级 CRUD 逻辑与 `grade-management` 模块重复定义，两套实现并存
|
||||
- ⚠️ P0-5（2026-06-22 审计发现）：`school/components/*` 4 个组件均缺少 i18n（`schools-view.tsx` 已修复，其余 3 个待修复）；缺少 Error Boundary / Skeleton
|
||||
- ✅ P0-5 部分修复（2026-06-22）：新增 `school.json` i18n 文件，`schools-view.tsx` 接入 `useTranslations("school")`
|
||||
- ✅ P1-3 修复（2026-06-22）：新增 school-error-boundary.tsx（class component Error Boundary + i18n + router.refresh 重试）和 school-skeleton.tsx（SchoolListSkeleton 表格骨架 + SchoolCardSkeleton 卡片骨架）；4 个页面（schools/grades/departments/academic-year）均已包裹 SchoolErrorBoundary；school.json 补充 errors.boundary.* 翻译键
|
||||
|
||||
**文件清单**：
|
||||
| 文件 | 行数 | 职责 |
|
||||
@@ -783,6 +795,8 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
| `data-access.ts` | 504 | 只读查询 + 12 个写操作 + 跨模块查询接口（`isGradeHead`/`isGradeManager`/`findGradeIdByHeadAndName`/`getGradeNameById`/`getSubjectNameById`） |
|
||||
| `schema.ts` | 51 | Zod 校验 |
|
||||
| `types.ts` | 96 | 类型定义（含 Insert/Update 入参类型） |
|
||||
| components/school-error-boundary.tsx | 72 | 共享 Error Boundary（class component + i18n + router.refresh 重试） |
|
||||
| components/school-skeleton.tsx | 69 | 共享骨架屏（SchoolListSkeleton 表格骨架 + SchoolCardSkeleton 卡片骨架） |
|
||||
|
||||
---
|
||||
|
||||
@@ -1000,7 +1014,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
|
||||
**导出函数**：
|
||||
- Actions：`sendMessageAction` / `markMessageAsReadAction` / `deleteMessageAction` / `getMessagesAction` / `getMessageDetailAction` / `getRecipientsAction` / `getUnreadMessageCountAction` / `getNotificationPreferencesAction` / `updateNotificationPreferencesAction`（✅ P1-4 已修复：通知 CRUD Action 已迁移至 notifications 模块，messaging 仅保留私信和通知偏好 Action）
|
||||
- Data-access：`getMessages` / `getMessageById` / `getMessageThread` / `createMessage` / `markMessageAsRead` / `deleteMessage` / `getUnreadMessageCount` / `getRecipients`（按 DataScope 过滤可发送对象：class_taught 教师→学生、grade_managed 年级管理员→教师/学生、all 管理员、class_members 学生→自己班级的任课教师/班主任、children 家长→孩子的班主任/任课教师；通过 classes data-access.getTeacherIdsByClassIds/getStudentActiveClassId 获取班级教师 ID）/ `getMessagesPageData`（✅ P1-5 新增：消息首页编排函数，一次性获取消息列表和通知列表）
|
||||
- Data-access：`getMessages` / `getMessageById` / `getMessageThread` / `createMessage` / `markMessageAsRead` / `deleteMessage` / `getUnreadMessageCount` / `getRecipients`（按 DataScope 过滤可发送对象：class_taught 教师→学生、grade_managed 年级管理员→教师/学生、all 管理员、class_members 学生→自己班级的任课教师/班主任、children 家长→孩子的班主任/任课教师；通过 classes data-access.getTeacherIdsByClassIds/getStudentActiveClassId 获取班级教师 ID）/ `getMessagesPageData`（✅ P1-5 新增：消息首页编排函数，一次性获取消息列表和通知列表）/ `getMessageDetailPageData`（✅ V2-P1-3 新增：消息详情页编排函数，获取详情并自动标记已读）
|
||||
- Hooks：`useMessageSearch`（✅ P1-7 新增：消息搜索 hook，含防抖和请求竞态取消）
|
||||
- Notification-preferences：~~re-export shim（实际逻辑在 `notifications/preferences.ts`）~~ ✅ P0-b 已修复：`notification-preferences.ts` 文件已删除（通知模块去重），消费方改为直接从 `@/modules/notifications/preferences` 导入 `getNotificationPreferences` / `upsertNotificationPreferences`
|
||||
|
||||
@@ -1025,12 +1039,17 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
- ✅ P1-7 已修复：~~消息列表客户端 `useEffect` + `setTimeout` 防抖搜索未取消已发出的请求~~ 搜索逻辑抽离为 `useMessageSearch` hook（含防抖 + 请求竞态取消）；~~无分页 UI~~ 新增客户端分页 UI（PAGE_SIZE=20，ChevronLeft/ChevronRight 按钮）
|
||||
- ✅ P1-9 已修复：~~`deleteMessage` 两个独立 UPDATE 无事务~~ 改为 `db.transaction` 包裹 senderDeletedAt 和 receiverDeletedAt 更新，保证原子性
|
||||
- ✅ P2-11 已修复：~~发送/删除消息无埋点~~ `sendMessageAction` / `markMessageAsReadAction` / `deleteMessageAction` 新增 `trackEvent` 埋点（message.sent / message.marked_read / message.deleted）
|
||||
- ✅ V2-P0-2 已修复：~~通知标题硬编码~~ `sendMessageAction` 通过 `getTranslations('messages')` 生成 i18n 通知标题（`notification.messageTitle` / `messageTitleNoSubject`）
|
||||
- ✅ V2-P1-2 已修复：~~MessageList 客户端过滤冗余~~ 客户端过滤仅在初始数据（type=all）时执行，搜索结果已由服务端按 tab 过滤
|
||||
- ✅ V2-P1-3 已修复：~~消息详情页分散编排~~ 新增 `getMessageDetailPageData` 编排函数，替代 page.tsx 中 `after()` + `getMessageById` + `markMessageAsRead` 的分散编排
|
||||
- ✅ V2-P1-4 已修复：~~表单无服务端校验错误展示~~ `message-compose.tsx` 新增 `fieldErrors` 状态 + `aria-invalid` 字段级错误展示（receiverId/subject/content）
|
||||
- ✅ V2-P2-1 已修复：~~轮询间隔魔法数字~~ `unread-message-badge.tsx` 轮询间隔提取为 `POLL_INTERVAL_MS` 常量（60_000ms）
|
||||
|
||||
**文件清单**：
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `actions.ts` | ~260 | 7 个私信 Server Action + 2 个通知偏好 Action（✅ P1-4：通知 CRUD Action 已迁移至 notifications 模块） |
|
||||
| `data-access.ts` | ~270 | 私信 CRUD + `getMessagesPageData` 编排函数（✅ P1-5 新增） |
|
||||
| `actions.ts` | ~280 | 7 个私信 Server Action + 2 个通知偏好 Action（✅ P1-4：通知 CRUD Action 已迁移至 notifications 模块；✅ V2-P0-2：通知标题 i18n 化） |
|
||||
| `data-access.ts` | ~290 | 私信 CRUD + `getMessagesPageData` 编排函数（✅ P1-5 新增）+ `getMessageDetailPageData` 编排函数（✅ V2-P1-3 新增） |
|
||||
| `schema.ts` | 44 | 私信发送校验 + messageId 校验 + 通知偏好更新校验 |
|
||||
| `types.ts` | 52 | 私信类型 + re-export 通知类型（向后兼容） |
|
||||
| `hooks/use-message-search.ts` | ~60 | ✅ P1-7 新增：消息搜索 hook（防抖 + 请求竞态取消） |
|
||||
@@ -1038,14 +1057,14 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
**组件清单**：
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| `components/message-list.tsx` | 消息列表（✅ P1-7：使用 `useMessageSearch` hook + 客户端分页 UI，PAGE_SIZE=20） |
|
||||
| `components/message-list.tsx` | 消息列表（✅ P1-7：使用 `useMessageSearch` hook + 客户端分页 UI，PAGE_SIZE=20；✅ V2-P1-2：客户端过滤仅在初始数据时执行） |
|
||||
| `components/message-detail.tsx` | 消息详情（含回复） |
|
||||
| `components/message-compose.tsx` | 撰写新消息 |
|
||||
| `components/unread-message-badge.tsx` | 未读消息计数徽章（侧边栏，每 60 秒轮询 `getUnreadMessageCountAction`） |
|
||||
| `components/message-compose.tsx` | 撰写新消息（✅ V2-P1-4：fieldErrors + aria-invalid 字段级错误展示） |
|
||||
| `components/unread-message-badge.tsx` | 未读消息计数徽章（侧边栏，每 60 秒轮询 `getUnreadMessageCountAction`；✅ V2-P2-1：POLL_INTERVAL_MS 常量） |
|
||||
|
||||
**客户端行为**：
|
||||
- `message-list.tsx`：客户端调用 `getMessagesAction` 搜索消息（useMessageSearch hook，400ms 防抖，请求竞态取消）
|
||||
- `unread-message-badge.tsx`：每 60 秒轮询 `getUnreadMessageCountAction` 刷新未读计数
|
||||
- `message-list.tsx`：客户端调用 `getMessagesAction` 搜索消息（useMessageSearch hook，400ms 防抖，请求竞态取消）；V2-P1-2 优化：客户端过滤仅在初始数据（type=all）时执行
|
||||
- `unread-message-badge.tsx`：每 `POLL_INTERVAL_MS`（60_000ms）轮询 `getUnreadMessageCountAction` 刷新未读计数
|
||||
|
||||
---
|
||||
|
||||
@@ -1071,6 +1090,8 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
- ✅ P1-1 已修复：~~`sendClassNotificationAction` 直查 `classes`/`classEnrollments`~~ 改为调用 `classes/data-access.getClassExists` / `getStudentIdsByClassId`
|
||||
- ✅ P1-4 已修复：~~通知 UI 组件放在 messaging/components 下，直接 import notifications 类型和 messaging/actions~~ `notification-list.tsx` 和 `notification-dropdown.tsx` 已迁移至 `notifications/components/`，通知 CRUD Action 已从 messaging 迁移至 `notifications/actions.ts`，消除 UI 层跨模块耦合
|
||||
- ✅ P2-11 已修复：~~通知标记已读无埋点~~ `markNotificationAsReadAction` / `markAllNotificationsAsReadAction` 新增 `trackEvent` 埋点（notification.marked_read / notification.marked_all_read）
|
||||
- ✅ V2-P0-1 已修复：~~通知 i18n 键混在 messages.json 中~~ 新增独立的 `notifications.json` 命名空间（zh-CN/en），通知组件 `useTranslations` 从 `"messages"` 切换到 `"notifications"`；`src/i18n/request.ts` 新增 notifications 命名空间加载
|
||||
- ✅ V2-P2-1 已修复：~~轮询间隔魔法数字~~ `notification-dropdown.tsx` 轮询间隔提取为 `POLL_INTERVAL_MS` 常量（30_000ms）
|
||||
- ⚠️ P1：发送日志仅 console，无 `notification_logs` 表
|
||||
- ✅ 渠道抽象优秀（接口 + 工厂 + Mock 实现）
|
||||
|
||||
@@ -1090,11 +1111,11 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
**组件清单**：
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| `components/notification-list.tsx` | 通知列表（消息页底部，展示所有通知，支持标记已读） |
|
||||
| `components/notification-dropdown.tsx` | 通知下拉菜单（站点头部，每 30 秒轮询 `getNotificationsAction` + `getUnreadNotificationCountAction`） |
|
||||
| `components/notification-list.tsx` | 通知列表（消息页底部，展示所有通知，支持标记已读；✅ V2-P0-1：useTranslations 命名空间从 "messages" 切换到 "notifications"） |
|
||||
| `components/notification-dropdown.tsx` | 通知下拉菜单（站点头部，每 30 秒轮询 `getNotificationsAction` + `getUnreadNotificationCountAction`；✅ V2-P0-1：useTranslations 命名空间切换；✅ V2-P2-1：POLL_INTERVAL_MS 常量） |
|
||||
|
||||
**客户端行为**：
|
||||
- `notification-dropdown.tsx`：每 30 秒轮询 `getNotificationsAction`（pageSize=10）和 `getUnreadNotificationCountAction` 刷新通知和未读计数
|
||||
- `notification-dropdown.tsx`：每 `POLL_INTERVAL_MS`（30_000ms）轮询 `getNotificationsAction`（pageSize=10）和 `getUnreadNotificationCountAction` 刷新通知和未读计数
|
||||
|
||||
---
|
||||
|
||||
@@ -1151,6 +1172,9 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
- ✅ P1-5 已修复：~~页面层 `Promise.all` 编排 announcements/school/classes 三个模块的 data-access~~ 新增 `getAdminAnnouncementsPageData` 和 `getEditAnnouncementPageData` 编排函数，页面层仅调用单一函数
|
||||
- ✅ P1-6 已修复：~~`targetGradeId` / `targetClassId` 为 optional，未根据 `type` 做条件必填校验~~ `CreateAnnouncementSchema` 和 `UpdateAnnouncementSchema` 添加 `superRefine(refineAudience)`，年级公告强制 `targetGradeId`，班级公告强制 `targetClassId`
|
||||
- ✅ P2-11 已修复：~~发布/归档/删除公告无埋点~~ `createAnnouncementAction` / `updateAnnouncementAction` / `deleteAnnouncementAction` / `publishAnnouncementAction` / `archiveAnnouncementAction` 新增 `trackEvent` 埋点（announcement.created / announcement.updated / announcement.published / announcement.deleted / announcement.archived）
|
||||
- ✅ V2-P0-2 已修复：~~通知标题硬编码~~ `createAnnouncementAction` / `updateAnnouncementAction` / `publishAnnouncementAction` 通过 `getTranslations('announcements')` 生成 i18n 通知标题（`notification.publishedTitle` / `publishedContent`）
|
||||
- ✅ V2-P1-1 已修复：~~AnnouncementList 客户端 useState/useMemo 过滤~~ 改为纯服务端过滤模式，Select 切换仅更新 URL `?status=` 触发 RSC 重新渲染
|
||||
- ✅ V2-P1-4 已修复：~~表单无服务端校验错误展示~~ `announcement-form.tsx` 新增 `fieldErrors` 状态 + `aria-invalid` 字段级错误展示（title/content/targetGradeId/targetClassId）
|
||||
|
||||
**文件清单**：
|
||||
| 文件 | 行数 | 职责 |
|
||||
@@ -1163,10 +1187,10 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
**组件清单**：
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| `components/announcement-list.tsx` | 公告列表（用户端，支持状态筛选） |
|
||||
| `components/announcement-list.tsx` | 公告列表（用户端，支持状态筛选；✅ V2-P1-1：纯服务端过滤，Select 切换更新 URL ?status= 触发 RSC 重新渲染） |
|
||||
| `components/announcement-card.tsx` | 公告卡片（列表项） |
|
||||
| `components/announcement-detail.tsx` | 公告详情（只读） |
|
||||
| `components/announcement-form.tsx` | 公告表单（创建/编辑，✅ P1-6：条件校验由 schema superRefine 保证） |
|
||||
| `components/announcement-form.tsx` | 公告表单（创建/编辑，✅ P1-6：条件校验由 schema superRefine 保证；✅ V2-P1-4：fieldErrors + aria-invalid 字段级错误展示） |
|
||||
| `components/admin-announcements-view.tsx` | 管理端公告视图（列表 + 筛选） |
|
||||
|
||||
---
|
||||
@@ -1661,39 +1685,39 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
| `lib/node-summary.ts` | **纯函数**：getNodeSummary（接受翻译函数注入，支持 i18n）+ NODE_COLORS + getNodeColor |
|
||||
| `lib/rf-mappers.ts` | **纯函数**：toRfNodes/toRfEdges/fromRfEdges（LessonPlanNode/Edge ↔ React Flow Node/Edge 映射） |
|
||||
| `config/block-registry.tsx` | **配置驱动**：BLOCK_REGISTRY 注册表 + getBlockComponent/isRichTextBlock，node-edit-panel 通过配置渲染 Block |
|
||||
| `providers/lesson-plan-provider.tsx` | **Provider + Context（P1-5/P1-7/P2-4）**：LessonPlanProvider 注入数据服务/角色配置/埋点；定义 LessonPlanDataService 接口、4 个角色配置（TEACHER/ADMIN/STUDENT/PARENT）、ROLE_CONFIGS 注册表、LessonPlanTracker 接口 + noopTracker；hooks：useLessonPlanContextSafe（返回 null 不抛错）/useLessonPlanContext/useRoleConfig/useLessonPlanService/useLessonPlanTracker |
|
||||
| `providers/lesson-plan-provider.tsx` | **Provider + Context（P1-5/P1-7/P2-4/V2-6）**：LessonPlanProvider 注入数据服务/角色配置/埋点；定义 LessonPlanDataService 接口、4 个角色配置（TEACHER/ADMIN/STUDENT/PARENT）、ROLE_CONFIGS 注册表、LessonPlanTracker 接口 + noopTracker；hooks：useLessonPlanContextSafe（返回 null 不抛错）/useLessonPlanContext/useRoleConfig/useLessonPlanService/useLessonPlanTracker/useLessonPlanTrackerSafe（V2-6 新增，返回 noopTracker 不抛错） |
|
||||
| `services/default-data-service.ts` | **默认数据服务实现**：createDefaultDataService() 包装 Server Actions 为 LessonPlanDataService 实现，测试可替换为 mock |
|
||||
| `data-access.ts` | 课案 CRUD + 模板查询（migrateV1ToV2/normalizeDocument/buildInitialContent 从 lib/ 导入并 re-export 保持向后兼容；buildScopeCondition 按 scope 类型精确过滤 P0-3） |
|
||||
| `data-access-versions.ts` | 版本管理（创建/查询/回滚/清理） |
|
||||
| `data-access-templates.ts` | 个人模板 CRUD |
|
||||
| `data-access-knowledge.ts` | 按知识点/题目反查课案 |
|
||||
| `actions.ts` | 课案 CRUD/版本/模板 Server Actions |
|
||||
| `actions-publish.ts` | 发布作业 Server Action |
|
||||
| `actions-ai.ts` | AI 知识点建议 Server Action |
|
||||
| `actions-kp.ts` | 知识点选项 Server Action |
|
||||
| `publish-service.ts` | 发布作业服务（编排 homework/exams/classes，通过对方 data-access 调用，无直查跨模块表） |
|
||||
| `data-access.ts` | 课案 CRUD + 模板查询（migrateV1ToV2/normalizeDocument/buildInitialContent 从 lib/ 导入并 re-export 保持向后兼容；buildScopeCondition 按 scope 类型精确过滤 P0-3；V2-1：抛出 `LessonPlanDataError` 错误码；V2-3：mapRowToLessonPlan/mapRowToListItem/mapRowToTemplate 显式映射 + isLessonPlanStatus/isTemplateType/isTemplateScope 类型守卫） |
|
||||
| `data-access-versions.ts` | 版本管理（创建/查询/回滚/清理；V2-3：mapRowToVersion 显式映射） |
|
||||
| `data-access-templates.ts` | 个人模板 CRUD（V2-3：mapRowToTemplate 显式映射 + 类型守卫） |
|
||||
| `data-access-knowledge.ts` | 按知识点/题目反查课案（V2-3：显式字段映射替代 `as unknown as`） |
|
||||
| `actions.ts` | 课案 CRUD/版本/模板 Server Actions（V2-1：getTranslations i18n + 错误码捕获；V2-2：createLessonPlanAction 传入 translateTitle 翻译 SYSTEM_TEMPLATES） |
|
||||
| `actions-publish.ts` | 发布作业 Server Action（V2-1：getTranslations i18n + PUBLISH_ERROR_KEY_MAP 错误码映射） |
|
||||
| `actions-ai.ts` | AI 知识点建议 Server Action（V2-1：i18n + 错误码） |
|
||||
| `actions-kp.ts` | 知识点选项 Server Action（V2-1：i18n + 错误码） |
|
||||
| `publish-service.ts` | 发布作业服务（编排 homework/exams/classes，通过对方 data-access 调用，无直查跨模块表；V2-1：抛出 `PublishServiceError` 错误码；V2-3：显式字段映射替代 `as unknown as`） |
|
||||
| `ai-suggest.ts` | AI 知识点建议服务 |
|
||||
| `seed-templates.ts` | 模板种子数据 |
|
||||
| `hooks/use-lesson-plan-editor.ts` | 课案编辑器 Hook（基于 zustand，支持 nodes/edges 操作：addNode/updateNode/updateNodePosition/removeNode/connect/disconnect/setEdges/selectNode） |
|
||||
| `components/lesson-plan-list.tsx` | 课案列表（i18n 已接入） |
|
||||
| `components/lesson-plan-card.tsx` | 课案卡片（i18n 已接入） |
|
||||
| `components/lesson-plan-filters.tsx` | 课案筛选器（i18n 已接入） |
|
||||
| `components/lesson-plan-editor.tsx` | 课案编辑器（编排 NodeEditor + NodeEditPanel，i18n 已接入） |
|
||||
| `components/node-editor.tsx` | **节点图画布**（React Flow，使用 lib/rf-mappers + lib/node-summary 纯函数，i18n 已接入） |
|
||||
| `components/lesson-plan-card.tsx` | 课案卡片（i18n 已接入；V2-6：duplicate/archive 调用 tracker.track） |
|
||||
| `components/lesson-plan-filters.tsx` | 课案筛选器（i18n 已接入；V2-5：3 个表单元素 label htmlFor 关联） |
|
||||
| `components/lesson-plan-editor.tsx` | 课案编辑器（编排 NodeEditor + NodeEditPanel，i18n 已接入；V2-6：handleManualSave 调用 tracker.track） |
|
||||
| `components/node-editor.tsx` | **节点图画布**（React Flow，使用 lib/rf-mappers + lib/node-summary 纯函数，i18n 已接入；V2-4：MiniMap 复用 getNodeColor；V2-5：role=application + 键盘导航配置） |
|
||||
| `components/node-edit-panel.tsx` | **侧边内容编辑面板**（配置驱动渲染 Block，通过 getBlockComponent + LessonPlanErrorBoundary 包裹，i18n 已接入） |
|
||||
| `components/nodes/lesson-node.tsx` | **自定义节点组件**（使用 lib/node-summary 的 getNodeSummary/getNodeColor，i18n 已接入） |
|
||||
| `components/lesson-plan-error-boundary.tsx` | **错误边界**：LessonPlanErrorBoundary 类组件，支持 fallback 和 onError 回调 |
|
||||
| `components/lesson-plan-skeleton.tsx` | **骨架屏**：VersionListSkeleton/QuestionBankSkeleton/KnowledgePointSkeleton/LessonPlanListSkeleton |
|
||||
| `components/block-renderer.tsx` | ⚠️ @deprecated Block 渲染器（已被 NodeEditor 替代，保留向后兼容） |
|
||||
| `components/template-picker.tsx` | 模板选择器（i18n 已接入） |
|
||||
| `components/version-history-drawer.tsx` | 版本历史抽屉（i18n 已接入） |
|
||||
| `components/template-picker.tsx` | 模板选择器（i18n 已接入；V2-6：create 调用 tracker.track） |
|
||||
| `components/version-history-drawer.tsx` | 版本历史抽屉（i18n 已接入；V2-6：revert 调用 tracker.track） |
|
||||
| `components/knowledge-point-picker.tsx` | 知识点选择器（i18n 已接入） |
|
||||
| `components/question-bank-picker.tsx` | 题库选择器（i18n 已接入） |
|
||||
| `components/inline-question-editor.tsx` | 内联题目编辑器（i18n 已接入） |
|
||||
| `components/publish-homework-dialog.tsx` | 发布作业对话框（i18n 已接入） |
|
||||
| `components/inline-question-editor.tsx` | 内联题目编辑器（i18n 已接入；V2-5：type/difficulty select label htmlFor 关联） |
|
||||
| `components/publish-homework-dialog.tsx` | 发布作业对话框（i18n 已接入；V2-6：publish 调用 tracker.track） |
|
||||
| `components/blocks/rich-text-block.tsx` | 富文本 Block（被 NodeEditPanel 复用，i18n 已接入） |
|
||||
| `components/blocks/text-study-block.tsx` | 课文研读 Block（被 NodeEditPanel 复用，i18n 已接入） |
|
||||
| `components/blocks/exercise-block.tsx` | 练习 Block（被 NodeEditPanel 复用，使用 router.refresh 替代 window.location.reload，i18n 已接入） |
|
||||
| `components/blocks/exercise-block.tsx` | 练习 Block（被 NodeEditPanel 复用，使用 router.refresh 替代 window.location.reload，i18n 已接入；V2-5：purpose select label 关联 + 题目列表 ul/li 语义化） |
|
||||
| `components/blocks/reflection-block.tsx` | 反思 Block（被 NodeEditPanel 复用，i18n 已接入） |
|
||||
|
||||
---
|
||||
|
||||
@@ -4086,6 +4086,12 @@
|
||||
"permission": "TEXTBOOK_UPDATE",
|
||||
"signature": "(chapterId, newIndex, parentId, textbookId) => Promise<ActionState>",
|
||||
"purpose": "章节排序"
|
||||
},
|
||||
{
|
||||
"name": "getKnowledgePointsByChapterAction",
|
||||
"permission": "TEXTBOOK_READ",
|
||||
"signature": "(chapterId, textbookId) => Promise<ActionState<KnowledgePoint[]>>",
|
||||
"purpose": "获取章节下的知识点列表（含资源归属校验）"
|
||||
}
|
||||
],
|
||||
"dataAccess": [
|
||||
@@ -4249,6 +4255,24 @@
|
||||
"updateKnowledgePointAction",
|
||||
"deleteKnowledgePointAction"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "getSubjectLabelKey",
|
||||
"signature": "(subject: string) => string",
|
||||
"purpose": "获取学科的 i18n 标签键",
|
||||
"usedBy": [
|
||||
"textbooks/components/textbook-filters.tsx",
|
||||
"textbooks/components/textbook-card.tsx"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "getGradeLabelKey",
|
||||
"signature": "(grade: string) => string",
|
||||
"purpose": "获取年级的 i18n 标签键",
|
||||
"usedBy": [
|
||||
"textbooks/components/textbook-filters.tsx",
|
||||
"textbooks/components/textbook-card.tsx"
|
||||
]
|
||||
}
|
||||
],
|
||||
"hooks": [
|
||||
@@ -4264,7 +4288,7 @@
|
||||
{
|
||||
"name": "useKnowledgePointActions",
|
||||
"file": "hooks/use-knowledge-point-actions.ts",
|
||||
"signature": "(textbookId, selectedChapterId, selectedChapterTextbookId, highlightedKpId, setHighlightedKpId, onKpCreated?) => { editingKp, setEditingKp, editKpDialogOpen, setEditKpDialogOpen, isUpdatingKp, questionDialogOpen, setQuestionDialogOpen, targetKpForQuestion, setTargetKpForQuestion, deleteConfirmOpen, setDeleteConfirmOpen, handleCreateKnowledgePoint, requestDeleteKP, confirmDeleteKP, handleUpdateKP }",
|
||||
"signature": "(textbookId, selectedChapterId, selectedChapterTextbookId, highlightedKpId, setHighlightedKpId, onKpCreated?) => { editingKp, setEditingKp, editKpDialogOpen, setEditKpDialogOpen, isUpdatingKp, questionDialogOpen, setQuestionDialogOpen, targetKpForQuestion, setTargetKpForQuestion, deleteConfirmOpen, setDeleteConfirmOpen, handleCreateKnowledgePoint, requestDeleteKnowledgePoint, confirmDeleteKnowledgePoint, handleUpdateKnowledgePoint }",
|
||||
"purpose": "知识点操作Hook(6参数)",
|
||||
"usedBy": [
|
||||
"textbook-reader.tsx"
|
||||
@@ -4361,6 +4385,105 @@
|
||||
]
|
||||
}
|
||||
],
|
||||
"constants": [
|
||||
{
|
||||
"name": "SUBJECTS",
|
||||
"file": "constants.ts",
|
||||
"purpose": "学科常量数组"
|
||||
},
|
||||
{
|
||||
"name": "GRADES",
|
||||
"file": "constants.ts",
|
||||
"purpose": "年级常量数组"
|
||||
},
|
||||
{
|
||||
"name": "SUBJECT_COLORS",
|
||||
"file": "constants.ts",
|
||||
"purpose": "学科颜色映射"
|
||||
},
|
||||
{
|
||||
"name": "getSubjectColor",
|
||||
"file": "constants.ts",
|
||||
"signature": "(subject: string) => string",
|
||||
"purpose": "获取学科对应颜色"
|
||||
},
|
||||
{
|
||||
"name": "getSubjectLabelKey",
|
||||
"file": "constants.ts",
|
||||
"signature": "(subject: string) => string",
|
||||
"purpose": "获取学科 i18n 标签键"
|
||||
},
|
||||
{
|
||||
"name": "getGradeLabelKey",
|
||||
"file": "constants.ts",
|
||||
"signature": "(grade: string) => string",
|
||||
"purpose": "获取年级 i18n 标签键"
|
||||
}
|
||||
],
|
||||
"utils": [
|
||||
{
|
||||
"name": "sortChapters",
|
||||
"file": "utils.ts",
|
||||
"purpose": "章节排序"
|
||||
},
|
||||
{
|
||||
"name": "buildChapterTree",
|
||||
"file": "utils.ts",
|
||||
"purpose": "构建章节树（返回 ChapterTreeNode[]）"
|
||||
},
|
||||
{
|
||||
"name": "buildChapterIndex",
|
||||
"file": "utils.ts",
|
||||
"purpose": "构建章节索引 Map"
|
||||
},
|
||||
{
|
||||
"name": "findChapterParent",
|
||||
"file": "utils.ts",
|
||||
"purpose": "查找章节父节点"
|
||||
},
|
||||
{
|
||||
"name": "filterKnowledgePointsByChapter",
|
||||
"file": "utils.ts",
|
||||
"purpose": "按章节过滤知识点"
|
||||
},
|
||||
{
|
||||
"name": "normalizeOptional",
|
||||
"file": "utils.ts",
|
||||
"purpose": "可选字段归一化"
|
||||
},
|
||||
{
|
||||
"name": "highlightKnowledgePoints",
|
||||
"file": "utils.ts",
|
||||
"purpose": "高亮知识点"
|
||||
}
|
||||
],
|
||||
"graphLayout": [
|
||||
{
|
||||
"name": "computeGraphLayout",
|
||||
"file": "graph-layout.ts",
|
||||
"purpose": "知识图谱布局计算纯函数"
|
||||
}
|
||||
],
|
||||
"analytics": [
|
||||
{
|
||||
"name": "TextbookAnalytics",
|
||||
"file": "analytics.tsx",
|
||||
"type": "context",
|
||||
"purpose": "教材分析 Context"
|
||||
},
|
||||
{
|
||||
"name": "TextbookAnalyticsProvider",
|
||||
"file": "analytics.tsx",
|
||||
"type": "component",
|
||||
"purpose": "教材分析 Provider"
|
||||
},
|
||||
{
|
||||
"name": "useTextbookAnalytics",
|
||||
"file": "analytics.tsx",
|
||||
"type": "hook",
|
||||
"purpose": "教材分析 Hook"
|
||||
}
|
||||
],
|
||||
"components": [
|
||||
{
|
||||
"name": "ChapterSidebarList",
|
||||
@@ -4370,10 +4493,6 @@
|
||||
"name": "CreateChapterDialog",
|
||||
"purpose": "创建章节对话框"
|
||||
},
|
||||
{
|
||||
"name": "CreateKnowledgePointDialog",
|
||||
"purpose": "创建知识点对话框"
|
||||
},
|
||||
{
|
||||
"name": "KnowledgeGraph",
|
||||
"purpose": "知识图谱可视化"
|
||||
@@ -4387,8 +4506,8 @@
|
||||
"purpose": "知识点列表"
|
||||
},
|
||||
{
|
||||
"name": "KnowledgePointPanel",
|
||||
"purpose": "知识点面板"
|
||||
"name": "SectionErrorBoundary",
|
||||
"purpose": "章节内容错误边界（class component + i18n + router.refresh 重试）"
|
||||
},
|
||||
{
|
||||
"name": "TextbookCard",
|
||||
@@ -4415,27 +4534,25 @@
|
||||
"purpose": "教材设置对话框"
|
||||
}
|
||||
],
|
||||
"uiDeps": [
|
||||
{
|
||||
"from": "textbooks/components/knowledge-point-dialogs.tsx",
|
||||
"to": "questions/components/create-question-dialog",
|
||||
"status": "P0 待解耦（直接 import 跨模块业务组件，应改为 props/Context 注入）",
|
||||
"auditRef": "audit/textbooks-audit-report.md §2.1.1"
|
||||
}
|
||||
],
|
||||
"uiDeps": [],
|
||||
"uiDepsNote": "已通过 render prop 解耦，不再直接 import questions 模块组件",
|
||||
"knownIssues": [
|
||||
"P0 跨模块 UI 依赖：knowledge-point-dialogs.tsx 直接 import questions 模块 CreateQuestionDialog",
|
||||
"P0 前端权限硬编码：canEdit={true} 按路由写死，未用 usePermission().hasPermission()",
|
||||
"P0 全模块零 i18n：中英文文案硬编码，未接入 next-intl",
|
||||
"P1 Server Action 未校验资源归属（chapterId 是否属于 textbookId）",
|
||||
"P1 data-access 缺数据范围过滤（学生端未按年级过滤）",
|
||||
"P1 缺 Error Boundary（无 error.tsx）",
|
||||
"P1 知识点列表/弹窗重复实现（knowledge-point-panel.tsx 无调用方）",
|
||||
"P1 学科/年级选项硬编码三处且彼此不一致",
|
||||
"P1 纯逻辑未导出，零单测",
|
||||
"P2 类型断言：chapter-sidebar-list.tsx 用 ! 、knowledge-graph.tsx 用 as+!",
|
||||
"P2 删除确认不一致：textbook-settings-dialog 用 confirm()，其余用 AlertDialog"
|
||||
"i18n 覆盖率约 95%（chapter-sidebar-list 已接入，actions.ts 已接入，section-error-boundary 默认值已改英文）",
|
||||
"类型断言残留 3 处 as string",
|
||||
"P2 图谱方向键导航未实现"
|
||||
],
|
||||
"files": {
|
||||
"actions.ts": 377,
|
||||
"data-access.ts": 619,
|
||||
"types.ts": 45,
|
||||
"schema.ts": 64,
|
||||
"constants.ts": 91,
|
||||
"utils.ts": 181,
|
||||
"graph-layout.ts": 141,
|
||||
"analytics.tsx": 43,
|
||||
"hooks/use-knowledge-point-actions.ts": 121,
|
||||
"hooks/use-text-selection.ts": 57
|
||||
},
|
||||
"auditReport": "audit/textbooks-audit-report.md"
|
||||
}
|
||||
},
|
||||
@@ -5804,6 +5921,24 @@
|
||||
{
|
||||
"name": "AcademicYearClient",
|
||||
"purpose": "学年管理客户端"
|
||||
},
|
||||
{
|
||||
"name": "SchoolErrorBoundary",
|
||||
"file": "components/school-error-boundary.tsx",
|
||||
"purpose": "school 模块共享 Error Boundary（class component + i18n + router.refresh 重试），4 个页面均包裹",
|
||||
"props": "children, fallback?"
|
||||
},
|
||||
{
|
||||
"name": "SchoolListSkeleton",
|
||||
"file": "components/school-skeleton.tsx",
|
||||
"purpose": "表格加载骨架屏（animate-pulse）",
|
||||
"props": "rows?"
|
||||
},
|
||||
{
|
||||
"name": "SchoolCardSkeleton",
|
||||
"file": "components/school-skeleton.tsx",
|
||||
"purpose": "卡片加载骨架屏（animate-pulse）",
|
||||
"props": ""
|
||||
}
|
||||
],
|
||||
"hooks": [
|
||||
@@ -12938,7 +13073,13 @@
|
||||
"P1-7": "新增 4 个角色配置（TEACHER/ADMIN/STUDENT/PARENT）+ ROLE_CONFIGS 注册表",
|
||||
"P1-8": "新增 BLOCK_REGISTRY 注册表，node-edit-panel 配置驱动渲染",
|
||||
"P2-1": "5 个组件添加 role=dialog/aria-modal/aria-label",
|
||||
"P2-4": "预留 LessonPlanTracker 接口 + noopTracker 默认实现"
|
||||
"P2-4": "预留 LessonPlanTracker 接口 + noopTracker 默认实现",
|
||||
"V2-1": "Server Actions i18n + 错误码模式：12 个 Action 通过 getTranslations 翻译错误消息；Service/DataAccess 层抛出 PublishServiceError/LessonPlanDataError 错误码，Actions 层通过 PUBLISH_ERROR_KEY_MAP 翻译",
|
||||
"V2-2": "SYSTEM_TEMPLATES i18n 化：name/title 改为 i18n 键，createLessonPlan 接受 translateTitle 函数在服务端翻译后存储到 DB",
|
||||
"V2-3": "as unknown as 类型断言清零：8 处替换为显式类型映射函数（mapRowToLessonPlan/mapRowToListItem/mapRowToTemplate/mapRowToVersion）+ 类型守卫（isLessonPlanStatus/isTemplateType/isTemplateScope）",
|
||||
"V2-4": "MiniMap nodeColor 复用 lib/node-summary.ts 的 getNodeColor",
|
||||
"V2-5": "a11y 深度修复：lesson-plan-filters/exercise-block/inline-question-editor 的 select 添加 label htmlFor 关联；exercise-block 题目列表改为 ul/li；node-editor 画布添加 role=application + 键盘导航配置",
|
||||
"V2-6": "Tracker 埋点接入：新增 useLessonPlanTrackerSafe hook，在 create/save/publish/revert/duplicate/archive 6 处调用 tracker.track"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
@@ -0,0 +1,159 @@
|
||||
# 公告和消息模块审计报告 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](file:///e:/Desktop/CICD/src/modules/notifications/components/notification-list.tsx) L29 | `useTranslations("messages")` 通知组件使用 messages 命名空间 | "模块标准结构" — notifications 模块应有独立 i18n 资源 |
|
||||
| [notifications/components/notification-dropdown.tsx](file:///e:/Desktop/CICD/src/modules/notifications/components/notification-dropdown.tsx) L39 | 同上 | 同上 |
|
||||
| `src/shared/i18n/messages/` | 无 `notifications.json` 翻译文件 | 翻译文件结构不完整 |
|
||||
| [i18n/request.ts](file:///e:/Desktop/CICD/src/i18n/request.ts) | 未加载 notifications 翻译文件 | 翻译文件未注册 |
|
||||
|
||||
**后果**：通知相关文案（`notificationType.*`、`empty.noNotifications*`、`actions.markAllRead` 等）散落在 messages 命名空间，模块边界混乱，维护困难。
|
||||
|
||||
### 2.2 通知标题硬编码（P0）
|
||||
|
||||
| 位置 | 代码 | 违反规则 |
|
||||
|------|------|----------|
|
||||
| [announcements/actions.ts](file:///e:/Desktop/CICD/src/modules/announcements/actions.ts) L75 | `title: \`新公告：${announcement.title}\`` | "所有用户可见文本必须适配 i18n" |
|
||||
| [messaging/actions.ts](file:///e:/Desktop/CICD/src/modules/messaging/actions.ts) L70-71 | `title: input.subject ? \`New message: ${input.subject}\` : "New message"` | 同上 |
|
||||
|
||||
**后果**：通知标题语言固定（公告通知中文、消息通知英文），无法随 locale 切换。
|
||||
|
||||
### 2.3 AnnouncementList 过滤模式不一致（P1）
|
||||
|
||||
| 位置 | 问题 |
|
||||
|------|------|
|
||||
| [announcement-list.tsx](file:///e:/Desktop/CICD/src/modules/announcements/components/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](file:///e:/Desktop/CICD/src/modules/messaging/components/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](file:///e:/Desktop/CICD/src/modules/announcements/components/announcement-form.tsx) L70-76 | 仅显示 `res.message`，未消费 `res.errors` 字段级错误 |
|
||||
| [message-compose.tsx](file:///e:/Desktop/CICD/src/modules/messaging/components/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](file:///e:/Desktop/CICD/src/modules/notifications/components/notification-dropdown.tsx) L71 | `30_000` 硬编码 |
|
||||
| [unread-message-badge.tsx](file:///e:/Desktop/CICD/src/modules/messaging/components/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` | 修改（同步） |
|
||||
Reference in New Issue
Block a user