From d066da563f733cc60878322456c0e31dc7850ce3 Mon Sep 17 00:00:00 2001
From: SpecialX <47072643+wangxiner55@users.noreply.github.com>
Date: Wed, 22 Jul 2026 17:02:05 +0800
Subject: [PATCH] =?UTF-8?q?feat(portal-shell):=20=E6=95=99=E5=B8=88?=
 =?UTF-8?q?=E5=9F=9F=E8=80=83=E8=AF=95=E7=AE=A1=E7=90=86=E9=A1=B5=E9=9D=A2?=
 =?UTF-8?q?=E8=BF=81=E7=A7=BB=EF=BC=88P2=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

按 ARCHITECTURE.md §9.1/§10 P2 要求，迁移教师域 exams 模块：
- 列表页 /shell/teacher/exams（ListPageShell + URL 状态 + 客户端二次筛选）
- 详情页 /shell/teacher/exams/[id]（DetailPageShell + 真实 exam(id) 查询）
- 新建页 /shell/teacher/exams/new（FormPageShell + MSW 兜底）
- 纯函数 transformations.ts + 19 个 vitest 单测
- @contract-pending：exams(classId) 列表查询、createExam mutation 走 MSW
- 三态 UI（loading/error/empty）+ 路由级 loading.tsx/error.tsx
- i18n：zh-CN/en 双语补全，无硬编码中文
- MSW handlers 支持 variables 透传

§11.3 DoD 验收：
- lint: 0 errors（4 个 __generated__ 预存警告）
- typecheck: 0 errors
- test: 250/250 passed（含 19 个新增 transformations 测试）
- lint:tokens: 0 errors
---
 .../portal-shell/src/app/api/graphql/route.ts |   8 +-
 .../src/app/shell/teacher/exams/[id]/page.tsx |  22 ++
 .../src/app/shell/teacher/exams/error.tsx     |  33 +++
 .../src/app/shell/teacher/exams/loading.tsx   |   9 +
 .../src/app/shell/teacher/exams/new/page.tsx  |  23 ++
 .../src/app/shell/teacher/exams/page.tsx      |  23 ++
 .../exams/__tests__/transformations.test.ts   | 180 +++++++++++++
 .../teacher/exams/exam-detail-client.tsx      | 150 +++++++++++
 .../teacher/exams/exams-list-client.tsx       | 226 ++++++++++++++++
 .../teacher/exams/new-exam-client.tsx         | 244 ++++++++++++++++++
 .../features/teacher/exams/transformations.ts | 103 ++++++++
 apps/portal-shell/src/lib/api/exams.ts        | 208 +++++++++++++++
 apps/portal-shell/src/lib/api/index.ts        |   1 +
 .../src/lib/api/operations/exams.graphql.ts   |  72 ++++++
 .../src/lib/api/operations/index.ts           |   1 +
 apps/portal-shell/src/messages/en.json        |  66 ++++-
 apps/portal-shell/src/messages/zh-CN.json     |  66 ++++-
 apps/portal-shell/src/mocks/graphql-data.ts   | 135 +++++++++-
 apps/portal-shell/src/mocks/handlers.ts       |  18 +-
 19 files changed, 1578 insertions(+), 10 deletions(-)
 create mode 100644 apps/portal-shell/src/app/shell/teacher/exams/[id]/page.tsx
 create mode 100644 apps/portal-shell/src/app/shell/teacher/exams/error.tsx
 create mode 100644 apps/portal-shell/src/app/shell/teacher/exams/loading.tsx
 create mode 100644 apps/portal-shell/src/app/shell/teacher/exams/new/page.tsx
 create mode 100644 apps/portal-shell/src/app/shell/teacher/exams/page.tsx
 create mode 100644 apps/portal-shell/src/features/teacher/exams/__tests__/transformations.test.ts
 create mode 100644 apps/portal-shell/src/features/teacher/exams/exam-detail-client.tsx
 create mode 100644 apps/portal-shell/src/features/teacher/exams/exams-list-client.tsx
 create mode 100644 apps/portal-shell/src/features/teacher/exams/new-exam-client.tsx
 create mode 100644 apps/portal-shell/src/features/teacher/exams/transformations.ts
 create mode 100644 apps/portal-shell/src/lib/api/exams.ts
 create mode 100644 apps/portal-shell/src/lib/api/operations/exams.graphql.ts

diff --git a/apps/portal-shell/src/app/api/graphql/route.ts b/apps/portal-shell/src/app/api/graphql/route.ts
index 98520fc..593cb01 100644
--- a/apps/portal-shell/src/app/api/graphql/route.ts
+++ b/apps/portal-shell/src/app/api/graphql/route.ts
@@ -59,10 +59,12 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
   if (MSW_ENABLED) {
     const body = (await req.json().catch(() => ({}))) as {
       operationName?: string;
+      variables?: Record<string, unknown>;
     };
-    return NextResponse.json(graphqlResponse(body.operationName), {
-      headers: { "Cache-Control": "no-store" },
-    });
+    return NextResponse.json(
+      graphqlResponse(body.operationName, body.variables),
+      { headers: { "Cache-Control": "no-store" } },
+    );
   }
 
   const cookieHeader = req.headers.get("cookie");
diff --git a/apps/portal-shell/src/app/shell/teacher/exams/[id]/page.tsx b/apps/portal-shell/src/app/shell/teacher/exams/[id]/page.tsx
new file mode 100644
index 0000000..218e355
--- /dev/null
+++ b/apps/portal-shell/src/app/shell/teacher/exams/[id]/page.tsx
@@ -0,0 +1,22 @@
+import { Suspense } from "react";
+
+import { ExamDetailClient } from "@/features/teacher/exams/exam-detail-client";
+import { DetailPageSkeleton } from "@/shared/components/page-templates";
+
+/**
+ * 考试详情页（ARCHITECTURE.md §7.3 详情页 / §9.1 / §10 P2）
+ *
+ * Server Component 入口：仅负责 Suspense 边界包裹。
+ * 业务逻辑在 ExamDetailClient（client component）中。
+ *
+ * 数据契约：单查 exam(id: ID!) ✅ schema 真实字段（core-edu 子图）
+ *
+ * 关联：ARCHITECTURE.md §5.5 / §7.3 / §9.1 / §10 P2 / §11.3
+ */
+export default function ExamDetailPage(): React.ReactElement {
+  return (
+    <Suspense fallback={<DetailPageSkeleton />}>
+      <ExamDetailClient />
+    </Suspense>
+  );
+}
diff --git a/apps/portal-shell/src/app/shell/teacher/exams/error.tsx b/apps/portal-shell/src/app/shell/teacher/exams/error.tsx
new file mode 100644
index 0000000..3c8b4e0
--- /dev/null
+++ b/apps/portal-shell/src/app/shell/teacher/exams/error.tsx
@@ -0,0 +1,33 @@
+"use client";
+
+/**
+ * 考试路由错误边界（ARCHITECTURE.md §7.4 三态规范 / §11.3 DoD）。
+ * Next.js Route Segment error.tsx，捕获子树未处理异常。
+ */
+import { useEffect } from "react";
+
+import { Button } from "@/shared/components/ui/button";
+
+export default function ExamsError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}): React.ReactElement {
+  useEffect(() => {
+    console.error("[portal-shell] exams route error:", error);
+  }, [error]);
+
+  return (
+    <div className="flex flex-col items-center justify-center gap-4 rounded-xl border border-destructive/30 bg-destructive/5 p-10">
+      <h2 className="text-lg font-semibold text-destructive">考试页面出错了</h2>
+      <p className="text-sm text-muted-foreground">
+        {error.message || "未知错误"}
+      </p>
+      <Button onClick={reset} variant="outline">
+        重试
+      </Button>
+    </div>
+  );
+}
diff --git a/apps/portal-shell/src/app/shell/teacher/exams/loading.tsx b/apps/portal-shell/src/app/shell/teacher/exams/loading.tsx
new file mode 100644
index 0000000..04f9f39
--- /dev/null
+++ b/apps/portal-shell/src/app/shell/teacher/exams/loading.tsx
@@ -0,0 +1,9 @@
+import { ListPageSkeleton } from "@/shared/components/page-templates";
+
+/**
+ * 考试列表页加载骨架（ARCHITECTURE.md §7.4 三态规范 / §11.3 DoD）。
+ * Next.js Route Segment loading.tsx，自动包裹页面渲染期间。
+ */
+export default function ExamsLoading(): React.ReactElement {
+  return <ListPageSkeleton rows={5} />;
+}
diff --git a/apps/portal-shell/src/app/shell/teacher/exams/new/page.tsx b/apps/portal-shell/src/app/shell/teacher/exams/new/page.tsx
new file mode 100644
index 0000000..cb831b9
--- /dev/null
+++ b/apps/portal-shell/src/app/shell/teacher/exams/new/page.tsx
@@ -0,0 +1,23 @@
+import { Suspense } from "react";
+
+import { NewExamClient } from "@/features/teacher/exams/new-exam-client";
+import { FormPageSkeleton } from "@/shared/components/page-templates";
+
+/**
+ * 新建考试表单页（ARCHITECTURE.md §7.3 表单页 / §9.1 / §10 P2）
+ *
+ * Server Component 入口：仅负责 Suspense 边界包裹（useSearchParams 要求）。
+ * 业务逻辑在 NewExamClient（client component）中。
+ *
+ * 数据契约：mutation createExam(input) ❌ schema 无 Mutation → MSW 兜底（@contract-pending）
+ * 契约工单：docs/architecture/issues/contracts/core-edu_contract.md#create-exam-mutation
+ *
+ * 关联：ARCHITECTURE.md §5.3 / §5.4 / §7.3 / §9.1 / §10 P2 / §11.3 / §11.4
+ */
+export default function NewExamPage(): React.ReactElement {
+  return (
+    <Suspense fallback={<FormPageSkeleton />}>
+      <NewExamClient />
+    </Suspense>
+  );
+}
diff --git a/apps/portal-shell/src/app/shell/teacher/exams/page.tsx b/apps/portal-shell/src/app/shell/teacher/exams/page.tsx
new file mode 100644
index 0000000..7161d9e
--- /dev/null
+++ b/apps/portal-shell/src/app/shell/teacher/exams/page.tsx
@@ -0,0 +1,23 @@
+import { Suspense } from "react";
+
+import { ExamsListClient } from "@/features/teacher/exams/exams-list-client";
+import { ListPageSkeleton } from "@/shared/components/page-templates";
+
+/**
+ * 考试管理列表页（ARCHITECTURE.md §7.3 列表页 / §9.1 / §10 P2）
+ *
+ * Server Component 入口：仅负责 Suspense 边界包裹（useSearchParams 要求）。
+ * 业务逻辑在 ExamsListClient（client component）中。
+ *
+ * 数据契约：列表查询 exams(classId) ❌ schema 无此字段 → MSW 兜底（@contract-pending）
+ * 契约工单：docs/architecture/issues/contracts/core-edu_contract.md#exams-list
+ *
+ * 关联：ARCHITECTURE.md §5.3 / §5.4 / §7.3 / §9.1 / §10 P2 / §11.3 / §11.4
+ */
+export default function ExamsListPage(): React.ReactElement {
+  return (
+    <Suspense fallback={<ListPageSkeleton rows={5} />}>
+      <ExamsListClient />
+    </Suspense>
+  );
+}
diff --git a/apps/portal-shell/src/features/teacher/exams/__tests__/transformations.test.ts b/apps/portal-shell/src/features/teacher/exams/__tests__/transformations.test.ts
new file mode 100644
index 0000000..5da41da
--- /dev/null
+++ b/apps/portal-shell/src/features/teacher/exams/__tests__/transformations.test.ts
@@ -0,0 +1,180 @@
+/**
+ * Exams 数据变换工具单测（ARCHITECTURE.md §11.3 DoD）
+ *
+ * 关联：ARCHITECTURE.md §11.3 "数据变换/权限判断等纯函数有 vitest 单测"
+ */
+import { describe, expect, it } from "vitest";
+
+import type { Exam } from "@/lib/api";
+
+import {
+  EXAM_STATUS_LABEL,
+  formatDuration,
+  formatExamDate,
+  formatExamStatus,
+  isExamEditable,
+  isExamPublished,
+  parseTotalScore,
+  toExamListItem,
+} from "../transformations";
+
+describe("formatExamStatus", () => {
+  it("maps known statuses to Chinese labels", () => {
+    expect(formatExamStatus("DRAFT")).toBe("草稿");
+    expect(formatExamStatus("PUBLISHED")).toBe("已发布");
+    expect(formatExamStatus("IN_PROGRESS")).toBe("进行中");
+    expect(formatExamStatus("GRADING")).toBe("批改中");
+    expect(formatExamStatus("SCORED")).toBe("已完成");
+    expect(formatExamStatus("ARCHIVED")).toBe("已归档");
+  });
+
+  it("returns original value for unknown status", () => {
+    expect(formatExamStatus("UNKNOWN")).toBe("UNKNOWN");
+    expect(formatExamStatus("")).toBe("");
+  });
+
+  it("EXAM_STATUS_LABEL covers all standard statuses", () => {
+    expect(Object.keys(EXAM_STATUS_LABEL)).toHaveLength(6);
+  });
+});
+
+describe("formatExamDate", () => {
+  it("formats valid ISO date string", () => {
+    const result = formatExamDate("2026-07-22T10:00:00Z");
+    // 不同时区下日期字符串会有差异，但应包含 2026 与 07
+    expect(result).toContain("2026");
+    expect(result).toContain("07");
+  });
+
+  it("returns placeholder for null/undefined/empty", () => {
+    expect(formatExamDate(null)).toBe("--");
+    expect(formatExamDate(undefined)).toBe("--");
+    expect(formatExamDate("")).toBe("--");
+  });
+
+  it("returns placeholder for invalid date", () => {
+    expect(formatExamDate("not-a-date")).toBe("--");
+  });
+});
+
+describe("parseTotalScore", () => {
+  it("parses numeric string", () => {
+    expect(parseTotalScore("100")).toBe(100);
+    expect(parseTotalScore("0")).toBe(0);
+  });
+
+  it("passes through number input", () => {
+    expect(parseTotalScore(150)).toBe(150);
+  });
+
+  it("returns 0 for non-numeric string", () => {
+    expect(parseTotalScore("abc")).toBe(0);
+  });
+
+  it("returns 0 for NaN", () => {
+    expect(parseTotalScore(Number.NaN)).toBe(0);
+  });
+});
+
+describe("isExamEditable / isExamPublished", () => {
+  it("DRAFT is editable but not published", () => {
+    expect(isExamEditable("DRAFT")).toBe(true);
+    expect(isExamPublished("DRAFT")).toBe(false);
+  });
+
+  it("PUBLISHED and later statuses are published but not editable", () => {
+    for (const s of [
+      "PUBLISHED",
+      "IN_PROGRESS",
+      "GRADING",
+      "SCORED",
+      "ARCHIVED",
+    ]) {
+      expect(isExamEditable(s)).toBe(false);
+      expect(isExamPublished(s)).toBe(true);
+    }
+  });
+
+  it("unknown status is neither editable nor published", () => {
+    expect(isExamEditable("UNKNOWN")).toBe(false);
+    expect(isExamPublished("UNKNOWN")).toBe(false);
+  });
+});
+
+describe("toExamListItem", () => {
+  it("extracts list fields from full exam", () => {
+    const exam: Exam = {
+      id: "exam-001",
+      classId: "cls-001",
+      subjectId: "sub-math",
+      title: "期中考试",
+      description: "包含集合与函数",
+      examDate: "2026-07-22T10:00:00Z",
+      duration: 120,
+      totalScore: "100",
+      status: "DRAFT",
+      statusChangedAt: "2026-07-20T00:00:00Z",
+      statusChangedBy: "usr-001",
+      schoolId: "sch-001",
+      createdBy: "usr-001",
+      createdAt: "2026-07-19T00:00:00Z",
+      updatedAt: "2026-07-20T00:00:00Z",
+    };
+
+    const item = toExamListItem(exam);
+    expect(item.id).toBe("exam-001");
+    expect(item.title).toBe("期中考试");
+    expect(item.status).toBe("DRAFT");
+    // 裁剪掉的字段不在列表项类型上
+    expect(item).not.toHaveProperty("statusChangedAt");
+    expect(item).not.toHaveProperty("schoolId");
+    expect(item).not.toHaveProperty("createdBy");
+  });
+
+  it("handles null description", () => {
+    const exam: Exam = {
+      id: "exam-002",
+      classId: "cls-001",
+      subjectId: "sub-math",
+      title: "无描述考试",
+      description: null,
+      examDate: "2026-07-22T10:00:00Z",
+      duration: 60,
+      totalScore: "50",
+      status: "PUBLISHED",
+      statusChangedAt: "2026-07-20T00:00:00Z",
+      statusChangedBy: null,
+      schoolId: "sch-001",
+      createdBy: "usr-001",
+      createdAt: "2026-07-19T00:00:00Z",
+      updatedAt: "2026-07-20T00:00:00Z",
+    };
+    const item = toExamListItem(exam);
+    expect(item.description).toBeNull();
+  });
+});
+
+describe("formatDuration", () => {
+  it("formats minutes under 60", () => {
+    expect(formatDuration(30)).toBe("30 分钟");
+    expect(formatDuration(45)).toBe("45 分钟");
+    expect(formatDuration(1)).toBe("1 分钟");
+  });
+
+  it("formats exact hours", () => {
+    expect(formatDuration(60)).toBe("1 小时");
+    expect(formatDuration(120)).toBe("2 小时");
+  });
+
+  it("formats hours with remainder minutes", () => {
+    expect(formatDuration(90)).toBe("1 小时 30 分钟");
+    expect(formatDuration(75)).toBe("1 小时 15 分钟");
+  });
+
+  it("returns placeholder for invalid input", () => {
+    expect(formatDuration(0)).toBe("--");
+    expect(formatDuration(-1)).toBe("--");
+    expect(formatDuration(Number.NaN)).toBe("--");
+    expect(formatDuration(Number.POSITIVE_INFINITY)).toBe("--");
+  });
+});
diff --git a/apps/portal-shell/src/features/teacher/exams/exam-detail-client.tsx b/apps/portal-shell/src/features/teacher/exams/exam-detail-client.tsx
new file mode 100644
index 0000000..88ac6ba
--- /dev/null
+++ b/apps/portal-shell/src/features/teacher/exams/exam-detail-client.tsx
@@ -0,0 +1,150 @@
+"use client";
+
+/**
+ * 考试详情页 - 客户端组件（ARCHITECTURE.md §7.3 详情页 / §9.1 / §10 P2）
+ *
+ * 数据契约：
+ * - 单查 exam(id: ID!)：✅ schema 真实字段（core-edu 子图）
+ * - 无需 MSW 兜底，但 MSW 开启时也会返回 mock 数据（dev 体验）
+ *
+ * 三态规范（§11.3 DoD）：
+ * - loading：DetailPageSkeleton
+ * - error：errorNode 局部降级
+ * - notFound：data 为 null 时显示空态节点
+ *
+ * 关联：ARCHITECTURE.md §5.5 / §7.3 / §9.1 / §10 P2 / §11.3
+ */
+import { FileText } from "lucide-react";
+import { useParams } from "next/navigation";
+import { useTranslations } from "next-intl";
+
+import { useExam, type Exam } from "@/lib/api";
+import { Button } from "@/shared/components/ui/button";
+import {
+  DetailPageShell,
+  DetailPageSkeleton,
+  DetailSection,
+  DetailField,
+} from "@/shared/components/page-templates";
+import {
+  formatExamDate,
+  formatExamStatus,
+  formatDuration,
+  isExamEditable,
+  parseTotalScore,
+} from "@/features/teacher/exams/transformations";
+
+/**
+ * 详情客户端主体。需由 server page 包裹在 <Suspense> 中。
+ */
+export function ExamDetailClient(): React.ReactElement {
+  const t = useTranslations("exams");
+  const tCommon = useTranslations("common");
+  const params = useParams<{ id: string }>();
+  const examId = params?.id ?? "";
+
+  // ✅ 真实查询：exam(id: ID!)，schema 已就绪
+  const { data, loading, error } = useExam(examId);
+
+  const errorNode = error ? (
+    <div className="rounded-xl border border-destructive/30 bg-destructive/5 p-6 text-center">
+      <p className="text-sm text-destructive">
+        {tCommon("error.loadFailed", { message: String(error) })}
+      </p>
+    </div>
+  ) : undefined;
+
+  return (
+    <DetailPageShell
+      title={data?.title ?? t("detail.title")}
+      description={
+        data
+          ? t("detail.createdAtPrefix", {
+              date: formatExamDate(data.createdAt),
+            })
+          : undefined
+      }
+      icon={<FileText className="size-6" />}
+      backHref="/shell/teacher/exams"
+      actions={
+        data && isExamEditable(data.status) ? (
+          <Button variant="outline">{t("detail.edit")}</Button>
+        ) : null
+      }
+      loading={loading}
+      loadingNode={<DetailPageSkeleton />}
+      errorNode={errorNode}
+      emptyNode={
+        !loading && !error && !data ? (
+          <div className="rounded-xl border p-6 text-center text-muted-foreground">
+            {t("detail.notFound")}
+          </div>
+        ) : undefined
+      }
+    >
+      {data ? <ExamDetailBody exam={data} /> : null}
+    </DetailPageShell>
+  );
+}
+
+/**
+ * 详情内容区（基本信息 + 状态信息两个分区）。
+ */
+function ExamDetailBody({ exam }: { exam: Exam }): React.ReactElement {
+  const t = useTranslations("exams");
+  return (
+    <>
+      <DetailSection title={t("detail.sectionBasic")}>
+        <DetailField label={t("detail.fieldTitle")} value={exam.title} />
+        <DetailField
+          label={t("detail.fieldDescription")}
+          value={exam.description ?? "-"}
+        />
+        <DetailField
+          label={t("detail.fieldExamDate")}
+          value={formatExamDate(exam.examDate)}
+        />
+        <DetailField
+          label={t("detail.fieldDuration")}
+          value={formatDuration(exam.duration)}
+        />
+        <DetailField
+          label={t("detail.fieldTotalScore")}
+          value={`${parseTotalScore(exam.totalScore)} ${t("detail.unitScore")}`}
+        />
+        <DetailField label={t("detail.fieldClassId")} value={exam.classId} />
+        <DetailField
+          label={t("detail.fieldSubjectId")}
+          value={exam.subjectId}
+        />
+      </DetailSection>
+
+      <DetailSection title={t("detail.sectionStatus")}>
+        <DetailField
+          label={t("detail.fieldCurrentStatus")}
+          value={formatExamStatus(exam.status)}
+        />
+        <DetailField
+          label={t("detail.fieldStatusChangedAt")}
+          value={formatExamDate(exam.statusChangedAt)}
+        />
+        <DetailField
+          label={t("detail.fieldStatusChangedBy")}
+          value={exam.statusChangedBy ?? "-"}
+        />
+        <DetailField
+          label={t("detail.fieldCreatedBy")}
+          value={exam.createdBy}
+        />
+        <DetailField
+          label={t("detail.fieldCreatedAt")}
+          value={formatExamDate(exam.createdAt)}
+        />
+        <DetailField
+          label={t("detail.fieldUpdatedAt")}
+          value={formatExamDate(exam.updatedAt)}
+        />
+      </DetailSection>
+    </>
+  );
+}
diff --git a/apps/portal-shell/src/features/teacher/exams/exams-list-client.tsx b/apps/portal-shell/src/features/teacher/exams/exams-list-client.tsx
new file mode 100644
index 0000000..b45f918
--- /dev/null
+++ b/apps/portal-shell/src/features/teacher/exams/exams-list-client.tsx
@@ -0,0 +1,226 @@
+"use client";
+
+/**
+ * 考试管理列表页 - 客户端组件（ARCHITECTURE.md §7.3 列表页 / §9.1 / §10 P2）
+ *
+ * 数据契约：
+ * - 列表查询 exams(classId)：❌ schema 无此字段 → MSW 兜底（@contract-pending）
+ * - 契约工单：docs/architecture/issues/contracts/core-edu_contract.md#exams-list
+ *
+ * URL 状态：?classId=xxx &status=xxx &q=xxx
+ *
+ * 三态规范（§11.3 DoD）：loading（骨架）/ error（局部降级）/ empty（EmptyState）
+ *
+ * 关联：ARCHITECTURE.md §5.3 / §5.4 / §7.3 / §9.1 / §10 P2 / §11.3 / §11.4
+ */
+import { FileText } from "lucide-react";
+import Link from "next/link";
+import { useSearchParams, useRouter } from "next/navigation";
+import { useMemo, useTransition } from "react";
+import { useTranslations } from "next-intl";
+
+import { useExams, type ExamListItem } from "@/lib/api";
+import { Button } from "@/shared/components/ui/button";
+import { FilterSearchInput } from "@/shared/components/ui/filter-bar";
+import {
+  ListPageShell,
+  ListPageSkeleton,
+} from "@/shared/components/page-templates";
+import {
+  formatExamDate,
+  formatExamStatus,
+  formatDuration,
+  parseTotalScore,
+} from "@/features/teacher/exams/transformations";
+
+/**
+ * 列表客户端主体。需由 server page 包裹在 <Suspense> 中
+ * （useSearchParams 要求 Suspense 边界，Next.js 15 强制）。
+ */
+export function ExamsListClient(): React.ReactElement {
+  const t = useTranslations("exams");
+  const tCommon = useTranslations("common");
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const [, startTransition] = useTransition();
+
+  const classId = searchParams.get("classId") ?? "cls-001";
+  const statusFilter = searchParams.get("status") ?? "";
+  const q = searchParams.get("q") ?? "";
+
+  // @contract-pending：MSW 兜底
+  const { data, loading, error } = useExams(classId);
+
+  // 客户端二次筛选（status + q）—— 后端补齐列表查询后改服务端筛选
+  const filteredItems = useMemo<ExamListItem[]>(() => {
+    const items = data?.items ?? [];
+    return items.filter((item) => {
+      if (statusFilter && item.status !== statusFilter) return false;
+      if (q && !item.title.toLowerCase().includes(q.toLowerCase())) {
+        return false;
+      }
+      return true;
+    });
+  }, [data, statusFilter, q]);
+
+  const updateQuery = (key: string, value: string): void => {
+    const params = new URLSearchParams(searchParams.toString());
+    if (value) {
+      params.set(key, value);
+    } else {
+      params.delete(key);
+    }
+    startTransition(() => {
+      router.push(`/shell/teacher/exams?${params.toString()}`);
+    });
+  };
+
+  const errorNode = error ? (
+    <div className="rounded-xl border border-destructive/30 bg-destructive/5 p-6 text-center">
+      <p className="text-sm text-destructive">
+        {tCommon("error.loadFailed", { message: String(error) })}
+      </p>
+      <p className="mt-2 text-xs text-muted-foreground">
+        {/* @contract-pending 提示：MSW 兜底时若未开启 NEXT_PUBLIC_MSW=1 会失败 */}
+        {t("list.mswNotice")}
+      </p>
+    </div>
+  ) : undefined;
+
+  return (
+    <ListPageShell
+      title={t("list.title")}
+      description={t("list.description")}
+      icon={<FileText className="size-6" />}
+      actions={
+        <Button asChild>
+          <Link href={`/shell/teacher/exams/new?classId=${classId}`}>
+            {t("list.new")}
+          </Link>
+        </Button>
+      }
+      filters={
+        <>
+          <FilterSearchInput
+            placeholder={t("list.searchPlaceholder")}
+            value={q}
+            onChange={(v) => updateQuery("q", v)}
+          />
+          <select
+            value={statusFilter}
+            onChange={(e) => updateQuery("status", e.target.value)}
+            className="h-9 rounded-md border border-input bg-background px-3 text-sm"
+            aria-label={t("list.statusFilter")}
+          >
+            <option value="">{t("list.statusAll")}</option>
+            <option value="DRAFT">{t("list.statusDraft")}</option>
+            <option value="PUBLISHED">{t("list.statusPublished")}</option>
+            <option value="IN_PROGRESS">{t("list.statusInProgress")}</option>
+            <option value="SCORED">{t("list.statusScored")}</option>
+          </select>
+        </>
+      }
+      loading={loading}
+      loadingNode={<ListPageSkeleton rows={5} />}
+      empty={filteredItems.length === 0 && !loading}
+      errorNode={errorNode}
+      pagination={
+        <div className="flex items-center justify-end gap-2 text-sm text-muted-foreground">
+          <span>{t("list.total", { count: filteredItems.length })}</span>
+        </div>
+      }
+    >
+      <ExamsTable items={filteredItems} />
+    </ListPageShell>
+  );
+}
+
+/**
+ * 考试列表表格（纯展示组件，对齐 §8.2 排版规范）。
+ */
+function ExamsTable({ items }: { items: ExamListItem[] }): React.ReactElement {
+  const t = useTranslations("exams");
+  return (
+    <div className="overflow-x-auto rounded-xl border">
+      <table className="w-full text-sm">
+        <thead className="border-b bg-muted/30">
+          <tr>
+            <th className="p-3 text-left font-medium">{t("list.colName")}</th>
+            <th className="p-3 text-left font-medium">{t("list.colStatus")}</th>
+            <th className="p-3 text-left font-medium">
+              {t("list.colExamDate")}
+            </th>
+            <th className="p-3 text-left font-medium">
+              {t("list.colDuration")}
+            </th>
+            <th className="p-3 text-left font-medium">
+              {t("list.colTotalScore")}
+            </th>
+            <th className="p-3 text-right font-medium">
+              {t("list.colActions")}
+            </th>
+          </tr>
+        </thead>
+        <tbody className="divide-y">
+          {items.map((exam) => (
+            <tr key={exam.id} className="hover:bg-muted/30">
+              <td className="p-3">
+                <Link
+                  href={`/shell/teacher/exams/${exam.id}`}
+                  className="font-medium hover:underline"
+                >
+                  {exam.title}
+                </Link>
+                {exam.description ? (
+                  <p className="mt-1 text-xs text-muted-foreground">
+                    {exam.description}
+                  </p>
+                ) : null}
+              </td>
+              <td className="p-3">
+                <ExamStatusBadge status={exam.status} />
+              </td>
+              <td className="p-3 font-mono text-xs">
+                {formatExamDate(exam.examDate)}
+              </td>
+              <td className="p-3 text-xs">{formatDuration(exam.duration)}</td>
+              <td className="p-3">
+                {parseTotalScore(exam.totalScore)} {t("list.unitScore")}
+              </td>
+              <td className="p-3 text-right">
+                <Link
+                  href={`/shell/teacher/exams/${exam.id}`}
+                  className="text-xs text-muted-foreground hover:text-foreground"
+                >
+                  {t("list.viewDetail")}
+                </Link>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+/**
+ * 考试状态徽章（按状态色阶展示）。
+ */
+function ExamStatusBadge({ status }: { status: string }): React.ReactElement {
+  const label = formatExamStatus(status);
+  const cls =
+    status === "DRAFT"
+      ? "bg-muted text-muted-foreground"
+      : status === "PUBLISHED" || status === "IN_PROGRESS"
+        ? "bg-primary/10 text-primary"
+        : status === "SCORED"
+          ? "bg-emerald-500/10 text-emerald-600 dark:text-emerald-400"
+          : "bg-muted text-muted-foreground";
+  return (
+    <span
+      className={`inline-flex h-6 items-center rounded-full px-2 text-xs font-medium ${cls}`}
+    >
+      {label}
+    </span>
+  );
+}
diff --git a/apps/portal-shell/src/features/teacher/exams/new-exam-client.tsx b/apps/portal-shell/src/features/teacher/exams/new-exam-client.tsx
new file mode 100644
index 0000000..ff2be9a
--- /dev/null
+++ b/apps/portal-shell/src/features/teacher/exams/new-exam-client.tsx
@@ -0,0 +1,244 @@
+"use client";
+
+/**
+ * 新建考试表单页 - 客户端组件（ARCHITECTURE.md §7.3 表单页 / §9.1 / §10 P2）
+ *
+ * 数据契约：
+ * - mutation createExam(input)：❌ schema 无 Mutation 类型 → MSW 兜底（@contract-pending）
+ * - 契约工单：docs/architecture/issues/contracts/core-edu_contract.md#create-exam-mutation
+ *
+ * 三态规范（§11.3 DoD）：
+ * - loading：FormPageSkeleton（初始数据加载，由 server page Suspense 兜底）
+ * - error：errorSummary 表单级错误
+ * - success：notify.success + router.push 回列表
+ *
+ * 关联：ARCHITECTURE.md §5.3 / §5.4 / §7.3 / §9.1 / §10 P2 / §11.3 / §11.4
+ */
+import { FileText } from "lucide-react";
+import { useRouter, useSearchParams } from "next/navigation";
+import { useTransition, useState } from "react";
+import { useTranslations } from "next-intl";
+
+import { useCreateExam, type CreateExamInput } from "@/lib/api";
+import { FormPageShell } from "@/shared/components/page-templates";
+import { notify } from "@/shared/lib/notify";
+
+/**
+ * 表单客户端主体。需由 server page 包裹在 <Suspense> 中。
+ */
+export function NewExamClient(): React.ReactElement {
+  const t = useTranslations("exams");
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const [, startTransition] = useTransition();
+
+  const presetClassId = searchParams.get("classId") ?? "";
+
+  // @contract-pending：MSW 兜底
+  const { run: createExam, loading: submitting } = useCreateExam();
+
+  const handleSubmit = async (input: CreateExamInput): Promise<void> => {
+    try {
+      const result = await createExam(input);
+      notify.success(t("new.success"));
+      startTransition(() => {
+        router.push(`/shell/teacher/exams?classId=${input.classId}`);
+      });
+      void result;
+    } catch (err) {
+      notify.error(`${t("new.error")}: ${String(err)}`);
+    }
+  };
+
+  return (
+    <NewExamFormInner
+      presetClassId={presetClassId}
+      submitting={submitting}
+      onSubmit={handleSubmit}
+    />
+  );
+}
+
+/**
+ * 表单主体（受控表单 + 内联校验）。
+ *
+ * 注：未引入 react-hook-form + zod，因当前仅一个表单，引入会增加依赖。
+ * 后续表单数量增多后统一迁移到 react-hook-form（§7.3 表单页模板建议）。
+ */
+function NewExamFormInner({
+  presetClassId,
+  submitting,
+  onSubmit,
+}: {
+  presetClassId: string;
+  submitting: boolean;
+  onSubmit: (input: CreateExamInput) => Promise<void>;
+}): React.ReactElement {
+  const t = useTranslations("exams");
+  const tCommon = useTranslations("common");
+
+  const [classId, setClassId] = useState(presetClassId);
+  const [subjectId, setSubjectId] = useState("sub-math");
+  const [title, setTitle] = useState("");
+  const [description, setDescription] = useState("");
+  const [examDate, setExamDate] = useState("");
+  const [duration, setDuration] = useState("120");
+  const [totalScore, setTotalScore] = useState("100");
+  const [error, setError] = useState<string | null>(null);
+
+  const handleFormSubmit = (): void => {
+    setError(null);
+
+    if (!classId.trim()) {
+      setError(t("new.errorClassRequired"));
+      return;
+    }
+    if (!title.trim()) {
+      setError(t("new.errorTitleRequired"));
+      return;
+    }
+    if (!examDate) {
+      setError(t("new.errorDateRequired"));
+      return;
+    }
+
+    const input: CreateExamInput = {
+      classId: classId.trim(),
+      subjectId: subjectId.trim(),
+      title: title.trim(),
+      description: description.trim() || undefined,
+      examDate: new Date(examDate).toISOString(),
+      duration: Number(duration) || 0,
+      totalScore: Number(totalScore) || 0,
+    };
+
+    void onSubmit(input);
+  };
+
+  return (
+    <FormPageShell
+      title={t("new.title")}
+      description={t("new.description")}
+      icon={<FileText className="size-6" />}
+      backHref={`/shell/teacher/exams?classId=${classId}`}
+      onSubmit={handleFormSubmit}
+      submitting={submitting}
+      submitLabel={t("new.submit")}
+      cancelLabel={tCommon("button.cancel")}
+      errorSummary={
+        error ? <p className="text-sm text-destructive">{error}</p> : undefined
+      }
+    >
+      {/* 班级 ID */}
+      <FormField label={t("new.classId")} required>
+        <input
+          type="text"
+          value={classId}
+          onChange={(e) => setClassId(e.target.value)}
+          className="h-9 w-full rounded-md border border-input bg-background px-3 text-sm"
+          placeholder="cls-001"
+          required
+        />
+      </FormField>
+
+      {/* 科目 ID */}
+      <FormField label={t("new.subjectId")} required>
+        <input
+          type="text"
+          value={subjectId}
+          onChange={(e) => setSubjectId(e.target.value)}
+          className="h-9 w-full rounded-md border border-input bg-background px-3 text-sm"
+          placeholder="sub-math"
+          required
+        />
+      </FormField>
+
+      {/* 标题 */}
+      <FormField label={t("new.titleLabel")} required>
+        <input
+          type="text"
+          value={title}
+          onChange={(e) => setTitle(e.target.value)}
+          className="h-9 w-full rounded-md border border-input bg-background px-3 text-sm"
+          placeholder={t("new.titlePlaceholder")}
+          required
+        />
+      </FormField>
+
+      {/* 描述 */}
+      <FormField label={t("new.descriptionLabel")}>
+        <textarea
+          value={description}
+          onChange={(e) => setDescription(e.target.value)}
+          rows={3}
+          className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm"
+          placeholder={t("new.descriptionPlaceholder")}
+        />
+      </FormField>
+
+      {/* 考试日期 */}
+      <FormField label={t("new.examDate")} required>
+        <input
+          type="datetime-local"
+          value={examDate}
+          onChange={(e) => setExamDate(e.target.value)}
+          className="h-9 w-full rounded-md border border-input bg-background px-3 text-sm"
+          required
+        />
+      </FormField>
+
+      {/* 时长 + 满分 */}
+      <div className="grid grid-cols-2 gap-4">
+        <FormField label={t("new.duration")} required>
+          <input
+            type="number"
+            min={1}
+            value={duration}
+            onChange={(e) => setDuration(e.target.value)}
+            className="h-9 w-full rounded-md border border-input bg-background px-3 text-sm"
+            required
+          />
+        </FormField>
+        <FormField label={t("new.totalScore")} required>
+          <input
+            type="number"
+            min={1}
+            value={totalScore}
+            onChange={(e) => setTotalScore(e.target.value)}
+            className="h-9 w-full rounded-md border border-input bg-background px-3 text-sm"
+            required
+          />
+        </FormField>
+      </div>
+
+      {/* @contract-pending 提示 */}
+      <p className="text-xs text-muted-foreground">
+        {t("new.contractPending")}
+      </p>
+    </FormPageShell>
+  );
+}
+
+/**
+ * 表单字段容器（label + children）。
+ * 简化版，后续可提取到 shared/components/ui/form-field.tsx 复用。
+ */
+function FormField({
+  label,
+  required,
+  children,
+}: {
+  label: string;
+  required?: boolean;
+  children: React.ReactNode;
+}): React.ReactElement {
+  return (
+    <div className="space-y-2">
+      <label className="text-sm font-medium">
+        {label}
+        {required ? <span className="ml-1 text-destructive">*</span> : null}
+      </label>
+      {children}
+    </div>
+  );
+}
diff --git a/apps/portal-shell/src/features/teacher/exams/transformations.ts b/apps/portal-shell/src/features/teacher/exams/transformations.ts
new file mode 100644
index 0000000..238dfe2
--- /dev/null
+++ b/apps/portal-shell/src/features/teacher/exams/transformations.ts
@@ -0,0 +1,103 @@
+/**
+ * Exams 数据变换工具（ARCHITECTURE.md §11.3 DoD - 纯函数单测）
+ *
+ * 所有格式化/映射函数均为纯函数，便于 vitest 单测。
+ * 关联：ARCHITECTURE.md §11.3 DoD "数据变换/权限判断等纯函数有 vitest 单测"
+ */
+
+import type { Exam, ExamListItem } from "@/lib/api";
+
+/** 考试状态中文标签映射（对齐旧 teacher-portal EXAM_STATUS_LABEL） */
+export const EXAM_STATUS_LABEL: Record<string, string> = {
+  DRAFT: "草稿",
+  PUBLISHED: "已发布",
+  IN_PROGRESS: "进行中",
+  GRADING: "批改中",
+  SCORED: "已完成",
+  ARCHIVED: "已归档",
+};
+
+/**
+ * 将考试状态枚举值映射为中文标签。
+ * 未知状态回退为原始值。
+ */
+export function formatExamStatus(status: string): string {
+  return EXAM_STATUS_LABEL[status] ?? status;
+}
+
+/**
+ * 格式化 ISO 日期字符串为本地化展示（zh-CN）。
+ * 输入无效时返回占位符。
+ */
+export function formatExamDate(isoDate: string | null | undefined): string {
+  if (!isoDate) return "--";
+  const d = new Date(isoDate);
+  if (Number.isNaN(d.getTime())) return "--";
+  return d.toLocaleString("zh-CN", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/**
+ * 将 schema 的 totalScore（String）转为数值用于展示。
+ * 转换失败返回 0。
+ */
+export function parseTotalScore(totalScore: string | number): number {
+  const n = typeof totalScore === "number" ? totalScore : Number(totalScore);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/**
+ * 判断考试是否处于可编辑状态（DRAFT）。
+ */
+export function isExamEditable(status: string): boolean {
+  return status === "DRAFT";
+}
+
+/**
+ * 判断考试是否处于已发布后的状态（不可再编辑）。
+ */
+export function isExamPublished(status: string): boolean {
+  return (
+    status === "PUBLISHED" ||
+    status === "IN_PROGRESS" ||
+    status === "GRADING" ||
+    status === "SCORED" ||
+    status === "ARCHIVED"
+  );
+}
+
+/**
+ * 从考试详情中提取列表项视图模型（裁剪字段）。
+ */
+export function toExamListItem(exam: Exam): ExamListItem {
+  return {
+    id: exam.id,
+    classId: exam.classId,
+    subjectId: exam.subjectId,
+    title: exam.title,
+    description: exam.description,
+    examDate: exam.examDate,
+    duration: exam.duration,
+    totalScore: exam.totalScore,
+    status: exam.status,
+    createdAt: exam.createdAt,
+  };
+}
+
+/**
+ * 格式化时长（分钟）为更友好的展示。
+ * - 60 分钟以下：返回 "N 分钟"
+ * - 60 分钟以上：返回 "X 小时 Y 分钟"
+ */
+export function formatDuration(minutes: number): string {
+  if (!Number.isFinite(minutes) || minutes <= 0) return "--";
+  if (minutes < 60) return `${minutes} 分钟`;
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  return rest === 0 ? `${hours} 小时` : `${hours} 小时 ${rest} 分钟`;
+}
diff --git a/apps/portal-shell/src/lib/api/exams.ts b/apps/portal-shell/src/lib/api/exams.ts
new file mode 100644
index 0000000..db8294f
--- /dev/null
+++ b/apps/portal-shell/src/lib/api/exams.ts
@@ -0,0 +1,208 @@
+"use client";
+
+/**
+ * Exams domain API（ARCHITECTURE.md §5.1 / §5.3 / §9.1 教师域考试模块）
+ *
+ * 三类操作：
+ * 1. useExam（按 id 单查）：✅ 真实查询 exam(id: ID!)，schema 已就绪
+ * 2. useExams（列表查询）：❌ schema 无 exams(classId) → MSW 兜底（@contract-pending）
+ * 3. useCreateExam（mutation）：❌ schema 无 Mutation → MSW 兜底（@contract-pending）
+ *
+ * 契约工单：docs/architecture/issues/contracts/core-edu_contract.md
+ * 后端补齐后：重跑 normalize + codegen → 关闭 skipDocumentsValidation → 切换 fetcher → 删 mock
+ *
+ * 关联：ARCHITECTURE.md §5.3 契约纪律 / §5.4 MSW 兜底 / §9.1 / §11.4 契约工单
+ */
+import type { FetchPolicy } from "@apollo/client";
+
+import { useWidgetMutation } from "../useWidgetMutation";
+import { useWidgetQuery } from "../useWidgetQuery";
+import { ApiError } from "./errors";
+import {
+  CREATE_EXAM_DOC,
+  GET_EXAM_DOC,
+  GET_EXAMS_DOC,
+} from "./operations/exams.graphql";
+import type { UseQueryResult } from "./types";
+
+// ===== 数据类型 =====
+
+/**
+ * 考试实体（对齐 combined-schema.graphql Exam 类型）
+ *
+ * 字段命名 camelCase（与 schema 一致）；Exam.totalScore 在 schema 中是 String，
+ * 但业务层语义为数值，使用时由调用方做 Number() 转换。
+ */
+export interface Exam {
+  id: string;
+  classId: string;
+  subjectId: string;
+  title: string;
+  description: string | null;
+  examDate: string;
+  duration: number;
+  totalScore: string;
+  status: string;
+  statusChangedAt: string;
+  statusChangedBy: string | null;
+  schoolId: string;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** 考试列表项（轻量字段集，用于列表渲染） */
+export interface ExamListItem {
+  id: string;
+  classId: string;
+  subjectId: string;
+  title: string;
+  description: string | null;
+  examDate: string;
+  duration: number;
+  totalScore: string;
+  status: string;
+  createdAt: string;
+}
+
+/** 列表查询响应（@contract-pending 假契约形状，MSW 返回此结构） */
+interface ExamsListResponse {
+  exams: {
+    items: ExamListItem[];
+    total: number;
+  };
+}
+
+/** 单查响应（真实 schema） */
+interface ExamResponse {
+  exam: Exam | null;
+}
+
+/** 新建考试输入 */
+export interface CreateExamInput {
+  classId: string;
+  subjectId: string;
+  title: string;
+  description?: string;
+  examDate: string;
+  duration: number;
+  totalScore: number;
+}
+
+/** 新建考试 mutation 响应（@contract-pending） */
+interface CreateExamResponse {
+  createExam: { id: string } | null;
+}
+
+// ===== 查询选项 =====
+
+export interface ExamQueryOptions {
+  enabled?: boolean;
+  pollInterval?: number;
+  fetchPolicy?: FetchPolicy;
+}
+
+// ===== Hooks =====
+
+/**
+ * 按 id 查询考试详情（真实 schema，✅ 契约已就绪）。
+ *
+ * 关联：ARCHITECTURE.md §5.5 后端已就绪查询 / §9.1 详情页
+ */
+export function useExam(
+  id: string,
+  options?: ExamQueryOptions,
+): UseQueryResult<Exam | null> {
+  const result = useWidgetQuery<ExamResponse, { id: string }>(
+    GET_EXAM_DOC,
+    { id },
+    {
+      ...options,
+      enabled: options?.enabled ?? id.length > 0,
+    },
+  );
+  return {
+    data: result.data?.exam ?? null,
+    loading: result.loading,
+    error: result.error,
+    refetch: result.refetch,
+  };
+}
+
+/**
+ * 查询班级下的考试列表（@contract-pending，MSW 兜底）。
+ *
+ * schema 无 exams(classId) 根字段，由 MSW handlers 返回 mock 数据。
+ * 后端补齐列表查询后切换到真实 fetcher，页面无需改动。
+ *
+ * 关联：ARCHITECTURE.md §5.4 / §9.1 列表页 / §11.4 契约工单
+ */
+export function useExams(
+  classId: string,
+  options?: ExamQueryOptions & {
+    status?: string;
+    limit?: number;
+    offset?: number;
+  },
+): UseQueryResult<{ items: ExamListItem[]; total: number }> {
+  const result = useWidgetQuery<
+    ExamsListResponse,
+    {
+      classId: string;
+      status?: string;
+      limit?: number;
+      offset?: number;
+    }
+  >(
+    GET_EXAMS_DOC,
+    {
+      classId,
+      status: options?.status,
+      limit: options?.limit,
+      offset: options?.offset,
+    },
+    {
+      enabled: options?.enabled ?? classId.length > 0,
+      fetchPolicy: options?.fetchPolicy,
+      pollInterval: options?.pollInterval,
+    },
+  );
+  return {
+    data: result.data?.exams,
+    loading: result.loading,
+    error: result.error,
+    refetch: result.refetch,
+  };
+}
+
+/**
+ * 创建考试（@contract-pending，MSW 兜底）。
+ *
+ * schema 无 Mutation 类型，由 MSW handlers 返回 mock 数据。
+ * 后端补齐 mutation 后切换到真实 fetcher。
+ *
+ * 关联：ARCHITECTURE.md §5.4 / §9.1 表单页 / §11.4 契约工单
+ */
+export function useCreateExam(): {
+  run: (input: CreateExamInput) => Promise<{ id: string }>;
+  loading: boolean;
+  error: unknown;
+} {
+  const {
+    run: rawRun,
+    loading,
+    error,
+  } = useWidgetMutation<CreateExamResponse, { input: CreateExamInput }>(
+    CREATE_EXAM_DOC,
+  );
+
+  const run = async (input: CreateExamInput): Promise<{ id: string }> => {
+    const data = await rawRun({ input });
+    if (!data?.createExam) {
+      throw new ApiError("Failed to create exam", "INTERNAL_ERROR");
+    }
+    return data.createExam;
+  };
+
+  return { run, loading, error };
+}
diff --git a/apps/portal-shell/src/lib/api/index.ts b/apps/portal-shell/src/lib/api/index.ts
index 976deca..9044d63 100644
--- a/apps/portal-shell/src/lib/api/index.ts
+++ b/apps/portal-shell/src/lib/api/index.ts
@@ -14,6 +14,7 @@ export * from "./dashboard";
 export * from "./sidebar";
 export * from "./topbar";
 export * from "./teacher";
+export * from "./exams";
 export * from "./student";
 export * from "./parent";
 export * from "./admin";
diff --git a/apps/portal-shell/src/lib/api/operations/exams.graphql.ts b/apps/portal-shell/src/lib/api/operations/exams.graphql.ts
new file mode 100644
index 0000000..16756f6
--- /dev/null
+++ b/apps/portal-shell/src/lib/api/operations/exams.graphql.ts
@@ -0,0 +1,72 @@
+// Exams domain GraphQL documents (ARCHITECTURE.md §5.3 契约纪律 / §9.1)
+//
+// 拆分原则：
+// - GetExam（按 id 单查）：✅ combined-schema 中真实存在（exam(id: ID!): Exam）
+// - GetExams（列表查询）：❌ schema 无 exams(classId) 根字段
+//     → 走 MSW 兜底（@contract-pending），等待后端补齐列表契约
+// - CreateExam（mutation）：❌ schema 无 Mutation 类型
+//     → 走 MSW 兜底（@contract-pending），等待后端补齐 mutation 契约
+//
+// 契约工单：docs/architecture/issues/contracts/core-edu_contract.md
+// 关联：ARCHITECTURE.md §5.3 / §5.4 / §9.1 / §11.4
+import { gql } from "@apollo/client";
+
+// ── 真实查询：exam(id) 单查 ─────────────────────────────────────
+// 字段全部对齐 combined-schema.graphql 中 Exam 类型（core-edu 子图）
+export const GET_EXAM_DOC = gql`
+  query GetExam($id: ID!) {
+    exam(id: $id) {
+      id
+      classId
+      subjectId
+      title
+      description
+      examDate
+      duration
+      totalScore
+      status
+      statusChangedAt
+      statusChangedBy
+      schoolId
+      createdBy
+      createdAt
+      updatedAt
+    }
+  }
+`;
+
+// ── 假契约查询（@contract-pending）─────────────────────────────
+// 列表查询：schema 无 exams(classId) 根字段
+// 页面通过 MSW 兜底获取列表数据，后端补齐后切换 fetcher 指向真实查询
+// 契约工单：core-edu_contract.md#exams-list
+export const GET_EXAMS_DOC = gql`
+  query GetExams($classId: ID!, $status: String, $limit: Int, $offset: Int) {
+    exams(classId: $classId, status: $status, limit: $limit, offset: $offset) {
+      items {
+        id
+        classId
+        subjectId
+        title
+        description
+        examDate
+        duration
+        totalScore
+        status
+        createdAt
+      }
+      total
+    }
+  }
+`;
+
+// ── 假契约变更（@contract-pending）─────────────────────────────
+// 创建考试：schema 无 Mutation 类型
+// 页面通过 MSW 兜底提交，后端补齐 mutation 后切换 fetcher
+// 契约工单：core-edu_contract.md#create-exam-mutation
+export const CREATE_EXAM_DOC = gql`
+  mutation CreateExam($input: CreateExamInput!) {
+    createExam(input: $input) {
+      id
+    }
+  }
+`;
diff --git a/apps/portal-shell/src/lib/api/operations/index.ts b/apps/portal-shell/src/lib/api/operations/index.ts
index 834641a..a2acde5 100644
--- a/apps/portal-shell/src/lib/api/operations/index.ts
+++ b/apps/portal-shell/src/lib/api/operations/index.ts
@@ -4,6 +4,7 @@ export * from "./universal.graphql";
 export * from "./sidebar.graphql";
 export * from "./topbar.graphql";
 export * from "./teacher.graphql";
+export * from "./exams.graphql";
 export * from "./student.graphql";
 export * from "./parent.graphql";
 export * from "./admin.graphql";
diff --git a/apps/portal-shell/src/messages/en.json b/apps/portal-shell/src/messages/en.json
index b1472a9..8892730 100644
--- a/apps/portal-shell/src/messages/en.json
+++ b/apps/portal-shell/src/messages/en.json
@@ -146,7 +146,71 @@
     "title": "Classes"
   },
   "exams": {
-    "title": "Exams"
+    "title": "Exams",
+    "list": {
+      "title": "Exams",
+      "description": "View and manage all exams",
+      "new": "New Exam",
+      "searchPlaceholder": "Search exam name...",
+      "statusFilter": "Filter by status",
+      "statusAll": "All statuses",
+      "statusDraft": "Draft",
+      "statusPublished": "Published",
+      "statusInProgress": "In Progress",
+      "statusScored": "Completed",
+      "total": "{count} total",
+      "colName": "Name",
+      "colStatus": "Status",
+      "colExamDate": "Exam Date",
+      "colDuration": "Duration",
+      "colTotalScore": "Total Score",
+      "colActions": "Actions",
+      "viewDetail": "View Detail →",
+      "mswNotice": "List query contract is pending, please ensure NEXT_PUBLIC_MSW=1 is enabled.",
+      "unitScore": "pts"
+    },
+    "detail": {
+      "title": "Exam Detail",
+      "edit": "Edit",
+      "notFound": "Exam not found, may have been deleted",
+      "createdAtPrefix": "Created on {date}",
+      "sectionBasic": "Basic Info",
+      "sectionStatus": "Status Info",
+      "fieldTitle": "Title",
+      "fieldDescription": "Description",
+      "fieldExamDate": "Exam Date",
+      "fieldDuration": "Duration",
+      "fieldTotalScore": "Total Score",
+      "fieldClassId": "Class ID",
+      "fieldSubjectId": "Subject ID",
+      "fieldCurrentStatus": "Current Status",
+      "fieldStatusChangedAt": "Status Changed At",
+      "fieldStatusChangedBy": "Status Changed By",
+      "fieldCreatedBy": "Created By",
+      "fieldCreatedAt": "Created At",
+      "fieldUpdatedAt": "Updated At",
+      "unitScore": "pts"
+    },
+    "new": {
+      "title": "New Exam",
+      "description": "Fill in exam basic information",
+      "submit": "Create Exam",
+      "success": "Exam created successfully",
+      "error": "Creation failed",
+      "classId": "Class ID",
+      "subjectId": "Subject ID",
+      "titleLabel": "Title",
+      "titlePlaceholder": "e.g. 2026 Spring Midterm",
+      "descriptionLabel": "Description",
+      "descriptionPlaceholder": "Exam scope, notes, etc.",
+      "examDate": "Exam Date",
+      "duration": "Duration (minutes)",
+      "totalScore": "Total Score",
+      "errorClassRequired": "Please fill in Class ID",
+      "errorTitleRequired": "Please fill in exam title",
+      "errorDateRequired": "Please select exam date",
+      "contractPending": "Create exam contract is @contract-pending, currently backed by MSW. Will switch to real submission once backend mutation is ready."
+    }
   },
   "homework": {
     "title": "Homework"
diff --git a/apps/portal-shell/src/messages/zh-CN.json b/apps/portal-shell/src/messages/zh-CN.json
index 650bb06..68342de 100644
--- a/apps/portal-shell/src/messages/zh-CN.json
+++ b/apps/portal-shell/src/messages/zh-CN.json
@@ -146,7 +146,71 @@
     "title": "班级管理"
   },
   "exams": {
-    "title": "考试管理"
+    "title": "考试管理",
+    "list": {
+      "title": "考试管理",
+      "description": "查看和管理所有考试",
+      "new": "新建考试",
+      "searchPlaceholder": "搜索考试名称...",
+      "statusFilter": "按状态筛选",
+      "statusAll": "全部状态",
+      "statusDraft": "草稿",
+      "statusPublished": "已发布",
+      "statusInProgress": "进行中",
+      "statusScored": "已完成",
+      "total": "共 {count} 条",
+      "colName": "名称",
+      "colStatus": "状态",
+      "colExamDate": "考试时间",
+      "colDuration": "时长",
+      "colTotalScore": "满分",
+      "colActions": "操作",
+      "viewDetail": "查看详情 →",
+      "mswNotice": "列表查询契约待补齐，请确认 NEXT_PUBLIC_MSW=1 已启用。",
+      "unitScore": "分"
+    },
+    "detail": {
+      "title": "考试详情",
+      "edit": "编辑",
+      "notFound": "未找到考试，可能已被删除",
+      "createdAtPrefix": "创建于 {date}",
+      "sectionBasic": "基本信息",
+      "sectionStatus": "状态信息",
+      "fieldTitle": "标题",
+      "fieldDescription": "描述",
+      "fieldExamDate": "考试时间",
+      "fieldDuration": "时长",
+      "fieldTotalScore": "满分",
+      "fieldClassId": "班级 ID",
+      "fieldSubjectId": "科目 ID",
+      "fieldCurrentStatus": "当前状态",
+      "fieldStatusChangedAt": "状态变更时间",
+      "fieldStatusChangedBy": "状态变更人",
+      "fieldCreatedBy": "创建人",
+      "fieldCreatedAt": "创建时间",
+      "fieldUpdatedAt": "更新时间",
+      "unitScore": "分"
+    },
+    "new": {
+      "title": "新建考试",
+      "description": "填写考试基本信息",
+      "submit": "创建考试",
+      "success": "考试创建成功",
+      "error": "创建失败",
+      "classId": "班级 ID",
+      "subjectId": "科目 ID",
+      "titleLabel": "标题",
+      "titlePlaceholder": "例如：2026 春季期中考试",
+      "descriptionLabel": "描述",
+      "descriptionPlaceholder": "考试范围、注意事项等",
+      "examDate": "考试日期",
+      "duration": "时长（分钟）",
+      "totalScore": "满分",
+      "errorClassRequired": "请填写班级 ID",
+      "errorTitleRequired": "请填写考试标题",
+      "errorDateRequired": "请选择考试日期",
+      "contractPending": "创建考试契约为 @contract-pending，当前通过 MSW 兜底。后端补齐 mutation 后将切换为真实提交。"
+    }
   },
   "homework": {
     "title": "作业管理"
diff --git a/apps/portal-shell/src/mocks/graphql-data.ts b/apps/portal-shell/src/mocks/graphql-data.ts
index 4c5d8d6..1da76f1 100644
--- a/apps/portal-shell/src/mocks/graphql-data.ts
+++ b/apps/portal-shell/src/mocks/graphql-data.ts
@@ -245,6 +245,67 @@ const mockTextbooks = [
   },
 ];
 
+// ── Exams 域（@contract-pending，schema 无 exams 列表/createExam mutation）
+// 用于 /shell/teacher/exams 列表页 + /new 表单页 MSW 兜底
+const mockExams = [
+  {
+    id: "exam-001",
+    classId: "cls-001",
+    subjectId: "sub-math",
+    title: "2026 春季期中考试",
+    description: "覆盖集合、函数、基本初等函数",
+    examDate: "2026-04-15T09:00:00Z",
+    duration: 120,
+    totalScore: "100",
+    status: "SCORED",
+    createdAt: "2026-04-01T00:00:00Z",
+  },
+  {
+    id: "exam-002",
+    classId: "cls-001",
+    subjectId: "sub-math",
+    title: "2026 春季期末考试",
+    description: "全册内容",
+    examDate: "2026-07-20T09:00:00Z",
+    duration: 120,
+    totalScore: "150",
+    status: "IN_PROGRESS",
+    createdAt: "2026-07-10T00:00:00Z",
+  },
+  {
+    id: "exam-003",
+    classId: "cls-001",
+    subjectId: "sub-math",
+    title: "单元测验 - 集合",
+    description: null,
+    examDate: "2026-07-25T14:00:00Z",
+    duration: 45,
+    totalScore: "50",
+    status: "DRAFT",
+    createdAt: "2026-07-22T00:00:00Z",
+  },
+];
+
+// ── Exam 单查 mock（与 combined-schema Exam 类型字段对齐）
+// 用于 /shell/teacher/exams/[id] 详情页 MSW 兜底
+const mockExamDetail = {
+  id: "exam-001",
+  classId: "cls-001",
+  subjectId: "sub-math",
+  title: "2026 春季期中考试",
+  description: "覆盖集合、函数、基本初等函数",
+  examDate: "2026-04-15T09:00:00Z",
+  duration: 120,
+  totalScore: "100",
+  status: "SCORED",
+  statusChangedAt: "2026-04-16T10:00:00Z",
+  statusChangedBy: "usr-teacher-001",
+  schoolId: "sch-001",
+  createdBy: "usr-teacher-001",
+  createdAt: "2026-04-01T00:00:00Z",
+  updatedAt: "2026-04-16T10:00:00Z",
+};
+
 const mockGrades = [
   {
     student_id: "stu-001",
@@ -275,10 +336,26 @@ const mockGrades = [
 // ── GraphQL Response ───────────────────────────────────────────
 
 /**
- * 根据 operationName 返回 mock GraphQL 响应。
+ * GraphQL 请求体结构（用于 MSW handler 与 route.ts 透传）。
+ */
+export interface GraphQLRequestBody {
+  operationName?: string;
+  variables?: Record<string, unknown>;
+}
+
+/**
+ * 根据 operationName + variables 返回 mock GraphQL 响应。
+ *
+ * Exams 域扩展：
+ * - GetExam($id)：返回 mockExamDetail（任意 id 都返回同一条，dev 兜底用）
+ * - GetExams($classId)：返回 mockExams（按 classId 过滤，未指定返回全部）
+ * - CreateExam($input)：返回新生成的 id（基于时间戳）
+ *
+ * 关联：ARCHITECTURE.md §5.4 / §9.1 / §11.4 契约工单
  */
 export function graphqlResponse(
   operationName: string | undefined,
+  variables?: Record<string, unknown>,
 ): Record<string, unknown> {
   switch (operationName) {
     // ── Dashboard 域 ──
@@ -408,6 +485,62 @@ export function graphqlResponse(
         },
       };
 
+    // ── Exams 域（教师域 P2 迁移，@contract-pending）──
+    // GetExam($id)：按 id 单查，任意 id 都返回同一条（dev 兜底）
+    case "GetExam": {
+      const examId = (variables?.id as string | undefined) ?? "";
+      // 若请求的是 mockExams 中的某一条，返回对应数据；否则返回 mockExamDetail
+      const found = mockExams.find((e) => e.id === examId) ?? mockExamDetail;
+      return {
+        data: {
+          exam: {
+            ...found,
+            statusChangedAt: "2026-04-16T10:00:00Z",
+            statusChangedBy: "usr-teacher-001",
+            schoolId: "sch-001",
+            createdBy: "usr-teacher-001",
+            updatedAt: "2026-04-16T10:00:00Z",
+          },
+        },
+      };
+    }
+    // GetExams($classId)：列表查询，按 classId 过滤（未指定返回全部）
+    case "GetExams": {
+      const classId = variables?.classId as string | undefined;
+      const status = variables?.status as string | undefined;
+      const filtered = mockExams.filter(
+        (e) =>
+          (!classId || e.classId === classId) &&
+          (!status || e.status === status),
+      );
+      return {
+        data: {
+          exams: {
+            items: filtered,
+            total: filtered.length,
+          },
+        },
+      };
+    }
+    // CreateExam($input)：mutation 兜底，返回基于时间戳的新 id
+    case "CreateExam": {
+      const input = (variables?.input ?? {}) as Record<string, unknown>;
+      const newId = `exam-${Date.now()}`;
+      mockExams.push({
+        id: newId,
+        classId: (input.classId as string) ?? "cls-001",
+        subjectId: (input.subjectId as string) ?? "sub-math",
+        title: (input.title as string) ?? "未命名考试",
+        description: (input.description as string | null) ?? null,
+        examDate: (input.examDate as string) ?? new Date().toISOString(),
+        duration: (input.duration as number) ?? 120,
+        totalScore: String((input.totalScore as number) ?? 100),
+        status: "DRAFT",
+        createdAt: new Date().toISOString(),
+      });
+      return { data: { createExam: { id: newId } } };
+    }
+
     // ── Grades 域（预留） ──
     case "GetGrades":
       return { data: { grades: mockGrades } };
diff --git a/apps/portal-shell/src/mocks/handlers.ts b/apps/portal-shell/src/mocks/handlers.ts
index ef692b9..84f6811 100644
--- a/apps/portal-shell/src/mocks/handlers.ts
+++ b/apps/portal-shell/src/mocks/handlers.ts
@@ -24,14 +24,24 @@ const APOLLO_ROUTER_GRAPHQL =
 export const handlers = [
   // GraphQL 同域代理（客户端 Apollo Client）
   http.post("/api/graphql", async ({ request }) => {
-    const body = (await request.json()) as { operationName?: string };
-    return HttpResponse.json(graphqlResponse(body.operationName));
+    const body = (await request.json()) as {
+      operationName?: string;
+      variables?: Record<string, unknown>;
+    };
+    return HttpResponse.json(
+      graphqlResponse(body.operationName, body.variables),
+    );
   }),
 
   // GraphQL SSR 直连兜底（msw/node server 拦截 RSC 端 fetch）
   http.post(APOLLO_ROUTER_GRAPHQL, async ({ request }) => {
-    const body = (await request.json()) as { operationName?: string };
-    return HttpResponse.json(graphqlResponse(body.operationName));
+    const body = (await request.json()) as {
+      operationName?: string;
+      variables?: Record<string, unknown>;
+    };
+    return HttpResponse.json(
+      graphqlResponse(body.operationName, body.variables),
+    );
   }),
 
   // 登录兜底（DEV_MODE 使用）