Edu/apps/admin-portal/docs/02-architecture-design.md

# 模块架构设计文档 — admin-portal

> AI：ai07（TS/React · 管理场景域前端 remote）
> 阶段：阶段 2 交付物
> 日期：2026-07-09
> 关联：[阶段 1 理解确认书](./01-understanding.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md) §5.4、[pending-features P6](../../../docs/architecture/roadmap/pending-features.md)、[teacher-portal 阶段2](../../teacher-portal/docs/02-architecture-design.md)
> 状态：待 coord 交叉审查

---

## 1. 模块内部分层图（简化版：admin-portal Remote + Shell 引用 + Gateway）

```mermaid
graph TB
    subgraph Browser["浏览器（系统/校管理员）"]
        URL[URL 路由 /admin/*]
    end

    subgraph Shell["teacher-portal（Shell 宿主）"]
        AppShell[AppShell<br/>左栏导航 + 主内容区<br/>按 scope=admin 过滤视口]
        RootLayout[RootLayout<br/>字体/令牌/i18n Provider<br/>TanStack QueryClientProvider<br/>Zustand StoreProvider]
        Router[Next.js App Router<br/>动态加载 admin Remote]
        SharedDeps["共享依赖暴露（singleton）<br/>react/react-dom/@tanstack/react-query/zustand/nuqs<br/>ui-components/ui-tokens/contracts/hooks/shared-ts"]
        Rewrites["rewrites /api/v1/* → api-gateway"]
    end

    subgraph RemoteAdmin["admin-portal（Remote 子应用）"]
        AdminPages[管理场景页面<br/>dashboard/users/roles/permissions/viewports/organization/monitoring]
        AdminComponents["admin 特有组件<br/>UserManagementTable/RolePermissionMatrix/ViewportConfigEditor/PlatformMonitor"]
        AdminHooks["admin 业务 Hooks<br/>useUsers/useRoles/usePermissions/useViewports/useMonitoring"]
    end

    subgraph Shared["共享层（packages/，由 Shell 暴露）"]
        UITokens[ui-tokens<br/>三层设计令牌]
        UIComponents[ui-components<br/>shadcn + A11y + ErrorBoundary + RequirePermission]
        Contracts[contracts<br/>Permissions 常量 + 类型]
        Hooks[hooks<br/>usePermission/useAuth/useViewports/useApi]
        LibTS[shared-ts<br/>ApiClient/Logger/Tracer]
    end

    subgraph Gateway["api-gateway"]
        GW[Gin 路由/鉴权/限流]
    end

    subgraph Backend["后端服务"]
        IAM[iam<br/>用户/角色/权限/视口 CRUD]
        BFF[teacher-bff<br/>/admin/* 聚合]
        MSG[msg<br/>/notifications/*（P5）]
    end

    Browser --> URL
    URL --> RootLayout
    RootLayout --> AppShell
    AppShell --> Router
    Router -->|动态加载 /admin/*| RemoteAdmin

    RemoteAdmin -->|消费 singleton| SharedDeps
    SharedDeps --> UITokens
    SharedDeps --> UIComponents
    SharedDeps --> Contracts
    SharedDeps --> Hooks
    SharedDeps --> LibTS

    AdminPages --> AdminComponents
    AdminPages --> AdminHooks
    AdminHooks -->|useApi → ApiClient| LibTS
    AdminComponents --> UIComponents

    AdminPages -->|fetch /api/v1/iam/*| Rewrites
    AdminPages -->|fetch /api/v1/admin/*| Rewrites
    AdminPages -->|fetch /api/v1/notifications/*| Rewrites
    Rewrites --> GW
    GW --> IAM
    GW --> BFF
    GW --> MSG

    AppShell -->|fetch /api/v1/iam/effective-permissions| Rewrites
```

### 1.1 Remote 与 Shell 的职责边界

| 职责                             | 归属                 | 说明                                                                  |
| -------------------------------- | -------------------- | --------------------------------------------------------------------- |
| RootLayout（字体/令牌/Provider） | teacher-portal Shell | admin-portal 复用，不重复引入                                         |
| AppShell（左栏 + 主内容区）      | teacher-portal Shell | admin-portal 通过 `<AppShell scope="admin">` 渲染管理端视口           |
| 路由表 `/admin/*`                | teacher-portal Shell | Shell 注册 `/admin/*` 路由组，动态 import admin Remote 模块           |
| 登录页                           | teacher-portal Shell | 统一登录入口，按角色重定向到 `/admin/dashboard`                       |
| rewrites `/api/v1/*`             | teacher-portal Shell | admin-portal 不实现 rewrites，依赖 Shell                              |
| 管理场景页面                     | admin-portal Remote  | `/admin/*` 下的所有 page.tsx                                          |
| 管理特有组件                     | admin-portal Remote  | UserManagementTable 等 4 个                                           |
| 管理业务 Hooks                   | admin-portal Remote  | useUsers/useRoles/usePermissions/useViewports/useMonitoring           |
| 共享组件库                       | Shell 暴露           | AppShell/RequirePermission/ErrorBoundary/DataTable/Form/Chart 等      |
| 共享 Hooks                       | Shell 暴露           | usePermission/useAuth/useViewports/useApi/useA11yId                   |
| ApiClient                        | Shell 暴露           | `packages/shared-ts/src/api-client.ts`，admin-portal 通过 useApi 获取 |

### 1.2 MF 配置（admin-portal/next.config.js，Remote 角色）

```javascript
// admin-portal/next.config.js（Remote）
const NextFederationPlugin = require("@module-federation/nextjs-mf");

module.exports = {
  reactStrictMode: true,
  transpilePackages: [
    "@edu/ui-tokens",
    "@edu/ui-components",
    "@edu/hooks",
    "@edu/contracts",
    "@edu/shared-ts",
  ],
  webpack(config, { isServer }) {
    config.plugins.push(
      new NextFederationPlugin({
        name: "admin_app",
        filename: "static/chunks/remoteEntry.js",
        // Remote 不暴露任何模块给 Shell（Shell 通过 dynamic import 加载 admin 的 pages）
        exposes: {
          "./pages": "./src/pages",
        },
        // Remote 反向引用 Shell 暴露的共享组件（可选，多数通过 singleton shared 解决）
        remotes: {
          teacher: `teacher_app@http://localhost:3000/_next/static/${isServer ? "ssr" : "chunks"}/remoteEntry.js`,
        },
        shared: {
          react: { singleton: true, requiredVersion: "^18.3.0" },
          "react-dom": { singleton: true, requiredVersion: "^18.3.0" },
          "@tanstack/react-query": { singleton: true },
          zustand: { singleton: true },
          nuqs: { singleton: true },
          "@edu/ui-tokens": { singleton: true },
          "@edu/ui-components": { singleton: true },
          "@edu/hooks": { singleton: true },
          "@edu/contracts": { singleton: true },
          "@edu/shared-ts": { singleton: true },
        },
        extraOptions: { exposePages: false },
      }),
    );
    return config;
  },
  // admin-portal 不实现 rewrites，依赖 teacher-portal Shell 的 rewrites 代理 /api/v1/*
};
```

> **说明**：
>
> - admin-portal 作为 Remote，`name: 'admin_app'`，被 Shell 在 `remotes` 中引用为 `admin: 'admin_app@http://localhost:3003/...'`
> - admin-portal 不实现 `rewrites`，所有 `/api/v1/*` 请求由 Shell 的 rewrites 代理到 api-gateway
> - `shared` 全部声明为 `singleton: true`，确保与 Shell 共享同一实例（避免 React 多实例报错、Zustand store 分裂）
> - `transpilePackages` 列出本地 packages/* 软链依赖，确保 SWC 正确编译

## 2. 领域模型（前端视角）

前端不持有业务聚合根，仅持有"视图模型"（ViewModel）和"会话状态"。

### 2.1 会话状态 / 视口 / 权限（与 teacher-portal 共享）

**Session**、**Viewport**、**Permission** 三个模型与 teacher-portal 完全共享，定义和存储策略见 [teacher-portal 阶段2 §2.1-2.3](../../teacher-portal/docs/02-architecture-design.md#2-领域模型前端视角)。

admin-portal 作为 Remote，通过 Shell 暴露的 `useAuth()` / `usePermission()` / `useViewports('admin')` Hook 消费这些模型，**不重复定义**。

### 2.2 管理场景视图模型（admin-portal 特有）

```typescript
// 用户管理视图模型
interface UserViewModel {
  id: string;
  email: string;
  name: string;
  roles: RoleViewModel[]; // 用户拥有的角色
  status: "active" | "disabled" | "locked";
  dataScope: DataScope; // L0-L5
  organizationId: string | null; // 所属组织
  lastLoginAt: number | null;
  createdAt: number;
  updatedAt: number;
}

// 角色管理视图模型
interface RoleViewModel {
  id: string;
  name: string;
  code: string; // 角色编码，如 'school_admin'
  description: string;
  permissions: PermissionViewModel[]; // 角色拥有的权限
  userCount: number; // 该角色下的用户数（用于删除前校验）
  dataScope: DataScope; // 角色默认数据范围
  isSystem: boolean; // 系统预置角色不可删除
  createdAt: number;
  updatedAt: number;
}

// 权限管理视图模型
interface PermissionViewModel {
  id: string;
  code: string; // 'IAM_USER_READ' 等
  name: string; // 显示名
  description: string;
  resource: string; // 资源类型 'user' | 'role' | 'permission' | 'viewport' | 'org' | 'monitoring'
  action: string; // 'read' | 'create' | 'update' | 'delete' | 'manage'
  isSystem: boolean; // 系统预置权限不可删除
}

// 视口配置视图模型（管理端可编辑）
interface ViewportConfigViewModel {
  id: string;
  key: string; // 'dashboard' | 'users' | ...
  label: string; // i18n key
  route: string; // '/admin/dashboard'
  icon: string | null;
  sortOrder: number;
  requiredPermission: string | null;
  scope: "teacher" | "student" | "parent" | "admin";
  isVisible: boolean; // 是否在导航显示
}

// 平台监控视图模型
interface MonitoringMetricsViewModel {
  timestamp: number;
  activeUsers: number; // 当前在线用户数
  totalUsers: number;
  requestsPerMinute: number;
  errorRate: number; // 0-1
  avgResponseTimeMs: number;
  serviceHealth: Array<{
    serviceName: string;
    status: "healthy" | "degraded" | "down";
    latencyMs: number;
  }>;
}
```

### 2.3 数据范围控制（admin-portal 特有）

```typescript
// admin-portal 用户可见的数据范围由 dataScope 决定
// L3 校管理员：仅见本校用户/角色/组织
// L4 区教研员：仅见本区
// L5 系统管理员：全平台
interface AdminDataScopeFilter {
  dataScope: DataScope; // L3-L5
  schoolId?: string; // L3 时必填
  districtId?: string; // L4 时必填
}

// 所有列表查询 API 自动注入此 filter（由 ApiClient 拦截器添加）
```

## 3. 数据模型（前端缓存层）

admin-portal 无数据库，仅有 TanStack Query 缓存层。**管理数据低频变，采用 5min 长缓存**策略：

| 数据类型                | 存储                   | TTL                         | 失效策略                                           |
| ----------------------- | ---------------------- | --------------------------- | -------------------------------------------------- |
| Session（token + user） | localStorage + Zustand | access 15min / refresh 7day | 401 自动 refresh，refresh 失败跳登录（复用 Shell） |
| 权限列表                | TanStack Query cache   | 5min                        | 角色变更主动 invalidate（复用 Shell）              |
| 视口列表                | TanStack Query cache   | 5min                        | 视口配置变更主动 invalidate                        |
| 用户列表                | TanStack Query cache   | 5min                        | staleTime 5min，mutation 后 invalidate             |
| 角色列表                | TanStack Query cache   | 5min                        | staleTime 5min，mutation 后 invalidate             |
| 权限列表（全量）        | TanStack Query cache   | 30min                       | staleTime 30min（权限点极少变更）                  |
| 视口配置列表            | TanStack Query cache   | 5min                        | staleTime 5min，mutation 后 invalidate             |
| 组织树                  | TanStack Query cache   | 5min                        | staleTime 5min                                     |
| 平台监控指标            | TanStack Query cache   | 60s                         | staleTime 60s（refetchInterval 60s 轮询）          |
| 用户活动统计            | TanStack Query cache   | 5min                        | staleTime 5min（refetchInterval 5min 轮询）        |
| URL 状态（分页/筛选）   | nuqs                   | —                           | 永久（可分享）                                     |
| 表单临时态              | react-hook-form        | —                           | 卸载即销毁                                         |

> **缓存策略说明**：管理数据（用户/角色/权限/视口/组织）低频变更，5min 长缓存减少 BFF 压力；监控指标需要相对实时，60s 轮询；权限点常量几乎不变，30min 长缓存。所有 mutation 成功后主动 invalidate 对应 queryKey，确保 UI 立即刷新。

## 4. API 设计（前端 → 后端）

前端不设计后端 API，仅声明消费的端点。详见 [01-understanding.md §3.1](./01-understanding.md#31-消费的后端-api经-api-gateway-代理)。

### 4.1 统一 API 请求层（复用 Shell 暴露的 ApiClient）

admin-portal **不重复实现** ApiClient，通过 Shell 暴露的 `useApi()` Hook 获取 ApiClient 实例。ApiClient 定义见 [teacher-portal 阶段2 §4.1](../../teacher-portal/docs/02-architecture-design.md#41-统一-api-请求层libapits)。

```typescript
// admin-portal 业务 Hook 示例（消费 Shell 暴露的 useApi）
import { useApi } from "@edu/hooks";
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";

export function useUsers(filter: AdminDataScopeFilter) {
  const api = useApi();
  return useQuery({
    queryKey: ["admin", "users", filter],
    queryFn: () => api.get<UserViewModel[]>("/api/v1/iam/users", filter),
    staleTime: 5 * 60 * 1000, // 5min
  });
}

export function useCreateUser() {
  const api = useApi();
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (input: CreateUserInput) =>
      api.post("/api/v1/iam/users", input),
    onSuccess: () =>
      queryClient.invalidateQueries({ queryKey: ["admin", "users"] }),
  });
}
```

### 4.2 TanStack Query 约定

```typescript
// Query Key 命名：[scope, resource, ...args]
queryKey: ["admin", "users", { schoolId, status }];
queryKey: ["admin", "users", userId]; // 详情
queryKey: ["admin", "roles", { dataScope }];
queryKey: ["admin", "permissions"]; // 全量，30min 缓存
queryKey: ["admin", "viewports", { scope }]; // 按 scope 过滤
queryKey: ["admin", "organization", { parentId }];
queryKey: ["admin", "monitoring", "metrics"]; // 60s 轮询
queryKey: ["admin", "stats", "active-sessions"]; // 5min 轮询

// Mutation 约定（mutation 后主动 invalidate）
const createUser = useMutation({
  mutationFn: (input) => api.post("/api/v1/iam/users", input),
  onSuccess: () =>
    queryClient.invalidateQueries({ queryKey: ["admin", "users"] }),
  onError: (e: ApiError) => toast.error(e.message),
});

// 轮询约定（监控指标）
const useMonitoringMetrics = () => {
  const api = useApi();
  return useQuery({
    queryKey: ["admin", "monitoring", "metrics"],
    queryFn: () =>
      api.get<MonitoringMetricsViewModel>("/api/v1/admin/monitoring/metrics"),
    staleTime: 60 * 1000, // 60s
    refetchInterval: 60 * 1000, // 60s 轮询
  });
};
```

## 5. 事件设计

**— N/A**

admin-portal **不消费** WebSocket 推送（不走 push-gateway），**不消费** SSE 流式响应。管理端场景对实时性要求低，采用**轮询**策略：

| 场景           | 轮询方式                                        | 说明                         |
| -------------- | ----------------------------------------------- | ---------------------------- |
| 平台监控指标   | TanStack Query `refetchInterval: 60s`           | 实时性要求中等               |
| 用户活动统计   | TanStack Query `refetchInterval: 5min`          | 实时性要求低                 |
| 通知中心（P5） | TanStack Query `refetchInterval: 30s`           | 不走 push-gateway，HTTP 拉取 |
| 长期监控面板   | `<iframe>` 嵌入 Grafana（PlatformMonitor 组件） | 不经过 BFF，直连 Grafana     |

> 管理端不接入 push-gateway 的原因：管理员场景低频，推送基础设施成本不划算；轮询策略对 BFF 压力可控（5min TTL 缓存命中率高）。

## 6. 横切关注点对齐清单

### 6.1 权限（前端等价）

| 路由                  | requiredPermission      |
| --------------------- | ----------------------- |
| `/admin/dashboard`    | `ADMIN_DASHBOARD_VIEW`  |
| `/admin/users`        | `IAM_USER_READ`         |
| `/admin/users/new`    | `IAM_USER_CREATE`       |
| `/admin/users/:id`    | `IAM_USER_UPDATE`       |
| `/admin/roles`        | `IAM_ROLE_READ`         |
| `/admin/permissions`  | `IAM_PERMISSION_READ`   |
| `/admin/viewports`    | `IAM_VIEWPORT_READ`     |
| `/admin/organization` | `ORG_MANAGE`            |
| `/admin/monitoring`   | `ADMIN_MONITORING_VIEW` |

> 完整权限点常量集中在 `packages/contracts/src/permissions.ts`（coord 维护）。L3 组件级视口用 `<RequirePermission perm="IAM_USER_CREATE"><Button>新建用户</Button></RequirePermission>`（复用 Shell 暴露组件）。

### 6.2 错误码清单（前端 i18n 路由）

| 前缀           | 来源服务    | i18n key 模式            |
| -------------- | ----------- | ------------------------ |
| `IAM_`         | iam         | `iam.error.{{code}}`     |
| `BFF_TEACHER_` | teacher-bff | `bff.error.{{code}}`     |
| `GW_`          | api-gateway | `gateway.error.{{code}}` |
| `NETWORK_`     | 前端网络层  | `network.error.{{code}}` |

> admin-portal 仅涉及 4 个错误码前缀（iam / teacher-bff / gateway / 网络层），不消费 core-edu/content/msg/ai 服务，不涉及 `CORE_EDU_` / `CONTENT_` / `MSG_` / `AI_` 前缀。

### 6.3 Logger

```typescript
// 复用 packages/shared-ts/src/logger.ts（Shell 暴露）
interface Logger {
  info(msg: string, meta?: Record<string, unknown>): void;
  warn(msg: string, meta?: Record<string, unknown>): void;
  error(msg: string, meta?: Record<string, unknown>): void;
}

// 实现：开发环境 console + 结构化；生产环境 → Sentry（P6，admin-portal 本身就是 P6 阶段）
// 必含字段：trace_id（从响应头提取）、user_id、scope='admin'、path
```

### 6.4 Metrics（Web Vitals）

| 指标                        | 类型 | 上报                                                |
| --------------------------- | ---- | --------------------------------------------------- |
| `admin_portal_lcp_seconds`  | LCP  | `next/web-vitals` → `POST /api/v1/admin/web-vitals` |
| `admin_portal_cls`          | CLS  | 同上                                                |
| `admin_portal_fid_seconds`  | FID  | 同上                                                |
| `admin_portal_ttfb_seconds` | TTFB | 同上                                                |

> admin-portal 本身就是 P6 阶段，Web Vitals 在建站时即接入（与 teacher-portal P6 同步）。

### 6.5 Tracer（OTel browser SDK，P6）

```typescript
// 复用 packages/shared-ts/src/tracer.ts（Shell 暴露）
import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
// BatchSpanProcessor → OTLP exporter → collector → Tempo
// 自动埋点：fetch、XMLHttpRequest、document load、user interaction
// admin-portal 通过 Shell 的 TracerProvider 注入，不重复初始化
```

### 6.6 健康检查

| 端点              | 用途                   | 实现                                                            |
| ----------------- | ---------------------- | --------------------------------------------------------------- |
| `GET /api/health` | Dockerfile HEALTHCHECK | Next.js Route Handler，返回 `{ status: 'ok', ts: Date.now() }`  |
| `GET /api/ready`  | K8s readinessProbe     | 检查 `process.env.TEACHER_PORTAL_URL` 可达（依赖 Shell 已启动） |

### 6.7 优雅关闭

Next.js 无长连接（admin-portal 不消费 WebSocket/SSE），无需特殊处理。

### 6.8 横切关注点对齐清单（汇总）

| 对齐项                | teacher-portal 实现                            | admin-portal 对齐方式                                   |
| --------------------- | ---------------------------------------------- | ------------------------------------------------------- |
| 权限校验              | `usePermission()` + `<RequirePermission>`      | 复用 Shell 暴露，权限点用 `IAM_*` / `ADMIN_*` / `ORG_*` |
| 错误码前缀统一        | ApiClient 按 `error.code` 前缀路由 i18n        | 复用 Shell 暴露的 ApiClient，前缀集缩减为 4 个          |
| logger                | `packages/shared-ts/src/logger.ts`             | 复用 Shell 暴露，scope 字段固定为 `'admin'`             |
| metrics               | Web Vitals → `POST /api/v1/admin/web-vitals`   | admin-portal 本身 P6，建站即接入                        |
| tracer                | OTel browser SDK（Shell 初始化）               | 复用 Shell 的 TracerProvider，不重复初始化              |
| /healthz + /readyz    | Next.js `/api/health` + Dockerfile HEALTHCHECK | admin-portal 独立实现 Route Handler                     |
| 优雅关闭              | N/A（Next.js 无长连接）                        | N/A                                                     |
| 测试覆盖率 ≥ 80%      | Vitest + @testing-library/react + Playwright   | 同 teacher-portal                                       |
| Dockerfile 多阶段构建 | builder + runtime                              | 同 teacher-portal                                       |
| Zod 输入验证          | react-hook-form + zodResolver                  | 同 teacher-portal                                       |
| GlobalErrorFilter     | React ErrorBoundary + API 请求层               | 复用 Shell 暴露的 ErrorBoundary                         |
| 设计令牌三层          | `packages/ui-tokens/`（Shell 暴露）            | 复用 Shell 暴露，不重复引入                             |
| A11y 工具集           | `packages/ui-components/`（Shell 暴露）        | 复用 Shell 暴露                                         |

## 7. 共享组件库（复用 Shell 暴露 + admin 特有）

### 7.1 复用 Shell 暴露的组件

| 组件                                       | 用途                               | 来源                                        |
| ------------------------------------------ | ---------------------------------- | ------------------------------------------- |
| `AppShell`                                 | 左侧栏 + 主内容区布局              | teacher-portal Shell 暴露                   |
| `RequirePermission`                        | L3 组件级视口控制                  | teacher-portal Shell 暴露                   |
| `ErrorBoundary`                            | React 渲染异常兜底                 | teacher-portal Shell 暴露                   |
| `Loading`                                  | 骨架屏（Skeleton）                 | teacher-portal Shell 暴露                   |
| `Empty`                                    | 空态（插画 + 文案 + CTA）          | teacher-portal Shell 暴露                   |
| `Modal` / `Dialog`                         | 全局 Modal                         | teacher-portal Shell 暴露（shadcn/ui）      |
| `Toast`                                    | 全局 toast                         | teacher-portal Shell 暴露（sonner）         |
| `Button` / `Input` / `Select` / `Textarea` | 基础表单                           | teacher-portal Shell 暴露（shadcn/ui）      |
| `DataTable`                                | 表格（排序/分页/筛选）             | teacher-portal Shell 暴露（TanStack Table） |
| `Chart`                                    | 图表封装（recharts）               | teacher-portal Shell 暴露                   |
| `A11y` 工具集                              | useA11yId / mergeA11yProps 等      | teacher-portal Shell 暴露                   |
| `Form`                                     | react-hook-form + zodResolver 封装 | teacher-portal Shell 暴露                   |

### 7.2 admin-portal 特有组件（新建）

| 组件                   | 用途                                    | 实现要点                                                                                                                     |
| ---------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `UserManagementTable`  | 用户管理表格（列表/筛选/分页/批量操作） | 基于 Shell 的 `DataTable` 封装；列：邮箱/姓名/角色/状态/数据范围/最后登录；筛选：角色/状态/组织；批量：启用/禁用/分配角色    |
| `RolePermissionMatrix` | 角色-权限矩阵编辑器（checkbox 网格）    | 行=角色，列=权限（按 resource 分组）；勾选触发 `PUT /api/v1/iam/roles/:id/permissions`；系统预置角色只读                     |
| `ViewportConfigEditor` | 视口配置编辑器（拖拽排序 + 权限绑定）   | 基于 `@dnd-kit` 拖拽排序；每行：key/label/route/requiredPermission/scope/isVisible；保存触发 `PUT /api/v1/iam/viewports/:id` |
| `PlatformMonitor`      | 平台监控（Grafana iframe embed）        | `<iframe>` 嵌入 Grafana 面板（按 serviceName 切换）；备选：recharts 渲染 `MonitoringMetricsViewModel`                        |

### 7.3 不使用的组件（明确排除）

| 组件             | 归属           | 排除原因           |
| ---------------- | -------------- | ------------------ |
| `RichTextEditor` | teacher-portal | 管理端无富文本场景 |
| `ExamTaking`     | student-portal | 管理端无作答场景   |
| `SSEViewer`      | teacher-portal | 管理端不消费 SSE   |
| `ChildSwitcher`  | parent-portal  | 管理端无多子女切换 |

## 8. 共享 Hooks（复用 Shell 暴露 + admin 特有）

### 8.1 复用 Shell 暴露的 Hooks

| Hook                  | 职责                                                 |
| --------------------- | ---------------------------------------------------- |
| `useAuth()`           | 会话状态（user/token/refresh/login/logout）          |
| `usePermission()`     | 权限查询（hasPermission/hasAny/hasAll + dataScope）  |
| `useViewports(scope)` | 视口列表（按 scope 过滤，admin-portal 传 `'admin'`） |
| `useApi()`            | ApiClient 实例（注入 token + 401 处理）              |
| `useA11yId()`         | 唯一 ARIA ID 生成                                    |
| `useAriaLive()`       | aria-live 区域管理                                   |
| `useToast()`          | 全局 toast（Zustand ui-store）                       |

### 8.2 admin-portal 特有业务 Hooks（新建）

| Hook                         | 职责                                             |
| ---------------------------- | ------------------------------------------------ |
| `useUsers(filter)`           | 用户列表查询（含筛选）                           |
| `useUser(userId)`            | 用户详情                                         |
| `useCreateUser()`            | 创建用户 mutation                                |
| `useUpdateUser()`            | 更新用户 mutation                                |
| `useToggleUserStatus()`      | 启用/禁用用户 mutation                           |
| `useRoles(filter)`           | 角色列表查询                                     |
| `useRole(roleId)`            | 角色详情（含权限列表）                           |
| `useCreateRole()`            | 创建角色 mutation                                |
| `useUpdateRolePermissions()` | 更新角色权限 mutation（RolePermissionMatrix 用） |
| `usePermissions()`           | 全量权限列表（30min 缓存）                       |
| `useViewportsConfig(scope)`  | 视口配置列表（可编辑）                           |
| `useUpdateViewport()`        | 更新视口配置 mutation（ViewportConfigEditor 用） |
| `useOrganization(parentId)`  | 组织树查询                                       |
| `useMonitoringMetrics()`     | 平台监控指标（60s 轮询）                         |
| `useActiveSessionsStats()`   | 用户活动统计（5min 轮询）                        |

## 9. 设计令牌三层（复用 Shell 暴露）

admin-portal **不重复建立**设计令牌，通过 Shell 暴露的 `packages/ui-tokens/` 消费。三层令牌结构见 [teacher-portal 阶段2 §9](../../teacher-portal/docs/02-architecture-design.md#9-设计令牌三层packagesui-tokens待建ai07-维护)。

**强制规则**（project_rules §3.10，admin-portal 同样遵守）：

- 禁止 `#hex` 字面量（ESLint `no-restricted-syntax`）
- 禁止 `'Inter'`/`'Fraunces'`/`'JetBrains Mono'` 字面量（ESLint `design-tokens/no-hardcoded-fonts`）
- 禁止 `font-size: Npx`（用 `var(--font-size-1~9)`）
- 禁止 Tailwind 任意值 `w-[Npx]`（用 `--space-*` 或默认阶梯）

## 10. 与其他模块的交互点（契约清单）

| 方向   | 对方服务             | 协议               | 接口/事件                                   | 用途                         | 阶段 |
| ------ | -------------------- | ------------------ | ------------------------------------------- | ---------------------------- | ---- |
| 调用   | api-gateway          | HTTP/REST          | `/api/v1/*` 代理（经 Shell rewrites）       | 全部业务请求                 | P1+  |
| 被调用 | —                    | —                  | —                                           | 前端不暴露接口给其他服务     | —    |
| 消费   | iam                  | HTTP（经 Gateway） | `/iam/*`（含用户/角色/权限/视口 CRUD）      | 用户/角色/权限/视口管理      | P2+  |
| 消费   | teacher-bff          | HTTP（经 Gateway） | `/admin/*`                                  | 平台监控、统计聚合           | P6+  |
| 消费   | msg                  | HTTP（经 Gateway） | `/notifications/*`                          | 通知中心                     | P5+  |
| 依赖   | coord 维护           | —                  | `packages/shared-proto`                     | TS 类型（仅 contracts 部分） | P1+  |
| 依赖   | coord 维护           | —                  | `packages/shared-ts`（待建）                | ApiClient/Logger/通用工具    | P6+  |
| 依赖   | ai07 维护            | —                  | `packages/ui-tokens`（待建）                | 三层设计令牌                 | P6+  |
| 依赖   | ai07 维护            | —                  | `packages/ui-components`（待建）            | shadcn + 共享组件            | P6+  |
| 依赖   | ai07 维护            | —                  | `packages/hooks`（待建）                    | usePermission/useAuth 等     | P6+  |
| 依赖   | coord 维护           | —                  | `packages/contracts`（待建）                | Permissions 常量 + 类型      | P6+  |
| 依赖   | teacher-portal Shell | —                  | Shell 暴露的 AppShell + 共享依赖 + rewrites | 宿主环境                     | P6+  |

> **proto 不直接消费**：前端不调用 gRPC，BFF 把 gRPC 聚合为 REST 暴露给前端。前端仅消费 `packages/contracts/src/permissions.ts` 中的权限点常量（TS 文件，非 proto 生成）。

## 11. 风险与假设

### 11.1 假设

1. **假设 coord 建立 `packages/shared-ts`、`packages/contracts`**：包含 ApiClient、Logger、Permissions 常量、通用类型。若 coord 未建立，ai07 自行在 `apps/teacher-portal/src/shared/` 内实现（已在 teacher-portal 阶段2 计划中），admin-portal 通过 MF shared 消费。
2. **假设 iam 提供用户/角色/权限/视口 CRUD 端点**：`IAM_USER_READ/CREATE/UPDATE`、`IAM_ROLE_READ`、`IAM_PERMISSION_READ`、`IAM_VIEWPORT_READ` 及对应 REST 端点。当前已实现（known-issues §2.3 iam）。
3. **假设 teacher-portal Shell 已就绪**：AppShell + 共享依赖暴露 + MF 配置 + rewrites。admin-portal 是 P6 阶段，依赖 teacher-portal P2-P5 已完成。
4. **假设 Next.js 14+ Module Federation 2.0 稳定**：`@module-federation/nextjs-mf` 在 Next.js App Router 下可用。若不稳定，admin-portal 降级为独立部署（重复实现 AppShell）。
5. **假设 Grafana 可嵌入 iframe**：PlatformMonitor 组件用 `<iframe>` 嵌入 Grafana 面板。若 Grafana 配置了 `X-Frame-Options: DENY`，需协调 SRE 放开 iframe 嵌入白名单，或降级为 recharts 渲染监控指标。

### 11.2 技术风险

| 风险                    | 影响                                                        | 缓解                                                                                             |
| ----------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Shell 未就绪阻塞 admin  | admin-portal 是 P6 阶段，依赖 teacher-portal P2-P5 完成     | P6 启动前确认 Shell 已暴露 AppShell + 共享依赖；若 Shell 延迟，admin-portal 先用 mock Shell 开发 |
| MF SSR 对齐复杂         | Remote 在 SSR 时需 Shell 提供上下文                         | 优先 CSR，SSR 仅用于首屏 dashboard；MF 2.0 支持 SSR                                              |
| 共享依赖版本漂移        | Remote 与 Shell 的 react/react-dom 版本不一致导致运行时错误 | MF `shared.singleton: true` + CI 检查版本对齐                                                    |
| Token 刷新竞态          | 多请求同时 401 触发多次 refresh                             | 复用 Shell 的 ApiClient 全局单例 + refresh promise 复用                                          |
| 权限缓存陈旧            | 角色变更后前端 5min 内仍用旧权限                            | iam 角色变更后管理员手动 invalidate；admin-portal 本身就是管理端，可主动触发                     |
| 数据范围越权            | L3 校管理员看到 L5 系统管理员视角的数据                     | 所有列表 API 由后端强制注入 dataScope filter；前端 `AdminDataScopeFilter` 仅作 UI 提示           |
| Grafana iframe 嵌入失败 | PlatformMonitor 组件白屏                                    | 降级为 recharts 渲染 `MonitoringMetricsViewModel`                                                |
| 轮询对 BFF 压力         | 60s 监控轮询 + 5min 统计轮询增加 BFF 负载                   | 5min TTL 缓存命中率高；监控指标直连 Grafana iframe 不经过 BFF                                    |

### 11.3 未决设计决策（需 coord 仲裁）

> 以下 4 项与 teacher-portal 阶段2 §11.3 相同，admin-portal 跟随 teacher-portal 决策：

1. **packages 归属**：`ui-tokens` / `ui-components` / `hooks` 是 ai07 维护还是 coord 维护？建议：ai07 维护（前端专属），coord 仅维护 `shared-ts` / `contracts`（跨语言/跨服务）。
2. **GraphQL vs REST**：004 §11.3 提到 BFF GraphQL Yoga + DataLoader，但当前 teacher-bff 实现为 REST。前端 API 请求层是否需要 GraphQL client（urql/apollo）？建议：P2-P5 用 REST，P6 admin-portal 同样用 REST，未来 BFF 切 GraphQL 再统一引入。
3. **i18n key 命名**：`iam.error.IAM_INVALID_CREDENTIALS` 还是 `error.iam.invalid_credentials`？建议：`error.{{service}}.{{code_snake_case}}`，与错误码前缀对齐。
4. **MF 暴露粒度**：Shell 暴露整个 AppShell 还是暴露更细粒度的组件（Sidebar、Header、Content）？建议：暴露 AppShell 整体 + 各 Remote 自行决定内部布局。

## 12. coord 交叉审查所需信息

### 12.1 端口矩阵

| 端           | dev 端口 | 生产端口 | 备注                 |
| ------------ | -------- | -------- | -------------------- |
| admin-portal | 3003     | 3003     | Remote，挂载到 Shell |

> 与 [full-stack-runbook](../../../docs/standards/full-stack-runbook.md) 端口矩阵对齐。Shell（teacher-portal）在 3000，其余 Remote：student-portal 3001 / parent-portal 3002 / admin-portal 3003。

### 12.2 依赖的共享包

| 包              | 路径                      | 维护方       | 内容                                              |
| --------------- | ------------------------- | ------------ | ------------------------------------------------- |
| `shared-ts`     | `packages/shared-ts/`     | coord        | ApiClient、Logger、通用工具                       |
| `contracts`     | `packages/contracts/`     | coord        | Permissions 常量、ActionState 类型、UserInfo 类型 |
| `ui-tokens`     | `packages/ui-tokens/`     | ai07（建议） | 三层设计令牌                                      |
| `ui-components` | `packages/ui-components/` | ai07（建议） | shadcn + ErrorBoundary + RequirePermission        |
| `hooks`         | `packages/hooks/`         | ai07（建议） | usePermission、useAuth、useViewports              |

### 12.3 依赖的后端契约（需对应 AI 确认）

| 契约                                                                | 提供方                | 当前状态                         |
| ------------------------------------------------------------------- | --------------------- | -------------------------------- |
| `GET/POST/PUT /iam/users`、`GET /iam/roles`、`GET /iam/permissions` | iam                   | ✅ 已实现                        |
| `GET/PUT /iam/viewports`、`PUT /iam/viewports/:id`                  | iam                   | ✅ 已实现                        |
| `PUT /iam/roles/:id/permissions`                                    | iam                   | ⚠️ 待确认（角色-权限矩阵）       |
| `GET /admin/dashboard`、`GET /admin/monitoring/metrics`             | teacher-bff           | ✅ 已实现（复用）                |
| `GET /admin/stats/users`、`GET /admin/stats/active-sessions`        | teacher-bff           | ⚠️ 待确认                        |
| `POST /admin/web-vitals`                                            | teacher-bff           | ⚠️ 待确认（Web Vitals 上报端点） |
| `GET /notifications/*`                                              | msg                   | 📐 待 P5                         |
| Grafana 面板 iframe 嵌入                                            | SRE（infra/grafana/） | ⚠️ 待确认 X-Frame-Options        |

### 12.4 错误码前缀（前端 i18n 路由依赖）

前端不产生错误码，仅消费。admin-portal 涉及的前缀（需各服务确认不重叠）：

| 前缀           | 服务        | 状态                    |
| -------------- | ----------- | ----------------------- |
| `IAM_`         | iam         | ✅ 已用                 |
| `BFF_TEACHER_` | teacher-bff | ⚠️ 待确认               |
| `GW_`          | api-gateway | ✅ 已用                 |
| `NETWORK_`     | 前端        | ai07 自有（复用 Shell） |

### 12.5 不产生 Kafka 事件

admin-portal 不发布/消费 Kafka 事件，不消费 WebSocket/SSE 推送。所有数据通过 HTTP 轮询获取。

## 13. 实施路线（ai07 自用，P6 阶段）

### P6（admin-portal 建站 + 硬化）

1. **建 `apps/admin-portal/` 骨架**（Remote 角色）
   - `next.config.js` 配置 MF Remote（见 §1.2）
   - `package.json` 引入 `@module-federation/nextjs-mf` + 软链 `@edu/*` 共享包
   - `tsconfig.json` 沿用 `tsconfig.base.json`
   - `tailwind.config.js` 引入 `@edu/ui-tokens`
   - `Dockerfile` 多阶段构建（builder + runtime）
2. **实现用户/角色/权限/视口/组织/监控管理页面**
   - `/admin/dashboard` — 管理仪表盘（recharts 渲染统计图表）
   - `/admin/users` + `/admin/users/new` + `/admin/users/:id` — 用户管理（UserManagementTable + Form）
   - `/admin/roles` — 角色管理（RolePermissionMatrix）
   - `/admin/permissions` — 权限管理（DataTable 只读列表）
   - `/admin/viewports` — 视口配置（ViewportConfigEditor）
   - `/admin/organization` — 组织管理（树形 + DataTable）
   - `/admin/monitoring` — 平台监控（PlatformMonitor = Grafana iframe + recharts）
3. **实现 admin 特有业务 Hooks**（见 §8.2）
4. **接入 5 层状态管理**（复用 Shell 暴露的 nuqs/TanStack Query/Zustand/Zustand-UI/react-hook-form）
5. **接入 i18n**（next-intl，admin 命名空间）
6. **接入权限校验**（`usePermission()` + `<RequirePermission>`，按 §6.1 路由表）
7. **Web Vitals + OTel browser SDK 接入**（复用 Shell 的 TracerProvider，scope='admin'）
8. **A11y WCAG 2.2 AA 审计**（eslint-plugin-jsx-a11y error 级 + 手动审计）
9. **性能优化**（MF shared 单例验证、bundle 分析、5min 长缓存验证）
10. **补 Vitest 单测 + Playwright E2E**（覆盖率 ≥ 80%）
11. **补 `/api/health` + `/api/ready` Route Handler + Dockerfile HEALTHCHECK**

### P6 验收标准

- [ ] 所有 9 个路由页面可访问，权限校验生效
- [ ] MF shared 单例验证通过（react/react-dom/Zustand/TanStack Query 不重复实例化）
- [ ] Web Vitals 上报到 `POST /api/v1/admin/web-vitals`
- [ ] OTel browser SDK trace 上报到 collector
- [ ] A11y 审计 0 个 error 级违规
- [ ] 测试覆盖率 ≥ 80%
- [ ] `/api/health` + `/api/ready` 返回 200
- [ ] Dockerfile 多阶段构建，非 root 用户，HEALTHCHECK 配置

---

**AI Agent**: ai07 (admin-portal remote)
**Branch**: docs/admin-portal-stage1-stage2-design-ai07
**Coordinator**: coord-ai