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

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

Browse Source 
删除合并版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
This commit is contained in:
SpecialX
2026-07-09 18:23:27 +08:00
parent fd5b6e19ae
commit e691cd267d
9 changed files with 3457 additions and 945 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
apps/teacher-portal/docs/01-understanding.md Normal file
View File

@@ -0,0 +1,205 @@
# 模块理解确认书 — teacher-portal
> AI：ai07（TS/React · 教学场景域前端 shell）
> 阶段：阶段 1 交付物
> 日期：2026-07-09
> 关联：[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) §1.1a/1.1b/§5.4、[AI 分配方案](../../../docs/architecture/ai-allocation.md) §5 ai13/ai07、[pending-features P2](../../../docs/architecture/roadmap/pending-features.md)、[known-issues §2.12](../../../docs/troubleshooting/known-issues.md)
---
## 1. 我在架构中的位置
- **层级**：L2 微前端层（004 §3.1 六层架构中的前端层）
- **MF 角色**：**Shell 宿主**（主应用），其余 3 端（student/parent/admin-portal）作为 Remote 子应用挂载
- **上游（谁调用我）**：浏览器（教师 / 教导主任 / 教研组长）
- **下游（同步）**：api-gateway（REST，经 Next.js `rewrites` 代理 `/api/v1/*`）
- **下游（推送，P5）**：push-gateway（WebSocket/SSE）
- **BFF 对接**：teacher-bff（GraphQL Yoga + DataLoader，P2-P3 用 REST 过渡）
- **通信方式**：HTTP/REST（前端→Gateway）+ WebSocket（前端→push-gateway，P5）
- **不直连**：前端不直连任何业务服务或 BFF 后端实例，全部经 api-gateway 代理
**说明**：
- 通过 `next.config.js` 的 `rewrites` 将 `/api/v1/*` 代理到 `api-gateway`
- MF 架构下，teacher-portal 作为 Shell 宿主提供 AppShell + 共享组件库 + 权限 Hook + API 请求层
- 场景域 BFF 复用策略（004 §5.4）：教导主任/教研组长复用 teacher-portal + 额外管理视口，不单独建 portal
## 2. 我的限界上下文
### 2.1 我负责的聚合 / 实体（前端视图模型）
- 班级、考试、作业、成绩、备课、AI 出题（教学场景域前端视图）
- 会话状态（Session）、视口（Viewport）、权限（Permission）
### 2.2 业务领域
- **D3 教学核心领域**（前端场景域：教学场景域）
### 2.3 不负责
- 学生作答界面（归 student-portal）
- 家长多子女切换（归 parent-portal）
- 用户/角色/权限 CRUD（归 admin-portal）
### 2.4 数据范围
- DataScope L1-L5（教师 L1 班级 / 教导主任 L2 年级 / 校管理员 L3 学校 / 区教研员 L4 / 系统管理员 L5）
## 3. 我与外部的契约
### 3.1 消费的后端 API（经 api-gateway 代理）
| 路径前缀 | 下游 BFF/服务 | 关键端点 |
| ------------------------------------------------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/v1/iam/*` | iam | `POST /iam/login`、`POST /iam/register`、`POST /iam/refresh`、`GET /iam/me`、`GET /iam/rbac/...`、`GET /iam/effective-permissions` |
| `/api/v1/teacher/*` | teacher-bff | `GET /teacher/viewports`、`GET /teacher/dashboard`、`GET /teacher/classes/:id/exams`、`GET /teacher/classes/:id/homework`、`GET /teacher/exams/:id/grades` |
| `/api/v1/classes/*` | core-edu（classes 模块） | CRUD（黄金模板） |
| `/api/v1/exams/*` `/api/v1/homework/*` `/api/v1/grades/*` | core-edu | P3 教学核心 |
| `/api/v1/textbooks/*` `/api/v1/knowledge-points/*` `/api/v1/questions/*` | content | P4 内容 |
| `/api/v1/ai/*` | ai（SSE 流式） | P5 AI 辅助出题 |
| `/api/v1/notifications/*` | msg | 通知中心（P5） |
### 3.2 统一响应契约
所有后端响应遵循 `ActionState` 结构（迁移指南 §7.5）：
```typescript
type ActionState<T> =
| { success: true; data: T }
| {
success: false;
error: { code: string; message: string; details?: unknown };
};
```
错误码前缀按服务名大写（如 `IAM_`、`CORE_EDU_`、`CONTENT_`、`MSG_`、`AI_`、`BFF_TEACHER_`、`GW_`）。前端 API 请求层根据 `error.code` 前缀路由到对应的 i18n key。
### 3.3 推送契约（P5）
| 协议 | 场景 |
| ------------------------- | -------------------------------------------- |
| WebSocket（push-gateway） | 学生提交作业通知、考试成绩录入提醒、全校广播 |
| SSE（ai 服务） | AI 辅助出题流式响应 |
### 3.4 proto 不直接消费
前端不调用 gRPC，BFF 把 gRPC 聚合为 REST/GraphQL 暴露给前端。前端仅消费 `packages/contracts/src/permissions.ts` 中的权限点常量（TS 文件，非 proto 生成）。
## 4. 我的技术栈
| 维度 | 选型 | 说明 |
| --------------------------- | -------------------------------------------------------- | ---------------------------------------------- |
| 框架 | Next.js 14+（App Router） | server components 默认，client components 按需 |
| 语言 | TypeScript 5.5+（strict） | 沿用 tsconfig.base.json |
| 微前端 | Module Federation 2.0（@module-federation/nextjs-mf） | teacher-portal = Shell |
| 样式 | Tailwind CSS 3.4+ | 配合设计令牌三层模型 |
| UI 组件库 | shadcn/ui（迁移指南 §7.2） | 平移至 `packages/ui-components/`，MF 共享 |
| 状态管理 L1 URL | nuqs | 可分享、可刷新状态 |
| 状态管理 L2 Server | TanStack Query v5 | 服务端数据缓存、重试、乐观更新 |
| 状态管理 L3 Client Business | Zustand slice | 客户端业务状态 |
| 状态管理 L4 Global UI | Zustand ui-store + ModalRoot | 全局 UI 状态 |
| 状态管理 L5 Form | react-hook-form + zodResolver | 表单状态 |
| 富文本 | Tiptap（备课、出题、反馈） | SSR 安全 |
| 图表 | recharts | 学情、Dashboard |
| i18n | next-intl | BFF/服务返回 i18n key + 参数，前端翻译 |
| A11y | eslint-plugin-jsx-a11y（error 级） | WCAG 2.2 AA |
| 字体 | Inter（sans）/ Fraunces（serif）/ JetBrains Mono（mono） | next/font/google 加载，CSS 变量暴露 |
## 5. 我的阶段归属
- **阶段**：P2
- **当前状态**：✅ 已实现 P1 测试页 + P2 骨架（登录/AppShell/Dashboard/classes CRUD）；⚠️ 待审计对齐黄金模板 + 引入 MF + 共享组件库
- **依赖上游阶段**：P1（api-gateway + classes + iam）
## 6. 我需要对齐的黄金模板项（对照 classes 服务）
> 前端无 `@RequirePermission` 装饰器（后端概念），对齐项改造为前端等价物。
| 对齐项 | classes（后端黄金模板） | teacher-portal 前端等价 | 当前状态 |
| --------------------- | ------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------- |
| 权限校验 | `@RequirePermission(Permissions.XXX)` | `usePermission().hasPermission("XXX")` Hook + `<RequirePermission>` 组件 | ❌ 缺失，直接硬编码 `user.roles.join(", ")` |
| 错误码前缀统一 | `CLASSES_*`、`IAM_*` | API 请求层根据 `error.code` 前缀路由 i18n | ❌ 缺失统一请求层 |
| logger | pino | 前端 console + Sentry（P6） | ⚠️ 仅 console.error |
| metrics | prom-client `/metrics` | 前端 Web Vitals → Gateway 上报 | ❌ 缺失 |
| tracer | OTel SDK | 前端 OTel browser SDK（P6） | ❌ 缺失 |
| /healthz + /readyz | `GET /healthz` `GET /readyz` | Next.js `/api/health` route + Dockerfile HEALTHCHECK | ⚠️ Dockerfile 有 HEALTHCHECK，无 /api/health |
| 优雅关闭 | SIGTERM handler | Next.js 无长连接，无需 | ✅ N/A |
| 测试覆盖率 ≥ 80% | Vitest | Vitest + @testing-library/react + Playwright E2E | ❌ 0% |
| Dockerfile 多阶段构建 | builder + runtime | 已有多阶段 | ✅ 已对齐 |
| Zod 输入验证 | class-validator + Zod schema | react-hook-form + zodResolver | ❌ 缺失 |
| GlobalErrorFilter | NestJS 全局异常过滤器 | React ErrorBoundary + API 请求层统一错误处理 | ❌ 缺失 |
| 设计令牌三层 | — | primitive.css / semantic-light/dark.css / tailwind-theme.css | ❌ 硬编码在 globals.css + tailwind.config.js |
| A11y 工具集 | — | useA11yId / mergeA11yProps / describeInput / focus-trap | ❌ 缺失 |
---
## 附：teacher-portal 现状审计（对齐黄金模板）
### 审计表
| 维度 | 状态 | 说明 |
| ------------------------------------ | ------ | ---------------------------------------------------------------------- |
| 权限装饰器（前端等价 usePermission） | ❌ | AppShell.tsx 直接 `user.roles.join(", ")`，违反 project_rules §3.8 |
| 错误码前缀 | ❌ | 无统一 API 请求层，错误处理散落在每个 page.tsx |
| logger | ⚠️ | 仅 `console.error`，无结构化、无 trace_id |
| metrics | ❌ | 无 Web Vitals 采集 |
| tracer | ❌ | 无 OTel browser SDK |
| /healthz | ⚠️ | Dockerfile 有 `HEALTHCHECK wget /`，但无 `/api/health` route |
| /readyz | ❌ | 无 |
| 优雅关闭 | ✅ N/A | Next.js 无长连接 |
| 测试覆盖率 | ❌ | 0%，无测试文件 |
| Dockerfile 多阶段 | ✅ | builder + runtime，非 root 用户，HEALTHCHECK |
| Zod 输入验证 | ❌ | 表单直接 useState，无 zodResolver |
| GlobalErrorFilter（ErrorBoundary） | ❌ | 无 React ErrorBoundary |
| 设计令牌三层 | ❌ | 硬编码在 globals.css（`:root` 变量）+ tailwind.config.js（hex 字面量） |
| A11y 工具集 | ❌ | 无 useA11yId、focus-trap 等 |
| Module Federation 配置 | ❌ | next.config.js 仅有 rewrites，无 MF |
| 5 层状态管理 | ❌ | 仅 useState + localStorage，无 nuqs/TanStack Query/Zustand |
| 共享组件库 | ❌ | 仅 AppShell，无 ErrorBoundary/Loading/Empty/RequirePermission |
| i18n | ❌ | 中文硬编码在 JSX |
| API 请求层 | ❌ | 每页重复 fetch + authHeaders + try/catch |
| ESLint flat config 自定义规则 | ❌ | 未配置 no-hardcoded-fonts / design-tokens 规则 |
### 现有文件清单
```
apps/teacher-portal/
├─ src/
│ ├─ app/
│ │ ├─ (app)/ # 受保护路由组（套 AppShell）
│ │ │ ├─ classes/page.tsx # 班级 CRUD（P1 测试页）
│ │ │ ├─ dashboard/page.tsx # 教师仪表盘
│ │ │ ├─ exams/page.tsx # 考试列表
│ │ │ ├─ grades/page.tsx # 成绩查询
│ │ │ ├─ homework/page.tsx # 作业列表
│ │ │ └─ layout.tsx # 套 AppShell
│ │ ├─ login/page.tsx # 登录页（不套壳）
│ │ ├─ globals.css # 全局样式 + 设计令牌（硬编码）
│ │ ├─ layout.tsx # 根布局（字体加载）
│ │ └─ page.tsx # 根路径重定向
│ ├─ components/
│ │ └─ AppShell.tsx # 左侧栏 + 主内容区
│ └─ lib/
│ └─ auth.ts # token + userInfo localStorage 管理
├─ Dockerfile # 多阶段构建 ✅
├─ next.config.js # 仅 rewrites，无 MF ❌
├─ package.json # 仅 next/react/react-dom，无 MF/Query/Zustand ❌
├─ tailwind.config.js # 硬编码 hex ❌
├─ postcss.config.js
└─ tsconfig.json
```
### 主要违规点（必须在 P2 收尾或 P3 起步时修复）
1. **权限硬编码**：[AppShell.tsx:143](../src/components/AppShell.tsx) `user.roles.join(", ")` 违反 project_rules §3.8，必须改为 `usePermission().hasPermission()`
2. **设计令牌硬编码**：[globals.css:6-13](../src/app/globals.css) 与 [tailwind.config.js:7-19](../tailwind.config.js) 出现 `hsl(...)` 字面量与 `'Fraunces'`/`'Inter'` 字面量，违反 project_rules §3.10
3. **无统一 API 请求层**：4 个 page.tsx 重复 `authHeaders()` + `fetch` + `try/catch` + `setError`，必须抽取到 `lib/api.ts`
4. **无权限 Hook**：缺少 `usePermission().hasPermission()`，无法做 L3 组件级视口控制
5. **无 ErrorBoundary**：React 渲染异常会白屏
6. **无 5 层状态管理**：登录态用 localStorage（L3），但无 TanStack Query（L2）导致每页重复 fetch
7. **字体名硬编码**：[layout.tsx:3-7](../src/app/layout.tsx) 直接 import `Inter/Fraunces/JetBrains_Mono`，应改为 `var(--font-family-sans/serif/mono)`
---
**AI Agent**: ai07 (teacher-portal shell)
**Branch**: docs/teacher-portal-stage1-stage2-design-ai07

562
apps/teacher-portal/docs/02-architecture-design.md Normal file
View File

@@ -0,0 +1,562 @@
# 模块架构设计文档 — teacher-portal
> AI：ai07（TS/React · 教学场景域前端 shell）
> 阶段：阶段 2 交付物
> 日期：2026-07-09
> 关联：[阶段 1 理解确认书](./01-understanding.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) §5.4、[pending-features P2](../../../docs/architecture/roadmap/pending-features.md)
> 状态：待 coord 交叉审查
---
## 1. 模块内部分层图（4 端统一 MF 架构）
```mermaid
graph TB
subgraph Browser["浏览器"]
URL[URL 路由]
end
subgraph Shell["teacher-portal（Shell 宿主）"]
AppShell[AppShell<br/>左栏导航 + 主内容区]
RootLayout[RootLayout<br/>字体/令牌/i18n Provider]
Router[Next.js App Router]
SharedDeps["共享依赖暴露<br/>react/react-dom/@tanstack/react-query/zustand/nuqs"]
end
subgraph RemoteTeacher["teacher-portal Remote 模块"]
TeacherPages[教学场景页面<br/>dashboard/classes/exams/homework/grades/ai-assist]
end
subgraph RemoteStudent["student-portal（Remote）"]
StudentPages[学习场景页面<br/>dashboard/homework/submit/diagnostic/exam-taking]
end
subgraph RemoteParent["parent-portal（Remote）"]
ParentPages[家长场景页面<br/>dashboard/children-switch/grades/notifications]
end
subgraph RemoteAdmin["admin-portal（Remote）"]
AdminPages[管理场景页面<br/>users/roles/permissions/viewports/monitoring]
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/>通用工具]
end
subgraph Gateway["api-gateway"]
GW[Gin 路由/鉴权/限流]
end
Browser --> URL
URL --> RootLayout
RootLayout --> AppShell
AppShell --> Router
Router -->|动态加载| RemoteTeacher
Router -->|动态加载| RemoteStudent
Router -->|动态加载| RemoteParent
Router -->|动态加载| RemoteAdmin
RemoteTeacher --> SharedDeps
RemoteStudent --> SharedDeps
RemoteParent --> SharedDeps
RemoteAdmin --> SharedDeps
Shell --> UITokens
Shell --> UIComponents
Shell --> Contracts
Shell --> Hooks
RemoteTeacher --> UITokens
RemoteStudent --> UITokens
RemoteParent --> UITokens
RemoteAdmin --> UITokens
AppShell -->|fetch /api/v1/iam/effective-permissions| Hooks
Hooks -->|透传 token| GW
RemoteTeacher -->|fetch /api/v1/teacher/*| GW
RemoteStudent -->|fetch /api/v1/student/*| GW
RemoteParent -->|fetch /api/v1/parent/*| GW
RemoteAdmin -->|fetch /api/v1/iam/* + /api/v1/admin/*| GW
```
### 1.1 MF 拓扑选型
| 方案 | 选否 | 理由 |
| ------------------------------------ | ---- | --------------------------------------------------------------------------------------- |
| 4 端独立部署 + 独立域名 + 各自 Shell | ❌ | 4 套 Shell 重复，登录态/权限/组件库要重复实现 |
| 单 Shell + 4 Remote（**采用**） | ✅ | teacher-portal 作为 Shell 宿主，提供 AppShell + 共享依赖；其余 3 端作为 Remote 动态加载 |
| 单一 Next.js 应用 + 4 路由组 | ❌ | 违反"微前端独立部署"目标（ADR-012） |
**Shell 职责**（teacher-portal）：
- RootLayout（字体、设计令牌、i18n Provider、TanStack QueryClientProvider、Zustand StoreProvider）
- AppShell（左侧导航 + 主内容区 + 用户信息 + 登出）
- 共享依赖暴露（react、react-dom、@tanstack/react-query、zustand、nuqs、ui-components、ui-tokens、contracts、hooks）
- 路由表（4 端路由前缀：`/teacher/*`、`/student/*`、`/parent/*`、`/admin/*`）
- 登录页（统一登录入口，按角色重定向到对应 portal）
### 1.2 MF 配置（teacher-portal/next.config.js）
```javascript
// teacher-portal/next.config.js（Shell）
const NextFederationPlugin = require("@module-federation/nextjs-mf");
const remotes = (isServer) => ({
student: `student_app@http://localhost:3001/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`,
parent: `parent_app@http://localhost:3002/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`,
admin: `admin_app@http://localhost:3003/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`,
});
module.exports = {
reactStrictMode: true,
webpack(config, { isServer }) {
config.plugins.push(
new NextFederationPlugin({
name: "teacher_app",
filename: "static/chunks/remoteEntry.js",
remotes: remotes(isServer),
exposes: {
"./AppShell": "./src/components/AppShell",
"./shared-deps": "./src/shared/deps",
},
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*`,
},
];
},
};
```
> Remote 端配置对称：`name: 'student_app'`，`exposes: { './pages': './src/pages' }`，`remotes: { teacher: 'teacher_app@...' }`。
## 2. 领域模型（前端视角）
前端不持有业务聚合根，仅持有"视图模型"（ViewModel）和"会话状态"。
### 2.1 会话状态（Session）
```typescript
interface Session {
user: UserInfo; // { id, email, name, roles, permissions, dataScope }
tokens: { accessToken: string; refreshToken: string };
viewports: ViewportItem[]; // L1 导航视口
expiresAt: number; // access token 过期时间戳
}
```
存储：Zustand sessionSlice（L3）+ localStorage 持久化（刷新恢复）+ TanStack Query 缓存 `['session']`（L2）。
### 2.2 视口模型（Viewport）
```typescript
interface ViewportItem {
key: string; // 'dashboard' | 'classes' | ...
label: string; // i18n key 或显式文案
route: string; // '/teacher/dashboard'
icon: string | null; // 图标 key（按需）
sortOrder: number; // 排序
requiredPermission: string | null; // 'CLASSES_READ' 等
scope: "teacher" | "student" | "parent" | "admin"; // 标记归属哪个 portal
}
```
来源：`GET /api/v1/{scope}/viewports`（BFF 聚合 iam 视口配置）。AppShell 按 `scope` 过滤渲染对应 portal 的导航。
### 2.3 权限模型（Permission）
```typescript
interface PermissionState {
permissions: string[]; // ['CLASSES_READ', 'EXAMS_CREATE', ...]
dataScope: DataScope; // L0-L5
hasPermission: (perm: string) => boolean;
hasAnyPermission: (perms: string[]) => boolean;
hasAllPermissions: (perms: string[]) => boolean;
}
```
来源：`GET /api/v1/iam/effective-permissions` → `{ permissions, viewports, dataScope }`。Redis 缓存 5min（iam 侧），前端 TanStack Query 缓存 5min，角色变更主动 invalidate。
## 3. 数据模型（前端）
前端无数据库，仅有缓存层：
| 数据类型 | 存储 | TTL | 失效策略 |
| ----------------------- | ---------------------- | --------------------------- | -------------------------------------- |
| Session（token + user） | localStorage + Zustand | access 15min / refresh 7day | 401 自动 refresh，refresh 失败跳登录 |
| 权限列表 | TanStack Query cache | 5min | 角色变更事件 invalidate |
| 视口列表 | TanStack Query cache | 5min | 同上 |
| 班级/年级列表 | TanStack Query cache | 5min | staleTime 5min，mutation 后 invalidate |
| 教学资源详情 | TanStack Query cache | 30s | staleTime 30s |
| 学情宽表 | TanStack Query cache | 30s | staleTime 30s（实时性由 BFF 决定） |
| URL 状态（分页/筛选） | nuqs | — | 永久（可分享） |
| 表单临时态 | react-hook-form | — | 卸载即销毁 |
## 4. API 设计（前端 → 后端）
前端不设计后端 API，仅声明消费的端点。详见 [01-understanding.md §3.1](./01-understanding.md)。
### 4.1 统一 API 请求层（lib/api.ts）
```typescript
// packages/shared-ts/src/api-client.ts（共享）
interface ApiClientOptions {
baseUrl?: string; // 默认 ''（走 Next.js rewrites）
getToken?: () => string | null;
onUnauthorized?: () => void; // 401 → refresh → 重试 / 跳登录
onError?: (error: ApiError) => void; // 全局 toast
}
class ApiClient {
async get<T>(path: string, query?: Record<string, string>): Promise<T>;
async post<T>(path: string, body: unknown): Promise<T>;
async put<T>(path: string, body: unknown): Promise<T>;
async delete<T>(path: string): Promise<T>;
async sse<T>(path: string, body: unknown): AsyncIterable<T>; // AI 流式
}
// 错误结构
interface ApiError {
code: string; // 'IAM_INVALID_CREDENTIALS'
message: string; // 已 i18n 翻译或后端原文
details?: unknown;
httpStatus: number;
}
```
**职责**：
- 自动注入 `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: ["teacher", "classes", { gradeId }];
queryKey: ["teacher", "exams", classId];
queryKey: ["session", "effective-permissions"];
queryKey: ["session", "viewports", "teacher"];
// Mutation 约定
const mutation = useMutation({
mutationFn: (input) => api.post("/api/v1/classes", input),
onSuccess: () =>
queryClient.invalidateQueries({ queryKey: ["teacher", "classes"] }),
onError: (e: ApiError) => toast.error(e.message),
});
```
## 5. 事件设计
前端不发布 Kafka 事件，仅消费 WebSocket 推送（P5）和 Server-Sent Events（AI 流式）。
### 5.1 WebSocket 推送（P5）
| 事件 | 触发 | teacher-portal 前端动作 |
| ----------------------- | ------------ | ------------------------------- |
| `NotificationRequested` | msg 服务投递 | toast 提示 + 通知中心未读数 +1 |
| `HomeworkSubmitted` | 学生提交作业 | toast + 作业批改列表 invalidate |
### 5.2 SSE 流式（P5 AI 辅助出题）
```
GET /api/v1/ai/generate-questions (SSE)
data: {"delta": "题目"}\n\n
data: {"delta": "A. option1"}\n\n
data: {"done": true}\n\n
```
前端用 `AsyncIterable<T>` 消费，Tiptap 逐字插入。
## 6. 横切关注点对齐清单
### 6.1 权限（前端等价）
| 路由 | requiredPermission |
| ----------------------------- | ------------------------ |
| `/teacher/dashboard` | `TEACHER_DASHBOARD_VIEW` |
| `/teacher/classes` | `CLASSES_READ` |
| `/teacher/classes/new` | `CLASSES_CREATE` |
| `/teacher/exams` | `EXAMS_READ` |
| `/teacher/exams/new` | `EXAMS_CREATE` |
| `/teacher/homework` | `HOMEWORK_READ` |
| `/teacher/homework/:id/grade` | `HOMEWORK_GRADE` |
| `/teacher/grades` | `GRADES_READ` |
| `/teacher/ai-assist` | `AI_GENERATE` |
| `/teacher/lesson-prep` | `LESSON_PREP_VIEW` |
| `/teacher/knowledge-graph` | `CONTENT_READ` |
> 完整权限点常量集中在 `packages/contracts/src/permissions.ts`（待建立，coord 负责 shared-ts，ai07 负责调用）。L3 组件级视口用 `<RequirePermission perm="EXAMS_CREATE"><Button>新建考试</Button></RequirePermission>`。
### 6.2 错误码清单（前端 i18n 路由）
| 前缀 | 来源服务 | i18n key 模式 |
| -------------- | ----------- | ------------------------ |
| `IAM_` | iam | `iam.error.{{code}}` |
| `CORE_EDU_` | core-edu | `coreEdu.error.{{code}}` |
| `CLASSES_` | core-edu | `classes.error.{{code}}` |
| `CONTENT_` | content | `content.error.{{code}}` |
| `MSG_` | msg | `msg.error.{{code}}` |
| `AI_` | ai | `ai.error.{{code}}` |
| `BFF_TEACHER_` | teacher-bff | `bff.error.{{code}}` |
| `GW_` | api-gateway | `gateway.error.{{code}}` |
| `NETWORK_` | 前端网络层 | `network.error.{{code}}` |
### 6.3 Logger
```typescript
// packages/shared-ts/src/logger.ts
interface Logger {
info(msg: string, meta?: Record<string, unknown>): void;
warn(msg: string, meta?: Record<string, unknown>): void;
error(msg: string, meta?: Record<string, unknown>): void;
}
// 实现：开发环境 console + 结构化；生产环境 → Sentry（P6）
// 必含字段：trace_id（从响应头提取）、user_id、scope、path
```
### 6.4 Metrics（Web Vitals）
| 指标 | 类型 | 上报 |
| ----------------------------- | ---- | --------------------------------------------------- |
| `teacher_portal_lcp_seconds` | LCP | `next/web-vitals` → `POST /api/v1/admin/web-vitals` |
| `teacher_portal_cls` | CLS | 同上 |
| `teacher_portal_fid_seconds` | FID | 同上 |
| `teacher_portal_ttfb_seconds` | TTFB | 同上 |
P6 接入，P2-P5 暂缓。
### 6.5 Tracer（OTel browser SDK，P6）
```typescript
// packages/shared-ts/src/tracer.ts
import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
// 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 无长连接（除 SSE/WS），无需特殊处理。SSE/WS 在 P5 由 push-gateway 管理，前端断线自动重连。
## 7. 共享组件库（packages/ui-components/，待建立，ai07 维护）
| 组件 | 用途 | 来源 |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------ |
| `AppShell` | 左侧栏 + 主内容区布局 | teacher-portal 现有 → 抽取共享 |
| `RequirePermission` | L3 组件级视口控制（无权限不渲染 children） | 新建 |
| `ErrorBoundary` | React 渲染异常兜底（fallback UI） | 新建 |
| `Loading` | 骨架屏（Skeleton） | 新建 |
| `Empty` | 空态（插画 + 文案 + CTA） | 新建 |
| `Modal` / `Dialog` | 全局 Modal（ModalRoot + Zustand ui-store） | shadcn/ui |
| `Toast` | 全局 toast（错误/成功/警告） | shadcn/ui sonner |
| `Button` / `Input` / `Select` / `Textarea` | 基础表单 | shadcn/ui |
| `DataTable` | 表格（排序/分页/筛选） | shadcn/ui + TanStack Table |
| `Chart` | 图表封装（recharts） | 新建 |
| `A11y` 工具集 | useA11yId / mergeA11yProps / describeInput / focus-trap / skip-link / visually-hidden / aria-status | 迁移指南 §7.7 |
| `Form` | react-hook-form + zodResolver 封装 | 新建 |
| `RichTextEditor` | Tiptap 封装（备课/出题/反馈） | 新建 |
## 8. 共享 Hooks（packages/hooks/，待建立，ai07 维护）
| Hook | 职责 |
| --------------------- | --------------------------------------------------- |
| `useAuth()` | 会话状态（user/token/refresh/login/logout） |
| `usePermission()` | 权限查询（hasPermission/hasAny/hasAll + dataScope） |
| `useViewports(scope)` | 视口列表（按 scope 过滤） |
| `useApi()` | ApiClient 实例（注入 token + 401 处理） |
| `useA11yId()` | 唯一 ARIA ID 生成 |
| `useAriaLive()` | aria-live 区域管理 |
| `useToast()` | 全局 toast（Zustand ui-store） |
## 9. 设计令牌三层（packages/ui-tokens/，待建立，ai07 维护）
```
packages/ui-tokens/
├─ primitive.css # Layer 1 原始色板/字号/间距/阴影
├─ semantic-light.css # Layer 2 语义令牌（亮色）
├─ semantic-dark.css # Layer 2 语义令牌（暗色）
├─ tailwind-theme.css # Layer 3 @theme inline 暴露 bg-*/text-*/font-*
└─ package.json
```
**强制规则**（project_rules §3.10）：
- 禁止 `#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-*` 或默认阶梯）
**令牌命名**（迁移指南 §7.1）：
| Layer 1 Primitive | Layer 2 Semantic | Layer 3 Tailwind |
| ------------------ | ------------------ | ---------------- |
| `--color-blue-500` | `--color-accent` | `bg-accent` |
| `--font-size-3` | `--font-size-body` | `text-body` |
| `--space-4` | `--space-md` | `p-md` |
## 10. 与其他模块的交互点（契约清单）
| 方向 | 对方服务 | 协议 | 接口/事件 | 用途 | 阶段 |
| ------ | ------------ | ------------------ | --------------------------------------------------- | ---------------------------- | ---- |
| 调用 | api-gateway | HTTP/REST | `/api/v1/*` 代理 | 全部业务请求 | P1+ |
| 调用 | push-gateway | WebSocket | `ws://push-gateway/ws` | 实时推送 | P5 |
| 调用 | ai | SSE | `GET /api/v1/ai/generate-questions` | AI 流式出题 | P5 |
| 被调用 | — | — | — | 前端不暴露接口给其他服务 | — |
| 消费 | teacher-bff | HTTP（经 Gateway） | `GET /teacher/viewports` 等 | 教师场景聚合 | P2+ |
| 消费 | iam | HTTP（经 Gateway） | `/iam/*` | 登录/权限/视口/用户管理 | P2+ |
| 消费 | core-edu | HTTP（经 Gateway） | `/classes/*` `/exams/*` `/homework/*` `/grades/*` | 教学核心 | P2+ |
| 消费 | content | HTTP（经 Gateway） | `/textbooks/*` `/knowledge-points/*` `/questions/*` | 内容资源 | P4+ |
| 消费 | data-ana | HTTP（经 Gateway） | `/analytics/*` | 学情分析 | P4+ |
| 消费 | msg | HTTP（经 Gateway） | `/notifications/*` | 通知中心 | P5+ |
| 依赖 | coord 维护 | — | `packages/shared-proto` | TS 类型（仅 contracts 部分） | P1+ |
| 依赖 | coord 维护 | — | `packages/shared-ts`（待建） | ApiClient/Logger/通用工具 | P2+ |
| 依赖 | ai07 维护 | — | `packages/ui-tokens`（待建） | 三层设计令牌 | P2+ |
| 依赖 | ai07 维护 | — | `packages/ui-components`（待建） | shadcn + 共享组件 | P2+ |
| 依赖 | ai07 维护 | — | `packages/hooks`（待建） | usePermission/useAuth 等 | P2+ |
| 依赖 | coord 维护 | — | `packages/contracts`（待建） | Permissions 常量 + 类型 | P2+ |
> **proto 不直接消费**：前端不调用 gRPC，BFF 把 gRPC 聚合为 REST/GraphQL 暴露给前端。前端仅消费 `packages/contracts/src/permissions.ts` 中的权限点常量（TS 文件，非 proto 生成）。
## 11. 风险与假设
### 11.1 假设
1. **假设 coord 建立 `packages/shared-ts`、`packages/contracts`**：包含 ApiClient、Logger、Permissions 常量、通用类型。若 coord 未建立，ai07 自行在 `apps/teacher-portal/src/shared/` 内实现，后续提取到 packages。
2. **假设 iam 提供 `GET /iam/effective-permissions`**：返回 `{ permissions, viewports, dataScope }`。当前已实现（known-issues §2.3 iam）。
3. **假设 teacher-bff 提供 `GET /teacher/viewports`**：返回 L1 导航视口。当前已实现。
4. **假设 core-edu classes 模块维持 `ActionState` 响应结构**：前端 API 请求层依赖此契约。
5. **假设 Next.js 14+ Module Federation 2.0 稳定**：`@module-federation/nextjs-mf` 在 Next.js App Router 下可用。若不稳定，降级为 4 端独立部署 + 各自 Shell（重复实现 AppShell）。
### 11.2 技术风险
| 风险 | 影响 | 缓解 |
| ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| MF SSR 对齐复杂 | Remote 在 SSR 时需 Shell 提供上下文 | 优先 CSR，SSR 仅用于首屏 dashboard；MF 2.0 支持 SSR |
| 共享依赖版本漂移 | Remote 与 Shell 的 react/react-dom 版本不一致导致运行时错误 | MF `shared.singleton: true` + CI 检查版本对齐 |
| Token 刷新竞态 | 多请求同时 401 触发多次 refresh | ApiClient 全局单例 + refresh promise 复用 |
| 权限缓存陈旧 | 角色变更后前端 5min 内仍用旧权限 | iam 角色变更发 Kafka 事件 → msg 推送 WebSocket → 前端 invalidate |
| 设计令牌迁移破坏现有样式 | teacher-portal 现有硬编码令牌迁移到三层模型后样式漂移 | 灰度迁移：先建 ui-tokens 包，teacher-portal 引入但不删除旧 globals.css，验证后切换 |
| TanStack Query 缓存膨胀 | 长时间使用后缓存项过多 | `gcTime` 5min + `staleTime` 按数据类型分级 |
### 11.3 未决设计决策（需 coord 仲裁）
1. **packages 归属**：`ui-tokens` / `ui-components` / `hooks` 是 ai07 维护还是 coord 维护？建议：ai07 维护（前端专属），coord 仅维护 `shared-ts` / `contracts`（跨语言/跨服务）。
2. **GraphQL vs REST**：004 §11.3 提到 BFF GraphQL Yoga + DataLoader，但当前 teacher-bff 实现为 REST。前端 API 请求层是否需要 GraphQL client（urql/apollo）？建议：P2-P3 用 REST，P4 起若 BFF 切 GraphQL 再引入 urql。
3. **i18n key 命名**：`iam.error.IAM_INVALID_CREDENTIALS` 还是 `error.iam.invalid_credentials`？建议：`error.{{service}}.{{code_snake_case}}`，与错误码前缀对齐。
4. **MF 暴露粒度**：Shell 暴露整个 AppShell 还是暴露更细粒度的组件（Sidebar、Header、Content）？建议：暴露 AppShell 整体 + 各 Remote 自行决定内部布局。
## 12. coord 交叉审查所需信息
### 12.1 端口矩阵
| 端 | dev 端口 | 生产端口 | 备注 |
| -------------- | -------- | -------- | ---------- |
| teacher-portal | 3000 | 3000 | Shell 宿主 |
> 与 [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 /teacher/viewports`、`GET /teacher/dashboard` | teacher-bff | ✅ 已实现 |
| `/classes/*` CRUD | core-edu | ✅ 已实现 |
| `/exams/*` `/homework/*` `/grades/*` | core-edu | ✅ 已实现（P3） |
| `/textbooks/*` `/knowledge-points/*` `/questions/*` | content | ✅ 已实现（P4） |
| `/analytics/*` | data-ana | ✅ 已实现（P4 CDC） |
| `/notifications/*` + WebSocket 推送 | msg + push-gateway | 📐 待 P5 |
| `GET /ai/generate-questions`（SSE） | ai | 📐 待 P5 |
### 12.4 错误码前缀（前端 i18n 路由依赖）
前端不产生错误码，仅消费。需各服务确认错误码前缀不重叠：
| 前缀 | 服务 | 状态 |
| ------------------------------ | ----------- | --------- |
| `IAM_` | iam | ✅ 已用 |
| `CLASSES_` | core-edu | ✅ 已用 |
| `EXAMS_`/`HOMEWORK_`/`GRADES_` | core-edu | ⚠️ 待确认 |
| `CONTENT_` | content | ⚠️ 待确认 |
| `MSG_` | msg | ⚠️ 待确认 |
| `AI_` | ai | ⚠️ 待确认 |
| `BFF_TEACHER_` | teacher-bff | ⚠️ 待确认 |
| `GW_` | api-gateway | ✅ 已用 |
| `NETWORK_` | 前端 | ai07 自有 |
### 12.5 不产生 Kafka 事件
前端不发布/消费 Kafka 事件。WebSocket 推送由 push-gateway 消费 Kafka 转发。
## 13. 实施路线（ai07 自用）
### P2 收尾（teacher-portal 审计对齐）
1. 建 `packages/ui-tokens/`（三层设计令牌）+ `packages/ui-components/`（ErrorBoundary/RequirePermission/Loading/Empty）+ `packages/hooks/`（usePermission/useAuth）
2. teacher-portal 引入 TanStack Query + Zustand + nuqs + react-hook-form
3. 抽取 `lib/api.ts` 统一 API 请求层
4. AppShell 改用 `usePermission()`，删除 `user.roles.join(", ")` 硬编码
5. globals.css / tailwind.config.js 迁移到 ui-tokens 三层令牌
6. 引入 next-intl + i18n key 路由
7. 引入 ESLint flat config 自定义规则（no-hardcoded-fonts / design-tokens）
8. 补 ErrorBoundary + /api/health route
9. 配置 next.config.js Module Federation（Shell 角色）
10. 补 Vitest 单测 + Playwright E2E（覆盖率 ≥ 80%）
### P5（推送 + AI 接入）
1. teacher-portal 接入 WebSocket（push-gateway）
2. teacher-portal AI 辅助出题（SSE + Tiptap）
### P6（硬化）
1. Web Vitals + OTel browser SDK 接入
2. A11y WCAG 2.2 AA 审计
3. 性能优化（MF shared 单例验证、bundle 分析）
---
**AI Agent**: ai07 (teacher-portal shell)
**Branch**: docs/teacher-portal-stage1-stage2-design-ai07
**Coordinator**: coord-ai