feat(teacher-portal): 完整实现 teacher-portal 微前端

包含 settings/students/api、graphql、mocks、ui-tokens 设计令牌等

apps/teacher-portal/src/app/(app)/classes/page.tsx

@@ -1,293 +1,97 @@
 "use client";
 
-import { useState, useEffect, useCallback } from "react";
-import { getToken } from "@/lib/auth";
+/**
+ * Classes 页面 - 班级管理（只读列表）
+ *
+ * 数据来源（ARB-001 §1.2）：GraphQL ClassesQuery
+ * - 返回当前教师 dataScope 范围内的班级列表
+ * - P2 阶段为只读展示（Mutation 在 P3 启用）
+ *
+ * 维护者：ai13（teacher-portal）
+ */
 
-interface ClassItem {
-  id: string;
-  name: string;
-  gradeId: string;
-  description?: string;
-  createdAt: number;
-  updatedAt: number;
-}
-
-interface ApiResponse<T> {
-  success: boolean;
-  data?: T;
-  error?: { code: string; message: string };
-}
+import { useQuery } from "urql";
+import Link from "next/link";
+import { Loading, Empty } from "@edu/ui-components";
+import { ClassesQuery } from "@/lib/graphql";
+import type { Class } from "@/lib/graphql";
 
 export default function ClassesPage() {
-  const [classes, setClasses] = useState<ClassItem[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [name, setName] = useState("");
-  const [gradeId, setGradeId] = useState(
-    "550e8400-e29b-41d4-a716-446655440000",
-  );
-  const [description, setDescription] = useState("");
-  const [error, setError] = useState<string | null>(null);
-
-  const authHeaders = (): Record<string, string> => {
-    const token = getToken();
-    return token ? { Authorization: `Bearer ${token}` } : {};
-  };
-
-  const fetchClasses = useCallback(async () => {
-    setLoading(true);
-    setError(null);
-    try {
-      const res = await fetch("/api/v1/classes", {
-        headers: authHeaders(),
-      });
-      const json: ApiResponse<ClassItem[]> = await res.json();
-      if (json.success && json.data) {
-        setClasses(json.data);
-      } else {
-        setError(json.error?.message || "Failed to load");
-      }
-    } catch (e) {
-      setError(e instanceof Error ? e.message : "Network error");
-    } finally {
-      setLoading(false);
-    }
-  }, []);
-
-  useEffect(() => {
-    fetchClasses();
-  }, [fetchClasses]);
-
-  const handleCreate = async (e: React.FormEvent) => {
-    e.preventDefault();
-    if (!name.trim()) return;
-    try {
-      const res = await fetch("/api/v1/classes", {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          ...authHeaders(),
-        },
-        body: JSON.stringify({ name, gradeId, description }),
-      });
-      const json = await res.json();
-      if (!json.success) {
-        setError(json.error?.message || "Create failed");
-        return;
-      }
-      setName("");
-      setDescription("");
-      await fetchClasses();
-    } catch (e) {
-      setError(e instanceof Error ? e.message : "Network error");
-    }
-  };
-
-  const handleDelete = async (id: string) => {
-    try {
-      const res = await fetch(`/api/v1/classes/${id}`, {
-        method: "DELETE",
-        headers: authHeaders(),
-      });
-      const json = await res.json();
-      if (!json.success) {
-        setError(json.error?.message || "Delete failed");
-        return;
-      }
-      await fetchClasses();
-    } catch (e) {
-      setError(e instanceof Error ? e.message : "Network error");
-    }
-  };
+  const [result] = useQuery({ query: ClassesQuery });
 
   return (
     <div className="px-10 py-10">
       <header className="mb-8">
-        <h1
-          className="text-3xl"
-          style={{
-            fontFamily: "var(--font-serif)",
-            color: "var(--color-ink)",
-          }}
-        >
-          班级管理
-        </h1>
-        <p className="mt-1 text-sm" style={{ color: "var(--color-ink-muted)" }}>
-          classes 域 CRUD · JWT 鉴权
+        <h1 className="text-3xl font-serif text-ink">班级管理</h1>
+        <p className="mt-1 text-sm text-ink-muted">
+          GraphQL ClassesQuery · 按教师 dataScope 过滤
         </p>
       </header>
 
       <div className="rule-thin mb-8" />
 
-      <div className="grid grid-cols-12 gap-8">
-        <aside className="col-span-4">
-          <h2
-            className="text-xl mb-4"
-            style={{ fontFamily: "var(--font-serif)" }}
-          >
-            新建班级
+      <section>
+        <div className="flex items-baseline justify-between mb-4">
+          <h2 className="text-xl font-serif text-ink">
+            班级列表
+            <span className="ml-2 text-sm font-sans text-ink-muted">
+              {result.data?.classes.length ?? 0} 个
+            </span>
           </h2>
-          <div className="rule-thin mb-4" />
-          <form onSubmit={handleCreate} className="space-y-4">
-            <div>
-              <label
-                className="block text-xs uppercase tracking-wide mb-1"
-                style={{ color: "var(--color-ink-muted)" }}
-              >
-                班级名称
-              </label>
-              <input
-                type="text"
-                value={name}
-                onChange={(e) => setName(e.target.value)}
-                className="w-full px-3 py-2 bg-transparent border-b focus:outline-none focus:border-b-2"
-                style={{
-                  borderColor: "var(--color-rule)",
-                  borderRadius: "6px 6px 0 0",
-                }}
-                placeholder="如：高三(1)班"
-                required
-              />
-            </div>
-            <div>
-              <label
-                className="block text-xs uppercase tracking-wide mb-1"
-                style={{ color: "var(--color-ink-muted)" }}
-              >
-                年级 ID
-              </label>
-              <input
-                type="text"
-                value={gradeId}
-                onChange={(e) => setGradeId(e.target.value)}
-                className="w-full px-3 py-2 bg-transparent border-b text-sm font-mono"
-                style={{
-                  borderColor: "var(--color-rule)",
-                  borderRadius: "6px 6px 0 0",
-                }}
-              />
-            </div>
-            <div>
-              <label
-                className="block text-xs uppercase tracking-wide mb-1"
-                style={{ color: "var(--color-ink-muted)" }}
-              >
-                描述（可选）
-              </label>
-              <textarea
-                value={description}
-                onChange={(e) => setDescription(e.target.value)}
-                className="w-full px-3 py-2 bg-transparent border-b resize-none"
-                style={{
-                  borderColor: "var(--color-rule)",
-                  borderRadius: "6px 6px 0 0",
-                }}
-                rows={3}
-              />
-            </div>
-            <button
-              type="submit"
-              className="px-4 py-2 text-white text-sm tracking-wide transition-opacity hover:opacity-90"
-              style={{ background: "var(--color-accent)", borderRadius: "6px" }}
-            >
-              创建班级
-            </button>
-          </form>
-        </aside>
+        </div>
+        <div className="rule-thin mb-6" />
 
-        <section className="col-span-8">
-          <div className="flex items-baseline justify-between mb-4">
-            <h2 className="text-xl" style={{ fontFamily: "var(--font-serif)" }}>
-              班级列表
-              <span
-                className="ml-2 text-sm font-sans"
-                style={{ color: "var(--color-ink-muted)" }}
-              >
-                {classes.length} 个
-              </span>
-            </h2>
-            <button
-              onClick={fetchClasses}
-              className="text-xs uppercase tracking-wide hover:opacity-70"
-              style={{ color: "var(--color-accent)" }}
-            >
-              刷新
-            </button>
+        {result.fetching ? (
+          <Loading lines={4} />
+        ) : result.error ? (
+          <div className="mark-left mb-4 py-2 border-l-2 border-danger pl-md">
+            <p className="text-sm px-3 text-danger">
+              加载失败：{result.error.message}
+            </p>
           </div>
-          <div className="rule-thin mb-6" />
-
-          {error && (
-            <div
-              className="mark-left mb-4 py-2"
-              style={{ borderColor: "var(--color-accent)" }}
-            >
-              <p
-                className="text-sm px-3"
-                style={{ color: "var(--color-accent)" }}
+        ) : !result.data?.classes || result.data.classes.length === 0 ? (
+          <Empty title="暂无班级" description="请联系管理员分配班级" />
+        ) : (
+          <ul className="space-y-0">
+            {(result.data.classes as Class[]).map((cls) => (
+              <li
+                key={cls.id}
+                className="py-4 grid grid-cols-12 gap-4 items-baseline border-b border-rule"
               >
-                {error}
-              </p>
-            </div>
-          )}
-
-          {loading ? (
-            <p className="text-sm" style={{ color: "var(--color-ink-muted)" }}>
-              加载中...
-            </p>
-          ) : classes.length === 0 ? (
-            <p
-              className="text-sm italic"
-              style={{ color: "var(--color-ink-muted)" }}
-            >
-              暂无班级，从左侧创建第一个
-            </p>
-          ) : (
-            <ul className="space-y-0">
-              {classes.map((cls) => (
-                <li
-                  key={cls.id}
-                  className="py-4 grid grid-cols-12 gap-4 items-baseline"
-                  style={{ borderBottom: "1px solid var(--color-rule)" }}
-                >
-                  <div className="col-span-7">
-                    <h3
-                      className="text-lg"
-                      style={{
-                        fontFamily: "var(--font-serif)",
-                        color: "var(--color-ink)",
-                      }}
-                    >
-                      {cls.name}
-                    </h3>
-                    {cls.description && (
-                      <p
-                        className="mt-1 text-sm"
-                        style={{ color: "var(--color-ink-muted)" }}
-                      >
-                        {cls.description}
-                      </p>
-                    )}
-                  </div>
-                  <div
-                    className="col-span-3 text-xs font-mono"
-                    style={{ color: "var(--color-ink-muted)" }}
+                <div className="col-span-7">
+                  <h3 className="text-lg font-serif text-ink">{cls.name}</h3>
+                  <p className="mt-1 text-tiny text-ink-muted">
+                    年级：{cls.gradeId}
+                  </p>
+                </div>
+                <div className="col-span-2 text-sm text-ink-muted">
+                  {cls.studentCount} 名学生
+                </div>
+                <div className="col-span-3 text-right flex justify-end gap-4">
+                  <Link
+                    href={`/students?classId=${cls.id}`}
+                    className="text-tiny uppercase tracking-wide text-accent hover:opacity-70"
                   >
-                    {cls.id.slice(0, 8)}...
-                  </div>
-                  <div className="col-span-2 text-right">
-                    <button
-                      onClick={() => handleDelete(cls.id)}
-                      className="text-xs uppercase tracking-wide hover:opacity-70"
-                      style={{ color: "var(--color-ink-muted)" }}
-                    >
-                      删除
-                    </button>
-                  </div>
-                </li>
-              ))}
-            </ul>
-          )}
-        </section>
-      </div>
+                    查看学生
+                  </Link>
+                  <Link
+                    href={`/exams?classId=${cls.id}`}
+                    className="text-tiny uppercase tracking-wide text-ink-muted hover:opacity-70"
+                  >
+                    考试
+                  </Link>
+                  <Link
+                    href={`/homework?classId=${cls.id}`}
+                    className="text-tiny uppercase tracking-wide text-ink-muted hover:opacity-70"
+                  >
+                    作业
+                  </Link>
+                </div>
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
     </div>
   );
 }

apps/teacher-portal/src/app/(app)/dashboard/page.tsx

@@ -1,139 +1,146 @@
 "use client";
 
-import { useEffect, useState } from "react";
-import { getToken, getUser, type UserInfo } from "@/lib/auth";
+/**
+ * Dashboard 页面 - 教师仪表盘
+ *
+ * 数据来源（ARB-001 §1.2）：GraphQL DashboardQuery
+ * - 并行聚合：iam.me + iam.viewports + iam.permissions + classes.byTeacher
+ * - 返回：user + classes + viewports + stats
+ *
+ * 维护者：ai13（teacher-portal）
+ */
 
-interface DashboardData {
-  user: { success: boolean; data?: { user: UserInfo } };
-  classes: { success: boolean; data?: unknown[] };
-}
+import { useQuery } from "urql";
+import Link from "next/link";
+import { Loading, Empty } from "@edu/ui-components";
+import { DashboardQuery } from "@/lib/graphql";
+import type { Class } from "@/lib/graphql";
 
 export default function DashboardPage() {
-  const [data, setData] = useState<DashboardData | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  const [loading, setLoading] = useState(true);
-  const user = getUser();
+  const [result] = useQuery({ query: DashboardQuery });
 
-  useEffect(() => {
-    const token = getToken();
-    if (!token) return;
-    (async () => {
-      try {
-        const res = await fetch("/api/v1/teacher/dashboard", {
-          headers: { Authorization: `Bearer ${token}` },
-        });
-        const json = await res.json();
-        if (json.success) {
-          setData(json.data);
-        } else {
-          setError(json.error?.message || "加载失败");
-        }
-      } catch (e) {
-        setError(e instanceof Error ? e.message : "网络错误");
-      } finally {
-        setLoading(false);
-      }
-    })();
-  }, []);
+  if (result.fetching) {
+    return (
+      <div className="px-10 py-10">
+        <Loading lines={5} />
+      </div>
+    );
+  }
 
-  const classesCount = Array.isArray(data?.classes?.data)
-    ? data!.classes.data.length
-    : 0;
+  if (result.error) {
+    return (
+      <div className="px-10 py-10">
+        <header className="mb-8">
+          <h1 className="text-3xl font-serif text-ink">欢迎</h1>
+        </header>
+        <div className="rule-thin mb-8" />
+        <div className="mark-left py-2 mb-4 border-l-2 border-danger pl-md">
+          <p className="text-sm px-3 text-danger">
+            仪表盘加载失败：{result.error.message}
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  const data = result.data?.dashboard;
+  if (!data) {
+    return (
+      <div className="px-10 py-10">
+        <Empty title="暂无数据" description="仪表盘数据尚未就绪" />
+      </div>
+    );
+  }
+
+  const { user, classes, stats } = data;
 
   return (
     <div className="px-10 py-10">
       <header className="mb-8">
-        <h1
-          className="text-3xl"
-          style={{ fontFamily: "var(--font-serif)", color: "var(--color-ink)" }}
-        >
-          欢迎，{user?.name || "老师"}
-        </h1>
-        <p className="mt-1 text-sm" style={{ color: "var(--color-ink-muted)" }}>
-          {user?.email} · 角色：{user?.roles.join(", ") || "无"} · 数据范围：
-          {user?.dataScope || "-"}
+        <h1 className="text-3xl font-serif text-ink">欢迎，{user.name}</h1>
+        <p className="mt-1 text-sm text-ink-muted">
+          {user.email} · 角色：{user.roles.join(", ") || "无"} · 数据范围：
+          {user.dataScope}
         </p>
       </header>
 
       <div className="rule-thin mb-8" />
 
-      {loading ? (
-        <p className="text-sm" style={{ color: "var(--color-ink-muted)" }}>
-          加载中...
-        </p>
-      ) : error ? (
-        <div
-          className="mark-left py-2 mb-4"
-          style={{ borderColor: "var(--color-accent)" }}
-        >
-          <p className="text-sm px-3" style={{ color: "var(--color-accent)" }}>
-            {error}
+      {/* 统计卡片 */}
+      <section className="grid grid-cols-3 gap-6 mb-10">
+        <div className="p-6 border border-rule rounded-card">
+          <p className="text-tiny uppercase tracking-wide text-ink-muted">
+            班级总数
+          </p>
+          <p className="mt-3 text-4xl font-serif text-ink">{classes.length}</p>
+        </div>
+        <div className="p-6 border border-rule rounded-card">
+          <p className="text-tiny uppercase tracking-wide text-ink-muted">
+            考试总数
+          </p>
+          <p className="mt-3 text-4xl font-serif text-ink">
+            {stats.totalExams}
           </p>
         </div>
-      ) : (
-        <section className="grid grid-cols-3 gap-6">
-          <div
-            className="p-6 border"
-            style={{ borderColor: "var(--color-rule)" }}
+        <div className="p-6 border border-rule rounded-card">
+          <p className="text-tiny uppercase tracking-wide text-ink-muted">
+            待批改
+          </p>
+          <p className="mt-3 text-4xl font-serif text-accent">
+            {stats.pendingGrading}
+          </p>
+        </div>
+      </section>
+
+      {/* 班级快览 */}
+      <section>
+        <div className="flex items-baseline justify-between mb-4">
+          <h2 className="text-xl font-serif text-ink">
+            我的班级
+            <span className="ml-2 text-sm font-sans text-ink-muted">
+              {classes.length} 个
+            </span>
+          </h2>
+          <Link
+            href="/classes"
+            className="text-tiny uppercase tracking-wide text-accent hover:opacity-70"
           >
-            <p
-              className="text-xs uppercase tracking-wide"
-              style={{ color: "var(--color-ink-muted)" }}
-            >
-              班级总数
-            </p>
-            <p
-              className="mt-3 text-4xl"
-              style={{
-                fontFamily: "var(--font-serif)",
-                color: "var(--color-ink)",
-              }}
-            >
-              {classesCount}
-            </p>
-          </div>
-          <div
-            className="p-6 border"
-            style={{ borderColor: "var(--color-rule)" }}
-          >
-            <p
-              className="text-xs uppercase tracking-wide"
-              style={{ color: "var(--color-ink-muted)" }}
-            >
-              权限点
-            </p>
-            <p
-              className="mt-3 text-4xl"
-              style={{
-                fontFamily: "var(--font-serif)",
-                color: "var(--color-ink)",
-              }}
-            >
-              {user?.permissions.length ?? 0}
-            </p>
-          </div>
-          <div
-            className="p-6 border"
-            style={{ borderColor: "var(--color-rule)" }}
-          >
-            <p
-              className="text-xs uppercase tracking-wide"
-              style={{ color: "var(--color-ink-muted)" }}
-            >
-              数据范围
-            </p>
-            <p
-              className="mt-3 text-2xl"
-              style={{
-                fontFamily: "var(--font-serif)",
-                color: "var(--color-ink)",
-              }}
-            >
-              {user?.dataScope || "-"}
-            </p>
-          </div>
-        </section>
-      )}
+            查看全部
+          </Link>
+        </div>
+        <div className="rule-thin mb-6" />
+
+        {classes.length === 0 ? (
+          <Empty title="暂无班级" description="请联系管理员分配班级" />
+        ) : (
+          <ul className="space-y-0">
+            {(classes as Class[]).slice(0, 5).map((cls) => (
+              <li
+                key={cls.id}
+                className="py-4 grid grid-cols-12 gap-4 items-baseline border-b border-rule"
+              >
+                <div className="col-span-8">
+                  <h3 className="text-lg font-serif text-ink">{cls.name}</h3>
+                  <p className="mt-1 text-tiny text-ink-muted">
+                    年级：{cls.gradeId}
+                  </p>
+                </div>
+                <div className="col-span-2 text-sm text-ink-muted">
+                  {cls.studentCount} 名学生
+                </div>
+                <div className="col-span-2 text-right">
+                  <Link
+                    href={`/students?classId=${cls.id}`}
+                    className="text-tiny uppercase tracking-wide text-accent hover:opacity-70"
+                  >
+                    查看学生
+                  </Link>
+                </div>
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
     </div>
   );
 }

apps/teacher-portal/src/app/(app)/exams/page.tsx

@@ -1,179 +1,96 @@
 "use client";
 
-import { useState, useEffect, useCallback } from "react";
-import { getToken } from "@/lib/auth";
+/**
+ * Exams 页面 - 考试管理
+ *
+ * 数据来源（contract.md §2.4）：GraphQL ClassExamsQuery（P3 扩展，MSW mock）
+ * - 通过 URL ?classId=xxx 指定班级
+ * - P2 阶段用 MSW mock 数据，待 teacher-bff P3 启用 core-edu 聚合
+ *
+ * 维护者：ai13（teacher-portal）
+ */
 
-interface ExamItem {
-  id: string;
-  classId: string;
-  title: string;
-  description?: string;
-  examDate: string;
-  duration: string;
-  totalScore: string;
-  status: string;
-  createdBy: string;
-  createdAt: string;
-  updatedAt: string;
-}
+import { useQuery } from "urql";
+import { useSearchParams } from "next/navigation";
+import { Suspense } from "react";
+import { Loading, Empty } from "@edu/ui-components";
+import { ClassExamsQuery, ClassQuery } from "@/lib/graphql";
+import type { ExamItem } from "@/lib/graphql";
 
-interface ApiResponse<T> {
-  success: boolean;
-  data?: T;
-  error?: { code: string; message: string };
-}
+function ExamsContent() {
+  const searchParams = useSearchParams();
+  const classId = searchParams.get("classId") ?? "";
 
-export default function ExamsPage() {
-  const [exams, setExams] = useState<ExamItem[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [classId, setClassId] = useState(
-    "00000000-0000-0000-0000-000000000001",
-  );
-  const [error, setError] = useState<string | null>(null);
+  const [classResult] = useQuery({
+    query: ClassQuery,
+    variables: { id: classId },
+    pause: !classId,
+  });
 
-  const authHeaders = (): Record<string, string> => {
-    const token = getToken();
-    return token ? { Authorization: `Bearer ${token}` } : {};
-  };
+  const [examsResult] = useQuery({
+    query: ClassExamsQuery,
+    variables: { classId },
+    pause: !classId,
+  });
 
-  const fetchExams = useCallback(async () => {
-    if (!classId.trim()) return;
-    setLoading(true);
-    setError(null);
-    try {
-      const res = await fetch(
-        `/api/v1/teacher/classes/${encodeURIComponent(classId)}/exams`,
-        { headers: authHeaders() },
-      );
-      const json: ApiResponse<ExamItem[]> = await res.json();
-      if (json.success && json.data) {
-        setExams(json.data);
-      } else {
-        setError(json.error?.message || "Failed to load");
-      }
-    } catch (e) {
-      setError(e instanceof Error ? e.message : "Network error");
-    } finally {
-      setLoading(false);
-    }
-  }, [classId]);
+  if (!classId) {
+    return (
+      <div className="px-10 py-10">
+        <Empty title="未指定班级" description="请从班级列表进入查看考试" />
+      </div>
+    );
+  }
 
-  useEffect(() => {
-    fetchExams();
-  }, [fetchExams]);
+  const cls = classResult.data?.class;
+  const exams = examsResult.data?.classExams ?? [];
 
   return (
     <div className="px-10 py-10">
       <header className="mb-8">
-        <h1
-          className="text-3xl"
-          style={{
-            fontFamily: "var(--font-serif)",
-            color: "var(--color-ink)",
-          }}
-        >
-          考试管理
+        <h1 className="text-3xl font-serif text-ink">
+          {cls ? `${cls.name} - 考试管理` : "考试管理"}
         </h1>
-        <p className="mt-1 text-sm" style={{ color: "var(--color-ink-muted)" }}>
-          core-edu 域 · BFF 聚合查询
+        <p className="mt-1 text-sm text-ink-muted">
+          GraphQL ClassExamsQuery · core-edu 域（P3 扩展，MSW mock）
         </p>
       </header>
 
       <div className="rule-thin mb-8" />
 
-      <div className="mb-6 flex items-baseline gap-3">
-        <label
-          className="text-xs uppercase tracking-wide"
-          style={{ color: "var(--color-ink-muted)" }}
-        >
-          班级 ID
-        </label>
-        <input
-          type="text"
-          value={classId}
-          onChange={(e) => setClassId(e.target.value)}
-          className="flex-1 max-w-md px-3 py-2 bg-transparent border-b text-sm font-mono"
-          style={{ borderColor: "var(--color-rule)" }}
-          placeholder="输入班级 UUID"
-        />
-        <button
-          onClick={fetchExams}
-          className="text-xs uppercase tracking-wide hover:opacity-70"
-          style={{ color: "var(--color-accent)" }}
-        >
-          查询
-        </button>
-      </div>
-
-      {error && (
-        <div
-          className="mark-left mb-4 py-2"
-          style={{ borderColor: "var(--color-accent)" }}
-        >
-          <p className="text-sm px-3" style={{ color: "var(--color-accent)" }}>
-            {error}
+      {examsResult.fetching ? (
+        <Loading lines={4} />
+      ) : examsResult.error ? (
+        <div className="mark-left mb-4 py-2 border-l-2 border-danger pl-md">
+          <p className="text-sm px-3 text-danger">
+            加载失败：{examsResult.error.message}
           </p>
         </div>
-      )}
-
-      {loading ? (
-        <p className="text-sm" style={{ color: "var(--color-ink-muted)" }}>
-          加载中...
-        </p>
       ) : exams.length === 0 ? (
-        <p
-          className="text-sm italic"
-          style={{ color: "var(--color-ink-muted)" }}
-        >
-          该班级下暂无考试
-        </p>
+        <Empty title="暂无考试" description="该班级尚未创建考试" />
       ) : (
         <ul className="space-y-0">
-          {exams.map((exam) => (
+          {(exams as ExamItem[]).map((exam) => (
             <li
               key={exam.id}
-              className="py-4 grid grid-cols-12 gap-4 items-baseline"
-              style={{ borderBottom: "1px solid var(--color-rule)" }}
+              className="py-4 grid grid-cols-12 gap-4 items-baseline border-b border-rule"
             >
               <div className="col-span-7">
-                <h3
-                  className="text-lg"
-                  style={{
-                    fontFamily: "var(--font-serif)",
-                    color: "var(--color-ink)",
-                  }}
-                >
-                  {exam.title}
-                </h3>
+                <h3 className="text-lg font-serif text-ink">{exam.title}</h3>
                 {exam.description && (
-                  <p
-                    className="mt-1 text-sm"
-                    style={{ color: "var(--color-ink-muted)" }}
-                  >
+                  <p className="mt-1 text-sm text-ink-muted">
                     {exam.description}
                   </p>
                 )}
-                <p
-                  className="mt-1 text-xs"
-                  style={{ color: "var(--color-ink-muted)" }}
-                >
+                <p className="mt-1 text-tiny text-ink-muted">
                   考试时间: {new Date(exam.examDate).toLocaleString("zh-CN")}
-                  {" · "}
-                  时长 {exam.duration} 分钟
-                  {" · "}
-                  满分 {exam.totalScore}
+                  {" · "}时长 {exam.duration} 分钟
+                  {" · "}满分 {exam.totalScore}
                 </p>
               </div>
-              <div
-                className="col-span-3 text-xs"
-                style={{ color: "var(--color-ink-muted)" }}
-              >
+              <div className="col-span-3 text-tiny text-ink-muted">
                 状态: {exam.status}
               </div>
-              <div
-                className="col-span-2 text-right text-xs font-mono"
-                style={{ color: "var(--color-ink-muted)" }}
-              >
+              <div className="col-span-2 text-right text-tiny font-mono text-ink-muted">
                 {exam.id.slice(0, 8)}...
               </div>
             </li>
@@ -183,3 +100,17 @@ export default function ExamsPage() {
     </div>
   );
 }
+
+export default function ExamsPage() {
+  return (
+    <Suspense
+      fallback={
+        <div className="px-10 py-10">
+          <Loading lines={3} />
+        </div>
+      }
+    >
+      <ExamsContent />
+    </Suspense>
+  );
+}

apps/teacher-portal/src/app/(app)/grades/page.tsx

@@ -1,174 +1,96 @@
 "use client";
 
-import { useState, useEffect, useCallback } from "react";
-import { getToken } from "@/lib/auth";
+/**
+ * Grades 页面 - 成绩查询
+ *
+ * 数据来源（contract.md §2.4）：GraphQL ExamGradesQuery（P3 扩展，MSW mock）
+ * - 通过 URL ?examId=xxx 指定考试
+ * - P2 阶段用 MSW mock 数据，待 teacher-bff P3 启用 core-edu 聚合
+ *
+ * 维护者：ai13（teacher-portal）
+ */
 
-interface GradeItem {
-  id: string;
-  studentId: string;
-  examId: string | null;
-  homeworkId: string | null;
-  score: string;
-  feedback?: string;
-  gradedBy: string;
-  createdAt: string;
-  updatedAt: string;
-}
+import { useState, Suspense } from "react";
+import { useQuery } from "urql";
+import { useSearchParams } from "next/navigation";
+import { Loading, Empty } from "@edu/ui-components";
+import { ExamGradesQuery } from "@/lib/graphql";
+import type { GradeItem } from "@/lib/graphql";
 
-interface ApiResponse<T> {
-  success: boolean;
-  data?: T;
-  error?: { code: string; message: string };
-}
+function GradesContent() {
+  const searchParams = useSearchParams();
+  const initialExamId = searchParams.get("examId") ?? "";
+  const [examId, setExamId] = useState(initialExamId);
 
-export default function GradesPage() {
-  const [items, setItems] = useState<GradeItem[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [examId, setExamId] = useState("");
-  const [error, setError] = useState<string | null>(null);
+  const [gradesResult] = useQuery({
+    query: ExamGradesQuery,
+    variables: { examId },
+    pause: !examId,
+  });
 
-  const authHeaders = (): Record<string, string> => {
-    const token = getToken();
-    return token ? { Authorization: `Bearer ${token}` } : {};
-  };
-
-  const fetchGrades = useCallback(async () => {
-    if (!examId.trim()) return;
-    setLoading(true);
-    setError(null);
-    try {
-      const res = await fetch(
-        `/api/v1/teacher/exams/${encodeURIComponent(examId)}/grades`,
-        { headers: authHeaders() },
-      );
-      const json: ApiResponse<GradeItem[]> = await res.json();
-      if (json.success && json.data) {
-        setItems(json.data);
-      } else {
-        setError(json.error?.message || "Failed to load");
-      }
-    } catch (e) {
-      setError(e instanceof Error ? e.message : "Network error");
-    } finally {
-      setLoading(false);
-    }
-  }, [examId]);
-
-  useEffect(() => {
-    fetchGrades();
-  }, [fetchGrades]);
+  const grades = gradesResult.data?.examGrades ?? [];
 
   return (
     <div className="px-10 py-10">
       <header className="mb-8">
-        <h1
-          className="text-3xl"
-          style={{
-            fontFamily: "var(--font-serif)",
-            color: "var(--color-ink)",
-          }}
-        >
-          成绩查询
-        </h1>
-        <p className="mt-1 text-sm" style={{ color: "var(--color-ink-muted)" }}>
-          core-edu 域 · BFF 聚合查询
+        <h1 className="text-3xl font-serif text-ink">成绩查询</h1>
+        <p className="mt-1 text-sm text-ink-muted">
+          GraphQL ExamGradesQuery · core-edu 域（P3 扩展，MSW mock）
         </p>
       </header>
 
       <div className="rule-thin mb-8" />
 
       <div className="mb-6 flex items-baseline gap-3">
-        <label
-          className="text-xs uppercase tracking-wide"
-          style={{ color: "var(--color-ink-muted)" }}
-        >
+        <label className="text-tiny uppercase tracking-wide text-ink-muted">
           考试 ID
         </label>
         <input
           type="text"
           value={examId}
           onChange={(e) => setExamId(e.target.value)}
-          className="flex-1 max-w-md px-3 py-2 bg-transparent border-b text-sm font-mono"
-          style={{ borderColor: "var(--color-rule)" }}
+          className="flex-1 max-w-md px-3 py-2 bg-transparent border-b border-rule text-sm font-mono"
           placeholder="输入考试 UUID"
         />
-        <button
-          onClick={fetchGrades}
-          className="text-xs uppercase tracking-wide hover:opacity-70"
-          style={{ color: "var(--color-accent)" }}
-        >
-          查询
-        </button>
       </div>
 
-      {error && (
-        <div
-          className="mark-left mb-4 py-2"
-          style={{ borderColor: "var(--color-accent)" }}
-        >
-          <p className="text-sm px-3" style={{ color: "var(--color-accent)" }}>
-            {error}
+      {gradesResult.fetching ? (
+        <Loading lines={4} />
+      ) : gradesResult.error ? (
+        <div className="mark-left mb-4 py-2 border-l-2 border-danger pl-md">
+          <p className="text-sm px-3 text-danger">
+            加载失败：{gradesResult.error.message}
           </p>
         </div>
-      )}
-
-      {loading ? (
-        <p className="text-sm" style={{ color: "var(--color-ink-muted)" }}>
-          加载中...
-        </p>
-      ) : items.length === 0 ? (
-        <p
-          className="text-sm italic"
-          style={{ color: "var(--color-ink-muted)" }}
-        >
-          {examId.trim() ? "该考试下暂无成绩" : "请输入考试 ID 查询成绩"}
-        </p>
+      ) : !examId ? (
+        <Empty title="请输入考试 ID" description="输入考试 UUID 后查询成绩" />
+      ) : grades.length === 0 ? (
+        <Empty title="暂无成绩" description="该考试尚未录入成绩" />
       ) : (
         <ul className="space-y-0">
-          {items.map((g) => (
+          {(grades as GradeItem[]).map((g) => (
             <li
               key={g.id}
-              className="py-4 grid grid-cols-12 gap-4 items-baseline"
-              style={{ borderBottom: "1px solid var(--color-rule)" }}
+              className="py-4 grid grid-cols-12 gap-4 items-baseline border-b border-rule"
             >
               <div className="col-span-6">
-                <h3
-                  className="text-lg"
-                  style={{
-                    fontFamily: "var(--font-serif)",
-                    color: "var(--color-ink)",
-                  }}
-                >
-                  学生: {g.studentId}
-                </h3>
+                <h3 className="text-lg font-serif text-ink">{g.studentName}</h3>
+                <p className="mt-1 text-tiny text-ink-muted">
+                  学生 ID: {g.studentId}
+                </p>
                 {g.feedback && (
-                  <p
-                    className="mt-1 text-sm"
-                    style={{ color: "var(--color-ink-muted)" }}
-                  >
+                  <p className="mt-1 text-sm text-ink-muted">
                     反馈: {g.feedback}
                   </p>
                 )}
               </div>
-              <div
-                className="col-span-2 text-2xl"
-                style={{
-                  fontFamily: "var(--font-serif)",
-                  color: "var(--color-accent)",
-                }}
-              >
+              <div className="col-span-2 text-2xl font-serif text-accent">
                 {g.score}
               </div>
-              <div
-                className="col-span-2 text-xs"
-                style={{ color: "var(--color-ink-muted)" }}
-              >
-                评分人: {g.gradedBy}
+              <div className="col-span-2 text-tiny text-ink-muted">
+                {g.examId ? `考试: ${g.examId.slice(0, 8)}...` : "作业成绩"}
               </div>
-              <div
-                className="col-span-2 text-right text-xs font-mono"
-                style={{ color: "var(--color-ink-muted)" }}
-              >
+              <div className="col-span-2 text-right text-tiny font-mono text-ink-muted">
                 {g.id.slice(0, 8)}...
               </div>
             </li>
@@ -178,3 +100,17 @@ export default function GradesPage() {
     </div>
   );
 }
+
+export default function GradesPage() {
+  return (
+    <Suspense
+      fallback={
+        <div className="px-10 py-10">
+          <Loading lines={3} />
+        </div>
+      }
+    >
+      <GradesContent />
+    </Suspense>
+  );
+}

apps/teacher-portal/src/app/(app)/homework/page.tsx

@@ -1,173 +1,94 @@
 "use client";
 
-import { useState, useEffect, useCallback } from "react";
-import { getToken } from "@/lib/auth";
+/**
+ * Homework 页面 - 作业管理
+ *
+ * 数据来源（contract.md §2.4）：GraphQL ClassHomeworkQuery（P3 扩展，MSW mock）
+ * - 通过 URL ?classId=xxx 指定班级
+ * - P2 阶段用 MSW mock 数据，待 teacher-bff P3 启用 core-edu 聚合
+ *
+ * 维护者：ai13（teacher-portal）
+ */
 
-interface HomeworkItem {
-  id: string;
-  classId: string;
-  title: string;
-  description?: string;
-  dueDate: string;
-  status: string;
-  createdBy: string;
-  createdAt: string;
-  updatedAt: string;
-}
+import { useQuery } from "urql";
+import { useSearchParams } from "next/navigation";
+import { Suspense } from "react";
+import { Loading, Empty } from "@edu/ui-components";
+import { ClassHomeworkQuery, ClassQuery } from "@/lib/graphql";
+import type { HomeworkItem } from "@/lib/graphql";
 
-interface ApiResponse<T> {
-  success: boolean;
-  data?: T;
-  error?: { code: string; message: string };
-}
+function HomeworkContent() {
+  const searchParams = useSearchParams();
+  const classId = searchParams.get("classId") ?? "";
 
-export default function HomeworkPage() {
-  const [items, setItems] = useState<HomeworkItem[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [classId, setClassId] = useState(
-    "00000000-0000-0000-0000-000000000001",
-  );
-  const [error, setError] = useState<string | null>(null);
+  const [classResult] = useQuery({
+    query: ClassQuery,
+    variables: { id: classId },
+    pause: !classId,
+  });
 
-  const authHeaders = (): Record<string, string> => {
-    const token = getToken();
-    return token ? { Authorization: `Bearer ${token}` } : {};
-  };
+  const [homeworkResult] = useQuery({
+    query: ClassHomeworkQuery,
+    variables: { classId },
+    pause: !classId,
+  });
 
-  const fetchHomework = useCallback(async () => {
-    if (!classId.trim()) return;
-    setLoading(true);
-    setError(null);
-    try {
-      const res = await fetch(
-        `/api/v1/teacher/classes/${encodeURIComponent(classId)}/homework`,
-        { headers: authHeaders() },
-      );
-      const json: ApiResponse<HomeworkItem[]> = await res.json();
-      if (json.success && json.data) {
-        setItems(json.data);
-      } else {
-        setError(json.error?.message || "Failed to load");
-      }
-    } catch (e) {
-      setError(e instanceof Error ? e.message : "Network error");
-    } finally {
-      setLoading(false);
-    }
-  }, [classId]);
+  if (!classId) {
+    return (
+      <div className="px-10 py-10">
+        <Empty title="未指定班级" description="请从班级列表进入查看作业" />
+      </div>
+    );
+  }
 
-  useEffect(() => {
-    fetchHomework();
-  }, [fetchHomework]);
+  const cls = classResult.data?.class;
+  const items = homeworkResult.data?.classHomework ?? [];
 
   return (
     <div className="px-10 py-10">
       <header className="mb-8">
-        <h1
-          className="text-3xl"
-          style={{
-            fontFamily: "var(--font-serif)",
-            color: "var(--color-ink)",
-          }}
-        >
-          作业管理
+        <h1 className="text-3xl font-serif text-ink">
+          {cls ? `${cls.name} - 作业管理` : "作业管理"}
         </h1>
-        <p className="mt-1 text-sm" style={{ color: "var(--color-ink-muted)" }}>
-          core-edu 域 · BFF 聚合查询
+        <p className="mt-1 text-sm text-ink-muted">
+          GraphQL ClassHomeworkQuery · core-edu 域（P3 扩展，MSW mock）
         </p>
       </header>
 
       <div className="rule-thin mb-8" />
 
-      <div className="mb-6 flex items-baseline gap-3">
-        <label
-          className="text-xs uppercase tracking-wide"
-          style={{ color: "var(--color-ink-muted)" }}
-        >
-          班级 ID
-        </label>
-        <input
-          type="text"
-          value={classId}
-          onChange={(e) => setClassId(e.target.value)}
-          className="flex-1 max-w-md px-3 py-2 bg-transparent border-b text-sm font-mono"
-          style={{ borderColor: "var(--color-rule)" }}
-          placeholder="输入班级 UUID"
-        />
-        <button
-          onClick={fetchHomework}
-          className="text-xs uppercase tracking-wide hover:opacity-70"
-          style={{ color: "var(--color-accent)" }}
-        >
-          查询
-        </button>
-      </div>
-
-      {error && (
-        <div
-          className="mark-left mb-4 py-2"
-          style={{ borderColor: "var(--color-accent)" }}
-        >
-          <p className="text-sm px-3" style={{ color: "var(--color-accent)" }}>
-            {error}
+      {homeworkResult.fetching ? (
+        <Loading lines={4} />
+      ) : homeworkResult.error ? (
+        <div className="mark-left mb-4 py-2 border-l-2 border-danger pl-md">
+          <p className="text-sm px-3 text-danger">
+            加载失败：{homeworkResult.error.message}
           </p>
         </div>
-      )}
-
-      {loading ? (
-        <p className="text-sm" style={{ color: "var(--color-ink-muted)" }}>
-          加载中...
-        </p>
       ) : items.length === 0 ? (
-        <p
-          className="text-sm italic"
-          style={{ color: "var(--color-ink-muted)" }}
-        >
-          该班级下暂无作业
-        </p>
+        <Empty title="暂无作业" description="该班级尚未布置作业" />
       ) : (
         <ul className="space-y-0">
-          {items.map((hw) => (
+          {(items as HomeworkItem[]).map((hw) => (
             <li
               key={hw.id}
-              className="py-4 grid grid-cols-12 gap-4 items-baseline"
-              style={{ borderBottom: "1px solid var(--color-rule)" }}
+              className="py-4 grid grid-cols-12 gap-4 items-baseline border-b border-rule"
             >
               <div className="col-span-7">
-                <h3
-                  className="text-lg"
-                  style={{
-                    fontFamily: "var(--font-serif)",
-                    color: "var(--color-ink)",
-                  }}
-                >
-                  {hw.title}
-                </h3>
+                <h3 className="text-lg font-serif text-ink">{hw.title}</h3>
                 {hw.description && (
-                  <p
-                    className="mt-1 text-sm"
-                    style={{ color: "var(--color-ink-muted)" }}
-                  >
+                  <p className="mt-1 text-sm text-ink-muted">
                     {hw.description}
                   </p>
                 )}
-                <p
-                  className="mt-1 text-xs"
-                  style={{ color: "var(--color-ink-muted)" }}
-                >
+                <p className="mt-1 text-tiny text-ink-muted">
                   截止: {new Date(hw.dueDate).toLocaleString("zh-CN")}
                 </p>
               </div>
-              <div
-                className="col-span-3 text-xs"
-                style={{ color: "var(--color-ink-muted)" }}
-              >
+              <div className="col-span-3 text-tiny text-ink-muted">
                 状态: {hw.status}
               </div>
-              <div
-                className="col-span-2 text-right text-xs font-mono"
-                style={{ color: "var(--color-ink-muted)" }}
-              >
+              <div className="col-span-2 text-right text-tiny font-mono text-ink-muted">
                 {hw.id.slice(0, 8)}...
               </div>
             </li>
@@ -177,3 +98,17 @@ export default function HomeworkPage() {
     </div>
   );
 }
+
+export default function HomeworkPage() {
+  return (
+    <Suspense
+      fallback={
+        <div className="px-10 py-10">
+          <Loading lines={3} />
+        </div>
+      }
+    >
+      <HomeworkContent />
+    </Suspense>
+  );
+}

apps/teacher-portal/src/app/(app)/settings/page.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+/**
+ * Settings 页面 - 个人设置
+ *
+ * 数据来源（ARB-001 §1.2）：GraphQL MeQuery（只读展示）
+ * - P2 阶段仅展示当前用户信息（P2 纯读，无 Mutation）
+ * - P3+ 启用 UpdateUserMutation 后开启编辑功能
+ *
+ * 维护者：ai13（teacher-portal）
+ */
+
+import { useQuery } from "urql";
+import { Loading } from "@edu/ui-components";
+import { MeQuery } from "@/lib/graphql";
+
+export default function SettingsPage() {
+  const [result] = useQuery({ query: MeQuery });
+
+  return (
+    <div className="px-10 py-10">
+      <header className="mb-8">
+        <h1 className="text-3xl font-serif text-ink">个人设置</h1>
+        <p className="mt-1 text-sm text-ink-muted">
+          GraphQL MeQuery · P2 只读展示（P3 启用编辑）
+        </p>
+      </header>
+
+      <div className="rule-thin mb-8" />
+
+      {result.fetching ? (
+        <Loading lines={4} />
+      ) : result.error ? (
+        <div className="mark-left mb-4 py-2 border-l-2 border-danger pl-md">
+          <p className="text-sm px-3 text-danger">
+            加载失败：{result.error.message}
+          </p>
+        </div>
+      ) : !result.data?.me ? (
+        <p className="text-sm italic text-ink-muted">暂无用户信息</p>
+      ) : (
+        <section className="max-w-2xl">
+          <div className="mb-6">
+            <h2 className="text-xl font-serif text-ink mb-2">基本信息</h2>
+            <div className="rule-thin mb-4" />
+            <dl className="space-y-4">
+              <div className="grid grid-cols-3 gap-4 items-baseline">
+                <dt className="text-tiny uppercase tracking-wide text-ink-muted">
+                  用户 ID
+                </dt>
+                <dd className="col-span-2 text-sm font-mono text-ink">
+                  {result.data.me.id}
+                </dd>
+              </div>
+              <div className="grid grid-cols-3 gap-4 items-baseline">
+                <dt className="text-tiny uppercase tracking-wide text-ink-muted">
+                  姓名
+                </dt>
+                <dd className="col-span-2 text-sm text-ink">
+                  {result.data.me.name}
+                </dd>
+              </div>
+              <div className="grid grid-cols-3 gap-4 items-baseline">
+                <dt className="text-tiny uppercase tracking-wide text-ink-muted">
+                  邮箱
+                </dt>
+                <dd className="col-span-2 text-sm text-ink">
+                  {result.data.me.email}
+                </dd>
+              </div>
+              <div className="grid grid-cols-3 gap-4 items-baseline">
+                <dt className="text-tiny uppercase tracking-wide text-ink-muted">
+                  角色
+                </dt>
+                <dd className="col-span-2 text-sm text-ink">
+                  {result.data.me.roles.join(", ") || "无角色"}
+                </dd>
+              </div>
+              <div className="grid grid-cols-3 gap-4 items-baseline">
+                <dt className="text-tiny uppercase tracking-wide text-ink-muted">
+                  数据范围
+                </dt>
+                <dd className="col-span-2 text-sm text-ink">
+                  {result.data.me.dataScope}
+                </dd>
+              </div>
+            </dl>
+          </div>
+
+          <div className="mt-8 p-4 border border-rule rounded-card bg-subtle">
+            <p className="text-sm text-ink-muted">
+              P2 阶段为只读模式，编辑功能（updateUser Mutation）将在 P3 启用。
+            </p>
+          </div>
+        </section>
+      )}
+    </div>
+  );
+}

apps/teacher-portal/src/app/(app)/students/page.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+/**
+ * Students 页面 - 班级学生名单
+ *
+ * 数据来源（contract.md §2.4）：GraphQL ClassStudentsQuery（P3 扩展，MSW mock）
+ * - 通过 URL ?classId=xxx 指定班级
+ * - P2 阶段用 MSW mock 数据，待 teacher-bff P3 启用 iam 聚合
+ *
+ * 维护者：ai13（teacher-portal）
+ */
+
+import { useQuery } from "urql";
+import { useSearchParams } from "next/navigation";
+import { Suspense } from "react";
+import { Loading, Empty } from "@edu/ui-components";
+import { ClassStudentsQuery, ClassQuery } from "@/lib/graphql";
+import type { Student } from "@/lib/graphql";
+
+function StudentsContent() {
+  const searchParams = useSearchParams();
+  const classId = searchParams.get("classId") ?? "";
+
+  // 班级详情（用于显示班级名称）
+  const [classResult] = useQuery({
+    query: ClassQuery,
+    variables: { id: classId },
+    pause: !classId,
+  });
+
+  // 学生名单
+  const [studentsResult] = useQuery({
+    query: ClassStudentsQuery,
+    variables: { classId },
+    pause: !classId,
+  });
+
+  if (!classId) {
+    return (
+      <div className="px-10 py-10">
+        <Empty title="未指定班级" description="请从班级列表进入查看学生名单" />
+      </div>
+    );
+  }
+
+  const cls = classResult.data?.class;
+  const students = studentsResult.data?.classStudents ?? [];
+
+  return (
+    <div className="px-10 py-10">
+      <header className="mb-8">
+        <h1 className="text-3xl font-serif text-ink">
+          {cls ? `${cls.name} - 学生名单` : "学生名单"}
+        </h1>
+        <p className="mt-1 text-sm text-ink-muted">
+          GraphQL ClassStudentsQuery · iam 数据聚合（P3 扩展，MSW mock）
+        </p>
+      </header>
+
+      <div className="rule-thin mb-8" />
+
+      {studentsResult.fetching ? (
+        <Loading lines={6} />
+      ) : studentsResult.error ? (
+        <div className="mark-left mb-4 py-2 border-l-2 border-danger pl-md">
+          <p className="text-sm px-3 text-danger">
+            加载失败：{studentsResult.error.message}
+          </p>
+        </div>
+      ) : students.length === 0 ? (
+        <Empty title="暂无学生" description="该班级尚未录入学生信息" />
+      ) : (
+        <ul className="space-y-0">
+          {(students as Student[]).map((s) => (
+            <li
+              key={s.id}
+              className="py-4 grid grid-cols-12 gap-4 items-center border-b border-rule"
+            >
+              <div className="col-span-5">
+                <h3 className="text-lg font-serif text-ink">{s.name}</h3>
+                <p className="mt-1 text-tiny text-ink-muted">{s.email}</p>
+              </div>
+              <div className="col-span-5 text-sm text-ink-muted">
+                ID: {s.id}
+              </div>
+              <div className="col-span-2 text-right text-tiny font-mono text-ink-muted">
+                {s.id.slice(0, 8)}...
+              </div>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+export default function StudentsPage() {
+  return (
+    <Suspense
+      fallback={
+        <div className="px-10 py-10">
+          <Loading lines={3} />
+        </div>
+      }
+    >
+      <StudentsContent />
+    </Suspense>
+  );
+}

apps/teacher-portal/src/app/api/health/route.ts

@@ -0,0 +1,21 @@
+/**
+ * Liveness 健康检查 - /api/health
+ *
+ * 用途：k8s livenessProbe，判断进程是否存活。
+ * 不检查依赖，仅返回进程状态。
+ *
+ * 维护者：ai13（teacher-portal）
+ * 关联：project_rules §12 可观测性规范
+ */
+
+import { NextResponse } from "next/server";
+
+export const dynamic = "force-dynamic";
+
+export function GET(): NextResponse {
+  return NextResponse.json({
+    status: "ok",
+    service: "teacher-portal",
+    timestamp: new Date().toISOString(),
+  });
+}

apps/teacher-portal/src/app/api/ready/route.ts

@@ -0,0 +1,28 @@
+/**
+ * Readiness 健康检查 - /api/ready
+ *
+ * 用途：k8s readinessProbe，判断是否准备好接收流量。
+ * P2 阶段：teacher-portal 是纯前端，无外部依赖（GraphQL 走客户端），
+ * readiness 检查仅返回进程状态。
+ *
+ * P3+ 扩展：当接入 MF Remote 时，可增加 Remote 可达性检查。
+ *
+ * 维护者：ai13（teacher-portal）
+ * 关联：project_rules §12 可观测性规范
+ */
+
+import { NextResponse } from "next/server";
+
+export const dynamic = "force-dynamic";
+
+export function GET(): NextResponse {
+  return NextResponse.json({
+    status: "ok",
+    service: "teacher-portal",
+    timestamp: new Date().toISOString(),
+    checks: {
+      process: true,
+      // P3+ 扩展：mfRemotes / graphqlEndpoint 等
+    },
+  });
+}

apps/teacher-portal/src/app/globals.css

@@ -1,43 +1,58 @@
+/**
+ * teacher-portal 全局样式
+ *
+ * 引入 @edu/ui-tokens 三层设计令牌（primitive → semantic → tailwind-theme）
+ * 维护者：ai13（teacher-portal）
+ * 关联：project_rules §3.10、02-architecture-design.md §9
+ *
+ * 禁止规则（ESLint + project_rules §3.10）：
+ * - 禁止 #hex 字面量（用 hsl(var(--*)) 或 Tailwind bg-* 类）
+ * - 禁止 'Inter'/'Fraunces'/'JetBrains Mono' 字面量（用 var(--font-family-*))
+ * - 禁止 font-size: Npx（用 var(--font-size-*) 或 Tailwind text-* 类）
+ * - 禁止 Tailwind 任意值 w-[Npx]（用 --space-* 或默认阶梯）
+ */
+
+@import "@edu/ui-tokens/all.css";
+
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
 
-:root {
-  --bg-paper: hsl(40, 20%, 98%);
-  --color-ink: hsl(25, 3%, 15%);
-  --color-ink-muted: hsl(30, 5%, 45%);
-  --color-accent: hsl(220, 60%, 35%);
-  --color-rule: hsl(30, 10%, 90%);
-  --font-serif: 'Fraunces', Georgia, serif;
-  --font-sans: 'Inter', system-ui, sans-serif;
-  --font-mono: 'JetBrains Mono', monospace;
+@layer base {
+  html,
+  body {
+    background: var(--bg-paper);
+    color: var(--color-ink);
+    font-family: var(--font-family-sans);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    font-family: var(--font-family-serif);
+    font-weight: var(--font-weight-semibold);
+    letter-spacing: var(--letter-spacing-tight);
+  }
 }
 
-html, body {
-  background: var(--bg-paper);
-  color: var(--color-ink);
-  font-family: var(--font-sans);
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-}
+@layer components {
+  /* 纸感分隔线 */
+  .rule {
+    border-top: 1px solid var(--color-rule);
+  }
 
-h1, h2, h3, h4, h5, h6 {
-  font-family: var(--font-serif);
-  font-weight: 600;
-  letter-spacing: -0.01em;
-}
+  .rule-thin {
+    border-top: 2px solid var(--color-rule);
+  }
 
-/* 纸感分隔线 */
-.rule {
-  border-top: 1px solid var(--color-rule);
-}
-
-.rule-thin {
-  border-top: 2px solid var(--color-rule);
-}
-
-/* 左侧竖线标记（节点展开样式）*/
-.mark-left {
-  border-left: 2px solid var(--color-rule);
-  padding-left: 12px;
+  /* 左侧竖线标记（节点展开样式） */
+  .mark-left {
+    border-left: 2px solid var(--color-rule);
+    padding-left: var(--space-md);
+  }
 }

apps/teacher-portal/src/app/layout.tsx

@@ -1,14 +1,40 @@
-import './globals.css';
-import type { Metadata } from 'next';
-import { Inter, Fraunces, JetBrains_Mono } from 'next/font/google';
+import "./globals.css";
+import type { Metadata } from "next";
+import { Inter, Fraunces, JetBrains_Mono } from "next/font/google";
+import { GraphQLProvider } from "./providers";
+import { ErrorBoundary } from "@edu/ui-components";
 
-const inter = Inter({ subsets: ['latin'], variable: '--font-inter' });
-const fraunces = Fraunces({ subsets: ['latin'], variable: '--font-fraunces' });
-const mono = JetBrains_Mono({ subsets: ['latin'], variable: '--font-mono' });
+/**
+ * 字体加载（next/font/google self-host）
+ *
+ * 通过 CSS 变量暴露字体族，业务代码用 var(--font-family-sans/serif/mono)
+ * 禁止字体名字面量（project_rules §3.10）
+ *
+ * 03-long-term-architecture.md §3.5 字体加载策略：
+ * - font-display: swap（FOUT，优先文本可见性）
+ * - 首屏字体 preload，次屏 lazy
+ */
+const inter = Inter({
+  subsets: ["latin"],
+  variable: "--font-inter",
+  display: "swap",
+});
+
+const fraunces = Fraunces({
+  subsets: ["latin"],
+  variable: "--font-fraunces",
+  display: "swap",
+});
+
+const mono = JetBrains_Mono({
+  subsets: ["latin"],
+  variable: "--font-jetbrains-mono",
+  display: "swap",
+});
 
 export const metadata: Metadata = {
-  title: 'Edu Teacher Portal',
-  description: 'K12 智慧教务平台 - 教师端',
+  title: "Edu Teacher Portal",
+  description: "K12 智慧教务平台 - 教师端",
 };
 
 export default function RootLayout({
@@ -17,8 +43,15 @@ export default function RootLayout({
   children: React.ReactNode;
 }) {
   return (
-    <html lang="zh-CN" className={`${inter.variable} ${fraunces.variable} ${mono.variable}`}>
-      <body>{children}</body>
+    <html
+      lang="zh-CN"
+      className={`${inter.variable} ${fraunces.variable} ${mono.variable}`}
+    >
+      <body>
+        <ErrorBoundary>
+          <GraphQLProvider>{children}</GraphQLProvider>
+        </ErrorBoundary>
+      </body>
     </html>
   );
 }

apps/teacher-portal/src/app/providers.tsx

@@ -0,0 +1,61 @@
+"use client";
+
+/**
+ * GraphQLProvider - urql client 单例 Provider
+ *
+ * 总裁裁决 §2.17 方案 A：Shell（teacher-portal）暴露 GraphQLProvider，
+ * Remote（student/parent/admin-portal）复用同一 client 单例。
+ *
+ * ARB-002 §2.2：通过 MF exposes './GraphQLProvider' 暴露给 Remote。
+ *
+ * MSW 启用：NEXT_PUBLIC_API_MOCKING=enabled 时在客户端注册 Service Worker
+ *
+ * 维护者：ai13（teacher-portal）
+ */
+
+import { useEffect, useMemo, useState } from "react";
+import { Provider } from "urql";
+import type { ReactNode } from "react";
+import { GraphQLClientContext } from "@edu/hooks";
+import { createGraphQLClient } from "@/lib/graphql";
+import { initMocks } from "@/mocks";
+
+export interface GraphQLProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * GraphQLProvider
+ *
+ * 初始化 urql client 单例，通过 React Context 注入给所有子组件 + Remote。
+ * MF shared singleton 配置确保 Remote 复用同一 client 实例（ARB-002 §2.2）。
+ *
+ * MSW 初始化在客户端渲染前异步完成，避免请求未拦截。
+ */
+export function GraphQLProvider({ children }: GraphQLProviderProps): ReactNode {
+  const client = useMemo(() => createGraphQLClient(), []);
+  const [mswReady, setMswReady] = useState(false);
+
+  useEffect(() => {
+    let mounted = true;
+    initMocks().finally(() => {
+      if (mounted) setMswReady(true);
+    });
+    return () => {
+      mounted = false;
+    };
+  }, []);
+
+  // MSW 未启用时直接渲染（initMocks 内部判断）
+  if (!mswReady && process.env.NEXT_PUBLIC_API_MOCKING === "enabled") {
+    return null;
+  }
+
+  return (
+    <GraphQLClientContext.Provider value={client}>
+      <Provider value={client}>{children}</Provider>
+    </GraphQLClientContext.Provider>
+  );
+}
+
+export default GraphQLProvider;