# Portal Shell 数据抽象层与 GraphQL 安全加固设计 > 版本：v1.0 > 日期：2026-07-17 > 状态：待评审 > 关联： > > - [Portal Shell 插件化仪表盘设计 v2.1](./2026-07-14-portal-shell-widget-dashboard-design.md) > - [004 架构影响地图](../../architecture/004_architecture_impact_map.md) §16 portal-shell > - [0010 架构蓝图](../../architecture/0010_architecture.md) §4 数据流 > - [项目规则](../../.trae/rules/project_rules.md) §3.8 Controller 规范、§4 安全规范 --- ## 1. 背景与目标 ### 1.1 问题诊断 portal-shell v2.1 已完成 31 个内置插件的迁移，但所有插件在 `widgets///index.tsx` 中**直接内嵌 `gql` 模板字符串**调用 apollo-router： ```typescript // 当前形态（每个 widget 都这样写） const GET_MY_CHILDREN = gql` query GetMyChildren { myChildren { id name grade className avatar recentGrades { subject score } attendance { present total } homeworkCompletion { completed total } } } `; interface MyChildrenQueryData { myChildren: ChildInfo[]; } // 手写类型 export default function ChildOverview() { const { data, loading } = useWidgetQuery< MyChildrenQueryData, Record >(GET_MY_CHILDREN, {}); // ... UI } ``` 全项目扫描：**29 个 widget 文件，92 处 `gql` 字面量，92 处手写 `interface XxxQueryData`**。 由此引发四类问题： 1. **Schema 耦合**：widget 直接知道后端字段名与嵌套结构，后端 schema 变更需修改前端组件 2. **查询重复/碎片化**：相同领域查询散落在多个 widget，无集中管理 3. **跨域聚合在前端**：`myChildren` 一次查询跨 iam + core-edu + msg 三个子图，聚合责任落在前端 4. **缺少数据抽象层**：widget 既写 UI 又写数据获取，职责混淆，平均 150 行/文件 同时存在**未显式暴露但真实存在**的安全缺口： 5. **生产环境明文 query**：DevTools 可抓到完整 query 文本，攻击者可构造任意查询探测 schema 6. **无查询深度/复杂度限制**：可构造 `user { parent { user { parent {...} } } }` 递归攻击或 `first: 1000000` 放大攻击 7. **字段级 @auth 覆盖率未知**：敏感字段（`auditLogs.details`、`user.email`、`auditLog.ip`）是否都有角色守卫未审计 ### 1.2 国际业界对比 | 模式 | 谁在用 | 查询字符串位置 | 抽象程度 | | ---------------------------- | --------------------------- | --------------------------------- | --------------------------- | | Inline gql in component | 小型项目、demo | 散落在每个组件 | 无抽象（portal-shell 现状） | | Co-located documents + hooks | Apollo 官方推荐中大型项目 | `*.graphql` 文件按域聚合 | 文档层抽象 | | Typed SDK / API client | 大型企业（GitHub、Shopify） | 后端 codegen 出 SDK | 完全屏蔽 GraphQL | | Relay-style fragments | Meta、Medium | Fragment 容器 + 编译时 hoisting | 数据需求就近声明 | | BFF / Router 聚合 | 微服务架构 | 前端发粗粒度查询，BFF/Router 拆分 | 跨域聚合下沉 | portal-shell 当前已是**微服务 + Apollo Federation** 架构，却在前端层用了"最朴素形态"。架构-代码不匹配是核心矛盾：**架构越复杂，前端的抽象责任应该越轻**，而当前正好相反。 ### 1.3 安全澄清 用户的三个直觉担忧澄清： - **"暴露数据库"**：GraphQL schema ≠ 数据库 schema。前端看到的是对外契约，不是 DB 表结构。但 DevTools 可抓到完整 query 文本，确实暴露"前端能用哪些字段"。搬到 `lib/api/` **不能**降低暴露面，**只能靠持久化查询**让生产环境只发 hash。 - **"串改"**：GraphQL 允许客户端任意构造查询，防线在 Router 层（持久化查询 manifest + 复杂度限制 + @auth）。与查询写在哪无关。 - **"注入"**：GraphQL 参数化（通过 `variables` 传递）+ 后端 ORM 参数化查询（Drizzle 默认），注入面基本为零。 ### 1.4 设计目标 把 portal-shell 的"组件内嵌 gql 字符串 + Apollo Client 薄包装"重构为"语义化 API 层 + 生产级 GraphQL 安全栈"，一次解决架构耦合与安全缺口两个维度： 1. **零 `gql` 字面量**：31 个 widget 全部迁移到 `lib/api/` 抽象层，widget 只调函数不发查询 2. **零手写类型**：所有 TypeScript 类型由 `graphql-codegen` 生成 3. **生产环境零明文 query**：Apollo Router 启用 APQ + manifest 校验，生产模式拒绝 manifest 之外的查询 4. **深度/复杂度限制**：max_depth = 10，max_cost = 1000 5. **字段级 @auth 全覆盖**：审计 7 个子图，敏感字段补齐守卫 6. **widget 平均行数下降**：从 ~150 行降至 ≤80 行，UI 为主 ### 1.5 非目标 - ❌ 跨域聚合下沉到 Router（@requires 指令方案，独立 spec 处理） - ❌ 子图 schema 重构（`myChildren` 的字段归属调整） - ❌ 性能优化（缓存策略、批合并等，独立 spec） - ❌ 移除 `useWidgetQuery` / `useWidgetMutation`（保留作为底层 Hook，新 API 层在其之上） - ❌ 第三方插件 SDK 设计（未来插件契约 spec 再做） - ❌ 引入 Relay（重写成本太高，Apollo 已够用） - ❌ fragment 共享（先看实际重复程度，YAGNI） --- ## 2. 整体架构 ### 2.1 四层分层 ``` ┌─────────────────────────────────────────────────────────────┐ │ Widget 层（UI） │ │ src/widgets///index.tsx │ │ 职责：渲染、交互、URL 状态 │ │ 禁止：gql 字面量、Apollo Client 直接调用、手写 QueryData 类型 │ └─────────────────────────────────────────────────────────────┘ ↓ 调用 ┌─────────────────────────────────────────────────────────────┐ │ API 层（语义化函数） │ │ src/lib/api/.ts │ │ 职责：领域语义封装、错误归一化、返回领域模型 │ │ 导出：useParentChildren(), useAuditLogs(filter), ... │ └─────────────────────────────────────────────────────────────┘ ↓ 调用 ┌─────────────────────────────────────────────────────────────┐ │ Operations 层（GraphQL 文档） │ │ src/lib/api/operations/.graphql.ts │ │ 职责：集中存放 gql 文档、按 domain 分文件 │ │ 导出：GET_MY_CHILDREN_DOC, GET_AUDIT_LOGS_DOC, ... │ └─────────────────────────────────────────────────────────────┘ ↓ 调用 ┌─────────────────────────────────────────────────────────────┐ │ Hook 层（保留，不动） │ │ src/lib/useWidgetQuery.ts / useWidgetMutation.ts │ │ 职责：Apollo Client 包装、缓存策略、SWR 刷新 │ └─────────────────────────────────────────────────────────────┘ ↓ HTTPS（生产发 hash，开发发明文） ┌─────────────────────────────────────────────────────────────┐ │ apollo-router（:3000） │ │ - APQ + manifest 校验 │ │ - 深度/复杂度限制 │ │ - 子图分发 │ └─────────────────────────────────────────────────────────────┘ ↓ gRPC / Federation 8 个业务子图（iam / config-service / classes / core-edu / content / msg / data-ana / ai） ``` **关键原则**：依赖单向向下，widget 不知道 GraphQL 字段名，API 层不知道 UI 细节，Hook 层保持现状作为底层抽象。 ### 2.2 lib/api/ 目录结构 ``` apps/portal-shell/src/lib/api/ ├─ index.ts # 统一出口（barrel），按 domain re-export ├─ operations/ # GraphQL 文档集中存放 │ ├─ parent.graphql.ts # myChildren / leaveApproval │ ├─ admin.graphql.ts # users / roles / auditLogs / invitationCodes / school / plugins │ ├─ teacher.graphql.ts # lessonPlan / questionBank / textbook / schedulingRules │ ├─ student.graphql.ts # errorBook / learningPath / elective / aiTutor │ ├─ universal.graphql.ts # grades / homework / schedule / attendance / exams / notifications / announcements │ ├─ sidebar.graphql.ts # classSelector / childSelector / termSwitcher / quickActions │ └─ topbar.graphql.ts # notificationBell / userMenu / globalSearch / localeSwitcher ├─ parent.ts # useParentChildren, useLeaveApprovals, useApproveLeave ├─ admin.ts # useUsers, useAuditLogs, useCreateInvitationCode, ... ├─ teacher.ts # useLessonPlans, useSaveLessonPlan, useQuestionBank, ... ├─ student.ts # useErrorBook, useLearningPath, ... ├─ universal.ts # useGrades, useHomework, useSchedule, ... ├─ sidebar.ts # useClasses, useChildren, useTerms, ... ├─ topbar.ts # useNotifications, useCurrentUser, ... ├─ internal.ts # 共享工具（normalizeError、类型定义） ├─ errors.ts # ApiError 类与 GraphQLErrorCode 枚举 ├─ types.ts # 共享类型（Pagination、Filter 等） └─ __tests__/ # API 层单测 ├─ parent.test.ts ├─ admin.test.ts └─ ... ``` **domain 划分原则**：与 Registry.tsx 的 7 个分类（universal/sidebar/topbar/teacher/student/parent/admin）一一对应，便于查找。 ### 2.3 API 函数签名规范 ```typescript // 查询：返回领域模型（非 GraphQL 原始响应形状） export function useParentChildren(): UseQueryResult { const result = useWidgetQuery>( GET_MY_CHILDREN_DOC, {}, ); return { ...result, data: result.data?.myChildren ?? [], }; } // 带参数的查询 export function useAuditLogs( filter: AuditLogFilter, pagination: { limit: number; offset: number }, ): UseQueryResult { const result = useWidgetQuery( GET_AUDIT_LOGS_DOC, { filter, ...pagination }, ); return { ...result, data: result.data?.auditLogs.items ?? [], }; } // Mutation（hook 形态，因为 useWidgetMutation 是 React Hook） export function useCreateInvitationCode(): [ (input: CreateInvitationCodeInput) => Promise, UseMutationResult, ] { const [run, result] = useWidgetMutation< CreateInvitationCodeMutation, CreateInvitationCodeMutationVariables >(CREATE_INVITATION_CODE_DOC); const wrappedRun = async ( input: CreateInvitationCodeInput, ): Promise => { const { data } = await run({ input }); if (!data?.createInvitationCode) { throw new ApiError("Failed to create invitation code", "INTERNAL_ERROR"); } return data.createInvitationCode; }; return [wrappedRun, result]; } ``` **规范要点**： - 查询返回**领域模型**（`ChildSummary[]`），不是 GraphQL 原始响应（`{ myChildren: [...] }`），避免 schema 形状泄漏 - Mutation 包装为 hook，返回 `[wrappedRun, result]` 元组；`wrappedRun` 抛 `ApiError`，widget 在事件 handler 中 `try/catch` - 命名：查询与 Mutation 都用 `use` 前缀（`useParentChildren`、`useCreateInvitationCode`、`useApproveLeave`），保持 React Hook 规范 - 文件名 `.ts`，函数名 `use`（查询）/ `use`（Mutation） ### 2.4 graphql-codegen 集成 **配置文件**：`apps/portal-shell/codegen.ts` ```typescript import type { CodegenConfig } from "@graphql-codegen/cli"; const config: CodegenConfig = { schema: "http://localhost:3000/graphql", // apollo-router documents: "src/lib/api/operations/**/*.graphql.ts", generates: { "src/lib/api/__generated__/types.ts": { plugins: ["typescript", "typescript-operations"], }, "src/lib/api/__generated__/operations.ts": { plugins: ["typescript-react-apollo"], }, }, config: { withHooks: false, // 不生成 hooks（已有 useWidgetQuery） withComponent: false, preResolveTypes: true, skipTypename: true, exportTypeKeyOnly: true, }, }; export default config; ``` **生成产物**： - `__generated__/types.ts` — 所有 GraphQL 类型（替代手写的 `interface XxxQueryData`） - `__generated__/operations.ts` — `TypedDocumentNode` 类型化的 DocumentNode **生成时机**： - 开发：`pnpm run codegen:watch` 监听 `operations/*.graphql.ts` 变更 - CI：`pnpm run codegen` 在 typecheck 前执行，确保 `__generated__/` 最新 - 不提交 `__generated__/` 到 git（加入 .gitignore） ### 2.5 与现有代码的关系 | 现有 | 处置 | | -------------------------------------- | ----------------------------------------------------------- | | `useWidgetQuery` / `useWidgetMutation` | 保留，API 层在其上封装，不改签名 | | `PluginProps` / `PluginManifest` | 不动 | | `Registry.tsx` | 不动 | | 31 个 widget 的 `index.tsx` | 全量重构：删除 `gql` 字面量与手写类型，改调 `lib/api/` 函数 | | `.env.local` | 新增 `NEXT_PUBLIC_APOLLO_APQ=true`（开发可关） | | `next.config.js` | 新增 `codegen` 时机（prebuild） | --- ## 3. 迁移策略（全量迁移，不保留老代码） ### 3.1 迁移原则 - **一次性全量迁移**：31 个 widget 在 M2 阶段单 PR 完成，不保留老代码共存期 - **删除所有 `gql` 字面量**：迁移后 widget 中不得出现 `gql` 标签 - **删除所有手写 `interface XxxQueryData`**：由 codegen 生成的类型替代 - **删除 widget 对 `useWidgetQuery`/`useWidgetMutation` 的直接调用**：改通过 `lib/api/` 间接使用 - **不合并到 main 直到 M2 完成**：避免半迁移状态 - **全量迁移前在分支上跑完整测试套件**：30 个现有测试 + 新增 API 层测试必须全绿 ### 3.2 单个 widget 迁移模板（5 步） 以 `child-overview` 为例： ```typescript // Step 1: 抽取 GraphQL 文档到 operations/parent.graphql.ts import { gql } from "@apollo/client"; export const GET_MY_CHILDREN_DOC = gql` query GetMyChildren { myChildren { id name grade className avatar recentGrades { subject score } attendance { present total } homeworkCompletion { completed total } } } `; // Step 2: codegen 生成类型（自动，无需手写） // 文件：src/lib/api/__generated__/types.ts // export type GetMyChildrenQuery = { myChildren: Array<{ id: string, name: string, ... }> }; // Step 3: lib/api/parent.ts 写语义函数 import type { GetMyChildrenQuery } from "@/lib/api/__generated__/types"; import { GET_MY_CHILDREN_DOC } from "@/lib/api/operations/parent.graphql"; import { useWidgetQuery } from "@/lib/useWidgetQuery"; export interface ChildSummary { id: string; name: string; grade: string; className: string; avatar: string; recentGrades: Array<{ subject: string; score: number }>; attendance: { present: number; total: number }; homeworkCompletion: { completed: number; total: number }; } export function useParentChildren(): UseQueryResult { const result = useWidgetQuery>( GET_MY_CHILDREN_DOC, {}, ); return { ...result, data: (result.data?.myChildren ?? []) as ChildSummary[], }; } // Step 4: widget/index.tsx 改造（150 行 → 60 行） import { useParentChildren } from "@/lib/api"; export default function ChildOverview(_props: PluginProps): React.ReactElement { const { data: children, loading } = useParentChildren(); // ... 只剩 UI 渲染逻辑 } // Step 5: 删除 widget 中原有的 gql、interface、类型断言 ``` ### 3.3 31 个 widget 全量迁移清单 | 批次 | widget | domain | 子图 | 备注 | | ---- | -------------------- | --------- | ------------------- | --------------------- | | 全量 | grades-widget | universal | core-edu | 单查询 | | 全量 | homework-widget | universal | core-edu | 查询+分页 | | 全量 | schedule-widget | universal | core-edu | 单查询 | | 全量 | attendance-widget | universal | core-edu | 单查询 | | 全量 | exams-widget | universal | core-edu | 单查询 | | 全量 | notifications-widget | universal | msg | 查询+分页 | | 全量 | announcements-widget | universal | msg | 查询+分页 | | 全量 | class-selector | sidebar | classes | 单查询 | | 全量 | child-selector | sidebar | iam | 单查询 | | 全量 | term-switcher | sidebar | config-service | 单查询 | | 全量 | quick-actions | sidebar | iam | 单查询 | | 全量 | notification-bell | topbar | msg | 单查询 | | 全量 | user-menu | topbar | iam | 单查询 | | 全量 | global-search | topbar | 全域 | 特殊处理 | | 全量 | locale-switcher | topbar | config-service | 单查询 | | 全量 | lesson-plan-editor | teacher | content | 查询+mutation | | 全量 | question-bank | teacher | content | 查询+分页 | | 全量 | textbook-manager | teacher | content | 查询+mutation | | 全量 | scheduling-rules | teacher | classes | 查询+mutation | | 全量 | error-book | student | core-edu | 单查询 | | 全量 | learning-path | student | ai | 单查询 | | 全量 | elective-selector | student | classes | 单查询 | | 全量 | ai-tutor | student | ai+core-edu+content | 跨域聚合 | | 全量 | child-overview | parent | iam+core-edu+msg | 跨域聚合 | | 全量 | leave-approval | parent | iam+msg | 跨域聚合 | | 全量 | user-management | admin | iam | 查询+mutation | | 全量 | rbac-manager | admin | iam | 查询+mutation（敏感） | | 全量 | audit-logs | admin | iam | 查询+分页 | | 全量 | invitation-codes | admin | iam | 查询+mutation | | 全量 | school-settings | admin | config-service | 查询+mutation | | 全量 | plugin-manager | admin | config-service | 查询+mutation | **3 个跨域聚合插件**（child-overview / leave-approval / ai-tutor）本次仅迁移到 API 层，**不做 @requires 下沉**（属下一 spec 范围）。 --- ## 4. 持久化查询实施 ### 4.1 Apollo Client 端配置 ```typescript // apps/portal-shell/src/lib/apollo-client.ts import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client"; import { createPersistedQueryLink } from "@apollo/client/link/persisted-queries"; import { sha256 } from "crypto-hash"; const httpLink = new HttpLink({ uri: "/api/graphql" }); // 开发模式可关闭 APQ 便于调试 const enableApq = process.env.NEXT_PUBLIC_APOLLO_APQ !== "false"; const link = enableApq ? createPersistedQueryLink({ sha256 }).concat(httpLink) : httpLink; export const apolloClient = new ApolloClient({ link, cache: new InMemoryCache(), }); ``` ### 4.2 Persisted Query Manifest 生成 **构建期生成 manifest**（生产用）： ```typescript // apps/portal-shell/scripts/generate-pq-manifest.ts import { print } from "graphql"; import { sha256 } from "crypto-hash"; import * as fs from "node:fs"; import * as path from "node:path"; import { operations } from "@/lib/api/operations"; async function generateManifest(): Promise { const manifest: Record = {}; for (const [name, doc] of Object.entries(operations)) { const query = print(doc); const hash = await sha256(query); manifest[hash] = query; } const outPath = path.resolve(process.cwd(), "public/pq-manifest.json"); fs.writeFileSync(outPath, JSON.stringify(manifest, null, 2)); console.log( `✓ PQ manifest generated: ${Object.keys(manifest).length} queries`, ); } generateManifest().catch((err) => { console.error(err); process.exit(1); }); ``` **接入流程**： - `pnpm --filter @edu/portal-shell run build` 前自动执行 `generate-pq-manifest` - manifest 部署到 apollo-router 容器的 `/etc/apollo-router/pq-manifest.json` - Router 配置加载该 manifest，生产模式拒绝 manifest 之外的查询 ### 4.3 apollo-router 配置 ```yaml # infra/apollo-router/router.yaml persisted_queries: enabled: true # 生产：仅接受 manifest 内的 hash require_manifest: ${env.APOLLO_REQUIRE_PQ_MANIFEST::false} manifest_path: /etc/apollo-router/pq-manifest.json limits: max_depth: 10 max_cost: 1000 cost_multiplicator: # 基础字段 = 1 default: 1 # 列表字段按 first 参数计费 list_field: 0.1 sandbox: enabled: ${env.APOLLO_ROUTER_SANDBOX::true} listen: 0.0.0.0:3000 # 生产关闭 introspection supergraph: introspection: ${env.APOLLO_ROUTER_INTROSPECTION::true} # 生产仅允许 POST csrf: enabled: true ``` ### 4.4 环境变量矩阵 | 环境 | `NEXT_PUBLIC_APOLLO_APQ` | `APOLLO_REQUIRE_PQ_MANIFEST` | `APOLLO_ROUTER_INTROSPECTION` | 效果 | | -------- | ------------------------ | ---------------------------- | ----------------------------- | ---------------------------------------------------------------- | | 本地 dev | `false` | `false` | `true` | 前端发明文，Router 接受任意查询（调试方便） | | 测试环境 | `true` | `false` | `false` | 前端发 hash，Router 接受未知 hash 回退明文，关闭 introspection | | 生产 | `true` | `true` | `false` | 前端发 hash，Router 拒绝 manifest 之外的查询，关闭 introspection | --- ## 5. GraphQL 安全加固 ### 5.1 深度/复杂度限制 **深度限制 max_depth = 10**： - 当前最深查询 4 层（`myChildren.recentGrades.subject`） - 留 6 层余量给未来扩展 - 超过返回 `QUERY_DEPTH_EXCEEDED` 错误 **复杂度限制 max_cost = 1000**： - 计费规则： - 标量字段：0 - 对象字段：1 - 列表字段：`first × 0.1`（`auditLogs(first: 100)` = 10 cost） - 嵌套列表：累乘（极少见，触发即警告） - 超过返回 `QUERY_COMPLEXITY_EXCEEDED` 错误 ### 5.2 字段级 @auth 审计 **审计范围**：8 个子图的所有 Query/Mutation/Field resolver **审计方法**： 1. 用 `pnpm run arch:query -- symbol-refs "@ResolveField"` 列出所有字段 resolver 2. 用 `pnpm run arch:query -- symbol-refs "@Query"` 列出所有 Query 3. 用 `pnpm run arch:query -- symbol-refs "@Mutation"` 列出所有 Mutation 4. 逐个核查是否有 `@RequirePermission()` 或字段级 `@auth` 指令 **审计输出**：`docs/security/graphql-auth-audit-2026-07.md` 格式： ```markdown | 子图 | 字段 | 当前守卫 | 期望守卫 | 状态 | | -------- | ----------------- | -------------------------------- | ---------------------------------------- | ------- | | iam | users | @RequirePermission('user:read') | 同 | ✅ | | iam | auditLogs.details | 无 | @RequirePermission('audit:read:details') | ❌ 补齐 | | core-edu | grades | @RequirePermission('grade:read') | 同 | ✅ | ``` **补齐策略**： - 仅修改 NestJS resolver 的装饰器，不动 schema 文件结构 - 装饰器缺失的字段补 `@RequirePermission()` - 敏感字段（`details`、`ip`、`email`、`phone`）补字段级 `@auth(requires: 'xxx')` ### 5.3 其他加固 | 项 | 措施 | 配置位置 | | ------------- | --------------------------- | --------------------------------------- | | Introspection | 生产关闭 | `router.yaml: supergraph.introspection` | | GET 方法查询 | 生产关闭（仅允许 POST） | `router.yaml: csrf.enabled` | | 批查询 | 限制 batch size ≤ 5 | `router.yaml: limits.max_batch_size` | | 文件上传 | 单文件 ≤ 10MB（如未来需要） | apollo-router upload plugin | --- ## 6. 错误处理 ### 6.1 统一错误类型 ```typescript // apps/portal-shell/src/lib/api/errors.ts export class ApiError extends Error { constructor( message: string, public readonly code: GraphQLErrorCode, public readonly statusCode: number = 500, public readonly fields?: string[], ) { super(message); this.name = "ApiError"; } } export type GraphQLErrorCode = | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION_ERROR" | "QUERY_DEPTH_EXCEEDED" | "QUERY_COMPLEXITY_EXCEEDED" | "PERSISTED_QUERY_NOT_FOUND" | "INTERNAL_ERROR"; ``` ### 6.2 API 层错误归一化 ```typescript // lib/api/internal.ts import { ApolloError } from "@apollo/client"; import { ApiError, GraphQLErrorCode } from "./errors"; export function normalizeError(error: ApolloError): ApiError { const gqlError = error.graphQLErrors?.[0]; const code = (gqlError?.extensions?.code ?? "INTERNAL_ERROR") as GraphQLErrorCode; const statusCode = (gqlError?.extensions?.statusCode ?? 500) as number; return new ApiError(gqlError?.message ?? error.message, code, statusCode); } ``` ### 6.3 Widget 层错误处理 - 查询类：`useWidgetQuery` 已返回 `{ error }`，widget 显示 `` 组件（已有） - Mutation 类：API 层返回的 `run` 函数抛 `ApiError`，widget 在 onClick/onChange 等事件 handler 中用 `try/catch` 捕获并显示 toast - 边界场景： - 网络断开 → `NetworkError`，显示重试按钮 - 401 → 自动跳登录（已有逻辑） - 403 → 显示"无权限"提示 - 持久化查询未命中 → 自动回退明文（Apollo Client 内置） ### 6.4 不做的事 - ❌ 不引入全局 error boundary（已有） - ❌ 不重试机制（已有 SWR 刷新） - ❌ 不做错误埋点（已有 observability） --- ## 7. 测试策略 ### 7.1 测试金字塔 ``` ┌─────────────┐ │ E2E (5) │ 关键用户流（登录→看孩子→审批） └─────────────┘ ┌───────────────────┐ │ Integration (15) │ API 函数 + Apollo Mock └───────────────────┘ ┌───────────────────────────┐ │ Unit (40+ existing) │ Widget 渲染、API 函数纯逻辑 └───────────────────────────┘ ``` ### 7.2 新增测试 **API 层单测（lib/api/**tests**/）**： - 每个 domain 一个测试文件，覆盖所有导出函数 - 用 `MockedProvider` mock Apollo Client - 断言：返回值形状、错误归一化、参数传递 ```typescript // 示例：parent.test.ts it("useParentChildren returns normalized ChildSummary[]", async () => { const mocks = [ { request: { query: GET_MY_CHILDREN_DOC }, result: { data: { myChildren: [{ id: "1", name: "Tom", ... }] } }, }, ]; renderHook(() => useParentChildren(), { wrapper: mockWrapper(mocks) }); // ... await waitFor(() => expect(result.current.data).toHaveLength(1)) }); ``` **Widget 集成测试（迁移后保留）**： - 现有 30 个测试用例不破坏 - 每个 widget 增加一个"API 层 mock"集成测试 **安全栈测试**： - APQ 行为测试：hash 命中、未命中回退、manifest 拒绝 - 深度限制测试：构造 11 层查询应被拒 - 复杂度限制测试：构造 `first: 100000` 应被拒 - @auth 测试：无 token 访问敏感字段应 403 ### 7.3 测试覆盖率目标 - API 层：≥ 90% - Widget 层：维持现状（≥ 70%） - 安全栈：100%（关键路径） --- ## 8. 实施阶段 ### 8.1 阶段划分 ``` M1: 基础设施搭建 ──── M2: 31 插件全量迁移 ──── M3: 安全加固 ──── M4: 文档同步 ``` ### 8.2 各阶段交付物 | 阶段 | 范围 | 交付物 | 验收 | | ------ | --------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------- | | **M1** | 基础设施 | `lib/api/` 骨架、codegen 配置、errors.ts、operations/ 7 个 domain 文件（仅 gql 文档）、单测脚手架 | typecheck 通过、空骨架可跑 | | **M2** | 31 插件全量迁移 | 7 个 domain API 文件、31 个 widget 改造、删除所有老 gql 字面量、APQ Client 配置 | 31 插件测试通过、`gql` 字面量数 = 0 | | **M3** | 安全加固 | apollo-router router.yaml、PQ manifest 生成脚本、@auth 审计与补齐、深度/复杂度限制、安全测试 | 生产 PQ 生效、深度/复杂度测试通过 | | **M4** | 文档同步 | 004 新增"前端数据访问层"章节、known-issues §2.17 追加经验、security 审计报告、arch.db 更新 | 文档 review | ### 8.3 关键依赖与并行性 - M1 必须先完成（其他阶段依赖骨架） - M2 依赖 M1，单 PR 完成 - M3 依赖 M2（manifest 需要全部 operations 文件就绪） - M4 在 M3 完成后 ### 8.4 风险与缓解 | 风险 | 缓解 | | ------------------------------- | --------------------------------------------------------------------- | | codegen 与 NestJS schema 不同步 | CI 在 typecheck 前强制执行 `pnpm run codegen`，schema 变更触发通知 | | APQ manifest 漏注册新 query | manifest 由构建时自动生成，不手动维护 | | 全量迁移触发隐藏 bug | M2 完成前不合并 main，分支跑完整测试套件（30 现有 + 新增 API 层测试） | | @auth 补齐影响现有功能 | 先在测试环境部署，跑全量 E2E 再上生产 | | persisted query 在 SSR 失效 | Apollo Client 配置 `ssrMode: false` + 客户端 hydrate（已有） | | M2 单 PR 体积过大 | 提交按 domain 分 commit（7 个 commit），便于 review 与回滚 | --- ## 9. 验收指标 | 维度 | 当前 | 目标 | | ----------------------------- | ------- | -------------------- | | 组件中 `gql` 字面量 | 92 处 | 0 处 | | 手写 `interface XxxQueryData` | 92 处 | 0 处（全 codegen） | | 插件平均行数 | ~150 行 | ≤ 80 行（UI 为主） | | 生产环境明文 query | 92 处 | 0 处（全 hash） | | 敏感字段 @auth 覆盖率 | 未知 | 100%（审计后补齐） | | 查询复杂度上限 | 无 | 单 query ≤ 1000 cost | | 查询深度上限 | 无 | max_depth = 10 | | API 层测试覆盖率 | 0% | ≥ 90% | | 现有 30 个测试 | 30/30 | 30/30（不破坏） | --- ## 10. 关联约束 ### 10.1 项目规则遵循 - §3.4 TS 规则：禁 `any`、禁 `as`（除 `unknown` 转换）、显式返回类型、`import type` - §3.8 Controller 规范：每个 Query/Mutation 必须有 `@RequirePermission()` - §3.10 设计令牌规范：新增代码不引入硬编码颜色/字体/字号 - §4 安全规范：JWT 校验、CORS 白名单、限流 - §14.2 模块边界：仅改 portal-shell + apollo-router 配置 + 子图 @auth 装饰器级修改 ### 10.2 与 v2.1 架构原则对齐 - "DataScope 跨服务数据需求必须使用 @requires 运行时解析" → 本 spec 不做（属下一 spec），但本 spec 的 API 层为未来 @requires 下沉做好准备 - "外部查询必须且只能通过 Apollo Router 聚合 GraphQL" → 本 spec 强化此约束（持久化查询） - "BFF 层不得包含手动聚合代码" → 本 spec 在 widget 层引入 API 抽象，与 BFF 层职责对齐 --- ## 11. 后续规划（不在本 spec 范围） 1. **跨域聚合下沉**：将 `myChildren` 等 3 个跨域查询用 @requires 指令下沉到 apollo-router 2. **fragment 共享**：观察 API 层稳定后的查询重复程度，决定是否引入 GraphQL fragment 3. **第三方插件 SDK**：基于 `lib/api/` 暴露的语义化函数，设计第三方插件契约 4. **性能优化**：批合并、缓存策略、预取策略 5. **查询埋点**：在 API 层注入 metrics，监控查询性能与失败率 --- ## 12. 术语表 | 术语 | 含义 | | ------------------- | --------------------------------------------------------------------- | | APQ | Automatic Persisted Queries，Apollo Client 自动持久化查询机制 | | manifest | persisted query hash → query 文本的白名单映射 | | @auth | NestJS 字段级权限装饰器 | | @requires | Apollo Federation 指令，子图声明跨域字段依赖 | | domain | 业务领域划分（universal/sidebar/topbar/teacher/student/parent/admin） | | operations | GraphQL 查询文档集合（gql 字符串） | | codegen | graphql-codegen，根据 schema 与 operations 自动生成 TypeScript 类型 | | `useWidgetQuery` | portal-shell 现有的 Apollo Client 查询包装 Hook（保留） | | `useWidgetMutation` | portal-shell 现有的 Apollo Client mutation 包装 Hook（保留） | --- **本 spec 完成后，portal-shell 将具备：** - 工程整洁的 4 层数据访问分层（Widget → API → Operations → Hook） - 生产级 GraphQL 安全栈（APQ + manifest + 深度/复杂度限制 + @auth 全覆盖） - 与 v2.1 微服务架构原则对齐的前端抽象层 - 为未来 @requires 下沉做好准备的 API 层契约