xiner/NextEdu
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

feat(settings): 设置与个人信息模块审计重构 — i18n + 服务注入解耦 + Error Boundary + 流式渲染

Browse Source 
- 新增 SettingsService 接口 + Context 注入，组件层不再直接 import users/messaging actions

- 新增 resolveRoleSettingsConfig 配置驱动角色路由，删除 parent/student/teacher-settings-view 冗余文件

- 新增 SettingsSectionErrorBoundary，每个 TabsContent + profile 角色概览区块均包裹

- 新增 ProfileStudentOverview/ProfileTeacherOverview 异步 Server Component + 骨架屏，支持流式渲染

- 抽取 buildStudentOverviewData 等纯函数到 lib/student-overview-data.ts，便于单元测试

- 新增 settings.json 翻译文件（zh-CN + en），所有组件改用 useTranslations/getTranslations

- 重构 profile/page.tsx：i18n 适配 + Suspense 分区加载 + 业务逻辑抽离

- 同步更新架构图 004/005
This commit is contained in:
SpecialX
2026-06-22 16:15:36 +08:00
parent 21c7e65fee
commit 5d42495480
29 changed files with 2445 additions and 1094 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
docs/architecture/004_architecture_impact_map.md
View File

@@ -1327,17 +1327,19 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
## 2.23 settings（设置模块）
**职责**：系统设置（学校信息/安全策略/文件上传/通知配置）+ AI Provider 管理 + 密码修改 + 个人资料 + 主题偏好 + 通知偏好。
**职责**：系统设置（学校信息/安全策略/文件上传/通知配置）+ AI Provider 管理 + 密码修改 + 个人资料 + 主题偏好 + 通知偏好 + 个人信息页（学生/教师概览）。
**导出函数**：
- Actions：`getAiProvidersAction` / `createAiProviderAction` / `updateAiProviderAction` / `deleteAiProviderAction` / `testAiProviderAction`
- Actions-password：`changePasswordAction`（✅ P1 已修复：使用 `requirePermission(USER_PROFILE_UPDATE)` + Zod 校验 + DB 操作下沉到 data-access）
- Data-access：`getAiProviderSummaries` / `countDefaultAiProviders` / `getAiProviderForUpdate` / `updateAiProvider` / `createAiProvider` / `getUserPasswordHash` / `getPasswordSecurityByUserId` / `updateUserPassword` / `upsertPasswordSecurityOnPasswordChange`（P1 新增，从 actions 下沉）
- Components：`SettingsView`（P2-a 新增：统一设置页布局，消除 admin/teacher/student/parent 四个设置视图的重复布局；5 标签页 General/Notifications/Appearance/Security/AI，角色差异通过 `description` / `backHref` / `generalExtra` 三个 props 注入；Tab 通过 URL `?tab=` 参数持久化；AI 标签页条件渲染需 `AI_CONFIGURE` 权限；登出按钮使用 AlertDialog 二次确认；4 个消费方：admin/teacher/student/parent 设置页）、`ParentSettingsView`（家长设置视图，backHref 指向 `/parent/dashboard`，含家长专属快捷链接）、`AdminSettingsView`（系统设置视图，4 个 Card：学校信息/安全策略/文件上传/通知配置；消费方：`/admin/settings` 页面，权限 `SETTINGS_ADMIN`）
- Types：`AiProviderSummary` / `AiProviderName` / `AiProviderExisting`（P1 新增，从 actions.ts 迁出）
- Components：`SettingsView`（统一设置页布局，5 标签页 General/Notifications/Appearance/Security/AI；角色差异通过 `resolveRoleSettingsConfig` 配置驱动 + `generalExtra` props 注入；Tab URL 持久化；每个 TabsContent 包裹 `SettingsSectionErrorBoundary` + `Suspense` 骨架屏；AI 标签页条件渲染需 `AI_CONFIGURE` 权限）、`SettingsServiceProvider` / `useSettingsService`（Context 注入 `SettingsService` 接口，解耦组件对 users/messaging actions 的直接依赖）、`SettingsSectionErrorBoundary`（分区 Error Boundary，局部失败不影响整页）、`QuickLinksCard`（快捷链接卡片，i18n 键驱动）、`ProfileStudentOverview` / `ProfileStudentOverviewSkeleton`（学生概览异步 Server Component + 骨架屏）、`ProfileTeacherOverview` / `ProfileTeacherOverviewSkeleton`（教师概览异步 Server Component + 骨架屏）、`AdminSettingsView`（系统设置视图，4 个 Card）
- Config：`ROLE_SETTINGS_CONFIG` / `resolveRoleSettingsConfig`（配置驱动角色 → 设置视图映射，新增角色只需添加条目）
- Lib：`buildStudentOverviewData` / `computeStudentStats` / `sortUpcomingAssignments` / `filterTodaySchedule` / `toWeekday`（纯数据计算函数，与 UI 分离，便于单元测试）
- Types：`AiProviderSummary` / `AiProviderName` / `AiProviderExisting` / `SettingsService` / `ProfileService` / `NotificationPreferenceService`（服务接口定义，用于依赖注入解耦）
**依赖关系**：
- 依赖：`shared/*`（含 `shared/lib/bcrypt-utils`，✅ P2 已修复：`actions-password.ts` 删除本地 `normalizeBcryptHash`，统一复用 `shared/lib/bcrypt-utils.normalizeBcryptHash`）、`@/auth`、`messaging`（通知偏好表单调用 messaging Action）
- 依赖：`shared/*`（含 `shared/lib/bcrypt-utils`）、`@/auth`、`messaging`（页面层通过 `SettingsService` 接口注入，组件层不直接 import）、`users`（页面层通过 `SettingsService` 接口注入）、`classes` / `homework` / `dashboard`（ProfileStudentOverview 异步组件获取学生概览数据）、`notifications`（页面层获取通知偏好）
- 被依赖：无
**已知问题**：
@@ -1345,27 +1347,42 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
- ✅ P1 已修复：~~无 `data-access.ts`，`actions.ts` 直接使用 `db`~~ 新建 `data-access.ts`，所有 DB 操作已下沉
- ✅ P1 已修复：~~`changePasswordAction` 使用 `requireAuth()` 无 Zod 校验~~ 改为 `requirePermission(USER_PROFILE_UPDATE)` + `ChangePasswordSchema` Zod 校验 + 并行查询优化
- ✅ P2 已修复：`actions-password.ts` 删除本地 `normalizeBcryptHash`，统一复用 `shared/lib/bcrypt-utils.normalizeBcryptHash`，消除重复代码
- ✅ P2-a 已修复：~~admin/teacher/student 三个设置视图重复布局~~ 新增 `SettingsView` 统一设置页布局（5 标签页 + 角色差异通过 props 注入），4 个设置页改为消费 `SettingsView`
- ✅ parent 角色路由已修复：~~parent 用户被错误渲染为 TeacherSettingsView~~ 新增 `ParentSettingsView`，`/settings` 页面增加 parent 角色分支
- ✅ P2-a 已修复：~~admin/teacher/student/parent 四个设置视图重复布局~~ 新增 `SettingsView` 统一设置页布局 + `resolveRoleSettingsConfig` 配置驱动角色路由，删除 `parent-settings-view.tsx` / `student-settings-view.tsx` / `teacher-settings-view.tsx`
- ✅ parent 角色路由已修复：通过 `ROLE_SETTINGS_CONFIG` 配置驱动，parent 用户正确渲染对应配置
- ✅ Tab URL 持久化已修复：`SettingsView` 改为受控模式，通过 `useSearchParams` 读取 `tab` 参数，`router.push` 更新 URL
- ✅ 登出二次确认已修复：`SettingsView` 的 Log out 按钮使用 `AlertDialog` 包裹，点击时弹出确认对话框
- ✅ AiProviderSettingsCard 已集成：`SettingsView` 新增 AI 标签页，条件渲染需 `AI_CONFIGURE` 权限
- ✅ password-change-form 任意值 Tailwind 类已修复：~~`[&>div]:bg-red-500` 等任意值类~~ Progress 组件新增 `indicatorClassName` prop，使用标准颜色类
- ⚠️ P2：`notification-preferences-form.tsx` 跨模块 UI 依赖
- ✅ P0 已修复：~~`notification-preferences-form.tsx` 跨模块直接 import messaging/actions~~ 改为通过 `useSettingsService().notifications.updatePreferences` 调用，页面层注入实现
- ✅ P0 已修复：~~`profile-settings-form.tsx` 跨模块直接 import users/actions~~ 改为通过 `useSettingsService().profile.updateProfile` 调用，页面层注入实现
- ✅ P0 已修复：~~i18n 完全缺失~~ 新增 `settings.json` 翻译文件（zh-CN + en），所有组件改用 `useTranslations` / `getTranslations`
- ✅ P1 已修复：~~缺少 Error Boundary~~ 新增 `SettingsSectionErrorBoundary`，每个 TabsContent + profile 页面角色概览区块均包裹
- ✅ P1 已修复：~~缺少 Suspense 骨架屏~~ 每个 TabsContent 包裹 `Suspense` + `SettingsSectionSkeleton`；profile 页面包裹 `ProfileStudentOverviewSkeleton` / `ProfileTeacherOverviewSkeleton`
- ✅ P1 已修复：~~profile/page.tsx 业务逻辑与 UI 混合~~ 抽取 `buildStudentOverviewData` 等纯函数到 `lib/student-overview-data.ts`；拆分 `ProfileStudentOverview` / `ProfileTeacherOverview` 异步组件
- ✅ 密码修改有速率限制
- ✅ AI Provider 操作有 `AI_CONFIGURE` 权限校验
**文件清单**：
| 文件 | 行数 | 职责 |
|------|------|------|
| `actions.ts` | 178 | AI Provider CRUD + 测试（P1 已修复，无直接 DB 操作） |
| `actions-password.ts` | 107 | 修改密码（P1 已修复：requirePermission + Zod + data-access） |
| `data-access.ts` | 175 | AI Provider CRUD + 密码修改 DB 操作（P1 新增） |
| `types.ts` | 16 | 类型定义（P1 新增，AiProviderSummary 等） |
| `components/settings-view.tsx` | 196 | SettingsView 统一设置页布局（P2-a 新增，5 标签页 + props 注入角色差异 + Tab URL 持久化 + 登出二次确认 + AI 标签页） |
| `components/admin-settings-view.tsx` | 195 | AdminSettingsView 系统设置视图（4 个 Card：学校信息/安全策略/文件上传/通知配置，模拟保存） |
| `components/parent-settings-view.tsx` | 70 | ParentSettingsView 家长设置视图（新增，复用 SettingsView 布局） |
| `components/*` | 9 文件 | 通用设置 + AI 配置 + 密码 + 主题 + 通知偏好 + 4 角色设置视图 |
| `actions.ts` | 160 | AI Provider CRUD + 测试（P1 已修复，无直接 DB 操作） |
| `actions-password.ts` | 87 | 修改密码（P1 已修复：requirePermission + Zod + data-access） |
| `data-access.ts` | 158 | AI Provider CRUD + 密码修改 DB 操作（P1 新增） |
| `types.ts` | 60 | 类型定义（AiProviderSummary + SettingsService/ProfileService/NotificationPreferenceService 接口） |
| `config/role-settings-config.tsx` | 85 | 角色设置页配置驱动映射（ROLE_SETTINGS_CONFIG + resolveRoleSettingsConfig） |
| `lib/student-overview-data.ts` | 150 | 学生概览纯数据计算（buildStudentOverviewData + computeStudentStats 等，便于单测） |
| `components/settings-view.tsx` | 236 | SettingsView 统一设置页布局（5 标签页 + Error Boundary + Suspense + i18n） |
| `components/settings-service-context.tsx` | 39 | SettingsServiceProvider + useSettingsService（Context 注入服务接口） |
| `components/settings-section-error-boundary.tsx` | 64 | 分区 Error Boundary（局部失败不影响整页） |
| `components/quick-links-card.tsx` | 42 | 快捷链接卡片（i18n 键驱动） |
| `components/profile-student-overview.tsx` | 91 | 学生概览异步 Server Component + 骨架屏 |
| `components/profile-teacher-overview.tsx` | 115 | 教师概览异步 Server Component + 骨架屏 |
| `components/admin-settings-view.tsx` | 195 | AdminSettingsView 系统设置视图（4 个 Card，i18n） |
| `components/profile-settings-form.tsx` | 158 | 个人资料表单（通过 SettingsService 注入，i18n） |
| `components/notification-preferences-form.tsx` | ~140 | 通知偏好表单（通过 SettingsService 注入，i18n） |
| `components/password-change-form.tsx` | ~130 | 密码修改表单（i18n + a11y） |
| `components/theme-preferences-card.tsx` | ~60 | 主题偏好卡片（i18n） |
| `components/ai-provider-settings-card.tsx` | ~200 | AI 服务商配置卡片（i18n） |
---
@@ -1488,13 +1505,25 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
- ✅ 编辑器架构升级：NodeEditor（React Flow 画布）+ NodeEditPanel（侧边内容编辑面板）+ LessonNode（自定义节点组件），支持节点拖拽、连线、画布缩放
- ⚠️ `block-renderer.tsx` 标记为 @deprecated（已被 NodeEditor 替代，保留用于向后兼容）
> 架构变更（2026-06-22，本次审计修复）：
> - **P0-1 跨模块直查修复**：`publish-service.ts` 不再直接 `db.insert(examQuestions)` 和本地实现 `getStudentIdsByClassIds`，改为调用 `exams/data-access.addExamQuestions` 和 `classes/data-access.getStudentIdsByClassIds`，恢复三层架构约束
> - **P0-2 i18n 接入**：新增 `shared/i18n/messages/zh-CN/lesson-preparation.json` 和 `shared/i18n/messages/en/lesson-preparation.json`，注册 `lessonPreparation` 命名空间到 `src/i18n/request.ts`，17 个组件改造为 `useTranslations`/`getTranslations`
> - **P1 纯函数抽取**：新增 `lib/document-migration.ts`（migrateV1ToV2/normalizeDocument/buildInitialContent，使用类型守卫替代 as 断言）、`lib/node-summary.ts`（getNodeSummary + NODE_COLORS + getNodeColor，接受翻译函数注入）、`lib/rf-mappers.ts`（toRfNodes/toRfEdges/fromRfEdges），data-access.ts 改为从 lib/ 导入并 re-export 保持向后兼容
> - **P1 错误边界 + 骨架屏**：新增 `components/lesson-plan-error-boundary.tsx`（LessonPlanErrorBoundary 类组件）和 `components/lesson-plan-skeleton.tsx`（VersionListSkeleton/QuestionBankSkeleton/KnowledgePointSkeleton/LessonPlanListSkeleton）
> - **P1 Block 注册表**：新增 `config/block-registry.tsx`（BLOCK_REGISTRY 配置表 + getBlockComponent/isRichTextBlock），`node-edit-panel.tsx` 重构为配置驱动渲染，移除 if/else 链
> - **P1 window.location.reload 修复**：`exercise-block.tsx` 改用 `router.refresh()` 精确刷新缓存
**文件清单**：
| 文件 | 职责 |
|------|------|
| `types.ts` | 类型定义（含 v1/v2 文档类型、LessonPlanNode、LessonPlanEdge） |
| `constants.ts` | 常量定义 |
| `schema.ts` | Zod 验证 |
| `data-access.ts` | 课案 CRUD + 模板查询 + 初始内容构建 + v1→v2 迁移（migrateV1ToV2 / normalizeDocument） |
| `lib/document-migration.ts` | **纯函数**：v1→v2 迁移（migrateV1ToV2）/ 规范化（normalizeDocument）/ 初始内容构建（buildInitialContent），使用类型守卫 isV1Document/isV2Document 替代 as 断言 |
| `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 |
| `data-access.ts` | 课案 CRUD + 模板查询（migrateV1ToV2/normalizeDocument/buildInitialContent 从 lib/ 导入并 re-export 保持向后兼容） |
| `data-access-versions.ts` | 版本管理（创建/查询/回滚/清理） |
| `data-access-templates.ts` | 个人模板 CRUD |
| `data-access-knowledge.ts` | 按知识点/题目反查课案 |
@@ -1502,28 +1531,30 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
| `actions-publish.ts` | 发布作业 Server Action |
| `actions-ai.ts` | AI 知识点建议 Server Action |
| `actions-kp.ts` | 知识点选项 Server Action |
| `publish-service.ts` | 发布作业服务（编排 homework/exams/classes） |
| `publish-service.ts` | 发布作业服务（编排 homework/exams/classes，通过对方 data-access 调用，无直查跨模块表） |
| `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` | 课案列表 |
| `components/lesson-plan-card.tsx` | 课案卡片 |
| `components/lesson-plan-filters.tsx` | 课案筛选器 |
| `components/lesson-plan-editor.tsx` | 课案编辑器（编排 NodeEditor + NodeEditPanel） |
| `components/node-editor.tsx` | **节点图画布**（React Flow，自定义 LessonNode，支持拖拽/连线/缩放） |
| `components/node-edit-panel.tsx` | **侧边内容编辑面板**（选中节点后编辑标题/数据） |
| `components/nodes/lesson-node.tsx` | **自定义节点组件**（按 BlockType 显示图标/颜色，含 Handle 连接点） |
| `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/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` | 模板选择器 |
| `components/version-history-drawer.tsx` | 版本历史抽屉 |
| `components/knowledge-point-picker.tsx` | 知识点选择器 |
| `components/question-bank-picker.tsx` | 题库选择器 |
| `components/inline-question-editor.tsx` | 内联题目编辑器 |
| `components/publish-homework-dialog.tsx` | 发布作业对话框 |
| `components/blocks/rich-text-block.tsx` | 富文本 Block（被 NodeEditPanel 复用） |
| `components/blocks/text-study-block.tsx` | 课文研读 Block（被 NodeEditPanel 复用） |
| `components/blocks/exercise-block.tsx` | 练习 Block（被 NodeEditPanel 复用） |
| `components/blocks/reflection-block.tsx` | 反思 Block（被 NodeEditPanel 复用） |
| `components/template-picker.tsx` | 模板选择器（i18n 已接入） |
| `components/version-history-drawer.tsx` | 版本历史抽屉（i18n 已接入） |
| `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/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/reflection-block.tsx` | 反思 Block（被 NodeEditPanel 复用，i18n 已接入） |
---