docs(textbooks): 新增教材模块审计报告并同步架构图
- 新增 docs/architecture/audit/textbooks-audit-report.md,覆盖三层架构、权限、i18n、类型安全、错误边界、组件复用、a11y、可测试性、性能、安全等维度的审计,并给出 P0/P1/P2 改进优先级与重构方案要点 - 同步 004 架构影响地图 §2.5:修正 actions/data-access 行数与导出函数名(移除不存在的读 Action,补充 reorderChaptersAction),补充跨模块 UI 依赖、已知问题清单 - 同步 005 架构数据 JSON:补充 getKnowledgePointOptions 跨模块接口、uiDeps、knownIssues、auditReport 字段,修正 getTextbooks/getTextbookById 的 usedBy 以包含学生端页面
This commit is contained in:
@@ -625,32 +625,44 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
|
||||
---
|
||||
|
||||
## 2.5 textbooks(教材模块)— 标杆模块
|
||||
## 2.5 textbooks(教材模块)— 标杆模块(data-access 层)
|
||||
|
||||
**职责**:教材与知识体系管理(教材/章节树形结构、知识点 CRUD、Markdown 内容编辑、知识图谱)。
|
||||
|
||||
**导出函数**:
|
||||
- Actions:`getTextbooksAction` / `getTextbookByIdAction` / `createTextbookAction` / `updateTextbookAction` / `deleteTextbookAction` / `getChaptersAction` / `createChapterAction` / `updateChapterAction` / `deleteChapterAction` / `getKnowledgePointsAction` / `createKnowledgePointAction` / `updateKnowledgePointAction` / `deleteKnowledgePointAction`
|
||||
- Data-access:与 actions 一一对应的 data-access 函数
|
||||
- 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 调用)
|
||||
|
||||
**依赖关系**:
|
||||
- 依赖:`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))
|
||||
|
||||
**已知问题**:
|
||||
- ✅ 无跨模块 DB 访问
|
||||
- ✅ 无跨模块 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 纯逻辑未导出,零单测
|
||||
|
||||
**文件清单**:
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `actions.ts` | 276 | 13 个 Server Action(标杆) |
|
||||
| `data-access.ts` | 428 | 教材/章节/知识点 CRUD |
|
||||
| `types.ts` | 79 | 类型定义 |
|
||||
| `actions.ts` | 317 | 10 个 Server Action(写操作) |
|
||||
| `data-access.ts` | 514 | 教材/章节/知识点 CRUD + 跨模块查询接口 |
|
||||
| `types.ts` | 45 | 类型定义 |
|
||||
| `schema.ts` | 64 | Zod 校验 |
|
||||
| `hooks/use-knowledge-point-actions.ts` | 121 | 知识点操作 Hook |
|
||||
| `components/*` | 12 文件 | 教材编辑/知识图谱组件 |
|
||||
| `hooks/use-text-selection.ts` | 57 | 文本选区捕获 Hook |
|
||||
| `components/*` | 11 文件 | 教材编辑/知识图谱组件 |
|
||||
|
||||
---
|
||||
|
||||
@@ -1068,11 +1080,13 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
|
||||
**导出函数**:
|
||||
- Data-access:`getChildren` / `getChildBasicInfo` / `getChildDashboardData` / `getParentDashboardData` / `verifyParentChildRelation` / `getChildNameList`(✅ v4 新增:用于详情页头部多子女切换器,一次批量查询避免 N+1)
|
||||
- Components:`ParentDashboard` / `ChildCard` / `ChildDetailHeader` / `ChildDetailPanel` / `SiblingSwitcher` / `ChildHomeworkSummary` / `ChildGradeSummary` / `ChildScheduleCard` / `ParentChildrenDataPage` / `ParentNoChildrenPage` / `ParentAttentionBanner`(v4 新增)/ `ParentAttendanceWarning`(v4 新增)/ `ParentExportButton`(v4 新增)
|
||||
- Components:`ParentDashboard` / `ChildCard` / `ChildDetailHeader` / `ChildDetailPanel` / `SiblingSwitcher` / `ChildHomeworkSummary` / `ChildHomeworkDetail`(v4 新增)/ `ChildGradeSummary` / `ChildGradeDetail`(v4 新增)/ `ChildScheduleCard` / `ParentChildrenDataPage` / `ParentNoChildrenPage` / `ParentAttentionBanner`(v4 新增)/ `ParentAttendanceWarning`(v4 新增)/ `ParentAttendanceRateCard`(v4 新增)/ `ParentAttendanceCalendar`(v4 新增)/ `ParentExportButton`(v4 新增)
|
||||
|
||||
**v4 修复(产品/UX 维度)**:
|
||||
- ✅ FEAT-G01:新增 `/parent/leave` 请假申请占位页(含 loading.tsx)
|
||||
- ✅ FEAT-G02:详情页 Schedule Tab 支持完整周课表(新增 `weeklySchedule` 字段 + `ChildWeeklyScheduleItem` 类型 + `buildWeeklySchedule` 函数)
|
||||
- ✅ FEAT-G03:详情页 Grades Tab 新增 `ChildGradeDetail` 按科目分组展示(平均分、趋势、最近成绩)
|
||||
- ✅ FEAT-G04:详情页 Homework Tab 新增 `ChildHomeworkDetail` 展示完整作业信息(状态、截止、提交时间、尝试次数)
|
||||
- ✅ FEAT-G05:考勤页新增 `ParentAttendanceWarning` 异常预警横幅(聚合缺勤/迟到/低出勤率)
|
||||
- ✅ FEAT-G06:详情页底部新增"Contact Teacher"快捷入口
|
||||
- ✅ FEAT-G07:详情页头部新增 `SiblingSwitcher` 多子女切换器
|
||||
@@ -1083,12 +1097,18 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
- ✅ LAYOUT-P05:详情页新增面包屑导航
|
||||
- ✅ LAYOUT-P07:成绩趋势图 X 轴改用序号,避免日期重叠
|
||||
- ✅ LAYOUT-P08:成绩页新增 `ParentExportButton` 导出按钮(占位)
|
||||
- ✅ LAYOUT-P09:考勤页新增 `ParentAttendanceCalendar` 月历视图(按状态着色,支持按月切换)
|
||||
- ✅ LAYOUT-P10:考勤异常高亮(与 FEAT-G05 同步实现)
|
||||
- ✅ NAV-P02:Grades/Attendance 页面描述明确职责(多子女对比 vs 单子女详情)
|
||||
- ✅ NAV-P03:详情页实现 `?tab=` 参数支持
|
||||
- ✅ NAV-P04:所有 parent 路由新增 `loading.tsx` 骨架屏 + `error.tsx` 错误边界
|
||||
- ✅ DATA-P02:成绩卡片新增 TrendIcon 进步/退步/持平标识
|
||||
- ✅ DATA-P03:排名展示新增"Top X%"百分比
|
||||
- ✅ DATA-P04:作业列表新增科目标识 Badge
|
||||
- ✅ DATA-P05:作业分数显示新增"pts"单位
|
||||
- ✅ DATA-P06:考勤页新增 `ParentAttendanceRateCard` 出勤率汇总卡片
|
||||
- ✅ HABIT-P01:仪表盘"一眼定位异常"能力(AttentionBanner 聚合)
|
||||
- ✅ HABIT-P02:待办横幅作业项直接跳转详情页 homework tab(1 次点击到达)
|
||||
- ✅ HABIT-P03:多子女切换无需返回仪表盘
|
||||
- ✅ HABIT-P06:仪表盘展示未读/待办数量
|
||||
- ✅ A11Y-P02:Overdue 状态增加 AlertTriangle 图标辅助
|
||||
@@ -1096,6 +1116,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
|
||||
- ✅ PERF-P01/P02:骨架屏 + 错误边界
|
||||
- ✅ PERF-P03:空状态新增"Contact support"引导按钮
|
||||
- ✅ PERF-P04:`ChildCard` Link 添加 `prefetch`
|
||||
- ✅ MOBILE-P03:移动端子女卡片改为水平滑动 Carousel(snap-x)
|
||||
- ✅ MOBILE-P04:作业/成绩列表项 `min-h-[44px]` 触摸区域
|
||||
|
||||
**依赖关系**:
|
||||
|
||||
Reference in New Issue
Block a user