2050 lines
95 KiB
Markdown
2050 lines
95 KiB
Markdown
# 模块架构设计文档 — student-portal
|
||
|
||
> AI：ai14（TS/React · 学习场景域前端 remote）
|
||
> 阶段：阶段 2 交付物（v2 — ai14 接管审计与补全版）
|
||
> 初版日期：2026-07-09（ai07 起草）
|
||
> 审计日期：2026-07-10（ai14 修订：协议 REST→GraphQL、端口 3001→4001、所有权 ai07→ai14、MF 配置 ARB-002、路由前缀、错误码前缀、长远架构补全）
|
||
> 关联：[阶段 1 理解确认书](./01-understanding.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) §5.4、[pending-features P3](../../../docs/architecture/roadmap/pending-features.md)、[teacher-portal 阶段 2 架构设计](../../teacher-portal/docs/02-architecture-design.md)、[teacher-portal 阶段 3 长远架构](../../teacher-portal/docs/03-long-term-architecture.md)、[known-issues §2.15](../../../docs/troubleshooting/known-issues.md)、[coord 仲裁 ARB-001](../../../docs/architecture/issues/coord.md#1-arb-001teacher-bff-graphql-schema-第一版)、[coord 仲裁 ARB-002](../../../docs/architecture/issues/coord.md#2-arb-002mf-shell-暴露清单)、[student-bff 契约](../../../docs/architecture/issues/contracts/student-bff_contract.md)、[student-portal 契约](../../../docs/architecture/issues/contracts/student-portal_contract.md)
|
||
> 状态：待 coord 交叉审查
|
||
|
||
> **v2 审计修订摘要**（ai14 → ai07 初稿）：
|
||
>
|
||
> 1. **协议修订**：REST → **GraphQL over HTTP**（ARB-001 已裁决 student-bff 走 GraphQL Yoga + ActionState 信封 + DataLoader；前端 all-in GraphQL，复用 Shell 暴露的 urql client 单例）
|
||
> 2. **端口修订**：3001 → **4001**（004 §1.2 强制 4 端 4000-4003；[port-allocation](../../../infra/port-allocation.md) §4 硬约束；3001 已被 classes 历史占用）
|
||
> 3. **所有权修订**：ai07 → **ai14**（ai-allocation.md §3.2 L94；ai07=classes/core-edu 交接）
|
||
> 4. **MF 配置修订**：按 ARB-002，Shell 暴露 `GraphQLProvider`/`useGraphQLClient`/`urql`/`graphql` 单例；student-portal 不再实现 ApiClient，不重复创建 GraphQL client
|
||
> 5. **路由修订**：`/student/*` → `/*`（无前缀，与 student-portal_contract.md §1.2 对齐；student-portal 是独立 dev server :4001）
|
||
> 6. **登录路径修订**：`/iam/login` → `POST /api/auth/login`（iam 仅 gRPC，登录由 api-gateway 聚合）
|
||
> 7. **错误码前缀修订**：`EXAMS_`/`HOMEWORK_`/`GRADES_` → **`CORE_EDU_`**（known-issues §2.15）；`STUDENT_BFF_` → **`BFF_STUDENT_`**
|
||
> 8. **遗漏补全**：考试作答架构设计（断网恢复/时间对齐/防作弊/IDB 队列）、详细组件设计、跨标签同步、API 版本管理、监控与降级、模块演化、长远架构愿景
|
||
> 9. **新增章节**：§14 考试作答架构设计、§15 详细组件设计、§16 跨标签同步实现、§17 API 版本管理、§18 监控与降级、§19 模块演化与解耦、§20 长远架构愿景
|
||
|
||
---
|
||
|
||
## 1. 模块内部分层图（student-portal Remote 视角）
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Browser["浏览器（学生）"]
|
||
URL[URL 路由 /*<br/>无 /student 前缀]
|
||
end
|
||
|
||
subgraph Shell["teacher-portal（Shell 宿主 :4000）"]
|
||
AppShell[AppShell<br/>左栏导航 + 主内容区<br/>按 scope=student 过滤视口]
|
||
RootLayout[RootLayout<br/>字体/令牌/i18n/GraphQL/Query Provider]
|
||
GraphQLProvider["GraphQLProvider<br/>urql client 单例（ARB-002）<br/>含 exchanges: cache/auth/error/retry"]
|
||
SharedDeps["共享依赖暴露（singleton）<br/>react/react-dom/urql/graphql/@tanstack/react-query<br/>zustand/nuqs/@edu/ui-components/@edu/ui-tokens<br/>@edu/contracts/@edu/hooks/@edu/shared-ts"]
|
||
Rewrites["rewrites /api/v1/* + /api/auth/* → api-gateway"]
|
||
end
|
||
|
||
subgraph RemoteStudent["student-portal（Remote :4001）"]
|
||
StudentPages["学习场景页面<br/>dashboard/my-homework/my-exams/take<br/>my-grades/my-attendance/learning-path<br/>diagnostic(P4)/weakness(P4)/notifications(P5)"]
|
||
ExamTaking[ExamTaking 组件<br/>倒计时 + 自动保存 + 断网恢复 + 防作弊]
|
||
StudentHooks["GraphQL Hooks<br/>useMyExams/useMyHomework/useExamTaking<br/>useSubmitHomework/useMyGrades 等"]
|
||
IDBQueue["IDB 队列<br/>断网恢复重试队列<br/>考试草稿持久化"]
|
||
end
|
||
|
||
subgraph Shared["共享层（packages/，由 Shell 暴露）"]
|
||
UITokens[ui-tokens<br/>三层设计令牌]
|
||
UIComponents[ui-components<br/>shadcn + A11y + ErrorBoundary + RequirePermission]
|
||
Contracts[contracts<br/>Permissions 常量 + 类型]
|
||
Hooks[hooks<br/>usePermission/useAuth/useViewports/useA11y]
|
||
LibTS[shared-ts<br/>Logger/Tracer/通用工具]
|
||
end
|
||
|
||
subgraph Gateway["api-gateway :8080"]
|
||
GW[Gin 路由/JWT 验签/限流]
|
||
end
|
||
|
||
subgraph BFF["student-bff :3009"]
|
||
BFFGraphQL[GraphQL Yoga endpoint<br/>POST /graphql]
|
||
end
|
||
|
||
subgraph PushGW["push-gateway :8081（P5）"]
|
||
WS[WebSocket /ws]
|
||
end
|
||
|
||
Browser --> URL
|
||
URL --> RootLayout
|
||
RootLayout --> AppShell
|
||
RootLayout --> GraphQLProvider
|
||
AppShell -->|动态加载 Remote| RemoteStudent
|
||
|
||
RemoteStudent -->|消费 singleton| SharedDeps
|
||
RemoteStudent --> StudentPages
|
||
StudentPages --> ExamTaking
|
||
StudentPages --> StudentHooks
|
||
StudentHooks -->|复用 urql client| GraphQLProvider
|
||
ExamTaking --> IDBQueue
|
||
|
||
SharedDeps --> UITokens
|
||
SharedDeps --> UIComponents
|
||
SharedDeps --> Contracts
|
||
SharedDeps --> Hooks
|
||
SharedDeps --> LibTS
|
||
|
||
StudentHooks -->|POST /api/v1/student/graphql| Rewrites
|
||
Rewrites --> GW
|
||
GW --> BFFGraphQL
|
||
|
||
RemoteStudent -.->|P5 WebSocket| WS
|
||
WS -.->|推送事件| RemoteStudent
|
||
```
|
||
|
||
### 1.1 Remote 与 Shell 的职责边界
|
||
|
||
| 职责 | Shell（teacher-portal） | Remote（student-portal） |
|
||
| -------------------------------- | ----------------------- | ------------------------ |
|
||
| RootLayout（字体/令牌/Provider） | ✅ 提供 | ❌ 复用 |
|
||
| AppShell（左栏 + 主内容区） | ✅ 提供 | ❌ 复用 |
|
||
| GraphQLProvider（urql client） | ✅ 提供（ARB-002） | ❌ 复用单例 |
|
||
| 共享依赖暴露（singleton） | ✅ 提供 | ❌ 消费 |
|
||
| 登录页 | ✅ 提供（P2 不走 MF） | ❌ 复用 |
|
||
| rewrites `/api/v1/*` | ✅ 提供 | ❌ 依赖 Shell |
|
||
| 路由表 `/*`（无 /student 前缀） | ❌ 由 Remote 暴露 | ✅ 提供 |
|
||
| 学习场景页面 | ❌ | ✅ |
|
||
| GraphQL 业务 Hooks | ❌ | ✅ |
|
||
| 考试作答组件（ExamTaking 等） | ❌ | ✅ |
|
||
| IDB 断网恢复队列 | ❌ | ✅ |
|
||
|
||
### 1.2 MF 配置（student-portal/next.config.js，Remote 角色）
|
||
|
||
```javascript
|
||
// apps/student-portal/next.config.js（Remote）
|
||
const NextFederationPlugin = require("@module-federation/nextjs-mf");
|
||
|
||
module.exports = {
|
||
reactStrictMode: true,
|
||
transpilePackages: [
|
||
"@edu/ui-tokens",
|
||
"@edu/ui-components",
|
||
"@edu/hooks",
|
||
"@edu/contracts",
|
||
"@edu/shared-ts",
|
||
],
|
||
webpack(config, { isServer }) {
|
||
config.plugins.push(
|
||
new NextFederationPlugin({
|
||
name: "student_app",
|
||
filename: "static/chunks/remoteEntry.js",
|
||
// Remote 暴露页面入口 + 考试作答组件（供 Shell 路由复用）
|
||
exposes: {
|
||
"./pages": "./src/pages",
|
||
"./ExamTaking": "./src/components/ExamTaking",
|
||
},
|
||
// Remote 反向引用 Shell 暴露的共享组件 + GraphQL 单例（可选，多数通过 singleton shared 解决）
|
||
remotes: {
|
||
teacher: `teacher_app@http://localhost:4000/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`,
|
||
},
|
||
shared: {
|
||
react: { singleton: true, requiredVersion: "^18.3.0" },
|
||
"react-dom": { singleton: true, requiredVersion: "^18.3.0" },
|
||
// ARB-002：GraphQL 相关依赖由 Shell 暴露为 singleton
|
||
urql: { singleton: true, requiredVersion: "^2.2.0" },
|
||
graphql: { singleton: true, requiredVersion: "^16.8.0" },
|
||
"@tanstack/react-query": { singleton: true, requiredVersion: "^5.0.0" },
|
||
zustand: { singleton: true },
|
||
nuqs: { singleton: true },
|
||
"@edu/ui-tokens": { singleton: true },
|
||
"@edu/ui-components": { singleton: true },
|
||
"@edu/hooks": { singleton: true },
|
||
"@edu/contracts": { singleton: true },
|
||
"@edu/shared-ts": { singleton: true },
|
||
},
|
||
extraOptions: { exposePages: false },
|
||
}),
|
||
);
|
||
return config;
|
||
},
|
||
// student-portal 不实现 rewrites，依赖 teacher-portal Shell 的 rewrites 代理 /api/v1/* 与 /api/auth/*
|
||
};
|
||
```
|
||
|
||
> **说明**（ARB-002 对齐）：
|
||
>
|
||
> - `name: 'student_app'`：Remote 应用名，被 Shell 在 `remotes` 中引用为 `student: 'student_app@http://localhost:4001/...'`
|
||
> - Shell 端口 **4000**（ARB-002 MF URL），student-portal dev 端口 **4001**
|
||
> - `urql`/`graphql` 声明为 `singleton: true`，确保与 Shell 共享同一 GraphQL client 实例（ARB-002 强制）
|
||
> - `shared` 全部 `singleton: true`，避免 React 多实例、Zustand store 分裂、GraphQL cache 分裂
|
||
> - `transpilePackages` 列出本地 `packages/*` 软链依赖，确保 SWC 正确编译
|
||
> - student-portal **不实现 rewrites**，所有 `/api/v1/*` 与 `/api/auth/*` 请求由 Shell 的 rewrites 代理到 api-gateway
|
||
|
||
## 2. 领域模型（前端视角）
|
||
|
||
前端不持有业务聚合根，仅持有"视图模型"（ViewModel）和"会话状态"。Session/Viewport/Permission 三模型与 Shell 共享，详见 [teacher-portal 阶段 2 §2](../../teacher-portal/docs/02-architecture-design.md#2-领域模型前端视角)。
|
||
|
||
### 2.1 会话状态（Session）
|
||
|
||
复用 Shell 的 Session 模型，student-portal 不重复定义。详见 teacher-portal 文档 §2.1。
|
||
|
||
### 2.2 视口模型（Viewport）
|
||
|
||
复用 Shell 的 ViewportItem 模型，但 `scope` 字段值为 `'student'`。来源：student-bff GraphQL `viewports` query（聚合 iam 视口配置）。AppShell 按 `scope='student'` 过滤渲染学生端导航。
|
||
|
||
### 2.3 权限模型（Permission）
|
||
|
||
复用 Shell 的 PermissionState 模型。来源：`POST /api/v1/student/graphql` query `currentUser` → `{ permissions, viewports, dataScope }`。学生 dataScope 固定为 **L0（仅本人）**。
|
||
|
||
### 2.4 student-portal 特有视图模型
|
||
|
||
```typescript
|
||
// 考试作答草稿（Zustand L3 + IDB，断网恢复用）
|
||
interface ExamTakingDraft {
|
||
examId: string;
|
||
studentId: string;
|
||
answers: Record<string, AnswerInput>; // questionId → answer
|
||
startedAt: number; // 客户端开始时间戳
|
||
serverStartedAt: number; // 服务器开始时间戳（用于倒计时校正）
|
||
lastSavedAt: number | null;
|
||
durationSeconds: number; // 考试时长（秒，来自服务器）
|
||
expiresAt: string; // ISO 8601 UTC，考试截止时间（来自服务器）
|
||
suspiciousBehaviors: SuspiciousBehaviorRecord[]; // 防作弊记录
|
||
}
|
||
|
||
// 答案输入（联合类型，按题型区分）
|
||
type AnswerInput =
|
||
| { type: "single-choice"; optionId: string }
|
||
| { type: "multiple-choice"; optionIds: string[] }
|
||
| { type: "fill-blank"; values: string[] }
|
||
| { type: "short-answer"; text: string }
|
||
| { type: "essay"; text: string; attachments?: AttachmentRef[] };
|
||
|
||
// 可疑行为记录（防作弊，前端仅记录，服务端最终判定）
|
||
interface SuspiciousBehaviorRecord {
|
||
type: "tab-switch" | "copy-paste" | "fullscreen-exit" | "multi-tab" | "window-blur";
|
||
timestamp: number;
|
||
duration?: number; // 持续时长（ms）
|
||
details?: string;
|
||
}
|
||
|
||
// 作业提交表单（react-hook-form L5）
|
||
interface HomeworkSubmitForm {
|
||
homeworkId: string;
|
||
answers: AnswerInput[];
|
||
attachments?: File[]; // 附件（图片/PDF）
|
||
note?: string; // 学生备注
|
||
}
|
||
|
||
// 学情诊断视图模型（P4）
|
||
interface DiagnosticViewModel {
|
||
examId: string;
|
||
examName: string;
|
||
score: number;
|
||
maxScore: number;
|
||
knowledgePoints: Array<{
|
||
id: string;
|
||
name: string;
|
||
mastery: number; // 0-1
|
||
questionCount: number;
|
||
correctCount: number;
|
||
}>;
|
||
radar: Array<{ axis: string; value: number }>; // 多维雷达图数据
|
||
trend: Array<{ date: string; score: number }>; // 趋势线数据
|
||
}
|
||
|
||
// 错题本视图模型（P4）
|
||
interface WeaknessViewModel {
|
||
questionId: string;
|
||
questionContent: string; // 题目内容（脱敏后）
|
||
knowledgePointId: string;
|
||
knowledgePointName: string;
|
||
mastery: number; // 0-1，掌握度
|
||
wrongCount: number;
|
||
lastWrongAt: string; // ISO 8601
|
||
recommendedAction: "review" | "practice" | "mastered";
|
||
}
|
||
|
||
// 学习路径节点（P4）
|
||
interface LearningPathNode {
|
||
id: string;
|
||
name: string;
|
||
knowledgePointId: string;
|
||
status: "locked" | "available" | "in-progress" | "completed";
|
||
dependencies: string[]; // 前置节点 ID
|
||
mastery: number;
|
||
recommendedOrder: number;
|
||
}
|
||
```
|
||
|
||
## 3. 数据模型（前端缓存层）
|
||
|
||
student-portal 无数据库，仅有 GraphQL cache（urql）+ TanStack Query cache + Zustand L3 + IDB。**学生数据实时性要求高，缓存策略偏短**：
|
||
|
||
| 数据类型 | 存储 | TTL | 失效策略 |
|
||
| ------------------------- | ------------------------- | ------- | ------------------------------------------------------------------ |
|
||
| Session（token + user） | localStorage + Zustand | — | 复用 Shell：access 15min / refresh 7day，401 自动 refresh |
|
||
| 权限列表 | urql cache | 5min | 复用 Shell：角色变更事件 invalidate |
|
||
| 视口列表（scope=student） | urql cache | 5min | 复用 Shell |
|
||
| 学生 Dashboard 聚合数据 | urql cache | 30s | staleTime 30s，WebSocket 事件触发 invalidate |
|
||
| 我的作业列表 | urql cache | 30s | staleTime 30s，提交后 invalidate |
|
||
| 我的考试列表 | urql cache | 30s | staleTime 30s，ExamPublished 事件 invalidate |
|
||
| 考试题目数据 | urql cache | **0s** | 考试作答页禁缓存（防预渲染泄露答案）；进入时强制 refetch |
|
||
| 考试作答草稿 | Zustand L3 + IDB | — | 卸载不销毁，自动保存（每 30s + blur 时）；提交成功后清除 IDB |
|
||
| 学情诊断数据 | urql cache | 30s | staleTime 30s（实时性由 BFF 决定） |
|
||
| 错题本列表 | urql cache | 30s | staleTime 30s |
|
||
| 学习路径 | urql cache | 5min | staleTime 5min（低频变更） |
|
||
| 通知列表（P5） | urql cache | 30s | staleTime 30s，WebSocket 事件 invalidate |
|
||
| 服务器时间偏移 | Zustand L3（内存） | — | 每次进入考试页同步一次 |
|
||
| 断网重试队列 | IDB | — | 网络恢复后批量重试，成功后清除 |
|
||
| URL 状态（分页/筛选） | nuqs | — | 永久（可分享）；考试作答页 URL 不携带答案（防泄露） |
|
||
| 表单临时态（作业提交） | react-hook-form | — | 卸载即销毁 |
|
||
| 防作弊行为记录 | Zustand L3（内存队列 100）| — | 队列满后批量上报，上报后清空 |
|
||
|
||
> **缓存策略说明**：学生数据（作业/考试/成绩）频变且实时性要求高，30s 短缓存平衡新鲜度与 BFF 压力；考试题目数据强制 0s 禁缓存防止泄露；考试作答草稿用 IDB 持久化保证断网恢复。
|
||
|
||
## 4. API 设计（前端 → 后端）
|
||
|
||
前端不设计后端 API，仅声明消费的 GraphQL 操作。详见 [01-understanding.md §3.1](./01-understanding.md#31-消费的后端-ap经-api-gateway-代理)。
|
||
|
||
### 4.1 GraphQL 请求层（复用 Shell 暴露的 urql client 单例）
|
||
|
||
student-portal **不重复创建 GraphQL client**，复用 Shell 暴露的 `GraphQLProvider`（ARB-002）。urql client 配置详见 [teacher-portal 阶段 2 §4.1](../../teacher-portal/docs/02-architecture-design.md#41-统一-api-请求层libapits)。
|
||
|
||
student-portal 仅封装业务 Hooks，消费 Shell 的 `useGraphQLClient()`：
|
||
|
||
```typescript
|
||
// apps/student-portal/src/lib/graphql.ts
|
||
import { useGraphQLClient } from "@edu/hooks";
|
||
import { useQuery, useMutation } from "@tanstack/react-query";
|
||
import { gql } from "urql";
|
||
|
||
// 学生 Dashboard 聚合查询
|
||
const STUDENT_DASHBOARD = gql`
|
||
query StudentDashboard {
|
||
studentDashboard {
|
||
upcomingHomework { id title dueAt subject { id name } status }
|
||
upcomingExams { id name startsAt expiresAt durationSeconds subject { id name } status }
|
||
recentGrades { id examName score maxScore grade submittedAt }
|
||
attendanceRate
|
||
learningStreakDays
|
||
}
|
||
}
|
||
`;
|
||
|
||
export function useStudentDashboard() {
|
||
const client = useGraphQLClient();
|
||
return useQuery({
|
||
queryKey: ["student", "dashboard"],
|
||
queryFn: () => client.query(STUDENT_DASHBOARD, {}).toPromise(),
|
||
staleTime: 30 * 1000, // 30s
|
||
});
|
||
}
|
||
|
||
// 考试作答相关
|
||
const MY_EXAMS = gql`
|
||
query MyExams($status: ExamStatus) {
|
||
myExams(status: $status) {
|
||
id name startsAt expiresAt durationSeconds
|
||
subject { id name }
|
||
status questionCount
|
||
}
|
||
}
|
||
`;
|
||
|
||
const EXAM_DETAIL = gql`
|
||
query ExamDetail($examId: ID!) {
|
||
exam(id: $examId) {
|
||
id name durationSeconds startsAt expiresAt
|
||
questions {
|
||
id type content options { id text }
|
||
score maxScore
|
||
}
|
||
}
|
||
}
|
||
`;
|
||
|
||
const SAVE_EXAM_ANSWER = gql`
|
||
mutation SaveExamAnswer($examId: ID!, $questionId: ID!, $answer: AnswerInput!) {
|
||
saveExamAnswer(examId: $examId, questionId: $questionId, answer: $answer) {
|
||
savedAt
|
||
ok
|
||
}
|
||
}
|
||
`;
|
||
|
||
const SUBMIT_EXAM = gql`
|
||
mutation SubmitExam($examId: ID!) {
|
||
submitExam(examId: $examId) {
|
||
submissionId submittedAt
|
||
}
|
||
}
|
||
`;
|
||
|
||
export function useMyExams(status?: ExamStatus) {
|
||
const client = useGraphQLClient();
|
||
return useQuery({
|
||
queryKey: ["student", "exams", { status }],
|
||
queryFn: () => client.query(MY_EXAMS, { status }).toPromise(),
|
||
staleTime: 30 * 1000,
|
||
});
|
||
}
|
||
|
||
export function useExamDetail(examId: string) {
|
||
const client = useGraphQLClient();
|
||
return useQuery({
|
||
queryKey: ["student", "exam", examId],
|
||
queryFn: () => client.query(EXAM_DETAIL, { examId }).toPromise(),
|
||
staleTime: 0, // 禁缓存，防泄露
|
||
});
|
||
}
|
||
```
|
||
|
||
### 4.2 GraphQL 操作清单（对齐 student-bff 契约）
|
||
|
||
| 操作类型 | 操作名 | 用途 | 阶段 |
|
||
| ---------- | --------------------- | --------------------------------- | ---- |
|
||
| query | `currentUser` | 当前学生信息 + 权限 + 视口 | P3 |
|
||
| query | `myClasses` | 我的班级列表 | P3 |
|
||
| query | `myExams` | 我的考试列表 | P3 |
|
||
| query | `exam` | 考试详情（含题目） | P3 |
|
||
| query | `examSubmissionStatus`| 考试提交状态（防重复提交） | P3 |
|
||
| query | `examResult` | 考试结果 | P3 |
|
||
| query | `myHomework` | 我的作业列表 | P3 |
|
||
| query | `homeworkDetail` | 作业详情 | P3 |
|
||
| mutation | `submitHomework` | 提交作业 | P3 |
|
||
| query | `myGrades` | 我的成绩列表 | P3 |
|
||
| query | `myAttendance` | 我的考勤 | P3 |
|
||
| query | `studentDashboard` | 学生仪表盘聚合 | P3 |
|
||
| query | `serverTime` | 服务器时间（倒计时校正） | P3 |
|
||
| mutation | `saveExamAnswer` | 保存考试答案（自动保存） | P3 |
|
||
| mutation | `submitExam` | 提交考试 | P3 |
|
||
| mutation | `uploadAttachment` | 上传附件 | P3 |
|
||
| mutation | `recordExamSuspiciousBehavior` | 记录可疑行为 | P3 |
|
||
| query | `textbooks` | 教材列表 | P4 |
|
||
| query | `chapters` | 章节列表 | P4 |
|
||
| query | `learningPath` | 学习路径 | P4 |
|
||
| query | `myWeakness` | 错题本 | P4 |
|
||
| query | `myTrend` | 学习趋势 | P4 |
|
||
| query | `myNotifications` | 通知列表 | P5 |
|
||
| mutation | `markAsRead` | 标记通知已读 | P5 |
|
||
|
||
### 4.3 Query Key 命名约定
|
||
|
||
```typescript
|
||
// GraphQL operation → TanStack Query key
|
||
queryKey: ["student", "dashboard"];
|
||
queryKey: ["student", "exams", { status }];
|
||
queryKey: ["student", "exam", examId]; // 考试详情
|
||
queryKey: ["student", "homework", { status, page }];
|
||
queryKey: ["student", "homework", homeworkId];
|
||
queryKey: ["student", "grades", { subjectId }];
|
||
queryKey: ["student", "attendance", { month }];
|
||
queryKey: ["student", "diagnostic", { examId }];
|
||
queryKey: ["student", "weakness", { knowledgePointId }];
|
||
queryKey: ["student", "learning-path"];
|
||
queryKey: ["student", "notifications", { unreadOnly }];
|
||
queryKey: ["session", "effective-permissions"]; // 复用 Shell
|
||
queryKey: ["session", "viewports", "student"]; // 复用 Shell
|
||
```
|
||
|
||
## 5. 事件设计
|
||
|
||
前端不发布 Kafka 事件，仅消费 WebSocket 推送（P5）+ 浏览器原生事件（防作弊）。
|
||
|
||
### 5.1 WebSocket 推送事件（P5）
|
||
|
||
| 事件 | 触发 | student-portal 前端动作 |
|
||
| ----------------------------- | -------------- | ------------------------------------------------------------------------------------ |
|
||
| `NotificationRequested` | msg 服务投递 | toast 提示 + 通知中心未读数 +1 + `["student","notifications"]` invalidate |
|
||
| `ExamPublished` | 教师发布考试 | toast + `["student","exams"]` invalidate + `["student","dashboard"]` invalidate |
|
||
| `ExamExtended` | 教师延长考试 | 重新拉取 `exam` query → 更新 `expiresAt` → 重置倒计时（待 ai10 msg 确认事件名） |
|
||
| `ExamQuestionReordered` | 教师调整题目顺序 | 重新拉取 `exam` query → 草稿按 questionId 映射（不依赖序号）（待 ai10 确认） |
|
||
| `GradeRecorded` | 教师录入成绩 | toast + `["student","grades"]` invalidate + `["student","dashboard"]` invalidate |
|
||
| `HomeworkDeadlineApproaching` | 作业截止前提醒 | toast + 作业列表高亮 + `["student","homework"]` invalidate |
|
||
|
||
### 5.2 WebSocket 连接管理（P5）
|
||
|
||
```typescript
|
||
// apps/student-portal/src/lib/ws.ts（P5 实现）
|
||
import { useAuth } from "@edu/hooks";
|
||
import { useQueryClient } from "@tanstack/react-query";
|
||
|
||
const RECONNECT_STRATEGY = {
|
||
maxRetries: 5,
|
||
backoff: "exponential", // 1s, 2s, 4s, 8s, 16s
|
||
onMaxRetriesExceeded: "fallback-polling", // 降级为 HTTP 轮询 60s
|
||
};
|
||
|
||
export function useStudentWebSocket() {
|
||
const { getToken } = useAuth();
|
||
const queryClient = useQueryClient();
|
||
const retryCount = useRef(0);
|
||
|
||
useEffect(() => {
|
||
const connect = () => {
|
||
const ws = new WebSocket(
|
||
`${process.env.NEXT_PUBLIC_PUSH_GATEWAY_URL}/ws?token=${getToken()}`,
|
||
);
|
||
|
||
ws.onmessage = (event) => {
|
||
const msg = JSON.parse(event.data) as PushMessage;
|
||
handlePushMessage(msg, queryClient);
|
||
};
|
||
|
||
ws.onclose = () => {
|
||
if (retryCount.current < RECONNECT_STRATEGY.maxRetries) {
|
||
const delay = Math.pow(2, retryCount.current) * 1000;
|
||
setTimeout(connect, delay);
|
||
retryCount.current += 1;
|
||
} else {
|
||
// 降级为 HTTP 轮询
|
||
startPollingFallback(queryClient);
|
||
}
|
||
};
|
||
|
||
ws.onerror = () => ws.close();
|
||
|
||
return () => ws.close();
|
||
};
|
||
|
||
return connect();
|
||
}, [getToken, queryClient]);
|
||
}
|
||
|
||
function handlePushMessage(msg: PushMessage, queryClient: QueryClient) {
|
||
switch (msg.type) {
|
||
case "NotificationRequested":
|
||
toast.info(t(msg.payload.title));
|
||
queryClient.invalidateQueries({ queryKey: ["student", "notifications"] });
|
||
break;
|
||
case "ExamPublished":
|
||
toast.info(t("exam.published", { name: msg.payload.examName }));
|
||
queryClient.invalidateQueries({ queryKey: ["student", "exams"] });
|
||
queryClient.invalidateQueries({ queryKey: ["student", "dashboard"] });
|
||
break;
|
||
case "ExamExtended":
|
||
// 重新拉取考试详情，更新 expiresAt
|
||
queryClient.invalidateQueries({ queryKey: ["student", "exam", msg.payload.examId] });
|
||
queryClient.invalidateQueries({ queryKey: ["student", "exams"] });
|
||
break;
|
||
case "ExamQuestionReordered":
|
||
queryClient.invalidateQueries({ queryKey: ["student", "exam", msg.payload.examId] });
|
||
break;
|
||
case "GradeRecorded":
|
||
toast.success(t("grade.recorded"));
|
||
queryClient.invalidateQueries({ queryKey: ["student", "grades"] });
|
||
queryClient.invalidateQueries({ queryKey: ["student", "dashboard"] });
|
||
break;
|
||
case "HomeworkDeadlineApproaching":
|
||
toast.warning(t("homework.deadlineApproaching", { name: msg.payload.homeworkName }));
|
||
queryClient.invalidateQueries({ queryKey: ["student", "homework"] });
|
||
break;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.3 浏览器原生事件（防作弊，考试作答页）
|
||
|
||
| 事件 | 用途 | 处理 |
|
||
| ------------------- | --------------------------------- | --------------------------------------------------- |
|
||
| `visibilitychange` | 切屏检测 | 记录切换次数 + 时长；超阈值警告；上报服务端 |
|
||
| `blur` / `focus` | 窗口失焦检测 | 同上 |
|
||
| `copy` / `paste` | 复制粘贴检测 | 阻止默认行为 + 警告；主观题允许粘贴自己输入（待确认）|
|
||
| `fullscreenchange` | 全屏退出检测 | 警告 + 记录 |
|
||
| `contextmenu` | 右键禁用 | 考试作答页 `preventDefault()` |
|
||
|
||
## 6. 横切关注点对齐清单
|
||
|
||
### 6.1 权限（前端等价）
|
||
|
||
| 路由 | requiredPermission |
|
||
| -------------------------- | ------------------------ |
|
||
| `/dashboard` | `STUDENT_DASHBOARD_VIEW` |
|
||
| `/my-homework` | `HOMEWORK_READ_OWN` |
|
||
| `/my-homework/:id/submit` | `HOMEWORK_SUBMIT` |
|
||
| `/my-exams` | `EXAMS_READ_OWN` |
|
||
| `/my-exams/:id/take` | `EXAMS_TAKE` |
|
||
| `/my-exams/:id/result` | `EXAMS_RESULT_VIEW` |
|
||
| `/my-grades` | `GRADES_READ_OWN` |
|
||
| `/my-attendance` | `ATTENDANCE_READ_OWN` |
|
||
| `/learning-path` | `LEARNING_PATH_VIEW` |
|
||
| `/diagnostic` | `DIAGNOSTIC_READ_OWN` |
|
||
| `/weakness` | `WEAKNESS_READ_OWN` |
|
||
| `/notifications` | `NOTIFICATION_READ_OWN` |
|
||
|
||
> 路由前缀**不带** `/student/`（student-portal 是独立 dev server :4001）。权限点常量集中在 `packages/contracts/src/permissions.ts`（coord 维护）。L3 组件级视口用 `<RequirePermission perm="HOMEWORK_SUBMIT"><Button>提交作业</Button></RequirePermission>`。权限点后缀 `_OWN` 强调学生仅能操作自己的数据（DataScope L0）。
|
||
|
||
### 6.2 错误码清单（前端 i18n 路由）
|
||
|
||
| 前缀 | 来源服务 | i18n key 模式 |
|
||
| --------------- | ----------- | -------------------------- |
|
||
| `IAM_` | iam | `iam.error.{{code}}` |
|
||
| `CORE_EDU_` | core-edu | `coreEdu.error.{{code}}` |
|
||
| `BFF_STUDENT_` | student-bff | `bffStudent.error.{{code}}`|
|
||
| `GW_` | api-gateway | `gateway.error.{{code}}` |
|
||
| `NETWORK_` | 前端网络层 | `network.error.{{code}}` |
|
||
|
||
> **错误码前缀统一**（known-issues §2.15）：core-edu 子域（考试/作业/成绩/考勤）统一用 `CORE_EDU_`，不再用 `EXAMS_`/`HOMEWORK_`/`GRADES_`；student-bff 用 `BFF_STUDENT_`，不再用 `STUDENT_BFF_`。前端 GraphQL 请求层根据 `extensions.code` 前缀路由 i18n key。
|
||
|
||
### 6.3 Logger
|
||
|
||
复用 `packages/shared-ts/src/logger.ts`（同 teacher-portal），开发环境 console + 结构化，生产环境 → Sentry（P6）。必含字段：`trace_id`、`user_id`、`scope=student`、`path`。
|
||
|
||
```typescript
|
||
// 使用示例（student-portal 内）
|
||
import { createLogger } from "@edu/shared-ts";
|
||
const logger = createLogger({ scope: "student" });
|
||
logger.info("exam taking started", { examId, durationSeconds });
|
||
logger.error("homework submit failed", { homeworkId, error: err.code });
|
||
```
|
||
|
||
### 6.4 Metrics（Web Vitals）
|
||
|
||
| 指标 | 类型 | 上报 |
|
||
| ----------------------------- | ---- | ---------------------------------------------------------- |
|
||
| `student_portal_lcp_seconds` | LCP | `next/web-vitals` → `POST /api/v1/admin/web-vitals` |
|
||
| `student_portal_cls` | CLS | 同上 |
|
||
| `student_portal_fid_seconds` | FID | 同上 |
|
||
| `student_portal_ttfb_seconds` | TTFB | 同上 |
|
||
| `student_portal_exam_save_failed` | Counter | 考试自动保存失败计数 |
|
||
| `student_portal_offline_duration` | Histogram | 离线时长（秒） |
|
||
|
||
P6 接入，P3-P5 暂缓（考试作答自动保存失败率除外，P3 即上报）。
|
||
|
||
### 6.5 Tracer（OTel browser SDK，P6）
|
||
|
||
复用 `packages/shared-ts/src/tracer.ts`（同 teacher-portal）。BatchSpanProcessor → OTLP exporter → collector → Tempo。自动埋点：fetch、XMLHttpRequest、document load、user interaction。
|
||
|
||
### 6.6 健康检查
|
||
|
||
| 端点 | 用途 | 实现 |
|
||
| ----------------- | ---------------------- | -------------------------------------------------------------------- |
|
||
| `GET /api/health` | Dockerfile HEALTHCHECK | Next.js Route Handler，返回 `{ status: 'ok', ts: Date.now() }` |
|
||
| `GET /api/ready` | K8s readinessProbe | 检查 `process.env.API_GATEWAY_URL` 可达 + 内存 < 阈值 + Shell MF 可达 |
|
||
|
||
### 6.7 优雅关闭
|
||
|
||
Next.js 无长连接（除 WS），无需特殊处理。WS 在 P5 由 push-gateway 管理，前端断线自动重连（指数退避，最多 5 次，5 次后降级 HTTP 轮询）。
|
||
|
||
## 7. 共享组件库（复用 Shell 暴露 + student 特有）
|
||
|
||
### 7.1 复用 Shell 暴露的组件（packages/ui-components/）
|
||
|
||
| 组件 | 用途 | 来源 |
|
||
| ------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------ |
|
||
| `AppShell` | 左侧栏 + 主内容区布局（按 scope=student 过滤视口） | teacher-portal Shell 暴露 |
|
||
| `RequirePermission` | L3 组件级视口控制（无权限不渲染 children） | Shell 暴露 |
|
||
| `ErrorBoundary` | React 渲染异常兜底（fallback UI） | Shell 暴露 |
|
||
| `Loading` / `Skeleton` | 骨架屏 | Shell 暴露 |
|
||
| `Empty` | 空态（插画 + 文案 + CTA） | Shell 暴露 |
|
||
| `Modal` / `Dialog` | 全局 Modal（ModalRoot + Zustand ui-store） | Shell 暴露（shadcn/ui） |
|
||
| `Toast` | 全局 toast（错误/成功/警告） | Shell 暴露（shadcn/ui sonner） |
|
||
| `Button` / `Input` / `Select` / `Textarea` | 基础表单 | Shell 暴露（shadcn/ui） |
|
||
| `DataTable` | 表格（排序/分页/筛选） | Shell 暴露 |
|
||
| `Chart` | 图表封装（recharts） | Shell 暴露 |
|
||
| `A11y` 工具集 | useA11yId / mergeA11yProps / describeInput / focus-trap / skip-link / visually-hidden / aria-status | Shell 暴露 |
|
||
| `Form` | react-hook-form + zodResolver 封装 | Shell 暴露 |
|
||
| `GraphQLProvider` | urql client 单例（ARB-002） | Shell 暴露 |
|
||
|
||
### 7.2 student-portal 特有组件（不暴露给 Shell，除 ExamTaking）
|
||
|
||
| 组件 | 用途 | 来源 | 是否 MF 暴露 |
|
||
| ----------------- | --------------------------------------------- | ---- | --------------------------------------- |
|
||
| `ExamTaking` | 考试作答（倒计时 + 自动保存 + 断网恢复 + 防作弊） | 新建 | ✅ 暴露 `./ExamTaking`（供 Shell 路由复用） |
|
||
| `HomeworkSubmit` | 作业提交表单（react-hook-form + zodResolver） | 新建 | ❌ 内部使用 |
|
||
| `DiagnosticChart` | 学情诊断图表（recharts 多维雷达 + 趋势线） | 新建 | ❌ 内部使用 |
|
||
| `WeaknessList` | 错题本列表（按知识点聚合 + 掌握度标签） | 新建 | ❌ 内部使用 |
|
||
| `LearningPathMap` | 学习路径图（知识点前置依赖可视化） | 新建 | ❌ 内部使用 |
|
||
| `ExamResultView` | 考试结果页（得分 + 错题分析 + 知识点掌握度） | 新建 | ❌ 内部使用 |
|
||
| `CountdownTimer` | 倒计时组件（基于服务器时间，避免客户端篡改） | 新建 | ❌ 内部使用 |
|
||
| `DraftRecovery` | 草稿恢复弹窗（断网恢复后提示是否恢复作答） | 新建 | ❌ 内部使用 |
|
||
|
||
### 7.3 不使用的组件（与 teacher-portal 差异）
|
||
|
||
- **不使用 `RichTextEditor`（Tiptap）**：学生不作答富文本，作业提交用表单
|
||
- 不使用 `SSEViewer`：学生不参与 AI 出题
|
||
- 不使用 `ChildSwitcher`：学生无多子女切换（家长端特有）
|
||
- 不使用 `UserManagementTable`：学生不管理用户
|
||
- 不使用 `RolePermissionMatrix`：学生不管理权限
|
||
|
||
## 8. 共享 Hooks（复用 Shell 暴露 + student 特有）
|
||
|
||
### 8.1 复用 Shell 暴露的 Hooks
|
||
|
||
| Hook | 职责 | 来源 |
|
||
| --------------------- | --------------------------------------------------- | ---------- |
|
||
| `useAuth()` | 会话状态（user/token/refresh/login/logout） | Shell 暴露 |
|
||
| `usePermission()` | 权限查询（hasPermission/hasAny/hasAll + dataScope） | Shell 暴露 |
|
||
| `useViewports(scope)` | 视口列表（按 scope 过滤） | Shell 暴露 |
|
||
| `useGraphQLClient()` | urql client 实例（ARB-002 单例） | Shell 暴露 |
|
||
| `useA11yId()` | 唯一 ARIA ID 生成 | Shell 暴露 |
|
||
| `useAriaLive()` | aria-live 区域管理 | Shell 暴露 |
|
||
| `useToast()` | 全局 toast（Zustand ui-store） | Shell 暴露 |
|
||
|
||
### 8.2 student-portal 特有 Hooks
|
||
|
||
| Hook | 职责 |
|
||
| ------------------------- | ----------------------------------------------------- |
|
||
| `useStudentDashboard()` | 学生仪表盘聚合查询 |
|
||
| `useMyExams(status?)` | 我的考试列表 |
|
||
| `useExamDetail(examId)` | 考试详情（含题目，禁缓存） |
|
||
| `useExamTaking(examId)` | 考试作答状态（草稿 + 倒计时 + 自动保存 + 断网队列） |
|
||
| `useSaveExamAnswer()` | 保存答案 mutation（自动保存） |
|
||
| `useSubmitExam()` | 提交考试 mutation |
|
||
| `useMyHomework(status?)` | 我的作业列表 |
|
||
| `useSubmitHomework()` | 提交作业 mutation |
|
||
| `useMyGrades(subjectId?)` | 我的成绩列表 |
|
||
| `useMyAttendance(month?)` | 我的考勤 |
|
||
| `useDiagnostic(examId?)` | 学情诊断（P4） |
|
||
| `useMyWeakness(kpId?)` | 错题本（P4） |
|
||
| `useLearningPath()` | 学习路径（P4） |
|
||
| `useMyNotifications()` | 通知列表（P5） |
|
||
| `useServerTime()` | 服务器时间同步（倒计时校正） |
|
||
| `useExamTabGuard(examId)` | 考试多标签检测（BroadcastChannel） |
|
||
| `useAntiCheat(examId)` | 防作弊行为采集（visibilitychange/copy/paste 等） |
|
||
| `useOfflineQueue()` | 断网恢复队列（IDB 读写 + 重连重试） |
|
||
|
||
## 9. 设计令牌三层（复用 Shell 提供的 packages/ui-tokens/）
|
||
|
||
student-portal **不独立维护设计令牌**，复用 Shell 暴露的 `packages/ui-tokens/`（详见 [teacher-portal 阶段 2 §9](../../teacher-portal/docs/02-architecture-design.md#9-设计令牌三层packagesui-tokens待建立ai07-维护)）。
|
||
|
||
**强制规则**（project_rules §3.10，与 Shell 一致）：
|
||
|
||
- 禁止 `#hex` 字面量（ESLint `no-restricted-syntax`）
|
||
- 禁止 `'Inter'`/`'Fraunces'`/`'JetBrains Mono'` 字面量（ESLint `design-tokens/no-hardcoded-fonts`）
|
||
- 禁止 `font-size: Npx`（用 `var(--font-size-1~9)`）
|
||
- 禁止 Tailwind 任意值 `w-[Npx]`（用 `--space-*` 或默认阶梯）
|
||
|
||
student-portal 的 ESLint flat config 与 Shell 共用，确保规则一致。
|
||
|
||
## 10. 与其他模块的交互点（契约清单）
|
||
|
||
| 方向 | 对方服务 | 协议 | 接口/事件 | 用途 | 阶段 |
|
||
| ------ | ------------ | ------------------ | ------------------------------------ | ---------------------------- | ---- |
|
||
| 调用 | api-gateway | GraphQL over HTTP | `POST /api/v1/student/graphql` | 全部业务请求 | P3+ |
|
||
| 调用 | api-gateway | HTTP | `POST /api/auth/login` | 学生登录 | P2+ |
|
||
| 调用 | push-gateway | WebSocket | `ws://push-gateway/ws` | 实时推送 | P5 |
|
||
| 被调用 | — | — | — | 前端不暴露接口给其他服务 | — |
|
||
| 消费 | student-bff | GraphQL | dashboard/myExams/myHomework 等 | 学生场景聚合 | P3+ |
|
||
| 消费 | iam | GraphQL（经 BFF） | currentUser（权限/视口） | 会话/权限 | P3+ |
|
||
| 消费 | core-edu | GraphQL（经 BFF） | exam/homework/grades 相关 | 教学核心（学生视角） | P3+ |
|
||
| 消费 | content | GraphQL（经 BFF） | textbooks/chapters/learningPath | 内容资源 | P4+ |
|
||
| 消费 | data-ana | GraphQL（经 BFF） | myWeakness/myTrend/diagnostic | 学情分析 | P4+ |
|
||
| 消费 | msg | GraphQL（经 BFF） | myNotifications/markAsRead | 通知中心 | P5+ |
|
||
| 依赖 | coord 维护 | — | `packages/shared-proto` | TS 类型（仅 contracts 部分） | P1+ |
|
||
| 依赖 | coord 维护 | — | `packages/shared-ts` | Logger/Tracer/通用工具 | P3+ |
|
||
| 依赖 | coord 维护 | — | `packages/contracts` | Permissions 常量 + 类型 | P3+ |
|
||
| 依赖 | ai13 维护 | — | `packages/ui-tokens` | 三层设计令牌 | P3+ |
|
||
| 依赖 | ai13 维护 | — | `packages/ui-components` | shadcn + 共享组件 | P3+ |
|
||
| 依赖 | ai13 维护 | — | `packages/hooks` | usePermission/useAuth 等 | P3+ |
|
||
|
||
> **proto 不直接消费**：前端不调用 gRPC，student-bff 把 gRPC 聚合为 GraphQL 暴露给前端。前端仅消费 `packages/contracts/src/permissions.ts` 中的权限点常量（TS 文件，非 proto 生成）。
|
||
|
||
## 11. 风险与假设
|
||
|
||
### 11.1 假设
|
||
|
||
1. **假设 coord 建立 `packages/shared-ts`、`packages/contracts`**：包含 Logger、Tracer、Permissions 常量、通用类型。若 coord 未建立，ai14 自行在 `apps/student-portal/src/shared/` 内实现，后续提取到 packages。
|
||
2. **假设 ai13 teacher-portal Shell 按 ARB-002 暴露 GraphQL 单例**：`GraphQLProvider`/`useGraphQLClient`/`urql`/`graphql` singleton。若 Shell 未暴露，student-portal 降级为自建 urql client（违反 ARB-002，需 coord 仲裁）。
|
||
3. **假设 ai04 student-bff 提供 GraphQL endpoint `POST /graphql`**：含 §4.2 全部 query/mutation。错误码前缀 `BFF_STUDENT_`（ARB-001 已确认）。
|
||
4. **假设 teacher-portal Shell 已就绪**：AppShell + 共享依赖暴露 + MF 配置 + GraphQLProvider（P2 收尾完成）。student-portal 作为 Remote 才能挂载。
|
||
5. **假设 Next.js 14+ Module Federation 2.0 稳定**：`@module-federation/nextjs-mf` 在 Next.js App Router + urql singleton 下可用。若不稳定，降级为 4 端独立部署 + 各自 Shell（重复实现 AppShell + GraphQLProvider）。
|
||
6. **假设 ai10 msg 提供 WebSocket 事件**：`ExamExtended`/`ExamQuestionReordered` 事件名待 ai10 确认（见 issues/contracts）。
|
||
|
||
### 11.2 技术风险
|
||
|
||
| 风险 | 影响 | 缓解 |
|
||
| ----------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------- |
|
||
| MF Remote SSR 对齐复杂 | Remote 在 SSR 时需 Shell 提供上下文 | 优先 CSR，SSR 仅用于首屏 dashboard；考试作答页强制 CSR（防缓存） |
|
||
| GraphQL singleton 分裂 | Remote 与 Shell 的 urql client 不是同一实例，cache 分裂 | MF `shared.singleton: true` + ARB-002 强制 + CI 检查 |
|
||
| 共享依赖版本漂移 | Remote 与 Shell 的 react/urql 版本不一致导致运行时错误 | MF `shared.singleton: true` + `requiredVersion` + CI 检查版本对齐 |
|
||
| 考试作答断网丢失 | 学生作答过程中断网，草稿丢失 | Zustand L3 + IDB 双写，每 30s + blur 时自动保存，重连后批量重试 |
|
||
| 考试倒计时不准 | 学生端时间与服务器时间偏差 | 倒计时基于服务器返回的 `expiresAt`，前端仅做展示，提交以服务器时间为准 |
|
||
| 考试题目缓存泄露 | 考试题目被缓存到 CDN/Service Worker，泄露答案 | 考试作答页 `ssr: false` + urql cache staleTime 0 + Security Header 防缓存 |
|
||
| 缓存陈旧导致看到旧作业 | 学生看到已截止的作业 | staleTime 30s + 截止时间客户端校验 + 提交时服务端二次校验 |
|
||
| Token 刷新竞态 | 多请求同时 401 触发多次 refresh | urql auth exchange 全局单例 + refresh promise 复用（复用 Shell） |
|
||
| 权限缓存陈旧 | 角色变更后前端 5min 内仍用旧权限 | iam 角色变更发 Kafka 事件 → msg 推送 WebSocket → 前端 invalidate |
|
||
| IDB 存储空间不足 | 考试草稿 + 断网队列累积超过浏览器配额 | 提交成功后立即清除 IDB 草稿；定期清理 7 天前的未提交草稿 |
|
||
| BroadcastChannel 兼容性 | Safari < 15.4 不支持 | 降级为 `localStorage` 事件（storage event listener） |
|
||
|
||
### 11.3 未决设计决策（需 coord 仲裁）
|
||
|
||
| 决策 | 当前方案 | 状态 |
|
||
| ------------------------------ | ------------------------------------- | ------------------- |
|
||
| GraphQL vs REST | **GraphQL**（ARB-001 已裁决） | ✅ 已裁决 |
|
||
| MF Shell 暴露清单 | **GraphQLProvider + urql singleton** | ✅ 已裁决（ARB-002）|
|
||
| packages 归属 | ai13 维护 ui-*/hooks，coord 维护 shared-ts/contracts | ✅ 已确认 |
|
||
| 考试作答防作弊事件名 | `ExamExtended`/`ExamQuestionReordered`| ⚠️ 待 ai10 msg 确认 |
|
||
| 附件上传协议 | GraphQL mutation `uploadAttachment` | ⚠️ 待 ai04 确认是否走 multipart |
|
||
| 主观题是否允许粘贴 | 阻止粘贴（待产品确认） | ⚠️ 待产品决策 |
|
||
| 考试作答页是否强制全屏 | 不强制（P6+ lockdown 浏览器才强制） | ⚠️ 待产品决策 |
|
||
|
||
## 12. coord 交叉审查所需信息
|
||
|
||
### 12.1 端口矩阵
|
||
|
||
| 端 | dev 端口 | 生产端口 | 备注 |
|
||
| -------------- | -------- | -------- | ------------------------------------- |
|
||
| student-portal | **4001** | **4001** | MF Remote 子应用（P3 首个 Remote） |
|
||
|
||
> 与 [port-allocation](../../../infra/port-allocation.md) §4 对齐（4000-4003 强制 4 端 portal）。
|
||
|
||
### 12.2 依赖的共享包（需 coord / ai13 建立）
|
||
|
||
| 包 | 路径 | 维护方 | 内容 |
|
||
| --------------- | ------------------------- | ------ | ------------------------------------------------- |
|
||
| `shared-ts` | `packages/shared-ts/` | coord | Logger、Tracer、通用工具 |
|
||
| `contracts` | `packages/contracts/` | coord | Permissions 常量、ActionState 类型、UserInfo 类型 |
|
||
| `ui-tokens` | `packages/ui-tokens/` | ai13 | 三层设计令牌 |
|
||
| `ui-components` | `packages/ui-components/` | ai13 | shadcn + ErrorBoundary + RequirePermission + GraphQLProvider |
|
||
| `hooks` | `packages/hooks/` | ai13 | usePermission、useAuth、useViewports、useGraphQLClient |
|
||
|
||
### 12.3 依赖的后端契约（需对应 AI 确认）
|
||
|
||
| 契约 | 提供方 | 当前状态 |
|
||
| ----------------------------------------------------- | ------------------ | --------------- |
|
||
| `POST /api/auth/login` | api-gateway | ✅ 已实现 |
|
||
| GraphQL `POST /api/v1/student/graphql`（§4.2 全部操作）| student-bff | 📐 待 ai04 设计 |
|
||
| `/exams/*` `/homework/*` `/grades/*`（gRPC，经 BFF） | core-edu | ✅ 已实现（P3） |
|
||
| `/analytics/*`（gRPC，经 BFF） | data-ana | ✅ 已实现（P4） |
|
||
| `/notifications/*` + WebSocket 推送 | msg + push-gateway | 📐 待 P5 |
|
||
| WebSocket 事件 `ExamExtended`/`ExamQuestionReordered` | msg | ⚠️ 待 ai10 确认 |
|
||
|
||
### 12.4 错误码前缀（前端 i18n 路由依赖）
|
||
|
||
前端不产生错误码，仅消费。需各服务确认错误码前缀不重叠：
|
||
|
||
| 前缀 | 服务 | 状态 |
|
||
| --------------- | ----------- | --------------- |
|
||
| `IAM_` | iam | ✅ 已用 |
|
||
| `CORE_EDU_` | core-edu | ✅ 已确认（§2.15）|
|
||
| `BFF_STUDENT_` | student-bff | ✅ 已确认（ARB-001）|
|
||
| `GW_` | api-gateway | ✅ 已用 |
|
||
| `NETWORK_` | 前端 | ai14 自有 |
|
||
|
||
### 12.5 不产生 Kafka 事件
|
||
|
||
前端不发布/消费 Kafka 事件。WebSocket 推送由 push-gateway 消费 Kafka 转发。
|
||
|
||
## 13. 实施路线（ai14 自用）
|
||
|
||
### P3（student-portal 起步 — 核心教学）
|
||
|
||
1. 建 `apps/student-portal/`（Remote 角色），配置 MF（ARB-002：urql/graphql singleton）
|
||
2. 实现 GraphQL Hooks 层（§8.2 全部 P3 Hooks），复用 Shell `useGraphQLClient()`
|
||
3. 实现 Dashboard + 我的作业 + 提交作业 + 我的考试 + 作答考试 + 考试结果 + 我的成绩 + 我的考勤
|
||
4. **考试作答核心**（§14 详述）：CountdownTimer + 自动保存 + IDB 断网恢复 + 防作弊采集 + DraftRecovery
|
||
5. 复用 Shell 的 AppShell + 共享组件（RequirePermission/ErrorBoundary/Loading/Empty/DataTable/Form/Chart）
|
||
6. 配置 Dockerfile 多阶段构建 + `/api/health` + `/api/ready` route
|
||
7. 补 Vitest 单测 + Playwright E2E（覆盖率 ≥ 80%，含考试作答边界场景 6 个 E2E）
|
||
8. 接入 MSW Mock（GraphQL handlers + mock-socket）
|
||
|
||
### P4（学情诊断 + 错题本 + 学习路径）
|
||
|
||
1. 实现学情诊断页面（DiagnosticChart 多维雷达 + 趋势线）
|
||
2. 实现错题本页面（WeaknessList 按知识点聚合 + 掌握度标签）
|
||
3. 实现学习路径页面（LearningPathMap 知识点前置依赖可视化）
|
||
4. 接入 content 服务 GraphQL（textbooks/chapters/learningPath）
|
||
|
||
### P5（推送 + 通知中心）
|
||
|
||
1. student-portal 接入 WebSocket（push-gateway），指数退避重连 + HTTP 轮询降级
|
||
2. 实现通知中心页面（通知列表 + 未读数 + 标记已读）
|
||
3. 处理 6 类推送事件（NotificationRequested/ExamPublished/ExamExtended/ExamQuestionReordered/GradeRecorded/HomeworkDeadlineApproaching）
|
||
|
||
### P6（硬化）
|
||
|
||
1. Web Vitals + OTel browser SDK 接入
|
||
2. A11y WCAG 2.2 AA 审计（考试作答页键盘可操作 + 屏幕阅读器友好）
|
||
3. 性能优化（MF shared 单例验证、bundle 分析、代码分割）
|
||
4. PWA 配置（manifest + Service Worker，考试作答页 Network Only）
|
||
5. 隐私合规完善（PIPL/未成年人保护法强制项）
|
||
6. 多语言（en-US/zh-TW）100% 完成度
|
||
|
||
---
|
||
|
||
## 14. 考试作答架构设计（ai14 新增 — 核心复杂场景）
|
||
|
||
> 考试作答是学生端最复杂、最易出问题的场景，必须在架构中预留所有边界场景的处理。本节是 ai14 新增，对齐 [01-understanding.md §11](./01-understanding.md#11-考试作答边界场景学生端特有必须覆盖)。
|
||
|
||
### 14.1 考试作答状态机
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> NotStarted: 进入 /my-exams/:id/take（早于 startsAt）
|
||
[*] --> InProgress: 进入（startsAt ≤ now ≤ expiresAt）
|
||
NotStarted --> InProgress: 到达 startsAt
|
||
|
||
InProgress --> AutoSaving: 每 30s / blur
|
||
AutoSaving --> InProgress: 保存成功
|
||
AutoSaving --> OfflineMode: 保存失败（网络中断）
|
||
|
||
OfflineMode --> InProgress: 网络恢复 + 队列重试成功
|
||
OfflineMode --> AutoSubmit: 倒计时归零
|
||
|
||
InProgress --> ConfirmSubmit: 学生点击提交
|
||
ConfirmSubmit --> Submitting: 确认提交
|
||
ConfirmSubmit --> InProgress: 取消提交
|
||
|
||
Submitting --> Submitted: 提交成功
|
||
Submitting --> Submitting: 重试（查询提交状态，防重复）
|
||
Submitting --> IDBQueue: 提交失败入队
|
||
|
||
AutoSubmit --> Submitting: 倒计时归零自动提交
|
||
|
||
IDBQueue --> Submitting: 网络恢复后重试
|
||
|
||
Submitted --> [*]: 跳转 /my-exams/:id/result
|
||
Submitted --> ClearDraft: 清除 IDB 草稿
|
||
ClearDraft --> [*]
|
||
```
|
||
|
||
### 14.2 倒计时与服务器时间对齐
|
||
|
||
```typescript
|
||
// apps/student-portal/src/lib/serverTimeSync.ts
|
||
import { useGraphQLClient } from "@edu/hooks";
|
||
|
||
const SERVER_TIME_QUERY = gql`
|
||
query ServerTime {
|
||
serverTime
|
||
}
|
||
`;
|
||
|
||
export function useServerTimeSync() {
|
||
const client = useGraphQLClient();
|
||
const [offset, setOffset] = useState(0); // serverTime - clientTime（ms）
|
||
|
||
const sync = useCallback(async () => {
|
||
const requestStart = Date.now();
|
||
const result = await client.query(SERVER_TIME_QUERY, {}).toPromise();
|
||
const requestEnd = Date.now();
|
||
if (result.data?.serverTime) {
|
||
const serverTime = new Date(result.data.serverTime).getTime();
|
||
const roundTrip = requestEnd - requestStart;
|
||
const estimatedClientTimeAtServer = requestStart + roundTrip / 2;
|
||
setOffset(serverTime - estimatedClientTimeAtServer);
|
||
}
|
||
}, [client]);
|
||
|
||
useEffect(() => {
|
||
sync();
|
||
// 每 5 分钟重新同步一次
|
||
const interval = setInterval(sync, 5 * 60 * 1000);
|
||
return () => clearInterval(interval);
|
||
}, [sync]);
|
||
|
||
// 获取校正后的当前时间
|
||
const getCorrectedTime = () => Date.now() + offset;
|
||
|
||
return { offset, sync, getCorrectedTime };
|
||
}
|
||
|
||
// 倒计时 Hook
|
||
export function useCountdownTimer(expiresAt: string, serverTimeOffset: number) {
|
||
const [remaining, setRemaining] = useState(0);
|
||
|
||
useEffect(() => {
|
||
const calculate = () => {
|
||
const correctedNow = Date.now() + serverTimeOffset;
|
||
const expiry = new Date(expiresAt).getTime();
|
||
const diff = expiry - correctedNow;
|
||
setRemaining(Math.max(0, Math.floor(diff / 1000)));
|
||
};
|
||
calculate();
|
||
const interval = setInterval(calculate, 1000);
|
||
return () => clearInterval(interval);
|
||
}, [expiresAt, serverTimeOffset]);
|
||
|
||
return {
|
||
remaining,
|
||
formatted: formatDuration(remaining),
|
||
isExpired: remaining === 0,
|
||
};
|
||
}
|
||
|
||
function formatDuration(seconds: number): string {
|
||
const h = Math.floor(seconds / 3600);
|
||
const m = Math.floor((seconds % 3600) / 60);
|
||
const s = seconds % 60;
|
||
return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
|
||
}
|
||
```
|
||
|
||
### 14.3 自动保存与断网恢复（IDB 队列）
|
||
|
||
```typescript
|
||
// apps/student-portal/src/lib/examQueue.ts
|
||
import { openDB } from "idb";
|
||
|
||
const DB_NAME = "student-exam";
|
||
const DB_VERSION = 1;
|
||
const DRAFT_STORE = "drafts";
|
||
const QUEUE_STORE = "queue";
|
||
|
||
async function getDB() {
|
||
return openDB(DB_NAME, DB_VERSION, {
|
||
upgrade(db) {
|
||
if (!db.objectStoreNames.contains(DRAFT_STORE)) {
|
||
db.createObjectStore(DRAFT_STORE, { keyPath: "examId" });
|
||
}
|
||
if (!db.objectStoreNames.contains(QUEUE_STORE)) {
|
||
db.createObjectStore(QUEUE_STORE, { keyPath: "id", autoIncrement: true });
|
||
}
|
||
},
|
||
});
|
||
}
|
||
|
||
// 保存草稿到 IDB（断网恢复用）
|
||
export async function saveDraftToIDB(draft: ExamTakingDraft): Promise<void> {
|
||
const db = await getDB();
|
||
await db.put(DRAFT_STORE, draft);
|
||
}
|
||
|
||
// 从 IDB 加载草稿
|
||
export async function loadDraftFromIDB(examId: string): Promise<ExamTakingDraft | undefined> {
|
||
const db = await getDB();
|
||
return db.get(DRAFT_STORE, examId);
|
||
}
|
||
|
||
// 清除草稿（提交成功后）
|
||
export async function clearDraftFromIDB(examId: string): Promise<void> {
|
||
const db = await getDB();
|
||
await db.delete(DRAFT_STORE, examId);
|
||
}
|
||
|
||
// 入队失败的保存请求（断网重试用）
|
||
export async function enqueueFailedSave(item: {
|
||
examId: string;
|
||
questionId: string;
|
||
answer: AnswerInput;
|
||
queuedAt: number;
|
||
}): Promise<void> {
|
||
const db = await getDB();
|
||
await db.add(QUEUE_STORE, item);
|
||
}
|
||
|
||
// 出队并重试
|
||
export async function processQueue(
|
||
retryFn: (item: { examId: string; questionId: string; answer: AnswerInput }) => Promise<boolean>,
|
||
): Promise<void> {
|
||
const db = await getDB();
|
||
const tx = db.transaction(QUEUE_STORE, "readwrite");
|
||
const allItems = await tx.store.getAll();
|
||
|
||
for (const item of allItems) {
|
||
const success = await retryFn({
|
||
examId: item.examId,
|
||
questionId: item.questionId,
|
||
answer: item.answer,
|
||
});
|
||
if (success) {
|
||
await tx.store.delete(item.id);
|
||
}
|
||
}
|
||
await tx.done;
|
||
}
|
||
|
||
// 监听网络恢复事件
|
||
export function useOfflineQueue_recovery(retryFn: (item: any) => Promise<boolean>) {
|
||
useEffect(() => {
|
||
const handleOnline = () => {
|
||
processQueue(retryFn);
|
||
};
|
||
window.addEventListener("online", handleOnline);
|
||
// 页面可见时也尝试处理队列
|
||
document.addEventListener("visibilitychange", () => {
|
||
if (document.visibilityState === "visible" && navigator.onLine) {
|
||
processQueue(retryFn);
|
||
}
|
||
});
|
||
return () => {
|
||
window.removeEventListener("online", handleOnline);
|
||
};
|
||
}, [retryFn]);
|
||
}
|
||
```
|
||
|
||
### 14.4 考试作答自动保存策略
|
||
|
||
```typescript
|
||
// apps/student-portal/src/hooks/useExamTaking.ts
|
||
export function useExamTaking(examId: string) {
|
||
const client = useGraphQLClient();
|
||
const { offset, getCorrectedTime } = useServerTimeSync();
|
||
const [draft, setDraft] = useState<ExamTakingDraft | null>(null);
|
||
const [isOnline, setIsOnline] = useState(navigator.onLine);
|
||
|
||
// 进入考试页时加载草稿
|
||
useEffect(() => {
|
||
loadDraftFromIDB(examId).then((saved) => {
|
||
if (saved) {
|
||
// 检测到未完成草稿，弹 DraftRecovery
|
||
showDraftRecoveryDialog(saved).then((restore) => {
|
||
if (restore) setDraft(saved);
|
||
else setDraft(createNewDraft(examId));
|
||
});
|
||
} else {
|
||
setDraft(createNewDraft(examId));
|
||
}
|
||
});
|
||
}, [examId]);
|
||
|
||
// 自动保存（每 30s + blur）
|
||
useEffect(() => {
|
||
if (!draft) return;
|
||
|
||
const autoSave = async () => {
|
||
if (!isOnline) {
|
||
// 离线：入 IDB 队列
|
||
await saveDraftToIDB(draft);
|
||
return;
|
||
}
|
||
try {
|
||
const result = await client
|
||
.mutation(SAVE_EXAM_ANSWER, {
|
||
examId,
|
||
questionId: "batch", // 批量保存
|
||
answer: draft.answers,
|
||
})
|
||
.toPromise();
|
||
if (result.data?.saveExamAnswer?.ok) {
|
||
setDraft((prev) => ({ ...prev!, lastSavedAt: Date.now() }));
|
||
await saveDraftToIDB(draft); // 同步到 IDB
|
||
}
|
||
} catch (err) {
|
||
// 保存失败，入队列
|
||
await enqueueFailedSave({
|
||
examId,
|
||
questionId: "batch",
|
||
answer: draft.answers as any,
|
||
queuedAt: Date.now(),
|
||
});
|
||
logger.warn("exam auto-save failed, queued", { examId, error: err });
|
||
}
|
||
};
|
||
|
||
const interval = setInterval(autoSave, 30 * 1000); // 每 30s
|
||
const onBlur = () => autoSave(); // blur 时
|
||
|
||
window.addEventListener("blur", onBlur);
|
||
return () => {
|
||
clearInterval(interval);
|
||
window.removeEventListener("blur", onBlur);
|
||
};
|
||
}, [draft, client, examId, isOnline]);
|
||
|
||
// 监听网络状态
|
||
useEffect(() => {
|
||
const updateOnline = () => setIsOnline(navigator.onLine);
|
||
window.addEventListener("online", updateOnline);
|
||
window.addEventListener("offline", updateOnline);
|
||
return () => {
|
||
window.removeEventListener("online", updateOnline);
|
||
window.removeEventListener("offline", updateOnline);
|
||
};
|
||
}, []);
|
||
|
||
// 网络恢复后处理队列
|
||
useOfflineQueue_recovery(async (item) => {
|
||
try {
|
||
const result = await client
|
||
.mutation(SAVE_EXAM_ANSWER, {
|
||
examId: item.examId,
|
||
questionId: item.questionId,
|
||
answer: item.answer,
|
||
})
|
||
.toPromise();
|
||
return result.data?.saveExamAnswer?.ok ?? false;
|
||
} catch {
|
||
return false;
|
||
}
|
||
});
|
||
|
||
// 更新答案
|
||
const updateAnswer = useCallback((questionId: string, answer: AnswerInput) => {
|
||
setDraft((prev) => {
|
||
if (!prev) return prev;
|
||
return {
|
||
...prev,
|
||
answers: { ...prev.answers, [questionId]: answer },
|
||
};
|
||
});
|
||
}, []);
|
||
|
||
return {
|
||
draft,
|
||
isOnline,
|
||
serverTimeOffset: offset,
|
||
correctedNow: getCorrectedTime(),
|
||
updateAnswer,
|
||
};
|
||
}
|
||
```
|
||
|
||
### 14.5 防作弊采集（前端配合，服务端最终判定）
|
||
|
||
```typescript
|
||
// apps/student-portal/src/hooks/useAntiCheat.ts
|
||
export function useAntiCheat(examId: string) {
|
||
const behaviorsRef = useRef<SuspiciousBehaviorRecord[]>([]);
|
||
const [warning, setWarning] = useState<string | null>(null);
|
||
|
||
const record = useCallback(
|
||
(type: SuspiciousBehaviorRecord["type"], details?: string) => {
|
||
const record_item: SuspiciousBehaviorRecord = {
|
||
type,
|
||
timestamp: Date.now(),
|
||
details,
|
||
};
|
||
behaviorsRef.current.push(record_item);
|
||
|
||
// 队列满 100 条后批量上报
|
||
if (behaviorsRef.current.length >= 100) {
|
||
flushBehaviors();
|
||
}
|
||
},
|
||
[examId],
|
||
);
|
||
|
||
const flushBehaviors = useCallback(async () => {
|
||
if (behaviorsRef.current.length === 0) return;
|
||
const batch = behaviorsRef.current.splice(0);
|
||
try {
|
||
await client
|
||
.mutation(RECORD_SUSPICIOUS_BEHAVIOR, {
|
||
examId,
|
||
behaviors: batch,
|
||
})
|
||
.toPromise();
|
||
} catch (err) {
|
||
// 上报失败，重新入队
|
||
behaviorsRef.current.unshift(...batch);
|
||
}
|
||
}, [examId]);
|
||
|
||
// 切屏检测
|
||
useEffect(() => {
|
||
let switchCount = 0;
|
||
const handleVisibility = () => {
|
||
if (document.visibilityState === "hidden") {
|
||
switchCount += 1;
|
||
record("tab-switch", `switch #${switchCount}`);
|
||
if (switchCount >= 3) {
|
||
setWarning(t("exam.antiCheat.tooManyTabSwitches"));
|
||
toast.warning(t("exam.antiCheat.tooManyTabSwitches"));
|
||
}
|
||
}
|
||
};
|
||
document.addEventListener("visibilitychange", handleVisibility);
|
||
return () => document.removeEventListener("visibilitychange", handleVisibility);
|
||
}, [record]);
|
||
|
||
// 复制粘贴检测
|
||
useEffect(() => {
|
||
const handleCopy = (e: ClipboardEvent) => {
|
||
e.preventDefault();
|
||
record("copy-paste", "copy attempted");
|
||
toast.warning(t("exam.antiCheat.copyDisabled"));
|
||
};
|
||
const handlePaste = (e: ClipboardEvent) => {
|
||
e.preventDefault();
|
||
record("copy-paste", "paste attempted");
|
||
toast.warning(t("exam.antiCheat.pasteDisabled"));
|
||
};
|
||
document.addEventListener("copy", handleCopy);
|
||
document.addEventListener("paste", handlePaste);
|
||
return () => {
|
||
document.removeEventListener("copy", handleCopy);
|
||
document.removeEventListener("paste", handlePaste);
|
||
};
|
||
}, [record]);
|
||
|
||
// 全屏退出检测
|
||
useEffect(() => {
|
||
const handleFullscreen = () => {
|
||
if (!document.fullscreenElement) {
|
||
record("fullscreen-exit");
|
||
toast.warning(t("exam.antiCheat.fullscreenExit"));
|
||
}
|
||
};
|
||
document.addEventListener("fullscreenchange", handleFullscreen);
|
||
return () => document.removeEventListener("fullscreenchange", handleFullscreen);
|
||
}, [record]);
|
||
|
||
// 窗口失焦检测
|
||
useEffect(() => {
|
||
const handleBlur = () => {
|
||
record("window-blur");
|
||
};
|
||
window.addEventListener("blur", handleBlur);
|
||
return () => window.removeEventListener("blur", handleBlur);
|
||
}, [record]);
|
||
|
||
// 右键禁用
|
||
useEffect(() => {
|
||
const handleContext = (e: MouseEvent) => {
|
||
e.preventDefault();
|
||
};
|
||
document.addEventListener("contextmenu", handleContext);
|
||
return () => document.removeEventListener("contextmenu", handleContext);
|
||
}, []);
|
||
|
||
// 卸载时 flush
|
||
useEffect(() => {
|
||
return () => {
|
||
flushBehaviors();
|
||
};
|
||
}, [flushBehaviors]);
|
||
|
||
return { warning, flushBehaviors };
|
||
}
|
||
```
|
||
|
||
### 14.6 考试提交防重复
|
||
|
||
```typescript
|
||
// apps/student-portal/src/hooks/useSubmitExam.ts
|
||
export function useSubmitExam(examId: string) {
|
||
const client = useGraphQLClient();
|
||
const queryClient = useQueryClient();
|
||
const [submitting, setSubmitting] = useState(false);
|
||
|
||
const submit = useCallback(async () => {
|
||
setSubmitting(true);
|
||
try {
|
||
// 提交前先查询提交状态，防重复
|
||
const statusResult = await client
|
||
.query(EXAM_SUBMISSION_STATUS, { examId })
|
||
.toPromise();
|
||
|
||
if (statusResult.data?.examSubmissionStatus?.submitted) {
|
||
// 已提交，跳转结果页
|
||
toast.info(t("exam.alreadySubmitted"));
|
||
router.push(`/my-exams/${examId}/result`);
|
||
return;
|
||
}
|
||
|
||
// 执行提交
|
||
const result = await client
|
||
.mutation(SUBMIT_EXAM, { examId })
|
||
.toPromise();
|
||
|
||
if (result.data?.submitExam) {
|
||
// 提交成功，清除 IDB 草稿
|
||
await clearDraftFromIDB(examId);
|
||
queryClient.invalidateQueries({ queryKey: ["student", "exams"] });
|
||
queryClient.invalidateQueries({ queryKey: ["student", "dashboard"] });
|
||
toast.success(t("exam.submitSuccess"));
|
||
router.push(`/my-exams/${examId}/result`);
|
||
} else if (result.error) {
|
||
// 提交失败，入 IDB 队列
|
||
toast.error(t("exam.submitFailed"));
|
||
// 入队，稍后重试
|
||
}
|
||
} catch (err) {
|
||
// 网络错误，入 IDB 队列
|
||
toast.error(t("exam.submitFailedNetwork"));
|
||
} finally {
|
||
setSubmitting(false);
|
||
}
|
||
}, [examId, client, queryClient]);
|
||
|
||
return { submit, submitting };
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 15. 详细组件设计（ai14 新增）
|
||
|
||
### 15.1 ExamTaking 组件
|
||
|
||
```typescript
|
||
// apps/student-portal/src/components/ExamTaking.tsx
|
||
interface ExamTakingProps {
|
||
examId: string;
|
||
}
|
||
|
||
export function ExamTaking({ examId }: ExamTakingProps) {
|
||
const { draft, isOnline, serverTimeOffset, updateAnswer } = useExamTaking(examId);
|
||
const { data: exam } = useExamDetail(examId);
|
||
const { remaining, formatted, isExpired } = useCountdownTimer(
|
||
exam?.expiresAt ?? "",
|
||
serverTimeOffset,
|
||
);
|
||
const { warning } = useAntiCheat(examId);
|
||
const { submit, submitting } = useSubmitExam(examId);
|
||
const [showConfirmSubmit, setShowConfirmSubmit] = useState(false);
|
||
|
||
// 倒计时归零自动提交
|
||
useEffect(() => {
|
||
if (isExpired && !submitting) {
|
||
toast.info(t("exam.timeUp"));
|
||
submit();
|
||
}
|
||
}, [isExpired, submitting, submit]);
|
||
|
||
// 考试延时事件
|
||
useEffect(() => {
|
||
// 由 WebSocket 事件触发 exam query invalidate，exam.expiresAt 更新后倒计时自动重置
|
||
}, [exam?.expiresAt]);
|
||
|
||
if (!draft || !exam) return <Skeleton rows={20} />;
|
||
|
||
const unansweredCount = exam.questions.filter((q) => !draft.answers[q.id]).length;
|
||
|
||
return (
|
||
<div className="exam-taking-container" data-testid="exam-taking">
|
||
{/* 顶部固定：倒计时 + 在线状态 */}
|
||
<div className="sticky top-0 z-10 bg-background border-b">
|
||
<div className="flex items-center justify-between p-4">
|
||
<CountdownTimer
|
||
remaining={remaining}
|
||
formatted={formatted}
|
||
isExpired={isExpired}
|
||
/>
|
||
<OnlineStatus isOnline={isOnline} />
|
||
</div>
|
||
{warning && <div className="bg-warning/10 p-2 text-sm">{warning}</div>}
|
||
</div>
|
||
|
||
{/* 题目区域 */}
|
||
<div className="p-4 space-y-6">
|
||
{exam.questions.map((q, index) => (
|
||
<QuestionCard
|
||
key={q.id}
|
||
question={q}
|
||
index={index}
|
||
answer={draft.answers[q.id]}
|
||
onChange={(answer) => updateAnswer(q.id, answer)}
|
||
/>
|
||
))}
|
||
</div>
|
||
|
||
{/* 底部固定：提交按钮 */}
|
||
<div className="sticky bottom-0 bg-background border-t p-4">
|
||
<Button
|
||
onClick={() => setShowConfirmSubmit(true)}
|
||
disabled={submitting}
|
||
className="w-full"
|
||
>
|
||
{t("exam.submit")}
|
||
</Button>
|
||
</div>
|
||
|
||
{/* 提交确认弹窗 */}
|
||
<Dialog open={showConfirmSubmit} onOpenChange={setShowConfirmSubmit}>
|
||
<DialogContent>
|
||
{unansweredCount > 0 && (
|
||
<p className="text-warning">
|
||
{t("exam.unansweredWarning", { count: unansweredCount })}
|
||
</p>
|
||
)}
|
||
<p>{t("exam.confirmSubmit")}</p>
|
||
<div className="flex gap-2 justify-end">
|
||
<Button variant="outline" onClick={() => setShowConfirmSubmit(false)}>
|
||
{t("common.cancel")}
|
||
</Button>
|
||
<Button onClick={submit} disabled={submitting}>
|
||
{t("common.confirm")}
|
||
</Button>
|
||
</div>
|
||
</DialogContent>
|
||
</Dialog>
|
||
|
||
{/* 草稿恢复弹窗由 useExamTaking 内部触发 */}
|
||
<DraftRecovery examId={examId} />
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 15.2 CountdownTimer 组件
|
||
|
||
```typescript
|
||
// apps/student-portal/src/components/CountdownTimer.tsx
|
||
interface CountdownTimerProps {
|
||
remaining: number; // 秒
|
||
formatted: string; // HH:mm:ss
|
||
isExpired: boolean;
|
||
}
|
||
|
||
export function CountdownTimer({ remaining, formatted, isExpired }: CountdownTimerProps) {
|
||
const isUrgent = remaining <= 300 && remaining > 0; // 最后 5 分钟
|
||
const isCritical = remaining <= 60 && remaining > 0; // 最后 1 分钟
|
||
|
||
return (
|
||
<div
|
||
className={cn(
|
||
"font-mono text-2xl tabular-nums",
|
||
isExpired && "text-destructive",
|
||
isCritical && "text-destructive animate-pulse",
|
||
isUrgent && "text-warning",
|
||
!isUrgent && !isCritical && !isExpired && "text-foreground",
|
||
)}
|
||
role="timer"
|
||
aria-live="polite"
|
||
aria-label={t("exam.timeRemaining", { formatted })}
|
||
>
|
||
{isExpired ? t("exam.timeUp") : formatted}
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 15.3 DraftRecovery 组件
|
||
|
||
```typescript
|
||
// apps/student-portal/src/components/DraftRecovery.tsx
|
||
interface DraftRecoveryProps {
|
||
examId: string;
|
||
}
|
||
|
||
export function DraftRecovery({ examId }: DraftRecoveryProps) {
|
||
const [open, setOpen] = useState(false);
|
||
const [savedDraft, setSavedDraft] = useState<ExamTakingDraft | null>(null);
|
||
|
||
useEffect(() => {
|
||
loadDraftFromIDB(examId).then((draft) => {
|
||
if (draft && Object.keys(draft.answers).length > 0) {
|
||
setSavedDraft(draft);
|
||
setOpen(true);
|
||
}
|
||
});
|
||
}, [examId]);
|
||
|
||
const handleRestore = () => {
|
||
// 父组件通过 context 接收恢复的草稿
|
||
setOpen(false);
|
||
};
|
||
|
||
const handleDiscard = async () => {
|
||
await clearDraftFromIDB(examId);
|
||
setOpen(false);
|
||
};
|
||
|
||
return (
|
||
<Dialog open={open} onOpenChange={setOpen}>
|
||
<DialogContent>
|
||
<h2>{t("exam.draftRecovery.title")}</h2>
|
||
<p>
|
||
{t("exam.draftRecovery.description", {
|
||
answeredCount: savedDraft ? Object.keys(savedDraft.answers).length : 0,
|
||
lastSavedAt: savedDraft?.lastSavedAt,
|
||
})}
|
||
</p>
|
||
<div className="flex gap-2 justify-end">
|
||
<Button variant="outline" onClick={handleDiscard}>
|
||
{t("exam.draftRecovery.discard")}
|
||
</Button>
|
||
<Button onClick={handleRestore}>
|
||
{t("exam.draftRecovery.restore")}
|
||
</Button>
|
||
</div>
|
||
</DialogContent>
|
||
</Dialog>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 15.4 HomeworkSubmit 组件
|
||
|
||
```typescript
|
||
// apps/student-portal/src/components/HomeworkSubmit.tsx
|
||
interface HomeworkSubmitProps {
|
||
homeworkId: string;
|
||
}
|
||
|
||
const homeworkSchema = z.object({
|
||
answers: z.array(
|
||
z.object({
|
||
questionId: z.string(),
|
||
answer: answerInputSchema,
|
||
}),
|
||
),
|
||
note: z.string().max(500).optional(),
|
||
});
|
||
|
||
export function HomeworkSubmit({ homeworkId }: HomeworkSubmitProps) {
|
||
const { data: homework } = useHomeworkDetail(homeworkId);
|
||
const { mutate, isPending } = useSubmitHomework();
|
||
const form = useForm<HomeworkSubmitForm>({
|
||
resolver: zodResolver(homeworkSchema),
|
||
});
|
||
|
||
const onSubmit = (data: HomeworkSubmitForm) => {
|
||
mutate({ homeworkId, ...data });
|
||
};
|
||
|
||
if (!homework) return <Skeleton rows={10} />;
|
||
|
||
return (
|
||
<Form {...form}>
|
||
<form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
|
||
{homework.questions.map((q, index) => (
|
||
<QuestionField
|
||
key={q.id}
|
||
question={q}
|
||
index={index}
|
||
control={form.control}
|
||
name={`answers.${index}.answer`}
|
||
/>
|
||
))}
|
||
|
||
{/* 附件上传 */}
|
||
<AttachmentUpload
|
||
maxFiles={5}
|
||
maxSize={10 * 1024 * 1024} // 10MB
|
||
accept={["image/jpeg", "image/png", "application/pdf"]}
|
||
/>
|
||
|
||
{/* 学生备注 */}
|
||
<Textarea
|
||
{...form.register("note")}
|
||
placeholder={t("homework.notePlaceholder")}
|
||
maxLength={500}
|
||
/>
|
||
|
||
<Button type="submit" disabled={isPending} className="w-full sticky bottom-0">
|
||
{isPending ? t("common.submitting") : t("homework.submit")}
|
||
</Button>
|
||
</form>
|
||
</Form>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 15.5 DiagnosticChart 组件（P4）
|
||
|
||
```typescript
|
||
// apps/student-portal/src/components/DiagnosticChart.tsx
|
||
interface DiagnosticChartProps {
|
||
data: DiagnosticViewModel;
|
||
}
|
||
|
||
export function DiagnosticChart({ data }: DiagnosticChartProps) {
|
||
return (
|
||
<div className="space-y-6">
|
||
{/* 多维雷达图：知识点掌握度 */}
|
||
<Chart type="radar" data={data.radar} options={radarOptions} />
|
||
|
||
{/* 趋势线：历次考试得分 */}
|
||
<Chart type="line" data={data.trend} options={trendOptions} />
|
||
|
||
{/* 知识点掌握度列表 */}
|
||
<DataTable
|
||
columns={[
|
||
{ key: "name", header: t("diagnostic.knowledgePoint") },
|
||
{
|
||
key: "mastery",
|
||
header: t("diagnostic.mastery"),
|
||
render: (row) => <MasteryBar value={row.mastery} />,
|
||
},
|
||
{ key: "correctCount", header: t("diagnostic.correctRate") },
|
||
]}
|
||
data={data.knowledgePoints}
|
||
/>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 16. 跨标签同步实现（ai14 新增）
|
||
|
||
### 16.1 考试作答防多标签（BroadcastChannel）
|
||
|
||
```typescript
|
||
// apps/student-portal/src/lib/examTabGuard.ts
|
||
const EXAM_CHANNEL_NAME = "student-exam-guard";
|
||
|
||
export function useExamTabGuard(examId: string) {
|
||
useEffect(() => {
|
||
// 降级：Safari < 15.4 不支持 BroadcastChannel
|
||
if (typeof BroadcastChannel === "undefined") {
|
||
// 降级为 localStorage 事件
|
||
return useLocalStorageFallback(examId);
|
||
}
|
||
|
||
const channel = new BroadcastChannel(EXAM_CHANNEL_NAME);
|
||
const tabId = `tab-${Date.now()}-${Math.random().toString(36).slice(2)}`;
|
||
|
||
// 广播：我正在作答此考试
|
||
channel.postMessage({ type: "exam-entered", examId, tabId, ts: Date.now() });
|
||
|
||
const onMessage = (event: MessageEvent) => {
|
||
const msg = event.data;
|
||
if (msg.tabId === tabId) return;
|
||
if (msg.type === "exam-entered" && msg.examId === examId) {
|
||
// 已有其他标签在作答，警告
|
||
toast.warning(t("exam.multiTabDetected"));
|
||
recordSuspiciousBehavior("multi-tab-exam");
|
||
// 回应：我也在作答
|
||
channel.postMessage({ type: "exam-exists", examId, tabId, ts: Date.now() });
|
||
}
|
||
if (msg.type === "exam-exists" && msg.examId === examId) {
|
||
// 收到其他标签的回应，说明我也不是第一个
|
||
toast.warning(t("exam.multiTabDetected"));
|
||
recordSuspiciousBehavior("multi-tab-exam");
|
||
}
|
||
};
|
||
channel.addEventListener("message", onMessage);
|
||
|
||
return () => {
|
||
channel.postMessage({ type: "exam-left", examId, tabId });
|
||
channel.close();
|
||
};
|
||
}, [examId]);
|
||
}
|
||
|
||
// localStorage 降级方案
|
||
function useLocalStorageFallback(examId: string) {
|
||
useEffect(() => {
|
||
const key = `exam-active-${examId}`;
|
||
const tabId = `tab-${Date.now()}-${Math.random().toString(36).slice(2)}`;
|
||
localStorage.setItem(key, JSON.stringify({ tabId, ts: Date.now() }));
|
||
|
||
const onStorage = (e: StorageEvent) => {
|
||
if (e.key === key && e.newValue) {
|
||
const otherTab = JSON.parse(e.newValue);
|
||
if (otherTab.tabId !== tabId) {
|
||
toast.warning(t("exam.multiTabDetected"));
|
||
recordSuspiciousBehavior("multi-tab-exam");
|
||
}
|
||
}
|
||
};
|
||
window.addEventListener("storage", onStorage);
|
||
|
||
return () => {
|
||
localStorage.removeItem(key);
|
||
window.removeEventListener("storage", onStorage);
|
||
};
|
||
}, [examId]);
|
||
}
|
||
```
|
||
|
||
### 16.2 通知未读数跨标签同步
|
||
|
||
```typescript
|
||
// apps/student-portal/src/lib/notificationSync.ts
|
||
const NOTIFICATION_CHANNEL = "student-notifications";
|
||
|
||
export function useNotificationSync() {
|
||
const queryClient = useQueryClient();
|
||
|
||
useEffect(() => {
|
||
if (typeof BroadcastChannel === "undefined") return;
|
||
|
||
const channel = new BroadcastChannel(NOTIFICATION_CHANNEL);
|
||
const onMessage = (event: MessageEvent) => {
|
||
if (event.data.type === "unread-count-updated") {
|
||
queryClient.invalidateQueries({ queryKey: ["student", "notifications"] });
|
||
}
|
||
};
|
||
channel.addEventListener("message", onMessage);
|
||
|
||
return () => channel.close();
|
||
}, [queryClient]);
|
||
|
||
const broadcastUnreadUpdate = useCallback(() => {
|
||
if (typeof BroadcastChannel !== "undefined") {
|
||
const channel = new BroadcastChannel(NOTIFICATION_CHANNEL);
|
||
channel.postMessage({ type: "unread-count-updated", ts: Date.now() });
|
||
channel.close();
|
||
}
|
||
}, []);
|
||
|
||
return { broadcastUnreadUpdate };
|
||
}
|
||
```
|
||
|
||
### 16.3 考试草稿跨标签恢复
|
||
|
||
若学生在 Tab A 开始作答，关闭 Tab A 后在 Tab B 重新打开：
|
||
|
||
1. IDB 草稿跨标签共享（同源策略保证）
|
||
2. Tab B 进入考试页时检测 IDB 草稿
|
||
3. 弹 `DraftRecovery` 提示"检测到未完成的作答草稿，是否恢复？"
|
||
4. 用户确认后从 IDB 加载草稿
|
||
|
||
```typescript
|
||
// 在 ExamTaking 组件内
|
||
useEffect(() => {
|
||
loadDraftFromIDB(examId).then((saved) => {
|
||
if (saved && Object.keys(saved.answers).length > 0) {
|
||
// 检测到草稿，触发恢复弹窗
|
||
setPendingDraft(saved);
|
||
}
|
||
});
|
||
}, [examId]);
|
||
```
|
||
|
||
---
|
||
|
||
## 17. API 契约版本管理（ai14 新增）
|
||
|
||
### 17.1 版本兼容矩阵
|
||
|
||
| API 版本 | 引入阶段 | 弃用阶段 | 移除阶段 | student-portal 兼容性 |
|
||
| -------- | -------- | -------- | -------- | ------------------------------ |
|
||
| v1 | P3 | - | - | ✅ P3+ 必须支持 |
|
||
| v2 | P6+ | - | - | ⚠️ P6+ 通过 Feature Flag 切换 |
|
||
| 字段裁剪 | P5+ | - | - | ⚠️ 可选，移动端低带宽时启用 |
|
||
|
||
### 17.2 GraphQL schema 演进策略
|
||
|
||
| 变更类型 | 策略 | 前端处理 |
|
||
| ---------------- | -------------------------------------------------------------------- | ---------------------------------------------- |
|
||
| 新增字段 | 非破坏性，直接新增 | 前端忽略未知字段（Zod 默认行为） |
|
||
| 废弃字段 | `@deprecated` 标注 | 前端监控使用率，< 1% 后移除调用 |
|
||
| 新增 Query/Mutation | 非破坏性 | 前端按需消费 |
|
||
| 废弃 Query/Mutation | 先 `@deprecated` → 1 个迭代周期后移除 | 前端迁移到替代操作 |
|
||
| 破坏性字段变更 | 新增字段 + 废弃旧字段 → 1 个迭代周期后移除旧字段 | 前端 Feature Flag 切换 |
|
||
| Enum 值新增 | 非破坏性 | 前端 default 分支兜底 |
|
||
|
||
### 17.3 urql client 版本协商
|
||
|
||
```typescript
|
||
// urql client 自动处理 GraphQL schema 演进
|
||
// 通过 @deprecated 标注 + schema registry 监控
|
||
const client = createClient({
|
||
url: "/api/v1/student/graphql",
|
||
exchanges: [
|
||
dedupExchange,
|
||
cacheExchange,
|
||
authExchange,
|
||
errorExchange({
|
||
onError: (error) => {
|
||
// 检测 deprecation 警告
|
||
const deprecationWarnings = error.graphQLErrors?.filter(
|
||
(e) => e.extensions?.code === "DEPRECATED_FIELD",
|
||
);
|
||
if (deprecationWarnings?.length) {
|
||
logger.warn("GraphQL deprecated field used", {
|
||
fields: deprecationWarnings.map((w) => w.path),
|
||
});
|
||
// 上报埋点，跟踪使用率
|
||
metrics.increment("graphql.deprecated_field_used", {
|
||
fields: deprecationWarnings.map((w) => w.path?.join(".")),
|
||
});
|
||
}
|
||
},
|
||
}),
|
||
fetchExchange,
|
||
],
|
||
});
|
||
```
|
||
|
||
### 17.4 字段裁剪使用场景（P5+）
|
||
|
||
| 场景 | 裁剪策略 | 节省带宽 |
|
||
| -------------------------- | --------------------------------------------------------------- | -------- |
|
||
| 移动端 4G 查看考试列表 | `myExams { id name startsAt expiresAt status }` | ~60% |
|
||
| 通知列表快速浏览 | `myNotifications { id title read createdAt }` | ~50% |
|
||
| Dashboard 概览 | `studentDashboard { upcomingHomework { id title dueAt } }` | ~40% |
|
||
| 完整考试详情（默认） | 不裁剪 | 0% |
|
||
|
||
---
|
||
|
||
## 18. 监控与降级（ai14 新增）
|
||
|
||
### 18.1 前端监控指标
|
||
|
||
| 指标 | 类型 | 采集方式 | 告警阈值 |
|
||
| ------------------------------------- | --------- | ------------------------- | -------------------- |
|
||
| `student_portal_lcp_seconds` | LCP | `next/web-vitals` | P95 > 2.5s |
|
||
| `student_portal_cls` | CLS | 同上 | P95 > 0.1 |
|
||
| `student_portal_ttfb_seconds` | TTFB | 同上 | P95 > 0.8s |
|
||
| `student_portal_mf_load_failed` | Counter | MF Remote 加载错误捕获 | > 1% |
|
||
| `student_portal_api_error_rate` | Counter | urql errorExchange 拦截 | 5xx > 1% |
|
||
| `student_portal_ws_reconnect` | Counter | WebSocket 重连计数 | 单用户 > 5 次/小时 |
|
||
| `student_portal_exam_save_failed` | Counter | 考试自动保存失败计数 | > 5% |
|
||
| `student_portal_exam_submit_failed` | Counter | 考试提交失败计数 | > 1% |
|
||
| `student_portal_offline_duration` | Histogram | 网络中断时长 | P95 > 30s |
|
||
| `student_portal_draft_recovery_used` | Counter | 草稿恢复使用次数 | 异常增长告警 |
|
||
| `student_portal_anti_cheat_triggered` | Counter | 防作弊触发次数 | 单考试 > 10 次 |
|
||
| `student_portal_cache_hit_rate` | Gauge | urql cache 命中率 | < 60%（异常） |
|
||
| `student_portal_a11y_violations` | Counter | axe-core 自动扫描 | 严重违规 > 0 |
|
||
|
||
### 18.2 降级策略矩阵
|
||
|
||
| 触发条件 | 降级动作 | 用户感知 |
|
||
| --------------------------------- | ----------------------------------------------------------- | ---------------------------- |
|
||
| MF Remote 加载失败（10s 超时） | 显示 Shell 内置的最小化静态引导页 | "学生端加载失败，请稍后重试" |
|
||
| BFF 5xx 错误率 > 5% | 隐藏 mutation 按钮（提交作业/提交考试）；展示只读模式 banner | 顶部黄色 banner："只读模式" |
|
||
| BFF P95 延迟 > 5s | 缩短缓存 TTL 至 5s；展示"加载缓慢"提示 | 顶部提示条 |
|
||
| WebSocket 连接失败 5 次 | 降级为 HTTP 轮询（60s 拉取通知列表） | 通知延迟最多 60s |
|
||
| 考试列表加载失败 3 次 | 显示错误页 + 重试按钮 | 错误页 |
|
||
| 考试作答自动保存失败 | 入 IDB 队列；UI 显示"离线模式"标识 | 顶部黄色标识 |
|
||
| 考试提交失败 | 自动重试 + 入 IDB 队列；3 次失败后人工介入提示 | "提交失败，正在重试" |
|
||
| i18n message 加载失败 | Fallback 到 key 本身作为文案 | 显示英文 key，不影响功能 |
|
||
| 设计令牌加载失败 | Fallback 到 Tailwind 默认色板 | 视觉风格降级，不影响功能 |
|
||
| BroadcastChannel 不支持（Safari < 15.4） | 降级为 storage 事件 | 跨 tab 同步延迟 ~500ms |
|
||
| IDB 存储空间不足 | 清理 7 天前的未提交草稿；提示用户 | toast 提示 |
|
||
| 服务器时间同步失败 | 使用客户端时间（偏差可能较大）；提示"时间同步失败" | 顶部警告条 |
|
||
|
||
### 18.3 错误恢复流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Error[发生错误] --> Classify{错误类型}
|
||
Classify -->|Network| Retry[指数退避重试 3 次]
|
||
Classify -->|401 Unauthorized| Refresh[刷新 token]
|
||
Classify -->|403 Forbidden| Toast[toast 提示无权限]
|
||
Classify -->|404 Not Found| Empty[显示空态]
|
||
Classify -->|5xx Server Error| Fallback[降级策略]
|
||
Classify -->|MF Load Failed| ShellFallback[Shell 兜底页]
|
||
Classify -->|GraphQL Partial| PartialRender[展示部分数据 + 降级标识]
|
||
|
||
Retry -->|成功| Recover[恢复正常]
|
||
Retry -->|失败| Fallback
|
||
|
||
Refresh -->|成功| Recover
|
||
Refresh -->|失败| Logout[跳转登录页]
|
||
|
||
Fallback --> ReadOnlyMode[只读模式]
|
||
Fallback --> CachedData[展示缓存数据]
|
||
Fallback --> ErrorPage[错误页 + 重试]
|
||
Fallback --> IDBQueue[入 IDB 队列等待恢复]
|
||
|
||
Toast --> Continue[继续当前操作]
|
||
Empty --> Continue
|
||
ShellFallback --> RetryMF[10s 后重试 MF]
|
||
ReadOnlyMode --> WaitForRecover[等待 BFF 恢复]
|
||
WaitForRecover --> Recover
|
||
IDBQueue --> Recover
|
||
```
|
||
|
||
### 18.4 GraphQL 降级模式（ARB-001 §3.4 方案 B）
|
||
|
||
student-bff 支持降级模式（ARB-001），部分上游服务不可用时返回部分数据 + `extensions.degraded: true`：
|
||
|
||
```typescript
|
||
// urql errorExchange 处理降级标记
|
||
errorExchange({
|
||
onError: (error) => {
|
||
const degradedErrors = error.graphQLErrors?.filter(
|
||
(e) => e.extensions?.degraded,
|
||
);
|
||
if (degradedErrors?.length) {
|
||
// 展示部分数据 + 降级标识
|
||
toast.warning(t("common.degradedMode"));
|
||
// UI 顶部显示"部分数据可能不是最新"
|
||
}
|
||
},
|
||
}),
|
||
```
|
||
|
||
---
|
||
|
||
## 19. 模块演化与解耦（ai14 新增）
|
||
|
||
### 19.1 拆分触发条件
|
||
|
||
| 触发条件 | 拆分方向 | 阶段 |
|
||
| --------------------------------------- | --------------------------------------------------------------- | ---- |
|
||
| student-portal bundle > 200KB（gzipped）| 按场景域拆分为 `student-core-remote` + `student-exam-remote` | P7+ |
|
||
| 团队规模 > 5 人同时维护 student-portal | 同上 | P7+ |
|
||
| 考试作答功能复杂度提升（lockdown/AI 监考）| 拆出 `student-exam-remote`（考试作答专用） | P7+ |
|
||
| AI 辅导功能引入 | 拆出 `student-ai-remote`（AI 辅导 + 个性化推荐） | P7+ |
|
||
| 多租户支持 | URL 前缀 `/{tenantId}/student/*`；TanStack Query key 加 tenantId | P8+ |
|
||
|
||
### 19.2 拆分后的 MF 配置
|
||
|
||
```javascript
|
||
// 拆分后：student-core-remote（核心场景：dashboard/homework/grades）
|
||
new NextFederationPlugin({
|
||
name: "student_core_app",
|
||
filename: "static/chunks/remoteEntry.js",
|
||
exposes: {
|
||
"./pages": "./src/pages", // dashboard/my-homework/my-grades/my-attendance
|
||
},
|
||
// ... shared 同原配置
|
||
});
|
||
|
||
// 拆分后：student-exam-remote（考试作答专用）
|
||
new NextFederationPlugin({
|
||
name: "student_exam_app",
|
||
filename: "static/chunks/remoteEntry.js",
|
||
exposes: {
|
||
"./pages": "./src/pages", // my-exams/take/result
|
||
"./ExamTaking": "./src/components/ExamTaking",
|
||
},
|
||
// ... shared 同原配置
|
||
});
|
||
```
|
||
|
||
### 19.3 技术栈演化路径
|
||
|
||
| 演化方向 | 触发条件 | 迁移策略 |
|
||
| -------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||
| student-portal 拆分为多个 Remote | bundle > 200KB 或团队规模 > 5 人 | 按场景域拆分：student-core-remote + student-exam-remote |
|
||
| MF 2.0 → 3.0 升级 | MF 3.0 稳定且解决 SSR 问题 | Shell 端 `@module-federation/nextjs-mf` 升级；student-portal 仅改 `name`/`filename` 字段 |
|
||
| 切换为原生 SSR（脱离 MF） | SEO 需求强烈或 MF 维护成本过高 | 保留 GraphQL 请求层和组件库；移除 MF 配置；独立部署为完整 Next.js 应用 |
|
||
| 状态管理迁移（Zustand → Jotai）| Zustand 性能瓶颈或团队偏好 | 逐 slice 迁移；Hook 接口保持不变 |
|
||
| urql → Apollo Client | urql 功能不足 | 替换 GraphQLProvider；业务 Hook 接口保持不变 |
|
||
| React 18 → 19 | React 19 稳定 | 跟随 Shell 升级；use hook / Suspense 改进可简化 TanStack Query 集成 |
|
||
|
||
---
|
||
|
||
## 20. 长远架构愿景（ai14 新增）
|
||
|
||
### 20.1 三年架构演进路线
|
||
|
||
```mermaid
|
||
graph LR
|
||
Y1[Year 1<br/>P3-P6 单体 Remote<br/>MF 2.0 + GraphQL] --> Y2[Year 2<br/>P7+ 多 Remote 拆分<br/>AI 辅导+错题推荐+学习计划]
|
||
Y2 --> Y3[Year 3<br/>P8+ 多租户+多区域<br/>MF 3.0 / 原生 SSR / 移动端原生壳]
|
||
```
|
||
|
||
### 20.2 架构原则（始终不变）
|
||
|
||
1. **Remote 角色不变**：student-portal 始终作为 teacher-portal Shell 的 Remote，不独立 Shell
|
||
2. **契约先行**：所有 API 变更先 proto/contracts，后实现
|
||
3. **无状态前端**：所有持久化状态走 localStorage/IDB，不依赖服务端 session
|
||
4. **复用优先**：组件/Hook/工具优先复用 Shell 暴露的，避免重复实现
|
||
5. **可降级**：任何依赖（BFF/WebSocket/Shell）故障都有降级方案
|
||
6. **可观测**：所有用户行为、错误、性能指标都可观测
|
||
7. **可测试**：所有组件/Hook/页面都有单测 + E2E 覆盖
|
||
8. **可演化**：模块可拆分、状态管理可迁移、框架可升级
|
||
9. **考试作答可靠性**：断网不丢草稿、时间对齐服务器、防作弊采集、防重复提交
|
||
10. **学生隐私保护**：PIPL/未成年人保护法合规，敏感数据最小化
|
||
|
||
### 20.3 与其他 portal 的协同演化
|
||
|
||
| 演化方向 | student-portal 角色 | 协同端 |
|
||
| -------------------------------------- | ------------------------------------ | ------------------------------------ |
|
||
| 共享组件抽取到 packages/ | 消费方（不再在 Remote 内自建组件） | teacher-portal（Shell）+ 其他 Remote |
|
||
| 共享 Hook 抽取到 packages/hooks/ | 消费方 | 同上 |
|
||
| 共享业务模型抽取到 packages/contracts/ | 消费方（类型定义） | 同上 |
|
||
| 多 portal 间通信（如教师↔学生） | 通过后端 BFF/gRPC，不直连其他 Remote | teacher-portal / parent-portal |
|
||
| 跨 portal 路由跳转 | 通过 Shell 统一路由表 | 所有 portal |
|
||
|
||
### 20.4 与后端架构的协同演化
|
||
|
||
| 后端演化 | student-portal 适配 |
|
||
| ------------------------------ | ----------------------------------------------- |
|
||
| BFF GraphQL schema 演进 | `@deprecated` 标注 + Feature Flag 切换 |
|
||
| BFF → BFF + 微前端 API Gateway | student-portal 不感知；urql client URL 不变 |
|
||
| 引入 Service Mesh（Istio） | student-portal 不感知；网络层透明 |
|
||
| 引入 Feature Flag 服务 | 集成 FeatureFlagProvider；组件按 flag 渲染 |
|
||
| 引入 A/B Testing 平台 | 集成 ABTestProvider；UI 按 variant 渲染 |
|
||
| 后端多租户 | URL 加 `/{tenantId}/student/*`；Query key 加维度 |
|
||
| 后端多区域 | urql client 按 region 路由；CDN 边缘缓存 |
|
||
| AI 辅导服务（P7） | 新增 SSE 流式消费；复用 teacher-portal AI 模式 |
|
||
|
||
### 20.5 关键技术债务预警
|
||
|
||
| 债务项 | 当前状态 | 紧急度 | 清理建议 |
|
||
| ---------------------------------------- | ---------- | ------ | --------------------------------------------- |
|
||
| ai07 初稿协议错误（REST vs GraphQL） | ✅ 已修订 | 高 | v2 全面对齐 ARB-001 |
|
||
| ai07 初稿端口错误（3001 vs 4001） | ✅ 已修订 | 高 | v2 对齐 port-allocation §4 |
|
||
| ai07 初稿所有权错误（ai07 vs ai14） | ✅ 已修订 | 高 | 004 §15 文档矩阵已记录 ai14 = student-portal |
|
||
| MF SSR 对齐 | 待验证 | 中 | P3 启动前 PoC 验证 MF 2.0 SSR；若失败降级 CSR |
|
||
| GraphQL singleton 分裂风险 | 待验证 | 高 | P3 启动前验证 ARB-002 singleton 生效 |
|
||
| shared-ts / contracts 未建立 | 待 coord | 高 | P3 启动前必须建立；否则 ai14 自行实现后续提取 |
|
||
| ui-tokens / ui-components / hooks 未建立 | 待 ai13 | 高 | P3 启动前必须建立；ai13 在 P2 收尾交付 |
|
||
| MF Remote 加载失败的兜底 | 待实现 | 中 | P3 实现期落地 Shell 内置兜底页 |
|
||
| 跨 tab 同步在 Safari 的兼容性 | 待验证 | 低 | P6 硬化期验证；降级为 storage 事件 |
|
||
| 考试作答 IDB 存储空间管理 | 待实现 | 中 | P3 实现期落地定期清理逻辑 |
|
||
| WebSocket 事件名待 ai10 确认 | 待 ai10 | 中 | P5 启动前确认 `ExamExtended`/`ExamQuestionReordered` |
|
||
|
||
---
|
||
|
||
**AI Agent**: ai14 (student-portal remote)
|
||
**Branch**: feat-review-student-portal-docs-9yN6Av
|
||
**Coordinator**: coord-ai
|
||
**Predecessor**: ai07（初版起草，ai14 接管审计与补全）
|