diff --git a/docs/troubleshooting/known-issues.md b/docs/troubleshooting/known-issues.md index be683fc..e6c04d7 100644 --- a/docs/troubleshooting/known-issues.md +++ b/docs/troubleshooting/known-issues.md @@ -727,42 +727,43 @@ > v2.1 架构：单 Next.js App Router 容器 + Micro-kernel 插件系统，替代旧 4 端微前端。关联 spec `2026-07-14-portal-shell-widget-dashboard-design.md`。 -| 场景 | 技术/规则 | -| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 插件契约跨包共享 | `packages/shared-ts/src/contracts/` 定义 PluginProps/PluginManifest/Layout 类型；`PluginManifest.Component` 用 `unknown`（shared-ts 不依赖 React），前端包引用时断言为 `React.ComponentType` | -| TVars 泛型约束与 TS interface 不兼容 | `useWidgetQuery>` 约束下，widget 文件用 `interface XxxVars` 会报 TS2344；改用 `type XxxVars = {...}` 类型别名（type alias 满足 index signature，interface 不满足） | -| shared-ts contracts 子路径导出 | `package.json` exports 新增 `"./contracts"` 指向 `./dist/contracts/index.js`；hooks 包通过 `@edu/shared-ts/contracts` 引用；typecheck 前需 `pnpm --filter @edu/shared-ts run build` 编译到 dist/ | -| Vitest 解析 workspace 子路径导出失败 | vitest.config.ts resolve.alias 需显式添加 `"@edu/shared-ts/contracts"` → 源码路径；Vite 不自动解析 package.json exports 字段 | -| portal-shell tsconfig paths 补全 | tsconfig.json paths 需添加 `"@edu/shared-ts/contracts": ["../../packages/shared-ts/src/contracts/index.ts"]`，否则 tsc 报 TS2307 | -| 插件 dynamic import 注册 | `Registry.tsx` 用 `next/dynamic`（ssr:false）懒加载 31 个内置插件；loading 展示 `PluginSkeleton` 变体（card/list/table/stats/chart） | -| URL Search Params + Zustand 状态分层 | URL 驱动可分享上下文（classId/childId/termId/view/examId/subjectId）；Zustand 管理纯 UI 状态（theme/locale/sidebarCollapsed）；插件间禁止直接 import | -| useWidgetMutation API 签名 | 返回 `{ run, ...result }`，`run` 是 `async (variables: TVars): Promise`；消费者用 `const { run } = useWidgetMutation(...)` 解构 | -| usePluginConfig 不直接调 API | fetcher 由消费者注入，保持 @edu/hooks "hooks 不直接调 API" 原则；支持轮询刷新（refreshInterval 默认 5 分钟）+ 网络恢复刷新 + visibilitychange 刷新 | -| usePluginStore 注入模式 | `useSyncExternalStore` + `injectPluginStore()` 让 hooks 包不直接依赖特定 store 实例；未注入 store 时返回 DEFAULT_STATE 空操作 | -| 28 个内置插件分类 | universal(7) + sidebar(4) + topbar(4) + teacher(4) + student(4) + parent(2) + admin(3)；每个插件含 `index.tsx` + `plugin.manifest.ts`，manifest 导出 `manifestMeta: Omit` | -| PluginLifecycle 版本兼容 | MVP 只校验 major 版本（`checkVersionCompatibility` 解析 `^`/`~`/`>=` 前缀 + major 数字）；完整 semver range 校验待引入 semver 库 | -| pnpm install --no-frozen-lockfile | parent-portal package.json 新增 `@opentelemetry/instrumentation-document-load` 后 lockfile 过期；开发环境用 `--no-frozen-lockfile` 安装，CI 用 frozen | -| Widget 内联 gql 字面量废弃 | 禁止 `const Q = gql\`...\``直接写在 widget；统一抽取到`lib/api/operations/*.graphql.ts`，widget 只 import `lib/api/.ts` 的语义化函数（ADR-042） | -| 4 层数据访问分层 | Widget（UI）→ API（语义化函数）→ Operations（gql DocumentNode 集中）→ Hook（useWidgetQuery/useWidgetMutation 封装 Apollo）；codegen 从 7 子图 schema 生成类型 | -| graphql-codegen skipDocumentsValidation | codegen.yml 必须设 `skipDocumentsValidation: true`，避免子图未启动时校验 operations 失败；schema 归一化脚本移除 federation 指令（@key/@requires/@extends）防止误解析 | -| useNotifications 命名冲突 | `universal.ts` 与 `topbar.ts` 同时导出 `useNotifications` 在 barrel `index.ts` 冲突（TS2308）；topbar 改名 `useNotificationBell`（铃铛专用，限 N 条） | -| APQ（Automatic Persisted Queries） | `apollo-client.ts` 用 `createPersistedQueryLink({ sha256 })` + `crypto-hash`；env `NEXT_PUBLIC_APOLLO_APQ=false` 关闭；Link 链顺序：authLink → pqLink → httpLink | -| PQ Manifest 生成 | `scripts/generate-pq-manifest.ts` 遍历 `operations/index.ts` 中 DocumentNode，`print(doc)` + `sha256(query)` 写入 `public/pq-manifest.json`；`prebuild` 钩子串联 codegen + generate | -| Windows ESM 动态 import 路径 | Node ESM 动态 `import()` 不支持 Windows 盘符路径（`e:\...`），必须 `url.pathToFileURL(path).href` 转 `file://` URL 再 import | -| apollo-router PQ manifest 挂载 | docker-compose 把 `apps/portal-shell/public/pq-manifest.json` 挂载到 router `/etc/apollo-router/pq-manifest.json:ro`；entrypoint.sh 启动前校验 `APOLLO_REQUIRE_PQ_MANIFEST=true` 时文件存在性 | -| apollo-router 安全限制 | `router.yaml` 配置 `limits.max_depth=10` / `max_cost=1000` / `max_batch_size=5`；`supergraph.introspection` 由 env `APOLLO_ROUTER_INTROSPECTION` 控制（生产 false） | -| Resolver @RequirePermission 字段级守卫 | 每个 GraphQL Resolver 必须用 `@RequirePermission('perm')` 声明权限点；50 resolver 审计后补齐 19 个 TS resolver，Python 子图待补 Strawberry/Ariadne 中间件 | -| TS interface 不满足 Record 约束 | `useWidgetQuery>` 约束下 widget 用 `interface XxxVars` 报 TS2344；改 `type XxxVars = {...}` 别名（满足 index signature） | -| parent.test.tsx 可选链 | `data?.[0].name` 报 TS2532（`data?.[0]` 可能为 undefined）；改 `data?.[0]?.name` 双重可选链 | -| PowerShell 不支持 heredoc | `git commit -m "$(cat <<'EOF'...)"` 在 PowerShell 报错；commit 消息写临时文件 `.git/COMMIT_MSG.txt`，用 `git commit -F .git/COMMIT_MSG.txt` | -| commitlint body-max-line-length | commit body 每行 ≤100 字符，Plan/Spec 路径过长会超限；移除 URL 行或换行简化 | -| commitlint scope-enum | `security` / `graphql` 不在允许 scope 列表；用 `docs` scope 提交审计报告，或用无 scope commit | -| Turbopack 不支持 .js 后缀 import | Next 16 默认 Turbopack 无法像 webpack 那样通过 `resolve.extensionAlias` 将 `.js` 映射到 `.ts/.tsx`；`packages/ui-components` 和 `packages/hooks` 源码内部 import 必须去掉 `.js` 后缀（shared-ts 是 NestJS ESM 模式按规则 §3.4 保留 `.js` 后缀，不修改） | -| 旧纸感令牌批量迁移 shadcn 标准 | 31 个 widget 全量替换：`bg-paper→bg-background` / `bg-surface→bg-card` / `text-ink→text-foreground` / `border-rule→border` 等 19 项映射；保留 button.tsx 中 `bg-accent`（shadcn 标准 hover 语义令牌，通过 `--accent` CSS 变量定义，非旧纸感 `bg-accent`） | -| PERMISSION_BITMAP_ORDER 重复权限点 | `GRADE_READ` 在数组 bit 14 和 bit 53 重复出现，全量编解码 round-trip 测试需用 `[...new Set(PERMISSION_BITMAP_ORDER)]` 去重后再比较 | -| jsdom Blob 不支持 .text() | jsdom 的 Blob 实现不提供 `.text()` 方法，`new Response(blob).text()` 也返回 `[object Blob]`；测试 sendBeacon 时用 `vi.stubGlobal("Blob", vi.fn(...))` mock 构造函数，捕获 `parts[0]` 字符串 | -| vi.mock 提升导致变量未初始化 | `vi.mock()` 被提升到文件顶部，引用外部变量报 `Cannot access 'X' before initialization`；用 `vi.hoisted()` 将 mock 变量初始化提升到 vi.mock 之前 | -| sonner toast 双重性质 mock | toast 既是可调用函数 `toast(msg, opts)` 又有方法 `toast.success/.error/.warning/.info`；mock 时需创建 `vi.fn()` 可调用对象后手动挂载 `.success/.error` 等方法 | -| React 19 use() + Suspense jsdom 测试 | `use(promise)` 在 jsdom 中 promise resolve 后不自动触发重新渲染；需用 `await act(async () => { render(...); await Promise.resolve(); })` 包裹 render，并设置 `globalThis.IS_REACT_ACT_ENVIRONMENT = true`（setup 文件） | -| 前端错误上报生产端点 | api-gateway 在 `/api/v1/log` 直接处理（不代理到下游），slog 结构化 JSON 日志，64KB body 限制，返回 204；`useErrorReport` 按 `process.env.NODE_ENV` 切换：production→`/api/v1/log`，development→`/api/log`（Next.js API route mock） | -| vitest setup 文件配置 | `vitest.config.ts` 的 `setupFiles: ["src/__tests__/setup.ts"]` 注册 `@testing-library/jest-dom/vitest` matchers + 设置 `IS_REACT_ACT_ENVIRONMENT`；`declare global { var IS_REACT_ACT_ENVIRONMENT: boolean \| undefined }` 补类型签名 | +| 场景 | 技术/规则 | +| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 插件契约跨包共享 | `packages/shared-ts/src/contracts/` 定义 PluginProps/PluginManifest/Layout 类型；`PluginManifest.Component` 用 `unknown`（shared-ts 不依赖 React），前端包引用时断言为 `React.ComponentType` | +| TVars 泛型约束与 TS interface 不兼容 | `useWidgetQuery>` 约束下，widget 文件用 `interface XxxVars` 会报 TS2344；改用 `type XxxVars = {...}` 类型别名（type alias 满足 index signature，interface 不满足） | +| shared-ts contracts 子路径导出 | `package.json` exports 新增 `"./contracts"` 指向 `./dist/contracts/index.js`；hooks 包通过 `@edu/shared-ts/contracts` 引用；typecheck 前需 `pnpm --filter @edu/shared-ts run build` 编译到 dist/ | +| Vitest 解析 workspace 子路径导出失败 | vitest.config.ts resolve.alias 需显式添加 `"@edu/shared-ts/contracts"` → 源码路径；Vite 不自动解析 package.json exports 字段 | +| portal-shell tsconfig paths 补全 | tsconfig.json paths 需添加 `"@edu/shared-ts/contracts": ["../../packages/shared-ts/src/contracts/index.ts"]`，否则 tsc 报 TS2307 | +| 插件 dynamic import 注册 | `Registry.tsx` 用 `next/dynamic`（ssr:false）懒加载 31 个内置插件；loading 展示 `PluginSkeleton` 变体（card/list/table/stats/chart） | +| URL Search Params + Zustand 状态分层 | URL 驱动可分享上下文（classId/childId/termId/view/examId/subjectId）；Zustand 管理纯 UI 状态（theme/locale/sidebarCollapsed）；插件间禁止直接 import | +| useWidgetMutation API 签名 | 返回 `{ run, ...result }`，`run` 是 `async (variables: TVars): Promise`；消费者用 `const { run } = useWidgetMutation(...)` 解构 | +| usePluginConfig 不直接调 API | fetcher 由消费者注入，保持 @edu/hooks "hooks 不直接调 API" 原则；支持轮询刷新（refreshInterval 默认 5 分钟）+ 网络恢复刷新 + visibilitychange 刷新 | +| usePluginStore 注入模式 | `useSyncExternalStore` + `injectPluginStore()` 让 hooks 包不直接依赖特定 store 实例；未注入 store 时返回 DEFAULT_STATE 空操作 | +| 28 个内置插件分类 | universal(7) + sidebar(4) + topbar(4) + teacher(4) + student(4) + parent(2) + admin(3)；每个插件含 `index.tsx` + `plugin.manifest.ts`，manifest 导出 `manifestMeta: Omit` | +| PluginLifecycle 版本兼容 | MVP 只校验 major 版本（`checkVersionCompatibility` 解析 `^`/`~`/`>=` 前缀 + major 数字）；完整 semver range 校验待引入 semver 库 | +| pnpm install --no-frozen-lockfile | parent-portal package.json 新增 `@opentelemetry/instrumentation-document-load` 后 lockfile 过期；开发环境用 `--no-frozen-lockfile` 安装，CI 用 frozen | +| Widget 内联 gql 字面量废弃 | 禁止 `const Q = gql\`...\``直接写在 widget；统一抽取到`lib/api/operations/*.graphql.ts`，widget 只 import `lib/api/.ts` 的语义化函数（ADR-042） | +| 4 层数据访问分层 | Widget（UI）→ API（语义化函数）→ Operations（gql DocumentNode 集中）→ Hook（useWidgetQuery/useWidgetMutation 封装 Apollo）；codegen 从 7 子图 schema 生成类型 | +| graphql-codegen skipDocumentsValidation | 全局 `skipDocumentsValidation: true` 保留（子图未启动时校验 operations 失败）；分域关闭：data-ana 域 dashboard-types.ts 输出已关 `skipDocumentsValidation: false`（P1-7），config 域待 `LayoutTemplateGql.availableSlots` schema 落地后关闭；schema 归一化脚本移除 federation 指令（@key/@requires/@extends）防止误解析 | +| useNotifications 命名冲突 | `universal.ts` 与 `topbar.ts` 同时导出 `useNotifications` 在 barrel `index.ts` 冲突（TS2308）；topbar 改名 `useNotificationBell`（铃铛专用，限 N 条） | +| APQ（Automatic Persisted Queries） | `apollo-client.ts` 用 `createPersistedQueryLink({ sha256 })` + `crypto-hash`；env `NEXT_PUBLIC_APOLLO_APQ=false` 关闭；Link 链顺序：authLink → pqLink → httpLink | +| PQ Manifest 生成 | `scripts/generate-pq-manifest.ts` 遍历 `operations/index.ts` 中 DocumentNode，`print(doc)` + `sha256(query)` 写入 `public/pq-manifest.json`；`prebuild` 钩子串联 codegen + generate | +| Windows ESM 动态 import 路径 | Node ESM 动态 `import()` 不支持 Windows 盘符路径（`e:\...`），必须 `url.pathToFileURL(path).href` 转 `file://` URL 再 import | +| apollo-router PQ manifest 挂载 | docker-compose 把 `apps/portal-shell/public/pq-manifest.json` 挂载到 router `/etc/apollo-router/pq-manifest.json:ro`；entrypoint.sh 启动前校验 `APOLLO_REQUIRE_PQ_MANIFEST=true` 时文件存在性 | +| CI 结构性检查三脚本（P1-8） | `scripts/check-route-table.ts`（路由表一致性：实际 `/shell/*` 路由必须登记到 route-permissions.ts）+ `scripts/check-page-count.ts`（页面计数 baseline=13）+ `scripts/check-codegen.ts`（codegen 契约校验：skipDocumentsValidation:false 输出严格校验）；CI 接线 `.github/workflows/ci.yml` quality-ts job | +| apollo-router 安全限制 | `router.yaml` 配置 `limits.max_depth=10` / `max_cost=1000` / `max_batch_size=5`；`supergraph.introspection` 由 env `APOLLO_ROUTER_INTROSPECTION` 控制（生产 false） | +| Resolver @RequirePermission 字段级守卫 | 每个 GraphQL Resolver 必须用 `@RequirePermission('perm')` 声明权限点；50 resolver 审计后补齐 19 个 TS resolver，Python 子图待补 Strawberry/Ariadne 中间件 | +| TS interface 不满足 Record 约束 | `useWidgetQuery>` 约束下 widget 用 `interface XxxVars` 报 TS2344；改 `type XxxVars = {...}` 别名（满足 index signature） | +| parent.test.tsx 可选链 | `data?.[0].name` 报 TS2532（`data?.[0]` 可能为 undefined）；改 `data?.[0]?.name` 双重可选链 | +| PowerShell 不支持 heredoc | `git commit -m "$(cat <<'EOF'...)"` 在 PowerShell 报错；commit 消息写临时文件 `.git/COMMIT_MSG.txt`，用 `git commit -F .git/COMMIT_MSG.txt` | +| commitlint body-max-line-length | commit body 每行 ≤100 字符，Plan/Spec 路径过长会超限；移除 URL 行或换行简化 | +| commitlint scope-enum | `security` / `graphql` 不在允许 scope 列表；用 `docs` scope 提交审计报告，或用无 scope commit | +| Turbopack 不支持 .js 后缀 import | Next 16 默认 Turbopack 无法像 webpack 那样通过 `resolve.extensionAlias` 将 `.js` 映射到 `.ts/.tsx`；`packages/ui-components` 和 `packages/hooks` 源码内部 import 必须去掉 `.js` 后缀（shared-ts 是 NestJS ESM 模式按规则 §3.4 保留 `.js` 后缀，不修改） | +| 旧纸感令牌批量迁移 shadcn 标准 | 31 个 widget 全量替换：`bg-paper→bg-background` / `bg-surface→bg-card` / `text-ink→text-foreground` / `border-rule→border` 等 19 项映射；保留 button.tsx 中 `bg-accent`（shadcn 标准 hover 语义令牌，通过 `--accent` CSS 变量定义，非旧纸感 `bg-accent`） | +| PERMISSION_BITMAP_ORDER 重复权限点 | `GRADE_READ` 在数组 bit 14 和 bit 53 重复出现，全量编解码 round-trip 测试需用 `[...new Set(PERMISSION_BITMAP_ORDER)]` 去重后再比较 | +| jsdom Blob 不支持 .text() | jsdom 的 Blob 实现不提供 `.text()` 方法，`new Response(blob).text()` 也返回 `[object Blob]`；测试 sendBeacon 时用 `vi.stubGlobal("Blob", vi.fn(...))` mock 构造函数，捕获 `parts[0]` 字符串 | +| vi.mock 提升导致变量未初始化 | `vi.mock()` 被提升到文件顶部，引用外部变量报 `Cannot access 'X' before initialization`；用 `vi.hoisted()` 将 mock 变量初始化提升到 vi.mock 之前 | +| sonner toast 双重性质 mock | toast 既是可调用函数 `toast(msg, opts)` 又有方法 `toast.success/.error/.warning/.info`；mock 时需创建 `vi.fn()` 可调用对象后手动挂载 `.success/.error` 等方法 | +| React 19 use() + Suspense jsdom 测试 | `use(promise)` 在 jsdom 中 promise resolve 后不自动触发重新渲染；需用 `await act(async () => { render(...); await Promise.resolve(); })` 包裹 render，并设置 `globalThis.IS_REACT_ACT_ENVIRONMENT = true`（setup 文件） | +| 前端错误上报生产端点 | api-gateway 在 `/api/v1/log` 直接处理（不代理到下游），slog 结构化 JSON 日志，64KB body 限制，返回 204；`useErrorReport` 按 `process.env.NODE_ENV` 切换：production→`/api/v1/log`，development→`/api/log`（Next.js API route mock） | +| vitest setup 文件配置 | `vitest.config.ts` 的 `setupFiles: ["src/__tests__/setup.ts"]` 注册 `@testing-library/jest-dom/vitest` matchers + 设置 `IS_REACT_ACT_ENVIRONMENT`；`declare global { var IS_REACT_ACT_ENVIRONMENT: boolean \| undefined }` 补类型签名 |