f7e52b5b7f
- 版本 1.0 -> 1.1，日期 2026-07-17 - 新增 §13 数据访问层与 GraphQL 安全栈（6 子节） - 更新 §5/§9.6/§10/§11/§12/附录 A/B/C - 修正 004 §16.5 测试数（admin 31->4，sidebar 5->9） - arch:scan 通过（TS 20 模块/4803 符号）
1209 lines
77 KiB
Markdown
1209 lines
77 KiB
Markdown
# portal-shell 模块架构文档
|
||
|
||
> 版本：1.1
|
||
> 日期：2026-07-17
|
||
> 状态：已落地（v2.1 M8-M12 完成 + 2026-07-17 数据抽象与 GraphQL 加固 M1-M4 完成）
|
||
> 架构范式：Modular Monolith + Micro-kernel（单 Next.js App Router 容器 + 插件化仪表盘）
|
||
> 关联文档：
|
||
>
|
||
> - [004 架构影响地图](../../docs/architecture/004_architecture_impact_map.md) §1.2/§3/§4/§11.7/§16
|
||
> - [portal-shell 仪表盘 spec](../../docs/superpowers/specs/2026-07-14-portal-shell-widget-dashboard-design.md) v2.1
|
||
> - [portal-shell 数据抽象与 GraphQL 加固 spec](../../docs/superpowers/specs/2026-07-17-portal-shell-data-abstraction-and-graphql-hardening-design.md) v1.0
|
||
> - [项目规则](../../.trae/rules/project_rules.md) §3.10 设计令牌、§14 多 AI 协作
|
||
> - [UI 设计系统](../../docs/standards/ui-design-system.md)
|
||
> - [known-issues §1.11/§2.17](../../docs/troubleshooting/known-issues.md)
|
||
> - [GraphQL @auth 审计报告](../../docs/security/graphql-auth-audit-2026-07.md)
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [引言与目标](#1-引言与目标)
|
||
2. [架构约束](#2-架构约束)
|
||
3. [系统范围与上下文（C4 L1）](#3-系统范围与上下文c4-l1)
|
||
4. [解决方案策略](#4-解决方案策略)
|
||
5. [构建块视图（C4 L2/L3）](#5-构建块视图c4-l2l3)
|
||
6. [插件目录与分类](#6-插件目录与分类)
|
||
7. [运行时视图（关键场景）](#7-运行时视图关键场景)
|
||
8. [部署视图](#8-部署视图)
|
||
9. [横切概念](#9-横切概念)
|
||
10. [架构决策记录（ADR 索引）](#10-架构决策记录adr-索引)
|
||
11. [质量要求与验收](#11-质量要求与验收)
|
||
12. [风险、技术债与演进路线](#12-风险技术债与演进路线)
|
||
13. [数据访问层与 GraphQL 安全栈（v1.1 新增）](#13-数据访问层与-graphql-安全栈v11-新增)
|
||
14. [术语表](#14-术语表)
|
||
|
||
---
|
||
|
||
## 1. 引言与目标
|
||
|
||
### 1.1 模块定位
|
||
|
||
portal-shell 是 Edu 平台 v2.1 架构重设计后的**唯一前端入口**，以单 Next.js App Router 容器替代 v1.0 的 4 个独立 portal（teacher / student / parent / admin）+ Module Federation 微前端方案。它承载教师、学生、家长、管理员四类角色的全部教学场景 UI，通过 **Micro-kernel + 插件化** 机制实现功能扩展。
|
||
|
||
- **服务端口**：4010（HTTP）
|
||
- **技术栈**：TypeScript 5.6 + Next.js 14 App Router + React 18 + Tailwind + Zustand + SWR + Apollo Client
|
||
- **架构风格**：Modular Monolith（单体）+ Micro-kernel（微内核插件）
|
||
- **部署形态**：单 Docker 容器（`output: "standalone"`）
|
||
- **上游依赖**：api-gateway（JWT 校验 + 反向代理）、apollo-router（GraphQL 联邦入口）
|
||
- **下游契约**：通过 apollo-router 查询 7 个业务子图（iam / config-service / core-edu / content / msg / data-ana / ai）
|
||
|
||
### 1.2 设计目标
|
||
|
||
| # | 目标 | 衡量标准 |
|
||
| --- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
||
| G1 | **单服务部署**：一个 Dockerfile、一个容器，无 MF 远程加载 | 容器数 = 1；无运行时远程 bundle |
|
||
| G2 | **配置驱动可见性**：admin 改配置 → 用户刷新生效，无需重新部署 | 配置变更感知延迟 ≤ 5 分钟（SWR refreshInterval） |
|
||
| G3 | **首屏秒开**：RSC 服务端预取 Config + initialData，消除 CSR 瀑布流 | LCP < 2s（本地 Docker） |
|
||
| G4 | **插件强隔离**：插件间禁止直接 import，仅通过 URL/Zustand 共享状态 | ESLint `no-restricted-imports` 强制；arch:scan 违规检测 |
|
||
| G5 | **设计系统一致**：所有插件使用 `@edu/ui-tokens`，禁硬编码颜色/字体/字号 | ESLint `no-restricted-syntax` + `design-tokens/no-hardcoded-fonts` 零违规 |
|
||
| G6 | **按需加载**：dynamic import 懒加载，首屏只加载可见 slot 插件 | 首屏 JS bundle ≤ 300KB（gzip） |
|
||
| G7 | **跨角色复用**：universal 插件按 role 渲染不同视图，一套代码服务多角色 | universal 插件复用率 100% |
|
||
|
||
### 1.3 非目标
|
||
|
||
- 不重写后端微服务、BFF、网关
|
||
- 不实现插件拖拽编辑器（canvas 模板预留接口，MVP 不做拖拽）
|
||
- MVP 不实现第三方插件上传（二期，预留 iframe + postMessage 沙箱方案）
|
||
- 不实现插件市场在线商店（二期仅支持本地 ZIP 上传）
|
||
|
||
---
|
||
|
||
## 2. 架构约束
|
||
|
||
### 2.1 全局约束（来自项目规则）
|
||
|
||
| 约束 | 来源 | portal-shell 落地方式 |
|
||
| ------------------------------- | ------------------- | ----------------------------------------------------------------- |
|
||
| 禁硬编码颜色（`#hex`） | project_rules §3.10 | ESLint `no-restricted-syntax` + Tailwind `bg-*` 类 |
|
||
| 禁硬编码字体（`'Inter'`） | project_rules §3.10 | `next/font/google` + CSS 变量 `--font-family-*` |
|
||
| 禁 Tailwind 任意值（`w-[Npx]`） | project_rules §3.10 | 映射到 `--space-*` 或 Tailwind 默认阶梯 |
|
||
| 函数返回值显式标注 | project_rules §3.4 | 所有插件 `React.ReactElement` / `Promise<T>` |
|
||
| 禁 `any` / `as` 断言 | project_rules §3.4 | `unknown` + 类型守卫；测试外不写 `as` |
|
||
| Controller 权限装饰器 | project_rules §3.8 | portal-shell 无 Controller，权限由 api-gateway 注入 `x-user-role` |
|
||
| ESM `.js` 后缀导入 | project_rules §3.4 | `next.config.js` webpack `extensionAlias` 映射 |
|
||
|
||
### 2.2 模块边界（多 AI 协作）
|
||
|
||
- **只修改**：`apps/portal-shell/` 目录
|
||
- **只读引用**：
|
||
- `packages/shared-ts/src/contracts/`（plugin.ts / layout.ts / plugin-store.ts / plugin-context.ts）
|
||
- `packages/ui-components/`、`packages/ui-tokens/`、`packages/hooks/`
|
||
- `packages/shared-proto/proto/`（仅查询字段命名对齐）
|
||
- **跨模块契约**：通过 apollo-router GraphQL 子图（不直接调 gRPC，不直接访问业务服务 DB）
|
||
- **禁止**：
|
||
- 直接 import 其他 `apps/*` 或 `services/*` 的源码
|
||
- 直接访问 MySQL / Redis / Kafka
|
||
- 在插件间直接 import（必须通过 URL Search Params 或 Zustand Store 共享状态）
|
||
|
||
### 2.3 通信约束
|
||
|
||
| 调用方 → 被调用方 | 协议 | 场景 |
|
||
| ------------------------------- | -------------- | ------------------------------------------------------------- |
|
||
| portal-shell → api-gateway | HTTP 反向代理 | `/api/v1/*` 透传（JWT 校验 + 注入 `x-user-id`/`x-user-role`） |
|
||
| portal-shell → apollo-router | HTTP / GraphQL | 所有业务查询与配置查询（M8 验收点） |
|
||
| portal-shell → realtime-gateway | SSE | 通知推送（默认） |
|
||
| portal-shell → realtime-gateway | WebSocket | 监考双向场景（仅此场景用 WS） |
|
||
|
||
**禁止**：portal-shell 直连业务服务 gRPC 或 DB。
|
||
|
||
---
|
||
|
||
## 3. 系统范围与上下文（C4 L1）
|
||
|
||
### 3.1 Context 图
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Users["用户"]
|
||
Teacher["教师"]
|
||
Student["学生"]
|
||
Parent["家长"]
|
||
Admin["管理员"]
|
||
end
|
||
|
||
subgraph PortalShell["portal-shell :4010"]
|
||
Shell["插件化仪表盘<br/>Modular Monolith + Micro-kernel"]
|
||
end
|
||
|
||
subgraph Upstream["上游服务"]
|
||
Gateway["api-gateway :8080<br/>JWT 校验 + 反向代理"]
|
||
Router["apollo-router :3000<br/>GraphQL 联邦入口"]
|
||
Realtime["realtime-gateway :8081<br/>SSE 推送"]
|
||
end
|
||
|
||
subgraph Subgraphs["业务子图（经 Router 聚合）"]
|
||
IAM["iam"]
|
||
Config["config-service"]
|
||
CoreEdu["core-edu"]
|
||
Content["content"]
|
||
Msg["msg"]
|
||
DataAna["data-ana"]
|
||
AI["ai"]
|
||
end
|
||
|
||
Teacher --> Shell
|
||
Student --> Shell
|
||
Parent --> Shell
|
||
Admin --> Shell
|
||
|
||
Shell -->|HTTP /api/v1/*| Gateway
|
||
Shell -->|GraphQL 查询| Router
|
||
Shell -->|SSE 通知| Realtime
|
||
|
||
Gateway -->|JWT 校验 + 注入头| Shell
|
||
Router --> IAM
|
||
Router --> Config
|
||
Router --> CoreEdu
|
||
Router --> Content
|
||
Router --> Msg
|
||
Router --> DataAna
|
||
Router --> AI
|
||
```
|
||
|
||
### 3.2 外部契约
|
||
|
||
| 契约 | 提供方 | 消费方式 | 说明 |
|
||
| -------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------- | ---------------------------- |
|
||
| `pluginConfig(userId, role)` | config-service 子图 | RSC 服务端查询 + SWR 客户端静默刷新 | 三层合并后的插件配置 |
|
||
| `pluginRegistry` / `rolePluginMapping` / `layoutTemplates` / `roleLayoutDefault` | config-service 子图 | admin 配置面板（plugin-manager 插件） | admin CRUD |
|
||
| `resetUserLayoutOverride(userId)` | config-service 子图 | admin 重置用户布局 | mutation |
|
||
| 业务查询（grades / homework / schedule 等） | core-edu / content / msg 等子图 | 各 widget 插件 `useWidgetQuery` | 经 apollo-router 自动路由 |
|
||
| `x-user-id` / `x-user-role` 请求头 | api-gateway | RSC `headers()` 读取 | JWT 校验后注入 |
|
||
| JWT | iam 签发 → api-gateway 校验 | Apollo Client `Authorization: Bearer` | localStorage + cookie 双通道 |
|
||
|
||
---
|
||
|
||
## 4. 解决方案策略
|
||
|
||
### 4.1 核心策略：Micro-kernel + Plugin Registry
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ Shell（微内核，纯宿主，无业务逻辑） │
|
||
│ ┌────────────┐ ┌────────────┐ ┌────────────────────┐ │
|
||
│ │ LayoutMgr │ │ SlotRend │ │ PluginLoader │ │
|
||
│ │ 5 模板 │→ │ 按slot分发 │→ │ dynamic import │ │
|
||
│ └────────────┘ └────────────┘ │ + ErrorBoundary │ │
|
||
│ └────────────────────┘ │
|
||
│ ┌────────────┐ ┌────────────┐ ┌────────────────────┐ │
|
||
│ │ Registry │ │ PropsMerge │ │ PluginStore │ │
|
||
│ │ 31 插件 │ │ 三层合并 │ │ Zustand UI 状态 │ │
|
||
│ └────────────┘ └────────────┘ └────────────────────┘ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
↑ PluginProps 契约 ↑
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ Widgets（31 内置插件，按 7 分类组织） │
|
||
│ universal / sidebar / topbar / teacher / student / ... │
|
||
└──────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**关键决策**：
|
||
|
||
1. **Shell 是纯宿主**：不含任何业务逻辑，只负责 Layout 框架、Config 下发、Registry 查表、Loader 挂载
|
||
2. **插件即卡片**：所有功能单元统一为"插件"，无"卡片"与"插件"之分
|
||
3. **编译时 Registry + 运行时 Config**：Registry 是 `plugin_id → dynamic import` 静态映射（编译时登记），Config 是"当前用户在哪些 slot 渲染哪些插件"的运行时配置（DB 三层合并）
|
||
4. **RSC 服务端预取**：Shell 在 Server Component 中完成 Config 拉取 + initialData 预取，随 HTML 直出
|
||
5. **dynamic import 懒加载**：插件按需加载，首屏只加载可见 slot 的插件
|
||
6. **强隔离**：插件间禁止直接 import，通过 URL Search Params（可分享）+ Zustand（纯 UI）共享状态
|
||
|
||
### 4.2 数据流分层
|
||
|
||
```
|
||
URL Search Params ← 可分享、可前进后退的全局上下文（classId/childId/termId/view）
|
||
Zustand Store ← 纯 UI、不可分享（theme/locale/sidebarCollapsed）
|
||
插件内部 useState ← 插件私有状态（表单临时值、弹窗开关）
|
||
PluginProps.props ← 三层合并后的配置 props（系统默认 < 角色默认 < 用户调整）
|
||
PluginProps.initialData ← RSC 服务端预取的初始数据（SWR fallbackData）
|
||
```
|
||
|
||
### 4.3 配置刷新策略
|
||
|
||
抛弃 Kafka + WebSocket 推送链路（对低频布局变更属于过度设计），改用 **SWR 静默后台刷新**：
|
||
|
||
- `revalidateOnFocus: true`：用户切回 Tab 时静默刷新
|
||
- `refreshInterval: 300_000`：每 5 分钟轮询
|
||
- `dedupingInterval: 60_000`：1 分钟内去重
|
||
- 检测到配置变化时回调上层 Toast 提示"发现新布局配置，刷新后生效"
|
||
|
||
---
|
||
|
||
## 5. 构建块视图（C4 L2/L3）
|
||
|
||
### 5.1 Container 图（C4 L2）
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph App["apps/portal-shell（单 Next.js 容器）"]
|
||
subgraph AppRouter["app/（Next.js App Router）"]
|
||
Layout["layout.tsx<br/>RootLayout + 字体"]
|
||
RootPage["page.tsx<br/>重定向 /shell"]
|
||
ShellPage["shell/[[...route]]/page.tsx<br/>RSC 入口"]
|
||
HealthAPI["api/health/route.ts"]
|
||
ReadyAPI["api/ready/route.ts"]
|
||
end
|
||
|
||
subgraph ShellCore["shell/（微内核）"]
|
||
Shell["Shell.tsx"]
|
||
ClientShell["ClientShell.tsx"]
|
||
LayoutMgr["LayoutManager.tsx<br/>5 Layout 模板"]
|
||
SlotRend["SlotRenderer.tsx"]
|
||
Loader["PluginLoader.tsx<br/>+ ErrorBoundary"]
|
||
Registry["Registry.tsx<br/>31 插件"]
|
||
Lifecycle["PluginLifecycle.ts"]
|
||
Store["PluginStore.ts<br/>Zustand"]
|
||
Merger["PropsMerger.ts<br/>三层合并"]
|
||
end
|
||
|
||
subgraph Lib["lib/（数据抽象）"]
|
||
Apollo["apollo-client.ts<br/>APQ + sha256"]
|
||
ConfigFetch["config-fetcher.ts"]
|
||
UseConfig["usePluginConfig.ts<br/>SWR 静默刷新"]
|
||
UseQuery["useWidgetQuery.ts"]
|
||
UseMut["useWidgetMutation.ts"]
|
||
Types["types.ts"]
|
||
end
|
||
|
||
subgraph ApiLayer["lib/api/（v1.1 数据访问层）"]
|
||
ApiDomain["<domain>.ts ×7<br/>parent/teacher/admin/student/<br/>universal/sidebar/topbar"]
|
||
ApiOps["operations/*.graphql.ts<br/>51 DocumentNode"]
|
||
ApiTypes["operations/types.ts<br/>codegen 生成"]
|
||
ApiErrors["errors.ts<br/>ApiError 归一化"]
|
||
end
|
||
|
||
subgraph Providers["providers/"]
|
||
ApolloProv["ApolloProvider.tsx"]
|
||
AuthProv["AuthProvider.tsx"]
|
||
ThemeProv["ThemeI18nProvider.tsx"]
|
||
end
|
||
|
||
subgraph Widgets["widgets/（31 内置插件）"]
|
||
Universal["universal/<br/>7 插件"]
|
||
Sidebar["sidebar/<br/>4 插件"]
|
||
Topbar["topbar/<br/>4 插件"]
|
||
Teacher["teacher/<br/>4 插件"]
|
||
Student["student/<br/>4 插件"]
|
||
Parent["parent/<br/>2 插件"]
|
||
Admin["admin/<br/>6 插件"]
|
||
end
|
||
end
|
||
|
||
ShellPage -->|RSC 调用| ConfigFetch
|
||
ShellPage -->|props| ClientShell
|
||
ClientShell --> Shell
|
||
Shell --> LayoutMgr
|
||
LayoutMgr --> SlotRend
|
||
SlotRend --> Registry
|
||
SlotRend --> Loader
|
||
Loader --> Widgets
|
||
ClientShell --> UseConfig
|
||
UseConfig --> Apollo
|
||
Widgets --> ApiDomain
|
||
ApiDomain --> ApiOps
|
||
ApiDomain --> UseQuery
|
||
ApiDomain --> UseMut
|
||
ApiOps --> ApiTypes
|
||
UseQuery --> Apollo
|
||
UseMut --> Apollo
|
||
```
|
||
|
||
### 5.2 组件职责矩阵
|
||
|
||
| 层 | 文件 | 职责 | 关键契约 |
|
||
| -------------- | ----------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
||
| **app/** | `shell/[[...route]]/page.tsx` | RSC 入口，服务端拉 Config + 预取 initialData | `fetchPluginConfig(userId, role)` |
|
||
| **app/** | `layout.tsx` | RootLayout，挂载 `next/font/google` 字体变量 | `--font-inter` / `--font-fraunces` / `--font-jetbrains-mono` |
|
||
| **app/** | `page.tsx` | 根路径重定向到 `/shell` | `redirect("/shell")` |
|
||
| **shell/** | `Shell.tsx` | 微内核入口，选择 LayoutManager 模板 | `config.activeLayout.layoutId` |
|
||
| **shell/** | `ClientShell.tsx` | 客户端入口，挂载 Providers + SWR 配置刷新 | `usePluginConfig(initialConfig)` |
|
||
| **shell/** | `LayoutManager.tsx` | 5 种 Layout 模板渲染器 | classic / focus / split / triple / canvas |
|
||
| **shell/** | `SlotRenderer.tsx` | 按 slot 过滤+排序+查表+注入 PluginProps | `PluginPlacement[]` |
|
||
| **shell/** | `PluginLoader.tsx` | dynamic loading 骨架 + ErrorBoundary 隔离 | `PluginSkeleton` 5 变体 |
|
||
| **shell/** | `Registry.tsx` | 编译时登记 31 内置插件 | `plugin_id → { Component, metadata }` |
|
||
| **shell/** | `PluginLifecycle.ts` | 版本兼容性 + 激活路径 + 可渲染判断 | `checkVersionCompatibility` / `isPluginRenderable` |
|
||
| **shell/** | `PluginStore.ts` | Zustand 全局 UI 状态 | theme / locale / sidebarCollapsed |
|
||
| **shell/** | `PropsMerger.ts` | 三层 props 深合并 | `mergeProps(sys, role, user)` |
|
||
| **lib/** | `apollo-client.ts` | Apollo Client 单例（客户端）+ 工厂（服务端）+ APQ 链 | `getApolloClient()` / `createApolloClient()`，`createPersistedQueryLink({ sha256 })` |
|
||
| **lib/** | `config-fetcher.ts` | RSC 服务端拉 Config，含三级降级 | apollo-router → config-service 直连 → 空默认 |
|
||
| **lib/** | `usePluginConfig.ts` | SWR 静默刷新配置 + 变更检测回调 | `revalidateOnFocus` + `refreshInterval: 300_000` |
|
||
| **lib/** | `useWidgetQuery.ts` | 统一 GraphQL 查询 Hook，支持 fallbackData | `useQuery` + `skip` + `pollInterval` |
|
||
| **lib/** | `useWidgetMutation.ts` | 统一 GraphQL 变更 Hook | `useMutation` + `errorPolicy: "all"` |
|
||
| **lib/** | `types.ts` | 共享类型契约 | `PluginProps` / `PluginManifest` / `PluginConfigResponse` |
|
||
| **lib/api/** | `<domain>.ts ×7` | 语义化函数 API 层（v1.1） | `useMyChildren()` / `saveLessonPlan()` 等，禁止 widget 直接写 gql |
|
||
| **lib/api/** | `operations/*.graphql.ts` | gql DocumentNode 集中存放（v1.1） | 51 个 query/mutation 常量 |
|
||
| **lib/api/** | `operations/types.ts` | codegen 生成的 TS 类型（v1.1） | 从 7 子图 schema.graphql 生成 |
|
||
| **lib/api/** | `errors.ts` | ApiError 归一化（v1.1） | `toApiError(graphQLErrors)` 统一错误模型 |
|
||
| **providers/** | `ApolloProvider.tsx` | 注入 Apollo Client 单例 | `getApolloClient(readToken)` |
|
||
| **providers/** | `AuthProvider.tsx` | 提供 `useAuth()`，从 RSC props 下发用户身份 | `AuthUser` context |
|
||
| **providers/** | `ThemeI18nProvider.tsx` | 主题类名同步到 `<html>` + 简易 i18n | `usePluginStore` theme/locale |
|
||
| **widgets/** | `*/index.tsx` | 插件入口，接收 `PluginProps`，default export | `PluginProps` 契约 |
|
||
| **widgets/** | `*/plugin.manifest.ts` | 插件元数据声明 | `manifestMeta: Omit<PluginManifest, "Component">` |
|
||
|
||
### 5.3 Layout 模板清单
|
||
|
||
| layoutId | 显示名 | 布局 | 可用 slots | 适用场景 |
|
||
| --------- | -------- | ------------------------------------------------- | ---------------------------- | -------------- |
|
||
| `classic` | 经典三栏 | TopBar + SideNav + Main | top / side / main | 默认（仪表盘） |
|
||
| `focus` | 聚焦 | TopBar + 全宽 Main | top / main | 备课/编辑器 |
|
||
| `split` | 双栏 | TopBar + 左右等分 Main | top / main-left / main-right | 对比/批改 |
|
||
| `triple` | 三栏内容 | TopBar + SideNav + Main + RightRail | top / side / main / right | 数据分析 |
|
||
| `canvas` | 自由画布 | TopBar + 自由摆放（MVP 按 grid 排列，不实现拖拽） | top / canvas-grid | 个性化 |
|
||
|
||
### 5.4 三层配置模型
|
||
|
||
**优先级**：用户覆盖 > 角色模板 > 系统默认
|
||
|
||
```
|
||
Layer 1: 系统默认（plugin_registry 表）
|
||
← 开发者在 plugin.manifest.ts 声明 defaultProps
|
||
← 构建时由 sync-builtin-plugins.ts 同步到 DB
|
||
|
||
Layer 2: 角色模板（role_plugin_mapping 表）
|
||
← admin 通过 plugin-manager 插件配置角色可用插件集 + 角色级 props
|
||
|
||
Layer 3: 用户覆盖（user_layout_override 表）
|
||
← 用户切换 Layout、调整插件位置、隐藏插件、调整 props
|
||
← 仅限角色可用集内操作
|
||
```
|
||
|
||
**Props 合并算法**（`PropsMerger.mergeProps`）：
|
||
|
||
- 普通对象递归合并（深合并）
|
||
- 数组、原始值后者覆盖前者
|
||
- `null` / `undefined` 跳过
|
||
|
||
---
|
||
|
||
## 6. 插件目录与分类
|
||
|
||
### 6.1 内置插件全览（31 个）
|
||
|
||
| 分类 | 数量 | 插入 slot | 跨角色 | 插件清单 |
|
||
| ----------- | ---- | --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `universal` | 7 | main-* | 是 | grades-widget / homework-widget / schedule-widget / attendance-widget / exams-widget / notifications-widget / announcements-widget |
|
||
| `sidebar` | 4 | side | 部分 | class-selector / child-selector / term-switcher / quick-actions |
|
||
| `topbar` | 4 | top | 是 | notification-bell / user-menu / global-search / locale-switcher |
|
||
| `teacher` | 4 | main | 否 | lesson-plan-editor / question-bank / textbook-manager / scheduling-rules |
|
||
| `student` | 4 | main | 否 | error-book / learning-path / elective-selector / ai-tutor |
|
||
| `parent` | 2 | main | 否 | child-overview / leave-approval |
|
||
| `admin` | 6 | main | 否 | user-management / rbac-manager / plugin-manager / school-settings / audit-logs / invitation-codes |
|
||
|
||
### 6.2 插件契约（PluginProps）
|
||
|
||
```typescript
|
||
interface PluginProps<TProps = Record<string, unknown>> {
|
||
instanceId: string; // 插件实例 ID（同插件多实例时区分）
|
||
role: "admin" | "teacher" | "student" | "parent";
|
||
user: {
|
||
id: string;
|
||
name: string;
|
||
email: string;
|
||
dataScope: string; // IAM DataScope 6 级
|
||
};
|
||
slot: {
|
||
name: string; // 'main' | 'side' | 'top' | 'main-left' | ...
|
||
layoutId: string; // 'classic' | 'focus' | ...
|
||
size?: { colSpan: number; rowSpan: number };
|
||
};
|
||
props: TProps; // 三层合并后的最终 props
|
||
initialData?: unknown; // RSC 服务端预取的初始数据
|
||
}
|
||
```
|
||
|
||
### 6.3 插件 Manifest 契约
|
||
|
||
每个插件通过 `plugin.manifest.ts` 声明元数据：
|
||
|
||
```typescript
|
||
export const manifestMeta: Omit<PluginManifest, "Component"> = {
|
||
pluginId: "grades-widget",
|
||
version: "0.1.0",
|
||
requiredShellVersion: "^1.0.0", // semver range，Shell 启动时校验
|
||
metadata: {
|
||
displayName: "成绩",
|
||
description: "查看班级成绩",
|
||
category: "universal",
|
||
requiredRoles: ["teacher", "student", "parent"],
|
||
defaultSlot: "main",
|
||
defaultSize: { colSpan: 2, rowSpan: 1 },
|
||
defaultProps: { limit: 20 },
|
||
propsSchema: {
|
||
// JSON Schema，admin 配置面板自动渲染表单
|
||
type: "object",
|
||
properties: {
|
||
limit: { type: "number", description: "显示条数" },
|
||
},
|
||
},
|
||
},
|
||
};
|
||
```
|
||
|
||
### 6.4 插件生命周期
|
||
|
||
| 阶段 | 内置插件 | 第三方插件（二期） |
|
||
| ------------- | ------------------------------ | ------------------------------------- |
|
||
| `registered` | 编译时登记到 Registry | 安装时登记到 DB（plugin_packages 表） |
|
||
| `enabled` | admin 通过 config-service 启用 | admin 启用 |
|
||
| `loaded` | dynamic import 加载 | iframe + postMessage 沙箱加载 |
|
||
| `active` | 渲染并挂载 | 渲染并挂载 |
|
||
| `disabled` | admin 禁用，不渲染 | admin 禁用，不渲染 |
|
||
| `uninstalled` | 不可卸载（内置） | admin 卸载，删除包 |
|
||
|
||
---
|
||
|
||
## 7. 运行时视图（关键场景）
|
||
|
||
### 7.1 场景一：首屏加载（RSC 服务端预取）
|
||
|
||
**目标**：消除 CSR 瀑布流，实现仪表盘"秒开"
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as 用户浏览器
|
||
participant N as Next.js RSC
|
||
participant R as apollo-router
|
||
participant C as config-service
|
||
participant S as 业务子图
|
||
|
||
U->>N: GET /shell
|
||
N->>N: headers() 读取 x-user-id / x-user-role
|
||
N->>R: query pluginConfig(userId, role)
|
||
R->>C: 路由到 config-service 子图
|
||
C-->>R: 三层合并后的 PluginConfigResponse
|
||
R-->>N: Config（activeLayout + plugins[]）
|
||
N->>N: PropsMerger 解析 propsJson / sizeJson
|
||
N->>R: 并发预取各插件 initialData（Promise.all）
|
||
R->>S: 路由到对应子图
|
||
S-->>R: 插件初始数据
|
||
R-->>N: initialData[]
|
||
N-->>U: HTML 直出（含 Config + initialData）
|
||
U->>U: 水合 → dynamic import 插件组件
|
||
U->>U: 插件用 initialData 作为 SWR fallbackData 渲染
|
||
```
|
||
|
||
**对比 v2.0 CSR 瀑布流**：
|
||
|
||
```
|
||
v2.0（4 层串行，LCP 差）：
|
||
HTML 骨架 → 水合 → 拉 Config → import 插件 → 插件拉数据 → 渲染
|
||
总耗时 = SSR + 水合 + Config RTT + import RTT + BFF RTT
|
||
|
||
v2.1 RSC 预取（2 层并行，LCP 秒开）：
|
||
服务端：RSC 拉 Config + 并发预取 initialData → HTML 直出
|
||
客户端：水合 → dynamic import → 用 initialData 渲染
|
||
总耗时 = max(Config RTT, BFF RTT) + 水合 + import RTT
|
||
```
|
||
|
||
### 7.2 场景二：配置变更生效（SWR 静默刷新）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant A as Admin
|
||
participant PM as plugin-manager 插件
|
||
participant R as apollo-router
|
||
participant C as config-service
|
||
participant U as 用户浏览器
|
||
participant SWR as SWR 缓存
|
||
|
||
A->>PM: 修改角色插件映射
|
||
PM->>R: mutation updateRolePluginMapping
|
||
R->>C: 路由到 config-service
|
||
C-->>R: 更新成功
|
||
R-->>PM: 返回结果
|
||
|
||
Note over U,SWR: 用户侧（异步感知）
|
||
U->>U: 切回 Tab（revalidateOnFocus）<br/>或 5 分钟轮询触发
|
||
SWR->>R: query pluginConfig(userId, role)
|
||
R->>C: 路由到 config-service
|
||
C-->>R: 新配置
|
||
R-->>SWR: 返回新配置
|
||
SWR->>SWR: hasConfigChanged(prev, next) 检测变化
|
||
SWR->>U: 回调 onChanged → Toast 提示
|
||
U->>U: 用户点击"刷新" → window.location.reload()
|
||
U->>N: 重新走 RSC 预取流程，加载新配置
|
||
```
|
||
|
||
### 7.3 场景三：跨插件状态共享（URL 驱动）
|
||
|
||
**示例**：class-selector 切换班级 → grades-widget 自动响应
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant CS as class-selector 插件
|
||
participant URL as URL Search Params
|
||
participant GW as grades-widget 插件
|
||
participant R as apollo-router
|
||
|
||
CS->>CS: 用户选择班级 "三年二班"
|
||
CS->>URL: router.push('?classId=cls-123')
|
||
Note over URL: URL 变更触发 React 重渲染
|
||
URL->>GW: useSearchParams() 返回新 classId
|
||
GW->>GW: useWidgetQuery(GET_GRADES, { classId })
|
||
GW->>R: query grades(classId: "cls-123")
|
||
R-->>GW: 返回成绩数据
|
||
GW->>GW: 重新渲染表格
|
||
```
|
||
|
||
**收益**：
|
||
|
||
- 无 EventBus 发布订阅黑盒
|
||
- URL 可分享（用户可复制链接定位特定班级视图）
|
||
- 浏览器前进后退天然支持
|
||
- React DevTools 可追踪状态变更
|
||
|
||
### 7.4 场景四：插件加载失败（ErrorBoundary 隔离）
|
||
|
||
```mermaid
|
||
graph TB
|
||
A[SlotRenderer 渲染插件] --> B{dynamic import 成功?}
|
||
B -- 是 --> C[组件渲染]
|
||
B -- 否 --> D[PluginErrorBoundary 捕获]
|
||
D --> E[PluginErrorFallback 显示]
|
||
E --> F[显示错误图标 + instanceId]
|
||
E --> G[重试按钮]
|
||
G --> H[重置 hasError=false 重新加载]
|
||
|
||
I[其他插件] -.->|不受影响| J[正常渲染]
|
||
```
|
||
|
||
**关键约束**：单个插件失败不影响其他插件，ErrorBoundary 隔离作用域。
|
||
|
||
---
|
||
|
||
## 8. 部署视图
|
||
|
||
### 8.1 容器化
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph Build["构建阶段"]
|
||
Src["源码 apps/portal-shell/"]
|
||
Docker["Dockerfile<br/>multi-stage"]
|
||
Img["本地镜像<br/>（不推送 registry）"]
|
||
end
|
||
|
||
subgraph Runtime["运行时（Docker Compose）"]
|
||
Container["portal-shell 容器 :4010"]
|
||
Next["Next.js standalone server"]
|
||
end
|
||
|
||
subgraph Deps["依赖容器"]
|
||
Gateway["api-gateway :8080"]
|
||
Router["apollo-router :3000"]
|
||
Realtime["realtime-gateway :8081"]
|
||
end
|
||
|
||
Src --> Docker
|
||
Docker --> Img
|
||
Img --> Container
|
||
Container --> Next
|
||
Next -->|HTTP /api/v1/*| Gateway
|
||
Next -->|GraphQL| Router
|
||
Next -->|SSE| Realtime
|
||
```
|
||
|
||
### 8.2 Dockerfile 要点
|
||
|
||
- **基础镜像**：`node:22-alpine`（CI 预拉，见 `infra/docker-compose.tools.yml`）
|
||
- **构建模式**：`output: "standalone"`（Next.js 内置，自动追踪依赖，产物在 `.next/standalone/`）
|
||
- **多阶段构建**：`deps` → `builder` → `runner`
|
||
- **依赖处理**：
|
||
- `COPY tsconfig.base.json*` 确保 TS 类型解析
|
||
- `transpilePackages: ["@edu/ui-components", "@edu/ui-tokens", "@edu/hooks", "@edu/shared-ts"]` 编译 workspace 包
|
||
- `pnpm install --no-frozen-lockfile` 解决 workspace 符号链接问题
|
||
- **端口**：4010
|
||
- **健康检查**：`/api/health`（liveness）+ `/api/ready`（readiness）
|
||
|
||
### 8.3 环境变量
|
||
|
||
| 变量 | 用途 | 默认值 |
|
||
| ------------------------------- | ------------------------------------------------------- | ------------------------------- |
|
||
| `NEXT_PUBLIC_APOLLO_ROUTER_URL` | apollo-router GraphQL 端点（客户端） | `http://localhost:3000/graphql` |
|
||
| `APOLLO_ROUTER_URL` | apollo-router GraphQL 端点（服务端 RSC） | 同上 |
|
||
| `API_GATEWAY_URL` | api-gateway 反向代理目标 | `http://localhost:8080` |
|
||
| `CONFIG_SERVICE_URL` | 开发态降级：直连 config-service GraphQL（生产不应设置） | 未设置 |
|
||
| `NEXT_PUBLIC_DEV_MODE` | 开发模式：绕过 JWT，接受 `dev-token` + 预定义角色 | `false` |
|
||
|
||
### 8.4 CI/CD
|
||
|
||
- **流水线**：`.github/workflows/ci.yml` 的 `quality-ts` job
|
||
- **触发**：分支 push / PR（质量检查）、合并到 main（部署）
|
||
- **质量门禁**：`pnpm lint` + `tsc --noEmit` + `vitest run` + `next build`
|
||
- **部署**：`docker compose up -d --build`（no-push 本地构建模式，见 project_rules §15）
|
||
- **回滚**：`git revert + push` 或 `workflow_dispatch` 指定 `commit_sha`
|
||
|
||
---
|
||
|
||
## 9. 横切概念
|
||
|
||
### 9.1 设计令牌（强制）
|
||
|
||
**三层令牌模型**（project_rules §3.10）：
|
||
|
||
| Layer | 用途 | 位置 | 业务代码引用 |
|
||
| ----------------- | ----------------------- | ------------------------------------------- | ---------------------------------- |
|
||
| L1 Primitive | 原始色板/字号/间距/阴影 | `packages/ui-tokens/src/primitive.css` | ❌ 禁止直接引用 |
|
||
| L2 Semantic | 语义令牌（light/dark） | `packages/ui-tokens/src/semantic-*.css` | ✅ 唯一引用入口（`hsl(var(--*))`） |
|
||
| L3 Tailwind Theme | 暴露为 Tailwind 类 | `packages/ui-tokens/src/tailwind-theme.css` | ✅ `bg-*` / `text-*` / `font-*` |
|
||
|
||
**ESLint 强制约束**：
|
||
|
||
- `no-restricted-syntax`：禁止 `#hex` 字面量
|
||
- `design-tokens/no-hardcoded-fonts`：禁止 `'Inter'` / `'Fraunces'` 字面量
|
||
- 白名单：`primitive.css`、`email-channel`、`manifest.ts`
|
||
|
||
**portal-shell 落地**：
|
||
|
||
- 字体通过 `next/font/google` self-host，CSS 变量暴露为 `--font-inter` / `--font-fraunces` / `--font-jetbrains-mono`
|
||
- 所有插件使用 Tailwind 类（`bg-surface` / `text-ink` / `border-rule` / `rounded-card` 等）
|
||
- `tailwind.config.js` 映射 semantic 令牌到 Tailwind 类
|
||
|
||
### 9.2 字体策略
|
||
|
||
| 字体族 | 用途 | CSS 变量 | Tailwind 类 |
|
||
| -------------- | --------------------- | --------------------- | ------------ |
|
||
| Inter | UI 文本（sans-serif） | `--font-family-sans` | `font-sans` |
|
||
| Fraunces | 主标题/正文（serif） | `--font-family-serif` | `font-serif` |
|
||
| JetBrains Mono | 代码/等宽 | `--font-family-mono` | `font-mono` |
|
||
|
||
### 9.3 纸感编辑器设计风格
|
||
|
||
参考 `docs/standards/ui-design-system.md`：
|
||
|
||
- **背景**：纸感 `hsl(var(--paper))` / `hsl(var(--surface))`
|
||
- **圆角**：`var(--radius-card)` / `var(--radius-button)`
|
||
- **间距**：`var(--space-xs)` ~ `var(--space-xl)`
|
||
- **插件容器**：`<section className="rounded-card border border-rule bg-surface p-md">`
|
||
- **插件标题**：`text-heading-3 text-ink`
|
||
- **加载态**：`<PluginSkeleton variant="card|list|chart|stats|table" />`
|
||
- **错误态**：`<PluginErrorFallback instanceId={...} onRetry={...} />`
|
||
|
||
### 9.4 可观测性
|
||
|
||
| 维度 | 实现 | 端点 |
|
||
| -------- | --------------------------------------------------------- | ---------------------------------- |
|
||
| 健康检查 | liveness + readiness | `/api/health` + `/api/ready` |
|
||
| 错误日志 | `console.error` + `PluginErrorBoundary componentDidCatch` | 浏览器控制台 |
|
||
| 性能 | Next.js 内置 Web Vitals（可接 OTel） | Next.js 自动采集 |
|
||
| 请求追踪 | Apollo Client 自动携带 traceparent | 经 api-gateway 注入 `X-Request-Id` |
|
||
|
||
### 9.5 国际化（MVP）
|
||
|
||
- **locale 管理**：`PluginStore.locale`（`zh-CN` / `en`）
|
||
- **locale 切换**：`locale-switcher` 插件（topbar）
|
||
- **翻译函数**：`useT()` 从 `ThemeI18nProvider` 导出
|
||
- **翻译范围**：MVP 仅覆盖 Shell 框架文案（toggleSidebar / layout / empty），插件文案暂硬编码中文（二期接 next-intl）
|
||
|
||
### 9.6 安全
|
||
|
||
| 维度 | 实现 |
|
||
| -------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||
| JWT 注入 | Apollo Client `setContext` 从 localStorage 读取，注入 `Authorization: Bearer` |
|
||
| Cookie | `credentials: "include"` 携带 httpOnly cookie |
|
||
| XSS 防护 | React 自动转义 + 禁止 `dangerouslySetInnerHTML` |
|
||
| CSRF | 依赖 SameSite=Strict cookie（api-gateway 配置） |
|
||
| 开发模式 | `NEXT_PUBLIC_DEV_MODE=true` 绕过 JWT，仅本地开发 |
|
||
| **APQ（v1.1）** | `createPersistedQueryLink({ sha256 })` 前端只发 query hash，env `NEXT_PUBLIC_APOLLO_APQ=false` 关闭 |
|
||
| **PQ Manifest（v1.1）** | `public/pq-manifest.json` 51 query 的 `sha256 → query` 白名单，由 `scripts/generate-pq-manifest.ts` 生成 |
|
||
| **Router 强制 manifest（v1.1）** | `APOLLO_REQUIRE_PQ_MANIFEST=true` 时 router 拒绝未知 hash，entrypoint.sh 启动前校验文件存在性 |
|
||
| **深度/成本/批量限制（v1.1）** | apollo-router `limits.max_depth=10` / `max_cost=1000` / `max_batch_size=5` |
|
||
| **Introspection 控制（v1.1）** | `APOLLO_ROUTER_INTROSPECTION=false` 生产关闭 schema 内省 |
|
||
| **Router-Authorization（v1.1）** | 子图 `RouterAuthGuard` 校验 header，拒绝非 Router 的直接 GraphQL 请求 |
|
||
| **Resolver 字段级权限（v1.1）** | 每个 GraphQL Resolver 必须用 `@RequirePermission('perm')` 声明权限点 |
|
||
|
||
---
|
||
|
||
## 10. 架构决策记录（ADR 索引）
|
||
|
||
portal-shell 的关键架构决策记录在 004 文档的 ADR 章节，此处为索引：
|
||
|
||
| ADR | 决策 | 状态 | 关联 |
|
||
| ------- | ------------------------------------------------------- | --------- | ------- |
|
||
| ADR-033 | portal-shell 单容器 Modular Monolith 替代 4 portal + MF | ✅ 已落地 | M8-M10 |
|
||
| ADR-023 | apollo-router 替代 3 BFF 手写聚合 | ✅ 已落地 | M2/M9 |
|
||
| ADR-026 | config-service 从 iam 拆分，三层配置合并 | ✅ 已落地 | M3 |
|
||
| ADR-029 | SSE 优先替代 WebSocket 单向推送 | ✅ 已落地 | M7 |
|
||
| ADR-034 | Redis Pub/Sub 作为推送背板 | ✅ 已落地 | M7 |
|
||
| ADR-036 | Router-Authorization 信任凭证 | ✅ 已落地 | M1 |
|
||
| ADR-041 | ScopeToken 优化大规模 ID 列表 | ✅ 已落地 | M4 |
|
||
| ADR-042 | portal-shell 前端数据访问四层分层（2026-07-17） | ✅ 已落地 | v1.1 M1 |
|
||
| ADR-043 | PQ Manifest + APQ 安全加固（2026-07-17） | ✅ 已落地 | v1.1 M3 |
|
||
|
||
### 10.1 模块级决策（未单独编号）
|
||
|
||
| 决策 | 理由 |
|
||
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||
| **dynamic import 替代 Module Federation** | 单体部署，无运行时远程加载，研发与运维复杂度最低 |
|
||
| **URL Search Params + Zustand 替代 EventBus** | 数据流向清晰、支持 React DevTools、URL 可分享、浏览器前进后退天然支持 |
|
||
| **SWR 静默刷新替代 Kafka+WebSocket 推送** | 低频布局变更无需实时推送，SWR 5 分钟轮询 + 切回 Tab 触发足够 |
|
||
| **RSC 服务端预取替代客户端拉取** | 消除 4 层 CSR 瀑布流，HTML 直出 Config + initialData，LCP 秒开 |
|
||
| **三层 props 合并（系统 < 角色 < 用户）** | 配置驱动可见性，admin 改配置无需重新部署 |
|
||
| **编译时 Registry + 运行时 Config 分离** | Registry 是静态映射（plugin_id → lazy 组件），Config 是动态配置（DB 三层合并） |
|
||
| **ErrorBoundary 隔离单插件失败** | 单个插件加载/渲染失败不影响其他插件 |
|
||
| **MVP 不实现第三方插件沙箱** | 单体应用直接 script 注入不信任代码等于交出主站权限，二期用 iframe + postMessage |
|
||
| **4 层数据访问分层（v1.1）** | Widget 内联 gql 字面量暴露 schema、难审计、难重构；抽取到 lib/api/ 四层架构集中管理（ADR-042） |
|
||
| **APQ + PQ Manifest（v1.1）** | 前端只发 query hash 防止 schema 探测；Router 白名单 manifest 拒绝未知 hash 任意查询（ADR-043） |
|
||
| **Router 深度/成本/批量限制（v1.1）** | 防止深度嵌套 / 高成本 / 批量查询 DoS，配置 max_depth=10 / max_cost=1000 / max_batch_size=5 |
|
||
| **Resolver 字段级 @RequirePermission（v1.1）** | 防止越权访问字段，每个 Resolver 必须声明权限点；50 resolver 审计后补齐 19 个 TS 守卫 |
|
||
|
||
---
|
||
|
||
## 11. 质量要求与验收
|
||
|
||
### 11.1 功能验收
|
||
|
||
- [x] 5 种 Layout 模板可切换，slot 正确渲染
|
||
- [x] 31 个内置插件全部加载正常（7 universal + 4 sidebar + 4 topbar + 4 teacher + 4 student + 2 parent + 6 admin）
|
||
- [x] admin 可通过 plugin-manager 插件配置角色插件集合（registry / mapping / layout / user 四 Tab）
|
||
- [x] admin 可配置角色默认 Layout 模板
|
||
- [x] admin 可配置插件默认 props（JSON 编辑）
|
||
- [x] admin 可重置用户自定义布局
|
||
- [x] admin 改配置 → SWR 静默刷新检测到变化 → Toast 提示用户刷新生效
|
||
- [x] 插件加载失败显示错误兜底，不影响其他插件（PluginErrorBoundary）
|
||
- [x] 跨插件状态共享正常（class-selector 切换班级 → grades-widget 自动响应）
|
||
- [x] 插件 props 三层合并正确（PropsMerger）
|
||
- [x] RSC 服务端预取正常：首屏 HTML 直出 Config + initialData
|
||
- [x] useWidgetQuery 自动经 Apollo Client 路由到 apollo-router
|
||
- [x] URL Search Params 可分享、可前进后退
|
||
- [x] config-fetcher 三级降级：apollo-router → config-service 直连 → 空默认
|
||
|
||
### 11.2 非功能验收
|
||
|
||
- [x] `pnpm run lint` + `pnpm run typecheck` 零错误
|
||
- [x] `pnpm run test` 95/95 通过（v1.1：lib/api 7 domain 55 用例 + 安全栈 10 用例 + Shell/Lifecycle/Context 30 用例）
|
||
- [x] 0 处 widget 内联 gql 字面量（v1.1 强制，arch:scan 违规检测）
|
||
- [x] 所有插件遵守设计令牌（ESLint 强制，无硬编码颜色/字体）
|
||
- [x] apollo-router 启用 APQ + PQ Manifest + 深度/成本/批量限制（v1.1）
|
||
- [x] 50 个 GraphQL resolver @auth 审计完成（35 TS + 15 Python），19 个 TS resolver 补齐 @RequirePermission（v1.1）
|
||
- [x] arch.db 更新，004 文档同步
|
||
- [ ] Shell 首屏 LCP < 2s（需真实环境压测验证）
|
||
- [ ] 插件加载耗时 < 500ms（dynamic import 缓存命中后，需真实环境验证）
|
||
- [ ] 单元测试覆盖率 ≥ 80%（当前覆盖核心纯函数 + lib/api 全量，admin domain 仅 4 用例待补，插件组件测试待补）
|
||
- [ ] E2E 测试（tests/e2e/portal-shell.spec.ts，待补）
|
||
- [ ] 视觉回归测试（5 种 layout 截图，待补）
|
||
- [ ] 生产部署前 APOLLO_REQUIRE_PQ_MANIFEST=true + APOLLO_ROUTER_INTROSPECTION=false 写入部署 env（v1.1 follow-up）
|
||
|
||
### 11.3 测试矩阵
|
||
|
||
| 测试类型 | 范围 | 文件 | 状态 |
|
||
| -------- | ------------------------------------------- | --------------------------------------------- | ----------------------- |
|
||
| 单元测试 | PluginLifecycle 纯函数 | `src/shell/__tests__/PluginLifecycle.test.ts` | ✅ 12 用例 |
|
||
| 单元测试 | Registry 插件注册 | `src/shell/__tests__/Registry.test.ts` | ✅ 6 用例 |
|
||
| 单元测试 | plugin-context URL 上下文 | `src/lib/__tests__/plugin-context.test.ts` | ✅ 12 用例 |
|
||
| 单元测试 | lib/api universal domain | `src/lib/api/__tests__/universal.test.ts` | ✅ 6 用例（v1.1） |
|
||
| 单元测试 | lib/api sidebar domain | `src/lib/api/__tests__/sidebar.test.tsx` | ✅ 9 用例（v1.1） |
|
||
| 单元测试 | lib/api topbar domain | `src/lib/api/__tests__/topbar.test.tsx` | ✅ 9 用例（v1.1） |
|
||
| 单元测试 | lib/api teacher domain | `src/lib/api/__tests__/teacher.test.tsx` | ✅ 7 用例（v1.1） |
|
||
| 单元测试 | lib/api student domain | `src/lib/api/__tests__/student.test.tsx` | ✅ 9 用例（v1.1） |
|
||
| 单元测试 | lib/api parent domain | `src/lib/api/__tests__/parent.test.tsx` | ✅ 11 用例（v1.1） |
|
||
| 单元测试 | lib/api admin domain | `src/lib/api/__tests__/admin.test.tsx` | ✅ 4 用例（v1.1，待补） |
|
||
| 单元测试 | PQ Manifest + APQ + 深度限制 | `src/lib/api/__tests__/security.test.ts` | ✅ 10 用例（v1.1） |
|
||
| 单元测试 | PropsMerger 三层合并 | 待补 | 🚧 |
|
||
| 单元测试 | 各插件组件渲染 | 待补 | 🚧 |
|
||
| E2E | 登录 → 加载 layout → 渲染插件 → 切换 layout | `tests/e2e/portal-shell.spec.ts` | ⏳ |
|
||
| E2E | admin 改配置 → 用户刷新生效 | `tests/e2e/plugin-config.spec.ts` | ⏳ |
|
||
| E2E | apollo-router 拒绝 11 层嵌套查询 | `tests/e2e/graphql-depth-limit.spec.ts` | ⏳（v1.1） |
|
||
| E2E | apollo-router 拒绝未知 PQ hash | `tests/e2e/graphql-pq-manifest.spec.ts` | ⏳（v1.1） |
|
||
| 视觉回归 | 5 种 layout 截图对比 | `tests/visual/portal-shell.spec.ts` | ⏳ |
|
||
|
||
---
|
||
|
||
## 12. 风险、技术债与演进路线
|
||
|
||
### 12.1 风险与缓解
|
||
|
||
| 风险 | 影响 | 缓解措施 |
|
||
| -------------------------------- | -------------------- | ---------------------------------------------------------------------------------- |
|
||
| 插件数量增长导致首屏 bundle 过大 | 首屏加载慢 | dynamic import 按需加载 + IntersectionObserver 滚动加载 + 首屏只加载可见 slot |
|
||
| 单体架构插件间隐式耦合 | 维护困难 | ESLint 禁止跨 widgets 目录 import + arch:scan 违规检测 + 强制 URL/Zustand 共享状态 |
|
||
| 单角色专属功能受 props 契约约束 | 复杂功能实现受限 | PluginProps 设计灵活（initialData + props 任意 JSON）；复杂功能在插件内部自行组织 |
|
||
| config-service 配置查询压力 | RSC 每次请求查询多表 | 复用 config-service Redis 缓存 + RSC `cache()` 去重 + SWR 客户端轮询自然刷新 |
|
||
| 插件 props 三层合并逻辑复杂 | props 不一致 | PropsMerger 集中实现 + 单元测试覆盖（待补） |
|
||
| admin 配置面板 propsSchema 复杂 | 表单体验差 | MVP 用 JSON textarea 编辑，二期接 react-jsonschema-form |
|
||
| 二期第三方插件沙箱 | 安全风险 | iframe + postMessage（最安全），禁止 same-origin，BFF 请求由 Shell 代理 |
|
||
|
||
### 12.2 技术债
|
||
|
||
| # | 技术债 | 优先级 | 计划 |
|
||
| ---- | ---------------------------------------------------------------------------- | ------ | ------------------------------------------------- |
|
||
| TD-1 | PluginLifecycle 版本校验仅 major，未引入 semver 库 | 低 | MVP 够用，二期按需引入 `semver` |
|
||
| TD-2 | ThemeI18nProvider 仅覆盖 Shell 框架文案，插件文案硬编码中文 | 中 | 二期接 next-intl，提取到 messages/{en,zh-CN}.json |
|
||
| TD-3 | PropsMerger 单元测试待补 | 中 | 补充深合并 + 数组覆盖 + null 跳过用例 |
|
||
| TD-4 | 插件组件单元测试待补（仅 Registry 与 Lifecycle 有测试） | 中 | 补充各插件渲染 + loading + error 用例 |
|
||
| TD-5 | E2E 测试与视觉回归测试待补 | 高 | 接 Playwright + 5 种 layout 截图 |
|
||
| TD-6 | `prefetchPluginData` 服务端并发预取未实现（仅拉 Config，未预取 initialData） | 中 | RSC 中按 pluginId 分发预取，传入 fallbackData |
|
||
| TD-7 | canvas layout 仅按 grid 排列，未实现拖拽 | 低 | MVP 预留接口，二期按需实现 |
|
||
| TD-8 | 第三方插件沙箱未实现 | 低 | 二期 iframe + postMessage |
|
||
|
||
### 12.3 演进路线
|
||
|
||
| 阶段 | 内容 | 状态 |
|
||
| ---------- | -------------------------------------------------------- | --------------------- |
|
||
| M8 | portal-shell 接入 apollo-router（RSC 预取 Config） | ✅ 完成 |
|
||
| M9 | 旧 BFF 下线（teacher/student/parent-bff） | ✅ 完成 |
|
||
| M10 | 旧 portal 下线（teacher/student/parent/admin-portal） | ✅ 完成 |
|
||
| v1.1 M1 | lib/api 四层架构 + 31 widget 迁移 | ✅ 完成（2026-07-17） |
|
||
| v1.1 M3 | GraphQL 安全加固（APQ + PQ Manifest + router limits） | ✅ 完成（2026-07-17） |
|
||
| v1.1 M4 | Resolver @RequirePermission 审计 + 补齐 | ✅ 完成（2026-07-17） |
|
||
| v1.1 FU-1 | 4 个 TS 子图 AuthMiddleware 覆盖 /graphql 路径 | ⏳ Follow-up |
|
||
| v1.1 FU-2 | Python 子图（data-ana/ai）补 @RequirePermission 基础设施 | ⏳ Follow-up |
|
||
| v1.1 FU-3 | admin domain 测试用例补齐（当前仅 4 用例） | ⏳ Follow-up |
|
||
| P1（二期） | 第三方插件上传 + iframe 沙箱 | ⏳ 规划 |
|
||
| P2（二期） | 插件市场在线商店 | ⏳ 规划 |
|
||
| P3（二期） | canvas 拖拽编辑器 | ⏳ 规划 |
|
||
| P4（二期） | next-intl 完整 i18n | ⏳ 规划 |
|
||
| P5（二期） | 视觉回归测试自动化 | ⏳ 规划 |
|
||
|
||
---
|
||
|
||
## 13. 数据访问层与 GraphQL 安全栈（v1.1 新增）
|
||
|
||
> 来源：[portal-shell 数据抽象与 GraphQL 加固 spec](../../docs/superpowers/specs/2026-07-17-portal-shell-data-abstraction-and-graphql-hardening-design.md) v1.0
|
||
> 关联 ADR：ADR-042（前端数据访问四层分层）、ADR-043（PQ Manifest + APQ 安全加固）
|
||
> 关联 004：§11.7 portal-shell 前端数据访问层 + GraphQL 安全栈
|
||
|
||
### 13.1 问题背景
|
||
|
||
v1.0 portal-shell 的 widget 直接内联 `gql\`...\`` 字面量查询，存在三个核心问题：
|
||
|
||
1. **Schema 泄露**：前端 bundle 包含明文 GraphQL 查询，攻击者可通过 DevTools 构造任意查询探测 schema
|
||
2. **查询碎片化**：31 个 widget 各自维护 gql 字符串，难审计、难重构、难统一优化
|
||
3. **缺抽象**：widget 直接 import Apollo hooks，业务逻辑与传输层耦合
|
||
|
||
### 13.2 解决方案：4 层数据访问分层（ADR-042）
|
||
|
||
```mermaid
|
||
graph TD
|
||
subgraph Widget["Widget 层（UI）"]
|
||
W[widgets/*.tsx<br/>只关心渲染]
|
||
end
|
||
subgraph API["API 层（语义化函数）"]
|
||
A1[lib/api/parent.ts]
|
||
A2[lib/api/teacher.ts]
|
||
A3[lib/api/admin.ts]
|
||
A4[lib/api/student.ts]
|
||
A5[lib/api/universal.ts]
|
||
A6[lib/api/sidebar.ts]
|
||
A7[lib/api/topbar.ts]
|
||
end
|
||
subgraph Ops["Operations 层（gql 文档集中）"]
|
||
O[lib/api/operations/*.graphql.ts<br/>51 个 DocumentNode 常量]
|
||
end
|
||
subgraph Hook["Hook 层（Apollo 封装）"]
|
||
H1[useWidgetQuery]
|
||
H2[useWidgetMutation]
|
||
end
|
||
subgraph Codegen["类型生成"]
|
||
C[graphql-codegen<br/>7 子图 schema.graphql → types.ts]
|
||
end
|
||
W --> A1 & A2 & A3 & A4 & A5 & A6 & A7
|
||
A1 & A2 & A3 & A4 & A5 & A6 & A7 --> O
|
||
A1 & A2 & A3 & A4 & A5 & A6 & A7 --> H1 & H2
|
||
O --> C
|
||
```
|
||
|
||
**层职责矩阵**：
|
||
|
||
| 层 | 位置 | 职责 | 禁止 |
|
||
| ---------- | --------------------------------------------- | ------------------------------------------------------- | ----------------------------------------- |
|
||
| Widget | `src/widgets/*.tsx` | UI 渲染、用户交互 | 内联 gql 字面量、直接 import Apollo hooks |
|
||
| API | `src/lib/api/<domain>.ts` | 语义化函数（`useMyChildren()` / `saveLessonPlan()` 等） | 写 gql 字符串、直接操作 Apollo cache |
|
||
| Operations | `src/lib/api/operations/*.graphql.ts` | gql DocumentNode 常量集中存放（51 个 query/mutation） | 包含业务逻辑 |
|
||
| Hook | `src/lib/useWidgetQuery/useWidgetMutation.ts` | Apollo useQuery/useMutation 封装 + ApiError 归一化 | 引用具体 domain |
|
||
|
||
**7 个 domain API 文件**：
|
||
|
||
| 文件 | Widget 数 | 主要场景 |
|
||
| -------------- | --------- | ---------------------------------------------------------------------------------- |
|
||
| `universal.ts` | 7 | 公告 / 通知 / 课表 / 作业 / 考试 / 成绩 / 考勤（多角色复用） |
|
||
| `sidebar.ts` | 3 | 当前用户 / 我的班级 / 学期列表（侧边栏） |
|
||
| `topbar.ts` | 2 | 搜索 / 通知铃铛（顶栏，`useNotificationBell` 限 N 条） |
|
||
| `teacher.ts` | 5 | 教材 / 教案 / 题目 / 课表规则 / 教案保存 / 课表更新 |
|
||
| `student.ts` | 5 | AI Tutor / 选修课 / 错题本 / 学习路径 / 错题掌握标记 |
|
||
| `parent.ts` | 3 | 我的子女 / 请假审批 / 请假驳回 |
|
||
| `admin.ts` | 11 | 用户 / 角色 / 权限 / 学校 / 插件注册 / 角色插件映射 / 布局模板 / 邀请码 / 审计日志 |
|
||
|
||
**类型生成（graphql-codegen）**：
|
||
|
||
- 配置：`apps/portal-shell/codegen.yml`
|
||
- schema 来源：7 个子图的 `services/<svc>/src/graphql/generated/schema.graphql`
|
||
- 生成产物：`src/lib/api/operations/types.ts`（仅类型，无运行时代码）
|
||
- 关键配置：`skipDocumentsValidation: true`（避免子图未启动时 codegen 失败）
|
||
- schema 归一化：`scripts/normalize-schema.ts` 移除 federation 指令（`@key` / `@requires` / `@extends`）防止 codegen 误解析
|
||
|
||
### 13.3 GraphQL 安全栈（ADR-043）
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph FE["portal-shell（前端）"]
|
||
APQ[createPersistedQueryLink<br/>sha256 query → hash]
|
||
end
|
||
subgraph Router["apollo-router :3000"]
|
||
Manifest[pq-manifest.json<br/>hash → query 白名单]
|
||
Limits[limits.max_depth=10<br/>max_cost=1000<br/>max_batch_size=5]
|
||
Intro[introspection<br/>环境变量控制]
|
||
end
|
||
subgraph Sub["子图 /graphql"]
|
||
Guard[RouterAuthGuard<br/>+ @RequirePermission]
|
||
end
|
||
APQ -->|只发 hash| Manifest
|
||
Manifest -->|未知 hash 拒绝| APQ
|
||
Manifest --> Limits
|
||
Limits --> Intro
|
||
Intro --> Guard
|
||
```
|
||
|
||
**安全机制矩阵**：
|
||
|
||
| 机制 | 位置 | 防御目标 | 配置 |
|
||
| ---------------------------------- | -------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------- |
|
||
| APQ（Automatic Persisted Queries） | `apps/portal-shell/src/lib/apollo-client.ts` | 前端只发 query hash，不发明文 query | `createPersistedQueryLink({ sha256 })`，env `NEXT_PUBLIC_APOLLO_APQ=false` 关闭 |
|
||
| PQ Manifest | `apps/portal-shell/public/pq-manifest.json` | Router 仅解析白名单 hash，拒绝未知 hash 任意查询 | 51 个 query 的 `sha256 → query` 映射，由 `scripts/generate-pq-manifest.ts` 生成 |
|
||
| Router 强制 manifest | `infra/apollo-router/router.yaml` | 生产模式（`require_manifest: true`）拒绝未注册查询 | env `APOLLO_REQUIRE_PQ_MANIFEST=true`，entrypoint.sh 启动前检查文件存在性 |
|
||
| 深度限制 | `router.yaml` `limits.max_depth=10` | 防止深度嵌套查询 DoS | 11 层嵌套被 router 拒绝（`QUERY_DEPTH_EXCEEDED`） |
|
||
| 成本限制 | `router.yaml` `limits.max_cost=1000` | 防止高成本查询 DoS | 按字段复杂度评分累加 |
|
||
| 批量限制 | `router.yaml` `limits.max_batch_size=5` | 防止批量查询 DoS | 单次请求最多 5 个 query |
|
||
| Introspection 控制 | `router.yaml` `supergraph.introspection` | 生产关闭 introspection 防止 schema 泄露 | env `APOLLO_ROUTER_INTROSPECTION=false`（开发默认 true） |
|
||
| Router-Authorization 信任 | 子图 `RouterAuthGuard`（见 §5.5） | 防止绕过 Router 直接访问子图 | 子图校验 `Router-Authorization` header，拒绝非 Router 请求（ADR-036） |
|
||
| Resolver 字段级权限 | 子图 `@RequirePermission()` 装饰器 | 防止越权访问字段 | 每个 Resolver 必须声明权限点（见 §3.8） |
|
||
|
||
### 13.4 PQ Manifest 生成流程
|
||
|
||
1. `pnpm --filter @edu/portal-shell run codegen` → 从 7 子图 schema 生成 TS 类型
|
||
2. `pnpm --filter @edu/portal-shell run generate-pq-manifest` → 遍历 `lib/api/operations/index.ts` 中所有 DocumentNode，`print(doc)` 后 `sha256(query)` 生成映射，写入 `public/pq-manifest.json`
|
||
3. `prebuild` 钩子自动串联 codegen + generate-pq-manifest
|
||
4. Docker compose 挂载 `pq-manifest.json` 到 apollo-router `/etc/apollo-router/pq-manifest.json:ro`
|
||
5. apollo-router entrypoint.sh 启动前校验 manifest 存在性（`require_manifest=true` 时缺失即 exit 1）
|
||
|
||
### 13.5 Resolver @RequirePermission 审计（M4）
|
||
|
||
> 详见：[docs/security/graphql-auth-audit-2026-07.md](../../docs/security/graphql-auth-audit-2026-07.md)
|
||
|
||
**已审计范围**：50 个 resolver（35 TS + 15 Python）
|
||
|
||
| 状态 | 数量 | 说明 |
|
||
| ------------------------- | ---- | -------------------------------------------------------------------------------------- |
|
||
| 已有 `@RequirePermission` | 37 | 18 原有 + 19 M4 补齐 |
|
||
| 缺失守卫 | 13 | 4 个 TS（`/graphql` 路径未覆盖，由 RouterAuthGuard 兜底）+ 9 个 Python（待补基础设施） |
|
||
|
||
**Follow-up（不阻断 M3 验收）**：
|
||
|
||
- 4 个 TS 子图（iam / core-edu / content / msg）的 `AuthMiddleware` 仅覆盖 REST 路径，未覆盖 `/graphql`（由 `RouterAuthGuard` 兜底，仍建议补齐字段级守卫）
|
||
- Python 子图（data-ana / ai）缺 `@RequirePermission` 基础设施，需补 Strawberry / Ariadne 中间件
|
||
|
||
### 13.6 常用命令
|
||
|
||
```bash
|
||
# 类型生成（从 7 子图 schema 生成 TS 类型）
|
||
pnpm --filter @edu/portal-shell run codegen
|
||
|
||
# PQ Manifest 生成
|
||
pnpm --filter @edu/portal-shell run generate-pq-manifest
|
||
|
||
# 生产构建（prebuild 自动串联 codegen + generate-pq-manifest）
|
||
pnpm --filter @edu/portal-shell run build
|
||
|
||
# 验证 0 处内联 gql 字面量
|
||
pnpm --filter @edu/portal-shell run lint
|
||
|
||
# 安全栈测试
|
||
npx vitest run src/lib/api/__tests__/security.test.ts
|
||
```
|
||
|
||
---
|
||
|
||
## 14. 术语表
|
||
|
||
| 术语 | 定义 |
|
||
| ------------------------------ | --------------------------------------------------------------------------------------------------- |
|
||
| **Shell** | 微内核宿主，渲染 Layout 框架 + Slots + PluginLoader，不含业务逻辑 |
|
||
| **Registry** | 编译时登记的插件清单，`plugin_id → dynamic import 组件` 静态映射 |
|
||
| **Config** | 运行时配置 JSON，决定当前用户在哪些 Slots 渲染哪些插件（DB 三层合并） |
|
||
| **PluginProps** | 插件契约，Shell 与插件之间的唯一交互接口 |
|
||
| **Slot** | Layout 模板预定义的插件放置区域（top / side / main / main-left / main-right / right / canvas-grid） |
|
||
| **Layout 模板** | 5 种内置布局（classic / focus / split / triple / canvas） |
|
||
| **三层配置** | 系统默认（plugin_registry） < 角色模板（role_plugin_mapping） < 用户覆盖（user_layout_override） |
|
||
| **三层 props 合并** | 系统默认 defaultProps < 角色默认 widgetProps < 用户调整 plugin_placements[].props |
|
||
| **RSC** | React Server Component，Next.js App Router 的服务端组件，可异步获取数据 |
|
||
| **dynamic import** | `next/dynamic` 懒加载，`ssr: false` 仅客户端渲染 |
|
||
| **SWR** | stale-while-revalidate 数据请求库，支持静默后台刷新 |
|
||
| **Zustand** | React 全局状态管理库，替代 EventBus |
|
||
| **apollo-router** | Apollo Federation 聚合层，替代 3 BFF 手写聚合 |
|
||
| **config-service** | 从 iam 拆分的配置服务，管理插件配置 + 布局 + 用户偏好 |
|
||
| **DataScope** | IAM 6 级数据范围（school / grade / class / subject / student / self） |
|
||
| **ScopeToken** | 大规模 ID 列表的轻量令牌（Redis 存储），替代 GraphQL 联邦全数组传递 |
|
||
| **Modular Monolith** | 单体应用 + 模块化组织，介于单进程与微服务之间 |
|
||
| **Micro-kernel** | 微内核架构，核心仅含基础框架，功能以插件形式扩展 |
|
||
| **APQ**（v1.1） | Automatic Persisted Queries，前端只发 query hash（sha256），不发明文 query |
|
||
| **PQ Manifest**（v1.1） | sha256(query) → query 文本的白名单 JSON，apollo-router 据此解析未知 hash |
|
||
| **4 层数据访问分层**（v1.1） | Widget → API → Operations → Hook，废弃 widget 内联 gql 字面量（ADR-042） |
|
||
| **@RequirePermission**（v1.1） | NestJS GraphQL Resolver 字段级权限装饰器，每个 Resolver 必须声明权限点 |
|
||
| **RouterAuthGuard**（v1.1） | 子图 Guard，校验 `Router-Authorization` header，拒绝非 Router 的直接 GraphQL 请求 |
|
||
|
||
---
|
||
|
||
## 附录 A：文件清单
|
||
|
||
```
|
||
apps/portal-shell/
|
||
├─ src/
|
||
│ ├─ app/
|
||
│ │ ├─ api/
|
||
│ │ │ ├─ health/route.ts # liveness
|
||
│ │ │ └─ ready/route.ts # readiness
|
||
│ │ ├─ shell/[[...route]]/page.tsx # RSC 入口
|
||
│ │ ├─ globals.css # 全局样式 + Tailwind
|
||
│ │ ├─ layout.tsx # RootLayout + 字体
|
||
│ │ └─ page.tsx # 重定向 /shell
|
||
│ ├─ lib/
|
||
│ │ ├─ __tests__/plugin-context.test.ts
|
||
│ │ ├─ api/ # v1.1 数据访问层
|
||
│ │ │ ├─ __tests__/
|
||
│ │ │ │ ├─ admin.test.tsx # 4 用例（待补）
|
||
│ │ │ │ ├─ parent.test.tsx # 11 用例
|
||
│ │ │ │ ├─ security.test.ts # 10 用例（PQ Manifest + APQ + 深度限制）
|
||
│ │ │ │ ├─ sidebar.test.tsx # 9 用例
|
||
│ │ │ │ ├─ student.test.tsx # 9 用例
|
||
│ │ │ │ ├─ teacher.test.tsx # 7 用例
|
||
│ │ │ │ ├─ topbar.test.tsx # 9 用例
|
||
│ │ │ │ └─ universal.test.ts # 6 用例
|
||
│ │ │ ├─ operations/
|
||
│ │ │ │ ├─ *.graphql.ts # 51 个 DocumentNode 常量
|
||
│ │ │ │ ├─ index.ts # barrel
|
||
│ │ │ │ └─ types.ts # codegen 生成
|
||
│ │ │ ├─ admin.ts # 11 widget API
|
||
│ │ │ ├─ errors.ts # ApiError 归一化
|
||
│ │ │ ├─ internal.ts # 内部工具
|
||
│ │ │ ├─ parent.ts # 3 widget API
|
||
│ │ │ ├─ sidebar.ts # 3 widget API
|
||
│ │ │ ├─ student.ts # 5 widget API
|
||
│ │ │ ├─ teacher.ts # 5 widget API
|
||
│ │ │ ├─ topbar.ts # 2 widget API
|
||
│ │ │ ├─ types.ts # 共享类型
|
||
│ │ │ └─ universal.ts # 7 widget API
|
||
│ │ ├─ apollo-client.ts # Apollo Client 工厂 + 单例 + APQ 链
|
||
│ │ ├─ config-fetcher.ts # RSC 服务端拉 Config（三级降级）
|
||
│ │ ├─ types.ts # 共享类型契约
|
||
│ │ ├─ usePluginConfig.ts # SWR 静默刷新
|
||
│ │ ├─ useWidgetQuery.ts # 统一查询 Hook
|
||
│ │ └─ useWidgetMutation.ts # 统一变更 Hook
|
||
│ ├─ providers/
|
||
│ │ ├─ ApolloProvider.tsx
|
||
│ │ ├─ AuthProvider.tsx
|
||
│ │ └─ ThemeI18nProvider.tsx
|
||
│ ├─ shell/
|
||
│ │ ├─ __tests__/
|
||
│ │ │ ├─ PluginLifecycle.test.ts # 12 用例
|
||
│ │ │ └─ Registry.test.ts # 6 用例
|
||
│ │ ├─ ClientShell.tsx # 客户端入口
|
||
│ │ ├─ LayoutManager.tsx # 5 Layout 模板
|
||
│ │ ├─ PluginLifecycle.ts # 生命周期管理
|
||
│ │ ├─ PluginLoader.tsx # 骨架 + ErrorBoundary
|
||
│ │ ├─ PluginStore.ts # Zustand 全局状态
|
||
│ │ ├─ PropsMerger.ts # 三层合并
|
||
│ │ ├─ Registry.tsx # 31 插件注册表
|
||
│ │ ├─ Shell.tsx # 微内核入口
|
||
│ │ └─ SlotRenderer.tsx # slot 渲染器
|
||
│ ├─ styles/
|
||
│ │ └─ tokens.css # 设计令牌映射
|
||
│ └─ widgets/
|
||
│ ├─ admin/ # 6 插件
|
||
│ │ ├─ audit-logs/
|
||
│ │ ├─ invitation-codes/
|
||
│ │ ├─ plugin-manager/
|
||
│ │ ├─ rbac-manager/
|
||
│ │ ├─ school-settings/
|
||
│ │ └─ user-management/
|
||
│ ├─ parent/ # 2 插件
|
||
│ │ ├─ child-overview/
|
||
│ │ └─ leave-approval/
|
||
│ ├─ sidebar/ # 4 插件
|
||
│ │ ├─ child-selector/
|
||
│ │ ├─ class-selector/
|
||
│ │ ├─ quick-actions/
|
||
│ │ └─ term-switcher/
|
||
│ ├─ student/ # 4 插件
|
||
│ │ ├─ ai-tutor/
|
||
│ │ ├─ elective-selector/
|
||
│ │ ├─ error-book/
|
||
│ │ └─ learning-path/
|
||
│ ├─ teacher/ # 4 插件
|
||
│ │ ├─ lesson-plan-editor/
|
||
│ │ ├─ question-bank/
|
||
│ │ ├─ scheduling-rules/
|
||
│ │ └─ textbook-manager/
|
||
│ ├─ topbar/ # 4 插件
|
||
│ │ ├─ global-search/
|
||
│ │ ├─ locale-switcher/
|
||
│ │ ├─ notification-bell/
|
||
│ │ └─ user-menu/
|
||
│ └─ universal/ # 7 插件
|
||
│ ├─ announcements-widget/
|
||
│ ├─ attendance-widget/
|
||
│ ├─ exams-widget/
|
||
│ ├─ grades-widget/
|
||
│ ├─ homework-widget/
|
||
│ ├─ notifications-widget/
|
||
│ └─ schedule-widget/
|
||
├─ .env.example
|
||
├─ .eslintrc.tokens.js # 设计令牌 ESLint 规则
|
||
├─ codegen.yml # v1.1 graphql-codegen 配置
|
||
├─ Dockerfile # standalone 构建
|
||
├─ eslint.config.js
|
||
├─ next.config.js # transpilePackages + 反向代理
|
||
├─ package.json
|
||
├─ postcss.config.js
|
||
├─ public/
|
||
│ └─ pq-manifest.json # v1.1 PQ Manifest（51 query hash → query 白名单）
|
||
├─ scripts/
|
||
│ ├─ generate-pq-manifest.ts # v1.1 PQ Manifest 生成脚本
|
||
│ └─ normalize-schema.ts # v1.1 schema 归一化（移除 federation 指令）
|
||
├─ tailwind.config.js
|
||
├─ tsconfig.json # paths 别名
|
||
├─ vitest.config.ts # jsdom + 别名
|
||
└─ README.md # 本文件
|
||
```
|
||
|
||
## 附录 B：常用命令
|
||
|
||
```bash
|
||
# 开发
|
||
pnpm --filter @edu/portal-shell run dev # 启动 dev server :4010
|
||
pnpm --filter @edu/portal-shell run build # 生产构建（prebuild 自动 codegen + generate-pq-manifest）
|
||
pnpm --filter @edu/portal-shell run start # 生产启动
|
||
|
||
# 质量校验
|
||
pnpm --filter @edu/portal-shell run lint # ESLint
|
||
pnpm --filter @edu/portal-shell run lint:tokens # 设计令牌专项
|
||
pnpm --filter @edu/portal-shell run typecheck # tsc --noEmit
|
||
pnpm --filter @edu/portal-shell run test # vitest run（95 用例）
|
||
|
||
# v1.1 数据层与安全栈
|
||
pnpm --filter @edu/portal-shell run codegen # graphql-codegen 生成 TS 类型
|
||
pnpm --filter @edu/portal-shell run generate-pq-manifest # 生成 public/pq-manifest.json
|
||
npx vitest run src/lib/api/__tests__/security.test.ts # 安全栈测试（10 用例）
|
||
|
||
# 架构扫描
|
||
pnpm run arch:scan # 更新 arch.db
|
||
pnpm run arch:query -- module-deps # 查模块依赖
|
||
```
|
||
|
||
## 附录 C：关联文档索引
|
||
|
||
| 文档 | 用途 |
|
||
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
|
||
| [004 架构影响地图](../../docs/architecture/004_architecture_impact_map.md) | 架构设计意图唯一源（§11.7 数据访问层 + 安全栈、§16.5 子阶段） |
|
||
| [portal-shell 仪表盘 spec](../../docs/superpowers/specs/2026-07-14-portal-shell-widget-dashboard-design.md) | 模块设计源（v1.0） |
|
||
| [portal-shell 数据抽象与 GraphQL 加固 spec](../../docs/superpowers/specs/2026-07-17-portal-shell-data-abstraction-and-graphql-hardening-design.md) | v1.1 数据访问层 + 安全栈设计源 |
|
||
| [portal-shell 数据抽象与 GraphQL 加固 plan](../../docs/superpowers/plans/2026-07-17-portal-shell-data-abstraction-and-graphql-hardening.md) | v1.1 20-task 实施 plan |
|
||
| [GraphQL @auth 审计报告](../../docs/security/graphql-auth-audit-2026-07.md) | 50 resolver @auth 审计（M4） |
|
||
| [项目规则](../../.trae/rules/project_rules.md) | 强制约束 |
|
||
| [UI 设计系统](../../docs/standards/ui-design-system.md) | 纸感编辑器设计风格 |
|
||
| [known-issues §1.11/§2.17](../../docs/troubleshooting/known-issues.md) | Apollo Router + portal-shell 已知问题速查 |
|
||
| [local-stack runbook](../../docs/runbooks/local-stack.md) | 本地运维手册 |
|
||
| [端口分配](../../infra/port-allocation.md) | 端口唯一源 |
|
||
|
||
---
|
||
|
||
> **本文件是 portal-shell 模块的架构文档（v1.1，2026-07-17），遵循 arc42 模板结构 + C4 模型可视化。后续代码变更须按 [项目规则 §1](../../.trae/rules/project_rules.md) 同步更新本文件 + 运行 `pnpm run arch:scan` 更新 arch.db。**
|