xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
包含 settings/students/api、graphql、mocks、ui-tokens 设计令牌等
This commit is contained in:
SpecialX
2026-07-10 19:10:20 +08:00
parent 14d836beb0
commit 1eacd1ed87
48 changed files with 3897 additions and 1056 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.env.example
View File

@@ -21,7 +21,17 @@ DEV_MODE=false
# 服务端口
API_GATEWAY_PORT=8080
CLASSES_SERVICE_PORT=3001
TEACHER_PORTAL_PORT=3000
TEACHER_PORTAL_PORT=4000
# teacher-portal（ai13，MF Shell）
# GraphQL endpoint（经 api-gateway 代理到 teacher-bff，contract.md §2.3）
NEXT_PUBLIC_TEACHER_BFF_GRAPHQL_URL=/api/v1/teacher/graphql
# MSW mock 开关（contract.md §4.2，enabled 时启用 MSW 拦截上游）
NEXT_PUBLIC_API_MOCKING=enabled
# MF Remote 开关（ARB-002 §2.3，P2 默认 false，P3+ 启用 student-portal）
NEXT_PUBLIC_MF_ENABLED=false
# api-gateway URL（next.config.js rewrites 代理目标）
API_GATEWAY_URL=http://localhost:8080
# 数据库连接
DATABASE_URL=mysql://edu:changeme@localhost:3306/next_edu_cloud

19
apps/teacher-portal/Dockerfile
View File

@@ -1,5 +1,6 @@
# 多阶段构建：Next.js 生产镜像
# 用法：docker build -t edu/teacher-portal:latest -f apps/teacher-portal/Dockerfile .
# 端口规范：teacher-portal :4000（matrix.md §1 微前端层）
# ============ Builder ============
FROM node:20-alpine AS builder
@@ -8,14 +9,20 @@ WORKDIR /app
# 启用 pnpm
RUN corepack enable && corepack prepare pnpm@9.12.0 --activate
# 先拷依赖清单，利用缓存
# 先拷依赖清单，利用缓存（含 workspace 共享包）
COPY package.json pnpm-lock.yaml* pnpm-workspace.yaml* ./
COPY apps/teacher-portal/package.json ./apps/teacher-portal/
COPY packages/ui-tokens/package.json ./packages/ui-tokens/
COPY packages/ui-components/package.json ./packages/ui-components/
COPY packages/hooks/package.json ./packages/hooks/
# 安装依赖（含 devDependencies，构建需要）
RUN pnpm install --filter @edu/teacher-portal... --frozen-lockfile || pnpm install --filter @edu/teacher-portal...
# 拷源码
COPY apps/teacher-portal ./apps/teacher-portal
COPY packages/ui-tokens ./packages/ui-tokens
COPY packages/ui-components ./packages/ui-components
COPY packages/hooks ./packages/hooks
# 构建（禁用 telemetry，生产模式）
ENV NEXT_TELEMETRY_DISABLED=1
@@ -27,7 +34,7 @@ WORKDIR /app
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV PORT=3000
ENV PORT=4000
# 非 root 用户运行
RUN addgroup -g 1001 -S nodejs && adduser -S nextjs -u 1001
@@ -40,10 +47,10 @@ COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/apps/teacher-portal/next.config.js ./next.config.js
USER nextjs
EXPOSE 3000
EXPOSE 4000
# 健康检查
# 健康检查（/api/health liveness 端点）
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
CMD wget --quiet --spider http://localhost:3000/ || exit 1
CMD wget --quiet --spider http://localhost:4000/api/health || exit 1
CMD ["node_modules/.bin/next", "start", "-p", "3000"]
CMD ["node_modules/.bin/next", "start", "-p", "4000"]

107
apps/teacher-portal/next.config.js
View File

@@ -1,11 +1,114 @@
/**
* teacher-portal Next.js 配置
*
* 角色：MF Shell 宿主（ARB-002 §2.3）
* - exposes: AppShell + GraphQLProvider + 共享 hooks + 共享 UI 组件
* - shared: react/react-dom/urql/graphql/@edu/* 设为 singleton
* - remotes: P2 为空（NEXT_PUBLIC_MF_ENABLED=false），P3+ 逐步接入
*
* 维护者：ai13（teacher-portal）
* 关联：ARB-002 §2.2 暴露清单、03-long-term-architecture.md §1.3 绞杀者模式
*/
/** @type {import('next').NextConfig} */
// NextFederationPlugin 动态 require，避免构建时硬依赖（MF 2.0 在 Next 14 App Router 下按需加载）
let NextFederationPlugin;
try {
// eslint-disable-next-line @typescript-eslint/no-require-imports
NextFederationPlugin = require("@module-federation/nextjs-mf").NextFederationPlugin;
} catch {
// 依赖未安装时跳过 MF 配置（如纯 typecheck 环境）
NextFederationPlugin = null;
}
/**
* 构建 Remote 列表（P2 为空，P3+ 按 NEXT_PUBLIC_MF_ENABLED 启用）
*
* ARB-002 §2.3：P2 Remote 数量 = 0，NEXT_PUBLIC_MF_ENABLED=false 默认关
* P3 首个 Remote：student-portal（总裁 §1.3 step 4）
*/
function buildRemotes(isServer) {
if (process.env.NEXT_PUBLIC_MF_ENABLED !== "true") return {};
const chunkPath = isServer ? "ssr" : "chunks";
return {
student: `student_app@http://localhost:4001/_next/static/${chunkPath}/remoteEntry.js`,
parent: `parent_app@http://localhost:4002/_next/static/${chunkPath}/remoteEntry.js`,
admin: `admin_app@http://localhost:4003/_next/static/${chunkPath}/remoteEntry.js`,
};
}
/**
* ARB-002 §2.2 MF Shell 暴露清单
*/
function buildExposes() {
return {
// 1. AppShell（布局 + 导航 + 认证守卫）
"./AppShell": "./src/components/AppShell.tsx",
// 2. GraphQLProvider（urql client 单例，总裁 §2.17 方案 A）
"./GraphQLProvider": "./src/app/providers.tsx",
// 3. 共享 hooks
"./useAuth": "./packages/hooks/src/use-auth.ts",
"./usePermission": "./packages/hooks/src/use-permission.ts",
"./useGraphQLClient": "./packages/hooks/src/use-graphql-client.ts",
// 4. 共享 UI 组件
"./ErrorBoundary": "./packages/ui-components/src/error-boundary.tsx",
"./Loading": "./packages/ui-components/src/loading.tsx",
"./Empty": "./packages/ui-components/src/empty.tsx",
"./RequirePermission": "./packages/ui-components/src/require-permission.tsx",
};
}
/**
* ARB-002 §2.2 MF shared singleton 配置
* 避免 Remote 多实例 + 缓存不一致
*/
function buildShared() {
return {
react: { singleton: true, requiredVersion: "^18.3.0" },
"react-dom": { singleton: true, requiredVersion: "^18.3.0" },
urql: { singleton: true, requiredVersion: "^2.2.0" },
graphql: { singleton: true, requiredVersion: "^16.8.0" },
"@edu/ui-tokens": { singleton: true },
"@edu/ui-components": { singleton: true },
"@edu/hooks": { singleton: true },
};
}
const nextConfig = {
reactStrictMode: true,
// ARB-002：MF Shell 配置（exposes + shared，P2 无 remotes）
webpack(config, { isServer }) {
if (NextFederationPlugin) {
config.plugins.push(
new NextFederationPlugin({
name: "teacher_app",
filename: "static/chunks/remoteEntry.js",
remotes: buildRemotes(isServer),
exposes: buildExposes(),
shared: buildShared(),
extraOptions: {
exposePages: false,
},
}),
);
}
return config;
},
// 反向代理：/api/v1/* → api-gateway :8080
async rewrites() {
const gateway = process.env.API_GATEWAY_URL || "http://localhost:8080";
return [
{
source: '/api/v1/:path*',
destination: `${process.env.API_GATEWAY_URL || 'http://localhost:8080'}/api/v1/:path*`,
source: "/api/v1/:path*",
destination: `${gateway}/api/v1/:path*`,
},
{
// 登录端点（非 GraphQL，认证前提，F12: JWT 存 localStorage）
source: "/api/auth/:path*",
destination: `${gateway}/api/auth/:path*`,
},
];
},

20
apps/teacher-portal/package.json
View File

@@ -3,25 +3,37 @@
"version": "0.1.0",
"private": true,
"scripts": {
"dev": "next dev -p 3000",
"dev": "next dev -p 4000",
"build": "next build",
"start": "next start -p 3000",
"start": "next start -p 4000",
"lint": "eslint src",
"typecheck": "tsc --noEmit"
},
"dependencies": {
"@edu/hooks": "workspace:*",
"@edu/ui-components": "workspace:*",
"@edu/ui-tokens": "workspace:*",
"graphql": "^16.8.0",
"next": "^14.2.0",
"react": "^18.3.0",
"react-dom": "^18.3.0"
"react-dom": "^18.3.0",
"urql": "^2.2.0"
},
"devDependencies": {
"@module-federation/nextjs-mf": "^8.3.0",
"@types/node": "^22.0.0",
"@types/react": "^18.3.0",
"@types/react-dom": "^18.3.0",
"autoprefixer": "^10.4.0",
"eslint": "^9.0.0",
"msw": "^2.4.0",
"postcss": "^8.4.0",
"tailwindcss": "^3.4.0",
"typescript": "^5.6.0"
},
"msw": {
"workerDirectory": [
"public"
]
}
}
}

361
apps/teacher-portal/public/mockServiceWorker.js Normal file
View File

@@ -0,0 +1,361 @@
/* eslint-disable */
/* tslint:disable */
/**
* Mock Service Worker.
* @see https://github.com/mswjs/msw
* - Please do NOT modify this file.
*/
const PACKAGE_VERSION = '2.15.0'
const INTEGRITY_CHECKSUM = '03cb67ac84128e63d7cd722a6e5b7f1e'
const IS_MOCKED_RESPONSE = Symbol('isMockedResponse')
const activeClientIds = new Set()
addEventListener('install', function () {
self.skipWaiting()
})
addEventListener('activate', function (event) {
event.waitUntil(self.clients.claim())
})
addEventListener('message', async function (event) {
const clientId = Reflect.get(event.source || {}, 'id')
if (!clientId || !self.clients) {
return
}
const client = await self.clients.get(clientId)
if (!client) {
return
}
const allClients = await self.clients.matchAll({
type: 'window',
})
switch (event.data) {
case 'KEEPALIVE_REQUEST': {
sendToClient(client, {
type: 'KEEPALIVE_RESPONSE',
})
break
}
case 'INTEGRITY_CHECK_REQUEST': {
sendToClient(client, {
type: 'INTEGRITY_CHECK_RESPONSE',
payload: {
packageVersion: PACKAGE_VERSION,
checksum: INTEGRITY_CHECKSUM,
},
})
break
}
case 'MOCK_ACTIVATE': {
activeClientIds.add(clientId)
sendToClient(client, {
type: 'MOCKING_ENABLED',
payload: {
client: {
id: client.id,
frameType: client.frameType,
},
},
})
break
}
case 'CLIENT_CLOSED': {
activeClientIds.delete(clientId)
const remainingClients = allClients.filter((client) => {
return client.id !== clientId
})
// Unregister itself when there are no more clients
if (remainingClients.length === 0) {
self.registration.unregister()
}
break
}
}
})
addEventListener('fetch', function (event) {
const requestInterceptedAt = Date.now()
// Bypass navigation requests.
if (event.request.mode === 'navigate') {
return
}
// Opening the DevTools triggers the "only-if-cached" request
// that cannot be handled by the worker. Bypass such requests.
if (
event.request.cache === 'only-if-cached' &&
event.request.mode !== 'same-origin'
) {
return
}
// Bypass all requests when there are no active clients.
// Prevents the self-unregistered worked from handling requests
// after it's been terminated (still remains active until the next reload).
if (activeClientIds.size === 0) {
return
}
const requestId = crypto.randomUUID()
event.respondWith(handleRequest(event, requestId, requestInterceptedAt))
})
/**
* @param {FetchEvent} event
* @param {string} requestId
* @param {number} requestInterceptedAt
*/
async function handleRequest(event, requestId, requestInterceptedAt) {
const client = await resolveMainClient(event)
const requestCloneForEvents = event.request.clone()
const response = await getResponse(
event,
client,
requestId,
requestInterceptedAt,
)
// Send back the response clone for the "response:*" life-cycle events.
// Ensure MSW is active and ready to handle the message, otherwise
// this message will pend indefinitely.
if (client && activeClientIds.has(client.id)) {
const serializedRequest = await serializeRequest(requestCloneForEvents)
// Omit the body of server-sent event stream responses.
// Cloning such responses would prevent client-side stream cancelations
// from reaching the original stream (a teed stream only cancels its
// source once both of its branches cancel) and would buffer the
// entire stream into the unconsumed clone indefinitely.
const isEventStreamResponse = response.headers
.get('content-type')
?.toLowerCase()
.startsWith('text/event-stream')
// Clone the response so both the client and the library could consume it.
const responseClone = isEventStreamResponse ? null : response.clone()
sendToClient(
client,
{
type: 'RESPONSE',
payload: {
isMockedResponse: IS_MOCKED_RESPONSE in response,
request: {
id: requestId,
...serializedRequest,
},
response: {
type: response.type,
status: response.status,
statusText: response.statusText,
headers: Object.fromEntries(response.headers.entries()),
body: responseClone ? responseClone.body : null,
},
},
},
responseClone && responseClone.body
? [serializedRequest.body, responseClone.body]
: [],
)
}
return response
}
/**
* Resolve the main client for the given event.
* Client that issues a request doesn't necessarily equal the client
* that registered the worker. It's with the latter the worker should
* communicate with during the response resolving phase.
* @param {FetchEvent} event
* @returns {Promise<Client | undefined>}
*/
async function resolveMainClient(event) {
const client = await self.clients.get(event.clientId)
if (activeClientIds.has(event.clientId)) {
return client
}
if (client?.frameType === 'top-level') {
return client
}
const allClients = await self.clients.matchAll({
type: 'window',
})
return allClients
.filter((client) => {
// Get only those clients that are currently visible.
return client.visibilityState === 'visible'
})
.find((client) => {
// Find the client ID that's recorded in the
// set of clients that have registered the worker.
return activeClientIds.has(client.id)
})
}
/**
* @param {FetchEvent} event
* @param {Client | undefined} client
* @param {string} requestId
* @param {number} requestInterceptedAt
* @returns {Promise<Response>}
*/
async function getResponse(event, client, requestId, requestInterceptedAt) {
// Clone the request because it might've been already used
// (i.e. its body has been read and sent to the client).
const requestClone = event.request.clone()
function passthrough() {
// Cast the request headers to a new Headers instance
// so the headers can be manipulated with.
const headers = new Headers(requestClone.headers)
// Remove the "accept" header value that marked this request as passthrough.
// This prevents request alteration and also keeps it compliant with the
// user-defined CORS policies.
const acceptHeader = headers.get('accept')
if (acceptHeader) {
const values = acceptHeader.split(',').map((value) => value.trim())
const filteredValues = values.filter(
(value) => value !== 'msw/passthrough',
)
if (filteredValues.length > 0) {
headers.set('accept', filteredValues.join(', '))
} else {
headers.delete('accept')
}
}
return fetch(requestClone, { headers })
}
// Bypass mocking when the client is not active.
if (!client) {
return passthrough()
}
// Bypass initial page load requests (i.e. static assets).
// The absence of the immediate/parent client in the map of the active clients
// means that MSW hasn't dispatched the "MOCK_ACTIVATE" event yet
// and is not ready to handle requests.
if (!activeClientIds.has(client.id)) {
return passthrough()
}
// Notify the client that a request has been intercepted.
const serializedRequest = await serializeRequest(event.request)
const clientMessage = await sendToClient(
client,
{
type: 'REQUEST',
payload: {
id: requestId,
interceptedAt: requestInterceptedAt,
...serializedRequest,
},
},
[serializedRequest.body],
)
switch (clientMessage.type) {
case 'MOCK_RESPONSE': {
return respondWithMock(clientMessage.data)
}
case 'PASSTHROUGH': {
return passthrough()
}
}
return passthrough()
}
/**
* @param {Client} client
* @param {any} message
* @param {Array<Transferable>} transferrables
* @returns {Promise<any>}
*/
function sendToClient(client, message, transferrables = []) {
return new Promise((resolve, reject) => {
const channel = new MessageChannel()
channel.port1.onmessage = (event) => {
if (event.data && event.data.error) {
return reject(event.data.error)
}
resolve(event.data)
}
client.postMessage(message, [
channel.port2,
...transferrables.filter(Boolean),
])
})
}
/**
* @param {Response} response
* @returns {Response}
*/
function respondWithMock(response) {
// Setting response status code to 0 is a no-op.
// However, when responding with a "Response.error()", the produced Response
// instance will have status code set to 0. Since it's not possible to create
// a Response instance with status code 0, handle that use-case separately.
if (response.status === 0) {
return Response.error()
}
const mockedResponse = new Response(response.body, response)
Reflect.defineProperty(mockedResponse, IS_MOCKED_RESPONSE, {
value: true,
enumerable: true,
})
return mockedResponse
}
/**
* @param {Request} request
*/
async function serializeRequest(request) {
return {
url: request.url,
mode: request.mode,
method: request.method,
headers: Object.fromEntries(request.headers.entries()),
cache: request.cache,
credentials: request.credentials,
destination: request.destination,
integrity: request.integrity,
redirect: request.redirect,
referrer: request.referrer,
referrerPolicy: request.referrerPolicy,
body: await request.arrayBuffer(),
keepalive: request.keepalive,
}
}

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

@@ -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>
);
}

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

@@ -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>
);
}

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

@@ -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>
);
}

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

@@ -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>
);
}

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

@@ -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>
);
}

99
apps/teacher-portal/src/app/(app)/settings/page.tsx Normal file
View File

@@ -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>
);
}

109
apps/teacher-portal/src/app/(app)/students/page.tsx Normal file
View File

@@ -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>
);
}

21
apps/teacher-portal/src/app/api/health/route.ts Normal file
View File

@@ -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(),
});
}

28
apps/teacher-portal/src/app/api/ready/route.ts Normal file
View File

@@ -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 等
},
});
}

83
apps/teacher-portal/src/app/globals.css
View File

@@ -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);
}
}

53
apps/teacher-portal/src/app/layout.tsx
View File

@@ -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>
);
}

61
apps/teacher-portal/src/app/providers.tsx Normal file
View File

@@ -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;

215
apps/teacher-portal/src/components/AppShell.tsx
View File

@@ -1,123 +1,126 @@
"use client";
import { useState, useEffect, useCallback } from "react";
/**
* AppShell - MF Shell 布局容器
*
* 职责（02-architecture-design.md §1.2）：
* 1. 左侧导航树（viewports GraphQL query，ARB-001 §1.2）
* 2. 主内容区（children slot）
* 3. 路由守卫（未登录跳转 /login）
* 4. 用户信息 + 登出
* 5. 按 requiredPermission 过滤视口（F7 权限点）
*
* 数据来源（ARB-002 §2.4 ai13 执行项 #3）：
* - viewports: GraphQL ViewportsQuery（替代 REST /api/v1/teacher/viewports）
* - user: GraphQL MeQuery（在 DashboardPage 已加载，AppShell 从 localStorage 兜底）
*
* 维护者：ai13（teacher-portal）
*/
import { useEffect, useMemo } from "react";
import { useRouter, usePathname } from "next/navigation";
import Link from "next/link";
import { useQuery } from "urql";
import { ErrorBoundary, Loading } from "@edu/ui-components";
import { usePermission } from "@edu/hooks";
import { ViewportsQuery, MeQuery } from "@/lib/graphql";
import type { ViewportItem, User } from "@/lib/graphql";
import { getToken, getUser, logout } from "@/lib/auth";
interface ViewportItem {
key: string;
label: string;
route: string;
icon: string | null;
sortOrder: string;
requiredPermission: string | null;
/**
* 权限上下文：从 localStorage 读取（登录时由 iam 返回并存储）。
* P3+ 改为 GraphQL me query 实时拉取（usePermission hook 接受 context props）。
*/
function buildPermissionContext(user: User | null) {
if (!user) return null;
// localStorage UserInfo 包含 permissions 字段（iam /iam/permissions/effective 返回）
const stored = getUser();
return {
permissions: stored?.permissions ?? [],
roles: user.roles,
dataScope: user.dataScope,
};
}
export default function AppShell({ children }: { children: React.ReactNode }) {
const router = useRouter();
const pathname = usePathname();
const [viewports, setViewports] = useState<ViewportItem[]>([]);
const [loading, setLoading] = useState(true);
const [mounted, setMounted] = useState(false);
const fetchViewports = useCallback(async () => {
// 路由守卫：未登录跳转 /login
useEffect(() => {
const token = getToken();
if (!token) {
router.replace("/login");
return;
}
try {
const res = await fetch("/api/v1/teacher/viewports", {
headers: { Authorization: `Bearer ${token}` },
});
if (res.status === 401) {
logout();
return;
}
const json = await res.json();
if (json.success && json.data) {
setViewports(json.data);
}
} catch {
// 网络错误，保持空视口
} finally {
setLoading(false);
}
}, [router]);
useEffect(() => {
setMounted(true);
const token = getToken();
if (!token) {
router.replace("/login");
return;
}
fetchViewports();
}, [router, fetchViewports]);
// GraphQL: viewports query（替代 REST /api/v1/teacher/viewports）
const [viewportsResult] = useQuery({
query: ViewportsQuery,
});
// 防止 SSR 闪烁
if (!mounted) return null;
// GraphQL: me query（实时获取当前用户信息，替代 localStorage 读取）
const [meResult] = useQuery({
query: MeQuery,
});
const user = getUser();
const user = meResult.data?.me ?? null;
const permissionContext = useMemo(
() => buildPermissionContext(user ?? null),
[user],
);
const { hasPermission } = usePermission({ context: permissionContext });
// 按权限过滤视口（F7: requiredPermission 为 null 表示公开视口）
const visibleViewports = useMemo(() => {
const list: ViewportItem[] = viewportsResult.data?.viewports ?? [];
return list.filter(
(vp) => !vp.requiredPermission || hasPermission(vp.requiredPermission),
);
}, [viewportsResult, hasPermission]);
// 视口加载中：占位（避免导航闪烁）
if (viewportsResult.fetching && visibleViewports.length === 0) {
return (
<div className="min-h-screen bg-paper">
<Loading lines={5} />
</div>
);
}
// 视口加载错误：ErrorBoundary 兜底（不阻塞主内容）
const viewportError = viewportsResult.error ? (
<p className="px-3 py-2 text-tiny text-danger">
导航加载失败：{viewportsResult.error.message}
</p>
) : null;
return (
<div
className="min-h-screen flex"
style={{ background: "var(--bg-paper)" }}
>
<div className="min-h-screen flex bg-paper">
{/* 左侧栏：导航树 */}
<aside
className="w-56 flex-shrink-0 border-r relative flex flex-col"
style={{
borderColor: "var(--color-rule)",
background: "var(--bg-paper)",
}}
>
<aside className="w-56 flex-shrink-0 border-r border-rule bg-paper flex flex-col">
<div className="px-6 py-6">
<h1
className="text-xl"
style={{
fontFamily: "var(--font-serif)",
color: "var(--color-ink)",
}}
>
Edu
</h1>
<p
className="text-xs mt-1"
style={{ color: "var(--color-ink-muted)" }}
>
教师端
</p>
<h1 className="text-xl font-serif text-ink">Edu</h1>
<p className="mt-1 text-tiny text-ink-muted">教师端</p>
</div>
<div className="rule-thin mx-6" />
<nav className="mt-4 px-3">
{loading ? (
<p
className="text-xs px-3 py-2"
style={{ color: "var(--color-ink-muted)" }}
>
加载导航...
</p>
{viewportError}
{visibleViewports.length === 0 && !viewportError ? (
<p className="px-3 py-2 text-tiny text-ink-muted">暂无可用视口</p>
) : (
viewports.map((vp) => {
visibleViewports.map((vp) => {
const active = pathname === vp.route;
return (
<Link
key={vp.key}
href={vp.route}
className="block px-3 py-2 text-sm transition-colors"
style={{
color: active ? "var(--color-accent)" : "var(--color-ink)",
borderLeft: active
? "2px solid var(--color-accent)"
: "2px solid transparent",
fontFamily: active
? "var(--font-serif)"
: "var(--font-inter)",
}}
className={`block px-3 py-2 text-sm transition-colors ${
active
? "text-accent border-l-2 border-accent font-serif"
: "text-ink border-l-2 border-transparent font-sans hover:text-accent"
}`}
>
{vp.label}
</Link>
@@ -127,27 +130,18 @@ export default function AppShell({ children }: { children: React.ReactNode }) {
</nav>
{/* 底部：用户信息 + 登出 */}
<div
className="mt-auto px-6 py-4 border-t"
style={{ borderColor: "var(--color-rule)" }}
>
<div className="mt-auto px-6 py-4 border-t border-rule">
{user && (
<div className="mb-2">
<p className="text-sm" style={{ color: "var(--color-ink)" }}>
{user.name}
</p>
<p
className="text-xs"
style={{ color: "var(--color-ink-muted)" }}
>
<p className="text-sm text-ink">{user.name}</p>
<p className="text-tiny text-ink-muted">
{user.roles.join(", ") || "无角色"}
</p>
</div>
)}
<button
onClick={logout}
className="text-xs uppercase tracking-wide hover:opacity-70"
style={{ color: "var(--color-ink-muted)" }}
className="text-tiny uppercase tracking-wide text-ink-muted hover:opacity-70"
>
退出登录
</button>
@@ -155,7 +149,28 @@ export default function AppShell({ children }: { children: React.ReactNode }) {
</aside>
{/* 中间：内容区（纸面） */}
<main className="flex-1 overflow-auto">{children}</main>
<main className="flex-1 overflow-auto">
<ErrorBoundary
fallback={(error, reset) => (
<div
role="alert"
className="flex min-h-[200px] flex-col items-center justify-center gap-4 p-8"
>
<h2 className="text-lg font-serif text-ink">页面出错了</h2>
<p className="text-sm text-ink-muted">{error.message}</p>
<button
type="button"
onClick={reset}
className="px-4 py-2 text-sm text-ink-on-accent bg-accent rounded-button hover:bg-accent-hover"
>
重试
</button>
</div>
)}
>
{children}
</ErrorBoundary>
</main>
</div>
);
}

17
apps/teacher-portal/src/lib/auth.ts
View File

@@ -1,4 +1,10 @@
// 认证工具：token 存储 + 路由保护
/**
* 认证工具：token 存储 + 路由保护
*
* F12 裁决：P2 用 localStorage（accessToken + userInfo），P6 迁移 httpOnly cookie
* 维护者：ai13（teacher-portal）
* 关联：02-architecture-design.md §2.1 会话状态
*/
const TOKEN_KEY = "edu_access_token";
const USER_KEY = "edu_user_info";
@@ -48,12 +54,17 @@ export function isAuthenticated(): boolean {
return getToken() !== null;
}
// 调用 Gateway 登录接口
/**
* 调用 Gateway 登录接口
*
* 非 GraphQL（认证前提，MF 依赖认证，F12 裁决）
* 路径：POST /api/auth/login（经 next.config.js rewrites 代理到 api-gateway）
*/
export async function login(
email: string,
password: string,
): Promise<{ user: UserInfo; token: string }> {
const res = await fetch("/api/v1/iam/login", {
const res = await fetch("/api/auth/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ email, password }),

302
apps/teacher-portal/src/lib/graphql.ts Normal file
View File

@@ -0,0 +1,302 @@
/**
* GraphQL client + queries/mutations（ARB-001 P2 第一版 schema）
*
* 维护者：ai13（teacher-portal）
* 关联：coord.md §1 ARB-001、02-architecture-design.md §4
*
* schema 来源：packages/shared-ts/contracts/graphql/teacher-bff.graphql（ai03 维护）
* P2 第一版 Query 范围（ARB-001 §1.2）：dashboard / viewports / me / classes / class（5 个）
* P2 不包含 Mutation（P3+ 扩展）
*
* 错误处理（ARB-001 §1.3）：
* - BFF 始终返回 ActionState 信封（success/errors/data）
* - GraphQL errors[].extensions.code = BFF_TEACHER_*（G14 裁决）
* - 前端按前缀路由 i18n key（F11: error.teacher_bff.<code_snake>）
*/
import { createClient, cacheExchange, fetchExchange } from "urql";
import { gql } from "urql";
import type { Client } from "urql";
// ============ Types（对齐 ARB-001 §1.2 schema） ============
export type DataScope =
"SELF" | "CLASS" | "GRADE" | "SCHOOL" | "DISTRICT" | "ALL";
export type ExamStatus =
"DRAFT" | "PUBLISHED" | "IN_PROGRESS" | "GRADING" | "SCORED" | "ARCHIVED";
export type SubmissionStatus = "NOT_SUBMITTED" | "SUBMITTED" | "GRADED";
export interface User {
id: string;
email: string;
name: string;
roles: string[];
dataScope: DataScope;
}
export interface ViewportItem {
key: string;
label: string;
route: string;
icon: string | null;
sortOrder: string;
requiredPermission: string | null;
}
export interface Class {
id: string;
name: string;
gradeId: string;
studentCount: number;
}
export interface DashboardStats {
totalExams: number;
pendingGrading: number;
todayHomework: number;
}
export interface DashboardData {
user: User;
classes: Class[];
viewports: ViewportItem[];
stats: DashboardStats;
}
// ============ urql client 单例（总裁 §2.17 方案 A） ============
/**
* 创建 urql client 单例
*
* Shell（teacher-portal）调用此函数创建 client，通过 GraphQLProvider 注入给所有 Remote。
* token 从 localStorage 读取（F12: P2 用 localStorage，P6 迁移 httpOnly cookie）。
*/
export function createGraphQLClient(): Client {
const url =
process.env.NEXT_PUBLIC_TEACHER_BFF_GRAPHQL_URL ||
"/api/v1/teacher/graphql";
return createClient({
url,
fetchOptions: () => {
const headers: Record<string, string> = {
"Content-Type": "application/json",
};
// F12: P2 token 存 localStorage
if (typeof window !== "undefined") {
const token = window.localStorage.getItem("edu_access_token");
if (token) {
headers["Authorization"] = `Bearer ${token}`;
}
}
return { headers };
},
exchanges: [cacheExchange, fetchExchange],
});
}
// ============ P2 Query（ARB-001 §1.2，5 个 Must Have） ============
/** 仪表盘聚合查询（并行：iam.me + iam.viewports + iam.permissions + classes.byTeacher） */
export const DashboardQuery = gql`
query Dashboard {
dashboard {
user {
id
email
name
roles
dataScope
}
classes {
id
name
gradeId
studentCount
}
viewports {
key
label
route
icon
sortOrder
requiredPermission
}
stats {
totalExams
pendingGrading
todayHomework
}
}
}
`;
/** 视口配置查询（导航） */
export const ViewportsQuery = gql`
query Viewports {
viewports {
key
label
route
icon
sortOrder
requiredPermission
}
}
`;
/** 当前用户信息查询 */
export const MeQuery = gql`
query Me {
me {
id
email
name
roles
dataScope
}
}
`;
/** 班级列表查询（按教师 dataScope 过滤） */
export const ClassesQuery = gql`
query Classes {
classes {
id
name
gradeId
studentCount
}
}
`;
/** 班级详情查询 */
export const ClassQuery = gql`
query Class($id: ID!) {
class(id: $id) {
id
name
gradeId
studentCount
}
}
`;
// ============ P3 Query/Mutation（MSW mock，待 teacher-bff P3+ 实现） ============
// 以下查询对应 workline.md §3 P3-P5 交付物，schema 尚未在 ARB-001 P2 第一版中定义。
// 开发期通过 MSW 拦截返回 mock 响应；上游就绪后由 ai03 在 teacher-bff.graphql 扩展。
/** 学生信息（iam 数据，经 teacher-bff 聚合） */
export interface Student {
id: string;
name: string;
email: string;
avatarUrl: string | null;
}
/** 班级学生名单查询（P3 扩展，MSW mock） */
export const ClassStudentsQuery = gql`
query ClassStudents($classId: ID!) {
classStudents(classId: $classId) {
id
name
email
avatarUrl
}
}
`;
/** 考试项（core-edu 域） */
export interface ExamItem {
id: string;
classId: string;
title: string;
description: string | null;
examDate: string;
duration: number;
totalScore: number;
status: ExamStatus;
}
/** 班级考试列表查询（P3 扩展，MSW mock） */
export const ClassExamsQuery = gql`
query ClassExams($classId: ID!) {
classExams(classId: $classId) {
id
classId
title
description
examDate
duration
totalScore
status
}
}
`;
/** 作业项（core-edu 域） */
export interface HomeworkItem {
id: string;
classId: string;
title: string;
description: string | null;
dueDate: string;
status: SubmissionStatus;
}
/** 班级作业列表查询（P3 扩展，MSW mock） */
export const ClassHomeworkQuery = gql`
query ClassHomework($classId: ID!) {
classHomework(classId: $classId) {
id
classId
title
description
dueDate
status
}
}
`;
/** 成绩项（core-edu 域） */
export interface GradeItem {
id: string;
studentId: string;
studentName: string;
examId: string | null;
homeworkId: string | null;
score: number;
feedback: string | null;
}
/** 考试成绩列表查询（P3 扩展，MSW mock） */
export const ExamGradesQuery = gql`
query ExamGrades($examId: ID!) {
examGrades(examId: $examId) {
id
studentId
studentName
examId
homeworkId
score
feedback
}
}
`;
/** 更新用户信息 Mutation（P3 扩展，MSW mock） */
export const UpdateUserMutation = gql`
mutation UpdateUser($input: UpdateUserInput!) {
updateUser(input: $input) {
id
email
name
roles
dataScope
}
}
`;

12
apps/teacher-portal/src/mocks/browser.ts Normal file
View File

@@ -0,0 +1,12 @@
/**
* MSW Browser Setup - 浏览器端 Service Worker 注册
*
* 用法：在客户端入口（如 providers.tsx 或 layout）调用 setupWorker()
*
* 维护者：ai13（teacher-portal）
*/
import { setupWorker } from "msw/browser";
import { handlers } from "./handlers";
export const worker = setupWorker(...handlers);

33
apps/teacher-portal/src/mocks/fixtures/classes.ts Normal file
View File

@@ -0,0 +1,33 @@
/**
* Mock 班级数据（classes 域）
*
* 维护者：ai13（teacher-portal）
*/
import type { Class } from "@/lib/graphql";
export const mockClasses: Class[] = [
{
id: "550e8400-e29b-41d4-a716-446655440010",
name: "高三(1)班",
gradeId: "grade-12",
studentCount: 32,
},
{
id: "550e8400-e29b-41d4-a716-446655440011",
name: "高三(2)班",
gradeId: "grade-12",
studentCount: 30,
},
{
id: "550e8400-e29b-41d4-a716-446655440012",
name: "高三(3)班",
gradeId: "grade-12",
studentCount: 28,
},
];
/** Mock 班级详情查找（按 id） */
export function findClass(id: string): Class | null {
return mockClasses.find((c) => c.id === id) ?? null;
}

43
apps/teacher-portal/src/mocks/fixtures/exams.ts Normal file
View File

@@ -0,0 +1,43 @@
/**
* Mock 考试数据（core-edu 域）
*
* 维护者：ai13（teacher-portal）
*/
import type { ExamItem } from "@/lib/graphql";
export function generateMockExams(classId: string): ExamItem[] {
const now = Date.now();
return [
{
id: `${classId}-exam-001`,
classId,
title: "2026 春季期中考试",
description: "覆盖第 1-6 章内容",
examDate: new Date(now + 7 * 24 * 60 * 60 * 1000).toISOString(),
duration: 120,
totalScore: 150,
status: "PUBLISHED",
},
{
id: `${classId}-exam-002`,
classId,
title: "单元测试 - 函数与导数",
description: null,
examDate: new Date(now + 14 * 24 * 60 * 60 * 1000).toISOString(),
duration: 60,
totalScore: 100,
status: "DRAFT",
},
{
id: `${classId}-exam-003`,
classId,
title: "月考 - 数学综合",
description: "全册综合测试",
examDate: new Date(now - 7 * 24 * 60 * 60 * 1000).toISOString(),
duration: 90,
totalScore: 120,
status: "SCORED",
},
];
}

26
apps/teacher-portal/src/mocks/fixtures/grades.ts Normal file
View File

@@ -0,0 +1,26 @@
/**
* Mock 成绩数据（core-edu 域）
*
* 维护者：ai13（teacher-portal）
*/
import type { GradeItem } from "@/lib/graphql";
export function generateMockGrades(examId: string): GradeItem[] {
const grades: GradeItem[] = [];
for (let i = 1; i <= 30; i++) {
const score = Math.floor(Math.random() * 40) + 60;
const feedback =
score < 70 ? "需要加强基础练习" : score > 90 ? "表现出色" : null;
grades.push({
id: `${examId}-grade-${i}`,
studentId: `${examId.slice(0, -3)}${String(i).padStart(3, "0")}`,
studentName: `学生${String(i).padStart(2, "0")}`,
examId,
homeworkId: null,
score,
feedback,
});
}
return grades;
}

37
apps/teacher-portal/src/mocks/fixtures/homework.ts Normal file
View File

@@ -0,0 +1,37 @@
/**
* Mock 作业数据（core-edu 域）
*
* 维护者：ai13（teacher-portal）
*/
import type { HomeworkItem } from "@/lib/graphql";
export function generateMockHomework(classId: string): HomeworkItem[] {
const now = Date.now();
return [
{
id: `${classId}-hw-001`,
classId,
title: "函数练习题",
description: "课本 P45 第 1-10 题",
dueDate: new Date(now + 3 * 24 * 60 * 60 * 1000).toISOString(),
status: "NOT_SUBMITTED",
},
{
id: `${classId}-hw-002`,
classId,
title: "导数应用题",
description: null,
dueDate: new Date(now + 7 * 24 * 60 * 60 * 1000).toISOString(),
status: "SUBMITTED",
},
{
id: `${classId}-hw-003`,
classId,
title: "月考错题订正",
description: "订正月考全部错题，并写解题思路",
dueDate: new Date(now - 2 * 24 * 60 * 60 * 1000).toISOString(),
status: "GRADED",
},
];
}

22
apps/teacher-portal/src/mocks/fixtures/students.ts Normal file
View File

@@ -0,0 +1,22 @@
/**
* Mock 学生名单（iam 数据，经 teacher-bff 聚合）
*
* 维护者：ai13（teacher-portal）
*/
import type { Student } from "@/lib/graphql";
/** 按班级 ID 生成学生名单（固定 30 名） */
export function generateMockStudents(classId: string): Student[] {
const students: Student[] = [];
for (let i = 1; i <= 30; i++) {
const id = `${classId.slice(0, -3)}${String(i).padStart(3, "0")}`;
students.push({
id,
name: `学生${String(i).padStart(2, "0")}`,
email: `student${i}@edu.test`,
avatarUrl: null,
});
}
return students;
}

39
apps/teacher-portal/src/mocks/fixtures/user.ts Normal file
View File

@@ -0,0 +1,39 @@
/**
* Mock 用户数据（iam 域）
*
* 维护者：ai13（teacher-portal）
* 关联：contract.md §4.2 MSW 拦截策略
*/
import type { User } from "@/lib/graphql";
export const mockUser: User = {
id: "550e8400-e29b-41d4-a716-446655440001",
email: "teacher@edu.test",
name: "张老师",
roles: ["teacher"],
dataScope: "GRADE",
};
/** localStorage 中存储的 UserInfo（含 permissions 字段） */
export const mockUserInfo = {
...mockUser,
permissions: [
"DASHBOARD_READ",
"VIEWPORT_READ",
"CLASS_READ",
"CLASS_READ_OWN",
"STUDENT_READ_OWN",
"EXAM_READ_OWN",
"HOMEWORK_READ_OWN",
"GRADE_READ_OWN",
"GRADE_READ_CHILD",
"USER_READ_OWN",
],
};
/** Mock JWT token（与 api-gateway DEV_MODE 公钥配对） */
export const mockToken =
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9." +
btoa(JSON.stringify(mockUserInfo)) +
".mock-signature";

58
apps/teacher-portal/src/mocks/fixtures/viewports.ts Normal file
View File

@@ -0,0 +1,58 @@
/**
* Mock 视口数据（iam 4 层视口模型，contract.md §2.4）
*
* 维护者：ai13（teacher-portal）
*/
import type { ViewportItem } from "@/lib/graphql";
export const mockViewports: ViewportItem[] = [
{
key: "dashboard",
label: "仪表盘",
route: "/dashboard",
icon: null,
sortOrder: "01",
requiredPermission: "DASHBOARD_READ",
},
{
key: "classes",
label: "班级管理",
route: "/classes",
icon: null,
sortOrder: "02",
requiredPermission: "CLASS_READ",
},
{
key: "exams",
label: "考试管理",
route: "/exams",
icon: null,
sortOrder: "03",
requiredPermission: "EXAM_READ_OWN",
},
{
key: "homework",
label: "作业管理",
route: "/homework",
icon: null,
sortOrder: "04",
requiredPermission: "HOMEWORK_READ_OWN",
},
{
key: "grades",
label: "成绩查询",
route: "/grades",
icon: null,
sortOrder: "05",
requiredPermission: "GRADE_READ_OWN",
},
{
key: "settings",
label: "个人设置",
route: "/settings",
icon: null,
sortOrder: "99",
requiredPermission: "USER_READ_OWN",
},
];

174
apps/teacher-portal/src/mocks/handlers.ts Normal file
View File

@@ -0,0 +1,174 @@
/**
* MSW Handlers - 拦截所有 HTTP / GraphQL 请求返回 mock 数据
*
* 拦截路径（contract.md §2.3 + §4.2）：
* - POST /api/auth/login → 返回固定 JWT + UserInfo
* - POST /api/v1/teacher/graphql → 按 operationName 返回对应 GraphQL 响应
*
* 切换：NEXT_PUBLIC_API_MOCKING=enabled 时启用（见 src/mocks/index.ts）
*
* 维护者：ai13（teacher-portal）
*/
import { http, HttpResponse } from "msw";
import { mockUser, mockUserInfo, mockToken } from "./fixtures/user";
import { mockViewports } from "./fixtures/viewports";
import { mockClasses, findClass } from "./fixtures/classes";
import { generateMockStudents } from "./fixtures/students";
import { generateMockExams } from "./fixtures/exams";
import { generateMockHomework } from "./fixtures/homework";
import { generateMockGrades } from "./fixtures/grades";
/** ActionState 信封（coord-final-decisions F9 + 总裁 §3.4 方案 B） */
function envelope<T>(data: T) {
return { success: true, errors: null, data };
}
/** GraphQL 响应体（urql 期望 { data: ... }） */
function graphqlData<T>(data: T) {
return HttpResponse.json({ data });
}
/**
* 根据 operationName 路由 GraphQL mock 响应
*
* 对应 graphql.ts 的 5 个 P2 Query + 4 个 P3 Query + 1 个 Mutation。
*/
function handleGraphQL(
operationName: string,
variables: Record<string, unknown>,
) {
switch (operationName) {
case "Dashboard":
return graphqlData({
dashboard: {
user: mockUser,
classes: mockClasses,
viewports: mockViewports,
stats: {
totalExams: 8,
pendingGrading: 12,
todayHomework: 3,
},
},
});
case "Viewports":
return graphqlData({ viewports: mockViewports });
case "Me":
return graphqlData({ me: mockUser });
case "Classes":
return graphqlData({ classes: mockClasses });
case "Class": {
const id = variables.id as string;
return graphqlData({ class: findClass(id) });
}
case "ClassStudents": {
const classId = variables.classId as string;
return graphqlData({ classStudents: generateMockStudents(classId) });
}
case "ClassExams": {
const classId = variables.classId as string;
return graphqlData({ classExams: generateMockExams(classId) });
}
case "ClassHomework": {
const classId = variables.classId as string;
return graphqlData({ classHomework: generateMockHomework(classId) });
}
case "ExamGrades": {
const examId = variables.examId as string;
return graphqlData({ examGrades: generateMockGrades(examId) });
}
case "UpdateUser": {
const input = variables.input as { name?: string; email?: string };
return graphqlData({
updateUser: { ...mockUser, ...input },
});
}
default:
return HttpResponse.json(
{
errors: [
{
message: `Mock 未覆盖的 GraphQL operation: ${operationName}`,
extensions: { code: "BFF_TEACHER_NOT_IMPLEMENTED" },
},
],
},
{ status: 200 },
);
}
}
export const handlers = [
// POST /api/auth/login → 登录
http.post("*/api/auth/login", async ({ request }) => {
const body = (await request.json()) as {
email?: string;
password?: string;
};
if (!body.email || !body.password) {
return HttpResponse.json(
{
success: false,
error: { code: "GW_UNAUTHORIZED", message: "邮箱和密码必填" },
},
{ status: 400 },
);
}
return HttpResponse.json(
envelope({
user: mockUserInfo,
tokens: { accessToken: mockToken, refreshToken: "mock-refresh" },
}),
);
}),
// POST /api/v1/teacher/graphql → GraphQL endpoint
http.post("*/api/v1/teacher/graphql", async ({ request }) => {
const body = (await request.json()) as {
operationName?: string;
query?: string;
variables?: Record<string, unknown>;
};
const operationName =
body.operationName ?? extractOperationName(body.query);
const variables = body.variables ?? {};
return handleGraphQL(operationName, variables);
}),
// GET /api/health → liveness
http.get("*/api/health", () =>
HttpResponse.json({ status: "ok", service: "teacher-portal" }),
),
// GET /api/ready → readiness
http.get("*/api/ready", () =>
HttpResponse.json({
status: "ok",
service: "teacher-portal",
checks: { msw: true },
}),
),
];
/**
* 从 query 字符串提取 operationName
* 兜底：当客户端未传 operationName 时从 query 文本提取
*/
function extractOperationName(query?: string): string {
if (!query) return "Unknown";
const match = query.match(/(?:query|mutation)\s+(\w+)/);
return match?.[1] ?? "Unknown";
}

37
apps/teacher-portal/src/mocks/index.ts Normal file
View File

@@ -0,0 +1,37 @@
/**
* MSW 启用入口 - 按 NEXT_PUBLIC_API_MOCKING 环境变量条件启用
*
* 启用方式：在 .env 中设置 NEXT_PUBLIC_API_MOCKING=enabled
* 关闭方式：删除该变量或设为 disabled
*
* 在客户端入口（providers.tsx）调用 initMocks() 触发注册。
*
* 维护者：ai13（teacher-portal）
*/
const MOCKING_ENABLED = process.env.NEXT_PUBLIC_API_MOCKING === "enabled";
async function initMocks(): Promise<void> {
if (!MOCKING_ENABLED) {
return;
}
if (typeof window === "undefined") {
// 服务端：启用 node server
const { server } = await import("./server");
server.listen({
onUnhandledRequest: "bypass",
});
} else {
// 客户端：注册 Service Worker
const { worker } = await import("./browser");
await worker.start({
onUnhandledRequest: "bypass",
serviceWorker: {
url: "/mockServiceWorker.js",
},
});
}
}
export { initMocks, MOCKING_ENABLED };

13
apps/teacher-portal/src/mocks/server.ts Normal file
View File

@@ -0,0 +1,13 @@
/**
* MSW Server Setup - Node.js 端 mock（用于 SSR + 测试）
*
* Next.js App Router 在服务端渲染时会调用 GraphQL（urql 支持 SSR），
* 需要在服务端也启用 MSW 拦截。
*
* 维护者：ai13（teacher-portal）
*/
import { setupServer } from "msw/node";
import { handlers } from "./handlers";
export const server = setupServer(...handlers);

81
apps/teacher-portal/tailwind.config.js
View File

@@ -1,24 +1,85 @@
/**
* Tailwind 配置 - 对齐三层设计令牌
*
* 维护者：ai13（teacher-portal）
* 关联：project_rules §3.10、02-architecture-design.md §9
*
* Layer 3 映射：将 Layer 2 Semantic CSS 变量暴露为 Tailwind 类名
* 业务代码使用 bg-paper / text-ink / font-serif 等语义类
*
* 禁止：
* - 禁止 hex 字面量（colors 引用 var(--*)）
* - 禁止字体名字面量（fontFamily 引用 var(--font-family-*))
*/
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ['./src/**/*.{js,ts,jsx,tsx}'],
content: ["./src/**/*.{js,ts,jsx,tsx}"],
theme: {
extend: {
colors: {
paper: 'hsl(40, 20%, 98%)',
// Layer 2 Semantic → Tailwind 类名映射
paper: "var(--bg-paper)",
surface: "var(--bg-surface)",
subtle: "var(--bg-subtle)",
ink: {
DEFAULT: 'hsl(25, 3%, 15%)',
muted: 'hsl(30, 5%, 45%)',
DEFAULT: "var(--color-ink)",
muted: "var(--color-ink-muted)",
subtle: "var(--color-ink-subtle)",
onAccent: "var(--color-ink-on-accent)",
},
accent: 'hsl(220, 60%, 35%)',
rule: 'hsl(30, 10%, 90%)',
accent: {
DEFAULT: "var(--color-accent)",
hover: "var(--color-accent-hover)",
subtle: "var(--color-accent-subtle)",
},
rule: {
DEFAULT: "var(--color-rule)",
strong: "var(--color-rule-strong)",
},
success: "var(--color-success)",
warning: "var(--color-warning)",
danger: "var(--color-danger)",
info: "var(--color-info)",
border: "var(--color-border)",
},
fontFamily: {
serif: ['Fraunces', 'Georgia', 'serif'],
sans: ['Inter', 'system-ui', 'sans-serif'],
mono: ['JetBrains Mono', 'monospace'],
sans: "var(--font-family-sans)",
serif: "var(--font-family-serif)",
mono: "var(--font-family-mono)",
},
fontSize: {
body: "var(--font-size-body)",
small: "var(--font-size-small)",
tiny: "var(--font-size-tiny)",
"heading-1": "var(--font-size-heading-1)",
"heading-2": "var(--font-size-heading-2)",
"heading-3": "var(--font-size-heading-3)",
display: "var(--font-size-display)",
"large-number": "var(--font-size-large-number)",
},
spacing: {
xs: "var(--space-xs)",
sm: "var(--space-sm)",
md: "var(--space-md)",
lg: "var(--space-lg)",
xl: "var(--space-xl)",
"2xl": "var(--space-2xl)",
},
borderRadius: {
DEFAULT: '6px',
DEFAULT: "var(--radius-default)",
card: "var(--radius-card)",
button: "var(--radius-button)",
},
boxShadow: {
sm: "var(--shadow-sm)",
md: "var(--shadow-md)",
lg: "var(--shadow-lg)",
xl: "var(--shadow-xl)",
},
transitionDuration: {
fast: "150ms",
normal: "200ms",
},
},
},

9
apps/teacher-portal/tsconfig.json
View File

@@ -21,6 +21,15 @@
"paths": {
"@/*": [
"./src/*"
],
"@edu/hooks": [
"../../packages/hooks/src/index.ts"
],
"@edu/ui-components": [
"../../packages/ui-components/src/index.ts"
],
"@edu/ui-tokens": [
"../../packages/ui-tokens/src/index.ts"
]
},
"isolatedModules": true

56
docs/architecture/issues/worklines/teacher-portal_workline.md
View File

@@ -131,26 +131,48 @@ gantt
### §4.1 我依赖的上游就绪标志
| 上游 | 就绪标志 | 阻塞阶段 | 状态 |
| --------------------------------------------------------- | ------------------------------------------------- | -------- | ---------------------- |
| packages 骨架（ai13 自建） | ui-tokens/ui-components/hooks 可 import | P2 启动 | ✅ 已就绪（批次 0.15） |
| teacher-bff GraphQL schema（ai03 + coord 仲裁 ISSUE-037） | packages/shared-ts/contracts/graphql/ 第一版 | P2 启动 | ⏳ 待 coord 仲裁 |
| api-gateway HTTP :8080（ai01） | /api/v1/teacher/graphql + /api/auth/login 路由可用 | P2 启动 | ⏳ 待 ai01 |
| teacher-bff core-edu 扩展（ai03 P3） | classExams/classHomework/studentGrades query 可用 | P3 启动 | ⏳ 待 ai03 P3 |
| teacher-bff content/data-ana 扩展（ai03 P4） | knowledgeGraph/studentAnalytics query 可用 | P4 启动 | ⏳ 待 ai03 P4 |
| push-gateway WebSocket :8081/ws（ai02 P5） | WS 连接可建立 + 推送可接收 | P5 启动 | ⏳ 待 ai02 P5 |
| ai 服务 gRPC（ai12 P5） | generateQuestion/generateLessonPlan 可调 | P5 启动 | ⏳ 待 ai12 P5 |
| iam refresh cookie 端点（ai06 P6） | POST /iam/auth/refresh 返回 httpOnly cookie | P6 启动 | ⏳ 待 ai06 P6 |
| 上游 | 就绪标志 | 阻塞阶段 | 状态 |
| --------------------------------------------------------- | -------------------------------------------------- | -------- | ---------------------- |
| packages 骨架（ai13 自建） | ui-tokens/ui-components/hooks 可 import | P2 启动 | ✅ 已就绪（批次 0.15） |
| teacher-bff GraphQL schema（ai03 + coord 仲裁 ISSUE-037） | packages/shared-ts/contracts/graphql/ 第一版 | P2 启动 | ⏳ 待 coord 仲裁 |
| api-gateway HTTP :8080（ai01） | /api/v1/teacher/graphql + /api/auth/login 路由可用 | P2 启动 | ⏳ 待 ai01 |
| teacher-bff core-edu 扩展（ai03 P3） | classExams/classHomework/studentGrades query 可用 | P3 启动 | ⏳ 待 ai03 P3 |
| teacher-bff content/data-ana 扩展（ai03 P4） | knowledgeGraph/studentAnalytics query 可用 | P4 启动 | ⏳ 待 ai03 P4 |
| push-gateway WebSocket :8081/ws（ai02 P5） | WS 连接可建立 + 推送可接收 | P5 启动 | ⏳ 待 ai02 P5 |
| ai 服务 gRPC（ai12 P5） | generateQuestion/generateLessonPlan 可调 | P5 启动 | ⏳ 待 ai12 P5 |
| iam refresh cookie 端点（ai06 P6） | POST /iam/auth/refresh 返回 httpOnly cookie | P6 启动 | ⏳ 待 ai06 P6 |
### §4.2 我的就绪信号（供下游消费）
| 信号 | 就绪标志 | 消费方 |
| ------------------------------- | -------------------------------------- | ---------------------------------- |
| teacher-portal dev server :4000 | next dev -p 4000 可访问 | 无（最前端） |
| MF Shell 可加载 | 首页渲染 AppShell + 导航 | student/parent/admin Remote（P3+） |
| 登录流程可用 | POST /api/auth/login → JWT → Dashboard | 无（最前端） |
| GraphQL 查询可执行 | currentUser/myClasses 返回数据 | 无（最前端） |
| parent-portal Remote 接入点 | MF remotes 配置就绪 | parent-portal（ai15 P4） |
| 信号 | 就绪标志 | 消费方 | P2 状态 |
| ------------------------------- | ----------------------------------------------------------------------- | ---------------------------------- | --------------------- |
| teacher-portal dev server :4000 | next dev -p 4000 可访问 | 无（最前端） | ✅ 已就绪 |
| MF Shell 可加载 | 首页渲染 AppShell + 导航 | student/parent/admin Remote（P3+） | ✅ 已就绪 |
| 登录流程可用 | POST /api/auth/login → JWT → Dashboard | 无（最前端） | ✅ 已就绪（MSW mock） |
| GraphQL 查询可执行 | DashboardQuery/ClassesQuery/MeQuery/ViewportsQuery/ClassQuery 返回数据 | 无（最前端） | ✅ 已就绪（MSW mock） |
| P3 扩展 Query 可执行 | ClassStudents/ClassExams/ClassHomework/ExamGrades + UpdateUser Mutation | 无（最前端） | ✅ 已就绪（MSW mock） |
| parent-portal Remote 接入点 | MF remotes 配置就绪 | parent-portal（ai15 P4） | ⏳ P4 启用 |
| /api/health + /api/ready | k8s livenessProbe + readinessProbe 端点 | infra（部署） | ✅ 已就绪 |
### §4.3 P2 交付物完成清单
- ✅ packages 骨架（ui-tokens/ui-components/hooks，批次 0.15）
- ✅ NextFederationPlugin 配置（exposes AppShell + GraphQLProvider + hooks + UI 组件，shared react/urql/graphql/@edu/* singleton）
- ✅ GraphQLProvider + urql client 单例（Shell 暴露，Remote 复用，§2.17 方案 A）
- ✅ AppShell（Layout + 侧边栏 + 路由守卫 + ErrorBoundary + 设计令牌三层 + GraphQL ViewportsQuery + MeQuery + usePermission）
- ✅ 登录页（POST /api/auth/login → JWT 存 localStorage，F12）
- ✅ 权限上下文（usePermission + buildPermissionContext，权限点 `<RESOURCE>_<ACTION>` F7）
- ✅ Dashboard 框架（GraphQL DashboardQuery + 统计卡片）
- ✅ 班级列表页（GraphQL ClassesQuery）
- ✅ 学生列表页（GraphQL ClassStudentsQuery，P3 扩展 MSW mock）
- ✅ 个人设置页（GraphQL MeQuery 只读展示）
- ✅ 考试/作业/成绩页面（GraphQL ClassExams/ClassHomework/ExamGrades，P3 扩展 MSW mock）
- ✅ MSW mock 层（handlers + fixtures + browser/server + initMocks + providers 集成 + mockServiceWorker.js）
- ✅ /api/health + /api/ready 路由（liveness + readiness）
- ✅ Dockerfile 端口 3000→4000 + 健康检查路径更新
- ✅ .env.example 添加 teacher-portal 变量（NEXT_PUBLIC_TEACHER_BFF_GRAPHQL_URL / NEXT_PUBLIC_API_MOCKING / NEXT_PUBLIC_MF_ENABLED / API_GATEWAY_URL）
- ✅ 质量校验通过（lint + typecheck 零错误）
- ✅ arch.db 已更新（arch:scan：TS 14 模块 / 343 符号 / Proto 138 契约）
---

58
docs/troubleshooting/known-issues.md
View File

@@ -406,29 +406,41 @@
### 2.12 teacher-portal（微前端宿主，P1 测试页）
| 场景 | 技术/规则 |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| P1 测试页 | 单一 Next.js 应用，验证 classes CRUD 端到端链路 |
| API 调用 | `fetch(${API_BASE}/api/v1/classes)` + `Authorization: Bearer ${TEST_JWT}` |
| P1 测试 JWT | 开发工具生成 HS256 token，P2 起由 IAM 签发 RS256 |
| P2 Module Federation | next.config.js 配置，按场景域分 4 个稳定 portal |
| P2 路由组 + AppShell | `app/(app)/layout.tsx` 用 AppShell 包裹受保护页；`/login` 与 `/` 不套壳 |
| P2 真实 JWT | 登录后 token 存 localStorage，`authHeaders()` 读 `Bearer ${getToken()}` |
| P2 视口驱动侧边栏 | AppShell fetch `/teacher/viewports` 渲染左侧导航，active 路由高亮 |
| P2 根路径重定向 | `app/page.tsx` 客户端组件 `router.replace(isAuthenticated() ? '/dashboard' : '/login')` |
| fetch headers 类型 | `authHeaders(): Record<string, string>` 显式标注，避免 `{}` 与 `HeadersInit` 不兼容 |
| P2 MF Shell+Remote 架构 | teacher-portal:**4000** 为 Shell，student:**4001**/parent:**4002**/admin:**4003** 为 Remote（004 §1.2 + coord final §F1）；MF 暴露 **AppShell 整体**（coord final §F10），各 Remote 自行决定内部布局 |
| P2 统一 API 请求层 | ApiClient 封装 401 自动刷新 token 轮转 + ActionState `{success,data,error:{code,message,details?,traceId}}` 解析 + 错误码前缀路由 i18n + trace_id 透传；**P2 起对接 GraphQL**（urql/apollo，coord final §F9/B1） |
| P2 统一 API 请求层 | ApiClient 封装 401 自动刷新 token 轮转 + ActionState `{success,data,error}` 解析 + 错误码前缀路由 i18n，替代页面级 `authHeaders()+fetch` 重复 |
| P2 设计令牌三层模型 | primitive（原始色板）→ semantic-light/dark（语义）→ tailwind-theme（`@theme inline` 暴露 `bg-*`）；ESLint `no-restricted-syntax` 禁 `#hex` + `design-tokens/no-hardcoded-fonts` 禁字面量字体（§3.10） |
| P2 4 端错误码前缀对齐 | **BFF_TEACHER\_=teacher-bff / BFF_STUDENT\_=student-bff / BFF_PARENT\_=parent-bff**（coord final §B5，统一 `BFF_XXX_` 风格）；admin-bff 待 P6 定；前端按前缀路由 i18n key |
| P2 4 端错误码前缀对齐 | TP_=teacher-bff / SP_=student-bff / PP_=parent-bff / AP_=admin-bff，前端按前缀路由 i18n key |
| P2 i18n key 命名 | **统一 `error.<service>.<code_snake>`**（如 error.iam.invalid_credentials、error.bffTeacher.validation_error，coord final §F4）；翻译文件按域分 namespace |
| P2 权限点命名风格 | **统一 `<RESOURCE>_<ACTION>`**（如 DASHBOARD_VIEW、EXAM_READ、GRADE_READ），数据范围用后缀 `_OWN`/`_CHILD`（如 GRADE_READ_CHILD，coord final §F7） |
| P2 Token 存储 | **P2 用 localStorage**（accessToken + refreshToken，coord final §F12）；httpOnly Cookie + CSRF Token **P6 单独评估**（非分阶段迁移，P2 直接采用最终方案的当前阶段形态） |
| P2 packages 归属 | **ai13 维护** packages/ui-tokens、ui-components、hooks（coord final §F8）；coord 仅维护 shared-ts、contracts；ai13 需建立这 3 个共享包 |
| P2 GraphQL 客户端 | **P2 起前端用 urql 或 apollo**（coord final §F9），对接 teacher-bff GraphQL Yoga + DataLoader；废弃 REST fetch 模式；ApiClient 适配 GraphQL 操作类型（query/mutation/subscription） |
| P2 视口端点对齐 | **GET /iam/permissions/effective**（非 /iam/effective-permissions，coord final §F6/I8）+ GET /iam/viewports + GET /iam/roles；parent 子女切换 POST /parent/children/:childId/select |
| 场景 | 技术/规则 |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| P1 测试页 | 单一 Next.js 应用，验证 classes CRUD 端到端链路 |
| API 调用 | `fetch(${API_BASE}/api/v1/classes)` + `Authorization: Bearer ${TEST_JWT}` |
| P1 测试 JWT | 开发工具生成 HS256 token，P2 起由 IAM 签发 RS256 |
| P2 Module Federation | next.config.js 配置，按场景域分 4 个稳定 portal |
| P2 路由组 + AppShell | `app/(app)/layout.tsx` 用 AppShell 包裹受保护页；`/login` 与 `/` 不套壳 |
| P2 真实 JWT | 登录后 token 存 localStorage，`authHeaders()` 读 `Bearer ${getToken()}` |
| P2 视口驱动侧边栏 | AppShell fetch `/teacher/viewports` 渲染左侧导航，active 路由高亮 |
| P2 根路径重定向 | `app/page.tsx` 客户端组件 `router.replace(isAuthenticated() ? '/dashboard' : '/login')` |
| fetch headers 类型 | `authHeaders(): Record<string, string>` 显式标注，避免 `{}` 与 `HeadersInit` 不兼容 |
| P2 MF Shell+Remote 架构 | teacher-portal:**4000** 为 Shell，student:**4001**/parent:**4002**/admin:**4003** 为 Remote（004 §1.2 + coord final §F1）；MF 暴露 **AppShell 整体**（coord final §F10），各 Remote 自行决定内部布局 |
| P2 统一 API 请求层 | ApiClient 封装 401 自动刷新 token 轮转 + ActionState `{success,data,error:{code,message,details?,traceId}}` 解析 + 错误码前缀路由 i18n + trace_id 透传；**P2 起对接 GraphQL**（urql/apollo，coord final §F9/B1） |
| P2 统一 API 请求层 | ApiClient 封装 401 自动刷新 token 轮转 + ActionState `{success,data,error}` 解析 + 错误码前缀路由 i18n，替代页面级 `authHeaders()+fetch` 重复 |
| P2 设计令牌三层模型 | primitive（原始色板）→ semantic-light/dark（语义）→ tailwind-theme（`@theme inline` 暴露 `bg-*`）；ESLint `no-restricted-syntax` 禁 `#hex` + `design-tokens/no-hardcoded-fonts` 禁字面量字体（§3.10） |
| P2 4 端错误码前缀对齐 | **BFF_TEACHER\_=teacher-bff / BFF_STUDENT\_=student-bff / BFF_PARENT\_=parent-bff**（coord final §B5，统一 `BFF_XXX_` 风格）；admin-bff 待 P6 定；前端按前缀路由 i18n key |
| P2 4 端错误码前缀对齐 | TP_=teacher-bff / SP_=student-bff / PP_=parent-bff / AP_=admin-bff，前端按前缀路由 i18n key |
| P2 i18n key 命名 | **统一 `error.<service>.<code_snake>`**（如 error.iam.invalid_credentials、error.bffTeacher.validation_error，coord final §F4）；翻译文件按域分 namespace |
| P2 权限点命名风格 | **统一 `<RESOURCE>_<ACTION>`**（如 DASHBOARD_VIEW、EXAM_READ、GRADE_READ），数据范围用后缀 `_OWN`/`_CHILD`（如 GRADE_READ_CHILD，coord final §F7） |
| P2 Token 存储 | **P2 用 localStorage**（accessToken + refreshToken，coord final §F12）；httpOnly Cookie + CSRF Token **P6 单独评估**（非分阶段迁移，P2 直接采用最终方案的当前阶段形态） |
| P2 packages 归属 | **ai13 维护** packages/ui-tokens、ui-components、hooks（coord final §F8）；coord 仅维护 shared-ts、contracts；ai13 需建立这 3 个共享包 |
| P2 GraphQL 客户端 | **P2 起前端用 urql 或 apollo**（coord final §F9），对接 teacher-bff GraphQL Yoga + DataLoader；废弃 REST fetch 模式；ApiClient 适配 GraphQL 操作类型（query/mutation/subscription） |
| P2 视口端点对齐 | **GET /iam/permissions/effective**（非 /iam/effective-permissions，coord final §F6/I8）+ GET /iam/viewports + GET /iam/roles；parent 子女切换 POST /parent/children/:childId/select |
| P2 MSW mock 层 | `src/mocks/` 含 handlers.ts（拦截 /api/auth/login + /api/v1/teacher/graphql）+ fixtures/*.ts + browser.ts（setupWorker）+ server.ts（setupServer）+ index.ts（initMocks 按 NEXT_PUBLIC_API_MOCKING=enabled 启用） |
| P2 MSW worker 脚本生成 | `npx msw init public/` 生成 mockServiceWorker.js 静态文件；package.json 自动添加 `msw.workerDirectory` 配置；必须在 teacher-portal 目录下执行（msw 在 devDependencies） |
| P2 MSW providers 集成 | GraphQLProvider 内 `initMocks()` ready 前返回 null 避免 GraphQL 请求未拦截；server.ts `onUnhandledRequest: "bypass"` 放行非 mock 请求 |
| P2 urql useQuery 类型 | urql useQuery 返回 data 类型推断不足，map 回调参数隐式 any；需 `import type { XxxItem } from "@/lib/graphql"` + `(data.xxx as XxxItem[]).map(...)` 显式断言 |
| P2 Suspense + useSearchParams | Next.js App Router 中 useSearchParams 必须包裹 `<Suspense>`，否则构建报错；students/exams/homework/grades 页面均用 `Suspense fallback={<Loading/>}` 包裹 StudentsContent |
| P2 DataScope 类型对齐 | graphql.ts 的 DataScope 必须与 hooks/types.ts 的 DataScope 完全一致（`"SELF" \| "CLASS" \| "GRADE" \| "SCHOOL" \| "DISTRICT" \| "ALL"`，ARB-001 §1.2 schema），否则 buildPermissionContext 返回类型不匹配 |
| P2 TS4114 override | tsconfig.base.json `noImplicitOverride: true` 下，React.Component 子类的 state/componentDidCatch/render 必须加 `override` 修饰符 |
| P2 cn.ts null vs undefined | `match ? match[1] : null` 在 noUncheckedIndexedAccess 下返回 `string \| undefined`，与 `string \| null` 不兼容；改用 `match?.[1] ?? null` |
| P2 AppShell GraphQL 化 | AppShell 从 REST `/teacher/viewports` 改为 GraphQL `ViewportsQuery` + `MeQuery`；权限上下文从 localStorage 读取 + usePermission 注入；视口按 requiredPermission 过滤 |
| P2 健康检查路由 | `app/api/health/route.ts`（liveness）+ `app/api/ready/route.ts`（readiness）均 `export const dynamic = "force-dynamic"`，返回 NextResponse.json；Dockerfile HEALTHCHECK 指向 :4000/api/health |
| P2 Dockerfile 端口对齐 | teacher-portal 端口 3000→4000（004 §1.2）；Dockerfile `ENV PORT=4000` + `EXPOSE 4000` + `CMD next start -p 4000` + HEALTHCHECK `http://localhost:4000/api/health` |
| P2 MSW GraphQL 路由 | handlers.ts `http.post("*/api/v1/teacher/graphql")` 按 operationName switch 路由；未传 operationName 时从 query 文本正则提取 `/(?:query\|mutation)\s+(\w+)/` 兜底 |
### 2.13 parent-portal（家长端微前端 Remote，P4）

3
packages/hooks/package.json
View File

@@ -14,7 +14,8 @@
},
"peerDependencies": {
"react": "^18.3.0",
"react-dom": "^18.3.0"
"react-dom": "^18.3.0",
"urql": "^2.2.0"
},
"devDependencies": {
"@types/react": "^18.3.0",

6
packages/hooks/src/index.ts
View File

@@ -51,6 +51,12 @@ export type { UseToastReturn } from "./use-toast.js";
export { useTraceId } from "./use-trace-id.js";
export type { UseTraceIdReturn } from "./use-trace-id.js";
export {
useGraphQLClient,
GraphQLClientContext,
} from "./use-graphql-client.js";
export type { UseGraphQLClientReturn } from "./use-graphql-client.js";
// 共享类型
export type {
UserSession,

5
packages/hooks/src/types.ts
View File

@@ -18,10 +18,11 @@ export interface UserSession {
}
/**
* 数据范围（对齐 iam DataScope 6 级）
* 数据范围（对齐 ARB-001 §1.2 schema DataScope enum）
* 与 apps/teacher-portal/src/lib/graphql.ts DataScope 保持一致
*/
export type DataScope =
"ALL" | "SCHOOL" | "GRADE" | "CLASS" | "SUBJECT" | "SELF";
"SELF" | "CLASS" | "GRADE" | "SCHOOL" | "DISTRICT" | "ALL";
/**
* 权限点检查结果

53
packages/hooks/src/use-graphql-client.ts Normal file
View File

@@ -0,0 +1,53 @@
import { useContext, useMemo } from "react";
import type { Client } from "urql";
/**
* useGraphQLClient - 获取 urql client 单例
*
* 用途：从 Shell 注入的 GraphQLProvider Context 中获取 urql client。
* 总裁裁决 §2.17 方案 A：Shell（teacher-portal）暴露 GraphQLProvider，
* Remote（student/parent/admin）复用同一 client 单例，避免多实例 + 缓存不一致。
*
* 注意：本 hook 必须在 GraphQLProvider 内部调用，否则抛出错误。
*
* @example
* const client = useGraphQLClient();
* const [result] = useQuery({ query: DashboardQuery });
*
* MF 暴露：ARB-002 §2.2 exposes './useGraphQLClient'
*/
// GraphQLClientContext 由 Shell（apps/teacher-portal/src/app/providers.tsx）创建并注入。
// 此处通过 createContext 占位，Shell 在初始化时通过 Provider value 覆盖。
// 为避免 hooks 包直接依赖 urql（peerDependency），Context 值类型用 Client（urql 类型）。
// urql 在 apps/* 的 dependencies 中，通过 peerDependencies 声明。
import { createContext } from "react";
/**
* GraphQL Client Context
*
* Shell（teacher-portal）通过 <Context.Provider value={client}> 注入。
* Remote（student/parent/admin-portal）通过 MF shared 复用同一 Context 实例。
*/
export const GraphQLClientContext = createContext<Client | null>(null);
GraphQLClientContext.displayName = "GraphQLClientContext";
export interface UseGraphQLClientReturn {
/** urql client 单例 */
client: Client;
}
export function useGraphQLClient(): UseGraphQLClientReturn {
const client = useContext(GraphQLClientContext);
if (!client) {
throw new Error(
"useGraphQLClient 必须在 GraphQLProvider 内部调用。" +
"请确保组件树被 <GraphQLProvider> 包裹（apps/teacher-portal/src/app/providers.tsx）。",
);
}
return useMemo(() => ({ client }), [client]);
}

6
packages/ui-components/src/error-boundary.tsx
View File

@@ -29,13 +29,13 @@ export class ErrorBoundary extends Component<
ErrorBoundaryProps,
ErrorBoundaryState
> {
state: ErrorBoundaryState = { error: null };
override state: ErrorBoundaryState = { error: null };
static getDerivedStateFromError(error: Error): ErrorBoundaryState {
return { error };
}
componentDidCatch(error: Error, info: ErrorInfo): void {
override componentDidCatch(error: Error, info: ErrorInfo): void {
this.props.onError?.(error, info);
}
@@ -44,7 +44,7 @@ export class ErrorBoundary extends Component<
this.setState({ error: null });
};
render(): ReactNode {
override render(): ReactNode {
const { error } = this.state;
const { children, fallback } = this.props;

2
packages/ui-components/src/utils/cn.ts
View File

@@ -79,5 +79,5 @@ function getTailwindPrefix(token: string): string | null {
const match = token.match(
/^(bg|text|p|m|px|py|mx|my|w|h|min-h|min-w|border|rounded|shadow|font|leading|tracking|gap|space|flex|grid|col|row|inset|top|right|bottom|left|z|opacity|transition|duration|delay|animate|hover|focus|sm|md|lg|xl|2xl)-/,
);
return match ? match[1] : null;
return match?.[1] ?? null;
}

13
packages/ui-tokens/package.json
View File

@@ -4,5 +4,16 @@
"private": true,
"type": "module",
"main": "./src/index.ts",
"types": "./src/index.ts"
"types": "./src/index.ts",
"exports": {
".": {
"types": "./src/index.ts",
"default": "./src/index.ts"
},
"./primitive.css": "./src/primitive.css",
"./semantic-light.css": "./src/semantic-light.css",
"./semantic-dark.css": "./src/semantic-dark.css",
"./tailwind-theme.css": "./src/tailwind-theme.css",
"./all.css": "./src/all.css"
}
}

13
packages/ui-tokens/src/all.css Normal file
View File

@@ -0,0 +1,13 @@
/**
* ui-tokens 全量样式入口
*
* 导入顺序：Layer 1 Primitive → Layer 2 Semantic（light + dark）→ Layer 3 Tailwind
*
* 用法（apps/teacher-portal/src/app/globals.css）：
* @import '@edu/ui-tokens/all.css';
*/
@import './primitive.css';
@import './semantic-light.css';
@import './semantic-dark.css';
@import './tailwind-theme.css';

112
packages/ui-tokens/src/primitive.css Normal file
View File

@@ -0,0 +1,112 @@
/**
* Layer 1: Primitive Tokens（原始色板/字号/间距/阴影）
*
* 业务代码不直接引用本层令牌，仅 Layer 2 Semantic 引用。
* 维护者：ai13（teacher-portal）
* 关联：project_rules §3.10 设计令牌规范
*
* 命名规范：
* - 颜色：--color-<hue>-<level>（HSL 分量，供 Layer 2 组合）
* - 字号：--font-size-<n>（1-9 阶梯）
* - 间距：--space-<n>（4px 基准阶梯）
* - 阴影：--shadow-<n>
* - 字重：--font-weight-<name>
* - 圆角：--radius-<name>
*/
:root {
/* ============ 颜色原始色板（HSL 分量，非完整颜色） ============ */
/* 中性色（纸张/墨色） */
--color-paper-h: 40;
--color-paper-s: 20%;
--color-paper-l-50: 50%;
--color-paper-l-98: 98%;
--color-paper-l-99: 99%;
--color-ink-h: 25;
--color-ink-s: 3%;
--color-ink-l-15: 15%;
--color-ink-l-45: 45%;
--color-ink-l-60: 60%;
/* 强调色（深蓝） */
--color-accent-h: 220;
--color-accent-s: 60%;
--color-accent-l-35: 35%;
--color-accent-l-50: 50%;
/* 分隔线（暖灰） */
--color-rule-h: 30;
--color-rule-s: 10%;
--color-rule-l-85: 85%;
--color-rule-l-90: 90%;
/* 语义原始色 */
--color-success-h: 142;
--color-success-s: 71%;
--color-success-l-45: 45%;
--color-warning-h: 38;
--color-warning-s: 92%;
--color-warning-l-50: 50%;
--color-danger-h: 0;
--color-danger-s: 84%;
--color-danger-l-60: 60%;
--color-info-h: 199;
--color-info-s: 89%;
--color-info-l-48: 48%;
/* ============ 字号阶梯（1-9，1 最小 9 最大） ============ */
--font-size-1: 0.75rem; /* 12px - 辅助说明 */
--font-size-2: 0.875rem; /* 14px - 次要正文 */
--font-size-3: 1rem; /* 16px - 正文 body */
--font-size-4: 1.125rem; /* 18px - 强调正文 */
--font-size-5: 1.25rem; /* 20px - 小标题 */
--font-size-6: 1.5rem; /* 24px - 区块标题 */
--font-size-7: 1.875rem; /* 30px - 页面标题 */
--font-size-8: 2.25rem; /* 36px - Hero */
--font-size-9: 3rem; /* 48px - 大数字 */
/* ============ 间距阶梯（4px 基准） ============ */
--space-1: 0.25rem; /* 4px */
--space-2: 0.5rem; /* 8px */
--space-3: 0.75rem; /* 12px */
--space-4: 1rem; /* 16px */
--space-5: 1.25rem; /* 20px */
--space-6: 1.5rem; /* 24px */
--space-8: 2rem; /* 32px */
--space-10: 2.5rem; /* 40px */
--space-12: 3rem; /* 48px */
--space-16: 4rem; /* 64px */
--space-20: 5rem; /* 80px */
/* ============ 阴影 ============ */
--shadow-1: 0 1px 2px 0 hsl(25 3% 15% / 0.05);
--shadow-2: 0 1px 3px 0 hsl(25 3% 15% / 0.1), 0 1px 2px -1px hsl(25 3% 15% / 0.1);
--shadow-3: 0 4px 6px -1px hsl(25 3% 15% / 0.1), 0 2px 4px -2px hsl(25 3% 15% / 0.1);
--shadow-4: 0 10px 15px -3px hsl(25 3% 15% / 0.1), 0 4px 6px -4px hsl(25 3% 15% / 0.1);
/* ============ 字重 ============ */
--font-weight-regular: 400;
--font-weight-medium: 500;
--font-weight-semibold: 600;
--font-weight-bold: 700;
/* ============ 圆角 ============ */
--radius-sm: 0.25rem; /* 4px */
--radius-md: 0.375rem; /* 6px */
--radius-lg: 0.5rem; /* 8px */
--radius-full: 9999px;
/* ============ 行高 ============ */
--line-height-tight: 1.25;
--line-height-normal: 1.5;
--line-height-relaxed: 1.75;
/* ============ 字间距 ============ */
--letter-spacing-tight: -0.01em;
--letter-spacing-normal: 0;
--letter-spacing-wide: 0.025em;
}

66
packages/ui-tokens/src/semantic-dark.css Normal file
View File

@@ -0,0 +1,66 @@
/**
* Layer 2: Semantic Tokens - Dark Theme（暗色语义令牌）
*
* 维护者：ai13（teacher-portal）
* 关联：project_rules §3.10
*
* 暗色主题覆盖，通过 [data-theme="dark"] 或 prefers-color-scheme: dark 激活。
*/
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
color-scheme: dark;
--bg-paper: hsl(var(--color-ink-h) var(--color-ink-s) var(--color-ink-l-15));
--bg-surface: hsl(var(--color-ink-h) var(--color-ink-s) 20%);
--bg-subtle: hsl(var(--color-ink-h) var(--color-ink-s) 25%);
--color-ink: hsl(var(--color-paper-h) var(--color-paper-s) var(--color-paper-l-98));
--color-ink-muted: hsl(var(--color-paper-h) var(--color-paper-s) 70%);
--color-ink-subtle: hsl(var(--color-paper-h) var(--color-paper-s) 60%);
--color-ink-on-accent: hsl(var(--color-paper-h) var(--color-paper-s) var(--color-paper-l-99));
--color-accent: hsl(var(--color-accent-h) var(--color-accent-s) var(--color-accent-l-50));
--color-accent-hover: hsl(var(--color-accent-h) var(--color-accent-s) 60%);
--color-accent-subtle: hsl(var(--color-accent-h) var(--color-accent-s) 25%);
--color-rule: hsl(var(--color-ink-h) var(--color-ink-s) 25%);
--color-rule-strong: hsl(var(--color-ink-h) var(--color-ink-s) 30%);
--color-border: var(--color-rule);
--color-input-bg: var(--bg-surface);
--shadow-sm: 0 1px 2px 0 hsl(0 0% 0% / 0.3);
--shadow-md: 0 1px 3px 0 hsl(0 0% 0% / 0.4), 0 1px 2px -1px hsl(0 0% 0% / 0.4);
--shadow-lg: 0 4px 6px -1px hsl(0 0% 0% / 0.4), 0 2px 4px -2px hsl(0 0% 0% / 0.4);
--shadow-xl: 0 10px 15px -3px hsl(0 0% 0% / 0.5), 0 4px 6px -4px hsl(0 0% 0% / 0.5);
}
}
[data-theme="dark"] {
color-scheme: dark;
--bg-paper: hsl(var(--color-ink-h) var(--color-ink-s) var(--color-ink-l-15));
--bg-surface: hsl(var(--color-ink-h) var(--color-ink-s) 20%);
--bg-subtle: hsl(var(--color-ink-h) var(--color-ink-s) 25%);
--color-ink: hsl(var(--color-paper-h) var(--color-paper-s) var(--color-paper-l-98));
--color-ink-muted: hsl(var(--color-paper-h) var(--color-paper-s) 70%);
--color-ink-subtle: hsl(var(--color-paper-h) var(--color-paper-s) 60%);
--color-ink-on-accent: hsl(var(--color-paper-h) var(--color-paper-s) var(--color-paper-l-99));
--color-accent: hsl(var(--color-accent-h) var(--color-accent-s) var(--color-accent-l-50));
--color-accent-hover: hsl(var(--color-accent-h) var(--color-accent-s) 60%);
--color-accent-subtle: hsl(var(--color-accent-h) var(--color-accent-s) 25%);
--color-rule: hsl(var(--color-ink-h) var(--color-ink-s) 25%);
--color-rule-strong: hsl(var(--color-ink-h) var(--color-ink-s) 30%);
--color-border: var(--color-rule);
--color-input-bg: var(--bg-surface);
--shadow-sm: 0 1px 2px 0 hsl(0 0% 0% / 0.3);
--shadow-md: 0 1px 3px 0 hsl(0 0% 0% / 0.4), 0 1px 2px -1px hsl(0 0% 0% / 0.4);
--shadow-lg: 0 4px 6px -1px hsl(0 0% 0% / 0.4), 0 2px 4px -2px hsl(0 0% 0% / 0.4);
--shadow-xl: 0 10px 15px -3px hsl(0 0% 0% / 0.5), 0 4px 6px -4px hsl(0 0% 0% / 0.4);
}

82
packages/ui-tokens/src/semantic-light.css Normal file
View File

@@ -0,0 +1,82 @@
/**
* Layer 2: Semantic Tokens - Light Theme（亮色语义令牌）
*
* 业务代码唯一引用入口：业务 TSX/CSS 引用 var(--color-*) / var(--font-*) 等。
* 维护者：ai13（teacher-portal）
* 关联：project_rules §3.10、03-long-term-architecture.md §1.5
*
* 引用 Layer 1 Primitive 组合成完整语义值。
*/
:root {
color-scheme: light;
/* ============ 背景与表面 ============ */
--bg-paper: hsl(var(--color-paper-h) var(--color-paper-s) var(--color-paper-l-98));
--bg-surface: hsl(var(--color-paper-h) var(--color-paper-s) var(--color-paper-l-99));
--bg-subtle: hsl(var(--color-rule-h) var(--color-rule-s) var(--color-rule-l-90));
/* ============ 文字 ============ */
--color-ink: hsl(var(--color-ink-h) var(--color-ink-s) var(--color-ink-l-15));
--color-ink-muted: hsl(var(--color-ink-h) var(--color-ink-s) var(--color-ink-l-45));
--color-ink-subtle: hsl(var(--color-ink-h) var(--color-ink-s) var(--color-ink-l-60));
--color-ink-on-accent: hsl(var(--color-paper-h) var(--color-paper-s) var(--color-paper-l-99));
/* ============ 强调色 ============ */
--color-accent: hsl(var(--color-accent-h) var(--color-accent-s) var(--color-accent-l-35));
--color-accent-hover: hsl(var(--color-accent-h) var(--color-accent-s) var(--color-accent-l-50));
--color-accent-subtle: hsl(var(--color-accent-h) var(--color-accent-s) var(--color-rule-l-90));
/* ============ 分隔线 ============ */
--color-rule: hsl(var(--color-rule-h) var(--color-rule-s) var(--color-rule-l-90));
--color-rule-strong: hsl(var(--color-rule-h) var(--color-rule-s) var(--color-rule-l-85));
/* ============ 语义色 ============ */
--color-success: hsl(var(--color-success-h) var(--color-success-s) var(--color-success-l-45));
--color-warning: hsl(var(--color-warning-h) var(--color-warning-s) var(--color-warning-l-50));
--color-danger: hsl(var(--color-danger-h) var(--color-danger-s) var(--color-danger-l-60));
--color-info: hsl(var(--color-info-h) var(--color-info-s) var(--color-info-l-48));
/* ============ 边框/输入 ============ */
--color-border: var(--color-rule);
--color-border-focus: var(--color-accent);
--color-input-bg: var(--bg-surface);
/* ============ 字体族（通过 var 引用，禁止字面量） ============ */
--font-family-sans: var(--font-inter, system-ui), -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
--font-family-serif: var(--font-fraunces, Georgia), "Times New Roman", serif;
--font-family-mono: var(--font-jetbrains-mono, "SF Mono"), Monaco, Consolas, monospace;
/* ============ 语义字号 ============ */
--font-size-body: var(--font-size-3);
--font-size-small: var(--font-size-2);
--font-size-tiny: var(--font-size-1);
--font-size-heading-1: var(--font-size-7);
--font-size-heading-2: var(--font-size-6);
--font-size-heading-3: var(--font-size-5);
--font-size-display: var(--font-size-9);
--font-size-large-number: var(--font-size-8);
/* ============ 语义间距 ============ */
--space-xs: var(--space-1);
--space-sm: var(--space-2);
--space-md: var(--space-4);
--space-lg: var(--space-6);
--space-xl: var(--space-8);
--space-2xl: var(--space-12);
/* ============ 语义阴影 ============ */
--shadow-sm: var(--shadow-1);
--shadow-md: var(--shadow-2);
--shadow-lg: var(--shadow-3);
--shadow-xl: var(--shadow-4);
/* ============ 语义圆角 ============ */
--radius-default: var(--radius-md);
--radius-card: var(--radius-lg);
--radius-button: var(--radius-md);
/* ============ 过渡 ============ */
--transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
--transition-normal: 200ms cubic-bezier(0.4, 0, 0.2, 1);
}

31
packages/ui-tokens/src/tailwind-theme.css Normal file
View File

@@ -0,0 +1,31 @@
/**
* Layer 3: Tailwind Theme Mapping（Tailwind 主题映射）
*
* 将 Layer 2 Semantic 令牌映射为 Tailwind 类名（bg-* / text-* / font-* 等）。
* 维护者：ai13（teacher-portal）
* 关联：project_rules §3.10、03-long-term-architecture.md §1.5
*
* Tailwind 3.4 通过 tailwind.config.js 的 theme.extend 映射；
* Tailwind 4 将改用 @theme inline 指令（未来升级时本文件可转为 @theme 块）。
*
* 使用方式（业务组件）：
* <div className="bg-paper text-ink font-serif">...</div>
* <p className="text-sm text-ink-muted">...</p>
*
* 对应 tailwind.config.js 中：
* colors: { paper: 'var(--bg-paper)', ink: 'var(--color-ink)', ... }
* fontFamily: { sans: 'var(--font-family-sans)', serif: 'var(--font-family-serif)', ... }
*/
/* 显式引用语义令牌，确保 CSS 变量在构建产物中可用 */
@layer base {
:root {
/* Tailwind 颜色类映射（与 tailwind.config.js theme.extend.colors 对齐） */
--tw-color-paper: var(--bg-paper);
--tw-color-surface: var(--bg-surface);
--tw-color-ink: var(--color-ink);
--tw-color-ink-muted: var(--color-ink-muted);
--tw-color-accent: var(--color-accent);
--tw-color-rule: var(--color-rule);
}
}

1161
pnpm-lock.yaml generated
View File

File diff suppressed because it is too large Load Diff