Edu/apps/student-portal/docs/nextstep.md

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（教材/章节）