160 lines
6.5 KiB
Markdown
160 lines
6.5 KiB
Markdown
# 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（教材/章节）
|