feat(portal-shell): 学生域全页面迁移与规范合规修复

- 学生域 32 页全量迁移(含作答/自动保存/提交/诊断) - 补齐 4 个 MSW mock 缺口,修 diagnostic case 名 - 修 4 处 Tailwind 任意值;新增共享组件与路由
2026-08-31 11:25:21 +08:00
parent 039db5efdd
commit 04b7a40bdc
493 changed files with 70985 additions and 2112 deletions
--- a/apps/portal-shell/docs/needtodo/parent-NeedTodo.md
+++ b/apps/portal-shell/docs/needtodo/parent-NeedTodo.md
@@ -1,10 +1,10 @@
-# 家长域（Parent）待完成功能分析
+# 家长域（Parent）实现完整性核查报告

-> 参考项目：`e:\desktop\CICD\src\app\(dashboard)\parent\`
+> 参考项目：`e:\Desktop\CICD\src\app\(dashboard)\parent\`
 > 当前项目：`e:\Desktop\Edu\apps\portal-shell\src\app\shell\parent\`
 > 规划依据：`apps/portal-shell/ARCHITECTURE.md` §9.3（24 页，B4 批次）
-> 分析日期：2026-07-24
-> 任务范围：仅分析，不写代码
+> 核查日期：2026-08-04
+> 任务范围：仅核查与文档更新，不修改源代码

 ---

@@ -41,6 +41,49 @@

 > **重要提示**：portal-shell 已转向微服务 + BFF 架构，迁移时**不能照搬 CICD 的 Server Action + Drizzle 直查模式**。家长页面应通过 `teacher-bff` / `data-ana` 等服务的 gRPC/HTTP API 获取数据，前端通过 hooks 消费。家长域多为**只读视图**，重点在 `myChildren` 契约 + `child-overview` 聚合。

+### 1.4 portal-shell 家长域资产核查（features / lib/api / mocks，已实际读取源码确认）
+
+#### 1.4.1 features/parent/ client 组件
+
+**`src/features/parent/` 目录不存在**。当前 `src/features/` 下仅有：`admin` / `notifications` / `settings` / `shared` / `student` / `teacher`。
+
+> **结论**：家长域**完全没有 features 层 client 组件**。CICD 中家长域依赖的模块组件（`ParentDashboard` / `ChildCard` / `ParentChildrenDataPage` / `ParentNoChildrenPage` / `ChildDetailHeader` / `SiblingSwitcher` / `StudentGradeSummary` / `GradeTrendCard` / `ReportCardView` / `ParentAttendanceCalendar` / `CoursePlanList` / `LessonPlanReadonlyView` / `StudentDiagnosticView` / `PracticeHistory` / `ParentSelectionView` / `LeaveRequestForm` 等）在 portal-shell 中**均未建立**，需在 B4 批次逐模块重建或下沉。
+
+#### 1.4.2 lib/api/ 家长相关 API hooks
+
+家长相关 hooks 分布在 2 个文件，共 **5 个 hooks**：
+
+**`src/lib/api/dashboard.ts`（1 个 hook）**：
+
+- `useParentDashboard()`：查询 `parentDashboard` 根字段，返回 `ParentDashboard | null`。operation：`GET_PARENT_DASHBOARD_DOC`，类型 `ParentDashboard` 字段 snake_case 对齐 data-ana 子图。
+
+**`src/lib/api/parent.ts`（4 个 hooks + 领域模型）**：
+
+- `useParentChildren()`：查询 `myChildren`（`GET_MY_CHILDREN_OVERVIEW_DOC`），返回 `ChildSummary[]`（含 `recentGrades` / `attendance` / `homeworkCompletion`）
+- `useLeaveRequests(childId, status)`：查询 `leaveRequests`（`GET_LEAVE_REQUESTS_DOC`），按孩子 ID 与状态筛选
+- `useApproveLeave()`：`APPROVE_LEAVE_DOC` mutation，失败抛 `ApiError`
+- `useRejectLeave()`：`REJECT_LEAVE_DOC` mutation（需 reason），失败抛 `ApiError`
+
+领域模型类型：`ChildSummary` / `ChildGrade` / `ChildAttendance` / `ChildHomeworkCompletion` / `LeaveRequest` / `LeaveType` / `LeaveStatus`
+
+operations 文件：`src/lib/api/operations/parent.graphql.ts`（4 个 document）。导出：`src/lib/api/index.ts` 第 36 行 `export * from "./parent";`。
+
+> **结论**：lib/api 层家长 hooks 已就绪 5 个（仪表盘 + 子女概览 + 请假审批链路）。§9.3 其余 18+ 页面所需 hooks（grades / report-card / exams / homework / attendance / classes / course-plans / lesson-plans / error-book / diagnostic / learning-path / practice / elective / preferences 等）**均未建立**。注：`lib/api/` 下虽有 `grades.ts` / `attendance.ts` 等同名文件，但属学生域 / 通用域 hooks，家长域多子女聚合 + 只读过滤尚未单独建模。
+
+#### 1.4.3 src/mocks/graphql-data.ts 家长相关 mock 数据
+
+| Mock 资产                        | 位置                   | 状态              | 服务对象                                                                                  |
+| -------------------------------- | ---------------------- | ----------------- | ----------------------------------------------------------------------------------------- |
+| `mockParentDashboard`            | `graphql-data.ts:84`   | ✅ 存在           | `GetParentDashboard` 查询（仪表盘页）                                                     |
+| `GetParentDashboard` case 分支   | `graphql-data.ts:5577` | ✅ 存在           | 仪表盘 hook 兜底                                                                          |
+| `mockLeaveRequests`              | `graphql-data.ts:4143` | 🟡 存在但属教师域 | `GetTeacherLeaveRequests`（教师域 B2）                                                    |
+| `GetMyChildrenOverview` mock     | —                      | ❌ **缺失**       | `useParentChildren` 无兜底                                                                |
+| `GetLeaveRequests`（家长版）mock | —                      | ❌ **缺失**       | `useLeaveRequests` 无兜底（教师版结构 `{ items, total }` 与家长版 `LeaveRequest[]` 不同） |
+| `ApproveLeave` mock              | —                      | ❌ **缺失**       | `useApproveLeave` 无兜底                                                                  |
+| `RejectLeave` mock               | —                      | ❌ **缺失**       | `useRejectLeave` 无兜底                                                                   |
+
+> **结论**：家长域 mock **仅仪表盘 1 项就绪**，`useParentChildren` / `useLeaveRequests`（家长版）/ `useApproveLeave` / `useRejectLeave` 4 个 hook 在 dev 环境**无 MSW 兜底**（会触发 Apollo 错误或空态）。需在 B4 补齐 4 个 mock，否则 dev 环境无法演示。
+
 ---

 ## 二、缺失页面清单（按模块分组）
@@ -51,7 +94,7 @@

 - **portal-shell 实现**：基础仪表盘，显示孩子平均分 / 班级排名 / 薄弱知识点 / 预警通知
 - **技术栈**：Client Component + `useParentDashboard()` Hook + `DashboardShell` / `StatCard` 共享组件
- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\dashboard\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\dashboard\page.tsx`
 - **CICD 技术栈**：Server Component + `getParentDashboardAction()` Server Action + `ParentDashboard` 视图组件 + React `use()` 流式渲染 + `generateMetadata`
 - **CICD 关键功能**：
  - 无子女时显示 `ParentNoChildrenPage` 空态
@@ -89,7 +132,7 @@

 #### 2.2.1 ❌ `/shell/parent/children/[studentId]`（子女详情页，缺失）⚠️ 重要

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\children\[studentId]\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\children\[studentId]\page.tsx`
 - **功能描述**：
  - **单个子女的完整详情视图**（家长域最核心页面）
  - **双重权限校验**：
@@ -126,7 +169,7 @@

 #### 2.3.1 ❌ `/shell/parent/grades`（子女成绩列表，缺失）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\grades\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\grades\page.tsx`
 - **功能描述**：
  - **多子女成绩对比视图**（家长域特色）
  - 每个子女一块：姓名标题 + **导出按钮**（`ParentExportButton`，按 studentId 导出）
@@ -146,7 +189,7 @@

 #### 2.3.2 ❌ `/shell/parent/grades/report-card`（子女成绩报告卡，缺失）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\grades\report-card\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\grades\report-card\page.tsx`
 - **功能描述**：
  - 学年 / 学期可切换的成绩报告卡（家长视角）
  - **必填查询参数**：`studentId`（必须在家长子女范围内）
@@ -215,7 +258,7 @@

 #### 2.6.1 ❌ `/shell/parent/attendance`（子女考勤，缺失）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\attendance\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\attendance\page.tsx`
 - **功能描述**：
  - **多子女考勤对比视图**（家长域特色）
  - 顶部 `headerExtra`：出勤率卡片（`ParentAttendanceRateCard`）+ 考勤预警（`ParentAttendanceWarning`）
@@ -253,7 +296,7 @@

 #### 2.8.1 ❌ `/shell/parent/course-plans`（课程计划列表，缺失）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\course-plans\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\course-plans\page.tsx`
 - **功能描述**：
  - 家长视角：解析**所有孩子的班级 ID**，用于过滤课程计划
  - 并行查询每个子女的活跃班级 ID（`getStudentActiveClassId`）
@@ -271,7 +314,7 @@

 #### 2.8.2 ❌ `/shell/parent/course-plans/[id]`（课程计划详情，缺失）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\course-plans\[id]\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\course-plans\[id]\page.tsx`
 - **功能描述**：
  - 家长视角：仅允许查看**孩子所在班级**的课程计划
  - 解析所有孩子的班级 ID，传入权限上下文
@@ -292,7 +335,7 @@

 #### 2.9.1 ❌ `/shell/parent/lesson-plans`（教案列表，缺失）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\lesson-plans\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\lesson-plans\page.tsx`
 - **功能描述**：
  - 家长视角：仅查看**已发布**教案（`status: "published"`）
  - 学科选项并行加载（`getSubjectOptions`）
@@ -310,7 +353,7 @@

 #### 2.9.2 ❌ `/shell/parent/lesson-plans/[planId]/view`（教案只读详情，缺失）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\lesson-plans\[planId]\view\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\lesson-plans\[planId]\view\page.tsx`
 - **功能描述**：
  - 家长视角：仅可查看**孩子所在年级**的已发布课案（V4 P0-1 修复，防跨年级信息泄露）
  - **scope 校验**：`assertPlanInScope(plan, ctx)`，失败 `notFound()`
@@ -334,7 +377,7 @@

 #### 2.10.1 ❌ `/shell/parent/error-book`（子女错题本，缺失）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\error-book\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\error-book\page.tsx`
 - **功能描述**：
  - **单/多子女分支渲染**（家长域特色）：
    - **单子女**：直接展示 `StatsGrid` 5 列统计卡片（总数 / 新增 / 学习中 / 已掌握 / 待复习）
@@ -358,7 +401,7 @@

 #### 2.11.1 ❌ `/shell/parent/diagnostic`（子女学情诊断，缺失）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\diagnostic\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\diagnostic\page.tsx`
 - **功能描述**：
  - **多子女诊断对比视图**（v4-P1-9 容错增强）
  - 预先查询所有子女姓名（`getUserNamesByIds`），用于错误卡片展示
@@ -394,7 +437,7 @@

 #### 2.13.1 ❌ `/shell/parent/practice`（子女练习查看，缺失）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\practice\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\practice\page.tsx`
 - **功能描述**：
  - **单/多子女分支渲染**（家长域特色）：
    - **单子女**：直接展示 4 列 `StatsGrid`（总练习次数 / 已完成 / 总答题数 / 正确率）+ `PracticeHistory` 历史列表
@@ -419,7 +462,7 @@

 #### 2.14.1 ❌ `/shell/parent/elective`（子女选课查看，缺失）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\elective\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\elective\page.tsx`
 - **功能描述**：
  - **多子女选课记录查看**（只读，家长不能选课）
  - 每个子女一块：`ParentSelectionView`（子女姓名 + 选课记录列表）
@@ -439,7 +482,7 @@

 #### 2.15.1 ❌ `/shell/parent/leave`（家长在线请假，缺失）

- **CICD 参考实现**：`e:\desktop\CICD\src\app\(dashboard)\parent\leave\page.tsx`
+- **CICD 参考实现**：`e:\Desktop\CICD\src\app\(dashboard)\parent\leave\page.tsx`
 - **功能描述**：
  - **家长域少有的"写"操作页面**（其他多为只读）
  - 顶部：**在线请假表单**（`LeaveRequestForm`，下拉选择子女，自动写入 classId）