docs(teacher-portal): ai07 阶段1+2 拆分到4端portal的docs目录

删除合并版README，按portal拆分8份文档(每端01-understanding+02-architecture-design) teacher-portal(shell/P2)+student-portal(remote/P3)+parent-portal(remote/P4)+admin-portal(remote/P6) AI Agent: ai07 (4 portals) Branch: docs/portals-stage1-stage2-design-ai07
2026-07-09 18:23:27 +08:00
parent fd5b6e19ae
commit e691cd267d
9 changed files with 3457 additions and 945 deletions
--- a/apps/student-portal/docs/02-architecture-design.md
+++ b/apps/student-portal/docs/02-architecture-design.md
@@ -0,0 +1,597 @@
+# 模块架构设计文档 — student-portal
+
+> AI：ai07（TS/React · 学习场景域前端 remote）
+> 阶段：阶段 2 交付物
+> 日期：2026-07-09
+> 关联：[阶段 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)
+> 状态：待 coord 交叉审查
+
+---
+
+## 1. 模块内部分层图（student-portal Remote 视角）
+
+```mermaid
+graph TB
+    subgraph Browser["浏览器（学生）"]
+        URL[URL 路由 /student/*]
+    end
+
+    subgraph Shell["teacher-portal（Shell 宿主）"]
+        AppShell[AppShell<br/>左栏导航 + 主内容区]
+        RootLayout[RootLayout<br/>字体/令牌/i18n/Query Provider]
+        SharedDeps["共享依赖暴露<br/>react/react-dom/@tanstack/react-query/zustand/nuqs<br/>ui-components/ui-tokens/contracts/hooks"]
+    end
+
+    subgraph RemoteStudent["student-portal（Remote）"]
+        StudentPages["学习场景页面<br/>dashboard/homework/submit/exams/take<br/>diagnostic(P4)/weakness(P4)/notifications(P5)"]
+        ExamTaking[ExamTaking 组件<br/>倒计时 + 自动保存]
+        StudentApiClient[ApiClient 实例<br/>注入 student scope token]
+    end
+
+    subgraph Shared["共享层（packages/）"]
+        UITokens[ui-tokens<br/>三层设计令牌]
+        UIComponents[ui-components<br/>shadcn + A11y + ErrorBoundary]
+        Contracts[contracts<br/>Permissions 常量 + 类型]
+        Hooks[hooks<br/>usePermission/useAuth/useA11y]
+        LibTS[shared-ts<br/>ApiClient/Logger/通用工具]
+    end
+
+    subgraph Gateway["api-gateway"]
+        GW[Gin 路由/鉴权/限流]
+    end
+
+    subgraph PushGW["push-gateway（P5）"]
+        WS[WebSocket /ws]
+    end
+
+    Browser --> URL
+    URL --> RootLayout
+    RootLayout --> AppShell
+    AppShell -->|动态加载 Remote| RemoteStudent
+
+    RemoteStudent -->|复用| SharedDeps
+    RemoteStudent --> ExamTaking
+    RemoteStudent --> StudentApiClient
+
+    Shell --> UITokens
+    Shell --> UIComponents
+    Shell --> Contracts
+    Shell --> Hooks
+    Shell --> LibTS
+    RemoteStudent --> UITokens
+    RemoteStudent --> UIComponents
+    RemoteStudent --> Contracts
+    RemoteStudent --> Hooks
+
+    StudentApiClient -->|fetch /api/v1/student/*| GW
+    StudentApiClient -->|fetch /api/v1/iam/*| GW
+    StudentApiClient -->|fetch /api/v1/notifications/*| GW
+
+    RemoteStudent -.->|P5 WebSocket| WS
+    WS -.->|推送事件| RemoteStudent
+```
+
+### 1.1 Remote 角色定位
+
+student-portal 作为 **Remote 子应用**，由 teacher-portal Shell 动态加载。与 Shell 的职责分工：
+
+| 职责                             | Shell（teacher-portal） | Remote（student-portal） |
+| -------------------------------- | ----------------------- | ------------------------ |
+| RootLayout（字体/令牌/Provider） | ✅ 提供                 | ❌ 复用                  |
+| AppShell（左栏 + 主内容区）      | ✅ 提供                 | ❌ 复用                  |
+| 共享依赖暴露（singleton）        | ✅ 提供                 | ❌ 消费                  |
+| 登录页                           | ✅ 提供                 | ❌ 复用                  |
+| 路由表 `/student/*`              | ❌ 由 Remote 暴露       | ✅ 提供                  |
+| 学习场景页面                     | ❌                      | ✅                       |
+| ApiClient 实例                   | ❌ 提供 ApiClient 类    | ✅ 注入 student scope    |
+| 业务组件（ExamTaking 等）        | ❌                      | ✅                       |
+
+### 1.2 MF 配置（student-portal/next.config.js）
+
+```javascript
+// student-portal/next.config.js（Remote）
+const NextFederationPlugin = require("@module-federation/nextjs-mf");
+
+const remotes = (isServer) => ({
+  teacher: `teacher_app@http://localhost:3000/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`,
+});
+
+module.exports = {
+  reactStrictMode: true,
+  webpack(config, { isServer }) {
+    config.plugins.push(
+      new NextFederationPlugin({
+        name: "student_app",
+        filename: "static/chunks/remoteEntry.js",
+        remotes: remotes(isServer),
+        exposes: {
+          "./pages": "./src/pages",
+          "./ExamTaking": "./src/components/ExamTaking",
+        },
+        shared: {
+          react: { singleton: true, requiredVersion: "^18.3.0" },
+          "react-dom": { singleton: true, requiredVersion: "^18.3.0" },
+          "@tanstack/react-query": { singleton: true },
+          zustand: { singleton: true },
+          nuqs: { singleton: true },
+        },
+        extraOptions: { exposePages: false },
+      }),
+    );
+    return config;
+  },
+  async rewrites() {
+    return [
+      {
+        source: "/api/v1/:path*",
+        destination: `${process.env.API_GATEWAY_URL || "http://localhost:8080"}/api/v1/:path*`,
+      },
+    ];
+  },
+};
+```
+
+**关键点**：
+
+- `name: 'student_app'`：Remote 应用名，与 Shell 中 `remotes.student` 对应
+- `exposes`：暴露页面入口 `./pages` 和 student 特有组件 `./ExamTaking`
+- `remotes.teacher`：引用 Shell 提供的 AppShell 和 shared-deps
+- `shared`：与 Shell 一致的 singleton 策略，保证 React/Query/Zustand 单例
+- `rewrites`：与 Shell 一致的 `/api/v1/*` 代理到 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'`。来源：`GET /api/v1/student/viewports`（student-bff 聚合 iam 视口配置）。AppShell 按 `scope='student'` 过滤渲染学生端导航。
+
+### 2.3 权限模型（Permission）
+
+复用 Shell 的 PermissionState 模型。来源：`GET /api/v1/iam/effective-permissions` → `{ permissions, viewports, dataScope }`。学生 dataScope 固定为 L0（仅本人）。
+
+### 2.4 student-portal 特有视图模型
+
+```typescript
+// 考试作答草稿（Zustand L3，断网恢复用）
+interface ExamTakingDraft {
+  examId: string;
+  answers: Record<string, AnswerInput>; // questionId → answer
+  startedAt: number;
+  lastSavedAt: number | null;
+  durationSeconds: number; // 考试时长（秒）
+}
+
+// 作业提交表单（react-hook-form L5）
+interface HomeworkSubmitForm {
+  homeworkId: string;
+  answers: AnswerInput[];
+  attachments?: File[]; // 附件（图片/PDF）
+  note?: string; // 学生备注
+}
+```
+
+## 3. 数据模型（前端缓存策略）
+
+前端无数据库，仅有缓存层。student-portal 缓存策略偏短（学生数据实时性要求高）：
+
+| 数据类型                  | 存储                      | TTL  | 失效策略                                                  |
+| ------------------------- | ------------------------- | ---- | --------------------------------------------------------- |
+| Session（token + user）   | localStorage + Zustand    | —    | 复用 Shell：access 15min / refresh 7day，401 自动 refresh |
+| 权限列表                  | TanStack Query cache      | 5min | 复用 Shell：角色变更事件 invalidate                       |
+| 视口列表（scope=student） | TanStack Query cache      | 5min | 复用 Shell                                                |
+| 学生 Dashboard 聚合数据   | TanStack Query cache      | 30s  | staleTime 30s，事件触发 invalidate                        |
+| 我的作业列表              | TanStack Query cache      | 30s  | staleTime 30s，提交后 invalidate                          |
+| 我的考试列表              | TanStack Query cache      | 30s  | staleTime 30s，ExamPublished 事件 invalidate              |
+| 考试作答草稿              | Zustand L3 + localStorage | —    | 卸载不销毁，自动保存（每 30s + blur 时）                  |
+| 学情诊断数据              | TanStack Query cache      | 30s  | staleTime 30s（实时性由 BFF 决定）                        |
+| 错题本列表                | TanStack Query cache      | 30s  | staleTime 30s                                             |
+| 通知列表（P5）            | TanStack Query cache      | 30s  | staleTime 30s，WebSocket 事件 invalidate                  |
+| URL 状态（分页/筛选）     | nuqs                      | —    | 永久（可分享）                                            |
+| 表单临时态（作业提交）    | react-hook-form           | —    | 卸载即销毁                                                |
+
+## 4. API 设计（前端 → 后端）
+
+前端不设计后端 API，仅声明消费的端点。详见 [01-understanding.md §3.1](./01-understanding.md)。
+
+### 4.1 统一 API 请求层（复用 Shell ApiClient）
+
+student-portal **不重复实现 ApiClient 类**，复用 `packages/shared-ts/src/api-client.ts`（详见 [teacher-portal 阶段 2 §4.1](../../teacher-portal/docs/02-architecture-design.md#41-统一-api-请求层libapits)）。
+
+student-portal 仅注入不同 baseUrl/token 和 scope 标记：
+
+```typescript
+// apps/student-portal/src/lib/api.ts
+import { ApiClient } from "@edu/shared-ts";
+import { useAuth } from "@edu/hooks";
+
+export function useStudentApi(): ApiClient {
+  const { getToken, logout } = useAuth();
+  return useMemo(
+    () =>
+      new ApiClient({
+        baseUrl: "", // 走 Next.js rewrites
+        getToken,
+        onUnauthorized: logout,
+        scope: "student", // 日志/trace 标记
+      }),
+    [getToken, logout],
+  );
+}
+```
+
+**职责**（与 Shell 一致，由 shared-ts ApiClient 承担）：
+
+- 自动注入 `Authorization: Bearer ${token}`
+- 401 自动 refresh token 一次，失败调 `onUnauthorized`
+- 解析 `ActionState`，success=false 抛 `ApiError`
+- 按 `error.code` 前缀路由 i18n key
+- 全局错误 toast（除 401）
+- 请求/响应 trace_id 透传（从响应头 `X-Request-Id` 提取）
+
+### 4.2 TanStack Query 约定
+
+```typescript
+// Query Key 命名：[scope, resource, ...args]
+queryKey: ["student", "dashboard"];
+queryKey: ["student", "homework", { status, page }];
+queryKey: ["student", "exams", { status }];
+queryKey: ["student", "exam-taking", examId];
+queryKey: ["student", "diagnostic"];
+queryKey: ["student", "weakness", { knowledgePointId }];
+queryKey: ["student", "notifications", { unreadOnly }];
+queryKey: ["session", "effective-permissions"]; // 复用 Shell
+queryKey: ["session", "viewports", "student"]; // 复用 Shell
+
+// Mutation 约定
+const submitHomework = useMutation({
+  mutationFn: (input) =>
+    api.post(`/api/v1/student/homework/${input.homeworkId}/submit`, input),
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: ["student", "homework"] });
+    toast.success(t("homework.submitSuccess"));
+  },
+  onError: (e: ApiError) => toast.error(e.message),
+});
+
+const saveExamAnswer = useMutation({
+  mutationFn: (input) =>
+    api.post(`/api/v1/student/exams/${input.examId}/answers`, input),
+  onSuccess: (data) => {
+    // 更新本地草稿的 lastSavedAt
+    examTakingStore.updateLastSavedAt(data.savedAt);
+  },
+  onError: (e: ApiError) => {
+    // 草稿保留在本地，下次 blur/定时重试
+    logger.warn("exam answer save failed", { examId: e.details });
+  },
+});
+```
+
+## 5. 事件设计
+
+前端不发布 Kafka 事件，仅消费 WebSocket 推送（P5）。
+
+### 5.1 WebSocket 推送（P5）
+
+| 事件                          | 触发           | student-portal 前端动作                                         |
+| ----------------------------- | -------------- | --------------------------------------------------------------- |
+| `NotificationRequested`       | msg 服务投递   | toast 提示 + 通知中心未读数 +1                                  |
+| `ExamPublished`               | 教师发布考试   | toast + `["student","exams"]` invalidate + dashboard invalidate |
+| `GradeRecorded`               | 教师录入成绩   | toast + `["student","grades"]` invalidate                       |
+| `HomeworkDeadlineApproaching` | 作业截止前提醒 | toast + 作业列表高亮 + `["student","homework"]` invalidate      |
+
+### 5.2 WebSocket 连接管理（P5）
+
+```typescript
+// apps/student-portal/src/lib/ws.ts（P5 实现）
+export function useStudentWebSocket() {
+  const { getToken } = useAuth();
+  const queryClient = useQueryClient();
+
+  useEffect(() => {
+    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;
+      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 "GradeRecorded":
+          toast.success(t("grade.recorded"));
+          queryClient.invalidateQueries({ queryKey: ["student", "grades"] });
+          break;
+        case "HomeworkDeadlineApproaching":
+          toast.warning(
+            t("homework.deadlineApproaching", {
+              name: msg.payload.homeworkName,
+            }),
+          );
+          queryClient.invalidateQueries({ queryKey: ["student", "homework"] });
+          break;
+      }
+    };
+    return () => ws.close();
+  }, [getToken, queryClient]);
+}
+```
+
+### 5.3 考试作答自动保存（SSE / HTTP 轮询）
+
+> 考试作答的自动保存采用 HTTP POST（每 30s + blur 时），不使用 SSE。SSE 仅 teacher-portal 用于 AI 流式出题，student-portal 不涉及。
+
+## 6. 横切关注点对齐清单
+
+### 6.1 权限（前端等价）
+
+| 路由                           | requiredPermission       |
+| ------------------------------ | ------------------------ |
+| `/student/dashboard`           | `STUDENT_DASHBOARD_VIEW` |
+| `/student/homework`            | `HOMEWORK_READ_OWN`      |
+| `/student/homework/:id/submit` | `HOMEWORK_SUBMIT`        |
+| `/student/exams`               | `EXAMS_READ_OWN`         |
+| `/student/exams/:id/take`      | `EXAMS_TAKE`             |
+| `/student/diagnostic`          | `DIAGNOSTIC_READ_OWN`    |
+| `/student/weakness`            | `WEAKNESS_READ_OWN`      |
+| `/student/notifications`       | `NOTIFICATION_READ_OWN`  |
+
+> 完整权限点常量集中在 `packages/contracts/src/permissions.ts`（待建立，coord 负责 contracts，ai07 负责调用）。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}}`  |
+| `EXAMS_`       | core-edu    | `exams.error.{{code}}`    |
+| `HOMEWORK_`    | core-edu    | `homework.error.{{code}}` |
+| `GRADES_`      | core-edu    | `grades.error.{{code}}`   |
+| `BFF_STUDENT_` | student-bff | `bff.error.{{code}}`      |
+| `GW_`          | api-gateway | `gateway.error.{{code}}`  |
+| `NETWORK_`     | 前端网络层  | `network.error.{{code}}`  |
+
+### 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 | 同上                                                |
+
+P6 接入，P3-P5 暂缓。
+
+### 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` 可达 + 内存 < 阈值          |
+
+### 6.7 优雅关闭
+
+Next.js 无长连接（除 WS），无需特殊处理。WS 在 P5 由 push-gateway 管理，前端断线自动重连（指数退避，最多 5 次）。
+
+## 7. 共享组件库（复用 Shell 暴露 + student 特有）
+
+### 7.1 复用 Shell 暴露的组件（packages/ui-components/）
+
+| 组件                                       | 用途                                                                                                | 来源                           |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------ |
+| `AppShell`                                 | 左侧栏 + 主内容区布局                                                                               | 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 暴露                     |
+
+### 7.2 student-portal 特有组件（不暴露给 Shell）
+
+| 组件              | 用途                                          | 来源 | 是否暴露给 Shell                            |
+| ----------------- | --------------------------------------------- | ---- | ------------------------------------------- |
+| `ExamTaking`      | 考试作答（倒计时 + 自动保存 + 断网恢复）      | 新建 | ✅ 暴露 `./ExamTaking`（供 Shell 路由复用） |
+| `HomeworkSubmit`  | 作业提交表单（react-hook-form + zodResolver） | 新建 | ❌ 内部使用                                 |
+| `DiagnosticChart` | 学情诊断图表（recharts 多维雷达 + 趋势线）    | 新建 | ❌ 内部使用                                 |
+| `WeaknessList`    | 错题本列表（按知识点聚合 + 掌握度标签）       | 新建 | ❌ 内部使用                                 |
+
+### 7.3 不使用的组件（与 teacher-portal 差异）
+
+- **不使用 `RichTextEditor`（Tiptap）**：学生不作答富文本，作业提交用表单
+- 不使用 `SSEViewer`：学生不参与 AI 出题
+- 不使用 `ChildSwitcher`：学生无多子女切换（家长端特有）
+- 不使用 `UserManagementTable`：学生不管理用户
+
+## 8. 共享 Hooks（复用 Shell 暴露）
+
+| Hook                  | 职责                                                | 来源       |
+| --------------------- | --------------------------------------------------- | ---------- |
+| `useAuth()`           | 会话状态（user/token/refresh/login/logout）         | Shell 暴露 |
+| `usePermission()`     | 权限查询（hasPermission/hasAny/hasAll + dataScope） | Shell 暴露 |
+| `useViewports(scope)` | 视口列表（按 scope 过滤）                           | Shell 暴露 |
+| `useApi()`            | ApiClient 实例（注入 token + 401 处理）             | Shell 暴露 |
+| `useA11yId()`         | 唯一 ARIA ID 生成                                   | Shell 暴露 |
+| `useAriaLive()`       | aria-live 区域管理                                  | Shell 暴露 |
+| `useToast()`          | 全局 toast（Zustand ui-store）                      | Shell 暴露 |
+
+## 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  | HTTP/REST          | `/api/v1/*` 代理                     | 全部业务请求                 | P1+  |
+| 调用   | push-gateway | WebSocket          | `ws://push-gateway/ws`               | 实时推送                     | P5   |
+| 被调用 | —            | —                  | —                                    | 前端不暴露接口给其他服务     | —    |
+| 消费   | student-bff  | HTTP（经 Gateway） | `GET /student/viewports` 等          | 学生场景聚合                 | P3+  |
+| 消费   | iam          | HTTP（经 Gateway） | `/iam/*`                             | 登录/权限/视口               | P2+  |
+| 消费   | core-edu     | HTTP（经 Gateway） | `/exams/*` `/homework/*` `/grades/*` | 教学核心（学生视角）         | P3+  |
+| 消费   | data-ana     | HTTP（经 Gateway） | `/analytics/*`                       | 学情分析                     | P4+  |
+| 消费   | msg          | HTTP（经 Gateway） | `/notifications/*`                   | 通知中心                     | P5+  |
+| 依赖   | coord 维护   | —                  | `packages/shared-proto`              | TS 类型（仅 contracts 部分） | P1+  |
+| 依赖   | coord 维护   | —                  | `packages/shared-ts`（待建）         | ApiClient/Logger/通用工具    | P3+  |
+| 依赖   | ai07 维护    | —                  | `packages/ui-tokens`（待建）         | 三层设计令牌                 | P3+  |
+| 依赖   | ai07 维护    | —                  | `packages/ui-components`（待建）     | shadcn + 共享组件            | P3+  |
+| 依赖   | ai07 维护    | —                  | `packages/hooks`（待建）             | usePermission/useAuth 等     | P3+  |
+| 依赖   | coord 维护   | —                  | `packages/contracts`（待建）         | Permissions 常量 + 类型      | P3+  |
+
+> **proto 不直接消费**：前端不调用 gRPC，BFF 把 gRPC 聚合为 REST 暴露给前端。前端仅消费 `packages/contracts/src/permissions.ts` 中的权限点常量（TS 文件，非 proto 生成）。
+
+## 11. 风险与假设
+
+### 11.1 假设
+
+1. **假设 coord 建立 `packages/shared-ts`、`packages/contracts`**：包含 ApiClient、Logger、Permissions 常量、通用类型。若 coord 未建立，ai07 自行在 `apps/student-portal/src/shared/` 内实现，后续提取到 packages。
+2. **假设 ai04 student-bff 提供 `GET /student/viewports`、`GET /student/dashboard`、`GET /student/homework`、`POST /student/homework/:id/submit`、`GET /student/diagnostic`**：返回 `ActionState` 结构。错误码前缀 `BFF_STUDENT_`（待 ai04 确认）。
+3. **假设 teacher-portal Shell 已就绪**：AppShell + 共享依赖暴露 + MF 配置（P2 收尾完成）。student-portal 作为 Remote 才能挂载。
+4. **假设 Next.js 14+ Module Federation 2.0 稳定**：`@module-federation/nextjs-mf` 在 Next.js App Router 下可用。若不稳定，降级为 4 端独立部署 + 各自 Shell（重复实现 AppShell）。
+
+### 11.2 技术风险
+
+| 风险                    | 影响                                                        | 缓解                                                                   |
+| ----------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------- |
+| MF Remote SSR 对齐复杂  | Remote 在 SSR 时需 Shell 提供上下文                         | 优先 CSR，SSR 仅用于首屏 dashboard；MF 2.0 支持 SSR                    |
+| 共享依赖版本漂移        | Remote 与 Shell 的 react/react-dom 版本不一致导致运行时错误 | MF `shared.singleton: true` + CI 检查版本对齐                          |
+| 考试作答断网丢失        | 学生作答过程中断网，草稿丢失                                | Zustand L3 + localStorage 双写，每 30s + blur 时自动保存，重连后重试   |
+| 考试倒计时不准          | 学生端时间与服务器时间偏差                                  | 倒计时基于服务器返回的 `expiresAt`，前端仅做展示，提交以服务器时间为准 |
+| 缓存陈旧导致看到旧作业  | 学生看到已截止的作业                                        | staleTime 30s + 截止时间客户端校验 + 提交时服务端二次校验              |
+| Token 刷新竞态          | 多请求同时 401 触发多次 refresh                             | ApiClient 全局单例 + refresh promise 复用（复用 Shell）                |
+| 权限缓存陈旧            | 角色变更后前端 5min 内仍用旧权限                            | iam 角色变更发 Kafka 事件 → msg 推送 WebSocket → 前端 invalidate       |
+| TanStack Query 缓存膨胀 | 长时间使用后缓存项过多                                      | `gcTime` 5min + `staleTime` 按数据类型分级                             |
+
+### 11.3 未决设计决策（需 coord 仲裁）
+
+与 teacher-portal 相同的 4 项（详见 [teacher-portal 阶段 2 §11.3](../../teacher-portal/docs/02-architecture-design.md#113-未决设计决策需-coord-仲裁)）：
+
+1. **packages 归属**：`ui-tokens` / `ui-components` / `hooks` 是 ai07 维护还是 coord 维护？建议：ai07 维护（前端专属），coord 仅维护 `shared-ts` / `contracts`（跨语言/跨服务）。
+2. **GraphQL vs REST**：student-bff 是 REST 还是 GraphQL？前端 API 请求层是否需要 GraphQL client（urql/apollo）？建议：P3-P4 用 REST，若 BFF 切 GraphQL 再引入 urql。
+3. **i18n key 命名**：`error.{{service}}.{{code_snake_case}}` 还是其他模式？建议：与 teacher-portal 对齐。
+4. **MF 暴露粒度**：Shell 暴露整个 AppShell 还是更细粒度的组件？建议：暴露 AppShell 整体 + 各 Remote 自行决定内部布局。
+
+## 12. coord 交叉审查所需信息
+
+### 12.1 端口矩阵
+
+| 端             | dev 端口 | 生产端口 | 备注          |
+| -------------- | -------- | -------- | ------------- |
+| student-portal | 3001     | 3001     | Remote 子应用 |
+
+> 与 [full-stack-runbook](../../../docs/standards/full-stack-runbook.md) 端口矩阵对齐。
+
+### 12.2 依赖的共享包（需 coord 建立）
+
+| 包              | 路径                      | 维护方       | 内容                                              |
+| --------------- | ------------------------- | ------------ | ------------------------------------------------- |
+| `shared-ts`     | `packages/shared-ts/`     | coord        | ApiClient、Logger、通用工具                       |
+| `contracts`     | `packages/contracts/`     | coord        | Permissions 常量、ActionState 类型、UserInfo 类型 |
+| `ui-tokens`     | `packages/ui-tokens/`     | ai07（建议） | 三层设计令牌                                      |
+| `ui-components` | `packages/ui-components/` | ai07（建议） | shadcn + ErrorBoundary + RequirePermission        |
+| `hooks`         | `packages/hooks/`         | ai07（建议） | usePermission、useAuth、useViewports              |
+
+### 12.3 依赖的后端契约（需对应 AI 确认）
+
+| 契约                                                               | 提供方             | 当前状态        |
+| ------------------------------------------------------------------ | ------------------ | --------------- |
+| `POST /iam/login`、`GET /iam/effective-permissions`、`GET /iam/me` | iam                | ✅ 已实现       |
+| `GET /student/viewports`、`GET /student/dashboard` 等              | student-bff        | 📐 待 ai04 设计 |
+| `/exams/*` `/homework/*` `/grades/*`                               | core-edu           | ✅ 已实现（P3） |
+| `/analytics/*`                                                     | data-ana           | ✅ 已实现（P4） |
+| `/notifications/*` + WebSocket 推送                                | msg + push-gateway | 📐 待 P5        |
+
+### 12.4 错误码前缀（前端 i18n 路由依赖）
+
+前端不产生错误码，仅消费。需各服务确认错误码前缀不重叠：
+
+| 前缀                           | 服务        | 状态            |
+| ------------------------------ | ----------- | --------------- |
+| `IAM_`                         | iam         | ✅ 已用         |
+| `EXAMS_`/`HOMEWORK_`/`GRADES_` | core-edu    | ⚠️ 待确认       |
+| `BFF_STUDENT_`                 | student-bff | ⚠️ 待 ai04 确认 |
+| `GW_`                          | api-gateway | ✅ 已用         |
+| `NETWORK_`                     | 前端        | ai07 自有       |
+
+### 12.5 不产生 Kafka 事件
+
+前端不发布/消费 Kafka 事件。WebSocket 推送由 push-gateway 消费 Kafka 转发。
+
+## 13. 实施路线（ai07 自用）
+
+### P3（student-portal 起步）
+
+1. 建 `apps/student-portal/`（Remote 角色）
+2. 配置 MF（`exposes: { './pages', './ExamTaking' }`，`remotes: { teacher: ... }`）
+3. 实现 Dashboard + 我的作业 + 提交作业 + 我的考试 + 作答考试
+4. 复用 Shell 的 AppShell + 共享组件（RequirePermission/ErrorBoundary/Loading/Empty/DataTable/Form/Chart）
+5. 考试作答自动保存（HTTP POST 每 30s + blur 时，Zustand L3 + localStorage 双写草稿）
+6. 配置 Dockerfile 多阶段构建 + `/api/health` + `/api/ready` route
+7. 补 Vitest 单测 + Playwright E2E（覆盖率 ≥ 80%）
+
+### P4（学情诊断 + 错题本）
+
+1. 实现学情诊断页面（DiagnosticChart 多维雷达 + 趋势线）
+2. 实现错题本页面（WeaknessList 按知识点聚合 + 掌握度标签）
+
+### P5（推送 + 通知中心）
+
+1. student-portal 接入 WebSocket（push-gateway）
+2. 实现通知中心页面（通知列表 + 未读数 + 标记已读）
+3. 处理 4 类推送事件（NotificationRequested/ExamPublished/GradeRecorded/HomeworkDeadlineApproaching）
+
+### P6（硬化）
+
+1. Web Vitals + OTel browser SDK 接入
+2. A11y WCAG 2.2 AA 审计
+3. 性能优化（MF shared 单例验证、bundle 分析）
+
+---
+
+**AI Agent**: ai07 (student-portal remote)
+**Branch**: docs/student-portal-stage1-stage2-design-ai07
+**Coordinator**: coord-ai