Edu/apps/portal-shell

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 架构影响地图 §1.2/§3/§4/§11.7/§16
• portal-shell 仪表盘 spec v2.1
• portal-shell 数据抽象与 GraphQL 加固 spec v1.0
• 项目规则 §3.10 设计令牌、§14 多 AI 协作
• UI 设计系统
• known-issues §1.11/§2.17
• GraphQL @auth 审计报告

---

目录

1. 引言与目标
2. 架构约束
3. 系统范围与上下文（C4 L1）
4. 解决方案策略
5. 构建块视图（C4 L2/L3）
6. 插件目录与分类
7. 运行时视图（关键场景）
8. 部署视图
9. 横切概念
10. 架构决策记录（ADR 索引）
11. 质量要求与验收
12. 风险、技术债与演进路线
13. 数据访问层与 GraphQL 安全栈（v1.1 新增）
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 图

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）

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）

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 声明元数据：

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 瀑布流，实现仪表盘"秒开"

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 静默刷新）

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 自动响应

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 隔离）

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 容器化

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 功能验收

• 5 种 Layout 模板可切换，slot 正确渲染
• 31 个内置插件全部加载正常（7 universal + 4 sidebar + 4 topbar + 4 teacher + 4 student + 2 parent + 6 admin）
• admin 可通过 plugin-manager 插件配置角色插件集合（registry / mapping / layout / user 四 Tab）
• admin 可配置角色默认 Layout 模板
• admin 可配置插件默认 props（JSON 编辑）
• admin 可重置用户自定义布局
• admin 改配置 → SWR 静默刷新检测到变化 → Toast 提示用户刷新生效
• 插件加载失败显示错误兜底，不影响其他插件（PluginErrorBoundary）
• 跨插件状态共享正常（class-selector 切换班级 → grades-widget 自动响应）
• 插件 props 三层合并正确（PropsMerger）
• RSC 服务端预取正常：首屏 HTML 直出 Config + initialData
• useWidgetQuery 自动经 Apollo Client 路由到 apollo-router
• URL Search Params 可分享、可前进后退
• config-fetcher 三级降级：apollo-router → config-service 直连 → 空默认

11.2 非功能验收

• pnpm run lint + pnpm run typecheck 零错误
• pnpm run test 95/95 通过（v1.1：lib/api 7 domain 55 用例 + 安全栈 10 用例 + Shell/Lifecycle/Context 30 用例）
• 0 处 widget 内联 gql 字面量（v1.1 强制，arch:scan 违规检测）
• 所有插件遵守设计令牌（ESLint 强制，无硬编码颜色/字体）
• apollo-router 启用 APQ + PQ Manifest + 深度/成本/批量限制（v1.1）
• 50 个 GraphQL resolver @auth 审计完成（35 TS + 15 Python），19 个 TS resolver 补齐 @RequirePermission（v1.1）
• 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 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）

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）

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

已审计范围：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 常用命令

# 类型生成（从 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：常用命令

# 开发
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 架构影响地图	架构设计意图唯一源（§11.7 数据访问层 + 安全栈、§16.5 子阶段）
portal-shell 仪表盘 spec	模块设计源（v1.0）
portal-shell 数据抽象与 GraphQL 加固 spec	v1.1 数据访问层 + 安全栈设计源
portal-shell 数据抽象与 GraphQL 加固 plan	v1.1 20-task 实施 plan
GraphQL @auth 审计报告	50 resolver @auth 审计（M4）
项目规则	强制约束
UI 设计系统	纸感编辑器设计风格
known-issues §1.11/§2.17	Apollo Router + portal-shell 已知问题速查
local-stack runbook	本地运维手册
端口分配	端口唯一源

---

本文件是 portal-shell 模块的架构文档（v1.1，2026-07-17），遵循 arc42 模板结构 + C4 模型可视化。后续代码变更须按 项目规则 §1 同步更新本文件 + 运行 pnpm run arch:scan 更新 arch.db。