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

feat: auto committed

Browse Source
This commit is contained in:
SpecialX
2026-07-10 15:05:47 +08:00
parent 9ba368477d
commit 14d836beb0
5 changed files with 337 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
apps/teacher-portal/docs/01-understanding.md
View File

@@ -1,9 +1,9 @@
# 模块理解确认书 — teacher-portal # 模块理解确认书 — teacher-portal
> AI：ai07（TS/React · 教学场景域前端 shell） > AI：ai13（TS/React · 教学场景域前端 shell）
> 阶段：阶段 1 交付物 > 阶段：阶段 1 交付物
> 日期：2026-07-09 > 日期：2026-07-09（2026-07-10 审查回写：对齐 F9 GraphQL P2 起 + ARB-001/002 仲裁）
> 关联：[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) > 关联：[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) §1.1a/1.1b/§5.4、[AI 分配方案](../../../docs/architecture/ai-allocation.md) §5 ai13、[pending-features P2](../../../docs/architecture/roadmap/pending-features.md)、[known-issues §2.12](../../../docs/troubleshooting/known-issues.md)、[coord 仲裁 ARB-001/002](../../../docs/architecture/issues/coord.md)
--- ---
@@ -12,16 +12,17 @@
- **层级**：L2 微前端层（004 §3.1 六层架构中的前端层） - **层级**：L2 微前端层（004 §3.1 六层架构中的前端层）
- **MF 角色**：**Shell 宿主**（主应用），其余 3 端（student/parent/admin-portal）作为 Remote 子应用挂载 - **MF 角色**：**Shell 宿主**（主应用），其余 3 端（student/parent/admin-portal）作为 Remote 子应用挂载
- **上游（谁调用我）**：浏览器（教师 / 教导主任 / 教研组长） - **上游（谁调用我）**：浏览器（教师 / 教导主任 / 教研组长）
- **下游（同步）**：api-gateway（REST，经 Next.js `rewrites` 代理 `/api/v1/*`） - **下游（同步）**：api-gateway（经 Next.js `rewrites` 代理 `/api/v1/*`），再反向代理到 teacher-bff `POST /graphql`
- **下游（推送，P5）**：push-gateway（WebSocket/SSE） - **下游（推送，P5）**：push-gateway（WebSocket/SSE）
- **BFF 对接**：teacher-bff（GraphQL Yoga + DataLoader，P2-P3 用 REST 过渡） - **BFF 对接**：teacher-bff（GraphQL Yoga + DataLoader，P2 起 all-in GraphQL，F9 裁决，无 REST 过渡）
- **通信方式**：HTTP/REST（前端→Gateway）+ WebSocket（前端→push-gateway，P5） - **通信方式**：GraphQL over HTTP（前端→Gateway→teacher-bff）+ WebSocket（前端→push-gateway，P5）+ SSE（前端→ai 服务，P5）
- **不直连**：前端不直连任何业务服务或 BFF 后端实例，全部经 api-gateway 代理 - **不直连**：前端不直连任何业务服务或 BFF 后端实例，全部经 api-gateway 代理
**说明**： **说明**：
- 通过 `next.config.js` 的 `rewrites` 将 `/api/v1/*` 代理到 `api-gateway` - 通过 `next.config.js` 的 `rewrites` 将 `/api/v1/*` 代理到 `api-gateway`，api-gateway 再反向代理到 teacher-bff GraphQL endpoint
- MF 架构下，teacher-portal 作为 Shell 宿主提供 AppShell + 共享组件库 + 权限 Hook + API 请求层 - F9 裁决：P2 起 BFF 用 GraphQL（Yoga + DataLoader），前端用 urql client，**无 REST 过渡阶段**（详见 [03-long-term-architecture.md §1.4](./03-long-term-architecture.md)）
- MF 架构下，teacher-portal 作为 Shell 宿主提供 AppShell + GraphQLProvider 单例 + 共享组件库 + 权限 Hook（ARB-002 暴露清单）
- 场景域 BFF 复用策略（004 §5.4）：教导主任/教研组长复用 teacher-portal + 额外管理视口，不单独建 portal - 场景域 BFF 复用策略（004 §5.4）：教导主任/教研组长复用 teacher-portal + 额外管理视口，不单独建 portal
## 2. 我的限界上下文 ## 2. 我的限界上下文
@@ -49,19 +50,21 @@
### 3.1 消费的后端 API（经 api-gateway 代理） ### 3.1 消费的后端 API（经 api-gateway 代理）
| 路径前缀 | 下游 BFF/服务 | 关键端点 | F9 裁决：P2 起 all-in GraphQL，前端不再消费 REST 端点（登录除外）。teacher-bff GraphQL endpoint `POST /graphql`（经 api-gateway `/api/v1/teacher/*` 代理），schema 详见 [coord ARB-001](../../../docs/architecture/issues/coord.md#§1) + [teacher-portal_contract.md §2.4](../../../docs/architecture/issues/contracts/teacher-portal_contract.md)。
| ------------------------------------------------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/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 统一响应契约 | 阶段 | 消费方式 | 下游 BFF/服务 | 关键 GraphQL Operation（P2 Must Have 加粗） |
| ---- | ---------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| P2 | GraphQL Query（teacher-bff，ARB-001 第一版） | teacher-bff → iam/classes | **`dashboard`**、**`viewports`**、**`me`**、**`classes`**、**`class(id)`**（5 个 Query，ARB-001 §1.2） |
| P2 | HTTP（登录，MF 依赖认证前提，非 GraphQL） | api-gateway → iam | `POST /api/auth/login`（F12：JWT 存 localStorage，P6 迁移 httpOnly cookie） |
| P3 | GraphQL Query + Mutation | teacher-bff → core-edu | `classExams` / `createExam` / `classHomework` / `assignHomework` / `studentGrades` / `recordGrade` |
| P4 | GraphQL Query | teacher-bff → content/data-ana | `knowledgeGraph` / `studentAnalytics` |
| P5 | GraphQL Query + Mutation + SSE/WS | teacher-bff → msg/ai + push-gateway | `myNotifications` / `markAsRead` / `generateQuestion`（SSE 流式）/ `generateLessonPlan` |
所有后端响应遵循 `ActionState` 结构（迁移指南 §7.5）： > P2 不包含：exams/homework/grades Query（P3 core-edu 就绪后）、classPerformance/studentWeakness/learningTrend（P4 data-ana）、notifications（P5 msg）、所有 Mutation（P3+）、Subscription（P6+ 评估）——见 ARB-001 §1.2。
### 3.2 统一响应契约（ActionState 信封 + GraphQL errors）
BFF GraphQL 始终返回 `ActionState` 信封（004 §11.5），GraphQL `errors[]` 数组扩展 ActionState 字段（`extensions.code` = `BFF_TEACHER_*`，G14 裁决）：
```typescript ```typescript
type ActionState<T> = type ActionState<T> =
@@ -72,18 +75,18 @@ type ActionState<T> =
}; };
``` ```
错误码前缀按服务名大写（如 `IAM_`、`CORE_EDU_`、`CONTENT_`、`MSG_`、`AI_`、`BFF_TEACHER_`、`GW_`）。前端 API 请求层根据 `error.code` 前缀路由到对应的 i18n key。 错误码前缀按服务名大写（如 `IAM_`、`CORE_EDU_`、`CONTENT_`、`MSG_`、`AI_`、`BFF_TEACHER_`、`GW_`，见 [matrix.md §6](../../../docs/architecture/issues/matrix.md)）。前端 urql client 解析 `errors[].extensions.code` 前缀路由到对应 i18n key（详见 [03 §1.4.3](./03-long-term-architecture.md)）。
### 3.3 推送契约（P5） ### 3.3 推送契约（P5）
| 协议 | 场景 | | 协议 | 场景 |
| ------------------------- | -------------------------------------------- | | ------------------------- | -------------------------------------------- |
| WebSocket（push-gateway） | 学生提交作业通知、考试成绩录入提醒、全校广播 | | WebSocket（push-gateway） | 学生提交作业通知、考试成绩录入提醒、全校广播 |
| SSE（ai 服务） | AI 辅助出题流式响应 | | SSE（ai 服务，经 teacher-bff 代理或直连） | AI 辅助出题流式响应 |
### 3.4 proto 不直接消费 ### 3.4 proto 不直接消费
前端不调用 gRPC，BFF 把 gRPC 聚合为 REST/GraphQL 暴露给前端。前端仅消费 `packages/contracts/src/permissions.ts` 中的权限点常量（TS 文件，非 proto 生成）。 前端不调用 gRPC，BFF 把 gRPC 聚合为 GraphQL 暴露给前端（F9 裁决）。前端仅消费 `packages/contracts/src/permissions.ts` 中的权限点常量（TS 文件，非 proto 生成）。
## 4. 我的技术栈 ## 4. 我的技术栈
@@ -91,11 +94,12 @@ type ActionState<T> =
| --------------------------- | -------------------------------------------------------- | ---------------------------------------------- | | --------------------------- | -------------------------------------------------------- | ---------------------------------------------- |
| 框架 | Next.js 14+（App Router） | server components 默认，client components 按需 | | 框架 | Next.js 14+（App Router） | server components 默认，client components 按需 |
| 语言 | TypeScript 5.5+（strict） | 沿用 tsconfig.base.json | | 语言 | TypeScript 5.5+（strict） | 沿用 tsconfig.base.json |
| 微前端 | Module Federation 2.0（@module-federation/nextjs-mf） | teacher-portal = Shell | | 微前端 | Module Federation 2.0（@module-federation/nextjs-mf） | teacher-portal = Shell（ARB-002 暴露清单） |
| **GraphQL client** | **urql**（F9 裁决 P2 起，shell 单例，ARB-002 shared singleton） | cacheExchange + fetchExchange，详见 [03 §1.4](./03-long-term-architecture.md) |
| 样式 | Tailwind CSS 3.4+ | 配合设计令牌三层模型 | | 样式 | Tailwind CSS 3.4+ | 配合设计令牌三层模型 |
| UI 组件库 | shadcn/ui（迁移指南 §7.2） | 平移至 `packages/ui-components/`，MF 共享 | | UI 组件库 | shadcn/ui（迁移指南 §7.2） | 平移至 `packages/ui-components/`，MF 共享 |
| 状态管理 L1 URL | nuqs | 可分享、可刷新状态 | | 状态管理 L1 URL | nuqs | 可分享、可刷新状态 |
| 状态管理 L2 Server | TanStack Query v5 | 服务端数据缓存、重试、乐观更新 | | 状态管理 L2 Server | urql cacheExchange（GraphQL 数据）+ TanStack Query（非 GraphQL 场景：文件上传/SSE） | F9 起不再双缓存层，详见 [03 §1.4.4](./03-long-term-architecture.md) |
| 状态管理 L3 Client Business | Zustand slice | 客户端业务状态 | | 状态管理 L3 Client Business | Zustand slice | 客户端业务状态 |
| 状态管理 L4 Global UI | Zustand ui-store + ModalRoot | 全局 UI 状态 | | 状态管理 L4 Global UI | Zustand ui-store + ModalRoot | 全局 UI 状态 |
| 状态管理 L5 Form | react-hook-form + zodResolver | 表单状态 | | 状态管理 L5 Form | react-hook-form + zodResolver | 表单状态 |
@@ -103,7 +107,7 @@ type ActionState<T> =
| 图表 | recharts | 学情、Dashboard | | 图表 | recharts | 学情、Dashboard |
| i18n | next-intl | BFF/服务返回 i18n key + 参数，前端翻译 | | i18n | next-intl | BFF/服务返回 i18n key + 参数，前端翻译 |
| A11y | eslint-plugin-jsx-a11y（error 级） | WCAG 2.2 AA | | A11y | eslint-plugin-jsx-a11y（error 级） | WCAG 2.2 AA |
| 字体 | Inter（sans）/ Fraunces（serif）/ JetBrains Mono（mono） | next/font/google 加载，CSS 变量暴露 | | 字体 | sans/serif/mono（通过 `var(--font-family-*)` 引用，禁止字面量） | next/font/google 加载，CSS 变量暴露（§3.10 强制） |
## 5. 我的阶段归属 ## 5. 我的阶段归属
@@ -201,5 +205,5 @@ apps/teacher-portal/
--- ---
**AI Agent**: ai07 (teacher-portal shell) **AI Agent**: ai13 (teacher-portal shell)
**Branch**: docs/teacher-portal-stage1-stage2-design-ai07 **Branch**: feat-review-teacher-portal-docs-vErc0L

485
apps/teacher-portal/docs/02-architecture-design.md
View File

@@ -1,14 +1,14 @@
# 模块架构设计文档 — teacher-portal # 模块架构设计文档 — teacher-portal
> AI：ai07（TS/React · 教学场景域前端 shell） > AI：ai13（TS/React · 教学场景域前端 shell）
> 阶段：阶段 2 交付物 > 阶段：阶段 2 交付物
> 日期：2026-07-09 > 日期：2026-07-09（2026-07-10 审查回写：对齐 F9 GraphQL P2 起 + ARB-001/002 仲裁，REST→GraphQL 全量重写）
> 关联：[阶段 1 理解确认书](./01-understanding.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) §5.4、[pending-features P2](../../../docs/architecture/roadmap/pending-features.md) > 关联：[阶段 1 理解确认书](./01-understanding.md)、[长远架构补全](./03-long-term-architecture.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) §5.4、[coord 仲裁 ARB-001/002](../../../docs/architecture/issues/coord.md)、[pending-features P2](../../../docs/architecture/roadmap/pending-features.md)
> 状态：待 coord 交叉审查 > 状态：✅ 已对齐 F9（GraphQL P2 起）+ ARB-001（schema 第一版）+ ARB-002（MF Shell 暴露清单）
--- ---
## 1. 模块内部分层图（4 端统一 MF 架构） ## 1. 模块内部分层图（4 端统一 MF + GraphQL 架构）
```mermaid ```mermaid
graph TB graph TB
@@ -16,26 +16,27 @@ graph TB
URL[URL 路由] URL[URL 路由]
end end
subgraph Shell["teacher-portal（Shell 宿主）"] subgraph Shell["teacher-portal（Shell 宿主 :4000）"]
AppShell[AppShell<br/>左栏导航 + 主内容区]
RootLayout[RootLayout<br/>字体/令牌/i18n Provider] RootLayout[RootLayout<br/>字体/令牌/i18n Provider]
GraphQLProvider[GraphQLProvider<br/>urql client 单例（ARB-002 §2.17 方案 A）]
AppShell[AppShell<br/>左栏导航 + 主内容区 + 路由守卫]
Router[Next.js App Router] Router[Next.js App Router]
SharedDeps["共享依赖暴露<br/>react/react-dom/@tanstack/react-query/zustand/nuqs"] SharedDeps["共享依赖暴露<br/>react/react-dom/urql/graphql/@edu/*（ARB-002 shared singleton）"]
end end
subgraph RemoteTeacher["teacher-portal Remote 模块"] subgraph RemoteTeacher["teacher-portal Remote 模块"]
TeacherPages[教学场景页面<br/>dashboard/classes/exams/homework/grades/ai-assist] TeacherPages[教学场景页面<br/>dashboard/classes/exams/homework/grades/ai-assist]
end end
subgraph RemoteStudent["student-portal（Remote）"] subgraph RemoteStudent["student-portal（Remote，P3+）"]
StudentPages[学习场景页面<br/>dashboard/homework/submit/diagnostic/exam-taking] StudentPages[学习场景页面<br/>dashboard/homework/submit/diagnostic/exam-taking]
end end
subgraph RemoteParent["parent-portal（Remote）"] subgraph RemoteParent["parent-portal（Remote，P4+）"]
ParentPages[家长场景页面<br/>dashboard/children-switch/grades/notifications] ParentPages[家长场景页面<br/>dashboard/children-switch/grades/notifications]
end end
subgraph RemoteAdmin["admin-portal（Remote）"] subgraph RemoteAdmin["admin-portal（Remote，P6+）"]
AdminPages[管理场景页面<br/>users/roles/permissions/viewports/monitoring] AdminPages[管理场景页面<br/>users/roles/permissions/viewports/monitoring]
end end
@@ -43,22 +44,27 @@ graph TB
UITokens[ui-tokens<br/>三层设计令牌] UITokens[ui-tokens<br/>三层设计令牌]
UIComponents[ui-components<br/>shadcn + A11y + ErrorBoundary] UIComponents[ui-components<br/>shadcn + A11y + ErrorBoundary]
Contracts[contracts<br/>Permissions 常量 + 类型] Contracts[contracts<br/>Permissions 常量 + 类型]
Hooks[hooks<br/>usePermission/useAuth/useA11y] Hooks[hooks<br/>usePermission/useAuth/useGraphQLClient]
LibTS[shared-ts<br/>通用工具] LibTS[shared-ts<br/>GraphQL schema + 通用工具]
end end
subgraph Gateway["api-gateway"] subgraph Gateway["api-gateway :8080"]
GW[Gin 路由/鉴权/限流] GW[Gin 路由/鉴权/限流]
end end
subgraph TeacherBFF["teacher-bff :3003"]
BFF[GraphQL Yoga + DataLoader<br/>POST /graphql（ARB-001 schema）]
end
Browser --> URL Browser --> URL
URL --> RootLayout URL --> RootLayout
RootLayout --> AppShell RootLayout --> GraphQLProvider
GraphQLProvider --> AppShell
AppShell --> Router AppShell --> Router
Router -->|动态加载| RemoteTeacher Router -->|动态加载| RemoteTeacher
Router -->|动态加载| RemoteStudent Router -->|动态加载 P3+| RemoteStudent
Router -->|动态加载| RemoteParent Router -->|动态加载 P4+| RemoteParent
Router -->|动态加载| RemoteAdmin Router -->|动态加载 P6+| RemoteAdmin
RemoteTeacher --> SharedDeps RemoteTeacher --> SharedDeps
RemoteStudent --> SharedDeps RemoteStudent --> SharedDeps
@@ -74,41 +80,43 @@ graph TB
RemoteParent --> UITokens RemoteParent --> UITokens
RemoteAdmin --> UITokens RemoteAdmin --> UITokens
AppShell -->|fetch /api/v1/iam/effective-permissions| Hooks GraphQLProvider -->|POST /graphql over HTTP| GW
Hooks -->|透传 token| GW GW -->|反向代理 /api/v1/teacher/*| BFF
RemoteTeacher -->|fetch /api/v1/teacher/*| GW BFF -->|gRPC 聚合 iam+classes+core-edu+content+data-ana+msg+ai| Services
RemoteStudent -->|fetch /api/v1/student/*| GW
RemoteParent -->|fetch /api/v1/parent/*| GW
RemoteAdmin -->|fetch /api/v1/iam/* + /api/v1/admin/*| GW
``` ```
### 1.1 MF 拓扑选型 ### 1.1 MF 拓扑选型
| 方案 | 选否 | 理由 | | 方案 | 选否 | 理由 |
| ------------------------------------ | ---- | --------------------------------------------------------------------------------------- | | ------------------------------------ | ---- | --------------------------------------------------------------------------------------- |
| 4 端独立部署 + 独立域名 + 各自 Shell | ❌ | 4 套 Shell 重复，登录态/权限/组件库要重复实现 | | 4 端独立部署 + 独立域名 + 各自 Shell | ❌ | 4 套 Shell 重复，登录态/权限/组件库/GraphQL client 要重复实现 |
| 单 Shell + 4 Remote（**采用**） | ✅ | teacher-portal 作为 Shell 宿主，提供 AppShell + 共享依赖；其余 3 端作为 Remote 动态加载 | | 单 Shell + 4 Remote（**采用**） | ✅ | teacher-portal 作为 Shell 宿主，提供 AppShell + GraphQLProvider 单例 + 共享依赖；其余 3 端作为 Remote 动态加载 |
| 单一 Next.js 应用 + 4 路由组 | ❌ | 违反"微前端独立部署"目标（ADR-012） | | 单一 Next.js 应用 + 4 路由组 | ❌ | 违反"微前端独立部署"目标（ADR-012） |
**Shell 职责**（teacher-portal）： **Shell 职责**（teacher-portal，ARB-002 §2.2）：
- RootLayout（字体、设计令牌、i18n Provider、TanStack QueryClientProvider、Zustand StoreProvider） - RootLayout（字体、设计令牌、i18n Provider、GraphQLProvider、Zustand StoreProvider）
- AppShell（左侧导航 + 主内容区 + 用户信息 + 登出） - AppShell（左侧导航 + 主内容区 + 用户信息 + 登出 + 路由守卫）
- 共享依赖暴露（react、react-dom、@tanstack/react-query、zustand、nuqs、ui-components、ui-tokens、contracts、hooks） - GraphQLProvider（urql client 单例，总裁 §2.17 方案 A，Remote 复用）
- 共享依赖暴露（react、react-dom、urql、graphql、@edu/ui-tokens、@edu/ui-components、@edu/hooks）
- 路由表（4 端路由前缀：`/teacher/*`、`/student/*`、`/parent/*`、`/admin/*`） - 路由表（4 端路由前缀：`/teacher/*`、`/student/*`、`/parent/*`、`/admin/*`）
- 登录页（统一登录入口，按角色重定向到对应 portal） - 登录页（统一登录入口 `POST /api/auth/login`，非 MF，登录是认证前提）
### 1.2 MF 配置（teacher-portal/next.config.js） ### 1.2 MF 配置（teacher-portal/next.config.js，ARB-002 §2.2 裁决）
```javascript ```javascript
// teacher-portal/next.config.js（Shell） // teacher-portal/next.config.js（Shell，ARB-002 第一版暴露清单）
const NextFederationPlugin = require("@module-federation/nextjs-mf"); const NextFederationPlugin = require("@module-federation/nextjs-mf");
const remotes = (isServer) => ({ // P2：remotes 为空（NEXT_PUBLIC_MF_ENABLED=false，ARB-002 §2.3），P3+ 逐步接入
student: `student_app@http://localhost:3001/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`, const remotes = (isServer) => {
parent: `parent_app@http://localhost:3002/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`, if (process.env.NEXT_PUBLIC_MF_ENABLED !== "true") return {};
admin: `admin_app@http://localhost:3003/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`, return {
}); student: `student_app@http://localhost:4001/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`,
parent: `parent_app@http://localhost:4002/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`,
admin: `admin_app@http://localhost:4003/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`,
};
};
module.exports = { module.exports = {
reactStrictMode: true, reactStrictMode: true,
@@ -117,17 +125,28 @@ module.exports = {
new NextFederationPlugin({ new NextFederationPlugin({
name: "teacher_app", name: "teacher_app",
filename: "static/chunks/remoteEntry.js", filename: "static/chunks/remoteEntry.js",
remotes: remotes(isServer), remotes: remotes(isServer), // P2 为 {}，ARB-002 §2.3
exposes: { exposes: {
"./AppShell": "./src/components/AppShell", // ARB-002 §2.2 暴露清单
"./shared-deps": "./src/shared/deps", "./AppShell": "./src/components/AppShell.tsx",
"./GraphQLProvider": "./src/app/providers.tsx",
"./useAuth": "./packages/hooks/src/use-auth.ts",
"./usePermission": "./packages/hooks/src/use-permission.ts",
"./useGraphQLClient": "./packages/hooks/src/use-graphql-client.ts",
"./ErrorBoundary": "./packages/ui-components/src/error-boundary.tsx",
"./Loading": "./packages/ui-components/src/loading.tsx",
"./Empty": "./packages/ui-components/src/empty.tsx",
"./RequirePermission": "./packages/ui-components/src/require-permission.tsx",
}, },
shared: { shared: {
// ARB-002 §2.2 singleton 配置
react: { singleton: true, requiredVersion: "^18.3.0" }, react: { singleton: true, requiredVersion: "^18.3.0" },
"react-dom": { singleton: true, requiredVersion: "^18.3.0" }, "react-dom": { singleton: true, requiredVersion: "^18.3.0" },
"@tanstack/react-query": { singleton: true }, urql: { singleton: true, requiredVersion: "^2.2.0" },
zustand: { singleton: true }, graphql: { singleton: true, requiredVersion: "^16.8.0" },
nuqs: { singleton: true }, "@edu/ui-tokens": { singleton: true },
"@edu/ui-components": { singleton: true },
"@edu/hooks": { singleton: true },
}, },
extraOptions: { exposePages: false }, extraOptions: { exposePages: false },
}), }),
@@ -145,154 +164,181 @@ module.exports = {
}; };
``` ```
> Remote 端配置对称：`name: 'student_app'`，`exposes: { './pages': './src/pages' }`，`remotes: { teacher: 'teacher_app@...' }`。 > **P2 Remote 数量 = 0**（ARB-002 §2.3，`NEXT_PUBLIC_MF_ENABLED=false` 默认关）。P3 student-portal 作为首个 Remote 接入（总裁 §1.3 step 4）。feature flag 控制回退单体路由。
## 2. 领域模型（前端视角） ## 2. 领域模型（前端视角）
前端不持有业务聚合根，仅持有"视图模型"（ViewModel）和"会话状态"。 前端不持有业务聚合根，仅持有"视图模型"（ViewModel）和"会话状态"。数据来源统一为 teacher-bff GraphQL（F9 裁决）。
### 2.1 会话状态（Session） ### 2.1 会话状态（Session）
```typescript ```typescript
interface Session { interface Session {
user: UserInfo; // { id, email, name, roles, permissions, dataScope } user: UserInfo; // { id, email, name, roles, dataScope }（GraphQL me Query）
tokens: { accessToken: string; refreshToken: string }; tokens: { accessToken: string; refreshToken: string }; // F12: localStorage（P6 迁移 cookie）
viewports: ViewportItem[]; // L1 导航视口 viewports: ViewportItem[]; // L1 导航视口（GraphQL viewports Query）
permissions: string[]; // 权限点（GraphQL me Query 内嵌或 effective-permissions）
expiresAt: number; // access token 过期时间戳 expiresAt: number; // access token 过期时间戳
} }
``` ```
存储：Zustand sessionSlice（L3）+ localStorage 持久化（刷新恢复）+ TanStack Query 缓存 `['session']`（L2）。 存储：Zustand sessionSlice（L3）+ localStorage 持久化（刷新恢复，F12）+ urql cache（L2，GraphQL document cache）。
### 2.2 视口模型（Viewport） ### 2.2 视口模型（Viewport）
```typescript ```typescript
// 对齐 ARB-001 §1.2 schema：ViewportItem
interface ViewportItem { interface ViewportItem {
key: string; // 'dashboard' | 'classes' | ... key: string; // 'dashboard' | 'classes' | ...
label: string; // i18n key 或显式文案 label: string; // i18n key 或显式文案
route: string; // '/teacher/dashboard' route: String; // '/teacher/dashboard'（schema 为 String）
icon: string | null; // 图标 key（按需） icon: String | null; // 图标 key（schema 可空）
sortOrder: number; // 排序 sortOrder: String; // 排序（schema 为 String）
requiredPermission: string | null; // 'CLASSES_READ' 等 requiredPermission: String | null; // 'CLASSES_READ' 等
scope: "teacher" | "student" | "parent" | "admin"; // 标记归属哪个 portal
} }
``` ```
来源：`GET /api/v1/{scope}/viewports`（BFF 聚合 iam 视口配置）。AppShell 按 `scope` 过滤渲染对应 portal 的导航。 来源：GraphQL `viewports` Query（ARB-001 §1.2）。AppShell 按 `requiredPermission` + `usePermission().hasPermission()` 过滤渲染导航。
### 2.3 权限模型（Permission） ### 2.3 权限模型（Permission）
```typescript ```typescript
interface PermissionState { interface PermissionState {
permissions: string[]; // ['CLASSES_READ', 'EXAMS_CREATE', ...] permissions: string[]; // ['CLASSES_READ', 'EXAMS_CREATE', ...]（GraphQL me Query 返回）
dataScope: DataScope; // L0-L5 dataScope: DataScope; // SELF | CLASS | GRADE | SCHOOL | DISTRICT | ALL（ARB-001 enum）
hasPermission: (perm: string) => boolean; hasPermission: (perm: string) => boolean;
hasAnyPermission: (perms: string[]) => boolean; hasAnyPermission: (perms: string[]) => boolean;
hasAllPermissions: (perms: string[]) => boolean; hasAllPermissions: (perms: string[]) => boolean;
} }
``` ```
来源：`GET /api/v1/iam/effective-permissions` → `{ permissions, viewports, dataScope }`。Redis 缓存 5min（iam 侧），前端 TanStack Query 缓存 5min，角色变更主动 invalidate。 来源：GraphQL `me` Query 返回 `{ user, roles, dataScope }`（ARB-001 §1.2）。角色变更由 iam 发 Kafka → msg → push-gateway WebSocket 推送 → 前端 invalidate urql cache（见 [03 §2.5](./03-long-term-architecture.md)）。
## 3. 数据模型（前端） ## 3. 数据模型（前端缓存层）
前端无数据库，仅有缓存层： 前端无数据库，仅有 urql 缓存层（03 §1.4.4 缓存策略）：
| 数据类型 | 存储 | TTL | 失效策略 | | 数据类型 | 存储 | staleTime | 失效策略 |
| ----------------------- | ---------------------- | --------------------------- | -------------------------------------- | | ----------------------- | ----------------------------- | ---------------------------------- | --------------------------------------------- |
| Session（token + user） | localStorage + Zustand | access 15min / refresh 7day | 401 自动 refresh，refresh 失败跳登录 | | Session（token + user） | localStorage + Zustand（F12） | access 15min / refresh 7day | 401 自动 refresh，refresh 失败跳登录 |
| 权限列表 | TanStack Query cache | 5min | 角色变更事件 invalidate | | 权限列表 + 视口 | urql cacheExchange | 0（always fetch） | 角色变更 WebSocket 推送后强制 invalidate |
| 视口列表 | TanStack Query cache | 5min | 同上 | | 班级/年级列表 | urql cacheExchange | 30s | mutation 后 invalidate |
| 班级/年级列表 | TanStack Query cache | 5min | staleTime 5min，mutation 后 invalidate | | 考试/作业/成绩 | urql cacheExchange | 10s | mutation 后 invalidate + 乐观更新（03 §10.1） |
| 教学资源详情 | TanStack Query cache | 30s | staleTime 30s | | 教学资源详情 | urql cacheExchange | 30s | staleTime 30s |
| 学情宽表 | TanStack Query cache | 30s | staleTime 30s（实时性由 BFF 决定） | | 学情宽表 | urql cacheExchange | 60s | ISR revalidate 60s + CSR 交互 |
| URL 状态（分页/筛选） | nuqs | — | 永久（可分享） | | URL 状态（分页/筛选） | nuqs | — | 永久（可分享） |
| 表单临时态 | react-hook-form | — | 卸载即销毁 | | 表单临时态 | react-hook-form | — | 卸载即销毁 |
## 4. API 设计（前端 → 后端） > urql 默认 document cache 适合简单场景；复杂关联（班级↔考试↔成绩）P3 起评估切 `@urql/exchange-graphcache` normalized cache（03 §1.4.4）。不引入 TanStack Query 做 GraphQL 缓存（避免双缓存层）；TanStack Query 仅用于非 GraphQL 场景（文件上传/SSE）。
前端不设计后端 API，仅声明消费的端点。详见 [01-understanding.md §3.1](./01-understanding.md)。 ## 4. API 设计（前端 → teacher-bff GraphQL）
### 4.1 统一 API 请求层（lib/api.ts） F9 裁决：P2 起 all-in GraphQL。前端不再设计 REST 请求层，统一通过 urql client 消费 teacher-bff GraphQL（ARB-001 schema 第一版）。
### 4.1 urql client 单例（packages/hooks + Shell GraphQLProvider）
```typescript ```typescript
// packages/shared-ts/src/api-client.ts（共享） // packages/hooks/src/use-graphql-client.ts（Shell 暴露，Remote 复用，ARB-002 §2.17 方案 A）
interface ApiClientOptions { import { createClient, Client } from "urql";
baseUrl?: string; // 默认 ''（走 Next.js rewrites） import { cacheExchange, fetchExchange } from "urql";
getToken?: () => string | null;
onUnauthorized?: () => void; // 401 → refresh → 重试 / 跳登录
onError?: (error: ApiError) => void; // 全局 toast
}
class ApiClient { const client: Client = createClient({
async get<T>(path: string, query?: Record<string, string>): Promise<T>; url: process.env.NEXT_PUBLIC_TEACHER_BFF_GRAPHQL_URL!, // teacher-bff POST /graphql（经 api-gateway 代理）
async post<T>(path: string, body: unknown): Promise<T>; fetchOptions: () => {
async put<T>(path: string, body: unknown): Promise<T>; const token = readAuthToken(); // useAuth 注入（F12: localStorage）
async delete<T>(path: string): Promise<T>; const traceId = readTraceId();
async sse<T>(path: string, body: unknown): AsyncIterable<T>; // AI 流式 return {
} headers: {
...(token ? { Authorization: `Bearer ${token}` } : {}),
"X-Trace-Id": traceId,
},
};
},
exchanges: [cacheExchange, fetchExchange],
});
// 错误结构 // Shell: src/app/providers.tsx 包裹 <Provider value={client}>，所有 Remote 复用同一 client
interface ApiError {
code: string; // 'IAM_INVALID_CREDENTIALS'
message: string; // 已 i18n 翻译或后端原文
details?: unknown;
httpStatus: number;
}
``` ```
**职责**： **职责**：
- 自动注入 `Authorization: Bearer ${token}` - Shell 初始化 urql client 单例，通过 React Context 注入给所有 Remote（ARB-002 方案 A）
- 401 自动 refresh token 一次，失败调 `onUnauthorized` - token 刷新/401 处理由 useAuth 统一拦截（不污染 urql exchange 链，见 [03 §2.7](./03-long-term-architecture.md)）
- 解析 `ActionState`，success=false 抛 `ApiError` - MF shared singleton（react/urql/graphql）避免 Remote 多实例 + 缓存不一致
- 按 `error.code` 前缀路由 i18n key - 请求/响应 trace_id 透传（`X-Trace-Id` header）
- 全局错误 toast（除 401）
- 请求/响应 trace_id 透传（从响应头 `X-Request-Id` 提取）
### 4.2 TanStack Query 约定 ### 4.2 GraphQL Query/Mutation 约定（对齐 ARB-001 schema）
```typescript ```typescript
// Query Key 命名：[scope, resource, ...args] // P2 Query（ARB-001 §1.2，5 个 Must Have）
queryKey: ["teacher", "classes", { gradeId }]; import { gql } from "urql";
queryKey: ["teacher", "exams", classId];
queryKey: ["session", "effective-permissions"];
queryKey: ["session", "viewports", "teacher"];
// Mutation 约定 const DashboardQuery = gql`
const mutation = useMutation({ query Dashboard {
mutationFn: (input) => api.post("/api/v1/classes", input), dashboard {
onSuccess: () => user { id email name roles dataScope }
queryClient.invalidateQueries({ queryKey: ["teacher", "classes"] }), classes { id name gradeId studentCount }
onError: (e: ApiError) => toast.error(e.message), viewports { key label route icon sortOrder requiredPermission }
}); stats { totalExams pendingGrading todayHomework }
}
}
`;
const ViewportsQuery = gql`query { viewports { key label route icon sortOrder requiredPermission } }`;
const MeQuery = gql`query { me { id email name roles dataScope } }`;
const ClassesQuery = gql`query { classes { id name gradeId studentCount } }`;
// P3+ Mutation（ARB-001 §1.2 P2 不包含）
const CreateExamMutation = gql`
mutation CreateExam($input: CreateExamInput!) {
createExam(input: $input) { ... on ExamCreated { id } }
}
`;
``` ```
**urql mutation + 乐观更新**：
```typescript
const [, createExam] = useMutation(CreateExamMutation);
// 乐观更新：onMutate 回滚 + invalidateQueries（见 03 §10.1）
```
### 4.3 错误处理（ActionState 信封 + GraphQL errors，ARB-001 §1.3）
| 场景 | 处理 |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| GraphQL 错误（errors[]） | 解析 `extensions.code`（BFF_TEACHER_* 前缀，G14），映射到 i18n key `error.teacher_bff.<code_snake>`（F11） |
| 网络错误 | 重试 1 次 → 提示网络异常 → 记录 trace_id |
| 401 | useAuth 静默 refresh 一次 → 重试；失败跳登录（见 03 §2.7） |
| 部分失败（data + errors 共存） | 渲染 data 可用部分 + errors 区域提示，不整体失败（ARB-001 §1.3 降级模式方案 B） |
- BFF 始终返回 `ActionState` 信封（004 §11.5），前端统一走 `normalizeActionState()` 工具（packages/hooks）
## 5. 事件设计 ## 5. 事件设计
前端不发布 Kafka 事件，仅消费 WebSocket 推送（P5）和 Server-Sent Events（AI 流式）。 前端不发布 Kafka 事件，仅消费 WebSocket 推送（P5）和 Server-Sent Events（AI 流式）。
### 5.1 WebSocket 推送（P5） ### 5.1 WebSocket 推送（P5）
| 事件 | 触发 | teacher-portal 前端动作 | | 事件 | 触发 | teacher-portal 前端动作 |
| ----------------------- | ------------ | ------------------------------- | | ----------------------- | ------------ | ----------------------------------------------- |
| `NotificationRequested` | msg 服务投递 | toast 提示 + 通知中心未读数 +1 | | `NotificationRequested` | msg 服务投递 | toast 提示 + 通知中心未读数 +1 |
| `HomeworkSubmitted` | 学生提交作业 | toast + 作业批改列表 invalidate | | `HomeworkSubmitted` | 学生提交作业 | toast + urql cache invalidate 作业批改列表 |
| 角色变更（iam） | iam Kafka | urql cache invalidate 权限/视口（强制刷新 me Query） |
### 5.2 SSE 流式（P5 AI 辅助出题） ### 5.2 SSE 流式（P5 AI 辅助出题）
``` ```
GET /api/v1/ai/generate-questions (SSE) GET /api/v1/ai/generate-questions (SSE) 或 GraphQL Subscription（P6+ 评估）
data: {"delta": "题目"}\n\n data: {"delta": "题目"}\n\n
data: {"delta": "A. option1"}\n\n
data: {"done": true}\n\n data: {"done": true}\n\n
``` ```
前端用 `AsyncIterable<T>` 消费，Tiptap 逐字插入。 前端用 `AsyncIterable<T>` 消费（非 GraphQL，TanStack Query 场景），Tiptap 逐字插入。
## 6. 横切关注点对齐清单 ## 6. 横切关注点对齐清单
### 6.1 权限（前端等价） ### 6.1 权限（前端等价，F7 命名 `<RESOURCE>_<ACTION>`）
| 路由 | requiredPermission | | 路由 | requiredPermission |
| ----------------------------- | ------------------------ | | ----------------------------- | ------------------------ |
@@ -308,9 +354,9 @@ data: {"done": true}\n\n
| `/teacher/lesson-prep` | `LESSON_PREP_VIEW` | | `/teacher/lesson-prep` | `LESSON_PREP_VIEW` |
| `/teacher/knowledge-graph` | `CONTENT_READ` | | `/teacher/knowledge-graph` | `CONTENT_READ` |
> 完整权限点常量集中在 `packages/contracts/src/permissions.ts`（待建立，coord 负责 shared-ts，ai07 负责调用）。L3 组件级视口用 `<RequirePermission perm="EXAMS_CREATE"><Button>新建考试</Button></RequirePermission>`。 > 完整权限点常量集中在 `packages/contracts/src/permissions.ts`（coord 维护，ai13 消费）。L3 组件级视口用 `<RequirePermission perm="EXAMS_CREATE"><Button>新建考试</Button></RequirePermission>`。
### 6.2 错误码清单（前端 i18n 路由） ### 6.2 错误码清单（前端 i18n 路由，对齐 [matrix.md §6](../../../docs/architecture/issues/matrix.md)）
| 前缀 | 来源服务 | i18n key 模式 | | 前缀 | 来源服务 | i18n key 模式 |
| -------------- | ----------- | ------------------------ | | -------------- | ----------- | ------------------------ |
@@ -320,7 +366,7 @@ data: {"done": true}\n\n
| `CONTENT_` | content | `content.error.{{code}}` | | `CONTENT_` | content | `content.error.{{code}}` |
| `MSG_` | msg | `msg.error.{{code}}` | | `MSG_` | msg | `msg.error.{{code}}` |
| `AI_` | ai | `ai.error.{{code}}` | | `AI_` | ai | `ai.error.{{code}}` |
| `BFF_TEACHER_` | teacher-bff | `bff.error.{{code}}` | | `BFF_TEACHER_` | teacher-bff | `error.teacher_bff.{{code_snake}}` |
| `GW_` | api-gateway | `gateway.error.{{code}}` | | `GW_` | api-gateway | `gateway.error.{{code}}` |
| `NETWORK_` | 前端网络层 | `network.error.{{code}}` | | `NETWORK_` | 前端网络层 | `network.error.{{code}}` |
@@ -333,7 +379,6 @@ interface Logger {
warn(msg: string, meta?: Record<string, unknown>): void; warn(msg: string, meta?: Record<string, unknown>): void;
error(msg: string, meta?: Record<string, unknown>): void; error(msg: string, meta?: Record<string, unknown>): void;
} }
// 实现：开发环境 console + 结构化；生产环境 → Sentry（P6） // 实现：开发环境 console + 结构化；生产环境 → Sentry（P6）
// 必含字段：trace_id（从响应头提取）、user_id、scope、path // 必含字段：trace_id（从响应头提取）、user_id、scope、path
``` ```
@@ -344,7 +389,7 @@ interface Logger {
| ----------------------------- | ---- | --------------------------------------------------- | | ----------------------------- | ---- | --------------------------------------------------- |
| `teacher_portal_lcp_seconds` | LCP | `next/web-vitals` → `POST /api/v1/admin/web-vitals` | | `teacher_portal_lcp_seconds` | LCP | `next/web-vitals` → `POST /api/v1/admin/web-vitals` |
| `teacher_portal_cls` | CLS | 同上 | | `teacher_portal_cls` | CLS | 同上 |
| `teacher_portal_fid_seconds` | FID | 同上 | | `teacher_portal_inp_seconds` | INP | 同上 |
| `teacher_portal_ttfb_seconds` | TTFB | 同上 | | `teacher_portal_ttfb_seconds` | TTFB | 同上 |
P6 接入，P2-P5 暂缓。 P6 接入，P2-P5 暂缓。
@@ -369,37 +414,38 @@ import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
Next.js 无长连接（除 SSE/WS），无需特殊处理。SSE/WS 在 P5 由 push-gateway 管理，前端断线自动重连。 Next.js 无长连接（除 SSE/WS），无需特殊处理。SSE/WS 在 P5 由 push-gateway 管理，前端断线自动重连。
## 7. 共享组件库（packages/ui-components/，待建立，ai07 维护） ## 7. 共享组件库（packages/ui-components/，ai13 维护，ARB-002 暴露）
| 组件 | 用途 | 来源 | | 组件 | 用途 | MF 暴露（ARB-002） |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------ | | ------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------ |
| `AppShell` | 左侧栏 + 主内容区布局 | teacher-portal 现有 → 抽取共享 | | `AppShell` | 左侧栏 + 主内容区布局 | ✅ `./AppShell` |
| `RequirePermission` | L3 组件级视口控制（无权限不渲染 children） | 新建 | | `RequirePermission` | L3 组件级视口控制（无权限不渲染 children） | ✅ `./RequirePermission` |
| `ErrorBoundary` | React 渲染异常兜底（fallback UI） | 新建 | | `ErrorBoundary` | React 渲染异常兜底（fallback UI） | ✅ `./ErrorBoundary` |
| `Loading` | 骨架屏（Skeleton） | 新建 | | `Loading` | 骨架屏（Skeleton） | ✅ `./Loading` |
| `Empty` | 空态（插画 + 文案 + CTA） | 新建 | | `Empty` | 空态（插画 + 文案 + CTA） | ✅ `./Empty` |
| `Modal` / `Dialog` | 全局 Modal（ModalRoot + Zustand ui-store） | shadcn/ui | | `Modal` / `Dialog` | 全局 Modal（ModalRoot + Zustand ui-store） | shadcn/ui |
| `Toast` | 全局 toast（错误/成功/警告） | shadcn/ui sonner | | `Toast` | 全局 toast（错误/成功/警告） | shadcn/ui sonner |
| `Button` / `Input` / `Select` / `Textarea` | 基础表单 | shadcn/ui | | `Button` / `Input` / `Select` / `Textarea` | 基础表单 | shadcn/ui |
| `DataTable` | 表格（排序/分页/筛选） | shadcn/ui + TanStack Table | | `DataTable` | 表格（排序/分页/筛选） | shadcn/ui + TanStack Table |
| `Chart` | 图表封装（recharts） | 新建 | | `Chart` | 图表封装（recharts） | 新建 |
| `A11y` 工具集 | useA11yId / mergeA11yProps / describeInput / focus-trap / skip-link / visually-hidden / aria-status | 迁移指南 §7.7 | | `A11y` 工具集 | useA11yId / mergeA11yProps / describeInput / focus-trap / skip-link / visually-hidden / aria-status | 迁移指南 §7.7 |
| `Form` | react-hook-form + zodResolver 封装 | 新建 | | `Form` | react-hook-form + zodResolver 封装 | 新建 |
| `RichTextEditor` | Tiptap 封装（备课/出题/反馈） | 新建 | | `RichTextEditor` | Tiptap 封装（备课/出题/反馈） | 新建 |
## 8. 共享 Hooks（packages/hooks/，待建立，ai07 维护） ## 8. 共享 Hooks（packages/hooks/，ai13 维护，ARB-002 暴露）
| Hook | 职责 | | Hook | 职责 | MF 暴露（ARB-002） |
| --------------------- | --------------------------------------------------- | | --------------------- | --------------------------------------------------- | ------------------ |
| `useAuth()` | 会话状态（user/token/refresh/login/logout） | | `useGraphQLClient()` | urql client 单例（Shell 注入，Remote 复用） | ✅ `./useGraphQLClient` |
| `usePermission()` | 权限查询（hasPermission/hasAny/hasAll + dataScope） | | `useAuth()` | 会话状态（user/token/refresh/login/logout） | ✅ `./useAuth` |
| `useViewports(scope)` | 视口列表（按 scope 过滤） | | `usePermission()` | 权限查询（hasPermission/hasAny/hasAll + dataScope） | ✅ `./usePermission` |
| `useApi()` | ApiClient 实例（注入 token + 401 处理） | | `useViewports(scope)` | 视口列表（GraphQL viewports Query，按 scope 过滤） | — |
| `useA11yId()` | 唯一 ARIA ID 生成 | | `useApi()` | 非 GraphQL 场景（文件上传/SSE）ApiClient 实例 | — |
| `useAriaLive()` | aria-live 区域管理 | | `useA11yId()` | 唯一 ARIA ID 生成 | — |
| `useToast()` | 全局 toast（Zustand ui-store） | | `useAriaLive()` | aria-live 区域管理 | — |
| `useToast()` | 全局 toast（Zustand ui-store） | — |
## 9. 设计令牌三层（packages/ui-tokens/，待建立，ai07 维护） ## 9. 设计令牌三层（packages/ui-tokens/，ai13 维护）
``` ```
packages/ui-tokens/ packages/ui-tokens/
@@ -429,52 +475,54 @@ packages/ui-tokens/
| 方向 | 对方服务 | 协议 | 接口/事件 | 用途 | 阶段 | | 方向 | 对方服务 | 协议 | 接口/事件 | 用途 | 阶段 |
| ------ | ------------ | ------------------ | --------------------------------------------------- | ---------------------------- | ---- | | ------ | ------------ | ------------------ | --------------------------------------------------- | ---------------------------- | ---- |
| 调用 | api-gateway | HTTP/REST | `/api/v1/*` 代理 | 全部业务请求 | P1+ | | 调用 | api-gateway | HTTP（GraphQL over HTTP） | `/api/v1/teacher/*` 代理到 teacher-bff `POST /graphql` | 全部 GraphQL 业务请求 | P2+ |
| 调用 | push-gateway | WebSocket | `ws://push-gateway/ws` | 实时推送 | P5 | | 调用 | api-gateway | HTTP | `POST /api/auth/login` | 教师登录（非 MF，认证前提） | P2 |
| 调用 | ai | SSE | `GET /api/v1/ai/generate-questions` | AI 流式出题 | P5 | | 调用 | push-gateway | WebSocket | `ws://push-gateway:8081/ws` | 实时推送 | P5 |
| 调用 | ai | SSE | `GET /api/v1/ai/generate-questions` | AI 流式出题（非 GraphQL） | P5 |
| 被调用 | — | — | — | 前端不暴露接口给其他服务 | — | | 被调用 | — | — | — | 前端不暴露接口给其他服务 | — |
| 消费 | teacher-bff | HTTP（经 Gateway） | `GET /teacher/viewports` 等 | 教师场景聚合 | P2+ | | 消费 | teacher-bff | GraphQL（ARB-001 schema） | `dashboard`/`viewports`/`me`/`classes`/`class` Query（P2）+ P3+ Mutation | 教师场景聚合 | P2+ |
| 消费 | iam | HTTP（经 Gateway） | `/iam/*` | 登录/权限/视口/用户管理 | P2+ | | 消费 | push-gateway | WebSocket | `NotificationRequested`/`HomeworkSubmitted`/角色变更 | 实时推送 | P5+ |
| 消费 | 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-proto` | TS 类型（仅 contracts 部分） | P1+ |
| 依赖 | coord 维护 | — | `packages/shared-ts`（待建） | ApiClient/Logger/通用工具 | P2+ | | 依赖 | coord 维护 | — | `packages/shared-ts` + `contracts/graphql/teacher-bff.graphql` | ApiClient/Logger/GraphQL schema/通用工具 | P2+ |
| 依赖 | ai07 维护 | — | `packages/ui-tokens`（待建） | 三层设计令牌 | P2+ | | 依赖 | ai13 维护 | — | `packages/ui-tokens`（已建，批次 0.15） | 三层设计令牌 | P2+ |
| 依赖 | ai07 维护 | — | `packages/ui-components`（待建） | shadcn + 共享组件 | P2+ | | 依赖 | ai13 维护 | — | `packages/ui-components`（已建，批次 0.15） | shadcn + 共享组件（ARB-002 暴露） | P2+ |
| 依赖 | ai07 维护 | — | `packages/hooks`（待建） | usePermission/useAuth 等 | P2+ | | 依赖 | ai13 维护 | — | `packages/hooks`（已建，批次 0.15） | useGraphQLClient/usePermission/useAuth（ARB-002 暴露） | P2+ |
| 依赖 | coord 维护 | — | `packages/contracts`（待建） | Permissions 常量 + 类型 | P2+ | | 依赖 | coord 维护 | — | `packages/contracts` | Permissions 常量 + 类型 | P2+ |
> **proto 不直接消费**：前端不调用 gRPC，BFF 把 gRPC 聚合为 REST/GraphQL 暴露给前端。前端仅消费 `packages/contracts/src/permissions.ts` 中的权限点常量（TS 文件，非 proto 生成）。 > **前端不直接调 gRPC**：teacher-bff 把 gRPC 聚合为 GraphQL 暴露给前端（F9 裁决）。前端仅消费 `packages/contracts/src/permissions.ts` 中的权限点常量（TS 文件，非 proto 生成）。
## 11. 风险与假设 ## 11. 风险与假设
### 11.1 假设 ### 11.1 假设
1. **假设 coord 建立 `packages/shared-ts`、`packages/contracts`**：包含 ApiClient、Logger、Permissions 常量、通用类型。若 coord 未建立，ai07 自行在 `apps/teacher-portal/src/shared/` 内实现，后续提取到 packages。 1. **假设 coord 建立 `packages/shared-ts`、`packages/contracts`**：包含 GraphQL schema、Logger、Permissions 常量、通用类型。✅ packages 骨架（ui-tokens/ui-components/hooks）已于批次 0.15 建立（ISSUE-039）。
2. **假设 iam 提供 `GET /iam/effective-permissions`**：返回 `{ permissions, viewports, dataScope }`。当前已实现（known-issues §2.3 iam）。 2. **假设 teacher-bff 提供 `POST /graphql`（ARB-001 schema 第一版）**：返回 dashboard/viewports/me/classes/class 5 个 Query。⏳ 待 ai03 + coord 仲裁。
3. **假设 teacher-bff 提供 `GET /teacher/viewports`**：返回 L1 导航视口。当前已实现。 3. **假设 api-gateway 代理 `/api/v1/teacher/*` → teacher-bff:3003**：⏳ 待 ai01。
4. **假设 core-edu classes 模块维持 `ActionState` 响应结构**：前端 API 请求层依赖此契约。 4. **假设 Next.js 14+ Module Federation 2.0 稳定**：`@module-federation/nextjs-mf` 在 Next.js App Router 下可用。若不稳定，降级为 4 端独立部署 + 各自 Shell（重复实现 AppShell）。
5. **假设 Next.js 14+ Module Federation 2.0 稳定**：`@module-federation/nextjs-mf` 在 Next.js App Router 下可用。若不稳定，降级为 4 端独立部署 + 各自 Shell（重复实现 AppShell）。 5. **假设 iam 提供 refresh cookie 端点**：P6 localStorage→httpOnly cookie 迁移前置。⏳ 待 ai06 P6。
### 11.2 技术风险 ### 11.2 技术风险
| 风险 | 影响 | 缓解 | | 风险 | 影响 | 缓解 |
| ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- | | ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| MF SSR 对齐复杂 | Remote 在 SSR 时需 Shell 提供上下文 | 优先 CSR，SSR 仅用于首屏 dashboard；MF 2.0 支持 SSR | | MF SSR 对齐复杂 | Remote 在 SSR 时需 Shell 提供上下文 | 优先 CSR，SSR 仅用于首屏 dashboard；MF 2.0 支持 SSR |
| 共享依赖版本漂移 | Remote 与 Shell 的 react/react-dom 版本不一致导致运行时错误 | MF `shared.singleton: true` + CI 检查版本对齐 | | 共享依赖版本漂移 | Remote 与 Shell 的 react/react-dom/urql/graphql 版本不一致导致运行时错误 | MF `shared.singleton: true`（ARB-002）+ CI 检查版本对齐 |
| Token 刷新竞态 | 多请求同时 401 触发多次 refresh | ApiClient 全局单例 + refresh promise 复用 | | Token 刷新竞态 | 多请求同时 401 触发多次 refresh | useAuth 全局单例 + refresh promise 复用（03 §2.7） |
| 权限缓存陈旧 | 角色变更后前端 5min 内仍用旧权限 | iam 角色变更发 Kafka 事件 → msg 推送 WebSocket → 前端 invalidate | | 权限缓存陈旧 | 角色变更后前端仍用旧权限 | iam 角色变更发 Kafka → msg → push-gateway WebSocket → urql cache invalidate |
| 设计令牌迁移破坏现有样式 | teacher-portal 现有硬编码令牌迁移到三层模型后样式漂移 | 灰度迁移：先建 ui-tokens 包，teacher-portal 引入但不删除旧 globals.css，验证后切换 | | GraphQL schema 演进阻塞 | ai03 schema 变更未同步 ai13 导致前端 query 失效 | SDL-first + schema 注册表 `packages/shared-ts/contracts/graphql/`（ARB-001） |
| TanStack Query 缓存膨胀 | 长时间使用后缓存项过多 | `gcTime` 5min + `staleTime` 按数据类型分级 | | 设计令牌迁移破坏现有样式 | teacher-portal 现有硬编码令牌迁移到三层模型后样式漂移 | 灰度迁移：先建 ui-tokens 包，teacher-portal 引入但不删除旧 globals.css，验证后切换 |
| urql cache 膨胀 | 长时间使用后缓存项过多 | staleTime 分级 + P3 评估 graphcache normalized cache |
### 11.3 未决设计决策（需 coord 仲裁） ### 11.3 已决策设计点（原未决决策，现已对齐仲裁）
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}}`，与错误码前缀对齐。 | packages 归属 | ai13 维护 ui-tokens/ui-components/hooks；coord 维护 shared-ts/contracts | 总裁 §2.18（ISSUE-039） |
4. **MF 暴露粒度**：Shell 暴露整个 AppShell 还是暴露更细粒度的组件（Sidebar、Header、Content）？建议：暴露 AppShell 整体 + 各 Remote 自行决定内部布局。 | GraphQL vs REST | **P2 起 all-in GraphQL（urql），无 REST 过渡** | F9 + ARB-001（ISSUE-036/037） |
| i18n key 命名 | `error.{{service}}.{{code_snake_case}}`，与错误码前缀对齐 | F11 |
| MF 暴露粒度 | 暴露 AppShell 整体 + GraphQLProvider + hooks + UI 组件（ARB-002 清单） | 总裁 §2.17 + ARB-002（ISSUE-038） |
| GraphQL client 单例 | Shell 暴露 GraphQLProvider，Remote 复用（方案 A） | 总裁 §2.17（ISSUE-038） |
| P2 Remote 数量 | 0（NEXT_PUBLIC_MF_ENABLED=false），P3 student 首个接入 | ARB-002 §2.3 |
## 12. coord 交叉审查所需信息 ## 12. coord 交叉审查所需信息
@@ -482,68 +530,74 @@ packages/ui-tokens/
| 端 | dev 端口 | 生产端口 | 备注 | | 端 | dev 端口 | 生产端口 | 备注 |
| -------------- | -------- | -------- | ---------- | | -------------- | -------- | -------- | ---------- |
| teacher-portal | 3000 | 3000 | Shell 宿主 | | teacher-portal | 4000 | 4000 | Shell 宿主 |
> 与 [full-stack-runbook](../../../docs/standards/full-stack-runbook.md) 端口矩阵对齐。 > 与 [matrix.md](../../../docs/architecture/issues/matrix.md) §1 端口矩阵对齐（teacher-portal :4000）。
### 12.2 依赖的共享包（需 coord 建立） ### 12.2 依赖的共享包
| 包 | 路径 | 维护方 | 内容 | | 包 | 路径 | 维护方 | 内容 |
| --------------- | ------------------------- | ------------ | ------------------------------------------------- | | --------------- | ------------------------- | ------------ | ------------------------------------------------- |
| `shared-ts` | `packages/shared-ts/` | coord | ApiClient、Logger、通用工具 | | `shared-ts` | `packages/shared-ts/` | coord | ApiClient、Logger、GraphQL schema、通用工具 |
| `contracts` | `packages/contracts/` | coord | Permissions 常量、ActionState 类型、UserInfo 类型 | | `contracts` | `packages/contracts/` | coord | Permissions 常量、ActionState 类型、UserInfo 类型 |
| `ui-tokens` | `packages/ui-tokens/` | ai07（建议） | 三层设计令牌 | | `ui-tokens` | `packages/ui-tokens/` | ai13 | 三层设计令牌（✅ 已建，批次 0.15） |
| `ui-components` | `packages/ui-components/` | ai07（建议） | shadcn + ErrorBoundary + RequirePermission | | `ui-components` | `packages/ui-components/` | ai13 | shadcn + ErrorBoundary + RequirePermission（✅ 已建，ARB-002 暴露） |
| `hooks` | `packages/hooks/` | ai07（建议） | usePermission、useAuth、useViewports | | `hooks` | `packages/hooks/` | ai13 | useGraphQLClient/usePermission/useAuth（✅ 已建，ARB-002 暴露） |
### 12.3 依赖的后端契约（需对应 AI 确认） ### 12.3 依赖的后端契约（需对应 AI 确认）
| 契约 | 提供方 | 当前状态 | | 契约 | 提供方 | 当前状态 |
| ------------------------------------------------------------------ | ------------------ | ------------------- | | ------------------------------------------------------------------ | ------------------ | ------------------- |
| `POST /iam/login`、`GET /iam/effective-permissions`、`GET /iam/me` | iam | ✅ 已实现 | | `POST /graphql` + dashboard/viewports/me/classes/class Query（ARB-001） | teacher-bff（ai03）| ⏳ 待 coord 仲裁 |
| `GET /teacher/viewports`、`GET /teacher/dashboard` | teacher-bff | ✅ 已实现 | | `POST /api/auth/login` | api-gateway（ai01）→ iam | ⏳ 待 ai01 |
| `/classes/*` CRUD | core-edu | ✅ 已实现 | | classExams/classHomework/studentGrades Query + Mutation | teacher-bff（ai03 P3）| ⏳ 待 ai03 P3 |
| `/exams/*` `/homework/*` `/grades/*` | core-edu | ✅ 已实现（P3） | | knowledgeGraph/studentAnalytics Query | teacher-bff（ai03 P4）| ⏳ 待 ai03 P4 |
| `/textbooks/*` `/knowledge-points/*` `/questions/*` | content | ✅ 已实现（P4） | | myNotifications/markAsRead Query + Mutation | teacher-bff（ai03 P5）| ⏳ 待 ai03 P5 |
| `/analytics/*` | data-ana | ✅ 已实现（P4 CDC） | | `ws://push-gateway:8081/ws` 推送 | push-gateway（ai02 P5）| ⏳ 待 ai02 P5 |
| `/notifications/*` + WebSocket 推送 | msg + push-gateway | 📐 待 P5 | | `GET /api/v1/ai/generate-questions`（SSE） | ai（ai12 P5） | ⏳ 待 ai12 P5 |
| `GET /ai/generate-questions`（SSE） | ai | 📐 待 P5 |
### 12.4 错误码前缀（前端 i18n 路由依赖） ### 12.4 错误码前缀（前端 i18n 路由依赖，对齐 [matrix.md §6](../../../docs/architecture/issues/matrix.md)）
前端不产生错误码，仅消费。需各服务确认错误码前缀不重叠： 前端不产生错误码，仅消费。需各服务确认错误码前缀不重叠：
| 前缀 | 服务 | 状态 | | 前缀 | 服务 | 状态 |
| ------------------------------ | ----------- | --------- | | ------------------------------ | ----------- | --------- |
| `IAM_` | iam | ✅ 已用 | | `IAM_` | iam | ✅ 已用 |
| `CORE_EDU_` | core-edu | ✅ 已用 |
| `CLASSES_` | core-edu | ✅ 已用 | | `CLASSES_` | core-edu | ✅ 已用 |
| `EXAMS_`/`HOMEWORK_`/`GRADES_` | core-edu | ⚠️ 待确认 | | `EXAMS_`/`HOMEWORK_`/`GRADES_` | core-edu | ⚠️ 待确认 |
| `CONTENT_` | content | ⚠️ 待确认 | | `CONTENT_` | content | ⚠️ 待确认 |
| `MSG_` | msg | ⚠️ 待确认 | | `MSG_` | msg | ⚠️ 待确认 |
| `AI_` | ai | ⚠️ 待确认 | | `AI_` | ai | ⚠️ 待确认 |
| `BFF_TEACHER_` | teacher-bff | ⚠️ 待确认 | | `BFF_TEACHER_` | teacher-bff | ✅ 已裁决（G14） |
| `GW_` | api-gateway | ✅ 已用 | | `GW_` | api-gateway | ✅ 已用 |
| `NETWORK_` | 前端 | ai07 自有 | | `NETWORK_` | 前端 | ai13 自有 |
### 12.5 不产生 Kafka 事件 ### 12.5 不产生 Kafka 事件
前端不发布/消费 Kafka 事件。WebSocket 推送由 push-gateway 消费 Kafka 转发。 前端不发布/消费 Kafka 事件。WebSocket 推送由 push-gateway 消费 Kafka 转发。
## 13. 实施路线（ai07 自用） ## 13. 实施路线（ai13 自用，详见 [workline.md](../../../docs/architecture/issues/worklines/teacher-portal_workline.md)）
### P2 收尾（teacher-portal 审计对齐） ### P2（MF Shell + GraphQL client + 基础页面，ARB-001/002）
1. 建 `packages/ui-tokens/`（三层设计令牌）+ `packages/ui-components/`（ErrorBoundary/RequirePermission/Loading/Empty）+ `packages/hooks/`（usePermission/useAuth） 1. ✅ packages 骨架（ui-tokens/ui-components/hooks，批次 0.15 已完成）
2. teacher-portal 引入 TanStack Query + Zustand + nuqs + react-hook-form 2. NextFederationPlugin 配置（ARB-002 exposes + shared，**无 remotes**）
3. 抽取 `lib/api.ts` 统一 API 请求层 3. GraphQLProvider + urql client 单例（Shell 暴露，§2.17 方案 A）
4. AppShell 改用 `usePermission()`，删除 `user.roles.join(", ")` 硬编码 4. AppShell（Layout + 侧边栏 + 路由守卫 + ErrorBoundary + 设计令牌三层）
5. globals.css / tailwind.config.js 迁移到 ui-tokens 三层令牌 5. 登录页（`POST /api/auth/login` → JWT 存 localStorage，F12）
6. 引入 next-intl + i18n key 路由 6. 权限上下文（usePermission + useViewports，权限点 `<RESOURCE>_<ACTION>` F7）
7. 引入 ESLint flat config 自定义规则（no-hardcoded-fonts / design-tokens） 7. Dashboard 框架（`dashboard` GraphQL Query）+ 班级列表（`classes`/`class` Query）+ 学生列表 + 个人设置
8. 补 ErrorBoundary + /api/health route 8. 补 ErrorBoundary + /api/health route
9. 配置 next.config.js Module Federation（Shell 角色） 9. 引入 ESLint flat config 自定义规则（no-hardcoded-fonts / design-tokens）
10. 补 Vitest 单测 + Playwright E2E（覆盖率 ≥ 80%） 10. 补 Vitest 单测 + Playwright E2E（覆盖率 ≥ 80%）
### P3（考试/作业/成绩 + 乐观更新 + 多 Tab 同步）
1. 考试/作业/成绩管理页面（GraphQL Query + Mutation）
2. 乐观更新（urql mutation onMutate 回滚 + invalidate）
3. 多 Tab 会话同步（BroadcastChannel，03 §2.5）
### P5（推送 + AI 接入） ### P5（推送 + AI 接入）
1. teacher-portal 接入 WebSocket（push-gateway） 1. teacher-portal 接入 WebSocket（push-gateway）
@@ -553,10 +607,11 @@ packages/ui-tokens/
1. Web Vitals + OTel browser SDK 接入 1. Web Vitals + OTel browser SDK 接入
2. A11y WCAG 2.2 AA 审计 2. A11y WCAG 2.2 AA 审计
3. 性能优化（MF shared 单例验证、bundle 分析） 3. localStorage → httpOnly Cookie 迁移
4. 性能优化（MF shared 单例验证、bundle 分析）
--- ---
**AI Agent**: ai07 (teacher-portal shell) **AI Agent**: ai13 (teacher-portal shell)
**Branch**: docs/teacher-portal-stage1-stage2-design-ai07 **Branch**: feat-review-teacher-portal-docs-vErc0L
**Coordinator**: coord-ai **Coordinator**: coord-ai

18
docs/architecture/issues/contracts/teacher-portal_contract.md
View File

@@ -60,11 +60,11 @@
### 2.3 HTTP 调用（如有） ### 2.3 HTTP 调用（如有）
| 被调用方 | Method.Path | 用途 | mock 策略 | | 被调用方 | Method.Path | 用途 | mock 策略 |
| ------------------- | ------------------------- | --------------------------------------------- | ----------------------------------------------------------------- | | ------------------- | ---------------------------- | --------------------------------------------- | ----------------------------------------------------------------- |
| api-gateway (ai01) | POST /api/teacher/graphql | 教师 GraphQL 查询（经网关代理到 teacher-bff） | api-gateway/teacher-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 | | api-gateway (ai01) | POST /api/v1/teacher/graphql | 教师 GraphQL 查询（经网关代理到 teacher-bff，对齐 matrix.md §5） | api-gateway/teacher-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 |
| api-gateway (ai01) | POST /api/auth/login | 教师登录 | api-gateway 就绪前使用 MSW 返回固定 JWT | | api-gateway (ai01) | POST /api/auth/login | 教师登录（非 GraphQL，认证前提，F12: JWT 存 localStorage） | api-gateway 就绪前使用 MSW 返回固定 JWT |
| push-gateway (ai02) | GET /ws | WebSocket 实时通知 | push-gateway 就绪前使用 mock-socket 模拟 WS 推送 | | push-gateway (ai02) | GET /ws | WebSocket 实时通知 | push-gateway 就绪前使用 mock-socket 模拟 WS 推送 |
### 2.4 GraphQL 查询域（经 api-gateway 代理到 teacher-bff） ### 2.4 GraphQL 查询域（经 api-gateway 代理到 teacher-bff）
@@ -97,8 +97,8 @@
- [ ] teacher-portal dev server :4000 启用 - [ ] teacher-portal dev server :4000 启用
- [ ] MF Shell 可加载（首页渲染 AppShell + 导航） - [ ] MF Shell 可加载（首页渲染 AppShell + 导航）
- [ ] 子应用路由可访问（/classes /exams /homework 等子页面渲染） - [ ] 子应用路由可访问（/classes /exams /homework 等子页面渲染）
- [ ] 登录流程可用（POST /api/auth/login 获取 JWT 存入 cookie） - [ ] 登录流程可用（POST /api/auth/login 获取 JWT 存入 localStorage，F12；P6 迁移 httpOnly cookie）
- [ ] GraphQL 查询可执行（currentUser / myClasses 返回数据） - [ ] GraphQL 查询可执行（dashboard / viewports / me / classes / class Query，ARB-001）
- [ ] WebSocket 通知可接收（push-gateway 推送 → 前端通知中心更新） - [ ] WebSocket 通知可接收（push-gateway 推送 → 前端通知中心更新）
--- ---
@@ -118,9 +118,9 @@ teacher-portal 是最前端，无下游消费方。但对开发体验提供：
- **HTTP/GraphQL mock**：使用 MSW（Mock Service Worker）拦截所有请求 - **HTTP/GraphQL mock**：使用 MSW（Mock Service Worker）拦截所有请求
- POST /api/auth/login → 返回固定 JWT + UserInfo - POST /api/auth/login → 返回固定 JWT + UserInfo
- POST /api/teacher/graphql → 根据 operationName 返回对应 mock 响应（与 teacher-bff mock 数据一致） - POST /api/v1/teacher/graphql → 根据 operationName 返回对应 mock 响应（与 teacher-bff mock 数据一致，对齐 §2.3）
- 所有 mock 响应定义在 `apps/teacher-portal/src/mocks/fixtures/*.json` - 所有 mock 响应定义在 `apps/teacher-portal/src/mocks/fixtures/*.json`
- **WebSocket mock**：使用 mock-socket 库 - **WebSocket mock**：使用 mock-socket 库
- 连接 ws://localhost:8081/ws 后每 30 秒推送 1 条 mock 通知 - 连接 ws://localhost:8081/ws 后每 30 秒推送 1 条 mock 通知
- **JWT mock**：使用固定 mock JWT（与 api-gateway mock 公钥配对），存入 httpOnly cookie - **JWT mock**：使用固定 mock JWT（与 api-gateway mock 公钥配对），存入 localStorage（F12；P6 迁移 httpOnly cookie）
- **环境切换**：通过 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制是否启用 MSW，上游就绪后设为 `disabled` - **环境切换**：通过 `NEXT_PUBLIC_API_MOCKING=enabled` 环境变量控制是否启用 MSW，上游就绪后设为 `disabled`

25
docs/architecture/issues/objections/teacher-portal_issue.md
View File

@@ -155,6 +155,31 @@
--- ---
### ISSUE-042-ai13：仲裁核查 - 01/02 文档未同步已裁决的 GraphQL 架构
- **提请方**：ai13
- **日期**：2026-07-10
- **类型**：文档同步遗漏（仲裁核查）
- **阶段**：P2
- **描述**：
- 按"对已有仲裁进行核查"要求，审查 ISSUE-036~041（均已裁决）在文档中的落地情况
- 核查发现：`apps/teacher-portal/docs/01-understanding.md` 和 `02-architecture-design.md` 仍为 ai07 标识 + REST 架构，**未同步**以下已裁决事项：
- F9（ISSUE-036）：P2 起 all-in GraphQL，无 REST 过渡 — 01 §1/§3.1 仍写"P2-P3 用 REST 过渡"；02 全文基于 REST（ApiClient/TanStack Query/契约清单）
- ARB-001（ISSUE-037）：teacher-bff GraphQL schema 第一版 5 Query — 01 §3.1 列 REST 端点；02 §4/§10 全 REST
- ARB-002（ISSUE-038/039）：MF Shell 暴露清单（GraphQLProvider + hooks + UI 组件 + urql/graphql singleton）— 01 未提；02 §1.2 exposes 仅 AppShell+shared-deps、P2 配 3 remotes、shared 无 urql
- 总裁 §2.17（ISSUE-038）：GraphQL client 单例方案 A — 02 §11.3.2 仍列"GraphQL vs REST"未决（已裁决）
- 对照已回写的 `03-long-term-architecture.md §1.4`（GraphQL 最终方案），01/02 严重滞后
- **建议方案**：
1. 01-understanding.md：ai07→ai13；§1 删除 REST 过渡；§3.1 REST 端点→GraphQL queries（ARB-001）；§4 技术栈补 urql；补 ARB-002 暴露清单
2. 02-architecture-design.md：ai07→ai13；全文 REST→GraphQL 重写（MF 配置对齐 ARB-002；API 层改 urql client；契约清单改 GraphQL；§11.3 未决决策改已决策）
- **状态**：✅ 已回写闭合（2026-07-10，审查批次）
- **coord 裁决**：无需新裁决（复用 ISSUE-036~040 已有裁决），本次为文档同步执行
- **回写执行**：
- `01-understanding.md`：已修正 ai07→ai13、§1 REST→GraphQL、§3.1 REST 端点→GraphQL queries（ARB-001）、§4 补 urql/GraphQL client 技术栈、补 ARB-002 暴露清单、端口对齐、字体令牌描述
- `02-architecture-design.md`：全量重写为 GraphQL 架构（§1 MF 图加 GraphQLProvider 层；§1.2 MF 配置对齐 ARB-002 exposes/shared/remotes=0；§2 领域模型数据源改 GraphQL Query；§3 缓存层改 urql cacheExchange；§4 API 设计改 urql client 单例 + ARB-001 Query/Mutation；§10 契约清单改 GraphQL；§11.3 未决决策改已决策表；端口 3000→4000）
---
**AI Agent**: ai13（teacher-portal） **AI Agent**: ai13（teacher-portal）
**Branch**: feat/teacher-portal-issues-migrate-ai13 **Branch**: feat/teacher-portal-issues-migrate-ai13
**Coordinator**: coord-ai **Coordinator**: coord-ai

4
docs/architecture/issues/worklines/teacher-portal_workline.md
View File

@@ -74,7 +74,7 @@ gantt
- 学生列表页（classStudents GraphQL query，iam 数据） - 学生列表页（classStudents GraphQL query，iam 数据）
- 个人设置页（currentUser + updateUser GraphQL query/mutation） - 个人设置页（currentUser + updateUser GraphQL query/mutation）
- **依赖**：teacher-bff GraphQL schema 第一版（ai03 + coord 仲裁 ISSUE-037）+ api-gateway 路由（ai01） - **依赖**：teacher-bff GraphQL schema 第一版（ai03 + coord 仲裁 ISSUE-037）+ api-gateway 路由（ai01）
- **Mock 策略**：MSW 拦截 POST /api/teacher/graphql + POST /api/auth/login（见 contract.md §4.2） - **Mock 策略**：MSW 拦截 POST /api/v1/teacher/graphql + POST /api/auth/login（见 contract.md §4.2，对齐 matrix.md §5 路径前缀）
- **验收标准**：MF 配置不破坏单体 + GraphQL 拉取数据 + 登录→Dashboard→班级列表→学生列表链路通 - **验收标准**：MF 配置不破坏单体 + GraphQL 拉取数据 + 登录→Dashboard→班级列表→学生列表链路通
### P3：考试/作业/成绩 + 乐观更新 + 多 Tab 同步 ### P3：考试/作业/成绩 + 乐观更新 + 多 Tab 同步
@@ -135,7 +135,7 @@ gantt
| --------------------------------------------------------- | ------------------------------------------------- | -------- | ---------------------- | | --------------------------------------------------------- | ------------------------------------------------- | -------- | ---------------------- |
| packages 骨架（ai13 自建） | ui-tokens/ui-components/hooks 可 import | P2 启动 | ✅ 已就绪（批次 0.15） | | packages 骨架（ai13 自建） | ui-tokens/ui-components/hooks 可 import | P2 启动 | ✅ 已就绪（批次 0.15） |
| teacher-bff GraphQL schema（ai03 + coord 仲裁 ISSUE-037） | packages/shared-ts/contracts/graphql/ 第一版 | P2 启动 | ⏳ 待 coord 仲裁 | | teacher-bff GraphQL schema（ai03 + coord 仲裁 ISSUE-037） | packages/shared-ts/contracts/graphql/ 第一版 | P2 启动 | ⏳ 待 coord 仲裁 |
| api-gateway HTTP :8080（ai01） | /api/teacher/graphql + /api/auth/login 路由可用 | P2 启动 | ⏳ 待 ai01 | | api-gateway HTTP :8080（ai01） | /api/v1/teacher/graphql + /api/auth/login 路由可用 | P2 启动 | ⏳ 待 ai01 |
| teacher-bff core-edu 扩展（ai03 P3） | classExams/classHomework/studentGrades query 可用 | P3 启动 | ⏳ 待 ai03 P3 | | teacher-bff core-edu 扩展（ai03 P3） | classExams/classHomework/studentGrades query 可用 | P3 启动 | ⏳ 待 ai03 P3 |
| teacher-bff content/data-ana 扩展（ai03 P4） | knowledgeGraph/studentAnalytics query 可用 | P4 启动 | ⏳ 待 ai03 P4 | | teacher-bff content/data-ana 扩展（ai03 P4） | knowledgeGraph/studentAnalytics query 可用 | P4 启动 | ⏳ 待 ai03 P4 |
| push-gateway WebSocket :8081/ws（ai02 P5） | WS 连接可建立 + 推送可接收 | P5 启动 | ⏳ 待 ai02 P5 | | push-gateway WebSocket :8081/ws（ai02 P5） | WS 连接可建立 + 推送可接收 | P5 启动 | ⏳ 待 ai02 P5 |