# Portal Shell 插件化仪表盘设计（Modular Monolith + Micro-kernel）

> 版本：v2.1（应用 React 单体哲学优化：URL 状态 + RSC 预取 + SWR 刷新 + 统一 Hook + 沙箱防御）
> 日期：2026-07-14
> 状态：待评审
> 关联：
>
> - [0010 架构蓝图](../../architecture/0010_architecture.md) §4 微前端
> - [004 架构影响地图](../../architecture/004_architecture_impact_map.md)
> - [UI 设计系统](../../standards/ui-design-system.md)
> - CICD 参考：`e:\Desktop\CICD\src\modules\dashboard\config\widget-configs.ts`
> - Halo 插件机制参考：JAR 分发 · 扩展点注入 · 完整生命周期

---

## 1. 背景与目标

### 1.1 问题诊断

当前 Edu 前端由 4 个独立 Next.js portal 组成（teacher / student / parent / admin），存在以下问题：

1. **拆分粒度错误**：后端按"领域"拆微服务，前端按"角色"拆 4 个粗 portal，边界不对齐
2. **重复度高**：4 套独立 Dockerfile、i18n、auth-provider、layout、design tokens
3. **复用性差**：跨角色复用功能（grades / homework / schedule）在 4 个 portal 各实现一遍
4. **耦合度高**：每个 portal 既当 Shell 又内置业务，职责混淆
5. **配置驱动缺失**：角色变更需改 4 个 portal 代码，无法后台动态配置
6. **扩展性差**：新增功能需修改多个 portal，无法像 Halo 那样插件化扩展

### 1.2 方向选择

抛弃 v1.0 的 Module Federation 微前端方案（7 个独立 widget 容器、运行时远程加载、部署运维复杂），采用 **Modular Monolith + Micro-kernel** 架构：

- **单 Next.js 项目**，单服务部署，单 Dockerfile
- **dynamic import 懒加载**，插件按需加载
- **前端 Registry + 后端 JSON Config**，配置驱动渲染
- **插件即卡片**，统一术语，MVP 内置插件，二期支持第三方上传（参考 Halo）

### 1.3 设计目标

1. **页面框架可配置**：TopBar + SideNav + ContentArea 三 region，预置 5 种内置 Layout 模板，admin 配置角色默认，用户可切换
2. **插件即卡片**：所有功能单元统一为"插件"（含单角色专属功能如备课画布、错题本），分类管理，admin 可启用/禁用/配置
3. **配置驱动可见性**：admin 改配置 → 用户刷新生效，无需重新部署
4. **声明式 props**：插件通过 manifest 声明 propsSchema，admin 配置默认 props，用户可调整，三层合并
5. **强隔离**：插件间禁止直接 import，仅通过 EventBus 通信；插件与 Shell 仅通过 PluginProps 契约交互
6. **设计系统一致**：所有插件强制遵守纸感编辑器设计风格，使用 @edu/ui-tokens
7. **单服务部署**：一个 Dockerfile，一个容器，无 MF 远程加载

### 1.4 非目标

- 不重写后端微服务、BFF、网关
- 不替换现有 4 个 portal（并行运行，逐步迁移）
- 不实现插件拖拽编辑器（canvas 模板预留接口，但不做拖拽实现）
- MVP 不实现第三方插件上传（二期，预留接口与 UI 入口）
- 不实现插件市场在线商店（二期仅支持本地 ZIP 上传）

---

## 2. 整体架构

### 2.1 Modular Monolith + Micro-kernel

```
┌──────────────────────────────────────────────────────────────┐
│  apps/portal-shell/（单 Next.js App Router · 单 Docker）      │
│                                                               │
│  src/app/shell/[[...route]]/page.tsx   ← RSC（Server Component）│
│    ① 服务端调 IAM gRPC 获取 PluginConfigResponse              │
│    ② 服务端并发调 BFF 预取各插件 initialData（Promise.all）   │
│    ③ 三层 props 合并（PropsMerger）                           │
│    ④ 将 Config + initialData 作为 props 传给 Client Shell     │
│                                                               │
│  src/shell/（Client Component）             ← 微内核           │
│    Shell.tsx           Layout 框架 + Slots                    │
│    Registry.ts         插件清单（plugin_id → lazy）           │
│    PluginLoader.tsx    dynamic import + ssr:false + 骨架屏    │
│    SlotRenderer.tsx    按 Config 渲染插件列表（含 initialData）│
│    PropsMerger.ts      三层 props 合并                        │
│    PluginStore.ts      Zustand 全局状态（theme/locale/sidebar）│
│                                                               │
│  src/widgets/                               ← 内置插件源码    │
│    universal/  sidebar/  topbar/                              │
│    teacher/    student/    parent/    admin/                  │
│                                                               │
│  src/lib/                                   ← 数据请求抽象    │
│    useWidgetQuery.ts   统一 BFF GraphQL 查询（自动按 role 路由）│
│    useWidgetMutation.ts 统一 BFF GraphQL 变更                 │
│    usePluginConfig.ts  SWR 静默刷新配置（revalidateOnFocus）  │
│                                                               │
└──────────────────────────────────────────────────────────────┘
        ↕ RSC 服务端预取（消除 CSR 瀑布流）↕
┌──────────────────────────────────────────────────────────────┐
│  IAM DB（配置存储）                                           │
│    plugin_registry / role_plugin_mapping / user_layout_override│
│    layout_templates / plugin_packages（二期）                 │
└──────────────────────────────────────────────────────────────┘
        ↕ RSC 服务端并发预取 initialData ↕
┌──────────────────────────────────────────────────────────────┐
│  BFF 层（已就绪，无需改动）                                   │
│   teacher-bff / student-bff / parent-bff                     │
│   useWidgetQuery 自动按 role 路由到对应 BFF                   │
└──────────────────────────────────────────────────────────────┘
```

### 2.2 核心三元组：Shell + Registry + Config

| 组件         | 职责                                                                       | 位置                    | 时机       |
| ------------ | -------------------------------------------------------------------------- | ----------------------- | ---------- |
| **Shell**    | 微内核，渲染 Layout 框架 + Slots + ConfigProvider + PluginLoader，不含业务 | `src/shell/`            | 运行时     |
| **Registry** | 插件清单，`plugin_id → dynamic import 组件`映射。内置插件编译时登记        | `src/shell/Registry.ts` | 编译时     |
| **Config**   | 渲染配置 JSON，决定当前用户在哪些 Slots 渲染哪些插件。三层合并             | IAM DB                  | 运行时拉取 |

### 2.3 关键设计原则

1. **Shell 是纯宿主**：只负责 Layout / Config / Registry / Loader，不含任何业务逻辑
2. **插件即卡片**：所有功能单元统一为"插件"，无"卡片"与"插件"之分。含单角色专属功能（备课画布、错题本等）
3. **RSC 服务端预取**：Shell 在 RSC（Server Component）中直接调 IAM gRPC 获取 Config，按需并发调 BFF 预取插件初始数据，Config + initialData 随 HTML 直出，客户端水合后 dynamic import 加载插件组件（initialData 已在 HTML 中），消除 CSR 瀑布流，实现仪表盘"秒开"
4. **dynamic import 懒加载**：插件按需加载，首屏只加载可见 slot 的插件，非可见插件滚动到视口再加载
5. **强隔离**：插件间禁止直接 import，通过 URL Search Params + Zustand Store 共享状态；插件与 Shell 仅通过 PluginProps 契约交互
6. **配置驱动**：admin 改配置 → SWR 静默后台刷新（revalidateOnFocus + refreshInterval）→ Toast 提示用户刷新，无需重新部署（内置插件增删仍需重新构建）
7. **单服务部署**：一个 Dockerfile，一个容器，无 MF 远程加载，无独立 widget 容器

---

## 3. 插件目录分类

内置插件源码按**用途分类**组织在 `src/widgets/<category>/` 下：

```
src/widgets/
├─ universal/                    # 通用插件（跨角色复用，按角色渲染不同视图）
│  ├─ grades-widget/
│  │  ├─ index.tsx               # 插件入口（接收 PluginProps）
│  │  ├─ plugin.manifest.ts      # 插件元数据（id/分类/版本/slot/size/propsSchema）
│  │  ├─ TeacherView.tsx         # 教师视图
│  │  ├─ StudentView.tsx         # 学生视图
│  │  ├─ ParentView.tsx          # 家长视图
│  │  └─ __tests__/
│  ├─ homework-widget/
│  ├─ schedule-widget/
│  ├─ attendance-widget/
│  ├─ exams-widget/
│  ├─ notifications-widget/
│  └─ announcements-widget/
│
├─ sidebar/                      # 侧栏插件（插入 SideNav slot）
│  ├─ class-selector/            # 班级选择器（教师）
│  ├─ child-selector/            # 孩子选择器（家长）
│  ├─ term-switcher/             # 学期切换
│  └─ quick-actions/             # 快捷操作
│
├─ topbar/                       # 顶栏插件（插入 TopBar slot）
│  ├─ global-search/             # 全局搜索
│  ├─ notification-bell/         # 通知铃铛
│  ├─ user-menu/                 # 用户菜单
│  └─ locale-switcher/           # 语言切换
│
├─ teacher/                      # 教师专属插件（仅教师可见）
│  ├─ lesson-plan-editor/        # 备课画布（V4 锚点/inline-node）
│  ├─ question-bank/             # 题库管理
│  ├─ textbook-manager/          # 教材管理
│  └─ scheduling-rules/          # 排课规则
│
├─ student/                      # 学生专属插件
│  ├─ error-book/                # 错题本
│  ├─ learning-path/             # 学习路径
│  ├─ elective-selector/         # 选课
│  └─ ai-tutor/                  # AI 辅导
│
├─ parent/                       # 家长专属插件
│  ├─ child-overview/            # 多孩子总览
│  └─ leave-approval/            # 请假审批
│
└─ admin/                        # 管理员专属插件
   ├─ user-management/           # 用户管理
   ├─ rbac-manager/              # 角色权限
   ├─ school-settings/           # 学校设置
   ├─ audit-logs/                # 审计日志
   ├─ invitation-codes/          # 邀请码
   └─ plugin-manager/            # 插件管理（admin 配置面板本身也是插件）
```

| 分类        | 用途                         | 插入 slot | 跨角色 | 示例                               |
| ----------- | ---------------------------- | --------- | ------ | ---------------------------------- |
| `universal` | 通用功能，按角色渲染不同视图 | main-*    | 是     | grades / homework / schedule       |
| `sidebar`   | 侧栏功能（选择器/切换器）    | side      | 部分   | class-selector / term-switcher     |
| `topbar`    | 顶栏功能（搜索/通知/菜单）   | top       | 是     | global-search / notification-bell  |
| `teacher`   | 教师专属，不跨角色复用       | main-*    | 否     | lesson-plan-editor / question-bank |
| `student`   | 学生专属                     | main-*    | 否     | error-book / ai-tutor              |
| `parent`    | 家长专属                     | main-*    | 否     | child-overview / leave-approval    |
| `admin`     | 管理员专属                   | main-*    | 否     | user-management / plugin-manager   |

---

## 4. Layout + Slot 模型

### 4.1 5 种内置 Layout 模板

| 模板 ID   | 显示名   | 布局描述                            | 可用 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 + 自由摆放（拖拽预留）       | top / canvas-grid            | 个性化         |

### 4.2 Slot 系统

每个 Layout 模板预定义一组 slot，插件配置到 slot 中渲染：

- **top slot**：TopBar 区域，可插入多个 topbar 类插件（logo / search / notification-bell / user-menu / locale-switcher）
- **side slot**：SideNav 区域，可插入 sidebar 类插件（class-selector / term-switcher / 导航项）
- **main slot**：主内容区，可插入 universal / teacher / student / parent / admin 类插件
- **main-left / main-right slot**：split 模板的左右等分
- **right slot**：triple 模板的右侧栏
- **canvas-grid slot**：canvas 模板的自由摆放区（MVP 不实现拖拽，仅按 grid 排列）

### 4.3 三层配置模型

**优先级**：用户覆盖 > 角色模板 > 系统默认

#### Layer 1: 系统默认（plugin_registry 表）

- 插件元数据：id / 分类 / 版本 / 默认 slot / 默认 size / 默认 props
- 由开发者在 `plugin.manifest.ts` 声明，构建时同步到 DB

#### Layer 2: 角色模板（role_plugin_mapping 表）

- admin 配置：角色可用哪些插件、角色默认 Layout、角色级 props 默认值
- 如：教师角色启用 grades-widget + homework-widget，默认 classic 模板，grades-widget 默认显示本学期

#### Layer 3: 用户覆盖（user_layout_override 表）

- 用户自定义：切换 Layout 模板、调整插件位置、隐藏插件、调整插件 props
- 仅限角色可用集内操作

### 4.4 插件 props 三层合并

插件通过 `plugin.manifest.ts` 声明 `propsSchema`（JSON Schema），admin 配置面板自动渲染表单。

**props 合并优先级**：用户调整 > 角色默认 > 系统默认

- **系统默认**：开发者在 `plugin.manifest.ts` 的 `defaultProps` 声明，构建时由 `sync-builtin-plugins.ts` 脚本同步到 `plugin_registry.default_props` 字段。运行时 Shell 从 DB 读取（DB 是唯一源，避免 manifest 与 DB 不一致）。
- **角色默认**：admin 通过配置面板写入 `role_plugin_mapping.widget_props`。
- **用户调整**：用户在插件内调整，写入 `user_layout_override.plugin_placements[].props`。

```typescript
// PropsMerger 三层合并（深合并 + 数组覆盖）
const finalProps = deepMerge(
  registry.defaultProps, // 系统默认（plugin_registry 表）
  roleMapping.widgetProps, // 角色默认（role_plugin_mapping 表）
  userPlacement.props, // 用户调整（user_layout_override 表）
);
```

---

## 5. 插件契约

### 5.1 PluginProps 契约

```typescript
// packages/shared-ts/src/contracts/plugin.ts

export interface PluginProps<TProps = Record<string, unknown>> {
  /** 插件实例 ID（同一插件多实例时区分） */
  instanceId: string;
  /** 当前用户角色 */
  role: "admin" | "teacher" | "student" | "parent";
  /** 当前用户信息（来自 IAM） */
  user: {
    id: string;
    name: string;
    email: string;
    dataScope: string;
  };
  /** 当前 slot 信息 */
  slot: {
    name: string; // 'main-top' | 'side' | 'top' | ...
    layoutId: string; // 'classic' | 'focus' | ...
    size?: { colSpan: number; rowSpan: number };
  };
  /** 插件自定义 props（三层合并后的最终值） */
  props: TProps;
  /** 服务端预取的初始数据（RSC 直出，避免客户端瀑布流） */
  initialData?: unknown;
}

// 注：跨插件状态不通过 props 传递，而是插件自行调用：
//   - useSearchParams() 读取 URL 上下文（classId/childId/termId/view）
//   - usePluginStore() 读取 Zustand 全局状态（theme/locale/sidebarCollapsed）
//   - useWidgetQuery() 读取 BFF 业务数据（自动按 role 路由）
// 这样插件无需接收 eventBus/ctx 等"注入"依赖，符合 React 函数式哲学

export interface PluginManifest {
  pluginId: string;
  version: string;
  /** 兼容的 Shell 版本范围（semver range，如 "^1.0.0"） */
  requiredShellVersion: string;
  /** React 组件（默认导出） */
  Component: React.ComponentType<PluginProps>;
  /** 插件元数据 */
  metadata: {
    displayName: string;
    description: string;
    category:
      | "universal"
      | "sidebar"
      | "topbar"
      | "teacher"
      | "student"
      | "parent"
      | "admin";
    requiredRoles: string[];
    defaultSlot: string;
    defaultSize: { colSpan: number; rowSpan: number };
    /** 插件可配置的 props schema（JSON Schema，用于 admin 配置面板自动渲染表单） */
    propsSchema?: JSONSchema;
    /** 系统默认 props（与 propsSchema 配合） */
    defaultProps?: Record<string, unknown>;
  };
}
```

### 5.2 跨插件状态管理（URL Params + Zustand）

抛弃 EventBus 发布订阅模式（微前端跨框架通信的无奈之举，在 React 单体中会导致"状态黑盒"、极难 Debug、不支持 React DevTools 追踪）。采用 React 单向数据流哲学：**URL 驱动 + Zustand 全局状态**。

#### 5.2.1 URL Search Params（高频/可分享上下文）

适合**需要 URL 分享、浏览器前进后退**的全局上下文：

```typescript
// packages/shared-ts/src/contracts/plugin-context.ts

/** URL 驱动的全局上下文（可分享、可前进后退） */
export interface UrlPluginContext {
  /** 当前选中的班级 ID（教师视角，class-selector 切换时更新 URL） */
  classId?: string;
  /** 当前选中的孩子 ID（家长视角） */
  childId?: string;
  /** 当前选中的学期 */
  termId?: string;
  /** 当前视图模式（如 grades-widget 的 'list' | 'chart'） */
  view?: string;
}

// 读取：useSearchParams()
// 写入：router.push('?classId=xxx')
// 响应：其他插件通过 useSearchParams() 自动响应，触发重新渲染
```

```typescript
// 示例：class-selector 插件切换班级
import { useRouter, useSearchParams } from "next/navigation";

export function ClassSelector() {
  const router = useRouter();
  const searchParams = useSearchParams();
  const currentClassId = searchParams.get("classId");

  const handleSelect = (classId: string) => {
    const params = new URLSearchParams(searchParams);
    params.set("classId", classId);
    router.push(`?${params.toString()}`);
    // grades-widget 等插件自动响应，无需 EventBus 广播
  };

  return <Select value={currentClassId} onSelect={handleSelect} />;
}

// 示例：grades-widget 插件响应班级切换
import { useSearchParams } from "next/navigation";

export function GradesWidget() {
  const classId = useSearchParams().get("classId");
  // classId 变化自动触发重新渲染和重新查询
  const { data } = useWidgetQuery(GET_GRADES, { classId });
  return <GradesTable data={data} />;
}
```

#### 5.2.2 Zustand Store（低频/不可分享状态）

适合**不需要 URL 分享、纯 UI 状态**的全局上下文：

```typescript
// packages/shared-ts/src/contracts/plugin-store.ts

import { create } from "zustand";

interface PluginStore {
  /** 主题模式（light/dark） */
  theme: "light" | "dark";
  setTheme: (theme: "light" | "dark") => void;

  /** i18n locale */
  locale: "zh-CN" | "en";
  setLocale: (locale: "zh-CN" | "en") => void;

  /** Sidebar 折叠状态 */
  sidebarCollapsed: boolean;
  toggleSidebar: () => void;

  /** 通知已读标记（纯 UI 状态，不进 URL） */
  unreadNotificationIds: string[];
  markNotificationsRead: (ids: string[]) => void;
}

export const usePluginStore = create<PluginStore>((set) => ({
  theme: "light",
  setTheme: (theme) => set({ theme }),
  locale: "zh-CN",
  setLocale: (locale) => set({ locale }),
  sidebarCollapsed: false,
  toggleSidebar: () => set((s) => ({ sidebarCollapsed: !s.sidebarCollapsed })),
  unreadNotificationIds: [],
  markNotificationsRead: (ids) =>
    set((s) => ({
      unreadNotificationIds: s.unreadNotificationIds.filter(
        (id) => !ids.includes(id),
      ),
    })),
}));
```

#### 5.2.3 URL vs Zustand 选型标准

| 状态类型           | 存储                           | 示例                              | 理由                                   |
| ------------------ | ------------------------------ | --------------------------------- | -------------------------------------- |
| 可分享、可前进后退 | URL Search Params              | classId / termId / view           | 用户可复制链接分享，浏览器前进后退生效 |
| 纯 UI、不可分享    | Zustand Store                  | theme / locale / sidebarCollapsed | 不需要 URL 体现，避免 URL 污染         |
| 插件内部私有       | 插件内部 useState / useReducer | 表单临时值、弹窗开关              | 最小作用域原则                         |

#### 5.2.4 弃用 EventBus 的收益

- ✅ 数据流向清晰：URL 是单一数据源，DevTools Network/URL 栏可见
- ✅ 支持 React DevTools 追踪：Zustand 状态可被 DevTools 检视
- ✅ 符合 React 单向数据流：状态变更 → 自动重渲染，无发布订阅黑盒
- ✅ URL 可分享：用户可分享带 classId 的链接，直接定位到特定班级视图
- ✅ 浏览器前进后退：URL 变更天然支持历史导航
- ✅ 减少 Debug 成本：无需维护事件名常量、订阅/取消订阅生命周期

### 5.3 插件加载与错误处理

- **加载态**：PluginLoader 显示 `<PluginSkeleton variant={slot.skeletonVariant} />`，骨架样式由 `@edu/ui-components` 提供
- **错误态**：插件加载失败时显示 `<PluginErrorFallback instanceId={instanceId} onRetry={...} />`，ErrorBoundary 隔离，单个插件失败不影响其他
- **超时**：dynamic import 超时 10s 后降级显示错误态
- **版本兼容**：插件 manifest 携带 `requiredShellVersion`，Shell 启动时校验，不兼容则拒绝加载并提示 admin 升级
- **懒加载**：首屏只加载可见 slot 的插件，非可见插件使用 IntersectionObserver 滚动到视口再加载

### 5.4 插件生命周期

| 阶段        | 内置插件              | 第三方插件（二期） |
| ----------- | --------------------- | ------------------ |
| registered  | 编译时登记到 Registry | 安装时登记到 DB    |
| enabled     | admin 启用            | admin 启用         |
| loaded      | dynamic import 加载   | script 注入加载    |
| active      | 渲染并挂载            | 渲染并挂载         |
| disabled    | admin 禁用，不渲染    | admin 禁用，不渲染 |
| uninstalled | 不可卸载（内置）      | admin 卸载，删除包 |

### 5.5 RSC 服务端预取流程（消除 CSR 瀑布流）

**v2.0 瀑布流问题**：Shell SSR 骨架 → 客户端水合 → 客户端拉 Config → 客户端 dynamic import 插件 → 插件拉 BFF 数据。4 层串行，LCP 差。

**v2.1 优化**：利用 Next.js App Router 的 Server Components，在服务端完成 Config 拉取 + initialData 预取，随 HTML 直出。

```typescript
// src/app/shell/[[...route]]/page.tsx（Server Component）
import { headers } from "next/headers";
import { iamClient } from "@/lib/iam-client";
import { bffClients } from "@/lib/bff-clients";
import { PropsMerger } from "@/shell/PropsMerger";
import ClientShell from "@/shell/ClientShell";

export default async function ShellPage() {
  // ① 从请求头获取 JWT，解析出 userId 和 role
  const headerList = headers();
  const userId = headerList.get("x-user-id")!;
  const role = headerList.get("x-user-role") as "admin" | "teacher" | "student" | "parent";

  // ② 服务端调 IAM gRPC 获取三层合并后的 PluginConfigResponse
  const config = await iamClient.getPluginConfig({ userId });

  // ③ 服务端并发预取各插件的 initialData
  const pluginsWithData = await Promise.all(
    config.plugins.map(async (placement) => {
      const initialData = await prefetchPluginData(placement, role, bffClients);
      return { ...placement, initialData };
    })
  );

  // ④ Config + initialData 作为 props 传给 Client Shell
  return <ClientShell config={{ ...config, plugins: pluginsWithData }} role={role} />;
}

/** 按插件类型预取初始数据（仅首屏可见插件） */
async function prefetchPluginData(placement, role, bffClients): Promise<unknown> {
  const bffClient = bffClients[role]; // 自动按 role 路由
  switch (placement.pluginId) {
    case "grades-widget":
      return bffClient.query(GET_GRADES, { classId: placement.props.classId });
    case "notifications-widget":
      return bffClient.query(GET_NOTIFICATIONS, { limit: 10 });
    // ... 其他插件
    default:
      return null;
  }
}
```

**数据流对比：**

```
v2.0 瀑布流（4 层串行，LCP 差）：
  HTML 骨架 → 水合 → 拉 Config → import 插件 → 插件拉数据 → 渲染
  [SSR]      [client] [client]    [client]     [client]    [client]
  ──────────┴────────┴───────────┴────────────┴───────────┴────────
  总耗时 = SSR + 水合 + Config RTT + import RTT + BFF RTT

v2.1 RSC 预取（2 层并行，LCP 秒开）：
  服务端：RSC 拉 Config + 并发预取 initialData → HTML 直出（含数据）
  客户端：水合 → dynamic import 插件组件 → 用 initialData 渲染
  [RSC 并行]                                      [client]
  ───────────────────────────────────────────────┴────────────────
  总耗时 = max(Config RTT, BFF RTT) + 水合 + import RTT
  （Config 和 BFF 在服务端并行，不阻塞客户端）
```

**约束：**

- `prefetchPluginData` 仅预取**首屏可见 slot** 的插件数据（非可见插件滚动到视口再加载）
- 插件组件仍用 `dynamic(() => import(...), { ssr: false })` 懒加载（避免插件 JS 阻塞首屏）
- 插件接收 `initialData` 作为 SWR/useWidgetQuery 的 `fallbackData`，首次渲染无需客户端请求
- 后续数据刷新（如手动刷新、轮询）仍走客户端 useWidgetQuery

### 5.6 统一 BFF 请求 Hook（Data Fetching Abstraction）

**痛点**：universal 分类插件（grades/homework/schedule 等）跨角色复用，如果每个插件自行判断角色并拼接 BFF URL，会导致大量重复样板代码。

**方案**：在 `src/lib/` 中封装统一的 `useWidgetQuery` 和 `useWidgetMutation`，内部自动读取 `AuthProvider` 中的 role，自动路由到对应 BFF。插件开发者只关心写 GraphQL 查询语句。

```typescript
// src/lib/useWidgetQuery.ts
import useSWR from "swr";
import { useAuth } from "@/providers/AuthProvider";

const BFF_ROUTE_MAP = {
  admin: "/api/admin-bff/graphql",
  teacher: "/api/teacher-bff/graphql",
  student: "/api/student-bff/graphql",
  parent: "/api/parent-bff/graphql",
} as const;

/**
 * 统一 BFF GraphQL 查询 Hook
 * 自动按当前用户 role 路由到对应 BFF
 * 插件开发者只需提供 GraphQL 查询语句和变量
 */
export function useWidgetQuery<
  TData = unknown,
  TVars = Record<string, unknown>,
>(
  query: string,
  variables?: TVars,
  options?: {
    fallbackData?: TData; // RSC 预取的 initialData
    refreshInterval?: number;
    enabled?: boolean;
  },
) {
  const { role } = useAuth();
  const bffUrl = BFF_ROUTE_MAP[role];

  return useSWR<TData>(
    options?.enabled === false ? null : [bffUrl, query, variables],
    async ([url, q, vars]) => {
      const res = await fetch(url, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ query: q, variables: vars }),
        credentials: "include",
      });
      const json = await res.json();
      if (json.errors) throw new Error(json.errors[0].message);
      return json.data;
    },
    {
      fallbackData: options?.fallbackData, // RSC 预取数据直出
      revalidateOnFocus: false, // 业务数据不自动刷新（配置才自动刷新）
      refreshInterval: options?.refreshInterval,
    },
  );
}

/**
 * 统一 BFF GraphQL 变更 Hook
 */
export function useWidgetMutation<
  TData = unknown,
  TVars = Record<string, unknown>,
>(mutation: string) {
  const { role } = useAuth();
  const bffUrl = BFF_ROUTE_MAP[role];

  return async (variables: TVars): Promise<TData> => {
    const res = await fetch(bffUrl, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ query: mutation, variables }),
      credentials: "include",
    });
    const json = await res.json();
    if (json.errors) throw new Error(json.errors[0].message);
    return json.data;
  };
}
```

**插件使用示例：**

```typescript
// grades-widget 插件（无需关心路由到哪个 BFF）
import { useWidgetQuery, useWidgetMutation } from "@/lib/useWidgetQuery";

const GET_GRADES = `
  query GetGrades($classId: ID!, $termId: ID!) {
    grades(classId: $classId, termId: $termId) { studentId score }
  }
`;

export function GradesWidget({ initialData }: PluginProps) {
  const classId = useSearchParams().get("classId");
  const termId = useSearchParams().get("termId");

  const { data, isLoading } = useWidgetQuery(GET_GRADES, { classId, termId }, {
    fallbackData: initialData,  // RSC 预取的数据
  });

  if (isLoading) return <PluginSkeleton variant="table" />;
  return <GradesTable data={data.grades} />;
}
```

**收益：**

- ✅ 插件开发者无需关心 BFF 路由策略
- ✅ role 切换时自动路由到对应 BFF（universal 插件天然支持多角色）
- ✅ RSC 预取数据通过 `fallbackData` 无缝衔接，首次渲染无瀑布流
- ✅ 统一错误处理、统一 credentials、统一 TypeScript 类型推导

---

## 6. 数据模型（IAM 扩展）

### 6.1 表结构

```sql
-- 插件注册表（系统级，admin 维护；内置插件由构建脚本同步）
plugin_registry (
  plugin_id         TEXT PRIMARY KEY,    -- 'grades-widget'
  category          TEXT,                -- 'universal'|'sidebar'|'topbar'|'teacher'|'student'|'parent'|'admin'
  version           TEXT,                -- semver
  display_name      TEXT,
  description       TEXT,
  required_roles    TEXT[],              -- ['teacher','student','parent']
  default_slot      TEXT,                -- 'main-top'
  default_size      JSONB,               -- {colSpan:2,rowSpan:1}
  default_props     JSONB,               -- 系统默认 props
  props_schema      JSONB,               -- JSON Schema（admin 配置面板用）
  is_builtin        BOOLEAN,             -- true=内置，false=第三方
  is_active         BOOLEAN,             -- 全局启用/禁用
  package_url       TEXT,                -- 二期：第三方插件包 URL
  created_at        TIMESTAMP,
  updated_at        TIMESTAMP
);

-- 角色-插件映射（admin 配置角色可用插件集 + 角色 Layout 默认）
role_plugin_mapping (
  role              TEXT,                -- 'teacher'
  plugin_id         TEXT,                -- 'grades-widget'
  slot              TEXT,                -- 'main-top'（角色默认 slot）
  sort_order        INT,                 -- 显示顺序
  is_enabled        BOOLEAN,             -- 角色是否启用
  widget_props      JSONB,               -- 角色默认 props（覆盖系统默认）
  PRIMARY KEY (role, plugin_id)
);

-- 角色 Layout 默认（admin 配置角色默认模板）
role_layout_default (
  role              TEXT PRIMARY KEY,
  layout_id         TEXT,                -- 'classic'|'focus'|'split'|'triple'|'canvas'
  slot_overrides    JSONB                -- 角色级 slot 默认
);

-- Layout 模板（系统预置，不可改）
layout_templates (
  layout_id         TEXT PRIMARY KEY,    -- 'classic'|'focus'|'split'|'triple'|'canvas'
  display_name      TEXT,
  description       TEXT,
  available_slots   JSONB,               -- ["top","side","main","right"]
  layout_schema     JSONB,               -- {grid:{rows,cols,areas},resizable,draggable}
  is_active         BOOLEAN
);

-- 用户布局覆盖（用户自定义）
user_layout_override (
  user_id           TEXT PRIMARY KEY,
  active_layout     TEXT,                -- 当前选用模板
  slot_overrides    JSONB,               -- 用户自定义 slot 项
  plugin_placements JSONB,               -- [{plugin_id,slot,sort_order,size,props}]
  hidden_plugins    TEXT[]               -- 用户隐藏的插件
);

-- 二期：第三方插件包存储
plugin_packages (
  package_id        TEXT PRIMARY KEY,
  plugin_id         TEXT,                -- 关联 plugin_registry
  version           TEXT,
  manifest_json     JSONB,               -- 解析后的 manifest
  storage_path      TEXT,                -- ZIP 包存储路径
  status            TEXT,                -- 'uploaded'|'installed'|'error'
  uploaded_by       TEXT,
  uploaded_at       TIMESTAMP
);
```

### 6.2 IAM gRPC 接口扩展

```protobuf
// packages/shared-proto/proto/iam.proto 新增

message GetPluginConfigRequest {
  string user_id = 1;
}

message PluginConfigResponse {
  LayoutTemplate active_layout = 1;
  repeated SlotConfig slots = 2;
  repeated PluginPlacement plugins = 3;
  repeated PluginRegistryItem registry = 4;
}

message LayoutTemplate {
  string layout_id = 1;
  string display_name = 2;
  string description = 3;
  repeated string available_slots = 4;
  string layout_schema_json = 5;
}

message SlotConfig {
  string slot_name = 1;
  repeated string nav_items = 2;
}

message PluginPlacement {
  string plugin_id = 1;
  string slot = 2;
  int32 sort_order = 3;
  string size_json = 4;
  string props_json = 5;            // 三层合并后的最终 props
  bool is_visible = 6;
}

message PluginRegistryItem {
  string plugin_id = 1;
  string category = 2;
  string version = 3;
  string display_name = 4;
  string description = 5;
  repeated string required_roles = 6;
  bool is_builtin = 7;
  bool is_active = 8;
}
```

### 6.3 Admin CRUD API

| 方法   | 路径                                  | 用途                                 | MVP     |
| ------ | ------------------------------------- | ------------------------------------ | ------- |
| GET    | `/admin/plugins`                      | 列出所有 plugin_registry 项          | ✅      |
| PUT    | `/admin/plugins/:id`                  | 更新插件配置（启用/禁用/默认 props） | ✅      |
| GET    | `/admin/role-plugin-mapping`          | 列出角色-插件映射                    | ✅      |
| PUT    | `/admin/role-plugin-mapping/:role`    | 批量更新角色插件配置                 | ✅      |
| GET    | `/admin/layout-templates`             | 列出 5 种内置模板                    | ✅      |
| PUT    | `/admin/role-layout-default/:role`    | 配置角色默认 Layout                  | ✅      |
| GET    | `/admin/user-layout-override/:userId` | 查看用户自定义                       | ✅      |
| DELETE | `/admin/user-layout-override/:userId` | 重置用户自定义                       | ✅      |
| POST   | `/admin/plugins/upload`               | 上传第三方插件包（ZIP）              | ⏸️ 二期 |
| DELETE | `/admin/plugins/:id/uninstall`        | 卸载第三方插件                       | ⏸️ 二期 |

### 6.4 配置变更生效路径（SWR 静默刷新）

**抛弃 Kafka + WebSocket 推送链路**（对 Dashboard 布局这种低频变更，引入 Kafka 和 WebSocket 的研发和运维成本过高，属于过度设计）。

改用 **SWR 静默后台刷新**机制：

```typescript
// src/lib/usePluginConfig.ts
import useSWR from "swr";

const fetcher = (url: string) => fetch(url).then((r) => r.json());

export function usePluginConfig(initialConfig: PluginConfigResponse) {
  const { data, mutate } = useSWR<PluginConfigResponse>(
    "/api/plugin-config",
    fetcher,
    {
      fallbackData: initialConfig, // RSC 直出的初始配置作为 fallback
      revalidateOnFocus: true, // 用户切回 Tab 时静默刷新
      revalidateOnReconnect: true, // 网络恢复时静默刷新
      refreshInterval: 300_000, // 每 5 分钟静默刷新一次
      dedupingInterval: 60_000, // 1 分钟内去重
      onSuccess: (newData, key, config) => {
        // 检测到配置变化时，Toast 提示用户刷新
        if (hasConfigChanged(initialConfig, newData)) {
          showToast("发现新布局配置，点击刷新生效", {
            action: { label: "刷新", onClick: () => window.location.reload() },
            duration: 0, // 常驻直到用户操作
          });
        }
      },
    },
  );

  return { config: data, refresh: mutate };
}
```

**生效路径：**

1. Admin 通过 REST API 修改 `plugin_registry` / `role_plugin_mapping` / `role_layout_default`
2. 用户侧 SWR 静默刷新触发（切回 Tab / 5 分钟轮询 / 网络恢复）
3. SWR 检测到配置变化，Toast 提示"发现新布局配置，点击刷新生效"
4. 用户点击刷新或下次刷新页面时，RSC 重新预取配置生效
5. **无需 Kafka、无需 WebSocket、无需 push-gateway 改动**

**收益：**

- ✅ 砍掉 Kafka Outbox 事件链路（IAM 侧）
- ✅ 砍掉 msg 服务消费 + push-gateway WebSocket 推送链路
- ✅ 砍掉前端 WebSocket 客户端订阅逻辑
- ✅ 利用 SWR 成熟机制，代码量减少 80%+
- ✅ 配置变更感知延迟 ≤ 5 分钟（refreshInterval）或即时（revalidateOnFocus），对低频变更完全够用

---

## 7. 设计系统一致性

### 7.1 强制约束

- 所有插件必须使用 `@edu/ui-tokens` 的设计令牌（`hsl(var(--*))` / `var(--font-*)` / `var(--space-*)`）
- 所有插件必须使用 `@edu/ui-components` 的基础组件
- 禁止硬编码颜色（`#hex`）、字体（`'Inter'`）、字号（`font-size: Npx`）、Tailwind 任意值（`w-[Npx]`）
- ESLint 规则 `no-restricted-syntax` + `design-tokens/no-hardcoded-fonts` 强制约束
- 插件必须使用 `PluginCard` 包装组件（纸感风格容器）

### 7.2 新增"插件视觉规范"章节

补充到 `docs/standards/ui-design-system.md`：

- **插件容器**：使用 `PluginCard`，纸感背景 `hsl(var(--card))`，圆角 `var(--radius-md)`，内边距 `var(--space-5)`
- **插件标题**：`font-family: var(--font-family-sans)`，`font-size: var(--font-size-4)`，`font-weight: var(--weight-semibold)`
- **插件加载态**：`<PluginSkeleton variant="card|list|chart|stats|table" />`
- **插件错误态**：`<PluginErrorFallback />`，居中显示错误图标 + 重试按钮
- **插件间距**：slot 内插件间距 `var(--space-4)`，slot 间距 `var(--space-6)`
- **响应式**：mobile 单列，tablet 2 列，desktop 按 layout 配置

### 7.3 新增 UI 组件

- `PluginCard`：纸感卡片容器，强制设计令牌
- `PluginSkeleton`：5 种 skeleton 变体（card/list/chart/stats/table）
- `PluginErrorFallback`：错误兜底组件
- `SlotPlaceholder`：空 slot 占位（admin 模式下显示"添加插件"按钮）
- `PropsConfigForm`：根据 propsSchema 自动渲染的配置表单（admin 配置面板用）

---

## 8. 迁移路径

### 8.1 阶段划分

| 阶段        | 内容                                                                                         | 验收标准                                      |
| ----------- | -------------------------------------------------------------------------------------------- | --------------------------------------------- |
| P1          | IAM 扩展（5 表 + gRPC + admin API）+ proto 契约 + 共享包契约                                 | gRPC 调用返回正确配置，admin CRUD 可用        |
| P2          | Shell 宿主（apps/portal-shell）+ 5 种 Layout 模板 + ConfigProvider + Registry + PluginLoader | Shell 启动、登录、渲染空 Layout、切换模板     |
| P3          | 首张插件（grades-widget）+ dynamic import 跑通 + 三层 props 合并                             | grades-widget 在 Shell 中渲染，props 合并正确 |
| P4          | 剩余 6 张 universal 插件 + sidebar/topbar 插件                                               | 所有 universal/sidebar/topbar 插件可用        |
| P5          | 单角色专属插件（lesson-plan-editor / error-book / ai-tutor / user-management 等）            | 单角色专属插件可用                            |
| P6          | Admin 配置面板（plugin-manager 插件）+ 用户自定义 UI                                         | admin 可配置角色插件，用户可切换 Layout       |
| P7          | api-gateway 路由 + docker-compose 部署 + CI/CD                                               | 容器化部署，CI 流水线通过                     |
| P8          | E2E + 视觉回归测试                                                                           | 测试全通过                                    |
| P9          | 用户逐步迁移，旧 portal 下线                                                                 | 旧 portal 流量为 0                            |
| P10（二期） | 第三方插件上传 + 运行时加载 + 沙箱隔离                                                       | 第三方插件可上传安装运行                      |

### 8.2 旧 Portal 处理

- 现有 4 个 portal（teacher / student / parent / admin）**保留并行运行**
- 新 Shell 使用路由前缀 `/shell/*` 避免冲突
- 用户通过入口链接逐步引导到新 Shell
- 迁移完成后，4 个旧 portal 下线，portal-shell 路由改为 `/`

### 8.3 回滚策略

- 任意阶段失败，回滚到上一阶段
- 旧 portal 始终可用，新 Shell 失败不影响现有用户
- IAM 新增表与现有表无外键依赖，可独立回滚

---

## 9. 完整对接清单

### 9.1 前端新建

| 路径                                                    | 职责                                                                     | 动作 |
| ------------------------------------------------------- | ------------------------------------------------------------------------ | ---- |
| `apps/portal-shell/`                                    | Shell 宿主应用（单 Next.js App Router）                                  | 新建 |
| `apps/portal-shell/src/app/layout.tsx`                  | RootLayout，挂载 Providers                                               | 新建 |
| `apps/portal-shell/src/app/shell/[[...route]]/page.tsx` | Shell 入口（RSC Server Component），服务端拉取 Config + 预取 initialData | 新建 |
| `apps/portal-shell/src/shell/ClientShell.tsx`           | Client Component，接收 RSC props，渲染 Layout + Plugins                  | 新建 |
| `apps/portal-shell/src/shell/Shell.tsx`                 | Layout 框架 + Slots                                                      | 新建 |
| `apps/portal-shell/src/shell/Registry.ts`               | 插件清单（plugin_id → dynamic import）                                   | 新建 |
| `apps/portal-shell/src/shell/PluginLoader.tsx`          | dynamic import + 骨架屏 + ErrorBoundary                                  | 新建 |
| `apps/portal-shell/src/shell/PluginLifecycle.ts`        | install/enable/disable 管理                                              | 新建 |
| `apps/portal-shell/src/shell/SlotRenderer.tsx`          | 按 Config 渲染插件列表                                                   | 新建 |
| `apps/portal-shell/src/shell/PropsMerger.ts`            | 三层 props 合并                                                          | 新建 |
| `apps/portal-shell/src/shell/LayoutManager.tsx`         | 5 种 Layout 模板渲染器                                                   | 新建 |
| `apps/portal-shell/src/shell/PluginStore.ts`            | Zustand 全局状态（theme/locale/sidebar）                                 | 新建 |
| `apps/portal-shell/src/lib/iam-client.ts`               | IAM gRPC 客户端（服务端调用）                                            | 新建 |
| `apps/portal-shell/src/lib/bff-clients.ts`              | BFF GraphQL 客户端（按 role 路由）                                       | 新建 |
| `apps/portal-shell/src/lib/useWidgetQuery.ts`           | 统一 BFF 查询 Hook（自动按 role 路由 + fallbackData）                    | 新建 |
| `apps/portal-shell/src/lib/useWidgetMutation.ts`        | 统一 BFF 变更 Hook                                                       | 新建 |
| `apps/portal-shell/src/lib/usePluginConfig.ts`          | SWR 静默刷新配置（revalidateOnFocus + refreshInterval）                  | 新建 |
| `apps/portal-shell/src/providers/AuthProvider.tsx`      | JWT + RBAC，提供 useAuth()                                               | 新建 |
| `apps/portal-shell/src/providers/ThemeI18nProvider.tsx` | 主题 + i18n                                                              | 新建 |
| `apps/portal-shell/next.config.js`                      | Next.js 配置（standalone 模式）                                          | 新建 |
| `apps/portal-shell/Dockerfile`                          | 独立容器构建（单服务）                                                   | 新建 |
| `apps/portal-shell/vitest.config.ts`                    | Shell 单元测试                                                           | 新建 |

### 9.2 内置插件源码

| 路径                                                            | 分类                         | 动作 |
| --------------------------------------------------------------- | ---------------------------- | ---- |
| `apps/portal-shell/src/widgets/universal/grades-widget/`        | universal                    | 新建 |
| `apps/portal-shell/src/widgets/universal/homework-widget/`      | universal                    | 新建 |
| `apps/portal-shell/src/widgets/universal/schedule-widget/`      | universal                    | 新建 |
| `apps/portal-shell/src/widgets/universal/attendance-widget/`    | universal                    | 新建 |
| `apps/portal-shell/src/widgets/universal/exams-widget/`         | universal                    | 新建 |
| `apps/portal-shell/src/widgets/universal/notifications-widget/` | universal                    | 新建 |
| `apps/portal-shell/src/widgets/universal/announcements-widget/` | universal                    | 新建 |
| `apps/portal-shell/src/widgets/sidebar/class-selector/`         | sidebar                      | 新建 |
| `apps/portal-shell/src/widgets/sidebar/child-selector/`         | sidebar                      | 新建 |
| `apps/portal-shell/src/widgets/sidebar/term-switcher/`          | sidebar                      | 新建 |
| `apps/portal-shell/src/widgets/topbar/global-search/`           | topbar                       | 新建 |
| `apps/portal-shell/src/widgets/topbar/notification-bell/`       | topbar                       | 新建 |
| `apps/portal-shell/src/widgets/topbar/user-menu/`               | topbar                       | 新建 |
| `apps/portal-shell/src/widgets/topbar/locale-switcher/`         | topbar                       | 新建 |
| `apps/portal-shell/src/widgets/teacher/lesson-plan-editor/`     | teacher                      | 新建 |
| `apps/portal-shell/src/widgets/teacher/question-bank/`          | teacher                      | 新建 |
| `apps/portal-shell/src/widgets/student/error-book/`             | student                      | 新建 |
| `apps/portal-shell/src/widgets/student/ai-tutor/`               | student                      | 新建 |
| `apps/portal-shell/src/widgets/parent/child-overview/`          | parent                       | 新建 |
| `apps/portal-shell/src/widgets/admin/user-management/`          | admin                        | 新建 |
| `apps/portal-shell/src/widgets/admin/rbac-manager/`             | admin                        | 新建 |
| `apps/portal-shell/src/widgets/admin/plugin-manager/`           | admin（配置面板本身）        | 新建 |
| 每个 `*/plugin.manifest.ts`                                     | 插件元数据 + propsSchema     | 新建 |
| 每个 `*/index.tsx`                                              | 插件入口（接收 PluginProps） | 新建 |

### 9.3 共享包扩展

| 路径                                                 | 变更                                                                                       | 动作       |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- |
| `packages/shared-ts/src/contracts/plugin.ts`         | 新增 PluginProps / PluginManifest 类型契约                                                 | 新增导出   |
| `packages/shared-ts/src/contracts/layout.ts`         | 新增 LayoutTemplate / SlotConfig / PluginPlacement 类型                                    | 新增导出   |
| `packages/shared-ts/src/contracts/plugin-store.ts`   | Zustand 全局状态 schema（theme/locale/sidebar）                                            | 新增导出   |
| `packages/shared-ts/src/contracts/plugin-context.ts` | URL Search Params 上下文 schema（classId/childId/termId/view）                             | 新增导出   |
| `packages/ui-components/src/`                        | 新增 PluginCard / PluginSkeleton / PluginErrorFallback / SlotPlaceholder / PropsConfigForm | 新增组件   |
| `packages/ui-tokens/src/`                            | 无需变更（现有令牌足够）                                                                   | 复用       |
| `packages/hooks/src/`                                | 新增 usePluginConfig（SWR）/ usePluginStore（Zustand）                                     | 新增 hooks |
| `pnpm-workspace.yaml`                                | 新增 `apps/portal-shell`                                                                   | 修改       |

### 9.4 后端 IAM 扩展

| 路径                                           | 变更                                                                                                                            | 动作            |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `services/iam/src/iam/iam.schema.ts`           | 新增 plugin_registry / role_plugin_mapping / role_layout_default / layout_templates / user_layout_override / plugin_packages 表 | 新增 schema     |
| `services/iam/src/iam/iam.service.ts`          | 新增 getPluginRegistry / getRolePluginMapping / getUserLayoutOverride / mergePluginConfig / mergeProps 方法                     | 新增方法        |
| `services/iam/src/iam/iam.grpc.controller.ts`  | 新增 GetPluginConfig RPC（合并三层配置返回）                                                                                    | 新增 RPC        |
| `packages/shared-proto/proto/iam.proto`        | 新增 PluginConfigRequest/Response、LayoutTemplate、PluginRegistryItem 等 message                                                | 新增 proto      |
| `services/iam/scripts/seed-plugins.ts`         | 初始化 5 个 Layout 模板 + 内置插件注册项                                                                                        | 新建 seed       |
| `services/iam/src/iam/admin.controller.ts`     | 新增 admin CRUD plugin_registry / role_plugin_mapping REST API                                                                  | 新增 controller |
| `services/iam/scripts/sync-builtin-plugins.ts` | 构建时从 portal-shell 的 manifest 同步到 plugin_registry 表                                                                     | 新建脚本        |

### 9.5 BFF 层

| 路径                    | 变更                                                             | 动作     |
| ----------------------- | ---------------------------------------------------------------- | -------- |
| `services/teacher-bff/` | 无需变更，插件直接调用现有 GraphQL                               | 复用     |
| `services/student-bff/` | 无需变更                                                         | 复用     |
| `services/parent-bff/`  | 无需变更                                                         | 复用     |
| 插件配置查询            | 由 Shell 直接调 IAM gRPC（不经 BFF），保持配置查询与业务查询分离 | 路由策略 |

### 9.6 网关层

| 路径                                             | 变更                                                           | 动作     |
| ------------------------------------------------ | -------------------------------------------------------------- | -------- |
| `services/api-gateway/internal/proxy/proxy.go`   | 新增 `/portal-shell` 路由（单服务）                            | 新增路由 |
| `services/api-gateway/internal/config/config.go` | 新增 portal-shell 服务地址配置                                 | 新增配置 |
| `services/push-gateway/`                         | 无需变更（配置刷新改用 SWR 客户端轮询，不依赖 WebSocket 推送） | 复用     |

### 9.7 部署与基础设施

| 路径                              | 变更                                                     | 动作     |
| --------------------------------- | -------------------------------------------------------- | -------- |
| `infra/docker-compose.deploy.yml` | 新增 portal-shell 服务（单服务，无独立 widget 容器）     | 新增服务 |
| `infra/port-allocation.md`        | 新增 portal-shell 端口（4010）                           | 新增     |
| `infra/init-sql/01-init.sql`      | 新增 IAM 6 张表的 DDL                                    | 新增     |
| `apps/portal-shell/Dockerfile`    | standalone 模式构建（单容器）                            | 新建     |
| `.github/workflows/ci.yml`        | 新增 portal-shell 构建作业（单作业，无 widget 独立构建） | 修改     |

### 9.8 设计系统对接

| 路径                                 | 变更                              | 动作        |
| ------------------------------------ | --------------------------------- | ----------- |
| `docs/standards/ui-design-system.md` | 新增"插件视觉规范"章节            | 补充章节    |
| `packages/ui-tokens/`                | 无需变更                          | 复用        |
| `packages/ui-components/`            | 新增 PluginCard 等组件            | 新增组件    |
| `apps/portal-shell/src/styles/`      | 复用现有 globals.css + tokens     | 复用        |
| 插件内部样式                         | 必须使用 @edu/ui-tokens，禁硬编码 | ESLint 强制 |

### 9.9 测试

| 路径                                         | 内容                                                                              | 动作 |
| -------------------------------------------- | --------------------------------------------------------------------------------- | ---- |
| `apps/portal-shell/vitest.config.ts`         | Shell 单元测试（Shell/ConfigProvider/Registry/PluginLoader/EventBus/PropsMerger） | 新建 |
| `apps/portal-shell/src/widgets/*/__tests__/` | 每个插件单元测试                                                                  | 新建 |
| `tests/e2e/portal-shell.spec.ts`             | E2E：登录 → 加载 layout → 渲染插件 → 切换 layout                                  | 新建 |
| `tests/e2e/plugin-config.spec.ts`            | E2E：admin 改配置 → 用户刷新生效                                                  | 新建 |
| `tests/visual/portal-shell.spec.ts`          | 视觉回归：5 种 layout 截图对比                                                    | 新建 |

### 9.10 架构元数据

| 路径                                               | 变更                                   | 动作     |
| -------------------------------------------------- | -------------------------------------- | -------- |
| `scripts/arch-scan/`                               | 扫描 `apps/portal-shell`，更新 arch.db | 扫描更新 |
| `docs/architecture/004_architecture_impact_map.md` | 新增 portal-shell 模块章节             | 补充章节 |
| `docs/troubleshooting/known-issues.md`             | 新增 portal-shell 分区                 | 补充分区 |
| `apps/portal-shell/README.md`                      | Shell 架构文档                         | 新建     |

### 9.11 Proto 契约

见 §6.2 `iam.proto` 新增 message 定义。

### 9.12 现有 4 个 Portal 处理

| 路径                   | 处理                                          | 动作     |
| ---------------------- | --------------------------------------------- | -------- |
| `apps/teacher-portal/` | 保留并行运行，逐步迁移                        | 保留     |
| `apps/student-portal/` | 保留并行运行                                  | 保留     |
| `apps/parent-portal/`  | 保留并行运行                                  | 保留     |
| `apps/admin-portal/`   | 保留并行运行                                  | 保留     |
| `apps/portal-shell/`   | 新 Shell，路由前缀 `/shell/*`                 | 新建     |
| 迁移完成后             | 4 个旧 portal 下线，portal-shell 路由改为 `/` | 最终切换 |

---

## 10. 风险与缓解

| 风险                                                  | 影响                         | 缓解                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 插件数量增长导致首屏 bundle 过大                      | 首屏加载慢                   | dynamic import 按需加载 + IntersectionObserver 滚动加载 + 首屏只加载可见 slot                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 单体架构插件间隐式耦合                                | 维护困难                     | ESLint 禁止跨 widgets 目录 import + 架构扫描检测违规 + 强制通过 URL/Zustand 共享状态（禁止直接 import 其他插件）                                                                                                                                                                                                                                                                                                                                                                                     |
| 单角色专属功能（如备课画布）作为插件受 props 契约约束 | 复杂功能实现受限             | PluginProps 设计足够灵活（initialData + props 任意 JSON）；复杂功能可在插件内部自行组织，仅对外暴露必要契约；跨插件状态通过 URL/Zustand 共享，不通过 props 注入                                                                                                                                                                                                                                                                                                                                      |
| IAM 配置查询压力                                      | RSC 每次请求查询 6 张表      | 复用 IAM 现有 cacheFn（ttl=60s）+ Redis 缓存；RSC 侧使用 React cache() 对同一请求内的重复查询去重；配置变更后 SWR 客户端轮询自然刷新                                                                                                                                                                                                                                                                                                                                                                 |
| 插件 props 三层合并逻辑复杂                           | props 不一致                 | PropsMerger 集中实现 + 单元测试覆盖；合并算法：深合并 + 数组覆盖                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| admin 配置面板表单自动渲染                            | propsSchema 复杂时表单体验差 | 基于 JSON Schema 的表单库（react-jsonschema-form 或自研）+ 支持 uiSchema 自定义                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 二期第三方插件沙箱隔离                                | 安全风险                     | 在单体应用中直接 script 注入第三方不信任代码等于交出主站最高权限（XSS、Token 窃取）。**MVP 不实现第三方插件**；二期必须采用以下方案之一：① **iframe + postMessage**（最安全，完全隔离 DOM/JS/CSS，通过 postMessage 通信，但样式/高度自适应复杂）；② **QuickJS 隔离沙箱**（参考 Figma，在 Web Worker 中运行第三方 JS，通过 RPC 通信，性能好但实现复杂）；③ **Shadow DOM + Proxy 限定 API 表面**（折中，样式隔离 + JS API 白名单代理，但安全性弱于 iframe）。**推荐 iframe + postMessage**，详见 §10.1 |

### 10.1 第三方插件沙箱方案（二期规划）

针对 v2.1 §5.4 中"二期第三方插件 script 注入加载"的风险，详细规划沙箱方案：

#### 方案对比

| 方案                 | 隔离强度       | 性能                   | 实现复杂度 | 通信方式           | 推荐度                 |
| -------------------- | -------------- | ---------------------- | ---------- | ------------------ | ---------------------- |
| iframe + postMessage | 强（完全隔离） | 中（每个插件独立进程） | 中         | postMessage 序列化 | ✅ 推荐                |
| QuickJS Web Worker   | 强（JS 隔离）  | 好（Worker 并行）      | 高         | RPC 代理           | △ 备选                 |
| Shadow DOM + Proxy   | 中（样式隔离） | 好（同进程）           | 低         | 直接调用 + Proxy   | ✗ 不推荐（安全性不足） |
| 动态 script 注入     | 弱（无隔离）   | 好（同进程）           | 低         | window 挂载        | ✗ 弃用                 |

#### 推荐方案：iframe + postMessage

```typescript
// 二期：第三方插件通过 iframe 加载
// 1. 第三方插件 ZIP 包含 manifest.json + index.html + JS bundle
// 2. 后端解压到 /plugins/{pluginId}/ 静态服务
// 3. Shell 通过 iframe 加载 /plugins/{pluginId}/index.html
// 4. 通过 postMessage 通信，限定 API 表面

<iframe
  src={`/plugins/${pluginId}/index.html?instanceId=${instanceId}`}
  sandbox="allow-scripts"  // 禁止 same-origin，强制跨域隔离
  referrerPolicy="no-referrer"
  style={{ width: '100%', height: '100%', border: 'none' }}
/>

// Shell 侧 API 表面（通过 postMessage 暴露给第三方插件）
const SANDBOXED_API = {
  'getPluginContext': () => ({ role, userId, classId, termId }),
  'queryBFF': (query, vars) => bffClient.query(query, vars),  // 代理 BFF 请求
  'mutateBFF': (mutation, vars) => bffClient.mutate(mutation, vars),
  'navigate': (url) => router.push(url),                       // 代理路由
  'setHeight': (height) => resizeIframe(height),               // 高度自适应
  // 注意：禁止暴露 localStorage、cookies、window 对象
};
```

**安全约束：**

- iframe `sandbox="allow-scripts"` 禁止 same-origin，第三方无法访问主站 cookie/localStorage
- 所有 API 通过 postMessage 代理，白名单机制限定可调用 API
- BFF 请求由 Shell 代理（第三方不直接持有 JWT），Shell 可做权限校验
- CSP 头限制第三方插件只能加载自身域名的资源

---

## 11. 验收标准

### 11.1 功能验收

- [ ] 5 种 Layout 模板可切换，slot 正确渲染
- [ ] 7 张 universal 插件 + sidebar/topbar 插件 + 单角色专属插件加载正常
- [ ] admin 可通过 REST API 配置角色插件集合
- [ ] admin 可配置角色默认 Layout 模板
- [ ] admin 可配置插件默认 props（基于 propsSchema 自动渲染表单）
- [ ] admin 可查看/重置用户自定义布局
- [ ] 用户可切换 Layout 模板（在可用集内）
- [ ] 用户可隐藏/显示插件
- [ ] 用户可调整插件 props（在 propsSchema 允许范围内）
- [ ] admin 改配置 → SWR 静默刷新检测到变化 → Toast 提示用户刷新生效
- [ ] 插件加载失败显示错误兜底，不影响其他插件
- [ ] 跨插件状态共享正常（class-selector 切换班级 → grades-widget 自动响应）
- [ ] 插件 props 三层合并正确
- [ ] RSC 服务端预取正常：首屏 HTML 直出 Config + initialData
- [ ] useWidgetQuery 自动按 role 路由到对应 BFF
- [ ] URL Search Params 可分享、可前进后退

### 11.2 非功能验收

- [ ] `pnpm run lint` + `pnpm run typecheck` 零错误
- [ ] Shell 首屏 LCP < 2s（SSR 骨架 + client 水合 + 按需加载）
- [ ] 插件加载耗时 < 500ms（dynamic import 缓存命中后）
- [ ] 单元测试覆盖率 ≥ 80%
- [ ] E2E 测试通过
- [ ] 视觉回归测试通过（5 种 layout 截图）
- [ ] 所有插件遵守设计令牌（ESLint 强制）
- [ ] arch.db 更新，004 文档同步

---

## 12. 参考资料

- [CICD widget-configs.ts](file:///e:/Desktop/CICD/src/modules/dashboard/config/widget-configs.ts) - 单应用 widget 配置驱动参考
- [0010 架构蓝图](../../architecture/0010_architecture.md) §4 微前端 - 统一 UI 库
- [UI 设计系统](../../standards/ui-design-system.md) - 纸感编辑器设计风格
- [项目规则](../../.trae/rules/project_rules.md) - DDD 分层、设计令牌、多 AI 协作规范
- Halo 插件机制 - JAR 分发 · 扩展点注入 · 完整生命周期 · 插件市场参考
- [Next.js Dynamic Import](https://nextjs.org/docs/pages/building-your-application/optimizing/lazy-loading) - dynamic import + ssr:false
- [Next.js Server Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components) - RSC 服务端预取参考
- [Zustand](https://github.com/pmndrs/zustand) - React 全局状态管理（替代 EventBus）
- [SWR](https://swr.vercel.app/) - 数据请求 + 静默后台刷新（替代 WebSocket 推送）
- [Figma QuickJS 沙箱](https://www.figma.com/blog/an-update-on-plugin-security/) - 第三方插件隔离参考

---

## 13. 版本演进对比

| 维度           | v1.0（MF 微前端）           | v2.0（Modular Monolith）    | v2.1（React 单体哲学优化）            |
| -------------- | --------------------------- | --------------------------- | ------------------------------------- |
| 架构           | MF 2.0 + 7 独立 widget 容器 | 单 Next.js + dynamic import | 单 Next.js App Router + RSC           |
| 部署           | 8+ 个容器                   | 1 个容器                    | 1 个容器                              |
| 加载           | 运行时 MF 远程加载          | 编译时打包 + dynamic import | RSC 服务端预取 + dynamic import       |
| 首屏           | MF 远程加载慢               | CSR 瀑布流（4 层串行）      | RSC 直出 Config + initialData（秒开） |
| 跨插件通信     | EventBus 发布订阅           | EventBus 发布订阅           | URL Search Params + Zustand           |
| 配置刷新       | Kafka + WebSocket 推送      | Kafka + WebSocket 推送      | SWR 静默刷新（revalidateOnFocus）     |
| BFF 请求       | 插件自行判断 role 路由      | 插件自行判断 role 路由      | useWidgetQuery 统一 Hook 自动路由     |
| 第三方插件沙箱 | script 注入（不安全）       | script 注入（不安全）       | iframe + postMessage（二期）          |
| 复杂度         | 高                          | 低                          | 最低                                  |
| 旧 portal 迁移 | 并行运行                    | 并行运行                    | 并行运行                              |