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

chore(student-portal): merge student-portal full implementation into main

Browse Source
This commit is contained in:
SpecialX
2026-07-10 19:19:35 +08:00
parent 860557e166 74474a2d04
commit 606acb674f
80 changed files with 14679 additions and 339 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -609,46 +609,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` 等） |
### 2.16 teacher-bff（TS/NestJS，P2）
> teacher-bff 是 GraphQL 聚合层（B1 裁决：P2 起直接 GraphQL），无 DB，无 @RequirePermission（B3 豁免），做数据权限防御（B4）。本节记录 teacher-bff 特有的"场景→技术"映射。
| 场景 | 技术/规则 |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| P2 GraphQL 直接实现 | B1 裁决：P2 起直接 GraphQL Yoga（禁止 REST 过渡），POST /graphql endpoint + SDL-first schema（packages/shared-ts/contracts/graphql/） |
| P2 gRPC 下游通信 | B2 裁决：首次实现即 gRPC（禁止 REST fetch），@grpc/grpc-js + @grpc/proto-loader 动态加载 proto（无生成代码依赖） |
| DownstreamClient 抽象 | B8 裁决：3 个 BFF 共用标准抽象层（src/clients/），base.client.ts + grpc.factory.ts + per-service client（iam/client.interface + grpc + mock） |
| DEV_MODE mock 开关 | TEACHER_BFF_DEV_MODE=true → IamClient 走 mock（固定数据）；false → gRPC（未就绪 RPC 降级 mock + warning，president §2.6 降级模式 B） |
| 越权防御 3 类错误码 | president §2.7：UNAUTHORIZED(401) / FORBIDDEN_RESOURCE(403 场景 A 资源无归属) / IDENTITY_MISMATCH(403 场景 B JWT 与 body 不一致) |
| AuthorizationGuard P2 策略 | president §2.9：P2 DEV_MODE 放行 + 日志告警，生产保守拒绝；P3+ 接入 core-edu.GetClassesByTeacher 真实校验 |
| /readyz 探针注册表 | president §2.4：DownstreamHealthCheck 注册表模式，P2 = Redis + iam gRPC（2 项），按阶段扩展（P3=3/P4=5/P5=7）；必需依赖失败返 503，可选失败返 200+degraded |
| Dashboard Resolver P2 实现 | president §2.8：P2 仅调 iam gRPC（user+viewports 有数据），未启用字段返 null + extensions.warning="field_unavailable_in_p2" |
| admin 命名空间预留 | president §5.1：P2 预留 schema（AdminQuery/AdminMutation 类型声明），Resolver 返 null/空；P6 实现 Resolver 真实数据（admin-portal 复用 teacher-bff GraphQL endpoint） |
| 错误码 BFF_TEACHER_ 前缀 | B5 + G14 裁决：统一 BFF_ 前缀（非 TEACHER_BFF_），含 10 个错误码（validation/unauthorized/forbidden_resource/identity_mismatch/not_found/conflict/business/upstream_unavailable/aggregation_failed/internal） |
| ESM .js 后缀 | G12 裁决：NestJS ESM 模式下相对 import 必须带 .js 后缀（构建产物），所有源码 import 路径已对齐 |
| import type 强制 | G13 裁决：仅类型导入用 `import type`，运行时导入用 `import` |
| gRPC 健康检查 | grpc.health.v1.Health/Check 标准协议，makeUnaryRequest + 2s 超时，解析 HealthCheckResponse.status varint |
| ioredis ESM 导入类型 | `import IORedis from "ioredis"` ESM 下报 TS2709/TS2351，改用命名导入 `import { Redis } from "ioredis"`，类型注解用 `Redis` 而非 `IORedis` |
| NestJS HttpAdapter 路由注册 | `app.getHttpAdapter().get()` 的 RequestHandler 与 Express 类型不兼容，改用 `getInstance() as Application` 获取 Express 实例后注册路由 |
| graphql-yoga v5 context | YogaInitialContext 不含 response，context 回调只解构 `{ request }`，buildGraphQLContext 只接收 request（P5+ SSE 再扩展 response） |
| readonly 属性延迟初始化 | `readonly` 属性只能在构造函数赋值，需在 initLogger() 方法中重新赋值时移除 readonly 修饰符 |
| 场景 | 技术/规则 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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 时执行 |