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

Merge worktree branch merge-15-modules-to-main-5ug5xJ

Browse Source
This commit is contained in:
SpecialX
2026-07-10 15:28:20 +08:00
parent 60d7173545
commit df62ffc176
51 changed files with 11559 additions and 1908 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
> AI：ai07（TS/React · 教学场景域前端 shell）
> AI：ai13（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)
> 日期：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、[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 六层架构中的前端层）
- **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）
- **BFF 对接**：teacher-bff（GraphQL Yoga + DataLoader，P2-P3 用 REST 过渡）
- **通信方式**：HTTP/REST（前端→Gateway）+ WebSocket（前端→push-gateway，P5）
- **BFF 对接**：teacher-bff（GraphQL Yoga + DataLoader，P2 起 all-in GraphQL，F9 裁决，无 REST 过渡）
- **通信方式**：GraphQL over HTTP（前端→Gateway→teacher-bff）+ WebSocket（前端→push-gateway，P5）+ SSE（前端→ai 服务，P5）
- **不直连**：前端不直连任何业务服务或 BFF 后端实例，全部经 api-gateway 代理
**说明**：
- 通过 `next.config.js` 的 `rewrites` 将 `/api/v1/*` 代理到 `api-gateway`
- MF 架构下，teacher-portal 作为 Shell 宿主提供 AppShell + 共享组件库 + 权限 Hook + API 请求层
- 通过 `next.config.js` 的 `rewrites` 将 `/api/v1/*` 代理到 `api-gateway`，api-gateway 再反向代理到 teacher-bff GraphQL endpoint
- 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
## 2. 我的限界上下文
@@ -49,19 +50,21 @@
### 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） |
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)。
### 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
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）
| 协议 | 场景 |
| ------------------------- | -------------------------------------------- |
| WebSocket（push-gateway） | 学生提交作业通知、考试成绩录入提醒、全校广播 |
| SSE（ai 服务） | AI 辅助出题流式响应 |
| SSE（ai 服务，经 teacher-bff 代理或直连） | AI 辅助出题流式响应 |
### 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. 我的技术栈
@@ -91,11 +94,12 @@ type ActionState<T> =
| --------------------------- | -------------------------------------------------------- | ---------------------------------------------- |
| 框架 | 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 |
| 微前端 | 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+ | 配合设计令牌三层模型 |
| UI 组件库 | shadcn/ui（迁移指南 §7.2） | 平移至 `packages/ui-components/`，MF 共享 |
| 状态管理 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 | 客户端业务状态 |
| 状态管理 L4 Global UI | Zustand ui-store + ModalRoot | 全局 UI 状态 |
| 状态管理 L5 Form | react-hook-form + zodResolver | 表单状态 |
@@ -103,7 +107,7 @@ type ActionState<T> =
| 图表 | 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 变量暴露 |
| 字体 | sans/serif/mono（通过 `var(--font-family-*)` 引用，禁止字面量） | next/font/google 加载，CSS 变量暴露（§3.10 强制） |
## 5. 我的阶段归属
@@ -201,5 +205,5 @@ apps/teacher-portal/
---
**AI Agent**: ai07 (teacher-portal shell)
**Branch**: docs/teacher-portal-stage1-stage2-design-ai07
**AI Agent**: ai13 (teacher-portal shell)
**Branch**: feat-review-teacher-portal-docs-vErc0L