xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(student-portal): 完整实现 student-portal 微前端

Browse Source 
包含 src 全部实现、Dockerfile、配置文件、contracts 包等
This commit is contained in:
SpecialX
2026-07-10 19:10:36 +08:00
parent 24c2860b41
commit 74474a2d04
80 changed files with 17226 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
docs/troubleshooting/known-issues.md
View File

@@ -482,22 +482,38 @@
> student-portal 复用 teacher-portal Shell 暴露的 AppShell / usePermission / ApiClient / ErrorBoundary / 设计令牌 / A11y 工具集，本节仅记录 student-portal **特有**的"场景→技术"映射，通用前端映射见 §2.12。
| 场景 | 技术/规则 |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| P3 端口分配 | student-portal = **4001**（004 §1.2 强制 4 端 4000-4003；ai07 初稿误用 3001 与 iam 冲突，ai14 修订） |
| P3 MF Remote 角色 | next.config.js 配 `@module-federation/nextjs-mf`（name: `student_app`，port 4001）暴露 `./pages` + `./ExamTaking`，复用 Shell 的 `AppShell`/`usePermission`/`ApiClient` |
| P3 DataScope SELF | 学生仅看自己数据（004 §5.4 L0），前端**无班级/年级/学校切换器**（与 teacher-portal L1-L5 核心差异），路由参数不含 classId/gradeId/schoolId |
| P3 错误码前缀统一 | core-edu 子域统一 `CORE_EDU_`（移除 `EXAMS_`/`HOMEWORK_`/`GRADES_` 独立前缀）；BFF 前缀 `BFF_STUDENT_`（coord §5.2 裁决，从 `STUDENT_BFF_` 迁移） |
| P3 考试防作弊 useAntiCheat | `visibilitychange` 切屏检测 + `blur` 失焦 + `copy`/`paste`/`contextmenu` 禁止 + 违规计数（maxViolations=3）+ 超限自动交卷；前端层仅辅助，最终权威由后端考试时长 + 服务端时间校准保证 |
| P3 服务器时间同步 | `useServerTimeSync` Hook：RTT 计算 `offset = (t1 + rtt/2) - serverTime` + 5min 重同步周期；`CountdownTimer` 用 `role="timer"` + `aria-live="polite"` 朗读剩余时间 |
| P3 考试作答状态机 | NotStarted→InProgress→Paused（切屏警告）→AutoSubmitting（倒计时归零）→Submitting→Submitted；Zustand L3 + localStorage 持久化草稿，自动保存每 30s + blur 时保存 |
| P3 考试页面 CSP iframe 防嵌套 | 考试路由 `frame-ancestors 'none'` + `X-Frame-Options: DENY`；其他路由允许 Shell 同源嵌入 |
| P3 考试 chunk 性能预算 | 考试作答 chunk < 200KB（动态 import 隔离）；总 Bundle < 300KB；LCP < 2.5s / CLS < 0.1 / INP < 200ms |
| P3 移动端一等公民 | 学生端高频移动场景：Tailwind 响应式断点 + viewport meta + 触摸优化（按钮 ≥ 44px）；考试页面支持横屏锁定 |
| P3 A11y 考试专项 | WCAG 2.2 AA：键盘导航作答（Tab/Enter/方向键）+ `aria-live` 倒计时 + 焦点陷阱（考试中不可 Tab 到地址栏）+ 屏幕阅读器兼容 |
| P3 考试草稿多设备同步预留 | 当前 localStorage 单设备；P5+ 预留草稿同步（LWW 冲突解决 + WebSocket 推送 + version 字段） |
| P3 Feature Flag 阶段化 | P3-P5 用环境变量（`NEXT_PUBLIC_FEATURE_*`）；P6+ 预留 Consul 配置中心动态开关 |
| P3 PWA 离线壳预留 | P5+ Service Worker 缓存考试壳，断网时仍可作答，恢复后自动提交 |
| P3 MF 降级与版本协商 | Remote `remoteEntry.js` 加载失败 → fallback 独立页面 + 错误提示；共享依赖版本不匹配 → 运行时协商降级 |
| P3 AI 答疑 SSE 流式（P5） | `POST /student/ai/stream-chat` SSE 流式响应 + `streamingText` 逐字渲染 + 打字机效果 + AbortController 取消 |
| P3 权限点命名 | 与 student-bff §3.2 对齐 `STUDENT_*_READ` 风格（`STUDENT_DASHBOARD_READ`/`STUDENT_EXAM_READ`/`STUDENT_HOMEWORK_SUBMIT`/`STUDENT_GRADE_READ` 等） |
| 场景 | 技术/规则 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| P3 端口分配 | student-portal = **4001**（004 §1.2 强制 4 端 4000-4003；ai07 初稿误用 3001 与 iam 冲突，ai14 修订） |
| P3 MF Remote 角色 | next.config.js 配 `@module-federation/nextjs-mf`（name: `student_app`，port 4001）暴露 `./pages` + `./ExamTaking`，复用 Shell 的 `AppShell`/`usePermission`/`ApiClient` |
| P3 DataScope SELF | 学生仅看自己数据（004 §5.4 L0），前端**无班级/年级/学校切换器**（与 teacher-portal L1-L5 核心差异），路由参数不含 classId/gradeId/schoolId |
| P3 错误码前缀统一 | core-edu 子域统一 `CORE_EDU_`（移除 `EXAMS_`/`HOMEWORK_`/`GRADES_` 独立前缀）；BFF 前缀 `BFF_STUDENT_`（coord §5.2 裁决，从 `STUDENT_BFF_` 迁移） |
| P3 考试防作弊 useAntiCheat | `visibilitychange` 切屏检测 + `blur` 失焦 + `copy`/`paste`/`contextmenu` 禁止 + 违规计数（maxViolations=3）+ 超限自动交卷；前端层仅辅助，最终权威由后端考试时长 + 服务端时间校准保证 |
| P3 服务器时间同步 | `useServerTimeSync` Hook：RTT 计算 `offset = (t1 + rtt/2) - serverTime` + 5min 重同步周期；`CountdownTimer` 用 `role="timer"` + `aria-live="polite"` 朗读剩余时间 |
| P3 考试作答状态机 | NotStarted→InProgress→Paused（切屏警告）→AutoSubmitting（倒计时归零）→Submitting→Submitted；Zustand L3 + localStorage 持久化草稿，自动保存每 30s + blur 时保存 |
| P3 考试页面 CSP iframe 防嵌套 | 考试路由 `frame-ancestors 'none'` + `X-Frame-Options: DENY`；其他路由允许 Shell 同源嵌入 |
| P3 考试 chunk 性能预算 | 考试作答 chunk < 200KB（动态 import 隔离）；总 Bundle < 300KB；LCP < 2.5s / CLS < 0.1 / INP < 200ms |
| P3 移动端一等公民 | 学生端高频移动场景：Tailwind 响应式断点 + viewport meta + 触摸优化（按钮 ≥ 44px）；考试页面支持横屏锁定 |
| P3 A11y 考试专项 | WCAG 2.2 AA：键盘导航作答（Tab/Enter/方向键）+ `aria-live` 倒计时 + 焦点陷阱（考试中不可 Tab 到地址栏）+ 屏幕阅读器兼容 |
| P3 考试草稿多设备同步预留 | 当前 localStorage 单设备；P5+ 预留草稿同步（LWW 冲突解决 + WebSocket 推送 + version 字段） |
| P3 Feature Flag 阶段化 | P3-P5 用环境变量（`NEXT_PUBLIC_FEATURE_*`）；P6+ 预留 Consul 配置中心动态开关 |
| P3 PWA 离线壳预留 | P5+ Service Worker 缓存考试壳，断网时仍可作答，恢复后自动提交 |
| P3 MF 降级与版本协商 | Remote `remoteEntry.js` 加载失败 → fallback 独立页面 + 错误提示；共享依赖版本不匹配 → 运行时协商降级 |
| P3 AI 答疑 SSE 流式（P5） | `POST /student/ai/stream-chat` SSE 流式响应 + `streamingText` 逐字渲染 + 打字机效果 + AbortController 取消 |
| P3 权限点命名 | 与 student-bff §3.2 对齐 `STUDENT_*_READ` 风格（`STUDENT_DASHBOARD_READ`/`STUDENT_EXAM_READ`/`STUDENT_HOMEWORK_SUBMIT`/`STUDENT_GRADE_READ` 等） |
| P2 MF Remote 独立壳双模式 | `NEXT_PUBLIC_MF_ENABLED=false` 独立壳渲染（自建 urql client + AppShell）；`true` 接入 Shell（复用 Shell 暴露的 GraphQL client 单例 + AppShell） |
| P2 设计令牌三层实现 | primitive.css（原始 HSL 分量 + 字面量白名单）→ semantic.css（语义令牌组合）→ tailwind.config.js（映射为 bg-_/text-_ 类），ESLint `no-restricted-syntax` 禁止 #hex 字面量 |
| P2 GraphQL endpoint 路径 | `POST /api/v1/student/graphql`（经 api-gateway 反向代理到 student-bff :3009），next.config.js `rewrites` 配置 `/api/v1/*` + `/api/auth/*` → api-gateway |
| P2 MSW mock ActionState 信封 | MSW handlers 返回 `{ success: true, errors: [], data: {...}, extensions: { degraded: false } }`，按 operationName 分发到 fixtures/*.json |
| P3 考试状态机实现 | useReducer 实现 NotStarted→InProgress→AutoSaving→Submitting→Submitted 状态机，`canSubmit` 防止非 InProgress/AutoSaving 状态提交 |
| P3 IDB 草稿持久化 | idb-keyval 存储草稿，key 格式 `exam-draft:${examId}:${studentId}`，自动保存每 30s（NEXT_PUBLIC_EXAM_AUTOSAVE_INTERVAL）+ 卸载时保存 |
| P3 服务器时间同步实现 | useServerTimeSync 轮询 serverTime query，RTT 中点估算 offset = (t1 + rtt/2) - serverTime，5min 重同步（NEXT_PUBLIC_EXAM_TIME_SYNC_INTERVAL），失败标记降级 |
| P3 多标签检测降级方案 | BroadcastChannel('student-exam-guard') 优先，Safari<15.4 降级到 localStorage StorageEvent |
| P3 提交防重复 | crypto.randomUUID 生成幂等 key（降级方案 timestamp+random），useRef 锁防快速点击重复提交 |
| P3 防作弊批量上报 | 违规事件队列（满 10 条批量上报 recordExamViolation mutation），visibilitychange hidden 计数 ≥3 显示警告遮罩 |
| P5 WebSocket 通知降级 | useNotificationsWebSocket 指数退避重连（1s/2s/4s/8s/max 30s），mock-socket 模拟推送，BroadcastChannel('edu-notification') 跨 Tab 同步 |
| P6 健康检查端点 | `/api/health` 返回 liveness（无外部依赖）；`/api/ready` 检查 GraphQL endpoint 可达性（fetch simple query），503 if not ready |
| P6 Dockerfile 多阶段构建 | node:22-alpine 三阶段（install→build→runtime），非 root 用户运行，EXPOSE 4001，healthcheck 用 /api/health |
| P6 Sentry PII 过滤 | beforeSend 过滤 studentName/studentNo/email 字段，仅 NEXT_PUBLIC_SENTRY_DSN 配置时初始化 |
| P2 @edu/hooks ESM .js 后缀解析 | webpack `resolve.extensionAlias` 映射 `.js → [.ts, .tsx, .js]`（仅 .js，不映射 .mjs 避免破坏 urql 等库内部解析） |
| P2 MSW setupWorker SSR 报错 | `setupWorker` 仅在浏览器调用，使用动态 `import('msw/browser')` + `typeof window === 'undefined'` 守卫，避免 Next.js prerender 时执行 |