1117 lines
127 KiB
Markdown
1117 lines
127 KiB
Markdown
# portal-shell 前端架构总纲（v3.0）
|
||
|
||
> 版本：3.0
|
||
> 日期：2026-07-20
|
||
> 状态：**P0 已完成 + P1 全部完成（P1-1 至 P1-8，2026-07-22 验收）；架构审计完成 + 重设计方案定稿**
|
||
> 本文档地位：**portal-shell 前端工作的唯一权威指导文档**。所有后续 AI/人工在此模块的工作必须先读本文件，以其为准。
|
||
>
|
||
> 关联文档（按效力排序）：
|
||
>
|
||
> 1. **本文件**（v3.0 总纲：审计结论 + 目标架构 + 路线图 + 工作规范）
|
||
> 2. [README.md](./README.md)（v2.0 模块文档：微内核仪表盘子系统的详细设计，仅其"插件仪表盘"部分继续有效）
|
||
> 3. [004 架构影响地图](../../docs/architecture/004_architecture_impact_map.md)（后端架构唯一源：§5.4 视口四层模型、§11.7 前端数据层）
|
||
> 4. [项目规则](../../.trae/rules/project_rules.md)（强制约束：§3.10 设计令牌、§4 安全、§14 多 AI 协作）
|
||
> 5. [MIGRATION_GUIDE.md](../../MIGRATION_GUIDE.md)（CICD → Edu 迁移背景）
|
||
>
|
||
> **效力声明**：README v2.0 中与本文件冲突的表述（完成度声明、设计方向、"旧 portal 已下线"等）以本文件为准；`docs/standards/ui-design-system.md`（v1.0，面向已废弃的 4 微前端方案）自本文件发布之日起**废止**，其有效内容已并入本文件 §8；`docs/architecture/0020_portal_shell_architecture.md`（v1.0）为历史评审稿，仅作背景参考。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [现状审计（2026-07-20 快照）](#1-现状审计2026-07-20-快照)
|
||
2. [问题根因分析](#2-问题根因分析)
|
||
3. [目标架构 v3.0](#3-目标架构-v30)
|
||
4. [认证与身份链](#4-认证与身份链)
|
||
5. [数据层架构](#5-数据层架构)
|
||
6. [安全架构（安全边际）](#6-安全架构安全边际)
|
||
7. [信息架构与页面体系](#7-信息架构与页面体系)
|
||
8. [前端设计规范（强制）](#8-前端设计规范强制)
|
||
9. [页面迁移总表（~140 页）](#9-页面迁移总表140-页)
|
||
10. [实施路线图（P0–P6）](#10-实施路线图p0p6)
|
||
11. [后续 AI 工作规范（强制）](#11-后续-ai-工作规范强制)
|
||
12. [风险登记册](#12-风险登记册)
|
||
13. [附录](#13-附录)
|
||
|
||
---
|
||
|
||
## 1. 现状审计（2026-07-20 快照）
|
||
|
||
> 审计方法：全部结论均可复现。每项发现标注证据（文件路径 + 行号 / 可执行命令）。审计环境：Windows 11 + Node 24，分支 `feat/architecture-v2.1`，工作区干净。
|
||
|
||
### 1.1 验收声明 vs 实测结果
|
||
|
||
README v2.0 声称"P0–P4 全部验证通过、功能验收 23 项全部 [x]"。实测：**构建级声明属实，功能级声明不成立**——现有门禁只验证"骨架不塌"，从不验证"功能可用"。
|
||
|
||
| README 声明 | 实测结果 | 结论 |
|
||
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
|
||
| `typecheck` 0 错误 | `node node_modules/typescript/bin/tsc --noEmit` 无输出退出 | ✅ 属实 |
|
||
| `vitest` 206/206 通过 | 实测 19 文件 206 用例全部通过（8.12s） | ✅ 属实 |
|
||
| `build` 6 路由生成成功 | 实测成功：`/`、`/_not-found`、`/api/health`、`/api/log`、`/api/ready`、`/shell/[[...route]]` | ✅ 属实——但**全应用只有 1 条业务路由** |
|
||
| "31 个内置插件全部加载正常" | 31 插件全部注册并能渲染（30 REAL + 1 PARTIAL，无 STUB/MOCK）；但其 GraphQL 查询**严格匹配 0/50**（见 §1.3-F2），运行时全部返回错误/空数据 | ⚠️ 代码真实，数据全断 |
|
||
| "31 个 widget 旧纸感令牌全部迁移（1104 次替换，零违规）" | `src/widgets/` 仍残留 **271 处**旧令牌类（`text-heading-*`/`mt-sm`/`py-xs`/`p-md` 等），这些类在 Tailwind v4 主题中**不存在**，渲染时无样式 | ❌ **不属实** |
|
||
| "M10 旧 portal 下线完成" | 4 个旧 portal 完整保留在 `apps/`（teacher 143 文件 / student 118 / parent 190 / admin 84），含全部页面源码 | ❌ **不属实**（未删 ≠ 已下线；但也未迁移） |
|
||
| "三层安全边界 L1/L2/L3 已落地" | `checkRoutePermission` 仅被**测试文件**引用；无 `middleware.ts`；`shell/[[...route]]/page.tsx` 不调用任何权限检查。**L1/L2 在生产请求路径上是死代码** | ❌ 代码存在但从未接线 |
|
||
| "admin 改配置 → 用户刷新生效" | 无后端时 `fetchPluginConfig` 返回**空插件集**，仪表盘渲染"暂无可见插件"；本地无种子数据/无 mock，**开发态开箱即为空壳** | ❌ 链路存在，起点即断 |
|
||
| ESLint 强制插件隔离与 notify 封装（`no-restricted-imports`） | `eslint.config.js` 仅有 hex 颜色 + 字体名两条规则；**无任何 import 限制规则** | ❌ 不属实 |
|
||
|
||
### 1.2 一句话诊断
|
||
|
||
**portal-shell 当前是一个"质量门禁全绿、但没有任何可用页面"的空壳**：微内核仪表盘骨架（Shell/Registry/SlotRenderer/PluginBoundary/数据层封装）工程质量合格，但它之上**既没有登录认证链，也没有一个真实业务页面**；31 个卡片插件查询的是后端并不存在的 GraphQL 字段；距离 CICD 原版（35 模块、4 端完整页面体系）的功能差距约为 **140 个页面**。
|
||
|
||
### 1.3 十大断裂点（按严重度排序，证据化）
|
||
|
||
#### F1.【致命】没有任何真实业务页面 —— "前端不可用"的第一根因
|
||
|
||
- 全应用仅 1 条业务路由：`src/app/shell/[[...route]]/page.tsx`（catch-all）。`ShellPage` **不读取 route 参数**（`src/app/shell/[[...route]]/page.tsx:26-45`），`/shell/teacher/grades` 与 `/shell/admin/users` 渲染完全相同的内容；业务区分被压缩到 query params（`?classId`/`?termId` 等）。
|
||
- `route-permissions.ts` 声明的 24 条路由（如 `/shell/admin/users`、`/shell/teacher/lesson-plans`）在文件系统中**一条都不存在**——权限表保护的是幽灵路由（该表从 CICD 项目平移，本意给网关 middleware 用，Next.js 侧从未接线）。
|
||
- 对照资产：CICD 原版 **155 个页面**（auth 4 + onboarding 1 + dashboard 公共 8 + admin 41 + teacher 54 + student 25 + parent 14 + management/grade 5，含 register/privacy/terms）；Edu 旧 4 portal 共 **140 个 page.tsx**（teacher 56 / student 36 / parent 24 / admin 24）已在仓库内但从未接入 portal-shell（旧 portal 本身缺 management/grade 与 register/onboarding 体系，属缺口待补）。
|
||
|
||
#### F2.【致命】GraphQL 契约前后端全面脱节 —— 50 个操作严格匹配 0 个
|
||
|
||
- 前端 `operations/*.graphql.ts` 定义 **50 个操作**（32 query + 18 mutation；README 写 51，其中 GetMyChildrenOverview 改名去重后为 50）。
|
||
- 合并 schema（`src/lib/api/__generated__/combined-schema.graphql`，700 行）仅有 **38 个 Query 字段，且完全没有 Mutation 类型**。
|
||
- **严格匹配数：0/50**。唯一 root 字段名命中的是 `GetLayoutTemplates`→`layoutTemplates`，但其选择的 `availableSlots` 字段在 `LayoutTemplateGql` 上不存在，仍然校验失败。
|
||
- 按域不匹配统计：**admin 19/19、teacher 6/6、student 8/8、parent 4/4、sidebar 3/3、topbar 3/3、universal 7/7，全部不匹配**。典型样例：
|
||
- 列表查询不存在：`grades(classId)`/`homeworks(classId)`/`exams(classId)` → 后端仅有 `grade(id)`/`homework(id)`/`exam(id)` 单查；`schedule`/`attendance`/`announcements`/`myClasses`/`terms`/`myChildren`/`users`/`roles`/`permissions`/`auditLogs`/`invitationCodes`/`school`/`lessonPlans`/`schedulingRules`/`myLearningPath`/`electiveCourses`/`aiTutorSessions`/`leaveRequests`/`search` 在 schema 中**全部不存在**。
|
||
- 形状不符：`me{id,name,email,role}` → iam `User` 实为 `userId/email/name/status/dataScope`；`exams` 选 `name/subject/maxScore` → `Exam` 实为 `title/totalScore`；`notifications(limit,offset)` 期望 `{items,total}` 包装 → msg 实为 `notifications(userId: ID!)` 平铺数组；`errorBookItems` 底层为 snake_case（`question_id` 等）。
|
||
- **18 个 mutation 全部无契约**（schema 无 Mutation 类型）：SaveLessonPlan/ApproveLeave/RejectLeave/UpdateUserStatus/UpdateUserRole/UpdateRolePermissions/CreateInvitationCode/RevokeInvitationCode/UpdateSchool/SaveSchedulingRule/EnrollCourse/DropCourse/MarkErrorMastered/SendAiTutorMessage 及 plugin-manager 的 4 个配置 mutation。
|
||
- **config-service resolver 实测**（唯一声称支撑全架构配置的后端）：仅实现 `plugin/plugins/layoutTemplates/userLayoutOverride/pluginConfig` 5 个 Query；**plugin-manager 面板依赖的 `rolePluginMapping`/`roleLayoutDefault` 及全部 update\*/reset mutation 在 schema 与 resolver 双层均未实现**——也就是说，即使后端全栈启动，"admin 改配置"这个插件架构的旗舰功能也**无法保存**。
|
||
- 唯一验证通过的查询：仪表盘启动用的 `pluginConfig`（不经 operations/，内联于 `config-fetcher.ts:24-58`；`PluginConfigLayoutGql` 含 `availableSlots`/`layoutSchemaJson`，形状吻合）——这就是"后端就绪时仪表盘能出框架、但所有卡片空转"的原因。
|
||
- 编译期防线自毁：`codegen.yml:49-56` 注释自述"forward-looking spec fields … not yet present in services subgraph SDL … 44 个 'Cannot query field X' 错误"，被迫 `skipDocumentsValidation: true`；同时 codegen 未配置 `typescript-operations`，**没有生成任何 per-operation 类型**，lib/api 的返回类型全部手写——编译期 0 报错，运行期全报错。
|
||
- 后端真正可用但**没有任何 widget 使用**的资产：data-ana 的 4 个仪表盘聚合查询（`teacherDashboard`/`studentDashboard`/`parentDashboard`/`adminDashboard`）+ `warnings`/`mastery*`/`diagnosticReports`/`errorBook*` + config-service 5 个配置查询 + iam `user/role/dataScope` + core-edu/content 按 id 单查。
|
||
- 无 GraphQL schema 的服务：`classes`、`student-bff`、`teacher-bff`、`parent-bff`、`push-gateway`（`api-gateway` 为 router 除外）——`classes` 域查询当前**无处落地**。
|
||
|
||
#### F3.【致命】认证与身份链断裂 —— 没有登录页，角色写死 teacher
|
||
|
||
- 无登录/注册页面；`src/app/page.tsx` 直接 `redirect("/shell")`。
|
||
- `ShellPage` 从 `x-user-id`/`x-user-role` 请求头取身份，**缺失时默认 `dev-user` / `teacher`**（`page.tsx:28-31`）——任何人直达 portal-shell 都是"教师"。
|
||
- Apollo Client 期望从 `localStorage["edu_token"]` 读 JWT（`ApolloProvider.tsx:18-27`），但**全应用没有任何代码写入这个 token**（没有登录流程）→ 所有 GraphQL 请求永远匿名。
|
||
- 浏览器直连 apollo-router :3000，**绕过 api-gateway**（JWT 校验在 gateway，而 gateway 不在浏览器→router 路径上）。
|
||
|
||
#### F4.【严重】安全边界是"纸面合规" —— L1/L2 从未接入请求路径
|
||
|
||
- 无 `middleware.ts`；`checkRoutePermission`/`batchCheckRoutePermission` 仅被 `*.test.ts` 引用（grep 实测 60+ 处引用全部在 `__tests__`）。
|
||
- 后果：`/shell/admin/users` 对 teacher/student/parent 角色**直接放行**；唯一的真实过滤发生在 config-service（L3），而它过滤的只是"仪表盘上显示哪些卡片"。
|
||
- 权限位图 `PERMISSION_BITMAP_ORDER` 中 **`GRADE_READ` 重复定义两次**（`permission-bitmap.ts:62` 与 `:79`）——按"顺序不可变"铁律属数据缺陷，趁未签发真实 JWT 前必须去重。
|
||
- `infra/docker-compose.yml` 的 portal-shell 服务（含生产 profile）环境变量写入 **`NEXT_PUBLIC_DEV_MODE: "true"`**——生产部署也以 dev 模式运行，等于永久绕过认证。
|
||
- `infra/apollo-router/router.yaml` 硬编码 `router-authorization: dev-router-secret`（明文入库）。
|
||
|
||
#### F5.【严重】设计系统三方冲突 + 令牌断裂
|
||
|
||
- **三个互相矛盾的"权威"**：`docs/standards/ui-design-system.md`（纸感米白 + Fraunces/Inter/JetBrains Mono 三字体 + 学术深蓝，面向已废弃的 4 微前端方案）；README v2.0（shadcn 标准 + Inter 单字体）；实际实现（`packages/ui-tokens` = shadcn zinc 默认色板）。
|
||
- 31 个 widget 残留 **271 处**旧令牌类（grep：`text-heading-3`/`mt-sm`/`py-xs`/`p-md`/`space-y-xs` 等），这些类在 `@theme` 中**没有定义** → 相关间距/字号渲染为零值，widget 视觉上是坏的。
|
||
- 另有批量出现的 `border border` 重复类（如 `grades-widget/index.tsx:32,42`）。
|
||
- `src/styles/tokens.css`（README 附录自称"旧，待 P1 移除"）仍在源码树中。
|
||
|
||
#### F6.【严重】31 个插件 ≈ 31 张信息卡片，不是功能
|
||
|
||
- 全量审计结论（31/31）：**30 REAL + 1 PARTIAL，0 STUB / 0 MOCK**——插件代码是"真"的，问题是**薄**且数据断供。平均 139 行/个，形态为"一张卡片 + 列表/表单局部"。
|
||
- 典型缺陷（审计实测）：
|
||
- `question-bank`（唯一 PARTIAL）：新建题目**不接 mutation**，仅 push 进本地 state（`local-${Date.now()}`），刷新即失。
|
||
- `lesson-plan-editor`：仅 标题/目标/内容/资源 四字段表单（216 行）；对照 CICD 同功能：lesson-preparation 是全仓最大模块（113 文件：结构树 + 纸面编辑器 + AI 建议 + 版本/审核/发布 + xyflow 画布）；错误处理 `catch { /* toast */ }` 空吞（违反 notify 强制）。
|
||
- `quick-actions`：导航目标 `/homework/new`、`/schedule`、`/grades` 等**全部不存在**（缺 `/shell` 前缀且无对应路由），点击即掉进 catch-all 仪表盘。
|
||
- `global-search`：跳转目标 `/students/:id` 等不存在；`user-menu` 无登出项；`locale-switcher` 只切本地 state 不加载任何 i18n；`ai-tutor` 切会话不加载历史；`notifications-widget` 分页 offset 固定 0。
|
||
- 对比 CICD 同功能页面量级：考试模块 11 页（all/create/new/[id]/build/edit-rich/analytics/proctoring/grading）、作业模块含扫描阅卷、成绩模块 5 页、教案模块 7 页。
|
||
- 插件间无页面级导航目标（没有可跳转的详情页），"点击卡片进详情"无从谈起。
|
||
|
||
#### F7.【严重】开发体验不可用 —— 无后端 = 空壳
|
||
|
||
- `fetchPluginConfig` 三级降级的终点是 `getDefaultConfig()`：**`plugins: []`**（`config-fetcher.ts:193-212`）→ 无后端/无种子数据时，仪表盘渲染空壳"暂无可见插件"。
|
||
- 仓库内**没有**本地 mock/seed/MSW 任何一条让前端独立可运行的路径；旧 portal 里的 MSW handlers（`teacher-portal/src/mocks/handlers-p*.ts`，覆盖 P4/P5/P7 场景）未被复用。
|
||
|
||
#### F8.【中】路由权限命名双轨制混乱
|
||
|
||
- README 示例用点号权限（`grade.read`），实际 `PERMISSION_BITMAP_ORDER` 用 `<RESOURCE>_<ACTION>` 大写下划线（`GRADE_READ`）；widget manifest 的 `requiredPermissions` 字段 31 个插件**无一使用**（L2 插件级门禁名存实亡）。
|
||
|
||
#### F9.【中】基础设施与文档脱节
|
||
|
||
- README §6.1 说 7 domain API 文件 "Widget 数" 与 §13.2 表格不一致（topbar 4 插件 vs 2 API 的统计口径混乱，实际 admin.ts 有 20 个 hook）；§11.3 测试矩阵与附录 B "95 用例" 自相矛盾（实际 206）。
|
||
- `src/shell/Registry.tsx` 头注释写"内置插件共 28 个…admin（3）"，实际注册 31 个（admin 6）——代码对、注释陈旧。
|
||
- `docs/standards/ui-design-system.md` 全文面向"4 个微前端 + Module Federation"——该架构已被 ADR-033 废弃。
|
||
- `MIGRATION_GUIDE.md`/根 README 仍写"前端：Next.js + Module Federation（4 微前端）"。
|
||
|
||
#### F10.【低】工程细节
|
||
|
||
- `next.config.js` 同时保留 Turbopack 与 webpack 双份配置（注释已说明，可接受）。
|
||
- `.env.local` 入库（含本地配置，虽无密钥，但 `.env.example` 已存在时应 gitignore）。
|
||
- `tsconfig.tsbuildinfo`（286KB 构建缓存）入库。
|
||
|
||
### 1.4 可复用资产盘点（不要把婴儿和洗澡水一起倒掉）
|
||
|
||
| 资产 | 位置 | 状态 | 处置 |
|
||
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------- |
|
||
| 微内核仪表盘骨架（Shell/LayoutManager/SlotRenderer/Registry/PluginBoundary/PluginLifecycle/PropsMerger） | `src/shell/` + `src/shared/components/plugin-boundary.tsx` | ✅ 工程质量合格，测试覆盖 | **保留**，收缩为"角色首页仪表盘"专用 |
|
||
| 数据层封装（apollo-client/useWidgetQuery/useWidgetMutation/ApiError） | `src/lib/` | ✅ 合格 | **保留**，改走同域代理（§5.2） |
|
||
| lib/api 7 domain + 50 operations | `src/lib/api/` | ⚠️ 结构合格；**50 操作严格匹配 0 个**，类型全部手写 | **保留结构**，按真实 schema 逐域重写操作并恢复 codegen 全量类型（§5.3） |
|
||
| 三级错误边界 + useErrorReport + notify | `src/shared/` + `packages/hooks/` | ✅ 合格 | **保留**，扩展到页面级 |
|
||
| 权限位图 + route-permissions 表 | `packages/shared-ts/` + `src/shared/lib/` | ⚠️ 未接线 + GRADE_READ 重复 | **接线到 middleware**，位图去重 |
|
||
| shadcn 令牌三层 + ui-components 19 件 | `packages/ui-tokens/` + `packages/ui-components/` | ✅ 合格 | **保留为唯一设计系统** |
|
||
| **4 个旧 portal 的 140 个页面实现** | `apps/{teacher,student,parent,admin}-portal/` | ⚠️ 完整但栈不同（urql + next-intl + MSW + 纸感令牌） | **迁移源**：逐页移植 + 换数据层 + 换令牌 |
|
||
| 旧 portal 的 MSW handlers（P4/P5/P7 全覆盖） | `apps/teacher-portal/src/mocks/` 等 | ✅ 可用 | **迁移为 portal-shell 开发兜底层** |
|
||
| next-intl messages（zh-CN/en） | 旧 portal `src/messages/` | ✅ 可用 | **随页面迁移** |
|
||
| PQ Manifest + APQ + Router limits 安全栈 | `public/pq-manifest.json` + `infra/apollo-router/router.yaml` | ✅ 链路完整 | **保留**，manifest 随操作清单更新重新生成 |
|
||
| 测试基座（vitest + 19 文件 206 用例） | `src/**/__tests__/` | ✅ 合格 | **保留**，新增页面级测试 |
|
||
|
||
---
|
||
|
||
## 2. 问题根因分析
|
||
|
||
为什么"质量门禁全绿"的系统会完全不可用？后续工作必须避免重蹈覆辙，四条根因：
|
||
|
||
1. **验收指标错位**：门禁只覆盖 typecheck/lint/单测/build 这些"骨架指标"，从未把"页面数、契约匹配率、关键用户流 E2E"纳入验收。于是"206 测试全过"与"没有一个可用页面"同时成立。**对策**：§10 的每个阶段退出标准必须包含功能指标 + 可复现证据。
|
||
2. **契约逆向编写**：前端 operations 按 spec 文档"超前"编写（50 个操作按设计意图而非后端实现，**0 个通过严格校验**），后端子图只落地了 38 个只读查询、0 个 mutation。`skipDocumentsValidation: true` + 不生成 per-operation 类型，让这种脱节编译期不可见。**对策**：§5.3 契约纪律——operations 只允许引用真实 schema 字段，mock 数据走 MSW 而不是"假契约"。
|
||
3. **范围误判**：v2.1 把"统一前端"收缩成"统一仪表盘"，默认了"页面以后再说"，但没有文档记录这个范围缺口，README 反而把仪表盘骨架的完成写成了整个前端的完成。**对策**：本文件 §7/§9 把页面体系定义为 portal-shell 的一等公民职责。
|
||
4. **文档激励扭曲**：多处"已完成"声明与实测不符（令牌迁移、旧 portal 下线、安全边界），说明验收只看了 PR 描述没看运行态。**对策**：§11.6 文档同步纪律——验收声明必须附可复现命令输出，Reviewer 运行命令复核。
|
||
|
||
---
|
||
|
||
## 3. 目标架构 v3.0
|
||
|
||
### 3.1 设计原则
|
||
|
||
| # | 原则 | 含义 |
|
||
| --- | ------------------ | -------------------------------------------------------------------------------------------------------------- |
|
||
| P1 | **页面一等公民** | 业务功能落在真实 Next.js 路由页面上（可寻址、可分享、可深链）；插件仪表盘只承担"角色首页聚合" |
|
||
| P2 | **契约真实** | 前端 GraphQL 操作只允许引用后端真实 schema；后端未就绪的功能用 MSW mock 数据，禁止"假契约" |
|
||
| P3 | **fail-closed** | 无身份 → 登录页；无权限 → 403 页；配置缺失 → 内置默认（而非空壳）；错误 → 显式兜底（而非静默） |
|
||
| P4 | **单一设计系统** | shadcn 标准令牌（@edu/ui-tokens）为唯一视觉权威；任何页面/插件不引入第二套令牌 |
|
||
| P5 | **微内核收敛** | Shell 插件系统收缩为仪表盘专用机制，不再承载"整个应用"的野心；新增功能默认建页面而非建插件 |
|
||
| P6 | **迁移优先于重写** | 140 个旧页面是迁移源而非重写对象；移植时换数据层（urql→Apollo hooks）、换令牌（纸感→shadcn）、保留业务交互逻辑 |
|
||
| P7 | **证据化验收** | 每个里程碑以可复现命令 + 运行态截图/录屏验收，禁止"声明即完成" |
|
||
|
||
### 3.2 总体结构（混合路由模型）
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────────┐
|
||
│ 浏览器 │
|
||
└──────────────┬─────────────────────────────────────────────────┘
|
||
│
|
||
┌──────────────▼─────────────────────────────────────────────────┐
|
||
│ portal-shell :4010（Next.js 16 App Router 单容器） │
|
||
│ │
|
||
│ middleware.ts（新） │
|
||
│ ├─ 公共路径放行（/login、/api/health、静态资源） │
|
||
│ ├─ JWT cookie 校验 → 注入 x-user-id/x-user-role/x-perms │
|
||
│ └─ checkRoutePermission（L1 角色 + L2 权限点，fail-closed） │
|
||
│ │
|
||
│ /login 登录页（新） │
|
||
│ /shell/forbidden 403 页（新） │
|
||
│ /shell ───────────────────── ┐ │
|
||
│ layout.tsx（新框架） │ AppFrame：TopBar + Sidebar │
|
||
│ ├─ page.tsx（catch-all） │ + 导航菜单（按角色/权限过滤） │
|
||
│ │ = 角色仪表盘 │ │
|
||
│ │ （微内核插件区，保留） │ │
|
||
│ ├─ teacher/exams/page.tsx │ 真实业务页面（迁移） │
|
||
│ ├─ teacher/exams/[id]/… │ │
|
||
│ ├─ student/my-grades/… ┘ │
|
||
│ └─ … ~140 页面 │
|
||
│ │
|
||
│ /api/graphql（新） GraphQL 同域代理 │
|
||
│ └─ 从 httpOnly cookie 取 JWT → Authorization → apollo-router │
|
||
│ /api/auth/login（新） 登录代理：调 iam → Set-Cookie │
|
||
│ /api/health /api/ready /api/log 保留 │
|
||
└──────────────┬─────────────────────────────────────────────────┘
|
||
│ 仅两条出站：
|
||
├─ /api/graphql → apollo-router :3000（业务查询，APQ）
|
||
└─ /api/v1/* → api-gateway :8080（REST：认证/上传/SSE 等）
|
||
```
|
||
|
||
**关键决策（v3.0 ADR 摘要，详见 §3.4）：**
|
||
|
||
- **V3-A1 混合路由模型**：真实页面 + 保留仪表盘微内核。废除"一切皆卡片、单 catch-all 承载全站"的极端；catch-all 仅保留给仪表盘（可选路由参数如 `?layout=`），新页面一律走显式路由。
|
||
- **V3-A2 认证链闭环**：登录页 + `/api/auth/login` 代理 + httpOnly cookie + middleware 校验 + `/api/graphql` 代理。**删除 localStorage JWT 方案**。
|
||
- **V3-A3 门禁接线**：`checkRoutePermission` 移入 `middleware.ts` 真实执行；新增路由必须在 `route-permissions.ts` 登记（CI 校验路由表与文件系统一致性）。
|
||
- **V3-A4 契约纪律**：operations 与真实 schema 强绑定；codegen 恢复 `typescript-operations` 全量类型；`skipDocumentsValidation` 随后端补齐分域关闭（§5.3）。
|
||
- **V3-A5 设计系统单源**：shadcn 标准（zinc）为唯一方向，废止纸感全局方案；备课编辑器二期可用模块命名空间（`--lp-*`）局部纸感化。
|
||
- **V3-A6 接入 next-intl**：复用旧 portal 的 messages，页面迁移不丢失已翻译文案。
|
||
- **V3-A7 MSW 开发兜底**：`NEXT_PUBLIC_MSW=1` 时启用，前端无后端可开发/演示/跑 E2E；生产构建永不包含。
|
||
- **V3-A8 验收门禁改革**：CI 增加契约匹配率检查、路由表一致性检查、页面计数、Playwright E2E（P6）。
|
||
|
||
### 3.3 与现有架构的关系（保留什么、改变什么）
|
||
|
||
| 现有（v2.0） | v3.0 处置 | 理由 |
|
||
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
|
||
| 单 catch-all `/shell/[[...route]]` 承载一切 | **收缩**：仅渲染角色仪表盘；新增显式路由优先于 catch-all（Next.js 路由规则天然支持） | 页面可寻址、RSC 预取、loading/error 按路由生效 |
|
||
| LayoutManager 5 模板（classic/focus/split/triple/canvas） | **保留**为仪表盘区布局；页面区用固定 AppFrame（TopBar+Sidebar+Main） | 模板化价值在仪表盘；页面需要稳定框架 |
|
||
| 31 个 widget 插件 | **保留骨架**，内容逐步替换/下线：与页面功能重复的卡片改为"页面入口卡 + 关键摘要"，数据接通真实 schema | 卡片应该是页面的摘要与入口，不是功能的全部 |
|
||
| config-service 三层插件配置 | **保留**，职责收缩为"仪表盘 + 导航可见性"配置 | 页面不再依赖插件配置，配置挂了不影响页面 |
|
||
| SWR 配置静默刷新 | **保留**于仪表盘 | 低频配置变更无需推送 |
|
||
| URL Search Params 跨插件共享 | **保留**并扩展为页面间状态契约（classId/childId/termId） | 已验证有效 |
|
||
| RSC 流式渲染（use() + Suspense） | **保留**并推广到页面级（页面 RSC 预取 + 流式注入） | 收益真实 |
|
||
| 三级错误边界 | **保留**，扩展：Route（页面 error.tsx）→ Section（页面区块）→ Widget（卡片） | 与页面体系对齐 |
|
||
|
||
### 3.4 v3.0 ADR 全文
|
||
|
||
#### V3-A1：混合路由模型（真实页面 + 仪表盘微内核）
|
||
|
||
- **背景**：v2.0 用单 catch-all + 插件配置承载全站，导致页面不可寻址（F1）、权限表空转（F4）、功能止步于卡片（F6）。
|
||
- **决策**：业务功能落在显式 Next.js 路由页面（`/shell/<role>/<module>/...`），共享 `AppFrame` 布局；插件系统收缩为 `/shell` 角色首页的聚合仪表盘。
|
||
- **取舍**：放弃"admin 可配置一切页面"的幻想——页面是代码、受版本控制、可 code review；admin 可配置的收缩为"导航可见性 + 仪表盘卡片 + 卡片 props"。这换来：真实 URL、浏览器前进后退、RSC 流式预取、路由级 loading/error、中间件门禁——全部是 Next.js 原生能力，不再自造。
|
||
- **插件与页面的关系**：卡片 = 页面的摘要 + 入口。点击卡片 → `router.push` 到对应页面。universal 插件按 role 渲染不同摘要视图的机制保留。
|
||
|
||
#### V3-A2：认证链闭环 + 删除 localStorage JWT
|
||
|
||
- **背景**：F3（无登录页、localStorage token 无人写入、默认角色 teacher）。
|
||
- **决策**：
|
||
1. `/login` 页面（迁移自旧 portal login，换 shadcn 令牌）。
|
||
2. `/api/auth/login` Route Handler：转发凭证到 iam（经 api-gateway），成功后把 JWT 写入 **httpOnly + Secure + SameSite=Strict cookie**（project_rules §4）；JS 永远接触不到 token。
|
||
3. `middleware.ts`：读取 cookie → 校验（开发态 decode 验签跳过，生产用 iam JWKS RS256 验签）→ 注入 `x-user-id`/`x-user-role`/`x-user-permissions` 请求头供 RSC 读取；无 token → redirect `/login?next=<pathname>`。
|
||
4. `/api/graphql` Route Handler：Apollo Client 的 HttpLink 指向同域 `/api/graphql`；Handler 从 cookie 取 token 加 `Authorization: Bearer` 转发 apollo-router，响应原样回传（含 APQ hash 请求）。
|
||
- **取舍**：多一跳同域代理（<5ms 本地开销），换来 token 全程不出 httpOnly cookie——消除 XSS 窃取凭证面；同时修复"浏览器绕过 api-gateway"问题（代理在服务端调 router，与 gateway 同信任域）。
|
||
- **DEV_MODE**：仅本地开发；提供 `dev-token` 合成身份（middleware 生成 x-user-* 头）。生产环境变量缺失/为 true 时启动直接拒绝（`instrumentation.ts` 启动校验）。
|
||
|
||
#### V3-A3：路由门禁 middleware 接线 + 权限模型修正
|
||
|
||
- **背景**：F4（checkRoutePermission 死代码）、F8（命名双轨）。
|
||
- **决策**：
|
||
1. `middleware.ts` 对每个 `/shell/**` 请求执行 `checkRoutePermission(pathname, bitmap, role)`；拒绝 → `/shell/forbidden`（403 页，新）。
|
||
2. `route-permissions.ts` 四表保留，**新增/移动路由必须同步登记**；CI 运行一致性脚本：扫描 `src/app/**/page.tsx` 路由 ⇄ 权限表双向核对，未登记即失败。
|
||
3. 权限点唯一来源 `PERMISSION_BITMAP_ORDER`；README 的点号示例作废；31 个 manifest 补登 `requiredPermissions`（L2 插件级，config-service 过滤用）。
|
||
4. `GRADE_READ` 重复项去重：保留首次出现位（索引 26），删除第二次（索引 31 处），该位标记 `_RESERVED_31` 占位永不复用；趁系统未签发真实 JWT，现在就改（P0）。
|
||
- **边界说明**：middleware 是 L1/L2 的**第一道**防线（性能/体验），不是唯一防线——resolver 级 `@RequirePermission`（后端）仍是权威。前端门禁防"走错门"，后端门禁防"恶意请求"。
|
||
|
||
#### V3-A4：GraphQL 契约纪律
|
||
|
||
- **背景**：F2（50 操作 vs 后端 38 查询/0 mutation，严格匹配 0/50）。
|
||
- **决策**：
|
||
1. **操作清单真实化**：`operations/*.graphql.ts` 只允许引用 `combined-schema.graphql` 真实存在的字段。每新增一个页面，先确认 schema 有所需字段；没有 → 走"契约工单"（§11.4）推动后端补齐，**同时**用 MSW mock 让页面先行。
|
||
2. **codegen 恢复强校验**：分域关闭 `skipDocumentsValidation`（哪个域后端补齐了就关哪个域），恢复 `typescript-operations` 生成操作级类型，**删除 lib/api 手写 inline 类型**（漂移源）。
|
||
3. **schema 同步自动化**：`scripts/normalize-schema.ts` 保留；新增 CI 步骤：子图 SDL 变更 → codegen diff 检查，operations 引用不存在字段即失败。
|
||
4. **PQ Manifest 随构建更新**：`prebuild` 已串联，保留。
|
||
- **后端已就绪可立即使用的资产**：config-service 全量配置查询；data-ana 的 4 个 `*Dashboard` 聚合查询 + `warnings`/`mastery*`/`diagnosticReports`/`errorBook*`；iam 的 `user/role/dataScope`；core-edu/content 的按 id 单查。**仪表盘首页应优先改用这些真实查询**（P1 任务）。
|
||
|
||
#### V3-A5：设计系统单源决议
|
||
|
||
- **背景**：F5（三方冲突 + 271 处断裂类）。
|
||
- **决策**：
|
||
1. **shadcn 标准令牌（@edu/ui-tokens，zinc 色板）为唯一设计系统**，全局适用（dashboard + 全部页面 + 登录页）。
|
||
2. `docs/standards/ui-design-system.md` 废止；其仍有价值的内容并入本文件 §8（布局/组件/动效/a11y 规范，按 shadcn 令牌重写）。
|
||
3. 纸感编辑器方向（Fraunces 主文 + 米白纸面）**降级为二期备课编辑器模块命名空间**（`--lp-*`），仅 lesson-plan 工作台内部使用；现在不做。
|
||
4. 31 widget 令牌清债（271 处）列入 P1：机械替换（`text-heading-3`→`text-lg font-semibold`、`mt-sm`→`mt-2`、`py-xs`→`py-1`、`px-sm`→`px-2`、`space-y-xs`→`space-y-1`、`p-md`→`p-4`、`gap-xs`→`gap-1`、`border border`→`border`），arch:scan 增加"未知 Tailwind 类"检测规则。
|
||
- **理由**：CICD 是已验证的 UX 基线，shadcn 生态（组件、文档、AI 协作默契度）最成熟；纸感全局化在旧 portal 实践中与 shadcn 组件冲突成本高，收敛为局部模块更现实。
|
||
|
||
#### V3-A6：next-intl 正式接入
|
||
|
||
- **背景**：旧页面用 `useTranslations`，messages 资产完整；portal-shell 现有自造 `useT()` 只有 3 条文案。
|
||
- **决策**：接入 next-intl（App Router 模式），`messages/zh-CN.json` + `messages/en.json` 从旧 portal 合并迁移；`ThemeI18nProvider` 删除自造 i18n，保留主题切换；新代码文案一律走 `useTranslations`，禁止硬编码中文字符串（ESLint 规则 P1 后启用，迁移期 warn）。
|
||
- **取舍**：增加一个依赖与少量配置，换取不重写全部文案 + 与 CICD/旧 portal 一致的 i18n 习惯。
|
||
|
||
#### V3-A7：MSW 开发兜底层
|
||
|
||
- **背景**：F7（无后端 = 空壳）。
|
||
- **决策**：迁移旧 portal 的 MSW handlers 为 portal-shell 的 `src/mocks/`（按 domain 分文件）；`NEXT_PUBLIC_MSW=1` 时 browser worker 拦截 `/api/graphql` 与 `/api/v1/*`；`src/instrumentation.ts`（或 middleware 旁路）在 dev + MSW 开启时给 RSC 侧也注入 mock fetcher。**生产构建通过 env 条件 import 保证 mocks 零字节进 bundle**。
|
||
- **双重收益**：前端不依赖后端就绪即可开发页面；Playwright E2E 直接复用 MSW 场景数据，测试稳定。
|
||
|
||
#### V3-A8：验收门禁改革
|
||
|
||
- **背景**：根因 1（验收指标错位）。
|
||
- **决策**：CI 质量门禁从 4 项扩为 8 项：`lint` + `typecheck` + `vitest` + `build` + **契约校验**（codegen diff）+ **路由表一致性** + **页面计数回归**（pages 数不得下降）+ **E2E 冒烟**（P6 起：登录 → 仪表盘 → 每角色 1 条核心流）。每个阶段的 README/本文件验收勾选必须附**命令输出或截图链接**。
|
||
|
||
---
|
||
|
||
## 4. 认证与身份链
|
||
|
||
### 4.1 目标流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as 浏览器
|
||
participant PS as portal-shell
|
||
participant GW as api-gateway :8080
|
||
participant IAM as iam
|
||
participant RT as apollo-router :3000
|
||
|
||
U->>PS: POST /api/auth/login {email, password}
|
||
PS->>GW: POST /api/v1/iam/auth/login
|
||
GW->>IAM: 验证凭证
|
||
IAM-->>GW: JWT (RS256) + user + permissions bitmap
|
||
GW-->>PS: 200 {token, user}
|
||
PS-->>U: Set-Cookie: edu_session=<JWT>; httpOnly; Secure; SameSite=Strict
|
||
Note over U: JS 永远拿不到 token
|
||
|
||
U->>PS: GET /shell/teacher/exams
|
||
PS->>PS: middleware: 校验 cookie → 注入 x-user-* 头 → checkRoutePermission
|
||
alt 无/坏 token
|
||
PS-->>U: 302 /login?next=/shell/teacher/exams
|
||
else 无权限
|
||
PS-->>U: 302 /shell/forbidden
|
||
else 放行
|
||
PS->>PS: RSC 读 x-user-* 头渲染页面
|
||
end
|
||
|
||
U->>PS: POST /api/graphql (Apollo, APQ hash)
|
||
PS->>PS: 从 cookie 取 token
|
||
PS->>RT: POST /graphql + Authorization: Bearer <JWT>
|
||
RT-->>PS: data
|
||
PS-->>U: data
|
||
```
|
||
|
||
### 4.2 组件清单
|
||
|
||
| 组件 | 文件 | 职责 |
|
||
| ------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
||
| 登录页 | `src/app/login/page.tsx` | 表单 → `/api/auth/login`；已登录跳转 next；迁移自旧 portal，换 shadcn 令牌 |
|
||
| 登录代理 | `src/app/api/auth/login/route.ts` | 调 gateway iam 登录 → Set-Cookie；失败归一化错误；限流透传 |
|
||
| 登出 | `src/app/api/auth/logout/route.ts` | 清 cookie + 调 iam 注销 |
|
||
| 中间件 | `src/middleware.ts` | 公共路径白名单 → cookie 校验 → 注入身份头 → `checkRoutePermission` → 重定向 |
|
||
| GraphQL 代理 | `src/app/api/graphql/route.ts` | cookie→Bearer 转发；APQ 透传；错误归一化；`cache: "no-store"` |
|
||
| RSC 身份工具 | `src/lib/auth/server.ts` | `getServerIdentity(): Promise<{userId, role, permissions}>`（读 middleware 注入的头，缺失即抛 → error boundary 跳登录） |
|
||
| DEV_MODE 守卫 | `src/instrumentation.ts` | `NODE_ENV=production && NEXT_PUBLIC_DEV_MODE=true` → 启动即抛错 |
|
||
| 403 页 | `src/app/shell/forbidden/page.tsx` | 说明 + 返回仪表盘链接 |
|
||
|
||
### 4.3 会话细节决策
|
||
|
||
- **cookie 名**：`edu_session`；`Path=/`；`Max-Age` 与 JWT exp 对齐；`Secure` 仅生产（本地 http 开发豁免，用 env 控制）。
|
||
- **验签**：middleware 用 `jose` 的 `createRemoteJWKSet(iam JWKS endpoint)` 验 RS256；JWKS 端点不可达时 **fail-closed**（跳登录），dev 模式降级为仅 decode（日志警告）。
|
||
- **权限位图来源**：登录响应中 iam 返回 permissions → login route 计算 base36 位图 → 写入第二个非 httpOnly cookie `edu_perms`（JS 可读，用于客户端按钮级显隐；**仅为 UX，不作为安全依据**——安全判断一律走后端 resolver + middleware 的 httpOnly 通道）。middleware 同样把位图注入 `x-user-permissions` 头。
|
||
- **角色切换/多角色**：iam 返回单主角色（与现 `x-user-role` 对齐）；多角色支持属后端二期，前端不预留。
|
||
- **旧 portal 的 `lib/auth.ts`（localStorage 方案）**：迁移时**删除**，不按原样搬运。
|
||
|
||
---
|
||
|
||
## 5. 数据层架构
|
||
|
||
### 5.1 分层（保留 v2.0 四层，修正两端）
|
||
|
||
```
|
||
页面/插件（UI）
|
||
→ lib/api/<domain>.ts（语义化 hooks：useExams(classId)）
|
||
→ lib/api/operations/*.graphql.ts（gql 文档，真实 schema 子集）
|
||
→ lib/useWidgetQuery / useWidgetMutation（Apollo 封装 + ApiError）
|
||
→ Apollo Client（APQ link）→ /api/graphql（同域代理）
|
||
→ apollo-router :3000 → 子图
|
||
```
|
||
|
||
- **RSC 服务端**：页面 RSC 用 `createApolloClient()`（已有）经内网直连 router（服务端不经代理，直接带 middleware 解析出的身份头）；客户端组件经 `/api/graphql` 代理。
|
||
- **SWR/轮询**：仪表盘配置保留 SWR；业务数据默认 Apollo `fetchPolicy: "cache-first"`，需要实时性的（通知铃铛）用 `pollInterval`；SSE 通知二期经 realtime-gateway。
|
||
|
||
### 5.2 GraphQL 同域代理（/api/graphql）
|
||
|
||
- 单文件 Route Handler，`POST` only；透传 body（APQ hash 或 query）；注入 `Authorization`；响应状态/JSON 原样返回。
|
||
- 不缓存（`export const dynamic = "force-dynamic"`）。
|
||
- 错误归一化：网络错误 → `{ errors: [{ message: "UPSTREAM_UNAVAILABLE" }] }`，客户端 `ApiError` 统一。
|
||
- 保留直连开关：`APOLLO_ROUTER_URL`（服务端 RSC 用），客户端永远只用 `/api/graphql`。
|
||
|
||
### 5.3 契约纪律（frontend ⇄ backend）
|
||
|
||
1. **schema 唯一源**：`src/lib/api/__generated__/combined-schema.graphql` 由 `scripts/normalize-schema.ts` 从 `services/*/src/graphql/generated/schema.graphql` 生成；**后端 SDL 变更后必须重跑 codegen**，CI 做 diff 检查。
|
||
2. **operations 真实性**：每个 operation 引用字段必须存在于 combined schema；恢复 `typescript-operations` 生成类型；lib/api 的手写 interface 逐步删除（P1 起按域推进：config → data-ana → core-edu → content → msg → iam）。
|
||
3. **后端未就绪的功能**：页面允许先上，数据走 MSW（`src/mocks/`），并在页面头部注释 `@contract-pending: <工单号>`；契约工单（§11.4）登记后端待补字段，**每周同步一次状态**。
|
||
4. **禁止事项**：禁止在 widget/页面内联 gql；禁止手写与 schema 冲突的类型；禁止为迁就前端瞎改 normalize 脚本（当前对 ai 子图的 String 改写保留，单独登记 TD）。
|
||
|
||
### 5.4 MSW 兜底层
|
||
|
||
- 位置：`src/mocks/`（`browser.ts`/`server.ts`/`handlers/<domain>.ts`），自旧 portal `src/mocks/handlers-p*.ts` 迁移并按 50+ 操作重组。
|
||
- 启用：`NEXT_PUBLIC_MSW=1`（仅 dev/test）；`src/app/layout.tsx` 条件 `import("@/mocks/browser")`（动态 import，production env 下该 import 永不执行 → tree-shaken）。
|
||
- 数据原则：使用与种子用户一致的语义数据（teacher2@edu.test 的班级/学生/成绩），数据量足够展示分页/空态/超长文本三种边界。
|
||
- E2E 复用：Playwright webServer 以 `NEXT_PUBLIC_MSW=1` 启动，用例不依赖真实后端。
|
||
|
||
### 5.5 后端已就绪查询的立即利用（P1 必做）
|
||
|
||
| 真实查询（schema 存在且 resolver 已实现） | 用于 | 注意 |
|
||
| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
|
||
| `pluginConfig(userId, role)` / `plugins` / `plugin(pluginId)` / `userLayoutOverride(userId)` | 仪表盘配置（已接，保留） | ✅ 全字段吻合 |
|
||
| `layoutTemplates` | admin 模板列表 | ⚠️ 仅 `layoutId/displayName/description/isActive`，**无 `availableSlots`**——前端选择集必须裁剪 |
|
||
| `teacherDashboard` / `studentDashboard` / `parentDashboard` / `adminDashboard` | **角色首页仪表盘主数据源**（替换现有卡片的假契约查询） | ✅，底层字段 snake_case 需在 lib/api 层映射 |
|
||
| `warnings` / `masterySummary` / `studentMastery` / `masteryDistribution` | 学情预警卡片 | ✅，同上 |
|
||
| `diagnosticReports` / `errorBookItems` / `errorBookStats` | 诊断/错题卡片与页面 | ✅，字段形状与现 widget 期望不同，需重写 hook |
|
||
| `user(userId)` / `role(roleId)` / `dataScope(userId)` | 用户菜单、权限显隐 | ⚠️ `User` 字段为 `userId/email/name/status/dataScope`（无 `id`/`role`） |
|
||
| `exam(id)` / `homework(id)` / `grade(id)` / `classInfo(id)` / `textbook(id)` / `question(id)` / `chapter(id)` / `knowledgePoint(id)` | 详情页首版（列表点击带 id 进入时可真实查询） | ⚠️ 字段名需按真实类型重写（如 `Exam.title/totalScore` 而非 `name/maxScore`） |
|
||
| `notifications(userId)` | 通知中心首版 | ⚠️ 平铺数组，无分页包装 |
|
||
| `lessonPlanStatus` | ai 子图唯一查询 | 仅状态轮询可用 |
|
||
|
||
---
|
||
|
||
## 6. 安全架构（安全边际）
|
||
|
||
### 6.1 威胁模型与防线矩阵
|
||
|
||
| 威胁 | 防线 | 位置 | 现状 | v3.0 处置 |
|
||
| ----------------------------------- | ----------------------------------------------------- | --------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------- |
|
||
| 未认证访问业务页 | middleware cookie 校验 | `src/middleware.ts` | ❌ 不存在 | P0 实现，fail-closed |
|
||
| 越权访问路由（teacher 进 admin 页） | L1 角色 + L2 权限点 | middleware + route-permissions 表 | ❌ 死代码 | P0 接线 + CI 一致性 |
|
||
| 越权访问数据 | resolver `@RequirePermission` + DataScope | 后端子图 | ✅（审计过 50 resolver） | 保持；前端不兜底也不替代 |
|
||
| 凭证被 XSS 窃取 | httpOnly cookie，JS 零接触 | `/api/auth/login` | ❌ localStorage 方案 | P0 替换 |
|
||
| GraphQL 任意查询探测 | APQ + PQ Manifest 白名单 | Apollo link + router | ✅ 链路完整（`require_manifest` 生产需开） | 保持；部署 env 列入 P6 检查单 |
|
||
| 深度/成本/批量 DoS | router limits | `router.yaml` | ✅ 已配 | 保持 |
|
||
| 绕过 router 直调子图 | RouterAuthGuard + `router-authorization` | 子图 | ⚠️ 密钥明文 `dev-router-secret` 入库 | P6 换 env 注入；生产 secret 轮换 |
|
||
| CSRF | SameSite=Strict cookie + 自定义头要求 | cookie + 代理 | ⚠️ 依赖 cookie 属性 | `/api/graphql` 要求 `content-type: application/json`（预检），登录接口 SameSite=Strict |
|
||
| 生产 DEV_MODE 误开 | 启动自检 | `instrumentation.ts` | ❌ compose 生产 profile 写 true | P0：compose 改 false + 启动校验抛错 |
|
||
| 错误上报刷爆 | sessionStorage digest 节流 | `useErrorReport` | ✅ 已实现 | 保持 |
|
||
| XSS 富文本 | 禁 `dangerouslySetInnerHTML`（grep 实测 src 内 0 处） | ESLint + 规范 | ✅ | 保持规则；富文本编辑器（二期）必须 DOMPurify |
|
||
| 敏感信息入仓 | `.env.local` 已入库（无密钥） | 仓库 | ⚠️ | P0：移出 + gitignore 补规则 |
|
||
|
||
### 6.2 三层安全边界（接线后真实形态）
|
||
|
||
| 层 | 机制 | 执行点 | 失败行为 |
|
||
| ----------- | ------------------------------------------------------------ | -------------------------------------------------- | ------------------------- |
|
||
| L1 角色门禁 | `requiredRoles` | **middleware**（每个 /shell/** 请求） | 302 → `/shell/forbidden` |
|
||
| L2 权限点 | `requiredPermissions`/`anyOfPermissions`（AND/OR，位图校验） | **middleware**（路由级）+ config-service（卡片级） | 302 → 403 页 / 卡片不渲染 |
|
||
| L3 数据范围 | DataScope 6 级 | 后端 resolver（权威）；前端仅 UX 显隐 | 后端拒绝 / 空态 |
|
||
|
||
**边界纪律（防"安全边际"幻觉）**：
|
||
|
||
1. 前端门禁是**体验层**，后端 resolver 是**权威层**；任何"前端已挡"不得成为后端不加 `@RequirePermission` 的理由。
|
||
2. `edu_perms` 可读 cookie 只用于按钮显隐；**禁止**用它做任何数据请求的放行判断。
|
||
3. middleware 校验失败一律 fail-closed；`checkRoutePermission` 未匹配的路由**默认拒绝**（当前实现默认放行，P0 改为：/shell/** 下未登记路由默认拒绝，公共路径显式白名单）。
|
||
4. JWT 过期统一处理：`/api/graphql` 收到 401 → 清 cookie → 返回 `{ errors: [{extensions:{code:"UNAUTHENTICATED"}}] }`；客户端 Apollo errorLink 拦截 → `location.href = "/login"`。
|
||
|
||
---
|
||
|
||
## 7. 信息架构与页面体系
|
||
|
||
### 7.1 路由树（目标态）
|
||
|
||
```
|
||
/login 登录
|
||
/shell/forbidden 403
|
||
/shell 角色仪表盘（按 x-user-role 分发渲染对应仪表盘）
|
||
/shell/teacher/… 教师功能区（~50 页，见 §9.1）
|
||
/shell/student/… 学生功能区（~34 页，见 §9.2）
|
||
/shell/parent/… 家长功能区（~21 页，见 §9.3）
|
||
/shell/admin/… 管理功能区（~22 页，见 §9.4）
|
||
/shell/settings 通用设置（全角色）
|
||
/shell/notifications 通知中心（全角色）
|
||
```
|
||
|
||
- URL 前缀 `/shell/<role>/` 与 route-permissions 表语义对齐（PREFIX 表按前缀批量保护）。
|
||
- 仪表盘 `/shell` 按角色渲染不同插件集（现有机制），同时是各功能卡的入口枢纽。
|
||
- 跨角色同构页面（如 notifications/settings）放共享路径，权限表按角色开放。
|
||
|
||
### 7.2 AppFrame（页面框架）
|
||
|
||
`src/app/shell/layout.tsx`（新）：
|
||
|
||
```
|
||
┌──────────────────────────────────────────────┐
|
||
│ TopBar：global-search · notification-bell │
|
||
│ locale-switcher · user-menu │
|
||
├──────────┬───────────────────────────────────┤
|
||
│ Sidebar │ Main（{children}） │
|
||
│ 导航菜单 │ 页面区（显式路由页面） │
|
||
│ （按角色/ │ 或仪表盘（/shell） │
|
||
│ 权限过滤）│ │
|
||
│ + 上下文 │ │
|
||
│ 选择器 │ │
|
||
└──────────┴───────────────────────────────────┘
|
||
```
|
||
|
||
- **TopBar**：复用现有 4 个 topbar 插件（它们本就是全站级组件），不再走插件配置（改为静态挂载 + 权限显隐），仪表盘配置不再能"关掉导航"导致页面失联。
|
||
- **Sidebar 导航菜单（新组件）**：导航项 = 静态注册表 `src/shared/lib/navigation.ts`（label/i18n key/icon/href/requiredRoles/requiredPermissions），渲染前用 `batchCheckRoutePermission` 过滤（对应 004 §5.4 视口 L1）；当前路由高亮；收纳现有 4 个 sidebar 插件（class-selector/child-selector/term-switcher/quick-actions）于菜单下方"上下文区"。
|
||
- **Main**：仪表盘路由渲染微内核仪表盘；业务路由渲染页面。页面内可用 `DashboardSection`/`SectionErrorBoundary` 组织区块。
|
||
- **RSC 流式**：layout 保持轻量（导航静态），页面各自 RSC 预取 + Suspense；现有 ClientShell 流式机制迁移为页面级工具（`src/lib/streaming.tsx` 导出 `StreamedPage` 封装，避免每页重写 Provider/Suspense 样板）。
|
||
|
||
### 7.3 页面四种类型与模板（新页面必须套模板）
|
||
|
||
| 类型 | 适用 | 结构骨架 | 示例 |
|
||
| ------------ | ---------------------- | ------------------------------------------------------------------------- | ---------------------------------------- |
|
||
| **列表页** | 集合浏览 + 筛选 + 分页 | PageHeader + FilterBar + DataTable/列表 + Pagination + 空态/骨架/错误三态 | exams、homework、users |
|
||
| **详情页** | 单实体查看 + 关联操作 | PageHeader（标题+操作） + 信息区 + Tabs/分区 + 关联列表 | exams/[id]、textbooks/[id] |
|
||
| **表单页** | 创建/编辑 | PageHeader + 表单（react-hook-form + zod）+ 提交/取消 + 错误摘要 | exams/new、lesson-plans/new |
|
||
| **工作台页** | 多栏协同复杂任务 | 三栏（树/画布/属性）复合组件（Workbench 模式） | lesson-plans/[id]/edit、exams/[id]/build |
|
||
|
||
模板代码位置：`src/shared/components/page-templates/{list-page,detail-page,form-page,workbench-page}.tsx`（P1 建）。**新页面一律 `import` 模板而非手排布局**——保证 140 页视觉/交互一致，也是 AI 批量迁移时的统一落点。
|
||
|
||
### 7.4 页面级数据获取模式（统一）
|
||
|
||
```tsx
|
||
// src/app/shell/teacher/exams/page.tsx（RSC 示例骨架）
|
||
export default async function ExamsPage(): Promise<React.ReactElement> {
|
||
const { userId, role } = await getServerIdentity();
|
||
const client = createApolloClient();
|
||
const dataPromise = client.query({
|
||
query: GET_EXAMS_DOC,
|
||
variables: {/* … */},
|
||
});
|
||
return (
|
||
<ListPageShell titleKey="exams.title">
|
||
{/* Promise 直传客户端组件，use() 消费（沿用现有流式模式） */}
|
||
<ExamsList dataPromise={dataPromise} />
|
||
</ListPageShell>
|
||
);
|
||
}
|
||
```
|
||
|
||
- 列表/详情页：RSC 预取首屏 → `use()` 流式注入 → 客户端交互（筛选/翻页）走 Apollo hooks。
|
||
- 表单页：客户端组件 + `useWidgetMutation`；成功后 `router.refresh()`。
|
||
- 每页必须实现三态：`loading.tsx`（骨架，复用 PluginSkeleton 变体）/ `error.tsx`（Route 级边界，已有模式）/ 空态（`empty-state.tsx`）。
|
||
|
||
---
|
||
|
||
## 8. 前端设计规范（强制）
|
||
|
||
> 本章是 portal-shell 唯一的视觉/交互权威，废止 `docs/standards/ui-design-system.md`。所有新页面/插件/组件必须遵守；迁移页面时按本章改造。违反本节任意"铁律"的 PR 不得合入。
|
||
|
||
### 8.1 设计令牌（三层，唯一来源）
|
||
|
||
| 层 | 位置 | 业务可用性 |
|
||
| ------------ | -------------------------------------------------------------- | ---------------------------------------------------------------- |
|
||
| L1 Primitive | `packages/ui-tokens/src/primitive.css` | ❌ 禁止直接引用 |
|
||
| L2 Semantic | `packages/ui-tokens/src/semantic-{light,dark}.css` | ✅ 经 `hsl(var(--*))` |
|
||
| L3 Tailwind | `packages/ui-tokens/src/tailwind-theme.css`（`@theme inline`） | ✅ 首选：`bg-background`/`text-foreground`/`bg-card`/`border` 等 |
|
||
|
||
**铁律（ESLint + code review 双重执行）**：
|
||
|
||
1. 禁 `#hex` 字面量（现有规则保留）。
|
||
2. 禁字体名字面量（现有规则保留）。
|
||
3. 禁 `font-size: Npx`；字号用 Tailwind 阶梯（`text-xs/sm/base/lg/xl/2xl`）或 `text-size-*`。
|
||
4. 禁 Tailwind 任意值（`w-[137px]`）；间距用默认阶梯（`p-2/p-4/p-6/gap-2/gap-4`）或 `--space-*`。
|
||
5. **禁引入第二套令牌/第二套 CSS 变量体系**（纸感 `--paper-*`/`--ink-*` 一律不得回潮；迁移旧页面时必须清除）。
|
||
6. 暗色主题：仅经 `.dark` class + 语义令牌响应；禁组件内写死亮色值。
|
||
7. 圆角：`rounded-xl`（卡）/`rounded-md`（控件）/`rounded-full`（头像徽章）；阴影克制：浮层 `shadow-sm`，卡片默认无阴影。
|
||
|
||
### 8.2 字体与排版
|
||
|
||
- **单一字体族 Inter**（`next/font` 已挂载 `--font-inter` → `font-sans`）；数字密集表格列用 `font-mono`（Tailwind 默认等宽）右对齐。
|
||
- 标题层级：页面标题 `text-2xl font-semibold`；区块标题 `text-lg font-semibold`；卡片标题 `text-base font-medium`；正文 `text-sm`；辅助 `text-xs text-muted-foreground`。
|
||
- 行高：正文 `leading-relaxed`；标题 `leading-tight`。
|
||
- 中文界面默认 `lang="zh-CN"`（已配置）；i18n 文案经 next-intl。
|
||
|
||
### 8.3 组件使用
|
||
|
||
- **基础组件一律来自** `src/shared/components/ui/*`（shadcn 标准件）与 `packages/ui-components/*`（data-table/form/modal/chart/calendar 等 19 件）；缺组件先扩库再使用，**禁止页面内手写第三套按钮/输入框**。
|
||
- 业务复合件：`page-templates` 四件套（§7.3）+ `page-header`/`stat-card`/`stats-grid`/`empty-state`/`filter-bar`（已有）。
|
||
- Toast 一律 `notify.*`（`src/shared/lib/notify.ts`）；**禁** `import { toast } from "sonner"`（P0 补 ESLint `no-restricted-imports` 真正落地）；**禁空 catch**（现有 `catch { /* toast */ }` 反例必须改）。
|
||
- 图标：`lucide-react` 单一来源；图标按钮必须 `aria-label`。
|
||
- 表格：数据列数字 `font-mono` 右对齐；行分隔 `divide-y divide-border`；禁大面积色块。
|
||
|
||
### 8.4 布局与间距
|
||
|
||
- 页面容器：`px-6 py-6`（桌面），最大宽度不设限（工作台型产品），列表页可 `max-w-7xl`。
|
||
- 区块间距 `space-y-6`；卡片内边距 `p-4` 或 `p-6`。
|
||
- 三栏工作台仅在"编辑类"页面使用（备课/组卷），比例 260px / 1fr / 380px（Workbench 模板内置）。
|
||
|
||
### 8.5 动效
|
||
|
||
- 交互反馈 ≤ 200ms；页面过渡 ≤ 300ms；遵守 `prefers-reduced-motion`（globals.css 已有）。
|
||
- 加载一律骨架屏（PluginSkeleton 五变体 / 页面 loading.tsx），**禁居中 spinner 长转**。
|
||
- 禁装饰性持续动画；hover 反馈用 `bg-muted`/`bg-accent`，禁 `scale-105`。
|
||
|
||
### 8.6 可访问性（WCAG AA）
|
||
|
||
- 对比度：正文 ≥ 4.5:1（zinc 令牌天然满足，禁自调浅色）。
|
||
- 所有交互元素可 Tab 聚焦；`focus-visible:ring-2 focus-visible:ring-ring`。
|
||
- 语义化标签（`nav/main/aside/table`）；表单控件必须 `<label>` 或 `aria-label`；动态更新区 `aria-live="polite"`（骨架组件已带，页面复用即可）。
|
||
- 右键/下拉菜单支持键盘（Radix 组件默认满足，勿破坏）。
|
||
|
||
### 8.7 文案与 i18n
|
||
|
||
- 一律 `useTranslations`；命名空间按页面域（`exams.*`/`homework.*`/`common.*`）。
|
||
- 占位/空态文案必须给出"下一步行动"（如"暂无考试 → 新建考试"按钮），禁裸"暂无数据"。
|
||
|
||
---
|
||
|
||
## 9. 页面迁移总表（~140 页）
|
||
|
||
> 功能全景基准：CICD 原版 **155 页**（Next.js 16 + Server Actions + Drizzle，无 GraphQL；auth 4 + onboarding 1 + dashboard 公共 8 + admin 41 + teacher 54 + student 25 + parent 14 + management/grade 5）。
|
||
> 迁移源：仓库内 4 个旧 portal（`apps/*-portal/`，共 140 个 page.tsx），其页面实现完整但栈为 urql + next-intl + MSW + 纸感令牌。
|
||
> 缺口说明：旧 portal 未覆盖 CICD 的 management/grade 年级组维度（5 页）与 register/privacy/terms/onboarding（4+ 页）——这两块列为**新增（N）**，排在对应批次末尾。
|
||
> 迁移动作统一定义：**M = 迁移改造**（移植交互逻辑 + 换 Apollo 数据层 + 换 shadcn 令牌 + 套页面模板）；**N = 新建**（旧版没有）；**R = 替换**（现有 widget 升级为页面）。
|
||
> 批次即 §10 路线图的阶段：B1=先行骨架（P1）、B2=教师（P2）、B3=学生（P3）、B4=家长（P4）、B5=管理（P5）。
|
||
> 契约列：✅=schema 已有（注意字段形状差异，见 §5.5）；🟡=部分（单查有/列表无）；❌=schema 无，需契约工单 + MSW 先行。
|
||
|
||
### 9.1 教师域（teacher-portal 56 页 → /shell/teacher/*，B1+B2）
|
||
|
||
| 源路由（teacher-portal） | 目标路由 | 动作 | 契约 | 批次 |
|
||
| ------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------- | ---------------------------------- | ----- |
|
||
| `login` | `/login` | M（全站唯一登录页） | ✅ | B1 |
|
||
| `(app)/dashboard` | `/shell`（教师仪表盘） | R（仪表盘改接 `teacherDashboard` 真实查询） | ✅ | B1 |
|
||
| `(app)/exams` | `/shell/teacher/exams` | M 列表页 | 🟡 | B2 |
|
||
| `(app)/exams/new` | `/shell/teacher/exams/new` | M 表单页 | ❌ mutation | B2 |
|
||
| `(app)/exams/[id]` | `/shell/teacher/exams/[id]` | M 详情页 | ✅ `exam(id)` | B2 |
|
||
| `(app)/exams/[id]/build` | `/shell/teacher/exams/[id]/build` | M 工作台页 | ❌ | B2 |
|
||
| `(app)/exams/[id]/edit-rich` | `/shell/teacher/exams/[id]/edit` | M 工作台页 | ❌ | B2 |
|
||
| `(app)/exams/[id]/analytics` | `/shell/teacher/exams/[id]/analytics` | M 详情页（图表） | 🟡 `assignmentAnalysis` | B2 |
|
||
| `(app)/exams/[id]/proctoring` | `/shell/teacher/exams/[id]/proctoring` | M（二期，WS） | ❌ | B2 末 |
|
||
| `(app)/homework`、`/new`、`/[id]`、`/submissions`（共 7 页） | `/shell/teacher/homework/*`（同构 7 页） | M | 🟡/❌ | B2 |
|
||
| `(app)/grades`、`/entry`、`/analytics`、`/stats`、`/report-card`（5 页） | `/shell/teacher/grades/*`（5 页） | M | 🟡/❌ | B2 |
|
||
| `(app)/lesson-plans`、`/new`、`/library`、`/calendar`、`/heatmap`、`/[planId]/edit`（6 页） | `/shell/teacher/lesson-plans/*`（6 页） | M（edit 为工作台页） | ❌ | B2 |
|
||
| `(app)/questions` | `/shell/teacher/questions` | M 列表页 | 🟡 `question(id)` | B2 |
|
||
| `(app)/textbooks`、`/[id]`（2 页） | `/shell/teacher/textbooks/*`（2 页） | M | 🟡 `textbook(id)` | B2 |
|
||
| `(app)/attendance`、`/sheet`、`/report`、`/stats`（4 页） | `/shell/teacher/attendance/*`（4 页） | M | ❌ | B2 |
|
||
| `(app)/classes`、`/[id]`、`/schedule`（3 页） | `/shell/teacher/classes/*`（3 页） | M | 🟡 `classInfo(id)` | B2 |
|
||
| `(app)/students` | `/shell/teacher/students` | M | ❌ | B2 |
|
||
| `(app)/course-plans`、`/[id]`（2 页） | `/shell/teacher/course-plans/*`（2 页） | M | ❌ | B2 |
|
||
| `(app)/elective`、`/create`、`/[id]/edit`（3 页） | `/shell/teacher/elective/*`（3 页） | M | ❌ | B2 |
|
||
| `(app)/error-book` | `/shell/teacher/error-book` | M | ✅ `errorBookItems/Stats` | B2 |
|
||
| `(app)/diagnostic`、`/class/[classId]`（2 页） | `/shell/teacher/diagnostic/*`（2 页） | M | ✅ `diagnosticReports` | B2 |
|
||
| `(app)/analytics`、`/[studentId]`（2 页） | `/shell/teacher/analytics/*`（2 页） | M | 🟡 data-ana 多查询 | B2 |
|
||
| `(app)/ai-assist`、`/ai-lesson-plan`、`/ai-report`（3 页） | `/shell/teacher/ai/*`（3 页） | M | ❌（ai 子图仅 `lessonPlanStatus`） | B2 末 |
|
||
| `(app)/knowledge-graph` | `/shell/teacher/knowledge-graph` | M | 🟡 `knowledgePoint(id)` | B2 末 |
|
||
| `(app)/practice` | `/shell/teacher/practice` | M | ❌ | B2 |
|
||
| `(app)/schedule-changes` | `/shell/teacher/schedule-changes` | M | ❌ | B2 |
|
||
| `(app)/leave` | `/shell/teacher/leave` | M | ❌ | B2 |
|
||
| `(app)/notifications` | `/shell/notifications`（共享） | M | ✅ `notifications(userId)` | B1 |
|
||
| `(app)/settings` | `/shell/settings`（共享） | M | ✅ | B1 |
|
||
|
||
### 9.2 学生域（student-portal 36 页 → /shell/student/*，B3）
|
||
|
||
| 源路由 | 目标路由 | 动作 | 契约 | 批次 |
|
||
| ----------------------------------------------- | ------------------------------------------- | ---------------------- | ------------------------------------------------------- | ----- |
|
||
| `dashboard`、`/trend`、`/weakness` | `/shell`（学生仪表盘）+ 2 详情页 | R + M | ✅ `studentDashboard`/`learningTrend`/`studentWeakness` | B3 |
|
||
| `my-grades`、`/report-card` | `/shell/student/grades/*`（2 页） | M | ❌（列表） | B3 |
|
||
| `my-exams`、`/[id]/result`、`/[id]/take` | `/shell/student/exams/*`（3 页） | M（take 为作答工作台） | 🟡/❌ | B3 |
|
||
| `my-homework`、`/[id]/submit`、`/[id]/analysis` | `/shell/student/homework/*`（3 页） | M | 🟡/❌ | B3 |
|
||
| `schedule` | `/shell/student/schedule` | M | ❌ | B3 |
|
||
| `my-attendance` | `/shell/student/attendance` | M | ❌ | B3 |
|
||
| `my-classes` | `/shell/student/classes` | M | ❌ `myClasses` | B3 |
|
||
| `courses`、`/[id]` | `/shell/student/courses/*`（2 页） | M | ❌ | B3 |
|
||
| `course-plans`、`/[id]` | `/shell/student/course-plans/*`（2 页） | M | ❌ | B3 |
|
||
| `lesson-plans`、`/[id]/view` | `/shell/student/lesson-plans/*`（2 页） | M | ❌ | B3 |
|
||
| `textbooks`、`/[id]/chapters` | `/shell/student/textbooks/*`（2 页） | M | 🟡 | B3 |
|
||
| `error-book` | `/shell/student/error-book` | M | ✅ | B3 |
|
||
| `learning`、`learning-path` | `/shell/student/learning`、`/learning-path` | M | ❌ | B3 |
|
||
| `practice`、`/[sessionId]` | `/shell/student/practice/*`（2 页） | M | ❌ | B3 |
|
||
| `elective`、`/[id]` | `/shell/student/elective/*`（2 页） | M | ❌ | B3 |
|
||
| `ai-tutor` | `/shell/student/ai-tutor` | M | ❌ | B3 末 |
|
||
| `announcements`、`/[id]` | `/shell/announcements/*`（共享 2 页） | M | ❌（列表） | B3 |
|
||
| `messages` | `/shell/messages` | M | ❌ | B3 末 |
|
||
| `notifications`、`settings` | 共享路由 | M | ✅ | B1/B3 |
|
||
| `leave` | `/shell/student/leave` | M | ❌ | B3 |
|
||
|
||
### 9.3 家长域（parent-portal 24 页 → /shell/parent/*，B4）
|
||
|
||
| 源路由 | 目标路由 | 动作 | 契约 | 批次 |
|
||
| --------------------------------------------------- | -------------------------------------- | ----- | -------------------- | ---- |
|
||
| `parent/dashboard`、`/trend`、`/weakness` | `/shell`（家长仪表盘）+ 2 页 | R + M | ✅ `parentDashboard` | B4 |
|
||
| `parent/children/[studentId]` | `/shell/parent/children/[studentId]` | M | ❌ `myChildren` | B4 |
|
||
| `parent/grades`、`/report-card` | `/shell/parent/grades/*`（2 页） | M | ❌ | B4 |
|
||
| `parent/exams`、`/[id]/result` | `/shell/parent/exams/*`（2 页） | M | 🟡/❌ | B4 |
|
||
| `parent/homework` | `/shell/parent/homework` | M | ❌ | B4 |
|
||
| `parent/attendance` | `/shell/parent/attendance` | M | ❌ | B4 |
|
||
| `parent/classes` | `/shell/parent/classes` | M | ❌ | B4 |
|
||
| `parent/course-plans`、`/[id]` | `/shell/parent/course-plans/*`（2 页） | M | ❌ | B4 |
|
||
| `parent/lesson-plans`、`/[planId]/view` | `/shell/parent/lesson-plans/*`（2 页） | M | ❌ | B4 |
|
||
| `parent/error-book` | `/shell/parent/error-book` | M | ✅ | B4 |
|
||
| `parent/diagnostic` | `/shell/parent/diagnostic` | M | ✅ | B4 |
|
||
| `parent/learning-path` | `/shell/parent/learning-path` | M | ❌ | B4 |
|
||
| `parent/practice` | `/shell/parent/practice` | M | ❌ | B4 |
|
||
| `parent/elective` | `/shell/parent/elective` | M | ❌ | B4 |
|
||
| `parent/leave` | `/shell/parent/leave` | M | ❌ | B4 |
|
||
| `parent/notifications`、`/settings`、`/preferences` | 共享 + `/shell/parent/preferences` | M | ✅/❌ | B4 |
|
||
|
||
### 9.4 管理域（admin-portal 24 页 → /shell/admin/*，B5）
|
||
|
||
| 源路由 | 目标路由 | 动作 | 契约 | 批次 |
|
||
| ---------------------------------- | -------------------------------------------- | --------------------------------- | ------------------- | ---- |
|
||
| `admin/dashboard` | `/shell`（管理仪表盘） | R | ✅ `adminDashboard` | B5 |
|
||
| `admin/users` | `/shell/admin/users` | R（现有 widget 升级整页） | ❌ `users` 列表 | B5 |
|
||
| `admin/roles`、`admin/permissions` | `/shell/admin/roles`、`/permissions`（2 页） | R/M | ❌ | B5 |
|
||
| `admin/audit-logs` + 3 子页 | `/shell/admin/audit-logs/*`（4 页） | M | ❌ | B5 |
|
||
| `admin/invitation-codes` | `/shell/admin/invitation-codes` | R | ❌ | B5 |
|
||
| `admin/school` + 5 子页 | `/shell/admin/school/*`（6 页） | M | ❌ | B5 |
|
||
| `admin/classes` | `/shell/admin/classes` | M | ❌ | B5 |
|
||
| `admin/students`、`admin/teachers` | `/shell/admin/students`、`/teachers`（2 页） | M | ❌ | B5 |
|
||
| `admin/organization` | `/shell/admin/organization` | M | ❌ | B5 |
|
||
| `admin/announcements` | `/shell/admin/announcements` | M | ❌ | B5 |
|
||
| `admin/files` | `/shell/admin/files` | M | ❌ | B5 |
|
||
| `admin/ai-settings` | `/shell/admin/ai-settings` | M | ❌ | B5 |
|
||
| `admin/system` | `/shell/admin/system` | M | ❌ | B5 |
|
||
| `admin/viewports` | `/shell/admin/viewports` | M（对齐 004 §5.4 视口配置） | ❌ | B5 |
|
||
| —（新）插件管理 | `/shell/admin/plugins` | R（现有 plugin-manager 升级整页） | ✅ config-service | B5 |
|
||
|
||
### 9.5 计数与节奏
|
||
|
||
| 域 | 页面数 | 契约已就绪（✅/🟡） | 批次 |
|
||
| -------------------------------------------------------------------------------------------------- | -------- | ------------------- | ------------- |
|
||
| 共享（login/notifications/settings/announcements/messages/forbidden） | ~7 | 4 | B1/B3 |
|
||
| 教师 | ~50 | ~14 | B1+B2 |
|
||
| 学生 | ~34 | ~8 | B3 |
|
||
| 家长 | ~21 | ~5 | B4 |
|
||
| 管理 | ~22 | ~3 | B5 |
|
||
| 缺口新增（management/grade 5 页 + register/onboarding/privacy/terms ~5 页，CICD 有而旧 portal 无） | ~10 | 0 | B2/B5 末（N） |
|
||
| **合计** | **~144** | **~34** | — |
|
||
|
||
**节奏原则**：契约就绪页先行；❌ 页用 MSW 先上 UI，契约工单跟踪后端补齐后切换真实查询（切换 = 改 hook 的 fetcher 指向，页面不动）。
|
||
|
||
---
|
||
|
||
## 10. 实施路线图（P0–P6）
|
||
|
||
> 每阶段列出：目标 / 范围 / 验收标准（可复现命令 + 运行态证据）。阶段内任务按 §11 规范拆给多 AI 并行。**未完成上一阶段退出标准不得进入下一阶段。**
|
||
|
||
### P0 · 地基止血（1 周）— ✅ 已完成（2026-07-22 验收）
|
||
|
||
**目标**：消除"空壳即不可用 + 认证裸奔"两大致命伤。
|
||
|
||
| # | 任务 | 验收 | 状态 |
|
||
| ---- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
||
| P0-1 | `/login` 页 + `/api/auth/login | logout`+`edu_session` httpOnly cookie | 本地起 iam/gateway，错误密码报错、正确密码进 /shell；cookie 在 DevTools Application 可见且 httpOnly | ✅ |
|
||
| P0-2 | `src/middleware.ts`：cookie 校验 + 身份头注入 + `checkRoutePermission` 接线 + `/shell/forbidden` | 无 cookie 访问 /shell/** → 302 /login；student 访问 /shell/admin/users → 302 /shell/forbidden（截图） | ✅ |
|
||
| P0-3 | `/api/graphql` 代理 + Apollo Client 指向同域 + 删除 localStorage token 方案 | DevTools Network 面板无 `localhost:3000` 直连；`grep -r "localStorage" src/providers` 无 token 读取 | ✅ |
|
||
| P0-4 | 配置兜底改进：`getDefaultConfig()` 返回**内置默认仪表盘插件集**（按角色静态定义），config-service 不可用时仪表盘仍有内容 | 停掉 config-service 与 router，启动前端，/shell 显示默认卡片而非"暂无可见插件"（截图） | ✅ |
|
||
| P0-5 | DEV_MODE 生产守卫：`instrumentation.ts` 启动校验 + `docker-compose.yml` 生产 profile 改 `NEXT_PUBLIC_DEV_MODE: "false"` | `NODE_ENV=production NEXT_PUBLIC_DEV_MODE=true pnpm start` 启动即报错退出 | ✅ |
|
||
| P0-6 | 权限位图修正：`GRADE_READ` 去重（保留索引位，二见位改 `_RESERVED_`）+ 单测更新 | `vitest run permission-bitmap` 通过；`validateRoutePermissionConfigs()` 返回空 | ✅ |
|
||
| P0-7 | ESLint 补齐：`no-restricted-imports`（禁 widget 跨目录 import、禁直 import sonner、禁页面绕过 lib/api 直 import @apollo/client） | `pnpm lint` 对预埋反例报错（附输出） | ✅ |
|
||
| P0-8 | 仓库卫生：`.env.local` 移出版本控制 + `.gitignore` 补 `tsconfig.tsbuildinfo` | `git status` 干净 | ✅ |
|
||
|
||
**P0 验收证据（2026-07-22）**：
|
||
|
||
- **P0-1**：`POST http://localhost:8080/api/v1/iam/login`（错误密码）→ 401；`POST http://localhost:4010/api/auth/login`（错误密码）→ 401 `{"error":"INVALID_CREDENTIALS","message":"邮箱或密码错误"}`。实现：[src/app/api/auth/login/route.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/app/api/auth/login/route.ts) + [src/app/api/auth/logout/route.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/app/api/auth/logout/route.ts) + [src/app/login/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/login/page.tsx)
|
||
- **P0-2**：[src/middleware.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/middleware.ts) 实现 cookie 校验 + 身份头注入 + `checkRoutePermission`；[src/app/shell/forbidden/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/forbidden/page.tsx) 提供 403 页面
|
||
- **P0-3**：`grep -r "localStorage" src/providers` 仅匹配 [ApolloProvider.tsx:12](file:///e:/Desktop/Edu/apps/portal-shell/src/providers/ApolloProvider.tsx#L12) 的删除说明注释，无 token 读取；[src/app/api/graphql/route.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/app/api/graphql/route.ts) 提供同域代理
|
||
- **P0-4**：[src/lib/config-fetcher.ts:214](file:///e:/Desktop/Edu/apps/portal-shell/src/lib/config-fetcher.ts#L214) `getDefaultConfig(role)` 返回内置默认仪表盘插件集（classic 布局 + top/side/main slots）
|
||
- **P0-5**：[src/instrumentation.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/instrumentation.ts) `register()` 在 `NODE_ENV=production` 且 `NEXT_PUBLIC_DEV_MODE!=false` 时 `process.exit(1)`
|
||
- **P0-6**：`vitest run permission-bitmap` → 27/27 通过；[packages/shared-ts/src/permission-bitmap.ts](file:///e:/Desktop/Edu/packages/shared-ts/src/permission-bitmap.ts) `GRADE_READ` 去重，`_RESERVED_31` 占位
|
||
- **P0-7**：`eslint .` → 0 errors, 2 warnings（均在 `__generated__/types.ts` 生成文件）；[eslint.config.js](file:///e:/Desktop/Edu/apps/portal-shell/eslint.config.js) 含 `no-restricted-imports`
|
||
- **P0-8**：`git status` 干净（commit `cfb7b00`）；`.env.local` 与 `tsconfig.tsbuildinfo` 已在 [.gitignore](file:///e:/Desktop/Edu/apps/portal-shell/.gitignore)
|
||
|
||
### P1 · 框架与数据源接通（1–2 周）— 全部完成（P1-1 至 P1-8 ✅ 2026-07-22 验收）
|
||
|
||
**目标**：AppFrame + 导航 + 真实数据仪表盘 + 页面模板 + MSW + i18n，页面迁移的"流水线"建成。
|
||
|
||
| # | 任务 | 验收 | 状态 |
|
||
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---- |
|
||
| P1-1 | `src/app/shell/layout.tsx` AppFrame（TopBar 静态挂载 + Sidebar 导航菜单 `navigation.ts` + 权限过滤） | 4 角色各见各菜单；导航项与 route-permissions 表一致（单测） | ✅ |
|
||
| P1-2 | 仪表盘改接真实查询：`teacherDashboard`/`studentDashboard`/`parentDashboard`/`adminDashboard` + `warnings`/`errorBookStats` | 起全栈，4 角色仪表盘显示真实聚合数据（截图）；widget 假契约查询（grades/homeworks/schedule/attendance/exams/announcements）全部下线或改造 | ✅ |
|
||
| P1-3 | 页面模板四件套（list/detail/form/workbench）+ 三态规范 | Storybook 或示例页 4 张（/shell/dev/templates/*，仅 dev 可见；注：Next.js 私有文件夹 `_xxx` 不参与路由，故使用 `dev` 而非 `_dev`） | ✅ |
|
||
| P1-4 | next-intl 接入 + messages 合并迁移 | 切换 locale 页面文案切换（截图）；`useT` 自造函数删除 | ✅ |
|
||
| P1-5 | MSW 兜底层（迁移旧 handlers，覆盖 dashboard/users/exams/grades 四域起步） | `NEXT_PUBLIC_MSW=1` 无后端启动，仪表盘 + users 页有数据（截图）；生产构建 bundle 无 mocks | ✅ |
|
||
| P1-6 | 31 widget 令牌清债（271 处机械替换）+ `border border` 去重 + 未知类检测进 arch:scan | `grep -c "text-heading-\|mt-sm\|py-xs\|p-md" src/widgets` = 0；`pnpm lint:tokens` 通过 | ✅ |
|
||
| P1-7 | codegen 恢复 typescript-operations（data-ana 域先行关闭 skipDocumentsValidation；config 域因 schema 缺 `availableSlots` 推迟，见证据段） | 生成操作级类型；lib/api 对应域删除手写 interface；typecheck 通过 | ✅ |
|
||
| P1-8 | CI 增补：路由表一致性脚本 + 页面计数 + codegen diff 检查 | CI 对预埋违规报红（附 pipeline 链接） | ✅ |
|
||
|
||
**P1-1 验收证据（2026-07-22）**：
|
||
|
||
- **单测**：`vitest run --reporter=verbose navigation` → 7/7 passed
|
||
- 每个导航项 href 在 EXACT/PREFIX/DASHBOARD 表登记
|
||
- teacher/student/parent/admin 各仅见本组导航项
|
||
- 4 角色导航项两两不交叉（角色隔离）
|
||
- admin 无权限位图时 `checkRoutePermission` 拒绝
|
||
- **实现文件**：
|
||
- [src/shared/lib/navigation.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/shared/lib/navigation.ts)：27 项扁平数组，按 4 角色分区，`group` 字段用于角色过滤
|
||
- [src/app/shell/layout.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/layout.tsx)：RSC AppFrame，从 `headers()` 读取身份头，`batchCheckRoutePermission` 按位图二次过滤导航项
|
||
- [src/shared/components/layout/user-menu.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/shared/components/layout/user-menu.tsx)：顶部用户菜单，显示 userId + role，登出 POST `/api/auth/logout`
|
||
- [src/shared/lib/route-permissions.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/shared/lib/route-permissions.ts)：补全 7 个列表页根路由的 EXACT 登记（`/shell/admin/announcements`、`/shell/admin/classes`、`/shell/teacher/exams` 等），与 PREFIX 表互补
|
||
- **质量校验**：`tsc --noEmit` 通过；`eslint`（5 文件）通过
|
||
|
||
**P1-2 验收证据（2026-07-22）**：
|
||
|
||
- **假契约查询全部下线**：`grep -rn "useGrades\|useHomework\|useSchedule\|useAttendance\|useExams\|useAnnouncements" src` 无业务调用；6 个 widget（grades/homework/schedule/attendance/exams/announcements）改为"数据源已迁移"占位 Card
|
||
- **6 个真实聚合查询接入**：
|
||
- [src/lib/api/operations/dashboard.graphql.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/lib/api/operations/dashboard.graphql.ts)：`GET_TEACHER_DASHBOARD_DOC` / `GET_STUDENT_DASHBOARD_DOC` / `GET_PARENT_DASHBOARD_DOC` / `GET_ADMIN_DASHBOARD_DOC` / `GET_WARNINGS_DOC` / `GET_ERROR_BOOK_STATS_DOC`，字段全部 snake_case 对齐 data-ana 子图
|
||
- [src/lib/api/dashboard.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/lib/api/dashboard.ts)：6 个 hooks（`useTeacherDashboard` / `useStudentDashboard` / `useParentDashboard` / `useAdminDashboard` / `useWarnings` / `useErrorBookStats`）+ 全部领域模型类型（`TeacherDashboard` / `StudentDashboard` / `ParentDashboard` / `AdminDashboard` / `WarningInfo` / `ErrorBookStats` 等）
|
||
- **4 角色仪表盘页面**（显式路由，先于 catch-all 匹配）：
|
||
- [src/app/shell/teacher/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/teacher/page.tsx)：StatCard×4（班级总数/学生总数/班级平均分/待批作业）+ DashboardSection×2（班级概况/近期预警）
|
||
- [src/app/shell/student/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/student/page.tsx)：StatCard×3（平均分/班级排名/待交作业）+ DashboardSection×2（薄弱知识点/近期成绩趋势）
|
||
- [src/app/shell/parent/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/parent/page.tsx)：StatCard×2（孩子平均分/班级排名）+ DashboardSection×2（薄弱知识点/预警通知）
|
||
- [src/app/shell/admin/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/admin/page.tsx)：StatCard×4（教师总数/学生总数/班级总数/全校平均分）+ DashboardSection×2（近期预警/AI 用量）
|
||
- **混合路由模型（V3-A1）**：[src/app/shell/\[\[...route\]\]/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/[[...route]]/page.tsx) 新增 `params` 异步读取 + `/shell` 空路由 `redirect(\`/shell/${role}\`)` 兜底
|
||
- **三态规范**：4 个仪表盘页统一遵循 loading（StatCard isLoading 骨架）→ error（Card 错误提示）→ success（真实数据）三态
|
||
- **质量校验**：`tsc --noEmit` 通过；`eslint`（新/改文件）通过；`vitest run` 全量 20 test files / 212 tests 全部通过
|
||
|
||
**P1-3 验收证据（2026-07-22）**：
|
||
|
||
- **4 个页面模板组件**：[src/shared/components/page-templates/](file:///e:/Desktop/Edu/apps/portal-shell/src/shared/components/page-templates/)
|
||
- [list-page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/shared/components/page-templates/list-page.tsx)：`ListPageShell` + `ListPageSkeleton`，结构 = PageHeader + FilterBar + 主内容 + Pagination，三态 = loading/empty/errorNode 优先级链
|
||
- [detail-page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/shared/components/page-templates/detail-page.tsx)：`DetailPageShell` + `DetailSection` + `DetailField` + `DetailPageSkeleton`，结构 = PageHeader（含 backHref） + 分区 + 字段表
|
||
- [form-page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/shared/components/page-templates/form-page.tsx)：`FormPageShell` + `FormPageSkeleton`，结构 = PageHeader + form + errorSummary + 提交/取消按钮
|
||
- [workbench-page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/shared/components/page-templates/workbench-page.tsx)：`WorkbenchPageShell` + `WorkbenchPanel` + `WorkbenchPageSkeleton`，结构 = PageHeader + 三栏（左树/中画布/右属性），左右栏宽度可配置
|
||
- [index.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/shared/components/page-templates/index.ts)：barrel 导出
|
||
- **4 个 dev 示例页**（仅 dev 可见，生产环境 `notFound()` 兜底）：
|
||
- [/shell/dev/templates](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/dev/templates/page.tsx)：索引页，列出 4 张模板
|
||
- [/shell/dev/templates/list](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/dev/templates/list/page.tsx)：列表页示例，支持 `?state=loading|empty|success` 切换三态
|
||
- [/shell/dev/templates/detail](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/dev/templates/detail/page.tsx)：详情页示例
|
||
- [/shell/dev/templates/form](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/dev/templates/form/page.tsx)：表单页示例
|
||
- [/shell/dev/templates/workbench](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/dev/templates/workbench/page.tsx)：工作台页示例
|
||
- **路径命名修正**：原 ARCHITECTURE.md 写 `/shell/_dev/templates/*`，但 Next.js 将下划线开头的文件夹视为"私有文件夹"（不参与路由），实测 `/shell/_dev/templates` 被 `[[...route]]/page.tsx` catch-all 兜底接管（ClientShell 微内核渲染）。改用 `dev` 命名后，显式路由优先匹配，catch-all 不再触发。route-permissions.ts 同步登记 `PREFIX /shell/dev/`（空 config = 仅校验登录身份）
|
||
- **三态规范验证**（HTTP 200 + 内容断言）：
|
||
- `GET /shell/dev/templates/list?state=loading` → 200，HTML 含 `animate-pulse` 骨架，无表格数据
|
||
- `GET /shell/dev/templates/list?state=empty` → 200，HTML 含"暂无数据"空态，无表格数据
|
||
- `GET /shell/dev/templates/list`（默认 success）→ 200，HTML 含表格行"考试 A"
|
||
- **单测**：`vitest run --reporter=verbose page-templates` → 19/19 passed（覆盖 4 个模板的三态、字段渲染、提交按钮禁用、errorSummary alert 等）
|
||
- **质量校验**：`tsc --noEmit` 通过；`eslint src/shared/components/page-templates src/app/shell/dev src/shared/lib/route-permissions.ts` 通过；`vitest run` 全量 21 test files / 231 tests 全部通过（212 原有 + 19 新增）
|
||
|
||
**P1-4 验收证据（2026-07-22）**：
|
||
|
||
- **next-intl v4.13.2 接入（无 i18n 路由模式）**：
|
||
- [next.config.js](file:///e:/Desktop/Edu/apps/portal-shell/next.config.js)：`createNextIntlPlugin("./src/i18n/request.ts")` 包装 `nextConfig`，Turbopack resolveAlias 注入 `next-intl/config`
|
||
- [src/i18n/request.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/i18n/request.ts)：`getRequestConfig` 从 `NEXT_LOCALE` cookie 读取 locale（缺省 `zh-CN`），动态 import 对应 messages JSON
|
||
- [src/app/layout.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/layout.tsx)：`async RootLayout` + `getLocale()` / `getMessages()` + `<NextIntlClientProvider>` 注入全局 messages；`<html lang={locale}>` 随 cookie 切换
|
||
- **messages 合并迁移**：
|
||
- [src/messages/zh-CN.json](file:///e:/Desktop/Edu/apps/portal-shell/src/messages/zh-CN.json)：从 teacher-portal 合并 + 新增 `shell.dev.templates` 命名空间（title/description/list/detail/form/workbench 及其 listExample 等子键）
|
||
- [src/messages/en.json](file:///e:/Desktop/Edu/apps/portal-shell/src/messages/en.json)：与 zh-CN.json 结构完全对称
|
||
- **自造 i18n 删除**：
|
||
- [src/providers/ThemeI18nProvider.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/providers/ThemeI18nProvider.tsx) 已删除（含 `useT()` 函数 + `DEFAULT_MESSAGES` 常量）
|
||
- [src/providers/ThemeProvider.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/providers/ThemeProvider.tsx)：新建，仅保留主题切换（`usePluginStore(s => s.theme)` + `document.documentElement.classList` 切换 `.dark`）
|
||
- [src/shell/PluginStore.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/shell/PluginStore.ts)：移除 `locale` / `setLocale` 字段
|
||
- `grep -rn "useT(\|ThemeI18nProvider\|DEFAULT_MESSAGES" src` → 无匹配（自造函数全删除）
|
||
- **locale-switcher 改造**：[src/widgets/topbar/locale-switcher/index.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/widgets/topbar/locale-switcher/index.tsx) 使用 `useLocale()` + `useTranslations()` + cookie 写入 + `router.refresh()` 触发 RSC 重新渲染
|
||
- **dev/templates 页面演示**：[src/app/shell/dev/templates/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/dev/templates/page.tsx) 使用 `getTranslations("shell.dev.templates")`（Server Component）
|
||
- **locale 切换 HTTP 验证**（dev server `next dev --turbopack -p 4010`）：
|
||
- `GET /login`（无 cookie）→ `<html lang="zh-CN">` + `NextIntlClientProvider locale="zh-CN"` + 中文文案（"保存"/"取消"/"切换侧栏"）
|
||
- `GET /login`（`Cookie: NEXT_LOCALE=en`）→ `<html lang="en">` + `NextIntlClientProvider locale="en"` + 英文文案（"Save"/"Cancel"/"Toggle sidebar"）
|
||
- **质量校验**：`tsc --noEmit` 通过；`eslint src` → 0 errors, 2 warnings（`__generated__/types.ts` 生成文件）；`vitest run` 全量 21 test files / 231 tests 全部通过
|
||
|
||
**P1-5 验收证据（2026-07-22）**：
|
||
|
||
- **MSW v2.7.0 兜底层（覆盖 dashboard/users/exams/grades 四域起步）**：
|
||
- [src/mocks/index.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/mocks/index.ts)：`initMocks()` 入口，`NEXT_PUBLIC_MSW=1` 时按环境动态启动 browser worker 或 node server
|
||
- [src/mocks/handlers.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/mocks/handlers.ts)：拦截 `POST /api/graphql` 与 `POST {APOLLO_ROUTER_URL}`，按 `operationName` 路由
|
||
- [src/mocks/graphql-data.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/mocks/graphql-data.ts)：mock 数据与 `graphqlResponse()` 函数，供 handlers.ts（MSW browser）和 route.ts（SSR）共用
|
||
- [src/mocks/browser.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/mocks/browser.ts) / [server.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/mocks/server.ts)：`setupWorker` / `setupServer`
|
||
- [public/mockServiceWorker.js](file:///e:/Desktop/Edu/apps/portal-shell/public/mockServiceWorker.js)：MSW Service Worker（`pnpm exec msw init public/ --save`）
|
||
- **SSR 端 mock 数据（Apollo Client 走同域代理）**：
|
||
- [src/lib/apollo-client.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/lib/apollo-client.ts)：`MSW_ENABLED` 时 SSR 端 HttpLink 也指向 `/api/graphql`（不走直连 router）
|
||
- [src/app/api/graphql/route.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/app/api/graphql/route.ts)：`MSW_ENABLED` 时直接返回 mock 数据，不连接后端
|
||
- **生产构建安全（bundle 无 mocks）**：
|
||
- [src/mocks/empty.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/mocks/empty.ts)：空 stub，导出与 `index.ts`/`graphql-data.ts` 同签名的 no-op 函数
|
||
- [next.config.js](file:///e:/Desktop/Edu/apps/portal-shell/next.config.js)：`NEXT_PUBLIC_MSW!=1` 时 Turbopack `resolveAlias` + webpack `resolve.alias` 把 `@/mocks` 与 `@/mocks/graphql-data` 重定向到 `@/mocks/empty`（注：Turbopack 不支持 Windows 绝对路径，故使用 `@/` 说明符）
|
||
- [src/providers/MswProvider.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/providers/MswProvider.tsx)：静态 `import { initMocks } from "@/mocks"`（alias 生效后指向 empty.ts），`MSW_ENABLED=false` 时 useEffect 分支被 dead-code 消除
|
||
- **构建验证**：`NEXT_PUBLIC_MSW=0 next build` 成功（20 路由生成）；`Select-String -Path ".next/static/chunks/**/*.js",".next/server/**/*.js" -Pattern "张老师","stu-001","setupWorker","dev-teacher-001","二次函数"` → **CLEAN：客户端 + 服务端 bundle 均无 mock 字符串**
|
||
- **dev server 验证（MSW=1 无后端）**：`GET /api/graphql` 返回 `{msw:true}`；`POST /api/graphql` 返回 mock 数据（teacherDashboard: total_classes=5/total_students=142；users: 5 条记录；questions: 3 条；grades: 3 条）
|
||
- **质量校验**：`tsc --noEmit` 通过；`eslint src` → 0 errors, 2 warnings（`__generated__/types.ts`）；`vitest run` 全量 21 test files / 231 tests 全部通过
|
||
|
||
**P1-6 验收证据（2026-07-22）**：
|
||
|
||
- **31 widget 令牌清债（516 处机械替换，覆盖 25 文件）**：
|
||
- 间距工具类 `xs/sm/md/lg/xl` → 数字 `1/2/3/4/6`（`mt-sm`→`mt-2`、`px-sm`→`px-2`、`py-xs`→`py-1`、`p-md`→`p-3`、`gap-sm`→`gap-2`、`space-y-xs`→`space-y-1`、`h-xs`→`h-1` 等）
|
||
- `text-heading-3` → `text-lg font-semibold`（25 处）
|
||
- `bg-danger` → `bg-destructive`（6 处，shadcn 标准）
|
||
- `border border` → `border`（去重，仅匹配真正的重复 border 类）
|
||
- **lint:tokens 修复**：[.eslintrc.tokens.js](file:///e:/Desktop/Edu/apps/portal-shell/.eslintrc.tokens.js) 原导入 `@typescript-eslint/parser`（未安装）导致脚本不可用，改用 `typescript-eslint` 包的 `tseslint.parser`（与 eslint.config.js 一致）
|
||
- **验收命令**：
|
||
- `grep -rn "text-heading-\|mt-sm\|py-xs\|p-md" src/widgets` → **0 匹配** ✅
|
||
- `eslint -c .eslintrc.tokens.js src` → **0 errors** ✅
|
||
- **质量校验**：`tsc --noEmit` 通过；`eslint src` → 0 errors, 2 warnings；`vitest run` 全量 21 test files / 231 tests 全部通过
|
||
|
||
**P1-7 验收证据（2026-07-22）**：
|
||
|
||
- **codegen 配置（[codegen.yml](file:///e:/Desktop/Edu/apps/portal-shell/codegen.yml)）**：
|
||
- 新增第 3 个输出 `src/lib/api/__generated__/dashboard-types.ts`，作用域 `documents: src/lib/api/operations/dashboard.graphql.ts`，插件 `typescript + typescript-operations`，`skipDocumentsValidation: false`（关闭校验）
|
||
- 全局 `skipDocumentsValidation: true` 保留（其余 7 域 operations 仍引用 schema 未实现字段，44 个 "Cannot query field" 错误仍需 skip）
|
||
- config 域关闭推迟：admin.graphql.ts 中 `GET_LAYOUT_TEMPLATES_DOC` 查询 `availableSlots` 字段，但 schema `LayoutTemplateGql` 未定义该字段，需后端补齐后才能关闭
|
||
- **data-ana 域 6 个 operation 严格匹配 schema**：`GetTeacherDashboard` / `GetStudentDashboard` / `GetParentDashboard` / `GetAdminDashboard` / `GetWarnings` / `GetErrorBookStats`，全部通过 codegen 严格校验，生成 per-operation Query/Variables 类型
|
||
- **lib/api/dashboard.ts 手写 interface 全部删除**：
|
||
- 删除 14 个手写 interface：`TeacherDashboard` / `StudentDashboard` / `ParentDashboard` / `AdminDashboard` / `WarningList` / `WarningInfo` / `ClassSummary` / `StudentSummary` / `WeakPoint` / `TrendPoint` / `AIUsageSummary` / `AIUsageByProvider` / `KnowledgePointErrorStats` / `ErrorBookStats`
|
||
- 删除 6 个内部 Query 类型别名：`TeacherDashboardQueryData` / `StudentDashboardQueryData` / `ParentDashboardQueryData` / `AdminDashboardQueryData` / `WarningsQueryData` / `ErrorBookStatsQueryData`
|
||
- 改用 `NonNullable<GetXxxQuery['xxx']>` 从生成类型派生 14 个 type alias，保持对外 API 形状不变（widgets 无需改动）
|
||
- 6 个 hook 改用生成的 `GetXxxQuery` 作为 `useWidgetQuery<TData, TVars>` 的泛型参数
|
||
- **page.tsx 空值守卫补全**：4 个仪表盘页（teacher/student/parent/admin）的 StatCard `value` prop 改用 `?? "--"` / `?? 0` 兜底，对齐 schema 字段可空语义
|
||
- **验收命令**：
|
||
- `tsx scripts/normalize-schema.ts` → `Combined schema written` ✅
|
||
- `graphql-codegen --config codegen.yml` → 3 outputs 全部 SUCCESS ✅
|
||
- `tsc --noEmit` → 0 errors ✅
|
||
- `eslint src` → 0 errors, 4 warnings（pre-existing `any` 警告，非本次引入） ✅
|
||
- `vitest run` → 21 test files / 231 tests 全部 passed ✅
|
||
- `next build` → `✓ Compiled successfully in 4.9s` ✅
|
||
- **实现文件**：
|
||
- [codegen.yml](file:///e:/Desktop/Edu/apps/portal-shell/codegen.yml)：3 个 generates 输出，dashboard-types.ts 为新增
|
||
- [src/lib/api/**generated**/dashboard-types.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/lib/api/__generated__/dashboard-types.ts)：codegen 生成（6 个 Query 类型 + 6 个 Variables 类型 + Exact 工具类型 + schema 类型子集）
|
||
- [src/lib/api/dashboard.ts](file:///e:/Desktop/Edu/apps/portal-shell/src/lib/api/dashboard.ts)：手写 interface 全部删除，改用生成类型派生
|
||
- [src/app/shell/teacher/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/teacher/page.tsx) / [student/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/student/page.tsx) / [parent/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/parent/page.tsx) / [admin/page.tsx](file:///e:/Desktop/Edu/apps/portal-shell/src/app/shell/admin/page.tsx)：StatCard value 空值守卫补全
|
||
|
||
**P1-8 验收证据（2026-07-22）**：
|
||
|
||
- **三个结构性检查脚本**：
|
||
1. [scripts/check-route-table.ts](file:///e:/Desktop/Edu/apps/portal-shell/scripts/check-route-table.ts)：扫描 `src/app/shell/**/page.tsx`，解析 `route-permissions.ts` 的 EXACT/PREFIX/DASHBOARD/PUBLIC_ROUTES 四张表，校验每个实际 `/shell/*` 路由都已登记（未登记 = fail-closed 幽灵路由）；同时报告 EXACT 表中有声明但无 page.tsx 的"幽灵条目"（informational，不阻断 CI，记录 P2-P5 待实现路由）
|
||
2. [scripts/check-page-count.ts](file:///e:/Desktop/Edu/apps/portal-shell/scripts/check-page-count.ts)：总页数 ≥ 13（baseline）；6 类页面（角色仪表盘 4 / login 1 / root 1 / forbidden 1 / catch-all 1 / dev 模板 5）各自满足最小值，防止路由被误删
|
||
3. [scripts/check-codegen.ts](file:///e:/Desktop/Edu/apps/portal-shell/scripts/check-codegen.ts)：运行 `pnpm run codegen`（normalize-schema + graphql-codegen），对 `skipDocumentsValidation: false` 的输出（当前为 dashboard-types.ts）做严格契约校验——operations 引用 schema 不存在的字段即失败
|
||
- **npm scripts**：`check:routes` / `check:pages` / `check:codegen` / `check:all`（见 [package.json](file:///e:/Desktop/Edu/apps/portal-shell/package.json)）
|
||
- **CI 接线**：[.github/workflows/ci.yml](file:///e:/Desktop/Edu/.github/workflows/ci.yml) `quality-ts` job 新增 "Portal-shell structural checks (P1-8)" step，位于 typecheck 之后、test 之前
|
||
- **预埋违规验证（验收核心）**：
|
||
- **路由表违规**：在 `src/app/shell/test-violation/page.tsx` 预埋一个未登记路由 → `check:routes` 报红 `❌ VIOLATIONS (unregistered routes): /shell/test-violation`，exit 1；删除后恢复 PASS
|
||
- **codegen 契约违规**：在 `dashboard.graphql.ts` 的 `GetTeacherDashboard` 查询中预埋 `non_existent_field_for_violation_test` 字段 → `check:codegen` 报红 `GraphQL Document Validation failed: Cannot query field "non_existent_field_for_violation_test" on type "TeacherDashboard"`，exit 1；还原后恢复 PASS
|
||
- **页面计数违规**：baseline=13，当前实际=13，任一 page.tsx 被删除即触发 `total < baseline` 报红
|
||
- **正常态验证**：三脚本在干净工作区全部 PASS（10 实际路由 / 28 EXACT / 9 PREFIX / 10 PUBLIC / 24 幽灵条目 informational / 13 页面 / codegen 3 输出 SUCCESS）
|
||
- **质量校验**：`tsc --noEmit` 0 errors；`eslint src` 0 errors 4 warnings（pre-existing）；脚本位于 `scripts/` 不在 tsconfig include 范围内，不影响 typecheck
|
||
|
||
### P2 · 教师域页面（2–3 周，可与 P3 部分并行）
|
||
|
||
- 范围：§9.1 全表（~50 页）。顺序建议：exams → homework → grades → lesson-plans → questions/textbooks → attendance/classes/students → diagnostic/error-book/analytics → elective/course-plans → ai-* → practice/schedule-changes/leave。
|
||
- 每模块退出：列表/详情/表单页齐 + 三态 + MSW 场景 + 单测（数据变换函数）+ 页面计数更新。
|
||
- 契约工单：exams CRUD mutation、homework CRUD、grades 录入/列表、lessonPlans CRUD、attendance、classes 列表等，随模块开工即登记。
|
||
|
||
### P3 · 学生域页面（1.5–2 周）
|
||
|
||
- 范围：§9.2 全表（~34 页）。先行：dashboard 详情（trend/weakness 已 ✅）→ error-book（✅）→ grades/exams/homework 只读 → exams/take 作答台 → practice → ai-tutor。
|
||
|
||
### P4 · 家长域页面（1–1.5 周）
|
||
|
||
- 范围：§9.3 全表（~21 页）。多为只读视图，复用学生域组件；重点：`myChildren` 契约 + child-overview 聚合。
|
||
|
||
### P5 · 管理域页面（1.5–2 周）
|
||
|
||
- 范围：§9.4 全表（~22 页）。先行：users（❌ 列表契约优先推）→ roles/permissions → audit-logs → school 体系 → invitation-codes → plugins（✅）→ viewports（对齐 004 §5.4）。
|
||
- 收尾：旧 4 portal 目录归档（`apps/_archive/`）或删除（决策点：待全量验收后执行，单独 PR）。
|
||
|
||
### P6 · 硬化与验收（1–2 周）
|
||
|
||
- Playwright E2E：登录 → 各角色核心流 1 条（教师建考试/学生交作业/家长看成绩/管理员建用户）+ 三级错误边界 + 门禁越权。
|
||
- 视觉回归：5 布局 + 每域代表页截图基线。
|
||
- 性能：首屏 JS ≤ 300KB(gzip)、LCP < 2s（本地 Docker 压测，附报告）。
|
||
- 生产检查单：`APOLLO_REQUIRE_PQ_MANIFEST=true`、`APOLLO_ROUTER_INTROSPECTION=false`、`NEXT_PUBLIC_DEV_MODE=false`、`ROUTER_AUTH_SECRET` env 化、CSP 头（`next.config.js headers()`）、`/api/log` 换生产端点。
|
||
- 文档：README v3.0 重写（本文件内容沉淀回模块 README + 本文件标记"已并入 README"）。
|
||
|
||
---
|
||
|
||
## 11. 后续 AI 工作规范（强制）
|
||
|
||
> 本章是给**所有后续在本模块工作的 AI/人**的操作规程。多 AI 协作同时遵守 project_rules §14（模块单一负责制：本模块只改 `apps/portal-shell/`，跨模块变更按 §14.4 顺序）。
|
||
|
||
### 11.1 开工前必读（按序）
|
||
|
||
1. 本文件（v3.0 总纲）
|
||
2. `project_rules.md` §3.4/§3.10/§4/§14
|
||
3. 所接任务的页面源（旧 portal 对应 page.tsx）与目标模板（§7.3）
|
||
|
||
### 11.2 目录与文件约定
|
||
|
||
```
|
||
src/
|
||
├─ app/
|
||
│ ├─ login/page.tsx # 登录
|
||
│ ├─ shell/
|
||
│ │ ├─ layout.tsx # AppFrame（唯一框架）
|
||
│ │ ├─ forbidden/page.tsx # 403
|
||
│ │ ├─ page.tsx # 角色仪表盘（catch-all 保留于仪表盘内部可选）
|
||
│ │ ├─ <role>/<module>/page.tsx # 业务页面（显式路由）
|
||
│ │ └─ <role>/<module>/{loading,error}.tsx
|
||
│ └─ api/{graphql,auth/login,auth/logout,health,ready,log}/route.ts
|
||
├─ middleware.ts # 认证 + 门禁（唯一入口）
|
||
├─ features/<domain>/ # 页面私有实现（组件/hooks/类型），按域组织
|
||
│ └─ exams/{exams-list.tsx, exam-detail.tsx, use-exam-filters.ts}
|
||
├─ widgets/ # 仅仪表盘卡片（存量，冻结新增——新功能建页面不建插件）
|
||
├─ shell/ # 微内核（存量，冻结）
|
||
├─ lib/{api,apollo-client,auth} # 数据层/认证工具
|
||
├─ mocks/ # MSW（dev/test only）
|
||
├─ shared/{components,lib} # 共享 UI 与工具
|
||
└─ messages/{zh-CN,en}.json # i18n
|
||
```
|
||
|
||
- **页面文件瘦身**：`page.tsx` 只做 RSC 预取 + 组装，实现代码放 `features/<domain>/`；单文件 ≤ 300 行（超出即拆分）。
|
||
- **features 域清单**：exams / homework / grades / lesson-plans / questions / textbooks / attendance / classes / students / course-plans / elective / error-book / diagnostic / analytics / practice / schedule-changes / leave / ai / notifications / settings / users / rbac / audit / school / invitations / plugins / organization / files / system / viewports / children / messages / announcements。新增域先在本文件 §9 登记。
|
||
|
||
### 11.3 每页硬性清单（DoD）
|
||
|
||
- [ ] 显式路由 + `route-permissions.ts` 已登记（CI 一致性通过）
|
||
- [ ] 套页面模板（§7.3），未手排布局
|
||
- [ ] `loading.tsx` + `error.tsx` + 空态三态齐全
|
||
- [ ] 数据走 `lib/api` hooks；无内联 gql；无手写与 schema 冲突类型
|
||
- [ ] schema 未就绪的查询走 MSW + 文件头 `@contract-pending: <工单>` 注释 + §11.4 登记
|
||
- [ ] 文案走 `useTranslations`；无硬编码中文（迁移期 lint warn，P2 末转 error）
|
||
- [ ] 无禁用类/字面量（§8.1 铁律）；`pnpm lint` + `lint:tokens` 通过
|
||
- [ ] 交互错误有 `notify.error`；无空 catch
|
||
- [ ] 数据变换/权限判断等纯函数有 vitest 单测
|
||
- [ ] i18n 两份 messages 同步更新
|
||
- [ ] 提交信息：`feat(portal-shell): <module> <page> migration`（Conventional Commits）
|
||
|
||
### 11.4 契约工单流程（前端缺 schema 字段时）
|
||
|
||
1. 在 `docs/architecture/issues/contracts/<service>_contract.md` 追加需求（字段名/类型/权限点/使用页面）。
|
||
2. 本文件 §9 对应行"契约"列标注工单号。
|
||
3. 页面用 MSW 先行；后端落地后：重跑 normalize + codegen → 该域关 `skipDocumentsValidation` → 切换 fetcher → 删 mock → 工单关闭。
|
||
4. **禁止**为绕过校验把查询写得与 schema 不符后开启 skip。
|
||
|
||
### 11.5 多 AI 并行分工建议
|
||
|
||
| AI 角色 | 负责 | 边界 |
|
||
| -------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||
| 框架 AI | P0/P1（middleware/代理/AppFrame/模板/MSW/i18n） | 独占 `src/{app/shell/layout.tsx,middleware.ts,shared/,lib/,mocks/}` |
|
||
| 教师域 AI | §9.1 | 独占 `src/app/shell/teacher/**` + `src/features/{exams,homework,grades,lesson-plans,...}` |
|
||
| 学生域 AI | §9.2 | 独占 `src/app/shell/student/**` + 对应 features |
|
||
| 家长域 AI | §9.3 | 独占 `src/app/shell/parent/**` + 对应 features |
|
||
| 管理域 AI | §9.4 | 独占 `src/app/shell/admin/**` + 对应 features |
|
||
| 公共区（login/notifications/settings） | 框架 AI | 防止撞车 |
|
||
|
||
- 跨域共享组件必须先提"共享申请"（改 `src/shared/` 或 `packages/ui-components/`），由框架 AI 评审合入；**禁止**各自复制粘贴。
|
||
- 分支：每域一个 feature 分支（`feat/portal-shell-<domain>`），按 project_rules §14.3。
|
||
|
||
### 11.6 文档与验收纪律
|
||
|
||
- 每个 PR 更新：本文件 §9 对应行状态 +（如涉及）README 对应章节。
|
||
- 验收勾选必须附**可复现命令输出**（typecheck/lint/test/build/截图），禁止"已完成"裸声明——本文件 §1.1 的对照表即为反面教材。
|
||
- 每阶段结束运行 `pnpm run arch:scan` 更新 arch.db，并同步 004 相关章节。
|
||
|
||
### 11.7 禁止事项（红线）
|
||
|
||
1. 禁止新增 widget 插件实现业务功能（冻结 `src/widgets/` 新增；新功能 = 新页面）。
|
||
2. 禁止恢复 localStorage 存 token；禁止 JS 读取 `edu_session`。
|
||
3. 禁止在页面/widget 内联 gql 或绕过 `lib/api` 直接 `useQuery`。
|
||
4. 禁止引入第二套设计令牌 / 第二套组件库 / 第二套 toast。
|
||
5. 禁止"默认放行"式的权限代码（未匹配路由必须拒绝）。
|
||
6. 禁止跳过 `@contract-pending` 登记直接写假查询。
|
||
7. 禁止删除/弱化现有测试来让门禁变绿。
|
||
|
||
---
|
||
|
||
## 12. 风险登记册
|
||
|
||
| # | 风险 | 等级 | 缓解 |
|
||
| --- | ---------------------------------------------- | ---- | ----------------------------------------------------------------------------------- |
|
||
| R1 | 后端契约补齐速度成为页面切换瓶颈（~100 页 ❌） | 高 | MSW 先行解耦；契约工单周同步；优先推 mutations 框架（后端 0 mutation 是系统性缺口） |
|
||
| R2 | 140 页迁移量大，AI 并行产出不一致 | 高 | 模板四件套强制 + 共享组件申请制 + 每模块 DoD 清单 + CI 一致性脚本 |
|
||
| R3 | 旧页面纸感令牌清理遗漏导致视觉混杂 | 中 | 迁移 DoD 含令牌检查；arch:scan 未知类检测；P6 视觉回归 |
|
||
| R4 | middleware 验签引入 JWKS 可用性依赖 | 中 | JWKS 缓存（5min）+ 故障 fail-closed + 启动自检 |
|
||
| R5 | next-intl 与 RSC 流式模式冲突 | 低 | P1 先做技术验证（一个页面跑通再推广） |
|
||
| R6 | MSW 数据与真实 schema 漂移 | 中 | mock 数据类型从 codegen types 导入；契约切换时删 mock |
|
||
| R7 | 旧 portal 删除时发现有未迁移边角功能 | 低 | P5 删除前做路由 diff 清单评审；先归档后删除 |
|
||
| R8 | config-service 单点故障影响仪表盘 | 低 | P0-4 内置默认配置已兜底；页面不依赖插件配置 |
|
||
|
||
---
|
||
|
||
## 13. 附录
|
||
|
||
### 13.1 命令手册
|
||
|
||
```bash
|
||
# 开发（无后端）
|
||
NEXT_PUBLIC_MSW=1 NEXT_PUBLIC_DEV_MODE=true node node_modules/next/dist/bin/next dev -p 4010
|
||
|
||
# 质量门禁（CI 全量）
|
||
node node_modules/typescript/bin/tsc --noEmit # typecheck
|
||
node node_modules/.bin/eslint src # lint（或 pnpm lint）
|
||
node node_modules/vitest/vitest.mjs run # 单测
|
||
node node_modules/next/dist/bin/next build # 构建
|
||
node node_modules/.bin/eslint -c .eslintrc.tokens.js src # 令牌专项
|
||
|
||
# 契约
|
||
node_modules/.bin/tsx scripts/normalize-schema.ts && node_modules/.bin/graphql-codegen --config codegen.yml
|
||
node_modules/.bin/tsx scripts/generate-pq-manifest.ts
|
||
|
||
# 一致性校验（P1 起）
|
||
node scripts/check-route-permissions.mjs # 路由表 ⇄ 文件系统
|
||
```
|
||
|
||
### 13.2 关键文件速查
|
||
|
||
| 主题 | 文件 |
|
||
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
|
||
| 微内核仪表盘 | `src/shell/{Shell,ClientShell,LayoutManager,SlotRenderer,Registry,PropsMerger,PluginLifecycle,PluginStore}.tsx?` |
|
||
| 数据层 | `src/lib/{apollo-client,useWidgetQuery,useWidgetMutation,config-fetcher,usePluginConfig}.ts` + `src/lib/api/` |
|
||
| 安全 | `src/shared/lib/route-permissions.ts` + `packages/shared-ts/src/permission-bitmap.ts` +（新）`src/middleware.ts` |
|
||
| 错误处理 | `src/shared/components/{plugin,route,section}-boundary.tsx` + `packages/hooks/src/use-error-report.ts` |
|
||
| 设计令牌 | `packages/ui-tokens/src/{primitive,semantic-light,semantic-dark,tailwind-theme}.css` |
|
||
| 组件库 | `src/shared/components/ui/*` + `packages/ui-components/src/*` |
|
||
| 迁移源 | `apps/{teacher,student,parent,admin}-portal/src/app/**/page.tsx` + `apps/teacher-portal/src/mocks/handlers-p*.ts` |
|
||
| 后端 schema 源 | `services/*/src/graphql/generated/schema.graphql` → `src/lib/api/__generated__/combined-schema.graphql` |
|
||
|
||
### 13.3 参考文档
|
||
|
||
| 文档 | 用途 |
|
||
| ----------------------------------------------------------------------- | ------------------------------------------ |
|
||
| [README.md](./README.md) v2.0 | 微内核仪表盘子系统详细设计（保留有效部分） |
|
||
| [004 §5.4](../../docs/architecture/004_architecture_impact_map.md) | 视口四层模型（导航/路由/组件/数据） |
|
||
| [004 §11.7](../../docs/architecture/004_architecture_impact_map.md) | 前端数据层 + GraphQL 安全栈设计意图 |
|
||
| [GraphQL @auth 审计](../../docs/security/graphql-auth-audit-2026-07.md) | 后端 resolver 权限现状 |
|
||
| [MIGRATION_GUIDE.md](../../MIGRATION_GUIDE.md) | CICD → Edu 迁移背景与资产清单 |
|
||
| [多 AI 协作规范](../../docs/standards/multi-ai-collaboration.md) | 并行工作规则 |
|
||
|
||
### 13.4 术语表
|
||
|
||
| 术语 | 定义 |
|
||
| ------------------- | ------------------------------------------------------------------- |
|
||
| AppFrame | 全站页面框架（TopBar + Sidebar + Main），`src/app/shell/layout.tsx` |
|
||
| 微内核仪表盘 | `/shell` 角色首页的插件聚合区（v2.0 遗产，保留收缩） |
|
||
| 页面模板四件套 | list / detail / form / workbench 四种页面骨架（§7.3） |
|
||
| 契约工单 | 前端缺 schema 字段时的后端需求登记单（§11.4） |
|
||
| MSW 兜底层 | `src/mocks/` 开发态模拟后端（§5.4） |
|
||
| `@contract-pending` | 页面头注释，标记数据来自 MSW 待契约切换 |
|
||
| fail-closed | 无身份/无权限/服务不可用时一律拒绝并显式提示，禁止静默放行 |
|
||
| 视口四层 | 004 §5.4：导航 L1 / 路由 L2 / 组件 L3 / 数据 L4 |
|
||
|
||
---
|
||
|
||
> **本文件自发布之日起为 portal-shell 前端工作唯一权威。任何"已完成"声明必须能以 §1.1 同等严格度复现。下一阶段开工前，先完成 P0 并回填本文件 §9/§10 状态。**
|