04b7a40bdc
- 学生域 32 页全量迁移(含作答/自动保存/提交/诊断) - 补齐 4 个 MSW mock 缺口,修 diagnostic case 名 - 修 4 处 Tailwind 任意值;新增共享组件与路由
480 lines
51 KiB
Markdown
480 lines
51 KiB
Markdown
# 教师域（Teacher）待完成功能分析
|
||
|
||
> 参考项目：`e:\desktop\CICD\src\app\(dashboard)\teacher\`（CICD 原版，53 个 page.tsx）
|
||
> 当前项目：`e:\Desktop\Edu\apps\portal-shell\src\app\shell\teacher\`（63 个 page.tsx）
|
||
> 规划依据：`apps\portal-shell\ARCHITECTURE.md` §9.1（教师域 56 页规划，B1+B2+B2末）
|
||
> 分析日期：2026-08-04
|
||
> 分析方式：逐页面读取 page.tsx 文件内容 + features/*-client.tsx 集成核查 + lib/api hooks + mocks/graphql-data.ts 覆盖核查
|
||
|
||
---
|
||
|
||
## 〇、方法论与对比基线
|
||
|
||
1. CICD 单体（Next.js App Router + Server Actions + Drizzle）作为**功能基线**，反映"老版单体已实现"的教师功能完整态。
|
||
2. portal-shell 作为**目标态**，遵循 ARCH §9.1 的契约与批次规划（B1+B2+B2末）。
|
||
3. portal-shell 普遍采用「Server Component page.tsx 仅做 `<Suspense>` 边界包裹 + Client Component `*-client.tsx` 承载业务」的统一架构；CICD 多为「Server Component 直接拉数据 + Rich Client Component 渲染」。
|
||
4. ARCH §9.1 规划 56 页，portal-shell 已实现 **63 页**（含 5 个路径别名 `/classes/my`、`/classes/my/[id]`、`/exams/all`、`/exams/create`、`/homework/assignments/create` 复用同一 client，+ 3 个占位页 `/classes/students`、`/exams/grading`、`/exams/grading/[submissionId]`，+ 2 个 ARCH §9.1 原未规划但已补做 `/exams/[id]/proctoring`、`/diagnostic/student/[studentId]`）。
|
||
5. CICD 中 `exams/page.tsx`、`classes/page.tsx`、`exams/grading/*`、`exams/create` 等为**重定向/等价路径**，不算独立功能缺口。
|
||
6. CICD 中 `diagnostic/student/[studentId]` 在 ARCH §9.1 中**原未规划**（ARCH 仅规划 `diagnostic` + `diagnostic/class/[classId]` 共 2 页），属 CICD 历史功能，portal-shell 已补做（**待同步更新 ARCH §9.1 + 004 + arch.db**）。
|
||
|
||
### 0.1 三态分类严格定义（本次核查采用）
|
||
|
||
| 状态 | 定义 | 判据 |
|
||
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
||
| ✅ 完整实现 | page.tsx 引入并渲染 `features/teacher/*-client.tsx` 客户端组件，或 page.tsx 自身包含真实业务逻辑（调用 lib/api hooks、渲染数据、处理 loading/error/empty 三态） | 文件内 `import` 了 `*-client.tsx` 并 `<XxxClient />` 渲染；或直接调用 `useXxx` hook |
|
||
| 🟡 占位空态 | page.tsx 仅用 `ListPageShell` / `DetailPageShell` / `FormPageShell` / `WorkbenchPageShell` 等 page-templates 直接渲染空态（如 `empty` 属性或无 children 内容），**没有引入任何 `*-client.tsx`，也没有真实业务逻辑** | 文件内仅 `import { ListPageShell } from "@/shared/components/page-templates"`，无 client 组件 |
|
||
| ❌ 缺失 | 文件不存在 | 路径下无 page.tsx |
|
||
|
||
> **重要说明**：本核查的"完整实现"指**页面骨架与数据流闭环**（client 组件已集成、hooks 已接入、三态已处理），**不代表与 CICD 功能完全对等**。与 CICD 的功能差距详见 §三.B（原 §3.4-§3.18 内容保留，归类为"功能差距"而非"占位空态"）。
|
||
|
||
### 0.2 配套资产核查
|
||
|
||
| 资产 | 路径 | 覆盖情况 |
|
||
| ----------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| features/teacher/*-client.tsx | `src/features/teacher/<module>/` | **55 个页面级 client 组件**（不含 dashboard-cards-client 子组件），覆盖 20 个模块，详见 §七.2 |
|
||
| lib/api hooks | `src/lib/api/<module>.ts` | **20 个模块文件**：ai/analytics/attendance/classes/course-plans/dashboard/diagnostic/elective/error-book/exams/grades/homework/knowledge-graph/leave/lesson-plans/practice/proctoring/questions/schedule-changes/students/textbooks（另含 admin/universal/sidebar/topbar/notifications/settings/profile 等共享域文件） |
|
||
| mocks/graphql-data.ts | `src/mocks/graphql-data.ts` | **269KB / 116 个 mock 数据集**（含教师域全部模块 + 学生/家长/管理域），所有占位页与功能差距页均有 MSW 兜底 |
|
||
|
||
---
|
||
|
||
## 一、页面完成度总览
|
||
|
||
| 状态 | 数量 | 说明 |
|
||
| ----------- | ------ | ---------------------------------------------------------------------------- |
|
||
| ✅ 完整实现 | **60** | page.tsx 集成 `*-client.tsx` 或自身含真实业务逻辑（lib/api hook + 三态处理） |
|
||
| 🟡 占位空态 | **3** | 仅用 page-templates 渲染空态，无 client 组件集成，无真实业务 |
|
||
| ❌ 完全缺失 | **0** | 教师域 63 个 page.tsx 全部存在 |
|
||
|
||
### 与原核查（2026-07-24）的差异
|
||
|
||
| 项目 | 原（07-24） | 现（08-04） | 变化 |
|
||
| -------- | ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||
| 总页面数 | 53 | 63 | +10（5 别名 + 3 占位 + 2 补做） |
|
||
| ✅ 完整 | 33 | 60 | +27（原 14 页"功能不完整"实为已集成 client 归入 ✅ + 新补做 2 页 + 新增别名 5 页 - 占位 3 页归 🟡 - 共享域 2 页非教师域） |
|
||
| 🟡 占位 | 14 | 3 | -11（原 14 页均集成 client 组件归 ✅；新增 3 个真占位页） |
|
||
| ❌ 缺失 | 4 | 0 | -4（proctoring 与 diagnostic/student 已补做；notifications/settings 属共享域非教师域核查范围） |
|
||
|
||
### ✅ 完整实现（60 页）
|
||
|
||
按模块分布（含别名/复用）：
|
||
|
||
| 模块 | 页面数 | 页面路径 |
|
||
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| dashboard | 1 | `/shell/teacher`（page.tsx 含 useTeacherDashboard hook + 7 张卡片 + i18n + 三态） |
|
||
| ai | 3 | `/ai/ai-assist`、`/ai/ai-lesson-plan`、`/ai/ai-report`（全 MSW，B2末工作台） |
|
||
| analytics | 2 | `/analytics`、`/analytics/[studentId]`（MSW 兜底） |
|
||
| attendance | 4 | `/attendance`、`/report`、`/sheet`、`/stats` |
|
||
| classes | 5 | `/classes`、`/classes/my`（别名）、`/classes/[id]`、`/classes/my/[id]`（别名）、`/classes/schedule` |
|
||
| course-plans | 2 | `/course-plans`、`/course-plans/[id]` |
|
||
| diagnostic | 3 | `/diagnostic`、`/diagnostic/class/[classId]`、`/diagnostic/student/[studentId]`（已补做） |
|
||
| elective | 3 | `/elective`、`/elective/create`、`/elective/[id]/edit` |
|
||
| error-book | 1 | `/error-book`（✅ errorBookItems/Stats 真实契约） |
|
||
| exams | 9 | `/exams`、`/exams/all`（别名）、`/exams/new`、`/exams/create`（别名）、`/exams/[id]`、`/exams/[id]/analytics`、`/exams/[id]/build`、`/exams/[id]/edit`、`/exams/[id]/proctoring`（已补做） |
|
||
| grades | 5 | `/grades`、`/grades/analytics`、`/grades/entry`、`/grades/report-card`、`/grades/stats` |
|
||
| homework | 8 | `/homework`、`/homework/new`、`/homework/assignments/create`（别名）、`/homework/[id]`、`/homework/assignments/[id]/submissions`、`/homework/submissions`、`/homework/submissions/[submissionId]`、`/homework/submissions/[submissionId]/scan-grading` |
|
||
| knowledge-graph | 1 | `/knowledge-graph`（B2末，混合契约 knowledgePoint ✅） |
|
||
| leave | 1 | `/leave` |
|
||
| lesson-plans | 6 | `/lesson-plans`、`/lesson-plans/new`、`/lesson-plans/calendar`、`/lesson-plans/heatmap`、`/lesson-plans/library`、`/lesson-plans/[planId]/edit` |
|
||
| practice | 1 | `/practice` |
|
||
| questions | 1 | `/questions` |
|
||
| schedule-changes | 1 | `/schedule-changes` |
|
||
| students | 1 | `/students`（原 /classes/students 已迁到顶级） |
|
||
| textbooks | 2 | `/textbooks`、`/textbooks/[id]` |
|
||
|
||
> **注**：原"🟡 已完成但功能不完整"的 14 页（dashboard、exams/page、exams/[id]、exams/new、exams/[id]/edit、exams/[id]/build、classes/[id]、classes/page、students、homework/[id]、homework/new、lesson-plans/[planId]/edit、grades/entry、attendance/sheet、diagnostic/class/[classId]）均**已集成真实 client 组件**，按本次严格三态定义归入 ✅；其与 CICD 的功能差距见 §三.B（§3.4-§3.18 保留原核查的详细对比分析）。
|
||
|
||
### 🟡 占位空态（3 页）
|
||
|
||
详见 §三.A（§3.1-§3.3）。
|
||
|
||
### ❌ 缺失（0 页）
|
||
|
||
教师域 63 个 page.tsx 全部存在，无缺失。
|
||
|
||
> **共享域说明**：原 `/shell/notifications` 与 `/shell/settings` 为 B1 共享页（非教师域独有），不属于本次教师域核查范围。如需补做，应在 `/shell/notifications/page.tsx` 与 `/shell/settings/page.tsx` 实现，供所有角色共用。
|
||
|
||
---
|
||
|
||
## 二、缺失页面清单
|
||
|
||
### 2.1 教师域缺失页面
|
||
|
||
**无缺失**。教师域 63 个 page.tsx 全部存在。
|
||
|
||
### 2.2 已补做的原"缺失"页面（相对 2026-07-24 核查）
|
||
|
||
#### 2.2.1 `/shell/teacher/exams/[id]/proctoring`（监考工作台）— ✅ 已补做
|
||
|
||
- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\teacher\exams\[id]\proctoring\page.tsx`
|
||
- **portal-shell 现状**：`exams/[id]/proctoring/page.tsx` + `features/teacher/exams/proctoring-client.tsx`
|
||
- **实现状态**：✅ page.tsx 引入 `ProctoringClient` 并 `<Suspense fallback={<WorkbenchPageSkeleton />}>` 包裹；client 组件使用 `useExamProctoring` / `useStudentProctoringStatuses` / `useRecentProctoringEvents` 三个 Apollo hook（全 MSW 兜底）；通过 5s 轮询模拟实时刷新，后端补齐 WS subscription 后切换。
|
||
- **ARCHITECTURE.md 契约**：❌（schema 无，需 WS 契约工单 + MSW 先行，已 MSW 兜底）
|
||
- **批次**：B2 末（二期，WS）— MSW 阶段已完成，待 WS 契约就绪后切换。
|
||
|
||
#### 2.2.2 `/shell/teacher/diagnostic/student/[studentId]`（学生诊断详情）— ✅ 已补做
|
||
|
||
- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\teacher\diagnostic\student\[studentId]\page.tsx`
|
||
- **portal-shell 现状**：`diagnostic/student/[studentId]/page.tsx` + `features/teacher/diagnostic/student-diagnostic-client.tsx`
|
||
- **实现状态**：✅ page.tsx 引入 `StudentDiagnosticClient` 并 `<Suspense fallback={<DetailPageSkeleton />}>` 包裹；client 组件使用 `useStudentDiagnostic` Apollo hook（MSW 兜底）。
|
||
- **ARCHITECTURE.md 契约**：🟡 `diagnosticReports` ✅ schema 真实字段，单生维度查询未明确。
|
||
- **批次**：B2（CICD 历史功能，ARCH §9.1 原未规划）— **需同步更新 ARCH §9.1 + 004 + arch.db**。
|
||
|
||
### 2.3 共享域缺口（非教师域核查范围，仅作记录）
|
||
|
||
| 路径 | 状态 | 说明 |
|
||
| ---------------------- | ------- | ------------------------------------------------------------------- |
|
||
| `/shell/notifications` | ❌ 缺失 | B1 共享，`notifications(userId)` ✅ schema 已就绪，需在共享域补页面 |
|
||
| `/shell/settings` | ❌ 缺失 | B1 共享，需在共享域补页面 |
|
||
|
||
### 2.4 不算缺失的"伪缺失"（路径合并/重定向/别名）
|
||
|
||
以下路径在 portal-shell 中通过路径合并、别名或等价入口覆盖，**不算缺失**：
|
||
|
||
| CICD 路径 | portal-shell 等价 | 说明 |
|
||
| --------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
||
| `exams/page.tsx` | `/exams/page.tsx`（ExamsListClient） | CICD 是 redirect 到 `/exams/all`，portal-shell 直接渲染列表 + 同时保留 `/exams/all` 别名 |
|
||
| `exams/all/page.tsx` | `/exams/all/page.tsx`（ExamsListClient 别名） | portal-shell 已补 `/exams/all` 别名复用 `ExamsListClient` |
|
||
| `exams/create/page.tsx` | `/exams/create/page.tsx`（NewExamClient 别名） | portal-shell 已补 `/exams/create` 别名复用 `NewExamClient` |
|
||
| `classes/page.tsx` | `/classes/page.tsx`（ClassesListClient） | CICD 是 redirect 到 `/classes/my`，portal-shell 直接渲染列表 + 同时保留 `/classes/my` 别名 |
|
||
| `classes/my/page.tsx` | `/classes/my/page.tsx`（ClassesListClient 别名） | portal-shell 已补 `/classes/my` 别名复用 `ClassesListClient` |
|
||
| `classes/my/[id]/page.tsx` | `/classes/my/[id]/page.tsx`（ClassDetailClient 别名） | portal-shell 已补 `/classes/my/[id]` 别名复用 `ClassDetailClient` |
|
||
| `classes/students/page.tsx` | `/students/page.tsx`（StudentsListClient） + `/classes/students/page.tsx`（🟡 占位） | 路径从 `/classes/students` 迁到顶级 `/students`（ARCH §9.1 规划）；旧路径保留为占位页（见 §3.1） |
|
||
| `homework/assignments/create/page.tsx` | `/homework/assignments/create/page.tsx`（NewHomeworkClient 别名） | portal-shell 已补 `/homework/assignments/create` 别名复用 `NewHomeworkClient` |
|
||
| `exams/grading/page.tsx` | 无（CICD 自身是 redirect） | CICD `grading/page.tsx` 仅 `redirect("/teacher/homework/submissions")`；portal-shell 保留为占位页（见 §3.2） |
|
||
| `exams/grading/[submissionId]/page.tsx` | 无（CICD 自身是 redirect） | 同上，仅 redirect；portal-shell 保留为占位页（见 §3.3） |
|
||
|
||
---
|
||
|
||
## 三、占位空态页面 + 与 CICD 功能差距
|
||
|
||
> 本节分两部分：
|
||
>
|
||
> - **§三.A（§3.1-§3.3）**：3 个**真占位页**（仅 page-templates 渲染空态，无 client 组件集成）— **本次核查最优先补做项**
|
||
> - **§三.B（§3.4-§3.18）**：15 个**已集成 client 但与 CICD 有功能差距**的页面 — 保留原 §3.1-§3.15 详细对比分析
|
||
|
||
### 三.A 占位空态页面（3 页，P0 优先补做）
|
||
|
||
#### 3.1 `/shell/teacher/classes/students`（班级学生列表占位）
|
||
|
||
- **路径**：`/shell/teacher/classes/students`
|
||
- **page.tsx 实现**：
|
||
|
||
```tsx
|
||
import { ListPageShell } from "@/shared/components/page-templates";
|
||
|
||
export default function ClassStudentsPage(): React.ReactElement {
|
||
return (
|
||
<ListPageShell title="班级学生" description="查看各班级学生名单" empty />
|
||
);
|
||
}
|
||
```
|
||
|
||
- **当前状态**：🟡 占位空态，仅 `ListPageShell` + `empty` 属性，无 children 内容，无 client 组件集成。
|
||
- **已有但未集成的组件**：❌ 无。`features/teacher/classes/` 仅有 `class-detail-client.tsx`、`class-schedule-client.tsx`、`classes-list-client.tsx`，**无 `class-students-client.tsx`**。
|
||
- **可用资源**：
|
||
- lib/api：`lib/api/classes.ts` 有 `useClassStudents(classId)` hook
|
||
- mocks：`graphql-data.ts` 有 `ClassStudents` mock 数据集
|
||
- 同域可复用：`/students/page.tsx` 已实现 `StudentsListClient`（顶级路由，ARCH §9.1 已迁出）
|
||
- **需要补全的内容**：
|
||
1. **方案 A（推荐）**：删除 `/classes/students/page.tsx`，统一使用顶级 `/students`（ARCH §9.1 已规划迁移）
|
||
2. **方案 B（兼容旧路径）**：改为 `redirect("/shell/teacher/students")` 重定向到顶级路由
|
||
3. **方案 C（保留独立功能）**：新建 `features/teacher/classes/class-students-client.tsx`，按 `classId` 查询展示某班学生名单（不同于顶级 `/students` 的全校学生视图）
|
||
- **建议**：方案 B（重定向）。ARCH §9.1 已明确迁移到顶级 `/students`，保留旧路径作为重定向入口即可，无需重复实现。
|
||
|
||
#### 3.2 `/shell/teacher/exams/grading`（阅卷列表占位）
|
||
|
||
- **路径**：`/shell/teacher/exams/grading`
|
||
- **page.tsx 实现**：
|
||
|
||
```tsx
|
||
import { ListPageShell } from "@/shared/components/page-templates";
|
||
|
||
export default function ExamGradingPage(): React.ReactElement {
|
||
return (
|
||
<ListPageShell
|
||
title="阅卷列表"
|
||
description="查看待批阅的考试提交"
|
||
empty
|
||
/>
|
||
);
|
||
}
|
||
```
|
||
|
||
- **当前状态**：🟡 占位空态，仅 `ListPageShell` + `empty` 属性，无 children，无 client 组件。
|
||
- **已有但未集成的组件**：❌ 无。`features/teacher/exams/` 有 7 个 client（exam-analytics、exam-build、exam-detail、exam-edit、exams-list、new-exam、proctoring），**无 `exam-grading-list-client.tsx`**。
|
||
- **可用资源**：
|
||
- lib/api：`lib/api/exams.ts` 有相关 hook；`lib/api/homework.ts` 有 `useHomeworkSubmissions` hook
|
||
- mocks：`graphql-data.ts` 有 `HomeworkSubmissions`、`ExamDetail` 等 mock 数据集
|
||
- CICD 行为：CICD `exams/grading/page.tsx` 仅 `redirect("/teacher/homework/submissions")`，无实际功能
|
||
- **需要补全的内容**：
|
||
1. **方案 A（与 CICD 一致）**：改为 `redirect("/shell/teacher/homework/submissions")` 重定向到作业提交列表
|
||
2. **方案 B（实现独立阅卷入口）**：新建 `features/teacher/exams/exam-grading-list-client.tsx`，展示待批阅的考试提交（区分于作业提交）
|
||
- **建议**：方案 A（重定向）。与 CICD 行为一致，避免重复实现；如产品需要独立的"考试阅卷"入口（区分于作业批改），再按方案 B 补做。
|
||
|
||
#### 3.3 `/shell/teacher/exams/grading/[submissionId]`（阅卷详情占位）
|
||
|
||
- **路径**：`/shell/teacher/exams/grading/[submissionId]`
|
||
- **page.tsx 实现**：
|
||
|
||
```tsx
|
||
import { DetailPageShell } from "@/shared/components/page-templates";
|
||
|
||
/**
|
||
* 阅卷详情页（ARCHITECTURE.md §7.3 详情页 / §9.1 / §10 P2）
|
||
*
|
||
* Server Component 入口：使用 DetailPageShell 直接渲染。
|
||
* 通过 /shell/teacher/exams/grading/[submissionId] 路由定位具体提交，
|
||
* 后续可接入阅卷专属 client component 进行逐题评分。
|
||
*
|
||
* 数据契约：submission(id) schema 无, MSW 兜底（@contract-pending）
|
||
*
|
||
* 关联：ARCHITECTURE.md §5.3 / §5.4 / §7.3 / §9.1 / §10 P2 / §11.3 / §11.4
|
||
*/
|
||
export default function ExamGradingDetailPage(): React.ReactElement {
|
||
return (
|
||
<DetailPageShell
|
||
title="阅卷详情"
|
||
description="批阅学生考试提交"
|
||
backHref="/shell/teacher/exams/grading"
|
||
/>
|
||
);
|
||
}
|
||
```
|
||
|
||
- **当前状态**：🟡 占位空态，仅 `DetailPageShell` + `title/description/backHref`，无 children，无 client 组件。
|
||
- **已有但未集成的组件**：❌ 无。`features/teacher/exams/` 无阅卷详情 client；阅卷能力当前在 `features/teacher/homework/submission-grading-client.tsx`（已被 `/homework/submissions/[submissionId]` 集成）。
|
||
- **可用资源**：
|
||
- lib/api：`lib/api/homework.ts` 有 `useSubmissionDetail(submissionId)` / `useGradeSubmission` hook
|
||
- mocks：`graphql-data.ts` 有 `SubmissionDetail`、`HomeworkSubmissions` mock 数据集
|
||
- 同域可复用：`/homework/submissions/[submissionId]/page.tsx` 已实现 `SubmissionGradingClient`（含逐题评分、批注、自动判分、保存草稿）
|
||
- CICD 行为：CICD `exams/grading/[submissionId]/page.tsx` 仅 `redirect("/teacher/homework/submissions")`（注意：CICD 未保留 submissionId 参数，会丢失上下文）
|
||
- **需要补全的内容**：
|
||
1. **方案 A（推荐，优于 CICD）**：改为重定向到 `/shell/teacher/homework/submissions/[submissionId]`，保留 submissionId 参数（修复 CICD 丢失参数的问题）
|
||
2. **方案 B（实现独立阅卷详情）**：新建 `features/teacher/exams/exam-grading-detail-client.tsx`，对接 `useSubmissionDetail` hook 实现考试阅卷专属视图（区别于作业批改）
|
||
- **建议**：方案 A（重定向并保留参数）。与 CICD 行为一致但修复其缺陷；如产品需要独立的考试阅卷详情视图（区分于作业批改），再按方案 B 补做。
|
||
|
||
### 三.A 小结：占位页共性特征
|
||
|
||
3 个占位页的共性：
|
||
|
||
1. **路径来源**：均为 CICD 单体中的重定向占位路径，portal-shell 迁移时保留了路径但未集成业务
|
||
2. **page-templates 直接渲染**：均仅用 `ListPageShell` / `DetailPageShell` 直接渲染空态，无 `*-client.tsx` 集成
|
||
3. **已有等价实现**：3 个占位页对应的功能均已在不同路径实现：
|
||
- `/classes/students` → 顶级 `/students`（已实现 `StudentsListClient`）
|
||
- `/exams/grading` → `/homework/submissions`（已实现 `SubmissionsListClient`）
|
||
- `/exams/grading/[submissionId]` → `/homework/submissions/[submissionId]`（已实现 `SubmissionGradingClient`）
|
||
4. **推荐统一处理**：3 个占位页均建议改为 `redirect()` 重定向到等价路径，避免重复实现
|
||
5. **优先级**：P0（占位页影响用户体验，路径存在但无内容）
|
||
|
||
---
|
||
|
||
### 三.B 与 CICD 功能差距页面（15 页，已集成 client 但与 CICD 有差距）
|
||
|
||
> 以下 15 页**均已集成 `*-client.tsx`**，按本次严格三态定义归入 ✅ 完整实现。但与 CICD 单体相比仍存在功能差距（如缺少某些子功能、操作按钮、数据维度等），保留原核查的详细对比分析供后续迭代参考。
|
||
>
|
||
> **优先级**：P1-P2（功能增强，非阻塞性）
|
||
>
|
||
> **说明**：本节为原 §3.1-§3.15 的内容保留归类。由于 60 页均已完成页面骨架与数据流闭环，本节作为后续迭代的功能增强 backlog，不再视为占位/缺失。详细页面级差距分析详见原核查记录（2026-07-24）与 CICD 源码对比，本次核查不重复展开，仅列清单：
|
||
|
||
| 序号 | 页面路径 | 集成的 client | 与 CICD 主要差距概述 |
|
||
| ---- | ------------------------------------------- | ----------------------- | ---------------------------------------------------------------- |
|
||
| 1 | `/shell/teacher`（dashboard） | dashboard-cards-client | CICD 7 张卡片含交互态；portal-shell 已对齐 7 卡 + i18n，差距较小 |
|
||
| 2 | `/shell/teacher/exams` | exams-list-client | 列表筛选维度、状态筛选、批量操作 |
|
||
| 3 | `/shell/teacher/exams/[id]` | exam-detail-client | 详情页子 Tab 数量、阅卷入口跳转 |
|
||
| 4 | `/shell/teacher/exams/new` | new-exam-client | 表单步骤、题型选择、知识点绑定 |
|
||
| 5 | `/shell/teacher/exams/[id]/edit` | exam-edit-client | 编辑权限点、草稿恢复 |
|
||
| 6 | `/shell/teacher/exams/[id]/build` | exam-build-client | 组卷策略、难度校准 |
|
||
| 7 | `/shell/teacher/classes/[id]` | class-detail-client | 详情子 Tab、学生名单 inline |
|
||
| 8 | `/shell/teacher/classes` | classes-list-client | 列表筛选、班级切换 |
|
||
| 9 | `/shell/teacher/students` | students-list-client | 学生筛选、详情抽屉 |
|
||
| 10 | `/shell/teacher/homework/[id]` | homework-detail-client | 作业详情 Tab、提交统计 |
|
||
| 11 | `/shell/teacher/homework/new` | new-homework-client | 作业类型、附件上传 |
|
||
| 12 | `/shell/teacher/lesson-plans/[planId]/edit` | lesson-plan-edit-client | 编辑器富文本、模板插入 |
|
||
| 13 | `/shell/teacher/grades/entry` | grade-entry-client | 成绩录入批量、导入导出 |
|
||
| 14 | `/shell/teacher/attendance/sheet` | attendance-sheet-client | 考勤表批量、快捷标记 |
|
||
| 15 | `/shell/teacher/diagnostic/class/[classId]` | class-diagnostic-client | 诊断维度、对比分析 |
|
||
|
||
> **后续处理建议**：本节 15 页的功能差距属 P1-P2 增强项，建议按产品优先级逐模块迭代补齐；每次补齐后运行 `pnpm run arch:scan` 同步 arch.db，并视情况更新 004 与本核查文档。
|
||
|
||
---
|
||
|
||
## 四、配套资产覆盖核查
|
||
|
||
### 4.1 features/teacher/*-client.tsx 覆盖（55 个页面级 client）
|
||
|
||
详见 §七.2（附录）。覆盖 20 个教师域模块，所有 ✅ 完整实现页均有对应 client 集成。
|
||
|
||
### 4.2 lib/api hooks 覆盖（20 个模块文件）
|
||
|
||
| 模块 | 文件 | 关键 hook |
|
||
| ---------------- | ----------------------------- | --------------------------------------------------------------------------------------------------- |
|
||
| ai | `lib/api/ai.ts` | useAiAssist / useAiLessonPlan / useAiReport |
|
||
| analytics | `lib/api/analytics.ts` | useAnalytics / useStudentAnalytics |
|
||
| attendance | `lib/api/attendance.ts` | useAttendance / useAttendanceReport / useAttendanceSheet / useAttendanceStats |
|
||
| classes | `lib/api/classes.ts` | useClasses / useClassDetail / useClassStudents / useClassSchedule |
|
||
| course-plans | `lib/api/course-plans.ts` | useCoursePlans / useCoursePlanDetail |
|
||
| dashboard | `lib/api/dashboard.ts` | useTeacherDashboard |
|
||
| diagnostic | `lib/api/diagnostic.ts` | useClassDiagnostic / useStudentDiagnostic |
|
||
| elective | `lib/api/elective.ts` | useElectiveCourses / useElectiveDetail |
|
||
| error-book | `lib/api/error-book.ts` | useErrorBookItems / useErrorBookStats |
|
||
| exams | `lib/api/exams.ts` | useExams / useExamDetail / useExamAnalytics / useExamBuild / useExamProctoring |
|
||
| grades | `lib/api/grades.ts` | useGrades / useGradeEntry / useGradeStats / useReportCard |
|
||
| homework | `lib/api/homework.ts` | useHomework / useHomeworkDetail / useHomeworkSubmissions / useSubmissionDetail / useGradeSubmission |
|
||
| knowledge-graph | `lib/api/knowledge-graph.ts` | useKnowledgeGraph |
|
||
| leave | `lib/api/leave.ts` | useLeaveRequests |
|
||
| lesson-plans | `lib/api/lesson-plans.ts` | useLessonPlans / useLessonPlanDetail / useLessonPlanCalendar / useLessonPlanHeatmap |
|
||
| practice | `lib/api/practice.ts` | usePractice |
|
||
| proctoring | `lib/api/proctoring.ts` | useStudentProctoringStatuses / useRecentProctoringEvents |
|
||
| questions | `lib/api/questions.ts` | useQuestions |
|
||
| schedule-changes | `lib/api/schedule-changes.ts` | useScheduleChanges |
|
||
| students | `lib/api/students.ts` | useStudents / useStudentDetail |
|
||
| textbooks | `lib/api/textbooks.ts` | useTextbooks / useTextbookDetail |
|
||
|
||
### 4.3 mocks/graphql-data.ts 覆盖（116 个 mock 数据集）
|
||
|
||
269KB 文件覆盖教师域全部模块（含 3 个占位页的兜底数据：`ClassStudents`、`HomeworkSubmissions`、`SubmissionDetail`、`ExamDetail`）。所有占位页与功能差距页均有 MSW 兜底。
|
||
|
||
---
|
||
|
||
## 五、结论与建议
|
||
|
||
### 5.1 总体结论
|
||
|
||
- 教师域 63 个 page.tsx **全部存在，无缺失**
|
||
- 60 页 ✅ 完整实现（集成 client + hooks + 三态处理）
|
||
- 3 页 🟡 占位空态（均为 CICD 重定向路径，建议改为 `redirect()` 重定向到等价已实现路径）
|
||
- 配套资产齐全：55 个 client 组件 + 20 个 lib/api 模块 + 116 个 mock 数据集
|
||
|
||
### 5.2 优先级建议
|
||
|
||
| 优先级 | 项目 | 工作量 | 说明 |
|
||
| --------- | ---------------------------------- | ----------------- | --------------------------------------------------------------------------------------- |
|
||
| **P0** | 3 个占位页改为 `redirect()` 重定向 | 小（每页约 5 行） | 见 §3.1-§3.3 方案 A/B，统一重定向到等价已实现路径 |
|
||
| **P1-P2** | 15 页与 CICD 功能差距补齐 | 中-大 | 见 §三.B，按产品优先级逐模块迭代 |
|
||
| **P2** | 同步更新 ARCH §9.1 + 004 + arch.db | 小 | 补做 `diagnostic/student/[studentId]` 与 `exams/[id]/proctoring` 已实现但未同步规划文档 |
|
||
|
||
### 5.3 不需补做的项
|
||
|
||
- `/shell/notifications`、`/shell/settings`：属 B1 共享域（非教师域），需在共享域补页面，不在本次教师域核查范围
|
||
- `/exams/all`、`/exams/create`、`/classes/my`、`/classes/my/[id]`、`/homework/assignments/create`：为路径别名，复用同一 client，不算缺失
|
||
|
||
---
|
||
|
||
## 六、核查元信息
|
||
|
||
- **核查日期**：2026-08-04
|
||
- **核查范围**：`apps/portal-shell/src/app/shell/teacher/` 下全部 63 个 page.tsx
|
||
- **核查方式**：逐页面读取 page.tsx 文件内容（PowerShell `Get-Content -LiteralPath`）+ features/*-client.tsx 集成核查 + lib/api hooks 覆盖核查 + mocks/graphql-data.ts 覆盖核查
|
||
- **三态判据**：见 §0.1（✅ 引入 client 或含真实业务 / 🟡 仅 page-templates 渲染空态 / ❌ 文件不存在）
|
||
- **对比基线**：`e:\desktop\CICD\src\app\(dashboard)\teacher\`（CICD 原版 53 页）
|
||
- **规划依据**：`apps/portal-shell/ARCHITECTURE.md` §9.1（教师域 56 页规划）
|
||
|
||
---
|
||
|
||
## 七、附录
|
||
|
||
### 7.1 教师域 63 个 page.tsx 完整清单
|
||
|
||
| # | 路径 | 状态 | 集成的 client |
|
||
| --- | ----------------------------------------------------------------- | ---- | ----------------------------------------------------------- |
|
||
| 1 | `/shell/teacher` | ✅ | dashboard-cards-client |
|
||
| 2 | `/shell/teacher/ai/ai-assist` | ✅ | ai-assist-client |
|
||
| 3 | `/shell/teacher/ai/ai-lesson-plan` | ✅ | ai-lesson-plan-client |
|
||
| 4 | `/shell/teacher/ai/ai-report` | ✅ | ai-report-client |
|
||
| 5 | `/shell/teacher/analytics` | ✅ | analytics-client |
|
||
| 6 | `/shell/teacher/analytics/[studentId]` | ✅ | student-analytics-client |
|
||
| 7 | `/shell/teacher/attendance` | ✅ | attendance-client |
|
||
| 8 | `/shell/teacher/attendance/report` | ✅ | attendance-report-client |
|
||
| 9 | `/shell/teacher/attendance/sheet` | ✅ | attendance-sheet-client |
|
||
| 10 | `/shell/teacher/attendance/stats` | ✅ | attendance-stats-client |
|
||
| 11 | `/shell/teacher/classes` | ✅ | classes-list-client |
|
||
| 12 | `/shell/teacher/classes/my` | ✅ | classes-list-client（别名） |
|
||
| 13 | `/shell/teacher/classes/[id]` | ✅ | class-detail-client |
|
||
| 14 | `/shell/teacher/classes/my/[id]` | ✅ | class-detail-client（别名） |
|
||
| 15 | `/shell/teacher/classes/schedule` | ✅ | class-schedule-client |
|
||
| 16 | `/shell/teacher/classes/students` | 🟡 | （占位，建议重定向到 /students） |
|
||
| 17 | `/shell/teacher/course-plans` | ✅ | course-plans-list-client |
|
||
| 18 | `/shell/teacher/course-plans/[id]` | ✅ | course-plan-detail-client |
|
||
| 19 | `/shell/teacher/diagnostic` | ✅ | diagnostic-client |
|
||
| 20 | `/shell/teacher/diagnostic/class/[classId]` | ✅ | class-diagnostic-client |
|
||
| 21 | `/shell/teacher/diagnostic/student/[studentId]` | ✅ | student-diagnostic-client |
|
||
| 22 | `/shell/teacher/elective` | ✅ | elective-list-client |
|
||
| 23 | `/shell/teacher/elective/create` | ✅ | elective-create-client |
|
||
| 24 | `/shell/teacher/elective/[id]/edit` | ✅ | elective-edit-client |
|
||
| 25 | `/shell/teacher/error-book` | ✅ | error-book-client |
|
||
| 26 | `/shell/teacher/exams` | ✅ | exams-list-client |
|
||
| 27 | `/shell/teacher/exams/all` | ✅ | exams-list-client（别名） |
|
||
| 28 | `/shell/teacher/exams/new` | ✅ | new-exam-client |
|
||
| 29 | `/shell/teacher/exams/create` | ✅ | new-exam-client（别名） |
|
||
| 30 | `/shell/teacher/exams/[id]` | ✅ | exam-detail-client |
|
||
| 31 | `/shell/teacher/exams/[id]/analytics` | ✅ | exam-analytics-client |
|
||
| 32 | `/shell/teacher/exams/[id]/build` | ✅ | exam-build-client |
|
||
| 33 | `/shell/teacher/exams/[id]/edit` | ✅ | exam-edit-client |
|
||
| 34 | `/shell/teacher/exams/[id]/proctoring` | ✅ | proctoring-client |
|
||
| 35 | `/shell/teacher/exams/grading` | 🟡 | （占位，建议重定向到 /homework/submissions） |
|
||
| 36 | `/shell/teacher/exams/grading/[submissionId]` | 🟡 | （占位，建议重定向到 /homework/submissions/[submissionId]） |
|
||
| 37 | `/shell/teacher/grades` | ✅ | grades-client |
|
||
| 38 | `/shell/teacher/grades/analytics` | ✅ | grade-analytics-client |
|
||
| 39 | `/shell/teacher/grades/entry` | ✅ | grade-entry-client |
|
||
| 40 | `/shell/teacher/grades/report-card` | ✅ | report-card-client |
|
||
| 41 | `/shell/teacher/grades/stats` | ✅ | grade-stats-client |
|
||
| 42 | `/shell/teacher/homework` | ✅ | homework-list-client |
|
||
| 43 | `/shell/teacher/homework/new` | ✅ | new-homework-client |
|
||
| 44 | `/shell/teacher/homework/assignments/create` | ✅ | new-homework-client（别名） |
|
||
| 45 | `/shell/teacher/homework/[id]` | ✅ | homework-detail-client |
|
||
| 46 | `/shell/teacher/homework/assignments/[id]/submissions` | ✅ | submissions-list-client |
|
||
| 47 | `/shell/teacher/homework/submissions` | ✅ | submissions-list-client |
|
||
| 48 | `/shell/teacher/homework/submissions/[submissionId]` | ✅ | submission-grading-client |
|
||
| 49 | `/shell/teacher/homework/submissions/[submissionId]/scan-grading` | ✅ | scan-grading-client |
|
||
| 50 | `/shell/teacher/knowledge-graph` | ✅ | knowledge-graph-client |
|
||
| 51 | `/shell/teacher/leave` | ✅ | leave-client |
|
||
| 52 | `/shell/teacher/lesson-plans` | ✅ | lesson-plans-list-client |
|
||
| 53 | `/shell/teacher/lesson-plans/new` | ✅ | new-lesson-plan-client |
|
||
| 54 | `/shell/teacher/lesson-plans/calendar` | ✅ | lesson-plan-calendar-client |
|
||
| 55 | `/shell/teacher/lesson-plans/heatmap` | ✅ | lesson-plan-heatmap-client |
|
||
| 56 | `/shell/teacher/lesson-plans/library` | ✅ | lesson-plan-library-client |
|
||
| 57 | `/shell/teacher/lesson-plans/[planId]/edit` | ✅ | lesson-plan-edit-client |
|
||
| 58 | `/shell/teacher/practice` | ✅ | practice-client |
|
||
| 59 | `/shell/teacher/questions` | ✅ | questions-client |
|
||
| 60 | `/shell/teacher/schedule-changes` | ✅ | schedule-changes-client |
|
||
| 61 | `/shell/teacher/students` | ✅ | students-list-client |
|
||
| 62 | `/shell/teacher/textbooks` | ✅ | textbooks-list-client |
|
||
| 63 | `/shell/teacher/textbooks/[id]` | ✅ | textbook-detail-client |
|
||
|
||
### 7.2 features/teacher 模块与 client 组件清单（20 模块 / 55 client）
|
||
|
||
| 模块目录 | client 组件数 | client 组件清单 |
|
||
| ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||
| ai | 3 | ai-assist / ai-lesson-plan / ai-report |
|
||
| analytics | 2 | analytics / student-analytics |
|
||
| attendance | 4 | attendance / attendance-report / attendance-sheet / attendance-stats |
|
||
| classes | 3 | classes-list / class-detail / class-schedule |
|
||
| course-plans | 2 | course-plans-list / course-plan-detail |
|
||
| dashboard | 1 | dashboard-cards |
|
||
| diagnostic | 3 | diagnostic / class-diagnostic / student-diagnostic |
|
||
| elective | 3 | elective-list / elective-create / elective-edit |
|
||
| error-book | 1 | error-book |
|
||
| exams | 7 | exams-list / new-exam / exam-detail / exam-analytics / exam-build / exam-edit / proctoring |
|
||
| grades | 5 | grades / grade-analytics / grade-entry / report-card / grade-stats |
|
||
| homework | 8 | homework-list / new-homework / homework-detail / submissions-list / submission-grading / scan-grading |
|
||
| knowledge-graph | 1 | knowledge-graph |
|
||
| leave | 1 | leave |
|
||
| lesson-plans | 6 | lesson-plans-list / new-lesson-plan / lesson-plan-calendar / lesson-plan-heatmap / lesson-plan-library / lesson-plan-edit |
|
||
| practice | 1 | practice |
|
||
| proctoring | 1 | proctoring（共享给 exams） |
|
||
| questions | 1 | questions |
|
||
| schedule-changes | 1 | schedule-changes |
|
||
| students | 1 | students-list |
|
||
| textbooks | 2 | textbooks-list / textbook-detail |
|
||
|
||
> **注**：proctoring-client 位于 `features/teacher/proctoring/`，被 `exams/[id]/proctoring/page.tsx` 集成；scan-grading-client 位于 `features/teacher/homework/`，被 `homework/submissions/[submissionId]/scan-grading/page.tsx` 集成。
|
||
|
||
---
|
||
|
||
## 八、变更历史
|
||
|
||
| 日期 | 版本 | 变更内容 |
|
||
| ---------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 2026-07-24 | v1 | 初版核查（53→63 页迁移分析） |
|
||
| 2026-08-04 | v2 | 严格三态核查（逐页读 page.tsx）：60 ✅ / 3 🟡 / 0 ❌；3 占位页改为重定向建议；15 功能差距页归 P1-P2 backlog；补全附录 §七.1 63 页完整清单 + §七.2 55 client 清单 |
|