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
2026-06-22 18:43:12 +08:00
parent 6d7838a210
commit 1fe30984b6
29 changed files with 1252 additions and 351 deletions

View File

@@ -636,39 +636,50 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
**职责**:教材与知识体系管理(教材/章节树形结构、知识点 CRUD、Markdown 内容编辑、知识图谱)。
**导出函数**
- Actions10 个,均为写操作;读操作由 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 调用)
- Actions11 个,均为写操作;读操作由 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-accessP0-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-22026-06-22 审计发现):年级 CRUD 逻辑与 `grade-management` 模块重复定义,两套实现并存
- ⚠️ P0-52026-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.tsxclass component Error Boundary + i18n + router.refresh 重试)和 school-skeleton.tsxSchoolListSkeleton 表格骨架 + SchoolCardSkeleton 卡片骨架4 个页面schools/grades/departments/academic-year均已包裹 SchoolErrorBoundaryschool.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 Boundaryclass 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~~ 新增客户端分页 UIPAGE_SIZE=20ChevronLeft/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 + 客户端分页 UIPAGE_SIZE=20 |
| `components/message-list.tsx` | 消息列表(✅ P1-7使用 `useMessageSearch` hook + 客户端分页 UIPAGE_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-4fieldErrors + aria-invalid 字段级错误展示) |
| `components/unread-message-badge.tsx` | 未读消息计数徽章(侧边栏,每 60 秒轮询 `getUnreadMessageCountAction`;✅ V2-P2-1POLL_INTERVAL_MS 常量 |
**客户端行为**
- `message-list.tsx`:客户端调用 `getMessagesAction` 搜索消息useMessageSearch hook400ms 防抖,请求竞态取消)
- `unread-message-badge.tsx`:每 60 秒轮询 `getUnreadMessageCountAction` 刷新未读计数
- `message-list.tsx`:客户端调用 `getMessagesAction` 搜索消息useMessageSearch hook400ms 防抖,请求竞态取消)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-1useTranslations 命名空间从 "messages" 切换到 "notifications" |
| `components/notification-dropdown.tsx` | 通知下拉菜单(站点头部,每 30 秒轮询 `getNotificationsAction` + `getUnreadNotificationCountAction`;✅ V2-P0-1useTranslations 命名空间切换;✅ V2-P2-1POLL_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-4fieldErrors + 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/fromRfEdgesLessonPlanNode/Edge ↔ React Flow Node/Edge 映射) |
| `config/block-registry.tsx` | **配置驱动**BLOCK_REGISTRY 注册表 + getBlockComponent/isRichTextBlocknode-edit-panel 通过配置渲染 Block |
| `providers/lesson-plan-provider.tsx` | **Provider + ContextP1-5/P1-7/P2-4**LessonPlanProvider 注入数据服务/角色配置/埋点;定义 LessonPlanDataService 接口、4 个角色配置TEACHER/ADMIN/STUDENT/PARENT、ROLE_CONFIGS 注册表、LessonPlanTracker 接口 + noopTrackerhooksuseLessonPlanContextSafe返回 null 不抛错)/useLessonPlanContext/useRoleConfig/useLessonPlanService/useLessonPlanTracker |
| `providers/lesson-plan-provider.tsx` | **Provider + ContextP1-5/P1-7/P2-4/V2-6**LessonPlanProvider 注入数据服务/角色配置/埋点;定义 LessonPlanDataService 接口、4 个角色配置TEACHER/ADMIN/STUDENT/PARENT、ROLE_CONFIGS 注册表、LessonPlanTracker 接口 + noopTrackerhooksuseLessonPlanContextSafe返回 null 不抛错)/useLessonPlanContext/useRoleConfig/useLessonPlanService/useLessonPlanTracker/useLessonPlanTrackerSafeV2-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-3V2-1抛出 `LessonPlanDataError` 错误码V2-3mapRowToLessonPlan/mapRowToListItem/mapRowToTemplate 显式映射 + isLessonPlanStatus/isTemplateType/isTemplateScope 类型守卫 |
| `data-access-versions.ts` | 版本管理(创建/查询/回滚/清理V2-3mapRowToVersion 显式映射 |
| `data-access-templates.ts` | 个人模板 CRUDV2-3mapRowToTemplate 显式映射 + 类型守卫) |
| `data-access-knowledge.ts` | 按知识点/题目反查课案V2-3显式字段映射替代 `as unknown as` |
| `actions.ts` | 课案 CRUD/版本/模板 Server ActionsV2-1getTranslations i18n + 错误码捕获V2-2createLessonPlanAction 传入 translateTitle 翻译 SYSTEM_TEMPLATES |
| `actions-publish.ts` | 发布作业 Server ActionV2-1getTranslations i18n + PUBLISH_ERROR_KEY_MAP 错误码映射) |
| `actions-ai.ts` | AI 知识点建议 Server ActionV2-1i18n + 错误码) |
| `actions-kp.ts` | 知识点选项 Server ActionV2-1i18n + 错误码) |
| `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 + NodeEditPaneli18n 已接入) |
| `components/node-editor.tsx` | **节点图画布**React Flow使用 lib/rf-mappers + lib/node-summary 纯函数i18n 已接入) |
| `components/lesson-plan-card.tsx` | 课案卡片i18n 已接入V2-6duplicate/archive 调用 tracker.track |
| `components/lesson-plan-filters.tsx` | 课案筛选器i18n 已接入V2-53 个表单元素 label htmlFor 关联 |
| `components/lesson-plan-editor.tsx` | 课案编辑器(编排 NodeEditor + NodeEditPaneli18n 已接入V2-6handleManualSave 调用 tracker.track |
| `components/node-editor.tsx` | **节点图画布**React Flow使用 lib/rf-mappers + lib/node-summary 纯函数i18n 已接入V2-4MiniMap 复用 getNodeColorV2-5role=application + 键盘导航配置 |
| `components/node-edit-panel.tsx` | **侧边内容编辑面板**(配置驱动渲染 Block通过 getBlockComponent + LessonPlanErrorBoundary 包裹i18n 已接入) |
| `components/nodes/lesson-node.tsx` | **自定义节点组件**(使用 lib/node-summary 的 getNodeSummary/getNodeColori18n 已接入) |
| `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-6create 调用 tracker.track |
| `components/version-history-drawer.tsx` | 版本历史抽屉i18n 已接入V2-6revert 调用 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-5type/difficulty select label htmlFor 关联 |
| `components/publish-homework-dialog.tsx` | 发布作业对话框i18n 已接入V2-6publish 调用 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.reloadi18n 已接入) |
| `components/blocks/exercise-block.tsx` | 练习 Block被 NodeEditPanel 复用,使用 router.refresh 替代 window.location.reloadi18n 已接入V2-5purpose select label 关联 + 题目列表 ul/li 语义化 |
| `components/blocks/reflection-block.tsx` | 反思 Block被 NodeEditPanel 复用i18n 已接入) |
---