062d9e9582
按 ARCHITECTURE.md §9.4 规划口径 + admin-NeedTodo.md §四补充批次完成管理域全量页面迁移： 【§9.4 规划 24 页（B5）】 - users(2) + roles(1) + permissions(1) + audit-logs(4) + invitation-codes(1) - school(6: redirect/schools/classes/departments/academic-year/grades) - announcements(1) + files(1) + ai-settings(1) + system(1) + viewports(1) - students(1) + teachers(1) + organization(1) + plugins(1, config-service) - 仪表盘已存在（/shell/admin/page.tsx） 【§四补充批次 21 页】 - course-plans(4) + elective(4) + questions(1) + lesson-plans(2) + error-book(1) - scheduling(3: auto/changes/rules) + attendance(1) + curriculum-map(1) - announcements 详情/编辑(2) + roles/[id] 详情(1) + users/import(1) 【实现要点】 - 全部使用 ListPageShell + loading/error/empty 三态规范（§11.3 DoD） - 走 lib/api hooks；未就绪契约走 MSW + @contract-pending 注释（§11.4） - 文案走 useTranslations（zh-CN + en 两份同步更新） - 42 个 features/<domain>/transformations.ts 纯函数 + 配套 vitest 单测 - catch 块统一 notify.error；无空 catch；lint:tokens 通过 - 路由全部登记到 route-permissions.ts（39 EXACT + 8 PREFIX） 【验收】 - tsc --noEmit: 0 errors - ESLint src: 0 errors (4 generated-files warnings, pre-existing) - lint:tokens: 0 errors - vitest: 1639/1639 passed (含 23 admin 测试文件 671 用例) - check:routes: PASS (143 routes, 4 ghost entries pre-existing) - check:pages: PASS (146 pages) - check:codegen: PASS - arch:scan: 24 modules, 8262 symbols 关联：ARCHITECTURE.md §9.4 / §10 P5 / §11.3 DoD / §11.6
333 lines
22 KiB
Markdown
333 lines
22 KiB
Markdown
# 年级组域（Management/Grade）待完成功能分析
|
||
|
||
> 参考项目：`e:\desktop\CICD\src\app\(dashboard)\management\grade\`（5 个 page.tsx）
|
||
> 当前项目：`e:\Desktop\Edu\apps\portal-shell\`（**无对应页面，全部缺失**）
|
||
> 规划依据：`apps\portal-shell\ARCHITECTURE.md` §9.5 缺口新增（5 页，B2/B5 末 N）
|
||
> 分析日期：2026-07-24
|
||
> 分析方式：逐页面读取 CICD page.tsx 源码 + 检查 portal-shell 对应路由是否存在
|
||
|
||
---
|
||
|
||
## 〇、方法论与对比基线
|
||
|
||
1. CICD 单体（Next.js App Router + Server Actions + Drizzle）作为**功能基线**，反映"老版单体已实现"的年级组功能完整态。
|
||
2. portal-shell 作为**目标态**，遵循 ARCH §9.5 的"缺口新增"规划（B2/B5 末，N=新建）。
|
||
3. CICD 的 5 个页面位于 `(dashboard)/management/grade/` 顶级路由组下，**不属于 /teacher 也不属于 /admin**，是独立的"年级组管理"维度，按 `GRADE_MANAGE` / `GRADE_RECORD_READ` / `ADAPTIVE_PRACTICE_READ` 三类权限放行。
|
||
4. CICD 的 `navigation.ts` 显示该菜单组同时出现在 `teacher` 与 `grade_head` 两个角色的导航中（permission 均为 `Permissions.GRADE_MANAGE`），即"年级组长"既可以是带 `grade_head` 角色的独立账号，也可以是普通教师被授予 `GRADE_MANAGE` 权限。
|
||
5. portal-shell 现有目录结构仅含 `/shell/{teacher|admin|student|parent|dev|forbidden}/*`，**未规划 `/shell/management/*` 独立段**，且 `route-permissions.ts` 中无任何 `management/grade` 条目。
|
||
6. ARCH §9.5 表格仅以"缺口新增"一行汇总 10 页（5 grade + 5 register/onboarding/privacy/terms），未细化每页的目标路由与契约；本文档补充细化。
|
||
|
||
---
|
||
|
||
## 一、页面完成度总览
|
||
|
||
| 状态 | 数量 | 说明 |
|
||
| ------- | ---- | -------------------------------------- |
|
||
| ❌ 缺失 | 5 | 5 个页面在 portal-shell 中均无对应实现 |
|
||
| 🟡 部分 | 0 | — |
|
||
| ✅ 完成 | 0 | — |
|
||
|
||
> portal-shell 路径检查：`apps/portal-shell/src/app/shell/**/management/**` 与 `apps/portal-shell/src/app/shell/**/grade/**` Glob 均返回 "No file found"。`route-permissions.ts` 亦无 `management` / `grade` 关键字命中。
|
||
|
||
---
|
||
|
||
## 二、缺失页面清单
|
||
|
||
### 2.1 年级组入口重定向（page.tsx）
|
||
|
||
- **CICD 路径**：`e:\desktop\CICD\src\app\(dashboard)\management\grade\page.tsx`
|
||
- **建议目标路由**：`/shell/teacher/management/grade`（见 §三角色归属分析）
|
||
- **功能描述**：空页面入口，仅做权限校验与重定向：
|
||
- `await requirePermission(Permissions.GRADE_MANAGE)` — 校验年级管理权限
|
||
- `redirect("/management/grade/classes")` — 重定向到班级列表页
|
||
- **技术栈**：
|
||
- Next.js `redirect` (from `next/navigation`)
|
||
- `requirePermission` 共享鉴权工具（`@/shared/lib/auth-guard`）
|
||
- `Permissions.GRADE_MANAGE` 权限位（`grade:manage`）
|
||
- `export const dynamic = "force-dynamic"` — 强制动态渲染（避免静态缓存鉴权信息）
|
||
- **权限**：`GRADE_MANAGE`（`grade:manage`）— 年级组长专属权限
|
||
- **ARCHITECTURE.md 契约**：❌（§9.5 缺口新增，无 GraphQL schema）
|
||
- **批次**：B2/B5 末（N）
|
||
|
||
### 2.2 年级组仪表盘（dashboard）
|
||
|
||
- **CICD 路径**：`e:\desktop\CICD\src\app\(dashboard)\management\grade\dashboard\page.tsx`
|
||
- **建议目标路由**：`/shell/teacher/management/grade/dashboard`
|
||
- **功能描述**：年级组长仪表盘，包含 4 个 Tab 切换的概览面板：
|
||
- **年级筛选器**（FilterBar + ChipNav）：拉取 `getGradesForStaff(teacherId)` 得到该教师可见年级列表，URL `?gradeId=xxx` 即时切换，无整页刷新
|
||
- **Tab distribution（成绩分布）**：调用 `getGradeDistributionByGradeId({ gradeId, scope: ctx.dataScope })`，渲染 `GradeDistributionPanel`
|
||
- **Tab homework（作业洞察）**：调用 `getGradeHomeworkInsights({ gradeId, limit: 50 })`，渲染 `GradeHomeworkPanel`
|
||
- **Tab exams（考试列表）**：调用 `getExamsByGradeId({ gradeId, scope: ctx.dataScope })`，渲染 `GradeExamsPanel`
|
||
- **Tab progress（课程计划进度）**：调用 `getGradeCoursePlanProgress({ gradeId })`，渲染 `GradeProgressPanel`
|
||
- **懒加载策略**：仅渲染当前激活 Tab 的数据（按 `tab` 参数选择性 fetch），其他 Tab 不预取
|
||
- **空状态**：无可见年级 / 未选年级 / 数据为 null 三种 EmptyState 兜底
|
||
- **错误边界**：`SectionErrorBoundary` 包裹面板区域（namespace="school"）
|
||
- **技术栈**：
|
||
- Server Component（`force-dynamic`）+ `generateMetadata` 动态标题（i18n `school.grades.gradeDashboard.*`）
|
||
- `next-intl/server` 的 `getTranslations`
|
||
- `getParam` / `SearchParams` 工具（`@/shared/lib/search-params`）
|
||
- 跨模块数据访问：`classes` / `school` / `grades` / `exams` / `course-plans` 5 个模块的 `data-access`
|
||
- 共享 UI：`FilterBar`、`ChipNav`、`EmptyState`、`SectionErrorBoundary`
|
||
- 业务组件：`modules/school/components/grade-dashboard/grade-{distribution,homework,exams,progress}-panel`
|
||
- DataScope 二次过滤：`ctx.dataScope` 传入查询，按教师可见范围过滤
|
||
- **权限**：`GRADE_RECORD_READ`（`grade_record:read`）— 比入口权限宽松，允许只读查看成绩的教师访问
|
||
- **ARCHITECTURE.md 契约**：❌（5 个 data-access 全部走 Drizzle 直查 DB，未走 GraphQL schema）
|
||
- **批次**：B2/B5 末（N）
|
||
|
||
### 2.3 年级组班级列表（classes）
|
||
|
||
- **CICD 路径**：`e:\desktop\CICD\src\app\(dashboard)\management\grade\classes\page.tsx`
|
||
- **建议目标路由**：`/shell/teacher/management/grade/classes`
|
||
- **功能描述**：年级组长管辖的班级管理页，并行拉取三组数据：
|
||
- `getGradeManagedClasses(userId)` — 该用户作为年级组长管辖的班级列表
|
||
- `getTeacherOptions()` — 教师下拉选项（用于班主任分配）
|
||
- `getManagedGrades(userId)` — 该用户管辖的年级列表
|
||
- 渲染 `GradeClassesClient` 客户端组件，承载班级 CRUD（建/删/改）交互
|
||
- **技术栈**：
|
||
- Server Component（`force-dynamic`）+ `generateMetadata`（i18n `school.classManagement.grade.*`）
|
||
- `Promise.all` 并行数据获取
|
||
- 客户端组件 `GradeClassesClient`（`modules/classes/components/grade-classes-view.tsx`）
|
||
- 客户端组件依赖：
|
||
- `createGradeClassAction` / `deleteGradeClassAction` / `updateGradeClassAction`（Server Actions，`modules/classes/actions.ts`）
|
||
- `useClassData` Hook（`modules/classes/hooks/use-class-data.ts`）
|
||
- `ClassDeleteDialog` / `ClassFormDialog` / `ClassListTable` / `ClassListToolbar`（4 个子组件）
|
||
- `ctx.userId` 用于 owner 维度过滤
|
||
- **权限**：`GRADE_MANAGE`（`grade:manage`）— 年级组长写权限
|
||
- **ARCHITECTURE.md 契约**：❌（5 个 data-access 全走 Drizzle，无 GraphQL）
|
||
- **批次**：B2/B5 末（N）
|
||
- **迁移注意**：portal-shell 现有 `/shell/teacher/classes` 是普通教师班级列表（教师授课班级），与年级组长管辖的班级列表**语义不同**（前者按 `teacherId` 关联 `class_teachers`，后者按年级组管辖范围 `grade_head`）。**不可合并**。
|
||
|
||
### 2.4 年级组作业洞察（insights）
|
||
|
||
- **CICD 路径**：`e:\desktop\CICD\src\app\(dashboard)\management\grade\insights\page.tsx`
|
||
- **建议目标路由**：`/shell/teacher/management/grade/insights`
|
||
- **功能描述**：年级组作业洞察页，单年级作业统计与班级排名：
|
||
- **年级筛选器**（FilterBar + ChipNav）：`getGradesForStaff(teacherId)` + `?gradeId=xxx` 切换
|
||
- **4 个统计卡（StatCard）**：
|
||
- 班级数（`insights.classCount`）
|
||
- 学生数（`studentCounts.total` / `active` / `inactive`）
|
||
- 整体平均分（`overallScores.avg`）
|
||
- 最近作业平均分（`insights.latest.scoreStats.avg` + 作业标题）
|
||
- **作业时间线表（Table）**：每个作业一行，列含：作业名 / 状态 / 创建时间 / 应交 / 已交 / 已批 / 平均分 / 中位数分
|
||
- **班级排名表（Table）**：每个班一行，列含：班级名（含班主任）/ 学生数 / 最近作业平均 / 上次平均 / 涨跌 / 整体平均
|
||
- **三段空状态**：无年级 / 未选 / 数据为空 / 无 insights 各自 EmptyState
|
||
- **移动端适配**：`overflow-x-auto` 包裹两个 Table（v4-P1-11）
|
||
- **技术栈**：
|
||
- Server Component（`force-dynamic`）+ `generateMetadata`（i18n `school.grades.gradeInsights.*`）
|
||
- `formatDate` / `formatNumber` 工具（`@/shared/lib/utils`）
|
||
- 共享 UI：`FilterBar` / `ChipNav` / `EmptyState` / `StatCard` / `Card` / `Badge` / `Table` 全套
|
||
- 数据访问：`getGradeHomeworkInsights({ gradeId, limit: 50 })`（`modules/classes/data-access`，limit=50）
|
||
- 辅助查询：`getTeacherIdForMutations` + `getGradesForStaff`
|
||
- 图标：`BarChart3`（lucide-react）
|
||
- **权限**：`GRADE_RECORD_READ`（`grade_record:read`）— 只读权限
|
||
- **ARCHITECTURE.md 契约**：❌（Drizzle 直查，无 GraphQL）
|
||
- **批次**：B2/B5 末（N）
|
||
|
||
### 2.5 年级组练习概览（practice）
|
||
|
||
- **CICD 路径**：`e:\desktop\CICD\src\app\(dashboard)\management\grade\practice\page.tsx`
|
||
- **建议目标路由**：`/shell/teacher/management/grade/practice`
|
||
- **功能描述**：年级组自适应练习概览页，三段式数据可视化：
|
||
- **年级筛选器**（FilterBar + ChipNav）：`getGradesForStaff(teacherId)` + `?gradeId=xxx` 切换
|
||
- **5 个统计卡（StatsGrid）**：
|
||
- 班级总数（`overview.totalClasses`，BookOpen 图标）
|
||
- 练习会话总数（`overview.totalSessions`，Activity 图标）
|
||
- 答题总数（`overview.totalQuestionsAnswered`，Target 图标）
|
||
- 平均正确率（`overview.averageAccuracy * 100`%，CheckCircle2 图标）
|
||
- 参与率（`overview.participationRate * 100`%，Users 图标）
|
||
- **班级练习对比表**：`ClassPracticeComparisonTable`（`modules/adaptive-practice/components`）渲染 `classComparison`
|
||
- **练习类型分布图**：`PracticeTypeBreakdownChart`（同模块）渲染 `typeBreakdown`
|
||
- **懒加载**：仅 `selected` 存在时执行 `Promise.all` 并行 3 查询
|
||
- **三段空状态**：无年级 / 未选 / 数据为 null 各自 EmptyState
|
||
- **技术栈**：
|
||
- Server Component（`force-dynamic`）+ `generateMetadata`（i18n `practice.grade.*`）
|
||
- 双 i18n namespace：`practice`（主）+ `school`（年级筛选器复用 `grades.gradeInsights.selectGrade`）
|
||
- 数据访问：`modules/adaptive-practice/data-access-analytics` 的 3 个查询：
|
||
- `getGradePracticeOverview(gradeId)`
|
||
- `getGradeClassPracticeComparison(gradeId)`
|
||
- `getPracticeTypeBreakdown(studentIds)` — 需要先调 `getUserIdsByGradeId(gradeId)` 取学生 ID 列表
|
||
- 共享 UI：`StatsGrid`（5 列）、`FilterBar`、`ChipNav`、`EmptyState`
|
||
- 业务组件：`ClassPracticeComparisonTable` + `PracticeTypeBreakdownChart`
|
||
- 6 个 lucide-react 图标：`Activity` / `BarChart3` / `BookOpen` / `CheckCircle2` / `Target` / `Users`
|
||
- **权限**：`ADAPTIVE_PRACTICE_READ`（`adaptive_practice:read`）— 自适应练习读权限
|
||
- **ARCHITECTURE.md 契约**：❌（Drizzle 直查，无 GraphQL）
|
||
- **批次**：B2/B5 末（N）
|
||
- **迁移注意**：CICD 的 `navigation.ts` 中 `teacher.gradeManagement` 菜单组**只列了 classes/dashboard/insights 3 项**，未列 practice 子菜单。但 page.tsx 实际存在，应作为隐藏/直接 URL 访问入口保留。
|
||
|
||
---
|
||
|
||
## 三、角色归属分析
|
||
|
||
### 3.1 CICD 中的权限校验
|
||
|
||
| 页面 | requirePermission | 权限语义 |
|
||
| --------------- | ------------------------------------ | ---------------- |
|
||
| page.tsx (入口) | `Permissions.GRADE_MANAGE` | 年级组管理（写） |
|
||
| classes | `Permissions.GRADE_MANAGE` | 年级组管理（写） |
|
||
| dashboard | `Permissions.GRADE_RECORD_READ` | 成绩记录读 |
|
||
| insights | `Permissions.GRADE_RECORD_READ` | 成绩记录读 |
|
||
| practice | `Permissions.ADAPTIVE_PRACTICE_READ` | 自适应练习读 |
|
||
|
||
> 5 个页面共用 3 类权限，无 `admin:*` 权限校验。**年级组页面是"年级组长"维度，不属于"管理员"维度**。
|
||
|
||
### 3.2 CICD 导航归属
|
||
|
||
`e:\desktop\CICD\src\modules\layout\config\navigation.ts` 中：
|
||
|
||
- `teacher` 角色菜单组：包含 `teacher.gradeManagement`（permission=`GRADE_MANAGE`），子项含 classes/dashboard/insights
|
||
- `grade_head` 角色菜单组：同样包含 `teacher.gradeManagement`，子项相同
|
||
- 两个角色都把年级组放在**与"teacher.grades"（成绩录入）平级**的位置，不在 `admin.*` 之下
|
||
|
||
### 3.3 portal-shell 角色与目录约定
|
||
|
||
- `apps\portal-shell\ARCHITECTURE.md` §9.1 教师域规划到 `/shell/teacher/*`，§9.4 管理域规划到 `/shell/admin/*`
|
||
- portal-shell 现有目录仅 `/shell/{teacher|admin|student|parent|dev|forbidden}/*`，无独立 `grade-head` 段
|
||
- `src/middleware.ts` 默认合成身份为 `role: "teacher"`，未对 `grade_head` 角色做特殊路由分发
|
||
- `src/shared/lib/route-permissions.ts` 中无 `management` / `grade` 路由条目（需新增）
|
||
|
||
### 3.4 建议归属
|
||
|
||
**推荐方案：归入教师域子路径** `/shell/teacher/management/grade/*`
|
||
|
||
理由：
|
||
|
||
1. CICD 在 `teacher` 与 `grade_head` 两角色菜单中都把"年级组管理"挂在教师主菜单下，语义上是"教师的扩展职责"
|
||
2. portal-shell 已有 `/shell/teacher/*` 体系，复用其布局壳、middleware 身份合成、route-permissions 表
|
||
3. 避免新建 `/shell/grade-head/*` 顶层段（会带来 sidebar 配置、middleware 分发、layout 重复实现等成本）
|
||
4. 路由权限按 `GRADE_MANAGE` / `GRADE_RECORD_READ` / `ADAPTIVE_PRACTICE_READ` 精确声明，与角色解耦——拥有这些权限位的教师（无论 role 字段是 `teacher` 还是 `grade_head`）都可访问
|
||
|
||
**备选方案**：若后续 portal-shell 引入 `grade_head` 独立角色段，可平滑迁移到 `/shell/grade-head/*`（page.tsx 实现完全可复用，仅需调整路由前缀）。
|
||
|
||
**目标路由建议**：
|
||
|
||
| CICD 源路径 | 建议目标路由 | 权限 |
|
||
| ----------------------------- | ------------------------------------------- | ------------------------ |
|
||
| `/management/grade` | `/shell/teacher/management/grade` | `GRADE_MANAGE` |
|
||
| `/management/grade/classes` | `/shell/teacher/management/grade/classes` | `GRADE_MANAGE` |
|
||
| `/management/grade/dashboard` | `/shell/teacher/management/grade/dashboard` | `GRADE_RECORD_READ` |
|
||
| `/management/grade/insights` | `/shell/teacher/management/grade/insights` | `GRADE_RECORD_READ` |
|
||
| `/management/grade/practice` | `/shell/teacher/management/grade/practice` | `ADAPTIVE_PRACTICE_READ` |
|
||
|
||
---
|
||
|
||
## 四、迁移注意事项
|
||
|
||
### 4.1 契约缺口（5 页全部 ❌）
|
||
|
||
5 个页面的数据访问在 CICD 中**全部走 Drizzle ORM 直查 DB**，未通过 GraphQL schema。迁移到 portal-shell 时按 ARCH §9.5 "节奏原则"处理：
|
||
|
||
- **MSW 先行**：用 Mock Service Worker 提供假数据，先把 5 个页面的 UI 跑起来
|
||
- **契约工单**：向后端开 5 类查询的 GraphQL schema 工单
|
||
- `gradeManagedClasses(userId)` + `managedGrades(userId)` + `teacherOptions()`
|
||
- `gradesForStaff(teacherId)`（年级列表）
|
||
- `gradeDistributionByGradeId(gradeId, scope)` + `gradeHomeworkInsights(gradeId, limit)` + `examsByGradeId(gradeId, scope)` + `gradeCoursePlanProgress(gradeId)`
|
||
- `gradePracticeOverview(gradeId)` + `gradeClassPracticeComparison(gradeId)` + `practiceTypeBreakdown(studentIds)` + `userIdsByGradeId(gradeId)`
|
||
- **切换策略**：契约就绪后，只改 hook 的 fetcher 指向（从 MSW 切到 Apollo Client），页面不动
|
||
|
||
### 4.2 跨模块依赖（5 个领域模块）
|
||
|
||
年级组页面是**跨模块聚合页**，依赖 5 个领域模块的 data-access：
|
||
|
||
| 依赖模块 | 用到的查询 |
|
||
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||
| `classes` | `getGradeManagedClasses` / `getManagedGrades` / `getTeacherIdForMutations` / `getGradeHomeworkInsights` / `getTeacherOptions` |
|
||
| `school` | `getGradesForStaff` |
|
||
| `grades` | `getGradeDistributionByGradeId` |
|
||
| `exams` | `getExamsByGradeId` |
|
||
| `course-plans` | `getGradeCoursePlanProgress` |
|
||
| `adaptive-practice` | `getGradePracticeOverview` / `getGradeClassPracticeComparison` / `getPracticeTypeBreakdown` |
|
||
| `users` | `getUserIdsByGradeId` |
|
||
|
||
迁移时需确保 portal-shell 对应的 7 个领域模块契约齐备或 MSW 兜底覆盖。
|
||
|
||
### 4.3 DataScope 二次过滤
|
||
|
||
CICD 的 `requirePermission` 返回 `ctx.dataScope`，传入 `getGradeDistributionByGradeId` 和 `getExamsByGradeId` 进行**数据范围二次过滤**（按教师可见的年级/班级范围裁剪结果）。
|
||
|
||
portal-shell 中需在 hook 层保留 dataScope 参数，避免越权读取非管辖年级数据。
|
||
|
||
### 4.4 i18n 命名空间
|
||
|
||
5 个页面用到 3 个 i18n namespace：
|
||
|
||
- `school`（dashboard / classes / insights 主命名空间）
|
||
- `practice`（practice 页主命名空间）
|
||
- `school.grades.gradeInsights.selectGrade`（practice 页复用）
|
||
|
||
迁移时需将 CICD 的 `messages/zh-CN/school.json` / `practice.json` 中相关键同步到 portal-shell 的 i18n 资源。
|
||
|
||
### 4.5 业务组件迁移
|
||
|
||
以下业务组件需要从 CICD 迁移到 portal-shell（按页面分组）：
|
||
|
||
| 页面 | 组件 | 来源模块 |
|
||
| --------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
|
||
| dashboard | `GradeDistributionPanel` / `GradeHomeworkPanel` / `GradeExamsPanel` / `GradeProgressPanel` | `modules/school/components/grade-dashboard` |
|
||
| classes | `GradeClassesClient` + 4 个子组件（`ClassDeleteDialog` / `ClassFormDialog` / `ClassListTable` / `ClassListToolbar`） | `modules/classes/components` |
|
||
| practice | `ClassPracticeComparisonTable` / `PracticeTypeBreakdownChart` | `modules/adaptive-practice/components` |
|
||
| insights | 仅用共享 UI（StatCard / Card / Table），无业务组件 | — |
|
||
|
||
### 4.6 route-permissions.ts 同步
|
||
|
||
迁移完成后需在 `apps/portal-shell/src/shared/lib/route-permissions.ts` 新增 5 条路由权限声明：
|
||
|
||
```ts
|
||
// 示例（实际实现时按真实 schema 编写）
|
||
"/shell/teacher/management/grade": { permission: "grade:manage", ... },
|
||
"/shell/teacher/management/grade/classes": { permission: "grade:manage", ... },
|
||
"/shell/teacher/management/grade/dashboard": { permission: "grade_record:read", ... },
|
||
"/shell/teacher/management/grade/insights": { permission: "grade_record:read", ... },
|
||
"/shell/teacher/management/grade/practice": { permission: "adaptive_practice:read", ... },
|
||
```
|
||
|
||
### 4.7 ARCHITECTURE.md 与 arch.db 同步
|
||
|
||
按 `e:\Desktop\Edu\.trae\rules\project_rules.md` §1.3「改码必同步图」要求：
|
||
|
||
- 完成 5 页迁移后运行 `pnpm run arch:scan` 更新 arch.db
|
||
- 在 `apps/portal-shell/ARCHITECTURE.md` §9.5 表格中将"缺口新增"行的"契约已就绪"列从 `0` 更新为实际就绪数（按契约工单进度）
|
||
- 在 `docs/troubleshooting/known-issues.md` 对应模块分区追加"场景→技术"映射（索引式一行，不标 AI 身份）
|
||
|
||
### 4.8 批次与顺序
|
||
|
||
按 ARCH §9.5 规划，5 页归入 **B2/B5 末** 批次：
|
||
|
||
- **B2 末**（教师域二期，与教师主功能一起补齐）：classes / dashboard / insights — 因 CICD navigation 中挂在 `teacher.gradeManagement` 菜单下
|
||
- **B5 末**（管理域，与管理员功能一起补齐）：practice — 因 CICD navigation 未列 practice 子项，按独立入口处理
|
||
|
||
**推荐实施顺序**（依赖从轻到重）：
|
||
|
||
1. `page.tsx`（入口重定向，最简单，0 数据访问）
|
||
2. `insights`（仅查 1 个 data-access + 共享 UI）
|
||
3. `classes`（3 个 data-access + 1 客户端组件 + 4 子组件）
|
||
4. `dashboard`（4 个 data-access + 4 业务面板组件）
|
||
5. `practice`（3 个 data-access + 2 业务组件 + 1 辅助查询）
|
||
|
||
---
|
||
|
||
## 五、附录：CICD 文件清单
|
||
|
||
```
|
||
e:\desktop\CICD\src\app\(dashboard)\management\grade\
|
||
├─ page.tsx # 入口重定向 → /classes
|
||
├─ error.tsx # 错误边界
|
||
├─ loading.tsx # 加载骨架
|
||
├─ classes\
|
||
│ ├─ page.tsx # 年级组班级列表
|
||
│ ├─ error.tsx
|
||
│ └─ loading.tsx
|
||
├─ dashboard\
|
||
│ ├─ page.tsx # 年级组仪表盘（4 Tab）
|
||
│ └─ loading.tsx
|
||
├─ insights\
|
||
│ ├─ page.tsx # 年级组作业洞察
|
||
│ ├─ error.tsx
|
||
│ └─ loading.tsx
|
||
└─ practice\
|
||
├─ page.tsx # 年级组练习概览
|
||
├─ error.tsx
|
||
└─ loading.tsx
|
||
```
|
||
|
||
> portal-shell 已有统一的 `loading.tsx` / `error.tsx` 模板（见 `apps/portal-shell/src/app/shell/teacher/*` 各目录），迁移时复用模板即可，无需单独迁 error/loading。
|