feat(portal-shell): add CI structural checks for routes, pages, codegen (P1-8)

ARCHITECTURE.md §10 P1-8: three structural checks wired into CI to
prevent regressions identified in the §1.3 audit.

Scripts (apps/portal-shell/scripts/):
- check-route-table.ts: scans src/app/shell/**/page.tsx, parses
  route-permissions.ts (EXACT/PREFIX/DASHBOARD/PUBLIC_ROUTES), fails
  if any actual /shell/* route is unregistered. Reports ghost entries
  (EXACT declarations without page.tsx) as informational.
- check-page-count.ts: asserts total page.tsx >= 13 and per-category
  minimums (dashboards/login/root/forbidden/catch-all/dev-templates).
- check-codegen.ts: runs pnpm run codegen, fails if any output with
  skipDocumentsValidation:false has operations referencing non-existent
  schema fields (currently enforces dashboard-types.ts output from P1-7).

npm scripts: check:routes / check:pages / check:codegen / check:all

CI: .github/workflows/ci.yml quality-ts job — new "Portal-shell
structural checks (P1-8)" step between typecheck and test.

Acceptance (ARCHITECTURE.md §10 P1-8 — "CI 对预埋违规报红"):
- Route violation: planted /shell/test-violation/page.tsx → check:routes
  exits 1 with "unregistered route" error; reverted → PASS
- Codegen violation: planted non_existent_field in GetTeacherDashboard →
  check:codegen exits 1 with "Cannot query field" error; reverted → PASS
- Page count: baseline=13, deleting any page.tsx triggers FAIL
- Clean state: all 3 checks PASS (10 routes, 28 EXACT, 24 ghost entries
  informational, 13 pages, codegen 3 outputs SUCCESS)

Refs: ARCHITECTURE.md §5.3, §10 P1-8, §11.6, §11.7 红线 #5

.github/workflows/ci.yml

@@ -49,6 +49,13 @@ jobs:
       - name: Typecheck
         run: pnpm -r run typecheck
 
+      - name: Portal-shell structural checks (P1-8)
+        working-directory: apps/portal-shell
+        run: |
+          pnpm run check:routes
+          pnpm run check:pages
+          pnpm run check:codegen
+
       - name: Test
         run: pnpm -r run test
         continue-on-error: true # P6: 部分服务无 test 脚本，待补全

apps/portal-shell/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 > 版本：3.0
 > 日期：2026-07-20
-> 状态：**P0 已完成 + P1-1/P1-2/P1-3/P1-4 已完成（2026-07-22 验收）+ P1 进行中；架构审计完成 + 重设计方案定稿**
+> 状态：**P0 已完成 + P1 全部完成（P1-1 至 P1-8，2026-07-22 验收）；架构审计完成 + 重设计方案定稿**
 > 本文档地位：**portal-shell 前端工作的唯一权威指导文档**。所有后续 AI/人工在此模块的工作必须先读本文件，以其为准。
 >
 > 关联文档（按效力排序）：
@@ -757,7 +757,7 @@ export default async function ExamsPage(): Promise<React.ReactElement> {
 - **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-2/P1-3/P1-4/P1-5/P1-6 ✅ 2026-07-22 验收）
+### P1 · 框架与数据源接通（1–2 周）— 全部完成（P1-1 至 P1-8 ✅ 2026-07-22 验收）
 
 **目标**：AppFrame + 导航 + 真实数据仪表盘 + 页面模板 + MSW + i18n，页面迁移的"流水线"建成。
 
@@ -770,7 +770,7 @@ export default async function ExamsPage(): Promise<React.ReactElement> {
 | 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（config + data-ana 两域先行关闭 skipDocumentsValidation）                               | 生成操作级类型；lib/api 对应域删除手写 interface；typecheck 通过                                                                          | ✅   |
-| P1-8 | CI 增补：路由表一致性脚本 + 页面计数 + codegen diff 检查                                                                   | CI 对预埋违规报红（附 pipeline 链接）                                                                                                     | ⏳   |
+| P1-8 | CI 增补：路由表一致性脚本 + 页面计数 + codegen diff 检查                                                                   | CI 对预埋违规报红（附 pipeline 链接）                                                                                                     | ✅   |
 
 **P1-1 验收证据（2026-07-22）**：
 
@@ -902,6 +902,21 @@ export default async function ExamsPage(): Promise<React.ReactElement> {
   - [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。

apps/portal-shell/package.json

@@ -15,6 +15,10 @@
     "codegen": "tsx scripts/normalize-schema.ts && graphql-codegen --config codegen.yml",
     "codegen:watch": "graphql-codegen --config codegen.yml --watch",
     "generate-pq-manifest": "tsx scripts/generate-pq-manifest.ts",
+    "check:routes": "tsx scripts/check-route-table.ts",
+    "check:pages": "tsx scripts/check-page-count.ts",
+    "check:codegen": "tsx scripts/check-codegen.ts",
+    "check:all": "pnpm run check:routes && pnpm run check:pages && pnpm run check:codegen",
     "prebuild": "pnpm run codegen && pnpm run generate-pq-manifest"
   },
   "dependencies": {

apps/portal-shell/scripts/check-codegen.ts

@@ -0,0 +1,64 @@
+// Codegen contract validation check (ARCHITECTURE.md §10 P1-8 / §5.3)
+//
+// Runs graphql-codegen and fails if any output with skipDocumentsValidation:false
+// contains operations that reference non-existent schema fields.
+// This is the "codegen diff check" — it diffs operations against schema.
+//
+// Currently enforces:
+// - dashboard-types.ts output (skipDocumentsValidation: false, P1-7)
+// As more domains fix their operations, their outputs will be validated too.
+//
+// Usage: tsx scripts/check-codegen.ts
+// Exit: 0 = codegen success, 1 = validation errors
+//
+// Related: ARCHITECTURE.md §5.3 契约纪律, §10 P1-8
+import { execSync } from "node:child_process";
+
+function main(): void {
+  console.log("=== Codegen Contract Validation Check ===");
+  console.log("Running: pnpm run codegen (normalize-schema + graphql-codegen)");
+  console.log("");
+
+  try {
+    const output = execSync("pnpm run codegen", {
+      cwd: process.cwd(),
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    console.log(output);
+
+    // Check for validation failures even on exit 0 (some may be warnings)
+    if (output.includes("GraphQL Document Validation failed")) {
+      console.log("❌ Codegen reported validation failures despite exit 0");
+      console.log("Result: FAIL");
+      process.exit(1);
+    }
+
+    console.log(
+      "Result: PASS (codegen succeeded, all validated outputs clean)",
+    );
+    process.exit(0);
+  } catch (err: unknown) {
+    const e = err as { stdout?: string; stderr?: string; message: string };
+    const output = `${e.stdout ?? ""}\n${e.stderr ?? ""}`;
+    console.log(output);
+
+    if (output.includes("GraphQL Document Validation failed")) {
+      console.log(
+        "❌ Codegen validation failed — operations reference non-existent schema fields",
+      );
+      console.log(
+        "   Fix: update operations/*.graphql.ts to match combined-schema.graphql",
+      );
+      console.log(
+        "   Or: keep skipDocumentsValidation: true for that output until schema is ready",
+      );
+    } else {
+      console.log(`❌ Codegen failed: ${e.message}`);
+    }
+    console.log("Result: FAIL");
+    process.exit(1);
+  }
+}
+
+main();

apps/portal-shell/scripts/check-page-count.ts

@@ -0,0 +1,160 @@
+// Page count baseline check (ARCHITECTURE.md §10 P1-8 / §11.6)
+//
+// Asserts that the total page.tsx count never drops below the baseline.
+// Prevents accidental route deletion. When adding new pages, update the
+// baseline in BASELINE.total. Per-category minimums catch regressions
+// in specific areas (dashboards, login, etc.).
+//
+// Usage: tsx scripts/check-page-count.ts
+// Exit: 0 = pass, 1 = below baseline
+//
+// Related: ARCHITECTURE.md §10 P1-8, §11.6 验收纪律
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const APP_DIR = path.resolve(process.cwd(), "src/app");
+
+interface Baseline {
+  total: number;
+  categories: Record<string, { pattern: string; min: number; label: string }>;
+}
+
+// Baseline as of P1-8 (2026-07-22). Update when adding pages.
+const BASELINE: Baseline = {
+  total: 13,
+  categories: {
+    dashboards: {
+      pattern: "shell/{admin,teacher,student,parent}/page.tsx",
+      min: 4,
+      label: "Role dashboards (admin/teacher/student/parent)",
+    },
+    login: {
+      pattern: "login/page.tsx",
+      min: 1,
+      label: "Login page",
+    },
+    root: {
+      pattern: "page.tsx",
+      min: 1,
+      label: "Root redirect page",
+    },
+    forbidden: {
+      pattern: "shell/forbidden/page.tsx",
+      min: 1,
+      label: "Forbidden page",
+    },
+    catchAll: {
+      pattern: "shell/[[...route]]/page.tsx",
+      min: 1,
+      label: "Shell catch-all",
+    },
+    devTemplates: {
+      pattern: "shell/dev/templates/**/page.tsx",
+      min: 5,
+      label: "Dev template pages",
+    },
+  },
+};
+
+function scanPages(): string[] {
+  const pages: string[] = [];
+
+  function walk(dir: string, base: string): void {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      const rel = path.relative(base, full).replace(/\\/g, "/");
+      if (entry.isDirectory()) {
+        walk(full, base);
+      } else if (entry.name === "page.tsx") {
+        pages.push(rel);
+      }
+    }
+  }
+
+  walk(APP_DIR, APP_DIR);
+  return pages.sort();
+}
+
+function matchGlob(pattern: string, relPath: string): boolean {
+  // Glob → regex: ** (any path), * (within segment), {a,b} (alternation)
+  let result = "";
+  let i = 0;
+  while (i < pattern.length) {
+    const c = pattern[i];
+    if (c === "*" && pattern[i + 1] === "*") {
+      // ** — match anything including /; skip trailing /
+      result += ".*";
+      i += 2;
+      if (pattern[i] === "/") i++;
+    } else if (c === "*") {
+      result += "[^/]*";
+      i++;
+    } else if (c === "{") {
+      const end = pattern.indexOf("}", i);
+      if (end === -1) {
+        result += "\\{";
+        i++;
+      } else {
+        const opts = pattern
+          .slice(i + 1, end)
+          .split(",")
+          .map((s) => s.trim());
+        result += `(${opts.join("|")})`;
+        i = end + 1;
+      }
+    } else if (".+?^$()[]|\\".includes(c)) {
+      result += `\\${c}`;
+      i++;
+    } else {
+      result += c;
+      i++;
+    }
+  }
+  return new RegExp(`^${result}$`).test(relPath);
+}
+
+function main(): void {
+  const pages = scanPages();
+  const total = pages.length;
+
+  console.log("=== Page Count Baseline Check ===");
+  console.log(`Total page.tsx files: ${total} (baseline: ${BASELINE.total})`);
+  console.log("");
+
+  // Per-category check
+  let categoryFail = false;
+  for (const [, cat] of Object.entries(BASELINE.categories)) {
+    const matched = pages.filter((p) => matchGlob(cat.pattern, p));
+    const count = matched.length;
+    const status = count >= cat.min ? "✅" : "❌";
+    if (count < cat.min) categoryFail = true;
+    console.log(`  ${status} ${cat.label}: ${count} (min ${cat.min})`);
+  }
+  console.log("");
+
+  // Total check
+  const totalOk = total >= BASELINE.total;
+  if (!totalOk) {
+    console.log(`❌ Total ${total} < baseline ${BASELINE.total}`);
+  }
+
+  // List all pages
+  console.log("Pages:");
+  for (const p of pages) {
+    console.log(
+      `  /${p.replace(/\/page\.tsx$/, "").replace(/^page\.tsx$/, "")}`,
+    );
+  }
+  console.log("");
+
+  if (!totalOk || categoryFail) {
+    console.log("Result: FAIL");
+    process.exit(1);
+  } else {
+    console.log(`Result: PASS (${total} pages, all categories meet minimum)`);
+    process.exit(0);
+  }
+}
+
+main();

apps/portal-shell/scripts/check-route-table.ts

@@ -0,0 +1,169 @@
+// Route table consistency check (ARCHITECTURE.md §10 P1-8)
+//
+// Verifies that every actual /shell/* page.tsx route is registered in
+// route-permissions.ts (EXACT / PREFIX / DASHBOARD / PUBLIC_ROUTES).
+// Catches "unregistered routes" that would fall through to the catch-all
+// and be denied by middleware (fail-closed) — developers get a clear CI
+// error instead of a confusing runtime 403.
+//
+// Also reports "ghost entries" (EXACT table entries without a page.tsx)
+// as informational output — these are planned future routes (P2-P5).
+//
+// Usage: tsx scripts/check-route-table.ts
+// Exit: 0 = pass, 1 = violations found
+//
+// Related: ARCHITECTURE.md §3.4 V3-A1, §5.3, §10 P1-8, §11.7 红线 #5
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const APP_DIR = path.resolve(process.cwd(), "src/app");
+const ROUTE_PERMS_FILE = path.resolve(
+  process.cwd(),
+  "src/shared/lib/route-permissions.ts",
+);
+
+interface Violation {
+  type: "unregistered_route" | "ghost_entry";
+  route: string;
+  detail: string;
+}
+
+function scanActualRoutes(): Set<string> {
+  const routes = new Set<string>();
+
+  function walk(dir: string, prefix: string): void {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        // Skip catch-all [[...route]] directory
+        if (entry.name.startsWith("[[")) continue;
+        walk(full, `${prefix}/${entry.name}`);
+      } else if (entry.name === "page.tsx") {
+        routes.add(prefix || "/");
+      }
+    }
+  }
+
+  walk(APP_DIR, "");
+  return routes;
+}
+
+function extractRegisteredRoutes(): {
+  exact: Set<string>;
+  prefixes: string[];
+  publicRoutes: Set<string>;
+} {
+  const content = fs.readFileSync(ROUTE_PERMS_FILE, "utf8");
+  const exact = new Set<string>();
+  const prefixes: string[] = [];
+  const publicRoutes = new Set<string>();
+
+  const routeKeyRe = new RegExp('"(/[^"]*?)":\\s*\\{', "g");
+  const prefixRe = new RegExp('prefix:\\s*"(/[^"]*?)"', "g");
+
+  let m: RegExpExecArray | null;
+  while ((m = routeKeyRe.exec(content)) !== null) {
+    exact.add(m[1]);
+  }
+  while ((m = prefixRe.exec(content)) !== null) {
+    prefixes.push(m[1]);
+  }
+  // PUBLIC_ROUTES array entries (skip past `readonly string[] =` to the real `[`)
+  const publicBlock = content.match(
+    new RegExp("PUBLIC_ROUTES[^=]*=\\s*\\[([\\s\\S]*?)\\]"),
+  )?.[1];
+  if (publicBlock) {
+    const re = new RegExp('"(/[^"]*?)"', "g");
+    while ((m = re.exec(publicBlock)) !== null) {
+      publicRoutes.add(m[1]);
+    }
+  }
+
+  return { exact, prefixes, publicRoutes };
+}
+
+function isRegistered(
+  route: string,
+  exact: Set<string>,
+  prefixes: string[],
+  publicRoutes: Set<string>,
+): boolean {
+  if (publicRoutes.has(route)) return true;
+  if (exact.has(route)) return true;
+  for (const p of prefixes) {
+    if (route.startsWith(p)) return true;
+  }
+  return false;
+}
+
+function main(): void {
+  const actualRoutes = scanActualRoutes();
+  const { exact, prefixes, publicRoutes } = extractRegisteredRoutes();
+
+  const violations: Violation[] = [];
+
+  // Check A: every actual /shell/* route must be registered
+  for (const route of [...actualRoutes].sort()) {
+    if (!route.startsWith("/shell")) continue;
+    if (!isRegistered(route, exact, prefixes, publicRoutes)) {
+      violations.push({
+        type: "unregistered_route",
+        route,
+        detail:
+          "page.tsx exists but route not in EXACT/PREFIX/DASHBOARD/PUBLIC_ROUTES",
+      });
+    }
+  }
+
+  // Check B (informational): ghost entries (EXACT entries without page.tsx)
+  const ghostEntries: string[] = [];
+  for (const entry of [...exact].sort()) {
+    if (!entry.startsWith("/shell/")) continue;
+    if (!actualRoutes.has(entry)) {
+      ghostEntries.push(entry);
+    }
+  }
+
+  // Report
+  console.log("=== Route Table Consistency Check ===");
+  console.log(
+    `Actual /shell/* routes: ${[...actualRoutes].filter((r) => r.startsWith("/shell")).length}`,
+  );
+  console.log(
+    `EXACT entries: ${[...exact].filter((r) => r.startsWith("/shell/")).length}`,
+  );
+  console.log(`PREFIX entries: ${prefixes.length}`);
+  console.log(`PUBLIC_ROUTES: ${publicRoutes.size}`);
+  console.log("");
+
+  if (violations.length > 0) {
+    console.log("❌ VIOLATIONS (unregistered routes):");
+    for (const v of violations) {
+      console.log(`  ${v.route} — ${v.detail}`);
+    }
+    console.log("");
+  }
+
+  if (ghostEntries.length > 0) {
+    console.log(
+      `ℹ️  GHOST ENTRIES (planned, no page.tsx yet): ${ghostEntries.length}`,
+    );
+    for (const g of ghostEntries) {
+      console.log(`  ${g}`);
+    }
+    console.log("");
+  }
+
+  if (violations.length > 0) {
+    console.log(`Result: FAIL (${violations.length} violation(s))`);
+    process.exit(1);
+  } else {
+    console.log(
+      `Result: PASS (0 violations, ${ghostEntries.length} ghost entries)`,
+    );
+    process.exit(0);
+  }
+}
+
+main();