feat(student-portal): 完成Docker构建验证+全量测试通过+nextstep下游依赖文档

apps/student-portal/docs/nextstep.md

@@ -0,0 +1,159 @@
+# Student Portal — 下游依赖工作（Next Steps）
+
+> 生成时间：2026-07-13
+> 生成者：ai14（student-portal）
+> 最近更新：2026-07-13（添加 Docker 测试验证结果）
+
+## 0. Docker 构建验证（已完成）
+
+student-portal Docker 镜像已在本地 Docker Desktop 验证通过：
+
+- **镜像名**：`edu/student-portal:test`
+- **构建命令**：`docker build -t edu/student-portal:test -f apps/student-portal/Dockerfile --build-arg NEXT_PUBLIC_API_MOCKING=disabled .`
+- **端口**：4001
+- **MSW 状态**：生产构建默认 `disabled`（无 mock 数据）
+- **健康检查**：`GET /api/health` → 200
+- **Dockerfile 改进**：
+  - 添加 `ARG NEXT_PUBLIC_API_MOCKING=disabled` 构建参数（生产默认关闭 MSW）
+  - 添加 `ARG NEXT_PUBLIC_MF_ENABLED=false` 构建参数（独立壳模式）
+  - 拷贝 `tsconfig.base.json`（TypeScript 配置基线）
+  - 拷贝 `packages/` 下 5 个 workspace 共享包源码（contracts/hooks/ui-components/ui-tokens/shared-ts）
+
+### Docker 测试结果
+
+| 验证项 | 状态 |
+|--------|------|
+| `pnpm typecheck` | ✅ 0 errors |
+| `pnpm lint` | ✅ 0 errors |
+| `pnpm test` | ✅ 481/481 passed |
+| `pnpm build`（本地） | ✅ 31 routes generated |
+| `docker build` | ✅ 镜像构建成功 |
+| `docker run` + healthcheck | ✅ /api/health 返回 200 |
+
+### 无 mock 数据运行说明
+
+生产镜像中 MSW 已禁用，所有 GraphQL 请求将走真实 API。在后端（student-bff）未就绪前：
+- 页面能正常渲染（SSR + 客户端 hydration）
+- API 调用将失败并显示错误状态（ActionState fail 信封）
+- 健康检查端点 `/api/health` 正常工作
+
+## 1. student-bff 后端实现（ai04）
+
+student-portal 前端已实现 57 个 GraphQL 操作（35 查询 + 22 变更），需要 student-bff 后端逐一实现对应 resolver。
+
+### 必须实现的 GraphQL 操作清单
+
+#### P3 核心（必须先完成）
+| 操作 | 类型 | 说明 |
+|------|------|------|
+| currentUser | query | 当前学生信息 + 权限 + 视口 |
+| myClasses | query | 我的班级列表 |
+| myExams | query | 我的考试列表 |
+| examDetail | query | 考试详情（含题目） |
+| myHomework | query | 我的作业列表 |
+| homeworkDetail | query | 作业详情 |
+| myGrades | query | 我的成绩列表 |
+| myAttendance | query | 我的考勤 |
+| studentDashboard | query | 学生仪表盘聚合 |
+| serverTime | query | 服务器时间（倒计时校正） |
+| submitHomework | mutation | 提交作业 |
+| submitExam | mutation | 提交考试（含幂等 key） |
+| saveExamDraft | mutation | 保存考试草稿 |
+| recordExamViolation | mutation | 记录防作弊违规 |
+| recordPasteEvent | mutation | 记录粘贴事件 |
+
+#### P3 扩展
+| mySchedule | query | 我的课表（周视图） |
+| studentGrowth | query | 成长曲线（vs 班级平均） |
+| assignmentAnalysis | query | 作业分析 |
+| myProfile | query | 个人资料 |
+| updateProfile | mutation | 更新个人资料 |
+| changePassword | mutation | 修改密码 |
+| requestExtension | mutation | 作业延期申请 |
+| joinClass | mutation | 加入班级 |
+| leaveClass | mutation | 退出班级 |
+
+#### P4 学习
+| textbooks | query | 教材列表 |
+| chapters | query | 章节目录 |
+| learningPath | query | 学习路径 |
+| myWeakness | query | 薄弱知识点 |
+| myTrend | query | 学习趋势 |
+| myMasterySummary | query | 掌握度概览 |
+| myDiagnosticReports | query | 诊断报告 |
+| myErrorBook | query | 错题本 |
+| addErrorBookItem | mutation | 添加错题 |
+| updateErrorBookItem | mutation | 更新错题 |
+| deleteErrorBookItem | mutation | 删除错题 |
+
+#### P5 校园生活
+| myNotifications | query | 通知列表 |
+| markAsRead | mutation | 标记已读 |
+| markAllAsRead | mutation | 全部已读 |
+| updateNotificationPreference | mutation | 更新通知偏好 |
+| announcements | query | 公告列表 |
+| announcementDetail | query | 公告详情 |
+| markAnnouncementRead | mutation | 标记公告已读 |
+| myLeaveRequests | query | 请假记录 |
+| createLeaveRequest | mutation | 创建请假 |
+| cancelLeaveRequest | mutation | 取消请假 |
+| myElectiveSelections | query | 我的选课 |
+| availableElectiveCourses | query | 可选课程 |
+| selectElectiveCourse | mutation | 选课 |
+| dropElectiveCourse | mutation | 退选 |
+| myLessonPlans | query | 课案列表 |
+| lessonPlanDetail | query | 课案详情 |
+| myCoursePlans | query | 课程计划列表 |
+| coursePlanDetail | query | 课程计划详情 |
+| myReportCard | query | 成绩报告卡 |
+| myPracticeSessions | query | 练习会话列表 |
+| startPracticeSession | query | 启动练习 |
+| submitPracticeAnswer | mutation | 提交练习答案 |
+
+### 关键约束
+- 所有 Query 不接受 `studentId` 参数，由 Resolver 从 JWT `x-user-id` 提取（ARB-019 §21.7）
+- 所有响应包裹 ActionState 信封（ok/fail/degraded 三态）
+- 路径统一为 `POST /api/v1/student/graphql`（ARB-019 §21）
+- 附件上传走 REST `POST /api/v1/student/upload`（ARB-019 §21.5 方案 A）
+
+## 2. api-gateway 路由配置（ai01）
+
+- `/api/v1/student/*` → `student-bff:3009/*`（ARB-019 §21 已裁决）
+- `/api/v1/student/upload` → 对象存储 + signed URL
+
+## 3. push-gateway WebSocket 事件（ai10）
+
+- `ExamExtended`：教师延长考试（ARB-019 §21.6 已确认）
+- `ExamForceSubmitted`：教师强制收卷（ARB-019 §21.6 已确认）
+- `ExamQuestionReordered`：教师调整题目顺序（P4 评估）
+
+## 4. 共享 schema 文件（ai04）
+
+- `packages/shared-ts/contracts/graphql/student-bff.graphql` 需创建（ARB-019 §21 已裁决）
+- 包含全部 57 个操作的 schema 定义
+
+## 5. Module Federation Shell 集成（ai02）
+
+- teacher-portal 作为 Shell 需注入 GraphQL client（`@edu/hooks` 的 `useGraphQLClient`）
+- student-portal 通过 `tryLoadShellClient` 运行时探测，Shell 未就绪时降级为独立 client
+- 当前降级路径已就绪，但 Shell 注入尚未实现
+
+## 6. 数据库 Schema（ai04）
+
+student-bff 需要的数据库表（基于 Drizzle ORM）：
+- users（学生信息）
+- classes / class_members（班级/成员）
+- exams / exam_questions / exam_submissions（考试/题目/提交）
+- homework / homework_submissions（作业/提交）
+- grade_records（成绩）
+- attendance_records（考勤）
+- notifications（通知）
+- announcements（公告）
+- error_book_items（错题本）
+- leave_requests（请假）
+- elective_courses / elective_selections（选课）
+- practice_sessions / practice_answers（自适应练习）
+- lesson_plans（课案）
+- course_plans（课程计划）
+- schedule（课表）
+- textbooks / textbook_chapters（教材/章节）