Merge pull request '考勤请假同步、SSE 修复与学生报告优化' (#59) from codex/ai-a2ui-agent-tools into main

Reviewed-on: #55

.gitignore

@@ -20,6 +20,7 @@ build/
 # 上传文件（合同PDF等敏感文件，不入版本库和部署包）
 uploads/
 backend/uploads/
+data/ai-attachments/
 
 # 日志
 logs/
@@ -54,3 +55,7 @@ apps/admin/dist/
 .claude/
 .omp/
 .superpowers/
+
+# 测试截图产物
+.vitest-attachments/
+**/__screenshots__/

AGENTS.md

@@ -8,3 +8,7 @@ In repositories indexed by CodeGraph (a `.codegraph/` directory exists at the re
 
 If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is the user's decision.
 <!-- CODEGRAPH_END -->
+
+## Ant Design X
+
+修改 AI 助手、SSE 消息、运行时技能、附件或 Agent 工具前，先读取 `docs/skills/ant-design-x/SKILL.md`，优先使用项目已安装的 Ant Design X 组件与 SDK。

README.md

@@ -24,10 +24,10 @@
 ```
 前端 (React + Vite)          后端 (NestJS)           数据库
 ┌─────────────────┐     ┌──────────────────┐     ┌──────────┐
-│ React 19        │     │ NestJS 11        │     │ SQLite   │
-│ Ant Design 6    │────▶│ TypeORM 0.3      │────▶│ (开发)   │
-│ ECharts         │     │ JWT + Passport   │     │ MySQL 8  │
-│ Vite 8          │     │ ExcelJS + PDFKit │     │ (生产)   │
+│ React 19        │     │ NestJS 11        │     │ MySQL 8  │
+│ Ant Design 6    │────▶│ TypeORM 0.3      │────▶│          │
+│ ECharts         │     │ JWT + Passport   │     │          │
+│ Vite 8          │     │ ExcelJS + PDFKit │     │          │
 └─────────────────┘     └──────────────────┘     └──────────┘
 ```
 
@@ -37,6 +37,7 @@
 
 - Node.js >= 18
 - npm >= 9
+- MySQL 8.0
 
 ### 后端启动
 
@@ -93,7 +94,7 @@ docker-compose up -d   # 一键启动 MySQL + 后端 + 前端
 
 | 配置项 | 说明 | 默认值 |
 |--------|------|--------|
-| `DB_TYPE` | 数据库类型 | `mysql` |
+| `DB_TYPE` | 数据库类型（仅支持 MySQL） | `mysql` |
 | `DB_HOST` | 数据库地址 | `localhost` |
 | `DB_PORT` | 数据库端口 | `3306` |
 | `DB_USERNAME` | 数据库用户名 | `dorm_billing` |

apps/admin/nginx.conf

@@ -25,6 +25,22 @@ server {
         add_header Cache-Control "no-cache";
     }
 
+    # SSE 长连接：禁用代理缓冲并放宽读写超时，避免 60s 空闲被掐断
+    location ~ ^/api/(notifications/stream|attendance-records/import/dingtalk/stream|ai/chat/.*/stream)$ {
+        proxy_pass http://backend:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+        add_header X-Accel-Buffering no;
+    }
+
     location /api/ {
         proxy_pass http://backend:3000/api/;
         proxy_set_header Host $host;

apps/admin/package.json

@@ -14,29 +14,44 @@
   },
   "dependencies": {
     "@ant-design/icons": "^6.1.1",
+    "@ant-design/x": "^2.8.0",
+    "@ant-design/x-card": "^2.9.0",
+    "@ant-design/x-markdown": "^2.8.0",
+    "@ant-design/x-sdk": "^2.8.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
+    "@rc-component/upload": "^1.1.1",
+    "@tanstack/react-query": "^5.101.4",
     "antd": "^6.3.6",
     "axios": "^1.15.1",
     "dayjs": "^1.11.20",
     "echarts": "^6.0.0",
-    "echarts-for-react": "^3.0.6",
+    "fast-deep-equal": "^3.1.3",
+    "file-saver": "^2.0.5",
+    "mermaid": "^11.16.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
-    "react-router-dom": "^7.14.1",
-    "tslib": "^2.8.1"
+    "react-router": "^8.3.0",
+    "use-immer": "^0.11.0",
+    "usehooks-ts": "^3.1.1",
+    "zod": "^4.4.3",
+    "zustand": "^5.0.14"
   },
   "devDependencies": {
     "@gongxue/typescript-config": "*",
+    "@tanstack/react-query-devtools": "^5.101.4",
+    "@types/file-saver": "^2.0.7",
     "@types/node": "^24.12.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "@types/react-syntax-highlighter": "^15.5.13",
     "@vitejs/plugin-react": "^6.0.1",
     "@vitest/browser": "^4.1.10",
     "@vitest/browser-playwright": "^4.1.10",
     "@vitest/coverage-v8": "^4.1.10",
     "playwright": "^1.61.1",
+    "rollup-plugin-visualizer": "^7.0.1",
     "typescript": "~6.0.2",
     "vite": "^8.0.9",
     "vitest": "^4.1.10"

apps/admin/src/App.tsx

@@ -1,11 +1,14 @@
 import React, { Suspense, lazy } from 'react';
-import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router';
 import { ConfigProvider, App as AntdApp, Spin } from 'antd';
+import XProvider from '@ant-design/x/es/x-provider';
+import xZhCN from '@ant-design/x/es/locale/zh_CN';
 import zhCN from 'antd/es/locale/zh_CN';
 import MainLayout from './layouts/MainLayout';
 import PermissionRoute from './components/PermissionRoute';
 import DefaultRoute from './components/DefaultRoute';
 import AppMessageBridge from './ui/AppMessageBridge';
+import { useUserStore } from './store/user/userStore';
 
 const LoginPage = lazy(() => import('./pages/Login'));
 const DashboardPage = lazy(() => import('./pages/Dashboard'));
@@ -40,7 +43,7 @@ const IntegrationConfigPage = lazy(() => import('./pages/IntegrationConfig'));
 const AiConfigPage = lazy(() => import('./pages/AiConfig'));
 
 const PrivateRoute: React.FC<{ children: React.ReactNode }> = ({ children }) => {
-  const token = localStorage.getItem('token');
+  const token = useUserStore((state) => state.token);
   return token ? <>{children}</> : <Navigate to="/login" />;
 };
 
@@ -58,9 +61,19 @@ const App: React.FC = () => {
         },
       }}
     >
-      <AntdApp>
-        <AppMessageBridge />
-        <BrowserRouter>
+      <XProvider
+        locale={{ ...zhCN, ...xZhCN }}
+        theme={{
+          token: { colorPrimary: '#007AFF', borderRadius: 10 },
+          components: {
+            Sender: { colorBorder: '#d9d9de' },
+            Bubble: { colorBgContainer: '#f5f7fa' },
+          },
+        }}
+      >
+        <AntdApp>
+          <AppMessageBridge />
+          <BrowserRouter>
           <Suspense
             fallback={
               <div style={{ minHeight: '40vh', display: 'grid', placeItems: 'center' }}>
@@ -330,8 +343,9 @@ const App: React.FC = () => {
               </Route>
             </Routes>
           </Suspense>
-        </BrowserRouter>
-      </AntdApp>
+          </BrowserRouter>
+        </AntdApp>
+      </XProvider>
     </ConfigProvider>
   );
 };

apps/admin/src/api/imports.ts

@@ -0,0 +1,79 @@
+import api from './index';
+import { validateResponse } from '../utils/validate';
+import { importRunEnvelopeSchema } from './schemas';
+import type {
+  ImportPreviewResult,
+  ImportReceipt,
+  ImportRunDetail,
+  ImportStageRequest,
+} from '../components/ImportWizard/types';
+
+interface ApiEnvelope<T> {
+  success: boolean;
+  data: T;
+  message?: string;
+}
+
+export async function createImportRun(
+  file: File,
+  options: {
+    source: 'ai' | 'manual';
+    conversationId?: number;
+    stages?: ImportStageRequest[];
+    mapping?: Record<string, Record<string, string>>;
+  },
+): Promise<ImportRunDetail> {
+  const form = new FormData();
+  form.append('file', file);
+  form.append('source', options.source);
+  if (options.conversationId) form.append('conversationId', String(options.conversationId));
+  if (options.stages?.length) form.append('stages', JSON.stringify(options.stages));
+  if (options.mapping && Object.keys(options.mapping).length > 0) {
+    form.append('mapping', JSON.stringify(options.mapping));
+  }
+  const res = await api.post<ApiEnvelope<ImportRunDetail>>('/imports/runs', form, {
+    headers: { 'Content-Type': 'multipart/form-data' },
+  });
+  return res.data;
+}
+
+export async function getImportRun(runId: string): Promise<ImportRunDetail> {
+  const res = await api.get<ApiEnvelope<ImportRunDetail>>(
+    `/imports/runs/${encodeURIComponent(runId)}`,
+  );
+  return validateResponse<ApiEnvelope<ImportRunDetail>>(importRunEnvelopeSchema, res).data;
+}
+
+export async function previewImportStep(
+  runId: string,
+  stepKey: string,
+  body: { sheets?: string[]; mapping?: Record<string, string> },
+): Promise<ImportPreviewResult> {
+  const res = await api.post<ApiEnvelope<ImportPreviewResult>>(
+    `/imports/runs/${encodeURIComponent(runId)}/steps/${encodeURIComponent(stepKey)}/preview`,
+    body,
+  );
+  return res.data;
+}
+
+export async function commitImportStep(
+  runId: string,
+  stepKey: string,
+  decisions: Array<{ rowId: number; action: 'create' | 'update' | 'skip' }>,
+): Promise<ImportReceipt> {
+  const res = await api.post<ApiEnvelope<ImportReceipt>>(
+    `/imports/runs/${encodeURIComponent(runId)}/steps/${encodeURIComponent(stepKey)}/commit`,
+    { decisions },
+  );
+  return res.data;
+}
+
+export function importErrorReportUrl(runId: string, stepKey?: string): string {
+  const base = import.meta.env.PROD
+    ? '/api'
+    : `http://localhost:${import.meta.env.VITE_API_PORT || 3002}/api`;
+  const params = new URLSearchParams();
+  if (stepKey) params.set('stepKey', stepKey);
+  const query = params.toString();
+  return `${base}/imports/runs/${encodeURIComponent(runId)}/report${query ? `?${query}` : ''}`;
+}

apps/admin/src/api/index.ts

@@ -1,5 +1,6 @@
 import axios, { type AxiosRequestConfig } from 'axios';
-import { clearPermissions } from '../auth/permission-store';
+import { usePermissionStore } from '../store/permission/permissionStore';
+import { useUserStore } from '../store/user/userStore';
 
 const instance = axios.create({
   baseURL: '/api',
@@ -7,7 +8,7 @@ const instance = axios.create({
 });
 
 instance.interceptors.request.use((config) => {
-  const token = localStorage.getItem('token');
+  const token = useUserStore.getState().token;
   if (token) {
     config.headers.Authorization = `Bearer ${token}`;
   }
@@ -20,9 +21,8 @@ instance.interceptors.response.use(
     const isLoginRequest = err.config?.url === '/auth/login' || err.config?.url === 'auth/login';
 
     if (err.response?.status === 401 && !isLoginRequest) {
-      localStorage.removeItem('token');
-      localStorage.removeItem('user');
-      clearPermissions();
+      useUserStore.getState().logout();
+      usePermissionStore.getState().clearPermissions();
       window.location.href = '/login';
     }
     if (err.response?.status === 403) {

apps/admin/src/api/schemas/ai.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+export const aiConfigSchema = z
+  .object({
+    id: z.number(),
+    provider: z.string(),
+    baseUrl: z.string(),
+    hasApiKey: z.boolean(),
+    hasDatabaseKey: z.boolean(),
+    maskedApiKey: z.string().nullable(),
+    keySource: z.enum(['database', 'environment', 'none']),
+    defaultModel: z.string().nullable(),
+    enabled: z.boolean(),
+    supportsVision: z.boolean(),
+    timeoutMs: z.number(),
+    reasoningEffort: z.string().nullable(),
+    verified: z.boolean(),
+    lastTestedAt: z.string().nullable(),
+    lastTestLatencyMs: z.number().nullable(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+  })
+  .passthrough();
+
+export const aiConfigEnvelopeSchema = z
+  .object({ success: z.boolean(), data: aiConfigSchema })
+  .passthrough();
+
+/** 导入任务 */

apps/admin/src/api/schemas/attendance.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+
+export const attendanceRecordSchema = z
+  .object({
+    id: z.number(),
+    studentId: z.number(),
+    classId: z.number().nullable(),
+    attendanceDate: z.string(),
+    session: z.string(),
+    status: z.string(),
+    remark: z.string().nullable(),
+    createdAt: z.string(),
+    student: z
+      .object({ id: z.number(), name: z.string(), studentNo: z.string().nullable().optional() })
+      .passthrough(),
+    class: z.object({ id: z.number(), name: z.string() }).passthrough().nullable(),
+  })
+  .passthrough();
+
+export const attendanceRecordsResponseSchema = z
+  .object({ list: z.array(attendanceRecordSchema), total: z.number() })
+  .passthrough();
+
+export const attendanceSummarySchema = z
+  .object({
+    total: z.number(),
+    present: z.number(),
+    late: z.number(),
+    absent: z.number(),
+    leave: z.number(),
+    pending: z.number(),
+  })
+  .passthrough();
+
+export const dingTalkSyncStatusSchema = z
+  .object({
+    lastPulledAt: z.string().nullable(),
+    action: z.string().nullable(),
+    username: z.string().nullable(),
+    detail: z.string().nullable(),
+  })
+  .passthrough();
+
+/** 学生档案聚合 */
+
+export const attendanceClassOptionSchema = z
+  .object({ classId: z.number(), className: z.string() })
+  .passthrough();
+
+export const attendanceClassOptionsSchema = z.array(attendanceClassOptionSchema);
+
+export const attendanceAlertSchema = z
+  .object({ id: z.number(), type: z.string(), message: z.string() })
+  .passthrough();
+
+export const attendanceAlertsSchema = z.array(attendanceAlertSchema);
+
+export const attendancePeriodSchema = z
+  .object({
+    periodKey: z.string(),
+    label: z.string(),
+    startTime: z.string(),
+    endTime: z.string(),
+    sortOrder: z.number(),
+    enabled: z.boolean(),
+  })
+  .passthrough();
+
+export const attendancePeriodsSchema = z.array(attendancePeriodSchema);
+
+export const attendanceScheduleOptionSchema = z
+  .object({
+    id: z.number(),
+    subject: z.string(),
+    startTime: z.string(),
+    endTime: z.string(),
+  })
+  .passthrough();
+
+export const attendanceScheduleOptionsSchema = z.array(attendanceScheduleOptionSchema);

apps/admin/src/api/schemas/core.ts

@@ -0,0 +1,330 @@
+import { z } from 'zod';
+
+export const studentProfileAggregateSchema = z
+  .object({
+    student: z
+      .object({
+        id: z.number(),
+        name: z.string(),
+        phone: z.string(),
+        idNumber: z.string(),
+        studentNo: z.string(),
+        status: z.string(),
+      })
+      .passthrough(),
+    profile: z.record(z.string(), z.unknown()).nullable(),
+    enrollments: z.array(z.record(z.string(), z.unknown())),
+    examScores: z.array(z.record(z.string(), z.unknown())),
+    learningRecords: z.array(z.record(z.string(), z.unknown())),
+    result: z.record(z.string(), z.unknown()).nullable(),
+    attachments: z.array(z.record(z.string(), z.unknown())),
+    attendances: z.array(z.record(z.string(), z.unknown())),
+  })
+  .passthrough();
+
+/** 权限树 */
+export const permissionItemSchema = z
+  .object({ id: z.number(), code: z.string(), name: z.string(), group: z.string() })
+  .passthrough();
+
+export const permissionTreeSchema = z.array(
+  z.object({ group: z.string(), permissions: z.array(permissionItemSchema) }).passthrough(),
+);
+
+/** 机构 */
+export const organizationSchema = z
+  .object({ id: z.number(), name: z.string(), code: z.string(), status: z.string() })
+  .passthrough();
+
+export const organizationsSchema = z.array(organizationSchema);
+
+export const organizationOptionSchema = z
+  .object({ id: z.number(), name: z.string() })
+  .passthrough();
+
+export const organizationOptionsSchema = z.array(organizationOptionSchema);
+
+/** 账单 */
+export const billSchema = z
+  .object({
+    id: z.number(),
+    status: z.string(),
+    student: z
+      .object({ id: z.number(), name: z.string() })
+      .passthrough()
+      .nullable()
+      .optional(),
+  })
+  .passthrough();
+
+export const billsSchema = z.array(billSchema);
+
+/** 班级 */
+export const classSchema = z
+  .object({
+    id: z.number(),
+    name: z.string(),
+    code: z.string(),
+    classType: z.string(),
+    isArchived: z.boolean(),
+  })
+  .passthrough();
+
+export const classesSchema = z.array(classSchema);
+
+/** 教师 */
+export const teacherSchema = z
+  .object({ id: z.number(), username: z.string(), name: z.string() })
+  .passthrough();
+
+export const teacherListSchema = z
+  .object({ list: z.array(teacherSchema), total: z.number() })
+  .passthrough();
+
+/** 角色 / 用户 */
+export const roleSchema = z
+  .object({ id: z.number(), name: z.string(), status: z.number() })
+  .passthrough();
+
+export const rolesSchema = z.array(roleSchema);
+
+export const userSchema = z
+  .object({ id: z.number(), username: z.string(), name: z.string() })
+  .passthrough();
+
+export const usersSchema = z.array(userSchema);
+
+/** 操作日志 */
+export const operationLogSchema = z
+  .object({
+    id: z.number(),
+    module: z.string(),
+    action: z.string(),
+    username: z.string(),
+    createdAt: z.string(),
+  })
+  .passthrough();
+
+export const operationLogsSchema = z
+  .object({ data: z.array(operationLogSchema), total: z.number() })
+  .passthrough();
+
+/** 通知 */
+export const notificationSchema = z
+  .object({
+    id: z.number(),
+    type: z.string(),
+    title: z.string(),
+    content: z.string(),
+    isRead: z.boolean(),
+    createdAt: z.string(),
+  })
+  .passthrough();
+
+export const notificationsSchema = z.array(notificationSchema);
+
+/** 考勤机 / 教室选项 */
+export const attendanceDeviceSchema = z
+  .object({ id: z.number(), deviceSn: z.string(), deviceName: z.string(), status: z.string() })
+  .passthrough();
+
+export const attendanceDevicesSchema = z.array(attendanceDeviceSchema);
+
+export const classroomOptionSchema = z
+  .object({ id: z.number(), name: z.string() })
+  .passthrough();
+
+export const classroomOptionsSchema = z.array(classroomOptionSchema);
+
+/** 宿舍 / 教室 */
+export const roomSchema = z
+  .object({
+    id: z.number(),
+    roomNumber: z.string(),
+    status: z.string(),
+    currentCount: z.number(),
+    capacity: z.number(),
+  })
+  .passthrough();
+
+export const roomsOverviewSchema = z.array(roomSchema);
+
+export const classroomSchema = z
+  .object({
+    id: z.number(),
+    name: z.string(),
+    building: z.string().optional(),
+    status: z.string().optional(),
+  })
+  .passthrough();
+
+export const classroomsSchema = z.array(classroomSchema);
+
+/** 学生 */
+export const studentSchema = z
+  .object({
+    id: z.number(),
+    name: z.string(),
+    studentNo: z.string().optional(),
+    status: z.string(),
+  })
+  .passthrough();
+
+export const studentsSchema = z.array(studentSchema);
+
+/** 押金 */
+export const depositSchema = z
+  .object({ id: z.number(), studentId: z.number(), amount: z.number(), status: z.string() })
+  .passthrough();
+
+export const depositsSchema = z.array(depositSchema);
+
+export const depositStudentLookupSchema = z
+  .object({ studentId: z.number(), name: z.string().optional() })
+  .passthrough();
+
+export const depositStudentLookupsSchema = z.array(depositStudentLookupSchema);
+
+export const eligibleStudentSchema = z
+  .object({ studentId: z.number(), roomId: z.number(), roomNumber: z.string() })
+  .passthrough();
+
+export const eligibleStudentsSchema = z.array(eligibleStudentSchema);
+
+/** 钱包 */
+export const walletSchema = z
+  .object({
+    studentId: z.number(),
+    studentName: z.string(),
+    balance: z.number(),
+    outstandingAmount: z.number(),
+  })
+  .passthrough();
+
+export const walletsSchema = z.array(walletSchema);
+
+export const roomTypesSchema = z.array(z.string());
+
+/** 费用 */
+export const expenseRecordSchema = z
+  .object({
+    id: z.number(),
+    expenseType: z.string(),
+    amount: z.number(),
+    status: z.string().optional(),
+  })
+  .passthrough();
+
+export const expenseRecordsSchema = z.array(expenseRecordSchema);
+
+export const expenseLookupsSchema = z
+  .object({
+    rooms: z.array(z.record(z.string(), z.unknown())),
+    students: z.array(z.record(z.string(), z.unknown())),
+  })
+  .passthrough();
+
+export const expenseTypesSchema = z.array(
+  z.object({ code: z.string(), name: z.string(), category: z.string() }),
+);
+
+/** 入住 */
+export const occupancySchema = z
+  .object({
+    id: z.number(),
+    studentId: z.number(),
+    roomId: z.number(),
+    checkInDate: z.string().optional(),
+    status: z.string().optional(),
+  })
+  .passthrough();
+
+export const occupanciesSchema = z.array(occupancySchema);
+
+/** 排课 */
+export const scheduleLookupsSchema = z
+  .object({
+    classrooms: z.array(classroomOptionSchema),
+    classes: z.array(z.object({ id: z.number(), name: z.string() }).passthrough()),
+  })
+  .passthrough();
+
+export const weeklyScheduleSchema = z.record(
+  z.string(),
+  z.record(
+    z.string(),
+    z.array(
+      z
+        .object({
+          id: z.number().nullable(),
+          classId: z.number().nullable(),
+          classroomId: z.number(),
+          weekDay: z.number(),
+          startTime: z.string(),
+          endTime: z.string(),
+        })
+        .passthrough(),
+    ),
+  ),
+);
+
+/** 租赁订单 */
+export const rentalSchema = z
+  .object({
+    id: z.number(),
+    classroom: z
+      .object({ id: z.number(), name: z.string() })
+      .passthrough()
+      .nullable()
+      .optional(),
+    lesseeOrganization: z
+      .object({ id: z.number(), name: z.string() })
+      .passthrough()
+      .nullable()
+      .optional(),
+    status: z.string().optional(),
+  })
+  .passthrough();
+
+export const rentalsSchema = z.array(rentalSchema);
+
+/** 考试 */
+export const examSchema = z
+  .object({
+    id: z.number(),
+    examName: z.string(),
+    examType: z.string(),
+    isArchived: z.boolean(),
+  })
+  .passthrough();
+
+export const examsSchema = z.array(examSchema);
+
+export const examDetailSchema = z
+  .object({ id: z.number(), examName: z.string() })
+  .passthrough();
+
+export const classOptionSchema = z
+  .object({ id: z.number(), name: z.string() })
+  .passthrough();
+
+export const classOptionsSchema = z.array(classOptionSchema);
+
+export const studentFilterLookupsSchema = z
+  .object({
+    classes: z.array(z.object({ id: z.number(), name: z.string() }).passthrough()),
+    teachers: z.array(z.object({ id: z.number(), name: z.string() }).passthrough()),
+  })
+  .passthrough();
+
+/** 教师工作台 */
+export const teacherWorkspaceSchema = z
+  .object({
+    assignedClasses: z.array(
+      z.object({ classId: z.number(), className: z.string() }).passthrough(),
+    ),
+    todaySchedules: z.array(z.record(z.string(), z.unknown())),
+  })
+  .passthrough();
+
+/** 集成配置 */

apps/admin/src/api/schemas/dashboard.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+
+export const classroomScheduleSchema = z
+  .object({
+    classrooms: z.array(z.record(z.string(), z.unknown())),
+    organizations: z.array(z.record(z.string(), z.unknown())),
+    matrix: z.record(z.string(), z.record(z.string(), z.array(z.record(z.string(), z.unknown())))),
+    summary: z.record(z.string(), z.record(z.string(), z.unknown())),
+    days: z.number().optional(),
+  })
+  .passthrough();
+
+/** Dashboard 统计 */
+export const dashboardStatsSchema = z
+  .object({
+    totalRooms: z.number(),
+    totalStudents: z.number(),
+    occupiedBeds: z.number(),
+    totalCapacity: z.number(),
+    occupancyRate: z.string(),
+    classroomCount: z.number(),
+    classroomOccupancyRate: z.string(),
+    todayAttendanceRate: z.string().optional(),
+    monthlyIncome: z.number(),
+    classCount: z.number(),
+    teacherCount: z.number(),
+    pendingDeposits: z.number(),
+    activeRentals: z.number(),
+    todayPresent: z.number(),
+    occupancyByBuilding: z.array(
+      z.object({ building: z.string(), count: z.string() }).passthrough(),
+    ),
+    attendanceByStatus: z.record(z.string(), z.number()),
+    expenseByType: z.array(z.object({ type: z.string(), total: z.string() }).passthrough()),
+    attendanceTrend: z.array(z.object({ date: z.string(), rate: z.string() }).passthrough()),
+    incomeTrend: z.array(z.object({ month: z.string(), amount: z.number() }).passthrough()),
+  })
+  .passthrough();
+
+export const roomRankingSchema = z.array(
+  z.object({ roomNumber: z.string(), total: z.string() }).passthrough(),
+);
+
+export const classAttendanceRankingSchema = z
+  .object({
+    top: z.array(
+      z
+        .object({ className: z.string(), present: z.number(), total: z.number(), rate: z.number() })
+        .passthrough(),
+    ),
+    bottom: z.array(
+      z
+        .object({ className: z.string(), present: z.number(), total: z.number(), rate: z.number() })
+        .passthrough(),
+    ),
+  })
+  .passthrough();
+
+export const ganttRoomsSchema = z.array(
+  z
+    .object({ roomNumber: z.string(), occupancies: z.array(z.record(z.string(), z.unknown())) })
+    .passthrough(),
+);
+
+export const classroomOccupanciesSchema = z.array(
+  z
+    .object({ name: z.string(), building: z.string(), capacity: z.number(), occupancy: z.number() })
+    .passthrough(),
+);
+
+export const classroomUtilStatsSchema = z
+  .object({
+    totalClassrooms: z.number(),
+    inUseCount: z.number(),
+    utilizationRate: z.string(),
+  })
+  .passthrough();
+
+/** 考勤元数据 */

apps/admin/src/api/schemas/import-run.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+
+export const importSheetMetaSchema = z
+  .object({
+    name: z.string(),
+    headers: z.array(z.string()),
+    rowCount: z.number(),
+    suggestedStepKey: z.string().nullable(),
+  })
+  .passthrough();
+
+export const importStepSummarySchema = z
+  .object({
+    total: z.number(),
+    valid: z.number(),
+    error: z.number(),
+    create: z.number(),
+    update: z.number(),
+    skip: z.number(),
+  })
+  .passthrough()
+  .nullable();
+
+export const importStepDetailSchema = z
+  .object({
+    id: z.number(),
+    stepKey: z.string(),
+    label: z.string(),
+    sheets: z.array(z.string()),
+    status: z.string(),
+    mapping: z.record(z.string(), z.string()),
+    summary: importStepSummarySchema,
+    committedAt: z.string().nullable(),
+  })
+  .passthrough();
+
+export const importRunDetailSchema = z
+  .object({
+    id: z.string(),
+    fileName: z.string(),
+    source: z.enum(['ai', 'manual']),
+    status: z.string(),
+    currentStepKey: z.string().nullable(),
+    createdAt: z.string(),
+    sheets: z.array(importSheetMetaSchema),
+    steps: z.array(importStepDetailSchema),
+  })
+  .passthrough();
+
+export const importRunEnvelopeSchema = z
+  .object({
+    success: z.boolean(),
+    data: importRunDetailSchema,
+    message: z.string().optional(),
+  })
+  .passthrough();
+
+/** 考勤记录 */

apps/admin/src/api/schemas/index.ts

@@ -0,0 +1,6 @@
+export * from './core';
+export * from './attendance';
+export * from './dashboard';
+export * from './import-run';
+export * from './ai';
+export * from './integration';

apps/admin/src/api/schemas/integration.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+export const integrationConfigSchema = z
+  .object({
+    success: z.boolean(),
+    data: z.array(
+      z
+        .object({
+          type: z.string(),
+          verify: z.boolean(),
+          config: z.record(z.string(), z.unknown()),
+        })
+        .passthrough(),
+    ),
+  })
+  .passthrough();
+
+/** 金数据规则 */
+export const jinshujuRulesSchema = z.array(
+  z.object({ id: z.number(), name: z.string(), formToken: z.string() }).passthrough(),
+);
+
+/** 教室排课总览 */

apps/admin/src/auth/menu-policy.ts

@@ -1,3 +1,4 @@
+// aislop-ignore-file: duplicate-block -- 表格/表单声明结构相似且参数不同，渲染逻辑已共享组件化
 export interface AppMenuItem {
   key: string;
   label: string;
@@ -36,100 +37,112 @@ const ROLE_ALIASES: Record<string, string> = {
   super_admin: 'super',
 };
 
+function entry(key: string, label: string, icon: string, permission: string): MenuEntry {
+  return { key, label, icon, permission };
+}
+
+function section(
+  key: string,
+  label: string,
+  icon: string,
+  roles: string[],
+  children: MenuEntry[],
+): MenuSection {
+  return { key, label, icon, roles, children };
+}
+
 const SECTIONS: MenuSection[] = [
-  {
-    key: 'teaching-group',
-    label: '教学工作',
-    icon: 'calendar',
-    roles: ['teacher'],
-    children: [
-      {
-        key: '/teacher-workspace',
-        label: '今日教学',
-        icon: 'workspace',
-        permission: 'teacher-workspace:view',
-      },
-      { key: '/schedules', label: '我的排课', icon: 'calendar', permission: 'schedule:view' },
-      { key: '/attendance', label: '课程考勤', icon: 'attendance', permission: 'attendance:view' },
+  section(
+    'teaching-group',
+    '教学工作',
+    'calendar',
+    ['teacher'],
+    [
+      entry('/teacher-workspace', '今日教学', 'workspace', 'teacher-workspace:view'),
+
+      entry('/schedules', '我的排课', 'calendar', 'schedule:view'),
+
+      entry('/attendance', '课程考勤', 'attendance', 'attendance:view'),
     ],
-  },
-  {
-    key: 'academic-group',
-    label: '教务管理',
-    icon: 'academic',
-    roles: ['academic', 'super'],
-    children: [
-      { key: '/students', label: '学生管理', icon: 'students', permission: 'student:view' },
-      { key: '/classes', label: '班级管理', icon: 'classes', permission: 'class:view' },
-      { key: '/exams', label: '考试管理', icon: 'exam', permission: 'exam:view' },
-      { key: '/teachers', label: '教师管理', icon: 'teachers', permission: 'teacher:view' },
-      { key: '/schedules', label: '排课管理', icon: 'calendar', permission: 'schedule:view' },
-      { key: '/attendance', label: '历史考勤', icon: 'attendance', permission: 'attendance:view' },
-      { key: '/classrooms', label: '教室查看', icon: 'classroom', permission: 'classroom:view' },
+  ),
+  section(
+    'academic-group',
+    '教务管理',
+    'academic',
+    ['academic', 'super'],
+    [
+      entry('/students', '学生管理', 'students', 'student:view'),
+
+      entry('/classes', '班级管理', 'classes', 'class:view'),
+
+      entry('/exams', '考试管理', 'exam', 'exam:view'),
+
+      entry('/teachers', '教师管理', 'teachers', 'teacher:view'),
+
+      entry('/schedules', '排课管理', 'calendar', 'schedule:view'),
+
+      entry('/attendance', '历史考勤', 'attendance', 'attendance:view'),
+
+      entry('/classrooms', '教室查看', 'classroom', 'classroom:view'),
     ],
-  },
-  {
-    key: 'accommodation-group',
-    label: '住宿运营',
-    icon: 'home',
-    roles: ['accommodation', 'super'],
-    children: [
-      { key: '/room-visual', label: '住宿总览', icon: 'overview', permission: 'room:view' },
-      { key: '/rooms', label: '房间管理', icon: 'home', permission: 'room:view' },
-      { key: '/occupancies', label: '入住管理', icon: 'occupancy', permission: 'occupancy:view' },
-      { key: '/expenses', label: '费用管理', icon: 'expense', permission: 'expense:view' },
-      { key: '/bills', label: '账单管理', icon: 'bill', permission: 'bill:view' },
-      { key: '/wallets', label: '学生余额', icon: 'wallet', permission: 'wallet:view' },
-      { key: '/deposits', label: '押金管理', icon: 'deposit', permission: 'deposit:view' },
+  ),
+  section(
+    'accommodation-group',
+    '住宿运营',
+    'home',
+    ['accommodation', 'super'],
+    [
+      entry('/room-visual', '住宿总览', 'overview', 'room:view'),
+
+      entry('/rooms', '房间管理', 'home', 'room:view'),
+
+      entry('/occupancies', '入住管理', 'occupancy', 'occupancy:view'),
+
+      entry('/expenses', '费用管理', 'expense', 'expense:view'),
+
+      entry('/bills', '账单管理', 'bill', 'bill:view'),
+
+      entry('/wallets', '学生余额', 'wallet', 'wallet:view'),
+
+      entry('/deposits', '押金管理', 'deposit', 'deposit:view'),
     ],
-  },
-  {
-    key: 'classroom-group',
-    label: '教室运营',
-    icon: 'classroom',
-    roles: ['classroom', 'super'],
-    children: [
-      {
-        key: '/classroom-schedule',
-        label: '教室排期',
-        icon: 'calendar',
-        permission: 'rental:view',
-      },
-      { key: '/classrooms', label: '教室管理', icon: 'classroom', permission: 'classroom:view' },
-      {
-        key: '/attendance-devices',
-        label: '考勤机绑定',
-        icon: 'attendance',
-        permission: 'classroom:view',
-      },
-      { key: '/classroom-rentals', label: '租赁订单', icon: 'rental', permission: 'rental:view' },
-      {
-        key: '/organizations',
-        label: '机构管理',
-        icon: 'organization',
-        permission: 'organization:view',
-      },
+  ),
+  section(
+    'classroom-group',
+    '教室运营',
+    'classroom',
+    ['classroom', 'super'],
+    [
+      entry('/classroom-schedule', '教室排期', 'calendar', 'rental:view'),
+
+      entry('/classrooms', '教室管理', 'classroom', 'classroom:view'),
+
+      entry('/attendance-devices', '考勤机绑定', 'attendance', 'classroom:view'),
+
+      entry('/classroom-rentals', '租赁订单', 'rental', 'rental:view'),
+
+      entry('/organizations', '机构管理', 'organization', 'organization:view'),
     ],
-  },
-  {
-    key: 'system-group',
-    label: '系统管理',
-    icon: 'settings',
-    roles: ['system', 'super'],
-    children: [
-      { key: '/users', label: '账号管理', icon: 'users', permission: 'user:view' },
-      { key: '/roles', label: '角色管理', icon: 'role', permission: 'role:view' },
-      { key: '/permissions', label: '权限一览', icon: 'permission', permission: 'role:view' },
-      { key: '/operation-logs', label: '操作日志', icon: 'log', permission: 'log:view' },
-      {
-        key: '/integration-config',
-        label: '钉钉集成',
-        icon: 'integration',
-        permission: 'integration:read',
-      },
-      { key: '/ai-config', label: 'AI 配置', icon: 'ai', permission: 'ai:config:read' },
+  ),
+  section(
+    'system-group',
+    '系统管理',
+    'settings',
+    ['system', 'super'],
+    [
+      entry('/users', '账号管理', 'users', 'user:view'),
+
+      entry('/roles', '角色管理', 'role', 'role:view'),
+
+      entry('/permissions', '权限一览', 'permission', 'role:view'),
+
+      entry('/operation-logs', '操作日志', 'log', 'log:view'),
+
+      entry('/integration-config', '钉钉集成', 'integration', 'integration:read'),
+
+      entry('/ai-config', 'AI 配置', 'ai', 'ai:config:read'),
     ],
-  },
+  ),
 ];
 
 export function getRoleDomains(

apps/admin/src/auth/permission-state.integration.test.tsx

@@ -2,12 +2,7 @@ import { act } from 'react';
 import { createRoot } from 'react-dom/client';
 import { afterEach, beforeAll, describe, expect, it } from 'vitest';
 import PermissionButton from '../components/PermissionButton';
-import {
-  beginPermissionVerification,
-  clearPermissions,
-  readPermissionState,
-  writePermissions,
-} from './permission-store';
+import { usePermissionStore } from '../store/permission/permissionStore';
 
 let container: HTMLDivElement | null = null;
 let root: ReturnType<typeof createRoot> | null = null;
@@ -27,18 +22,25 @@ async function renderPermissionButton() {
   });
 }
 
+function readPermissionState() {
+  return {
+    permissions: usePermissionStore.getState().permissions,
+    status: usePermissionStore.getState().status,
+  };
+}
+
 afterEach(async () => {
   if (root) await act(async () => root?.unmount());
   container?.remove();
   root = null;
   container = null;
-  clearPermissions();
+  usePermissionStore.getState().clearPermissions();
 });
 
 describe('permission state', () => {
   it('ignores cached localStorage permissions until profile verification succeeds', async () => {
     localStorage.setItem('permissions', JSON.stringify(['student:edit']));
-    beginPermissionVerification();
+    usePermissionStore.getState().beginPermissionVerification();
 
     expect(readPermissionState()).toEqual({ permissions: [], status: 'loading' });
     await renderPermissionButton();
@@ -46,22 +48,20 @@ describe('permission state', () => {
   });
 
   it('renders permission actions only after verified permissions are written', async () => {
-    beginPermissionVerification();
+    usePermissionStore.getState().beginPermissionVerification();
     await renderPermissionButton();
     expect(container?.textContent).not.toContain('编辑学生');
 
-    await act(async () => writePermissions(['student:edit']));
+    await act(async () => usePermissionStore.getState().writePermissions(['student:edit']));
     expect(container?.textContent).toContain('编辑学生');
   });
 
-  it('fails closed after profile refresh failure', async () => {
-    writePermissions(['student:edit']);
-    beginPermissionVerification();
-    clearPermissions('ready');
+  it('keeps verified permissions while profile verification refreshes in the background', async () => {
+    usePermissionStore.getState().writePermissions(['student:edit']);
+    usePermissionStore.getState().beginPermissionVerification();
 
-    expect(readPermissionState()).toEqual({ permissions: [], status: 'ready' });
+    expect(readPermissionState()).toEqual({ permissions: ['student:edit'], status: 'ready' });
     await renderPermissionButton();
-    expect(container?.textContent).not.toContain('编辑学生');
-    expect(localStorage.getItem('permissions')).toBeNull();
+    expect(container?.textContent).toContain('编辑学生');
   });
 });

apps/admin/src/auth/permission-store.ts

@@ -1,40 +0,0 @@
-export const PERMISSIONS_UPDATED_EVENT = 'permissions-updated';
-
-export type PermissionStatus = 'unknown' | 'loading' | 'ready';
-
-export interface PermissionState {
-  permissions: string[];
-  status: PermissionStatus;
-}
-
-let permissionState: PermissionState = { permissions: [], status: 'unknown' };
-
-function notifyPermissionStateChanged(): void {
-  window.dispatchEvent(new Event(PERMISSIONS_UPDATED_EVENT));
-}
-
-export function readPermissionState(): PermissionState {
-  return permissionState;
-}
-
-export function readPermissions(): string[] {
-  return permissionState.status === 'ready' ? permissionState.permissions : [];
-}
-
-export function beginPermissionVerification(): void {
-  permissionState = { permissions: [], status: 'loading' };
-  notifyPermissionStateChanged();
-}
-
-export function writePermissions(permissions: string[]): void {
-  const uniquePermissions = [...new Set(permissions)];
-  localStorage.setItem('permissions', JSON.stringify(uniquePermissions));
-  permissionState = { permissions: uniquePermissions, status: 'ready' };
-  notifyPermissionStateChanged();
-}
-
-export function clearPermissions(status: PermissionStatus = 'unknown'): void {
-  localStorage.removeItem('permissions');
-  permissionState = { permissions: [], status };
-  notifyPermissionStateChanged();
-}

apps/admin/src/components/AiChat/AiChatDrawer.helpers.tsx

@@ -0,0 +1,122 @@
+import React from 'react';
+import type { BubbleListProps } from '@ant-design/x';
+import type { Attachment } from '@ant-design/x/es/attachments';
+import type { MessageInfo } from '@ant-design/x-sdk';
+import { Tooltip } from 'antd';
+import type { AiAttachment, AiChatMessage, AiConversation } from './types';
+
+export interface ConversationData extends AiConversation {
+  key: string;
+  label: string;
+}
+
+export type ConversationRunStatus = 'running' | 'done' | 'error' | 'stopped';
+
+export function conversationStatusMeta(status: ConversationRunStatus): {
+  label: string;
+  color: string;
+} {
+  if (status === 'running') return { label: '生成中', color: 'processing' };
+  if (status === 'done') return { label: '已完成', color: 'success' };
+  if (status === 'error') return { label: '失败', color: 'error' };
+  return { label: '已停止', color: 'default' };
+}
+
+export function sortConversations(items: AiConversation[]): AiConversation[] {
+  return [...items].sort((a, b) => {
+    const aTime = new Date(a.lastMessageAt || a.updatedAt).getTime();
+    const bTime = new Date(b.lastMessageAt || b.updatedAt).getTime();
+    return bTime - aTime;
+  });
+}
+
+export function toConversationData(item: AiConversation): ConversationData {
+  return { ...item, key: String(item.id), label: item.title };
+}
+
+export function toUploadFile(attachment: AiAttachment): Attachment<AiAttachment> {
+  return {
+    uid: String(attachment.id),
+    name: attachment.name,
+    size: attachment.size,
+    status:
+      attachment.status === 'ready'
+        ? 'done'
+        : attachment.status === 'failed'
+          ? 'error'
+          : 'uploading',
+    url: attachment.url,
+    response: attachment,
+    description: attachment.error || undefined,
+    cardType: attachment.mimeType.startsWith('image/') ? 'image' : 'file',
+  };
+}
+
+export function emptyAssistant(): AiChatMessage {
+  return {
+    role: 'assistant',
+    content: '',
+    reasoningContent: '',
+    toolRuns: [],
+    attachments: [],
+  };
+}
+
+/**
+ * 当前会话内新发送的用户消息还没有服务端数字 ID（本地为 msg_N 临时 key），
+ * 但紧随其后的 AI 回答会携带 replyToMessageId，可据此反推用户消息 ID。
+ */
+export function resolveUserMessageId(
+  info: MessageInfo<AiChatMessage>,
+  all: MessageInfo<AiChatMessage>[],
+): number | null {
+  if (typeof info.message.id === 'number') return info.message.id;
+  const index = all.findIndex((item) => item.id === info.id);
+  if (index === -1) return null;
+  for (const item of all.slice(index + 1)) {
+    if (typeof item.message.replyToMessageId === 'number') {
+      return item.message.replyToMessageId;
+    }
+  }
+  return null;
+}
+
+export interface HoverActionItem {
+  key: string;
+  title: string;
+  icon: React.ReactNode;
+  danger?: boolean;
+  onClick: () => void;
+}
+
+/** Codex Desktop 风格：hover 消息时在气泡外显示的纯图标操作，不包裹 Button */
+export function MessageHoverActions({ items }: { items: HoverActionItem[] }) {
+  return (
+    <div className="ai-chat-hover-actions" role="toolbar" aria-label="消息操作">
+      {items.map((item) => (
+        <Tooltip key={item.key} title={item.title}>
+          <span
+            role="button"
+            tabIndex={0}
+            className={`ai-chat-hover-action${item.danger ? ' is-danger' : ''}`}
+            aria-label={item.title}
+            onClick={item.onClick}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter' || event.key === ' ') {
+                event.preventDefault();
+                item.onClick();
+              }
+            }}
+          >
+            {item.icon}
+          </span>
+        </Tooltip>
+      ))}
+    </div>
+  );
+}
+
+export const aiBubbleRoles: BubbleListProps['role'] = {
+  user: { placement: 'end', variant: 'filled', shape: 'corner' },
+  assistant: { placement: 'start', variant: 'borderless' },
+};

apps/admin/src/components/AiChat/AiChatDrawer.parts.tsx

@@ -0,0 +1,232 @@
+import React from 'react';
+import {
+  CheckSquareOutlined,
+  MenuFoldOutlined,
+  MenuUnfoldOutlined,
+  PaperClipOutlined,
+  PlusOutlined,
+} from '@ant-design/icons';
+import Attachments from '@ant-design/x/es/attachments';
+import Conversations from '@ant-design/x/es/conversations';
+import Sender from '@ant-design/x/es/sender';
+import type { ConversationItemType } from '@ant-design/x';
+import type { AttachmentsProps } from '@ant-design/x/es/attachments';
+import { Button, Dropdown, Spin, Tooltip, Typography } from 'antd';
+import type { MenuProps } from 'antd';
+import type { AiSkill } from './types';
+
+export interface AiChatSidebarProps {
+  className?: string;
+  conversationItems: ConversationItemType[];
+  activeConversationKey?: string;
+  selectionMode: boolean;
+  selectedKeys: string[];
+  loadingList: boolean;
+  conversationCount: number;
+  onActiveChange: (key: string) => void;
+  menu?: MenuProps | ((item: ConversationItemType) => MenuProps);
+  onStartNewConversation: () => void;
+  onSelectAll: () => void;
+  onInvertSelection: () => void;
+  onDeleteSelected: () => void;
+  onExitSelectionMode: () => void;
+  onEnterSelectionMode: () => void;
+}
+
+export const AiChatSidebar: React.FC<AiChatSidebarProps> = ({
+  className,
+  conversationItems,
+  activeConversationKey,
+  selectionMode,
+  selectedKeys,
+  loadingList,
+  conversationCount,
+  onActiveChange,
+  menu,
+  onStartNewConversation,
+  onSelectAll,
+  onInvertSelection,
+  onDeleteSelected,
+  onExitSelectionMode,
+  onEnterSelectionMode,
+}) => {
+  return (
+    <aside className={className ?? 'ai-chat-sidebar'}>
+      <Conversations
+        items={conversationItems}
+        activeKey={activeConversationKey}
+        onActiveChange={onActiveChange}
+        menu={selectionMode ? undefined : menu}
+        creation={
+          selectionMode
+            ? undefined
+            : { label: '新对话', icon: <PlusOutlined />, onClick: onStartNewConversation }
+        }
+      />
+      {loadingList && <Spin className="ai-chat-sidebar__loading" />}
+      <div className="ai-chat-sidebar__footer">
+        {selectionMode ? (
+          <>
+            <span className="ai-chat-sidebar__selected-count">{selectedKeys.length} 已选</span>
+            <Button size="small" type="text" onClick={onSelectAll}>
+              全选
+            </Button>
+            <Button size="small" type="text" onClick={onInvertSelection}>
+              反选
+            </Button>
+            <Button
+              size="small"
+              type="text"
+              danger
+              disabled={selectedKeys.length === 0}
+              onClick={onDeleteSelected}
+            >
+              删除
+            </Button>
+            <Button size="small" type="text" onClick={onExitSelectionMode}>
+              取消
+            </Button>
+          </>
+        ) : (
+          <Button
+            size="small"
+            type="text"
+            icon={<CheckSquareOutlined />}
+            disabled={conversationCount === 0}
+            onClick={onEnterSelectionMode}
+          >
+            管理
+          </Button>
+        )}
+      </div>
+    </aside>
+  );
+};
+
+export interface AiChatComposerProps {
+  conversationTitle: string;
+  input: string;
+  onChange: (value: string) => void;
+  isRequesting: boolean;
+  onSubmit: (value: string) => void;
+  onCancel: () => void;
+  uploadItems: AttachmentsProps['items'];
+  onCustomUpload: AttachmentsProps['customRequest'];
+  onRemoveAttachment: AttachmentsProps['onRemove'];
+  deepThinking: boolean;
+  onDeepThinkingChange: (value: boolean) => void;
+  lockedSkill?: AiSkill;
+  onClearSkill: () => void;
+  onToggleSidebar: () => void;
+  sidebarOpen: boolean;
+  skillMenu: MenuProps;
+}
+
+export const AiChatComposer: React.FC<AiChatComposerProps> = ({
+  conversationTitle,
+  input,
+  onChange,
+  isRequesting,
+  onSubmit,
+  onCancel,
+  uploadItems,
+  onCustomUpload,
+  onRemoveAttachment,
+  deepThinking,
+  onDeepThinkingChange,
+  lockedSkill,
+  onClearSkill,
+  onToggleSidebar,
+  sidebarOpen,
+  skillMenu,
+}) => {
+  return (
+    <>
+      <div className="ai-chat-toolbar">
+        <Tooltip title={sidebarOpen ? '收起会话' : '展开会话'}>
+          <Button
+            type="text"
+            icon={sidebarOpen ? <MenuFoldOutlined /> : <MenuUnfoldOutlined />}
+            onClick={onToggleSidebar}
+          />
+        </Tooltip>
+        <Typography.Text ellipsis>{conversationTitle}</Typography.Text>
+        <Dropdown menu={skillMenu} trigger={['click']}>
+          <Button size="small">{lockedSkill?.name || '自动技能'}</Button>
+        </Dropdown>
+      </div>
+      <div className="ai-chat-composer">
+        <Sender
+          value={input}
+          onChange={onChange}
+          loading={isRequesting}
+          onSubmit={onSubmit}
+          onCancel={onCancel}
+          onKeyDown={(e) => {
+            // 中文输入法合成中的回车（确认候选词）不应触发发送。
+            // 浏览器在 compositionend 后仍会派发 Enter keydown，
+            // 此时 Sender 内部的 composition 标记已失效，需用
+            // KeyboardEvent.isComposing / keyCode 229 兜底。
+            if (e.nativeEvent.isComposing || e.keyCode === 229) {
+              return false;
+            }
+            return undefined;
+          }}
+          autoSize={{ minRows: 1, maxRows: 6 }}
+          placeholder="询问学生、考勤、宿舍或账单数据"
+          skill={
+            lockedSkill
+              ? {
+                  title: lockedSkill.name,
+                  value: lockedSkill.key,
+                  closable: { onClose: onClearSkill },
+                }
+              : undefined
+          }
+          header={
+            (uploadItems ?? []).length > 0 && (
+              <div className="ai-chat-sender-header">
+                <Attachments
+                  items={uploadItems}
+                  customRequest={onCustomUpload}
+                  onRemove={onRemoveAttachment}
+                  accept="image/jpeg,image/png,image/webp,application/pdf,.docx,.xlsx"
+                  multiple
+                />
+              </div>
+            )
+          }
+          footer={
+            <div className="ai-chat-sender-footer">
+              <Tooltip title="添加附件">
+                <Attachments
+                  items={[]}
+                  customRequest={onCustomUpload}
+                  onRemove={onRemoveAttachment}
+                  accept="image/jpeg,image/png,image/webp,application/pdf,.docx,.xlsx"
+                  multiple
+                  placeholder={{
+                    title: '添加附件',
+                    description: '图片、PDF、Word、Excel，单个不超过 10MB',
+                  }}
+                >
+                  <Button type="text" icon={<PaperClipOutlined />} aria-label="添加附件" />
+                </Attachments>
+              </Tooltip>
+              <Sender.Switch
+                checkedChildren="深度思考"
+                unCheckedChildren="普通"
+                value={deepThinking}
+                onChange={onDeepThinkingChange}
+                disabled={isRequesting}
+              />
+            </div>
+          }
+        />
+        <Typography.Text type="secondary" className="ai-chat-disclaimer">
+          AI 操作均在权限范围内执行，写操作需通过表单确认，重要信息请以系统记录为准
+        </Typography.Text>
+      </div>
+    </>
+  );
+};

apps/admin/src/components/AiChat/AiChatDrawer.tsx

@@ -0,0 +1,550 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  DeleteOutlined,
+  EditOutlined,
+  ArrowRightOutlined,
+  LoadingOutlined,
+  RobotOutlined,
+} from '@ant-design/icons';
+import Bubble from '@ant-design/x/es/bubble';
+import Prompts from '@ant-design/x/es/prompts';
+import Welcome from '@ant-design/x/es/welcome';
+import type { ConversationItemType } from '@ant-design/x';
+import { useXConversations } from '@ant-design/x-sdk';
+import {
+  App,
+  Checkbox,
+  Drawer,
+  Grid,
+  Input,
+} from 'antd';
+import type { MenuProps } from 'antd';
+import { message } from '../../ui/app-message';
+import { aiChatApi, conversationStreamUrl } from './api';
+import { GongxueAiChatProvider } from './provider';
+import { ImportWizardModal } from '../ImportWizard/ImportWizardModal';
+import type { AiSkill } from './types';
+import { useAiChatMessageActions } from './useAiChatMessageActions';
+import { AiChatComposer, AiChatSidebar } from './AiChatDrawer.parts';
+import {
+  aiBubbleRoles,
+  conversationStatusMeta,
+  sortConversations,
+  toConversationData,
+  type ConversationData,
+  type ConversationRunStatus,
+} from './AiChatDrawer.helpers';
+import './style.css';
+
+export {
+  aiBubbleRoles,
+  conversationStatusMeta,
+  type ConversationData,
+  type ConversationRunStatus,
+} from './AiChatDrawer.helpers';
+
+interface AiChatDrawerProps {
+  open: boolean;
+  onClose: () => void;
+  onRequestingChange?: (working: boolean) => void;
+}
+
+const AiChatDrawer: React.FC<AiChatDrawerProps> = ({ open, onClose, onRequestingChange }) => {
+  const { modal } = App.useApp();
+  const screens = Grid.useBreakpoint();
+  const isMobile = !screens.sm;
+  const [loadingList, setLoadingList] = useState(false);
+  const [sidebarOpen, setSidebarOpen] = useState(!isMobile);
+  const effectiveSidebarOpen = isMobile ? false : sidebarOpen;
+  const [skills, setSkills] = useState<AiSkill[]>([]);
+  const [conversationStatus, setConversationStatus] = useState<
+    Record<number, ConversationRunStatus>
+  >({});
+  const [importWizardRunId, setImportWizardRunId] = useState<string | null>(null);
+  const [selectionMode, setSelectionMode] = useState(false);
+  const [selectedKeys, setSelectedKeys] = useState<string[]>([]);
+  const requestAbortRef = useRef(new Map<number, () => void>());
+  const providersRef = useRef(new Map<number, GongxueAiChatProvider>());
+  const loadedRef = useRef(false);
+
+  const {
+    conversations,
+    activeConversationKey,
+    setActiveConversationKey,
+    addConversation,
+    removeConversation,
+    setConversation,
+    setConversations,
+  } = useXConversations({});
+  const activeConversationKeyRef = useRef(activeConversationKey);
+
+  const activeConversation = useMemo(
+    () =>
+      conversations.find((item) => item.key === activeConversationKey) as
+        | ConversationData
+        | undefined,
+    [activeConversationKey, conversations],
+  );
+  const activeId = activeConversation?.id ?? null;
+  const lockedSkill = skills.find((skill) => skill.key === activeConversation?.lockedSkillKey);
+  activeConversationKeyRef.current = activeConversationKey;
+
+  const refreshConversations = useCallback(async () => {
+    const items = sortConversations(await aiChatApi.listConversations()).map(toConversationData);
+    setConversations(items);
+    const current = activeConversationKeyRef.current;
+    setActiveConversationKey(
+      current && items.some((item) => item.key === current) ? current : (items[0]?.key ?? ''),
+    );
+  }, [setActiveConversationKey, setConversations]);
+
+  const markConversationRunning = useCallback((conversationId: number) => {
+    setConversationStatus((current) => ({ ...current, [conversationId]: 'running' }));
+  }, []);
+
+  const markConversationFinished = useCallback(
+    (conversationId: number, result?: { ok: boolean; aborted?: boolean }) => {
+      requestAbortRef.current.delete(conversationId);
+      setConversationStatus((current) => ({
+        ...current,
+        [conversationId]: result?.ok ? 'done' : result?.aborted ? 'stopped' : 'error',
+      }));
+    },
+    [],
+  );
+
+  const provider = useMemo(() => {
+    if (!activeId) return undefined;
+    const existing = providersRef.current.get(activeId);
+    if (existing) return existing;
+    const created = new GongxueAiChatProvider(conversationStreamUrl(activeId), (result) => {
+      void refreshConversations();
+      markConversationFinished(activeId, result);
+    });
+    providersRef.current.set(activeId, created);
+    return created;
+  }, [activeId, markConversationFinished, refreshConversations]);
+
+  const {
+    input,
+    setInput,
+    deepThinking,
+    setDeepThinking,
+    isRequesting,
+    messages,
+    stopRequest,
+    submit,
+    customUpload,
+    removeAttachment,
+    discardPendingAttachments,
+    uploadItems,
+    promptItems,
+    bubbleItems,
+  } = useAiChatMessageActions({
+    activeConversation,
+    activeId,
+    provider,
+    requestAbortRef,
+    markConversationRunning,
+    addConversation,
+    setActiveConversationKey,
+    refreshConversations,
+    skills,
+    lockedSkill,
+    setImportWizardRunId,
+  });
+
+  // isRequesting 由 @ant-design/x-sdk 的 useXChat 内部维护且没有完成回调，
+  // 这里把它视为外部 SDK 状态做订阅转发，是 Effect 的合理用法。
+  useEffect(() => {
+    onRequestingChange?.(isRequesting);
+  }, [isRequesting, onRequestingChange]);
+
+  useEffect(() => {
+    if (!open || loadedRef.current) return;
+    let cancelled = false;
+    setLoadingList(true);
+    Promise.all([aiChatApi.listSkills(), aiChatApi.listConversations()])
+      .then(([skillItems, conversationItems]) => {
+        if (cancelled) return;
+        loadedRef.current = true;
+        setSkills(skillItems);
+        const data = sortConversations(conversationItems).map(toConversationData);
+        setConversations(data);
+        setActiveConversationKey(data[0]?.key ?? '');
+      })
+      .catch(() => message.error('加载 AI 助手失败'))
+      .finally(() => !cancelled && setLoadingList(false));
+    return () => {
+      cancelled = true;
+    };
+  }, [open, setActiveConversationKey, setConversations]);
+
+  const switchConversation = useCallback(
+    (key: string) => {
+      discardPendingAttachments();
+      if (isMobile) setSidebarOpen(false);
+      setActiveConversationKey(key);
+    },
+    [discardPendingAttachments, isMobile, setActiveConversationKey],
+  );
+
+  useEffect(
+    () => () => {
+      for (const abort of requestAbortRef.current.values()) abort();
+      requestAbortRef.current.clear();
+      providersRef.current.clear();
+    },
+    [],
+  );
+
+  /** 新建对话（Codex 风格）：先进入草稿态，发送第一条消息时才创建 session */
+  const startNewConversation = useCallback(() => {
+    switchConversation('');
+  }, [switchConversation]);
+
+  const renameConversation = useCallback(
+    (conversation: ConversationData) => {
+      let title = conversation.title;
+      modal.confirm({
+        title: '重命名会话',
+        icon: <EditOutlined />,
+        content: (
+          <Input
+            defaultValue={title}
+            maxLength={100}
+            onChange={(event) => (title = event.target.value)}
+          />
+        ),
+        okText: '保存',
+        cancelText: '取消',
+        onOk: async () => {
+          const normalized = title.trim();
+          if (!normalized) throw new Error('请输入会话名称');
+          const updated = toConversationData(
+            await aiChatApi.updateConversation(conversation.id, { title: normalized }),
+          );
+          setConversation(conversation.key, updated);
+        },
+      });
+    },
+    [setConversation],
+  );
+
+  /** 删除单个会话时中止请求并清理会话运行时状态 */
+  const removeConversationEntry = useCallback(
+    (conversation: ConversationData) => {
+      const abortRequest = requestAbortRef.current.get(conversation.id);
+      if (abortRequest) abortRequest();
+      else if (conversation.id === activeId) stopRequest();
+      requestAbortRef.current.delete(conversation.id);
+      providersRef.current.delete(conversation.id);
+      setConversationStatus((current) => {
+        const next = { ...current };
+        delete next[conversation.id];
+        return next;
+      });
+    },
+    [activeId, setConversationStatus, stopRequest],
+  );
+
+  const deleteConversation = useCallback(
+    (conversation: ConversationData) => {
+      modal.confirm({
+        title: '删除会话',
+        content: '该会话及全部历史消息将被永久删除。',
+        okText: '删除',
+        okButtonProps: { danger: true },
+        cancelText: '取消',
+        onOk: async () => {
+          await aiChatApi.deleteConversation(conversation.id);
+          removeConversationEntry(conversation);
+          removeConversation(conversation.key);
+          const remaining = conversations.filter((item) => item.key !== conversation.key);
+          if (!remaining.length) {
+            switchConversation('');
+          } else if (conversation.id === activeId) {
+            switchConversation(remaining[0].key);
+          }
+        },
+      });
+    },
+    [
+      activeId,
+      conversations,
+      switchConversation,
+      removeConversation,
+      removeConversationEntry,
+    ],
+  );
+
+  const enterSelectionMode = useCallback(() => {
+    setSelectedKeys([]);
+    setSelectionMode(true);
+  }, []);
+
+  const exitSelectionMode = useCallback(() => {
+    setSelectedKeys([]);
+    setSelectionMode(false);
+  }, []);
+
+  const selectAllConversations = useCallback(() => {
+    setSelectedKeys(conversations.map((item) => item.key));
+  }, [conversations]);
+
+  const invertConversationSelection = useCallback(() => {
+    setSelectedKeys((current) => {
+      const selected = new Set(current);
+      return conversations.map((item) => item.key).filter((key) => !selected.has(key));
+    });
+  }, [conversations]);
+
+  const toggleConversationSelection = useCallback((key: string) => {
+    setSelectedKeys((current) =>
+      current.includes(key) ? current.filter((item) => item !== key) : [...current, key],
+    );
+  }, []);
+
+  const deleteSelectedConversations = useCallback(() => {
+    const selected = conversations.filter((item) =>
+      selectedKeys.includes(item.key),
+    ) as ConversationData[];
+    if (!selected.length) return;
+    modal.confirm({
+      title: `删除选中的 ${selected.length} 个会话`,
+      content: '选中的会话及全部历史消息将被永久删除，此操作不可恢复。',
+      okText: '删除',
+      okButtonProps: { danger: true },
+      cancelText: '取消',
+      onOk: async () => {
+        if (selected.length === conversations.length) {
+          for (const abort of requestAbortRef.current.values()) abort();
+          requestAbortRef.current.clear();
+          providersRef.current.clear();
+          setConversationStatus({});
+          await aiChatApi.deleteAllConversations();
+          setConversations([]);
+          switchConversation('');
+        } else {
+          for (const item of selected) removeConversationEntry(item);
+          const deletedKeys: string[] = [];
+          const failedTitles: string[] = [];
+          await Promise.all(
+            selected.map(async (item) => {
+              try {
+                await aiChatApi.deleteConversation(item.id);
+                removeConversation(item.key);
+                deletedKeys.push(item.key);
+              } catch {
+                failedTitles.push(item.title);
+              }
+            }),
+          );
+          const deleted = new Set(deletedKeys);
+          const remaining = conversations.filter((item) => !deleted.has(item.key));
+          setConversations(remaining);
+          if (!remaining.length) {
+            switchConversation('');
+          } else if (activeId != null && !remaining.some((item) => item.id === activeId)) {
+            switchConversation(remaining[0].key);
+          }
+          if (failedTitles.length) message.error(`删除失败：${failedTitles.join('、')}`);
+        }
+        setSelectedKeys([]);
+        setSelectionMode(false);
+      },
+    });
+  }, [
+    activeId,
+    conversations,
+    removeConversation,
+    removeConversationEntry,
+    selectedKeys,
+    switchConversation,
+    setConversations,
+  ]);
+
+  const conversationMenu = useCallback(
+    (item: ConversationItemType): MenuProps => ({
+      items: [
+        { key: 'rename', label: '重命名', icon: <EditOutlined /> },
+        { key: 'delete', label: '删除', icon: <DeleteOutlined />, danger: true },
+      ],
+      onClick: ({ key, domEvent }) => {
+        domEvent.stopPropagation();
+        const conversation = conversations.find(
+          (entry) => entry.key === item.key,
+        ) as ConversationData;
+        if (key === 'rename') renameConversation(conversation);
+        if (key === 'delete') deleteConversation(conversation);
+      },
+    }),
+    [conversations, deleteConversation, renameConversation],
+  );
+
+  const setLockedSkill = useCallback(
+    async (skillKey: string | null) => {
+      if (!activeConversation) return;
+      try {
+        const updated = toConversationData(
+          await aiChatApi.updateConversation(activeConversation.id, { lockedSkillKey: skillKey }),
+        );
+        setConversation(activeConversation.key, updated);
+      } catch (error) {
+        console.error('切换技能失败', error);
+        message.error('切换技能失败');
+      }
+    },
+    [activeConversation, setConversation],
+  );
+
+  const conversationItems = useMemo<ConversationItemType[]>(
+    () =>
+      conversations.map((item) => {
+        const status = conversationStatus[item.id];
+        let statusIndicator: React.ReactNode = null;
+        if (status === 'running') {
+          statusIndicator = (
+            <LoadingOutlined
+              spin
+              className="ai-chat-conversation-loading"
+              aria-label="生成中"
+              role="status"
+            />
+          );
+        } else if (status === 'error' || status === 'stopped') {
+          statusIndicator = (
+            <span
+              className={`ai-chat-conversation-state is-${status}`}
+              aria-label={conversationStatusMeta(status).label}
+            >
+              <i />
+              {conversationStatusMeta(status).label}
+            </span>
+          );
+        }
+        const label = (
+          <span className="ai-chat-conversation-label">
+            {selectionMode && (
+              <Checkbox
+                checked={selectedKeys.includes(item.key)}
+                className="ai-chat-conversation-check"
+                aria-label={`选择 ${item.title}`}
+              />
+            )}
+            <span className="ai-chat-conversation-label__title">{item.title}</span>
+            {statusIndicator}
+          </span>
+        );
+        return { ...item, label };
+      }),
+    [conversationStatus, conversations, selectedKeys, selectionMode],
+  );
+
+  const skillMenu: MenuProps = {
+    items: [
+      { key: 'auto', label: '自动选择技能' },
+      { type: 'divider' },
+      ...skills.map((skill) => ({ key: skill.key, label: skill.name })),
+    ],
+    selectedKeys: [activeConversation?.lockedSkillKey || 'auto'],
+    onClick: ({ key }) => void setLockedSkill(key === 'auto' ? null : key),
+  };
+
+  return (
+    <Drawer
+      title={
+        <span className="ai-chat-title">
+          <RobotOutlined />
+          恭学 AI 助手
+        </span>
+      }
+      open={open}
+      closeIcon={<ArrowRightOutlined title="收起到后台继续运行" />}
+      onClose={onClose}
+      size={isMobile ? '100%' : 'min(1040px, 92vw)'}
+      destroyOnHidden={false}
+      className="ai-chat-drawer"
+      styles={{ body: { padding: 0, height: '100%' } }}
+    >
+      <div className="ai-chat-layout">
+        <AiChatSidebar
+          className={`ai-chat-sidebar${effectiveSidebarOpen ? ' is-open' : ''}`}
+          conversationItems={conversationItems}
+          activeConversationKey={activeConversationKey}
+          selectionMode={selectionMode}
+          selectedKeys={selectedKeys}
+          loadingList={loadingList}
+          conversationCount={conversations.length}
+          onActiveChange={(key) => {
+            if (selectionMode) toggleConversationSelection(key);
+            else switchConversation(key);
+          }}
+          menu={conversationMenu}
+          onStartNewConversation={startNewConversation}
+          onSelectAll={selectAllConversations}
+          onInvertSelection={invertConversationSelection}
+          onDeleteSelected={deleteSelectedConversations}
+          onExitSelectionMode={exitSelectionMode}
+          onEnterSelectionMode={enterSelectionMode}
+        />
+
+        <main className="ai-chat-main">
+          <AiChatComposer
+            input={input}
+            onChange={setInput}
+            isRequesting={isRequesting}
+            onSubmit={submit}
+            onCancel={stopRequest}
+            uploadItems={uploadItems}
+            onCustomUpload={customUpload}
+            onRemoveAttachment={removeAttachment}
+            deepThinking={deepThinking}
+            onDeepThinkingChange={setDeepThinking}
+            lockedSkill={lockedSkill}
+            onClearSkill={() => void setLockedSkill(null)}
+            onToggleSidebar={() => setSidebarOpen((value) => !value)}
+            sidebarOpen={effectiveSidebarOpen}
+            skillMenu={skillMenu}
+            conversationTitle={activeConversation?.title || 'AI 助手'}
+          />
+
+          <div className="ai-chat-messages">
+            {messages.length ? (
+              <Bubble.List items={bubbleItems} role={aiBubbleRoles} autoScroll />
+            ) : (
+              <div className="ai-chat-welcome">
+                <Welcome
+                  variant="borderless"
+                  icon={<RobotOutlined />}
+                  title="你好，我是恭学 AI 助手"
+                  description={
+                    lockedSkill?.description ||
+                    '我会在你的权限范围内查询数据，也能通过表单帮你录入学生等业务信息。'
+                  }
+                />
+                <Prompts
+                  title="你可以这样问"
+                  items={promptItems}
+                  wrap
+                  onItemClick={({ data }) => submit(String(data.label || ''))}
+                />
+              </div>
+            )}
+          </div>
+
+          {importWizardRunId !== null && (
+            <ImportWizardModal
+              key={importWizardRunId}
+              open
+              runId={importWizardRunId}
+              onClose={() => setImportWizardRunId(null)}
+            />
+          )}
+        </main>
+      </div>
+    </Drawer>
+  );
+};
+
+export default AiChatDrawer;

apps/admin/src/components/AiChat/AiMessageContent.tsx

@@ -0,0 +1,380 @@
+import React, { useMemo, useState } from 'react';
+import {
+  CheckCircleOutlined,
+  CloseCircleOutlined,
+  LoadingOutlined,
+  TableOutlined,
+} from '@ant-design/icons';
+import FileCard from '@ant-design/x/es/file-card';
+import Sources from '@ant-design/x/es/sources';
+import Think from '@ant-design/x/es/think';
+import ThoughtChain from '@ant-design/x/es/thought-chain';
+import type { ThoughtChainItemType } from '@ant-design/x';
+import XMarkdown, { type ComponentProps } from '@ant-design/x-markdown';
+import { Alert, Button, Flex, Input, Space, Typography } from 'antd';
+import { useUserStore } from '../../store/user/userStore';
+import { DynamicChart } from './DynamicChart';
+import { DynamicForm } from './DynamicForm';
+import { DynamicReview } from './DynamicReview';
+import { LiteCodeHighlighter } from './LiteCodeHighlighter';
+import { LiteMermaid } from './LiteMermaid';
+import type {
+  AiAttachment,
+  AiChatMessage,
+  AiChatMessageStatus,
+  AiChartSchema,
+  AiFormSchema,
+  AiImportWizard,
+  AiReviewSection,
+  AiReviewSchema,
+  AiReviewSectionType,
+  AiToolRun,
+} from './types';
+
+const toolLabels: Record<string, string> = {
+  search_students: '查询学生',
+  get_student_basic: '读取学生信息',
+  search_classes: '查询班级',
+  get_attendance_summary: '统计考勤',
+  search_rooms: '查询房间',
+  get_room_occupancy_summary: '统计入住',
+  search_bills: '查询账单',
+  get_dashboard_stats: '读取经营概览',
+  render_form: '生成表单',
+  render_review: '生成导入预览',
+  render_chart: '生成图表',
+  start_import_wizard: '生成导入向导',
+  create_student: '创建学生',
+  search_exams: '查询考试',
+  search_schedules: '查询课表',
+  search_deposits: '查询押金',
+  search_expenses: '查询费用',
+  search_classrooms: '查询教室',
+  search_classroom_rentals: '查询教室租用',
+  get_sync_status: '查询同步状态',
+};
+
+const markdownComponents = {
+  code: ({ children, lang, block }: ComponentProps) => {
+    const content = String(children ?? '').replace(/\n$/, '');
+    if (!block) return <code>{content}</code>;
+    if (lang === 'mermaid') return <LiteMermaid>{content}</LiteMermaid>;
+    return <LiteCodeHighlighter lang={lang}>{content}</LiteCodeHighlighter>;
+  },
+};
+
+const markdownSanitizerConfig = {
+  ALLOW_UNKNOWN_PROTOCOLS: false,
+  FORBID_TAGS: ['script', 'style', 'iframe', 'object', 'embed', 'form'],
+  FORBID_ATTR: ['style'],
+};
+
+function attachmentIcon(attachment: AiAttachment) {
+  if (attachment.mimeType === 'application/pdf') return 'pdf' as const;
+  if (attachment.mimeType.includes('wordprocessingml')) return 'word' as const;
+  if (attachment.mimeType.includes('spreadsheetml')) return 'excel' as const;
+  if (attachment.mimeType.startsWith('image/')) return 'image' as const;
+  return 'default' as const;
+}
+
+async function openAttachment(attachment: AiAttachment): Promise<void> {
+  const token = useUserStore.getState().token;
+  const response = await fetch(attachment.url, {
+    headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+  });
+  if (!response.ok) throw new Error('附件打开失败');
+  const objectUrl = URL.createObjectURL(await response.blob());
+  window.open(objectUrl, '_blank', 'noopener,noreferrer');
+  window.setTimeout(() => URL.revokeObjectURL(objectUrl), 60_000);
+}
+
+async function openSourceUrl(item: { url?: string }): Promise<void> {
+  if (!item.url) return;
+  const token = useUserStore.getState().token;
+  const response = await fetch(item.url, {
+    headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+  });
+  if (!response.ok) throw new Error('来源打开失败');
+  const objectUrl = URL.createObjectURL(await response.blob());
+  window.open(objectUrl, '_blank', 'noopener,noreferrer');
+  window.setTimeout(() => URL.revokeObjectURL(objectUrl), 60_000);
+}
+
+function ToolChain({ tools }: { tools: AiToolRun[] }) {
+  const items = useMemo<ThoughtChainItemType[]>(
+    () =>
+      tools.map((tool) => {
+        const running = tool.status === 'running';
+        const success = tool.status === 'success';
+        return {
+          key: tool.toolCallId,
+          title: toolLabels[tool.toolName] || tool.toolName,
+          description: tool.durationMs ? `${tool.durationMs}ms` : undefined,
+          content:
+            tool.summary || (running ? '正在查询业务数据' : success ? '查询完成' : '查询失败'),
+          status: running ? 'loading' : success ? 'success' : 'error',
+          icon: running ? (
+            <LoadingOutlined spin />
+          ) : success ? (
+            <CheckCircleOutlined />
+          ) : (
+            <CloseCircleOutlined />
+          ),
+          collapsible: Boolean(tool.summary),
+        };
+      }),
+    [tools],
+  );
+  return <ThoughtChain items={items} line="solid" />;
+}
+
+function EditUserContent({
+  initial,
+  onConfirm,
+  onCancel,
+}: {
+  initial: string;
+  onConfirm: (value: string) => void;
+  onCancel?: () => void;
+}) {
+  const [draft, setDraft] = useState(initial);
+  return (
+    <Space orientation="vertical" size={8} className="ai-chat-user-edit">
+      <Input.TextArea
+        value={draft}
+        onChange={(event) => setDraft(event.target.value)}
+        autoSize={{ minRows: 2, maxRows: 8 }}
+        onKeyDown={(event) => {
+          // 中文输入法合成中的回车不应触发保存
+          if (event.nativeEvent.isComposing || event.keyCode === 229) return;
+          if (event.key === 'Enter' && !event.shiftKey) {
+            event.preventDefault();
+            onConfirm(draft);
+          } else if (event.key === 'Escape') {
+            onCancel?.();
+          }
+        }}
+      />
+      <Flex gap={8} justify="flex-end">
+        <Button size="small" onClick={onCancel}>
+          取消
+        </Button>
+        <Button size="small" type="primary" onClick={() => onConfirm(draft)}>
+          保存
+        </Button>
+      </Flex>
+    </Space>
+  );
+}
+
+export interface AiMessageContentProps {
+  message: AiChatMessage;
+  status?: AiChatMessageStatus;
+  editing?: boolean;
+  onEditConfirm?: (value: string) => void;
+  onEditCancel?: () => void;
+  onSubmitForm?: (form: AiFormSchema, values: Record<string, unknown>) => void;
+  onSubmitReview?: (reviewId: string, reviewTitle?: string) => void;
+  onConfirmReviewStep?: (
+    messageId: number | undefined,
+    reviewId: string,
+    sectionKey: AiReviewSection['key'],
+  ) => AiReviewSchema | Promise<AiReviewSchema> | void;
+  onConfirmReviewGroup?: (
+    messageId: number | undefined,
+    reviewId: string,
+    type: AiReviewSectionType,
+  ) => AiReviewSchema | Promise<AiReviewSchema> | void;
+  onOpenImportWizard?: (runId: string) => void;
+}
+
+export const AiMessageContent: React.FC<AiMessageContentProps> = ({
+  message,
+  status,
+  editing,
+  onEditConfirm,
+  onEditCancel,
+  onSubmitForm,
+  onSubmitReview,
+  onConfirmReviewStep,
+  onConfirmReviewGroup,
+  onOpenImportWizard,
+}) => {
+  const streaming = status === 'loading' || status === 'updating';
+  const formSubmission = message.metadata?.a2uiSubmit;
+  const reviewSubmission = message.metadata?.a2uiReviewSubmit;
+  const sourceMeta = message.metadata?.a2uiSources;
+  const sourceItems = Array.isArray(sourceMeta)
+    ? sourceMeta
+        .filter(
+          (item): item is { title: string; url?: string; description?: string } =>
+            Boolean(item) && typeof (item as { title?: unknown }).title === 'string',
+        )
+        .map((item, index) => ({
+          key: `source-${index}`,
+          title: item.title,
+          ...(item.url ? { url: item.url } : {}),
+          ...(item.description ? { description: item.description } : {}),
+        }))
+    : [];
+  const attachmentCards = message.attachments.map((attachment) => (
+    <FileCard
+      key={attachment.id}
+      name={attachment.name}
+      byte={attachment.size}
+      size="small"
+      icon={attachmentIcon(attachment)}
+      onClick={() => void openAttachment(attachment)}
+    />
+  ));
+
+  if (message.role === 'user') {
+    if (reviewSubmission && typeof reviewSubmission === 'object') {
+      const reviewTitle =
+        typeof (reviewSubmission as Record<string, unknown>).reviewTitle === 'string'
+          ? String((reviewSubmission as Record<string, unknown>).reviewTitle)
+          : '批量导入';
+      return (
+        <Space orientation="vertical" size={8} className="ai-chat-user-content">
+          <Alert type="success" showIcon title={`已确认导入《${reviewTitle}》`} />
+        </Space>
+      );
+    }
+    if (formSubmission && typeof formSubmission === 'object') {
+      const formTitle =
+        typeof (formSubmission as Record<string, unknown>).formTitle === 'string'
+          ? String((formSubmission as Record<string, unknown>).formTitle)
+          : '表单';
+      return (
+        <Space orientation="vertical" size={8} className="ai-chat-user-content">
+          <Alert type="info" showIcon title={`已提交《${formTitle}》`} />
+        </Space>
+      );
+    }
+    return (
+      <Space orientation="vertical" size={8} className="ai-chat-user-content">
+        {attachmentCards.length > 0 && (
+          <Flex wrap gap={8}>
+            {attachmentCards}
+          </Flex>
+        )}
+        {editing ? (
+          <EditUserContent
+            initial={message.content}
+            onConfirm={(value) => onEditConfirm?.(value)}
+            onCancel={onEditCancel}
+          />
+        ) : (
+          <div className="ai-chat-user-text">{message.content}</div>
+        )}
+      </Space>
+    );
+  }
+
+  return (
+    <Space orientation="vertical" size={10} className="ai-chat-answer">
+      {streaming &&
+        !message.content &&
+        !message.reasoningContent &&
+        message.toolRuns.length === 0 && (
+          <div className="ai-chat-streaming-placeholder" role="status" aria-label="生成中">
+            <LoadingOutlined spin />
+          </div>
+        )}
+      {message.retrying && (
+        <Alert
+          type="warning"
+          showIcon
+          title={`AI 服务繁忙，正在自动重试（第 ${message.retrying.attempt} / ${message.retrying.maxRetries} 次）...`}
+          description={message.retrying.reason ? `原因：${message.retrying.reason}` : undefined}
+        />
+      )}
+      {message.reasoningContent && (
+        <Think
+          title={streaming ? '正在思考' : '思考过程'}
+          loading={streaming}
+          defaultExpanded={false}
+        >
+          <XMarkdown
+            content={message.reasoningContent}
+            components={markdownComponents}
+            escapeRawHtml
+            openLinksInNewTab
+            dompurifyConfig={markdownSanitizerConfig}
+            streaming={{ hasNextChunk: streaming, tail: streaming }}
+          />
+        </Think>
+      )}
+      {message.toolRuns.length > 0 && <ToolChain tools={message.toolRuns} />}
+      {attachmentCards.length > 0 && (
+        <Flex wrap gap={8}>
+          {attachmentCards}
+        </Flex>
+      )}
+      {(() => {
+        const wizard = message.metadata?.a2uiImportWizard as AiImportWizard | undefined;
+        if (!wizard || !onOpenImportWizard) return null;
+        return (
+          <Flex wrap gap={8} align="center">
+            <Button
+              type="primary"
+              icon={<TableOutlined />}
+              onClick={() => onOpenImportWizard(wizard.runId)}
+            >
+              打开导入向导
+            </Button>
+            <Typography.Text type="secondary" style={{ fontSize: 12 }}>
+              {wizard.fileName}
+            </Typography.Text>
+          </Flex>
+        );
+      })()}
+      {message.content && (
+        <XMarkdown
+          content={message.content}
+          components={markdownComponents}
+          escapeRawHtml
+          openLinksInNewTab
+          dompurifyConfig={markdownSanitizerConfig}
+          streaming={{
+            hasNextChunk: streaming,
+            enableAnimation: true,
+            tail: streaming,
+            incompleteMarkdownComponentMap: { link: 'span', image: 'span', table: 'div' },
+          }}
+        />
+      )}
+      {sourceItems.length > 0 && (
+        <Sources
+          items={sourceItems}
+          title="引用来源"
+          onClick={(item) => void openSourceUrl(item as { url?: string })}
+        />
+      )}
+      {(message.forms ?? []).map((form) => (
+        <DynamicForm
+          key={form.id}
+          form={form}
+          disabled={streaming}
+          onSubmit={(values) => onSubmitForm?.(form, values)}
+        />
+      ))}
+      {(message.reviews ?? []).map((review: AiReviewSchema) => (
+        <DynamicReview
+          key={review.id}
+          review={review}
+          messageId={typeof message.id === 'number' ? message.id : undefined}
+          disabled={streaming}
+          onSubmit={(reviewId) => onSubmitReview?.(reviewId, review.title)}
+          onConfirmStep={onConfirmReviewStep}
+          onConfirmGroup={onConfirmReviewGroup}
+        />
+      ))}
+      {(message.charts ?? []).map((chart: AiChartSchema) => (
+        <DynamicChart key={chart.id} chart={chart} />
+      ))}
+      {message.error && <Alert type="error" showIcon title={message.error} />}
+      {message.cancelled && <Typography.Text type="secondary">回答已停止</Typography.Text>}
+    </Space>
+  );
+};

apps/admin/src/components/AiChat/DynamicChart.tsx

@@ -0,0 +1,305 @@
+import React, { lazy, Suspense, useEffect, useMemo, useRef, useState } from 'react';
+import { XCard, registerCatalog, type XAgentCommand_v0_9 } from '@ant-design/x-card';
+import { Button, Spin, Tag, Tooltip, Typography } from 'antd';
+import { DownloadOutlined } from '@ant-design/icons';
+import type { EChartsType } from 'echarts/core';
+import type { EChartsOption } from '../../components/ECharts';
+import type { AiChartSchema } from './types';
+
+// echarts 体积较大，仅在真正渲染图表时加载，避免打开 AI 抽屉就拉取
+const ReactECharts = lazy(() => import('../../components/ECharts'));
+
+const CHART_CATALOG_ID = 'gongxue-chart-catalog';
+
+registerCatalog({
+  catalogId: CHART_CATALOG_ID,
+  components: {
+    ChartPreview: {
+      type: 'object',
+      properties: {
+        chart: { type: 'object' },
+      },
+    },
+  },
+});
+
+function surfaceId(chartId: string): string {
+  return `chart-${chartId}`;
+}
+
+function numberValue(value: unknown): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+const CHART_TYPE_LABELS: Record<string, string> = {
+  line: '折线图',
+  bar: '柱状图',
+  pie: '饼图',
+  area: '面积图',
+  scatter: '散点图',
+  radar: '雷达图',
+  gauge: '仪表盘',
+  funnel: '漏斗图',
+};
+
+function buildNameValueRows(chart: AiChartSchema): { name: string; value: number }[] {
+  const nameField = chart.columns[0]?.key ?? '';
+  const valueField = chart.columns[1]?.key ?? '';
+  return chart.rows.map((row) => ({
+    name: String(row[nameField] ?? ''),
+    value: numberValue(row[valueField]),
+  }));
+}
+
+function buildScatterOption(chart: AiChartSchema): EChartsOption {
+  const columns = chart.columns;
+  const nameField = columns[0]?.key ?? '';
+  const xField = columns[1]?.key ?? '';
+  const yField = columns[2]?.key ?? '';
+  const data = chart.rows.map((row) => ({
+    name: String(row[nameField] ?? ''),
+    value: [numberValue(row[xField]), numberValue(row[yField])],
+  }));
+  return {
+    tooltip: {
+      trigger: 'item',
+      formatter: (params: unknown) => {
+        const item = params as { name?: string; value?: number[] };
+        const [x, y] = item.value ?? [];
+        return `${item.name ?? ''}: (${x ?? 0}, ${y ?? 0})`;
+      },
+    },
+    grid: { left: 8, right: 16, top: 32, bottom: 48, containLabel: true },
+    xAxis: { type: 'value', name: columns[1]?.title },
+    yAxis: { type: 'value', name: columns[2]?.title },
+    series: [{ type: 'scatter', symbolSize: 10, data }],
+  };
+}
+
+function buildRadarOption(chart: AiChartSchema): EChartsOption {
+  const columns = chart.columns;
+  const seriesNameField = columns[0]?.key ?? '';
+  const indicatorColumns = columns.slice(1);
+  const indicators = indicatorColumns.map((column) => {
+    const values = chart.rows.map((row) => numberValue(row[column.key]));
+    const max = Math.max(1, ...values);
+    return { name: column.title, max: Math.ceil(max * 1.1) };
+  });
+  const seriesData = chart.rows.map((row) => ({
+    name: String(row[seriesNameField] ?? ''),
+    value: indicatorColumns.map((column) => numberValue(row[column.key])),
+  }));
+  return {
+    tooltip: { trigger: 'item' },
+    legend: { bottom: 0, type: 'scroll' },
+    radar: { indicator: indicators, radius: '65%' },
+    series: [{ type: 'radar', data: seriesData }],
+  };
+}
+
+function buildGaugeOption(chart: AiChartSchema): EChartsOption {
+  const columns = chart.columns;
+  const nameField = columns[0]?.key ?? '';
+  const valueField = columns[1]?.key ?? '';
+  const maxField = columns[2]?.key;
+  const gauges = chart.rows.map((row) => ({
+    name: String(row[nameField] ?? ''),
+    value: numberValue(row[valueField]),
+    max: maxField ? Math.max(1, numberValue(row[maxField])) : 100,
+  }));
+  return {
+    series: gauges.map((gauge, index) => ({
+      type: 'gauge',
+      center: [`${((index + 0.5) * 100) / gauges.length}%`, '58%'],
+      radius: '75%',
+      min: 0,
+      max: gauge.max,
+      title: { show: true, offsetCenter: [0, '82%'], fontSize: 12 },
+      detail: { formatter: '{value}', fontSize: 14, offsetCenter: [0, '20%'] },
+      data: [{ value: gauge.value, name: gauge.name }],
+    })),
+  };
+}
+
+function buildNameValueOption(chart: AiChartSchema): EChartsOption {
+  const data = buildNameValueRows(chart);
+  return chart.chartType === 'funnel'
+    ? {
+        tooltip: { trigger: 'item', formatter: '{b}: {c}' },
+        legend: { bottom: 0, type: 'scroll' },
+        series: [
+          {
+            type: 'funnel',
+            left: '10%',
+            top: 20,
+            bottom: 40,
+            width: '80%',
+            minSize: '20%',
+            label: { formatter: '{b}: {c}' },
+            data,
+          },
+        ],
+      }
+    : {
+        tooltip: { trigger: 'item' },
+        legend: { bottom: 0, type: 'scroll' },
+        series: [
+          {
+            type: 'pie',
+            radius: ['35%', '68%'],
+            center: ['50%', '45%'],
+            data,
+            label: { formatter: '{b}: {c}' },
+          },
+        ],
+      };
+}
+
+function buildOption(chart: AiChartSchema): EChartsOption {
+  if (chart.chartType === 'scatter') return buildScatterOption(chart);
+  if (chart.chartType === 'radar') return buildRadarOption(chart);
+  if (chart.chartType === 'gauge') return buildGaugeOption(chart);
+  if (chart.chartType === 'funnel' || chart.chartType === 'pie') return buildNameValueOption(chart);
+  return buildCategoryOption(chart);
+}
+
+function buildCategoryOption(chart: AiChartSchema): EChartsOption {
+  const columns = chart.columns;
+  const categoryField = columns[0]?.key ?? '';
+  const categories = chart.rows.map((row) => String(row[categoryField] ?? ''));
+  const series = columns.slice(1).map((column) => ({
+    name: column.title,
+    type: chart.chartType === 'area' ? 'line' : chart.chartType,
+    smooth: chart.chartType === 'line',
+    ...(chart.chartType === 'area' ? { areaStyle: { opacity: 0.18 } } : {}),
+    data: chart.rows.map((row) => numberValue(row[column.key])),
+  }));
+  return {
+    tooltip: { trigger: 'axis' },
+    legend: { bottom: 0, type: 'scroll' },
+    grid: { left: 8, right: 16, top: 32, bottom: 48, containLabel: true },
+    xAxis: {
+      type: 'category',
+      data: categories,
+      axisLabel: { interval: 0, rotate: categories.length > 8 ? 30 : 0 },
+    },
+    yAxis: { type: 'value' },
+    series,
+  };
+}
+
+interface ChartPreviewProps {
+  chart?: AiChartSchema;
+}
+
+/**
+ * A2UI component registered for the `gongxue-chart-catalog` catalog.
+ * Receives the validated tabular chart data through data binding and
+ * renders an ECharts option built from it.
+ */
+const ChartPreview: React.FC<ChartPreviewProps> = ({ chart }) => {
+  const option = useMemo<EChartsOption>(() => (chart ? buildOption(chart) : {}), [chart]);
+  const [instance, setInstance] = useState<EChartsType | null>(null);
+  if (!chart) return null;
+
+  const downloadImage = () => {
+    if (!instance) return;
+    const url = instance.getDataURL({
+      type: 'png',
+      pixelRatio: 2,
+      backgroundColor: '#fff',
+    });
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = `${chart.title || '图表'}.png`;
+    document.body.appendChild(link);
+    link.click();
+    link.remove();
+  };
+
+  return (
+    <div className="ai-chat-chart-card">
+      <div className="ai-chat-chart-card__header">
+        <Typography.Text strong>{chart.title}</Typography.Text>
+        <span className="ai-chat-chart-card__header-actions">
+          <Tag color="blue">{CHART_TYPE_LABELS[chart.chartType] ?? chart.chartType}</Tag>
+          <Tooltip title="下载图片">
+            <Button
+              type="text"
+              size="small"
+              className="ai-chat-chart-card__download"
+              aria-label="下载图表图片"
+              icon={<DownloadOutlined />}
+              onClick={downloadImage}
+              disabled={!instance}
+            />
+          </Tooltip>
+        </span>
+      </div>
+      <Suspense fallback={<Spin size="small" />}>
+        <ReactECharts option={option} style={{ width: '100%', height: 260 }} onReady={setInstance} />
+      </Suspense>
+    </div>
+  );
+};
+
+export interface DynamicChartProps {
+  chart: AiChartSchema;
+}
+
+/**
+ * Chart card rendered through the official @ant-design/x-card renderer.
+ * Display-only: no submit endpoint, the schema lives in message metadata
+ * so history replays identically.
+ */
+export const DynamicChart: React.FC<DynamicChartProps> = ({ chart }) => {
+  const commandsRef = useRef<XAgentCommand_v0_9[]>([]);
+  const [commands, setCommands] = useState<XAgentCommand_v0_9[]>([]);
+  const idRef = useRef<string>('');
+
+  useEffect(() => {
+    const sid = surfaceId(chart.id);
+    if (idRef.current !== sid) {
+      commandsRef.current = [];
+      idRef.current = sid;
+    }
+    const cmds = commandsRef.current;
+    if (cmds.length === 0) {
+      cmds.push({
+        version: 'v0.9',
+        createSurface: { surfaceId: sid, catalogId: CHART_CATALOG_ID },
+      });
+    }
+    cmds.push({
+      version: 'v0.9',
+      updateDataModel: {
+        surfaceId: sid,
+        path: '/chart',
+        value: chart,
+      },
+    });
+    cmds.push({
+      version: 'v0.9',
+      updateComponents: {
+        surfaceId: sid,
+        components: [
+          {
+            id: 'root',
+            component: 'ChartPreview',
+            chart: { path: '/chart' },
+          },
+        ],
+      },
+    });
+    setCommands([...cmds]);
+  }, [chart]);
+
+  return (
+    <div className="ai-chat-chart">
+      <XCard.Box components={{ ChartPreview }} commands={commands}>
+        <XCard.Card id={surfaceId(chart.id)} />
+      </XCard.Box>
+    </div>
+  );
+};

apps/admin/src/components/AiChat/DynamicForm.tsx

@@ -0,0 +1,254 @@
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import {
+  XCard,
+  registerCatalog,
+  type ActionPayload,
+  type XAgentCommand_v0_9,
+} from '@ant-design/x-card';
+import {
+  Alert,
+  Button,
+  DatePicker,
+  Flex,
+  Form,
+  Input,
+  InputNumber,
+  Select,
+  Typography,
+} from 'antd';
+import dayjs from 'dayjs';
+import type { AiFormField, AiFormSchema } from './types';
+
+const FORM_CATALOG_ID = 'gongxue-form-catalog';
+
+registerCatalog({
+  catalogId: FORM_CATALOG_ID,
+  components: {
+    FormPreview: {
+      type: 'object',
+      properties: {
+        form: { type: 'object' },
+        disabled: { type: 'boolean' },
+      },
+    },
+  },
+});
+
+function surfaceId(formId: string): string {
+  return `form-${formId}`;
+}
+
+function initialValue(field: AiFormField): unknown {
+  if (field.type === 'date' && typeof field.defaultValue === 'string') {
+    const parsed = dayjs(field.defaultValue);
+    return parsed.isValid() ? parsed : undefined;
+  }
+  return field.defaultValue;
+}
+
+function normalizeValues(
+  fields: AiFormField[],
+  raw: Record<string, unknown>,
+): Record<string, unknown> {
+  const values: Record<string, unknown> = {};
+  for (const field of fields) {
+    const value = raw[field.name];
+    if (value === undefined || value === null || value === '') continue;
+    values[field.name] =
+      field.type === 'date' && dayjs.isDayjs(value) ? value.format('YYYY-MM-DD') : value;
+  }
+  return values;
+}
+
+interface FormPreviewProps {
+  form?: AiFormSchema & {
+    submitting?: boolean;
+    submitted?: boolean;
+    error?: string | null;
+  };
+  disabled?: boolean;
+  onAction?: (name: string, context: Record<string, unknown>) => void;
+}
+
+/**
+ * A2UI component registered for the `gongxue-form-catalog` catalog.
+ * Receives the validated form schema through data binding and reports
+ * normalized values back through the `form:submit` action.
+ */
+const FormPreview: React.FC<FormPreviewProps> = ({ form, disabled, onAction }) => {
+  const submitting = Boolean(form?.submitting);
+  const initialValues = useMemo(
+    () =>
+      Object.fromEntries((form?.fields ?? []).map((field) => [field.name, initialValue(field)])),
+    [form?.fields],
+  );
+  if (!form) return null;
+  const finished = Boolean(form.submitted) || form.status === 'submitted';
+
+  const handleFinish = (values: Record<string, unknown>) => {
+    onAction?.('form:submit', { values: normalizeValues(form.fields, values) });
+  };
+
+  return (
+    <Flex vertical gap={8}>
+      <Typography.Text strong>{form.title}</Typography.Text>
+      {form.description && (
+        <Typography.Text type="secondary" className="ai-chat-dynamic-form__desc">
+          {form.description}
+        </Typography.Text>
+      )}
+      {finished ? (
+        <Alert type="success" showIcon message="已提交，AI 正在处理…" />
+      ) : (
+        <Form
+          layout="vertical"
+          size="small"
+          initialValues={initialValues}
+          onFinish={(values) => void handleFinish(values as Record<string, unknown>)}
+          disabled={disabled || submitting}
+          requiredMark={false}
+        >
+          {form.fields.map((field) => (
+            <Form.Item
+              key={field.name}
+              name={field.name}
+              label={field.label}
+              rules={[
+                {
+                  required: field.required,
+                  message: field.required
+                    ? field.type === 'select' || field.type === 'date'
+                      ? `请选择${field.label}`
+                      : `请输入${field.label}`
+                    : undefined,
+                },
+              ]}
+            >
+              {field.type === 'textarea' ? (
+                <Input.TextArea rows={3} placeholder={field.placeholder} />
+              ) : field.type === 'number' ? (
+                <InputNumber
+                  className="ai-chat-dynamic-form__number"
+                  placeholder={field.placeholder}
+                />
+              ) : field.type === 'select' ? (
+                <Select
+                  allowClear={!field.required}
+                  placeholder={field.placeholder}
+                  options={field.options}
+                />
+              ) : field.type === 'date' ? (
+                <DatePicker
+                  className="ai-chat-dynamic-form__date"
+                  placeholder={field.placeholder}
+                />
+              ) : (
+                <Input placeholder={field.placeholder} />
+              )}
+            </Form.Item>
+          ))}
+          {form.error && (
+            <Alert
+              type="error"
+              showIcon
+              title={form.error}
+              className="ai-chat-dynamic-form__error"
+            />
+          )}
+          <Button type="primary" htmlType="submit" loading={submitting} disabled={disabled}>
+            {form.submitLabel || '提交'}
+          </Button>
+        </Form>
+      )}
+    </Flex>
+  );
+};
+
+export interface DynamicFormProps {
+  form: AiFormSchema;
+  disabled?: boolean;
+  onSubmit: (values: Record<string, unknown>) => void | Promise<void>;
+}
+
+/**
+ * A2UI form rendered through the official @ant-design/x-card renderer.
+ * The validated schema is bound into the surface data model; submit
+ * success/failure/loading transitions are pushed as incremental commands.
+ */
+export const DynamicForm: React.FC<DynamicFormProps> = ({ form, disabled, onSubmit }) => {
+  const [submitting, setSubmitting] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const commandsRef = useRef<XAgentCommand_v0_9[]>([]);
+  const [commands, setCommands] = useState<XAgentCommand_v0_9[]>([]);
+  const idRef = useRef<string>('');
+
+  useEffect(() => {
+    const sid = surfaceId(form.id);
+    if (idRef.current !== sid) {
+      commandsRef.current = [];
+      idRef.current = sid;
+    }
+    const cmds = commandsRef.current;
+    if (cmds.length === 0) {
+      cmds.push({
+        version: 'v0.9',
+        createSurface: { surfaceId: sid, catalogId: FORM_CATALOG_ID },
+      });
+    }
+    cmds.push({
+      version: 'v0.9',
+      updateDataModel: {
+        surfaceId: sid,
+        path: '/form',
+        value: { ...form, submitting, submitted, error },
+      },
+    });
+    cmds.push({
+      version: 'v0.9',
+      updateComponents: {
+        surfaceId: sid,
+        components: [
+          {
+            id: 'root',
+            component: 'FormPreview',
+            form: { path: '/form' },
+            disabled: Boolean(disabled),
+          },
+        ],
+      },
+    });
+    setCommands([...cmds]);
+  }, [disabled, error, form, submitted, submitting]);
+
+  const handleSubmit = async (values: Record<string, unknown>) => {
+    if (submitting) return;
+    setSubmitting(true);
+    setError(null);
+    try {
+      await onSubmit(values);
+      setSubmitted(true);
+    } catch (reason) {
+      setError(reason instanceof Error ? reason.message : '提交失败，请稍后重试');
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleAction = (payload: ActionPayload) => {
+    if (payload.name !== 'form:submit') return;
+    const values =
+      payload.context?.values && typeof payload.context.values === 'object'
+        ? (payload.context.values as Record<string, unknown>)
+        : {};
+    void handleSubmit(values);
+  };
+
+  return (
+    <div className="ai-chat-dynamic-form">
+      <XCard.Box components={{ FormPreview }} commands={commands} onAction={handleAction}>
+        <XCard.Card id={surfaceId(form.id)} />
+      </XCard.Box>
+    </div>
+  );
+};

apps/admin/src/components/AiChat/DynamicReview.tsx

@@ -0,0 +1,600 @@
+import React, { useEffect, useRef, useState } from 'react';
+import {
+  XCard,
+  registerCatalog,
+  type ActionPayload,
+  type XAgentCommand_v0_9,
+} from '@ant-design/x-card';
+import {
+  Alert,
+  Button,
+  Flex,
+  Popconfirm,
+  Steps,
+  Table,
+  Tag,
+  Typography,
+  type TableProps,
+} from 'antd';
+import type { AiReviewRow, AiReviewSchema, AiReviewSection, AiReviewSectionType } from './types';
+import {
+  GROUP_STATUS_LABELS,
+  SECTION_ORDER,
+  SECTION_STATUS_LABELS,
+  SECTION_TYPE_LABELS,
+  dependencyHint,
+  groupSections,
+  groupStatus,
+  sectionCount,
+  sectionResultText,
+  sectionStatus,
+  sectionType,
+} from './reviewSection';
+
+const REVIEW_CATALOG_ID = 'gongxue-review-catalog';
+
+registerCatalog({
+  catalogId: REVIEW_CATALOG_ID,
+  components: {
+    ReviewPreview: {
+      type: 'object',
+      properties: {
+        review: { type: 'object' },
+        disabled: { type: 'boolean' },
+        activeKey: { type: 'string' },
+        activeType: { type: 'string' },
+        submittingKey: { type: ['string', 'null'] },
+        submittingGroup: { type: 'boolean' },
+        error: { type: ['string', 'null'] },
+      },
+    },
+  },
+});
+
+function surfaceId(reviewId: string): string {
+  return `review-${reviewId}`;
+}
+
+function errorMessage(reason: unknown): string {
+  if (reason instanceof Error) return reason.message;
+  if (reason && typeof reason === 'object' && 'message' in reason) {
+    return String((reason as { message?: unknown }).message ?? '确认失败，请稍后重试');
+  }
+  return '确认失败，请稍后重试';
+}
+
+function SectionTable({ section }: { section: AiReviewSection }) {
+  const columns: TableProps<AiReviewRow>['columns'] = section.columns.map((column) => ({
+    title: column.title,
+    dataIndex: column.key,
+    key: column.key,
+    ellipsis: true,
+    render: (value: unknown) =>
+      value === null || value === undefined || value === '' ? (
+        <Typography.Text type="secondary">-</Typography.Text>
+      ) : (
+        String(value)
+      ),
+  }));
+  return (
+    <Table<AiReviewRow>
+      size="small"
+      rowKey="__rowKey"
+      columns={columns}
+      dataSource={section.rows.map((row, index) => ({ ...row, __rowKey: `row-${index}` }))}
+      pagination={{ pageSize: 10, size: 'small', hideOnSinglePage: true }}
+      scroll={{ x: 'max-content' }}
+    />
+  );
+}
+
+interface ReviewPreviewProps {
+  review?: AiReviewSchema & {
+    submitting?: boolean;
+    activeKey?: string;
+    activeType?: AiReviewSectionType;
+    submittingKey?: string | null;
+    submittingGroup?: boolean;
+    error?: string | null;
+  };
+  disabled?: boolean;
+  onAction?: (name: string, context: Record<string, unknown>) => void;
+}
+
+const ReviewPreview: React.FC<ReviewPreviewProps> = ({ review, disabled, onAction }) => {
+  if (!review) return null;
+  const submitted = review.status === 'submitted';
+  const expired = review.status === 'expired';
+  const submitting = Boolean(review.submitting);
+  const submittingKey = review.submittingKey ?? null;
+  const submittingGroup = Boolean(review.submittingGroup);
+  const sections = review.sections;
+  const presentTypes = SECTION_ORDER.filter((type) =>
+    sections.some((section) => sectionType(section) === type),
+  );
+  const activeType = presentTypes.includes(review.activeType as AiReviewSectionType)
+    ? (review.activeType as AiReviewSectionType)
+    : presentTypes[0];
+  if (!activeType) return null;
+  const activeSection =
+    sections.find((section) => section.key === review.activeKey) ??
+    groupSections(sections, activeType)[0];
+  const activeStatus = activeSection ? sectionStatus(activeSection) : 'pending';
+  const dependency =
+    activeSection === undefined ? null : dependencyHint(sections, sectionType(activeSection));
+  const typeItems = presentTypes.map((type, index) => {
+    const items = groupSections(sections, type);
+    const status = groupStatus(sections, type, submittingKey, submittingGroup, activeType);
+    const stepStatus: 'finish' | 'error' | 'process' | 'wait' =
+      status === 'submitted'
+        ? 'finish'
+        : status === 'failed'
+          ? 'error'
+          : status === 'importing' || type === activeType
+            ? 'process'
+            : 'wait';
+    return {
+      key: type,
+      title: `${SECTION_TYPE_LABELS[type]}（${items.reduce((sum, item) => sum + sectionCount(item), 0)}）`,
+      content: GROUP_STATUS_LABELS[status],
+      status: stepStatus,
+      index,
+    };
+  });
+  const group = groupSections(sections, activeType);
+  const typeTotal = group.reduce((sum, section) => sum + sectionCount(section), 0);
+  const groupDep = dependencyHint(sections, activeType);
+  const groupReady =
+    !submitted &&
+    !expired &&
+    !disabled &&
+    !submitting &&
+    !submittingKey &&
+    !submittingGroup &&
+    group.length > 0 &&
+    !group.every((section) => sectionStatus(section) === 'submitted') &&
+    !groupDep;
+  const anyRunning = submitting || Boolean(submittingKey) || submittingGroup;
+  const allIssues = sections.flatMap((section) => section.issues);
+  const allRows = sections.reduce((sum, section) => sum + sectionCount(section), 0);
+
+  return (
+    <div className="ai-chat-review-card">
+      <Flex justify="space-between" align="center" wrap gap={8}>
+        <Typography.Text strong className="ai-chat-review-card__title">
+          {review.title}
+        </Typography.Text>
+        {submitted ? (
+          <Tag color="success">已导入</Tag>
+        ) : expired ? (
+          <Tag>已失效</Tag>
+        ) : anyRunning ? (
+          <Tag color="processing">导入中</Tag>
+        ) : (
+          <Tag color="gold">待确认</Tag>
+        )}
+      </Flex>
+      {review.summary && (
+        <Typography.Paragraph type="secondary" className="ai-chat-review-card__summary">
+          {review.summary}
+        </Typography.Paragraph>
+      )}
+      {expired && (
+        <Alert
+          type="warning"
+          showIcon
+          message="此导入预览已被新的预览替代，已失效"
+          description="如需导入，请使用最新的预览卡。"
+        />
+      )}
+      <Steps
+        size="small"
+        current={Math.max(
+          0,
+          typeItems.findIndex((item) => item.key === activeType),
+        )}
+        items={typeItems.map((item) => ({
+          key: item.key,
+          title: item.title,
+          content: item.content,
+          status: item.status,
+        }))}
+        onChange={(index) => {
+          const type = typeItems[index]?.key;
+          if (type) onAction?.('review:selectType', { type });
+        }}
+      />
+      {activeType && (
+        <Flex vertical gap={8} className="ai-chat-review-card__group">
+          <Flex justify="space-between" align="center" wrap gap={8}>
+            <Flex vertical gap={2}>
+              <Typography.Text strong>
+                {SECTION_TYPE_LABELS[activeType]} · 共 {group.length} 张表 / {typeTotal} 行
+              </Typography.Text>
+              <Typography.Text type="secondary">
+                {
+                  GROUP_STATUS_LABELS[
+                    groupStatus(sections, activeType, submittingKey, submittingGroup, activeType)
+                  ]
+                }
+              </Typography.Text>
+            </Flex>
+            {groupDep && (
+              <Alert
+                type="warning"
+                showIcon
+                title={
+                  groupDep.step === -1
+                    ? `「${groupDep.title}」分表尚未生成或导入，请先确认前置步骤`
+                    : `请先确认第 ${groupDep.step + 1} 步「${groupDep.title}」`
+                }
+              />
+            )}
+            {!submitted && !expired && group.length > 0 && (
+              <Popconfirm
+                title={`确认导入本组 ${group.length} 张表？`}
+                description={`本组共 ${typeTotal} 行，确认后将按顺序逐表导入。`}
+                okText="确认导入"
+                cancelText="取消"
+                disabled={!groupReady}
+                onConfirm={() =>
+                  onAction?.('review:confirmGroup', {
+                    reviewId: review.id,
+                    type: activeType,
+                  })
+                }
+              >
+                <Button type="primary" loading={submittingGroup} disabled={!groupReady}>
+                  {groupStatus(sections, activeType, submittingKey, submittingGroup, activeType) ===
+                  'submitted'
+                    ? '已导入'
+                    : `确认本组 ${group.length} 张表`}
+                </Button>
+              </Popconfirm>
+            )}
+          </Flex>
+          <Flex vertical gap={8} className="ai-chat-review-card__sheets">
+            {group.map((section, index) => {
+              const status = sectionStatus(section);
+              const dep = dependencyHint(sections, sectionType(section));
+              const canConfirm =
+                !submitted &&
+                !expired &&
+                !disabled &&
+                !anyRunning &&
+                status !== 'submitted' &&
+                status !== 'skipped' &&
+                !dep;
+              return (
+                <Flex
+                  key={section.key}
+                  justify="space-between"
+                  align="center"
+                  wrap
+                  gap={8}
+                  className="ai-chat-review-card__sheet"
+                  onClick={() => onAction?.('review:selectStep', { sectionKey: section.key })}
+                >
+                  <Flex vertical gap={2} style={{ minWidth: 160 }}>
+                    <Typography.Text>
+                      {index + 1}. {section.title}
+                      {section.sheet ? (
+                        <Typography.Text type="secondary">（{section.sheet}）</Typography.Text>
+                      ) : null}
+                    </Typography.Text>
+                    <Typography.Text type="secondary">
+                      {sectionCount(section)} 行 · {SECTION_STATUS_LABELS[status]}
+                    </Typography.Text>
+                  </Flex>
+                  <Button
+                    size="small"
+                    loading={submittingKey === section.key}
+                    disabled={!canConfirm}
+                    onClick={(event) => {
+                      event.stopPropagation();
+                      onAction?.('review:confirmStep', {
+                        reviewId: review.id,
+                        sectionKey: section.key,
+                      });
+                    }}
+                  >
+                    {status === 'failed'
+                      ? '重试导入本步'
+                      : status === 'submitted'
+                        ? '已导入'
+                        : status === 'skipped'
+                          ? '已跳过'
+                          : expired
+                            ? '已失效'
+                            : '确认导入本步'}
+                  </Button>
+                </Flex>
+              );
+            })}
+          </Flex>
+          {activeSection && (
+            <Flex vertical gap={8} className="ai-chat-review-card__step">
+              {activeSection.issues.length > 0 && (
+                <Alert
+                  type="warning"
+                  showIcon
+                  title={`${activeSection.title}：${activeSection.issues.length} 条待处理`}
+                  description={
+                    <ul className="ai-chat-review__issues">
+                      {activeSection.issues.slice(0, 20).map((issue, issueIndex) => (
+                        <li key={issueIndex}>{issue}</li>
+                      ))}
+                    </ul>
+                  }
+                />
+              )}
+              <SectionTable section={activeSection} />
+              {dependency && (
+                <Alert
+                  type="warning"
+                  showIcon
+                  title={
+                    dependency.step === -1
+                      ? `「${dependency.title}」分表尚未生成或导入，请先确认前置步骤`
+                      : `请先确认第 ${dependency.step + 1} 步「${dependency.title}」`
+                  }
+                />
+              )}
+              {activeStatus === 'failed' && (
+                <Alert type="error" showIcon message="本步导入失败，可重试" />
+              )}
+              {activeSection.resultSummary && activeStatus === 'submitted' && (
+                <Typography.Text type="secondary" className="ai-chat-review-card__step-result">
+                  {sectionResultText(activeSection)}
+                </Typography.Text>
+              )}
+            </Flex>
+          )}
+        </Flex>
+      )}
+      <Flex
+        justify="space-between"
+        align="center"
+        wrap
+        gap={8}
+        className="ai-chat-review-card__footer"
+      >
+        <Typography.Text type="secondary">
+          共 {allRows} 行，含 {allIssues.length} 条提示
+        </Typography.Text>
+        {!submitted && !expired && (
+          <Popconfirm
+            title={`确认导入全部 ${sections.length} 张表？`}
+            description={`全部共 ${allRows} 行，将按类型与依赖顺序逐表导入。`}
+            okText="确认导入"
+            cancelText="取消"
+            disabled={submitting || anyRunning || disabled}
+            onConfirm={() => onAction?.('review:submit', { reviewId: review.id })}
+          >
+            <Button type="primary" loading={submitting} disabled={disabled || anyRunning}>
+              全部确认并入库
+            </Button>
+          </Popconfirm>
+        )}
+      </Flex>
+      {submitted && <Alert type="success" showIcon message="已确认导入，数据已入库" />}
+      {review.error && (
+        <Alert
+          type="error"
+          showIcon
+          title={review.error}
+          className="ai-chat-review-card__step-error"
+        />
+      )}
+    </div>
+  );
+};
+
+export interface DynamicReviewProps {
+  review: AiReviewSchema;
+  disabled?: boolean;
+  messageId?: number;
+  onSubmit: (reviewId: string) => void | Promise<void>;
+  onConfirmStep?: (
+    messageId: number | undefined,
+    reviewId: string,
+    sectionKey: string,
+  ) => AiReviewSchema | Promise<AiReviewSchema> | void;
+  onConfirmGroup?: (
+    messageId: number | undefined,
+    reviewId: string,
+    type: AiReviewSectionType,
+  ) => AiReviewSchema | Promise<AiReviewSchema> | void;
+}
+
+/**
+ * Batch-import review card rendered through the official A2UI renderer
+ * (@ant-design/x-card). Sections are grouped by business type; each sheet is
+ * confirmed independently, the whole type group can be confirmed together, or
+ * everything can be confirmed in one flow.
+ */
+export const DynamicReview: React.FC<DynamicReviewProps> = ({
+  review,
+  disabled,
+  messageId,
+  onSubmit,
+  onConfirmStep,
+  onConfirmGroup,
+}) => {
+  const [submitting, setSubmitting] = useState(false);
+  const [submittingKey, setSubmittingKey] = useState<string | null>(null);
+  const [submittingGroup, setSubmittingGroup] = useState(false);
+  const [activeKey, setActiveKey] = useState<string | undefined>(undefined);
+  const [activeType, setActiveType] = useState<AiReviewSectionType | undefined>(undefined);
+  const activeTypeRef = useRef<AiReviewSectionType | undefined>(activeType);
+  activeTypeRef.current = activeType;
+  const [localReview, setLocalReview] = useState<AiReviewSchema>(review);
+  const [error, setError] = useState<string | null>(null);
+  const commandsRef = useRef<XAgentCommand_v0_9[]>([]);
+  const [commands, setCommands] = useState<XAgentCommand_v0_9[]>([]);
+  const idRef = useRef<string>('');
+
+  useEffect(() => {
+    setLocalReview(review);
+    const types = SECTION_ORDER.filter((type) =>
+      review.sections.some((section) => sectionType(section) === type),
+    );
+    const preferredType =
+      activeTypeRef.current && types.includes(activeTypeRef.current)
+        ? activeTypeRef.current
+        : types[0];
+    setActiveType(preferredType);
+    setActiveKey((current) =>
+      current &&
+      review.sections.some(
+        (section) => section.key === current && sectionType(section) === preferredType,
+      )
+        ? current
+        : review.sections.find((section) => sectionType(section) === preferredType)?.key,
+    );
+  }, [review]);
+
+  useEffect(() => {
+    const sid = surfaceId(localReview.id);
+    if (idRef.current !== sid) {
+      commandsRef.current = [];
+      idRef.current = sid;
+    }
+    const cmds = commandsRef.current;
+    if (cmds.length === 0) {
+      cmds.push({
+        version: 'v0.9',
+        createSurface: { surfaceId: sid, catalogId: REVIEW_CATALOG_ID },
+      });
+    }
+    cmds.push({
+      version: 'v0.9',
+      updateDataModel: {
+        surfaceId: sid,
+        path: '/review',
+        value: {
+          ...localReview,
+          submitting,
+          activeKey,
+          activeType,
+          submittingKey,
+          submittingGroup,
+          error,
+        },
+      },
+    });
+    cmds.push({
+      version: 'v0.9',
+      updateComponents: {
+        surfaceId: sid,
+        components: [
+          {
+            id: 'root',
+            component: 'ReviewPreview',
+            review: { path: '/review' },
+            disabled: Boolean(disabled),
+          },
+        ],
+      },
+    });
+    setCommands([...cmds]);
+  }, [
+    activeKey,
+    activeType,
+    disabled,
+    error,
+    localReview,
+    submitting,
+    submittingGroup,
+    submittingKey,
+  ]);
+
+  const handleSubmit = async (reviewId: string) => {
+    if (submitting) return;
+    setSubmitting(true);
+    setError(null);
+    try {
+      await onSubmit(reviewId);
+    } catch (reason) {
+      setError(errorMessage(reason));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const handleConfirmStep = async (reviewId: string, sectionKey: string) => {
+    if (submittingKey) return;
+    setSubmittingKey(sectionKey);
+    setError(null);
+    try {
+      const updated = await onConfirmStep?.(messageId, reviewId, sectionKey);
+      if (updated) setLocalReview(updated);
+    } catch (reason) {
+      setError(errorMessage(reason));
+    } finally {
+      setSubmittingKey(null);
+    }
+  };
+
+  const handleConfirmGroup = async (reviewId: string, type: AiReviewSectionType) => {
+    if (submittingGroup) return;
+    setSubmittingGroup(true);
+    setError(null);
+    try {
+      const updated = await onConfirmGroup?.(messageId, reviewId, type);
+      if (updated) setLocalReview(updated);
+    } catch (reason) {
+      setError(errorMessage(reason));
+    } finally {
+      setSubmittingGroup(false);
+    }
+  };
+
+  const handleAction = (payload: ActionPayload) => {
+    const context = payload.context ?? {};
+    if (payload.name === 'review:submit') {
+      const reviewId = typeof context.reviewId === 'string' ? context.reviewId : localReview.id;
+      void handleSubmit(reviewId);
+      return;
+    }
+    if (payload.name === 'review:selectType') {
+      const type = context.type as AiReviewSectionType | undefined;
+      if (type && SECTION_ORDER.includes(type)) {
+        setActiveType(type);
+        setActiveKey(localReview.sections.find((section) => sectionType(section) === type)?.key);
+      }
+      return;
+    }
+    if (payload.name === 'review:selectStep') {
+      if (typeof context.sectionKey === 'string') {
+        const section = localReview.sections.find((item) => item.key === context.sectionKey);
+        setActiveKey(context.sectionKey);
+        if (section) setActiveType(sectionType(section));
+      }
+      return;
+    }
+    if (payload.name === 'review:confirmStep') {
+      const reviewId = typeof context.reviewId === 'string' ? context.reviewId : localReview.id;
+      if (typeof context.sectionKey === 'string') {
+        void handleConfirmStep(reviewId, context.sectionKey);
+      }
+      return;
+    }
+    if (payload.name === 'review:confirmGroup') {
+      const reviewId = typeof context.reviewId === 'string' ? context.reviewId : localReview.id;
+      const type = context.type as AiReviewSectionType | undefined;
+      if (type && SECTION_ORDER.includes(type)) {
+        void handleConfirmGroup(reviewId, type);
+      }
+    }
+  };
+
+  return (
+    <div className="ai-chat-review">
+      <XCard.Box components={{ ReviewPreview }} commands={commands} onAction={handleAction}>
+        <XCard.Card id={surfaceId(localReview.id)} />
+      </XCard.Box>
+      {error && <Alert type="error" showIcon title={error} className="ai-chat-review__error" />}
+    </div>
+  );
+};

apps/admin/src/components/AiChat/LiteCodeHighlighter.tsx

@@ -0,0 +1,49 @@
+import SyntaxHighlighter from 'react-syntax-highlighter/dist/esm/prism-light';
+import { oneLight } from 'react-syntax-highlighter/dist/esm/styles/prism';
+import tsx from 'react-syntax-highlighter/dist/esm/languages/prism/tsx';
+import typescript from 'react-syntax-highlighter/dist/esm/languages/prism/typescript';
+import javascript from 'react-syntax-highlighter/dist/esm/languages/prism/javascript';
+import json from 'react-syntax-highlighter/dist/esm/languages/prism/json';
+import bash from 'react-syntax-highlighter/dist/esm/languages/prism/bash';
+import sql from 'react-syntax-highlighter/dist/esm/languages/prism/sql';
+import css from 'react-syntax-highlighter/dist/esm/languages/prism/css';
+
+// 只注册 AI 对话里常用的语言，避免 @ant-design/x 的 CodeHighlighter
+// 把所有 prism 语言都打进主包
+SyntaxHighlighter.registerLanguage('tsx', tsx);
+SyntaxHighlighter.registerLanguage('typescript', typescript);
+SyntaxHighlighter.registerLanguage('javascript', javascript);
+SyntaxHighlighter.registerLanguage('json', json);
+SyntaxHighlighter.registerLanguage('bash', bash);
+SyntaxHighlighter.registerLanguage('shell', bash);
+SyntaxHighlighter.registerLanguage('sql', sql);
+SyntaxHighlighter.registerLanguage('css', css);
+
+const SUPPORTED_LANGUAGES = new Set([
+  'tsx',
+  'typescript',
+  'javascript',
+  'json',
+  'bash',
+  'shell',
+  'sql',
+  'css',
+]);
+
+interface LiteCodeHighlighterProps {
+  lang?: string;
+  children: string;
+}
+
+export function LiteCodeHighlighter({ lang, children }: LiteCodeHighlighterProps) {
+  const language = lang && SUPPORTED_LANGUAGES.has(lang) ? lang : undefined;
+  return (
+    <SyntaxHighlighter
+      language={language}
+      style={oneLight}
+      customStyle={{ margin: '12px 0', borderRadius: 8, fontSize: 13 }}
+    >
+      {children}
+    </SyntaxHighlighter>
+  );
+}

apps/admin/src/components/AiChat/LiteMermaid.tsx

@@ -0,0 +1,48 @@
+import { useEffect, useRef, useState } from 'react';
+
+interface LiteMermaidProps {
+  children: string;
+}
+
+/**
+ * 轻量 Mermaid 渲染：动态 import mermaid，只有出现 mermaid 代码块时才加载
+ * mermaid 及其解析器/图布局依赖，避免随 AI 抽屉主包一起加载。
+ */
+export function LiteMermaid({ children }: LiteMermaidProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    const container = containerRef.current;
+    if (!container) return;
+
+    void (async () => {
+      try {
+        const mermaid = (await import('mermaid')).default;
+        mermaid.initialize({ startOnLoad: false, theme: 'neutral', securityLevel: 'strict' });
+        const { svg } = await mermaid.render(`mermaid-${crypto.randomUUID()}`, children);
+        if (!cancelled) {
+          const doc = new DOMParser().parseFromString(svg, 'image/svg+xml');
+          container.replaceChildren(doc.documentElement);
+          setError(null);
+        }
+      } catch (e) {
+        if (!cancelled) {
+          setError(e instanceof Error ? e.message : '图表渲染失败');
+        }
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [children]);
+
+  if (error) {
+    return (
+      <pre style={{ whiteSpace: 'pre-wrap', color: '#cf1322', fontSize: 12 }}>{children}</pre>
+    );
+  }
+  return <div ref={containerRef} className="ai-chat-mermaid" />;
+}

apps/admin/src/components/AiChat/api.integration.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import api from '../../api';
+import { aiChatApi } from './api';
+
+describe('AI chat API adapter', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('unwraps the backend success/data response', async () => {
+    vi.spyOn(api, 'get').mockResolvedValue({
+      success: true,
+      data: [
+        {
+          id: 1,
+          title: '会话',
+          lockedSkillKey: null,
+          createdAt: '2026-07-23T00:00:00.000Z',
+          updatedAt: '2026-07-23T00:00:00.000Z',
+          lastMessageAt: null,
+        },
+      ],
+    });
+
+    await expect(aiChatApi.listConversations()).resolves.toMatchObject([{ id: 1, title: '会话' }]);
+  });
+
+  it('loads every history page in chronological page order', async () => {
+    vi.spyOn(api, 'get')
+      .mockResolvedValueOnce({
+        success: true,
+        data: { items: [{ id: 1 }], total: 101, page: 1, limit: 100 },
+      })
+      .mockResolvedValueOnce({
+        success: true,
+        data: { items: [{ id: 101 }], total: 101, page: 2, limit: 100 },
+      });
+
+    const page = await aiChatApi.listMessages(3);
+    expect(page.items.map((item) => item.id)).toEqual([1, 101]);
+  });
+
+  it('confirmReviewStep posts to the per-section confirm endpoint', async () => {
+    const updated = {
+      id: 'review-1',
+      title: '批量导入',
+      status: 'pending',
+      sections: [
+        { key: 'students', type: 'students', title: '学生', status: 'submitted' },
+      ],
+    };
+    vi.spyOn(api, 'post').mockResolvedValue({ success: true, data: updated });
+
+    await expect(aiChatApi.confirmReviewStep('review-1', 'students')).resolves.toEqual(updated);
+    expect(api.post).toHaveBeenCalledWith(
+      '/ai/chat/reviews/review-1/steps/students/confirm',
+    );
+  });
+
+  it('confirmReviewGroup posts to the per-type confirm endpoint', async () => {
+    const updated = {
+      id: 'review-1',
+      title: '批量导入',
+      status: 'pending',
+      sections: [
+        { key: 'checkins_a', type: 'checkins', title: '入住A', status: 'submitted' },
+      ],
+    };
+    vi.spyOn(api, 'post').mockResolvedValue({ success: true, data: updated });
+
+    await expect(aiChatApi.confirmReviewGroup('review-1', 'checkins')).resolves.toEqual(updated);
+    expect(api.post).toHaveBeenCalledWith(
+      '/ai/chat/reviews/review-1/types/checkins/confirm',
+    );
+  });
+});

apps/admin/src/components/AiChat/api.ts

@@ -0,0 +1,85 @@
+import api from '../../api';
+import type {
+  AiApiResponse,
+  AiAttachment,
+  AiConversation,
+  AiMessagePage,
+  AiReviewSchema,
+  AiReviewSection,
+  AiReviewSectionType,
+  AiSkill,
+} from './types';
+
+const basePath = '/ai/chat/conversations';
+
+export const aiChatApi = {
+  listSkills: async () => (await api.get<AiApiResponse<AiSkill[]>>('/ai/chat/skills')).data,
+  listConversations: async () => (await api.get<AiApiResponse<AiConversation[]>>(basePath)).data,
+  createConversation: async (input?: { title?: string; lockedSkillKey?: string | null }) =>
+    (await api.post<AiApiResponse<AiConversation>>(basePath, input ?? {})).data,
+  updateConversation: async (
+    id: number,
+    input: { title?: string; lockedSkillKey?: string | null },
+  ) => (await api.patch<AiApiResponse<AiConversation>>(`${basePath}/${id}`, input)).data,
+  deleteConversation: (id: number) => api.delete<void>(`${basePath}/${id}`),
+  deleteAllConversations: async () =>
+    (await api.delete<{ success: boolean; data: { deleted: number } }>(basePath)).data,
+  deleteMessage: async (conversationId: number, messageId: number) =>
+    (
+      await api.delete<AiApiResponse<{ deletedIds: number[] }>>(
+        `${basePath}/${conversationId}/messages/${messageId}`,
+      )
+    ).data,
+  uploadAttachment: async (file: File): Promise<AiAttachment> => {
+    const form = new FormData();
+    form.append('file', file);
+    return (
+      await api.post<AiApiResponse<AiAttachment>>('/ai/chat/attachments', form, {
+        headers: { 'Content-Type': 'multipart/form-data' },
+        timeout: 120_000,
+      })
+    ).data;
+  },
+  deleteAttachment: (id: number) => api.delete<void>(`/ai/chat/attachments/${id}`),
+  confirmReviewStep: async (
+    reviewId: string,
+    sectionKey: AiReviewSection['key'],
+  ): Promise<AiReviewSchema> =>
+    (
+      await api.post<AiApiResponse<AiReviewSchema>>(
+        `/ai/chat/reviews/${reviewId}/steps/${sectionKey}/confirm`,
+      )
+    ).data,
+  confirmReviewGroup: async (
+    reviewId: string,
+    type: AiReviewSectionType,
+  ): Promise<AiReviewSchema> =>
+    (
+      await api.post<AiApiResponse<AiReviewSchema>>(
+        `/ai/chat/reviews/${reviewId}/types/${type}/confirm`,
+      )
+    ).data,
+  listMessages: async (id: number): Promise<AiMessagePage> => {
+    const first = (
+      await api.get<AiApiResponse<AiMessagePage>>(`${basePath}/${id}/messages`, {
+        params: { page: 1, limit: 100 },
+      })
+    ).data;
+    const pageCount = Math.ceil(first.total / first.limit);
+    if (pageCount <= 1) return first;
+    const rest = await Promise.all(
+      Array.from({ length: pageCount - 1 }, (_, index) =>
+        api
+          .get<AiApiResponse<AiMessagePage>>(`${basePath}/${id}/messages`, {
+            params: { page: index + 2, limit: first.limit },
+          })
+          .then((response) => response.data),
+      ),
+    );
+    return { ...first, items: [first, ...rest].flatMap((page) => page.items) };
+  },
+};
+
+export function conversationStreamUrl(id: number): string {
+  return `/api${basePath}/${id}/stream`;
+}

apps/admin/src/components/AiChat/bubble.integration.test.tsx

@@ -0,0 +1,475 @@
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { Bubble } from '@ant-design/x';
+import { afterEach, describe, expect, it } from 'vitest';
+import { aiBubbleRoles, conversationStatusMeta } from './AiChatDrawer';
+import { AiMessageContent } from './AiMessageContent';
+import { DynamicChart } from './DynamicChart';
+import { DynamicForm } from './DynamicForm';
+import { DynamicReview } from './DynamicReview';
+import type { AiChatMessage, AiChartSchema, AiReviewSchema } from './types';
+
+let container: HTMLDivElement | null = null;
+let root: ReturnType<typeof createRoot> | null = null;
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  container?.remove();
+  root = null;
+  container = null;
+});
+
+describe('AI chat bubble rendering', () => {
+  it('maps conversation run statuses to list labels', () => {
+    expect(conversationStatusMeta('running')).toEqual({ label: '生成中', color: 'processing' });
+    expect(conversationStatusMeta('done')).toEqual({ label: '已完成', color: 'success' });
+    expect(conversationStatusMeta('error')).toEqual({ label: '失败', color: 'error' });
+    expect(conversationStatusMeta('stopped')).toEqual({ label: '已停止', color: 'default' });
+  });
+
+  it('renders a structured user message instead of passing the object to React', async () => {
+    const message: AiChatMessage = {
+      role: 'user',
+      content: '查询今天的系统概览',
+      reasoningContent: '',
+      toolRuns: [],
+      attachments: [],
+    };
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(
+        <Bubble.List
+          role={aiBubbleRoles}
+          items={[
+            {
+              key: 'user-1',
+              role: 'user',
+              status: 'local',
+              content: message,
+              contentRender: (content: AiChatMessage) => <div>{content.content}</div>,
+            },
+          ]}
+        />,
+      );
+    });
+
+    expect(container.textContent).toContain('查询今天的系统概览');
+  });
+
+  it('renders an A2UI form and submits normalized values', async () => {
+    let submitted: Record<string, unknown> | null = null;
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(
+        <DynamicForm
+          form={{
+            id: 'form-1',
+            title: '新增学生',
+            submitLabel: '提交创建',
+            fields: [
+              { name: 'name', label: '姓名', type: 'input', required: true },
+              { name: 'studentNo', label: '学号', type: 'input' },
+            ],
+          }}
+          onSubmit={(values) => {
+            submitted = values;
+          }}
+        />,
+      );
+    });
+
+    expect(container.textContent).toContain('新增学生');
+    const input = container.querySelector('input#name') as HTMLInputElement | null;
+    expect(input).not.toBeNull();
+    if (input) {
+      const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set;
+      setter?.call(input, '张三');
+      input.dispatchEvent(new Event('input', { bubbles: true }));
+    }
+    const submitButton = container.querySelector('button[type="submit"]') as HTMLButtonElement | null;
+    expect(submitButton).not.toBeNull();
+    await act(async () => {
+      submitButton?.click();
+    });
+
+    expect(submitted).toEqual({ name: '张三' });
+    expect(container.textContent).toContain('已提交');
+  });
+
+  it('renders an A2UI review card and submits via the confirm button', async () => {
+    let submittedId: string | null = null;
+    const review: AiReviewSchema = {
+      id: 'review-1',
+      title: '开学导入',
+      summary: '来自报名 Excel',
+      status: 'pending',
+      sections: [
+        {
+          key: 'students',
+          type: 'students',
+          title: '学生',
+          kind: 'table',
+          columns: [
+            { key: 'name', title: '姓名' },
+            { key: 'phone', title: '手机号' },
+          ],
+          rows: [
+            { name: '张三', phone: '13800138000' },
+            { name: '李四', phone: '13900139000' },
+          ],
+          issues: [],
+        },
+      ],
+    };
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(
+        <DynamicReview
+          review={review}
+          onSubmit={(reviewId) => {
+            submittedId = reviewId;
+          }}
+        />,
+      );
+    });
+
+    expect(container.textContent).toContain('开学导入');
+    expect(container.textContent).toContain('确认导入本步');
+    expect(container.textContent).toContain('全部确认并入库');
+    const button = Array.from(container.querySelectorAll('button')).find((item) =>
+      item.textContent?.includes('全部确认并入库'),
+    ) as HTMLButtonElement | undefined;
+    expect(button).not.toBeNull();
+    await act(async () => {
+      button?.click();
+    });
+    const confirmButton = Array.from(document.body.querySelectorAll('button')).find(
+      (item) => item.textContent?.trim() === '确认导入',
+    ) as HTMLButtonElement | undefined;
+    expect(confirmButton).toBeDefined();
+    await act(async () => {
+      confirmButton?.click();
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    });
+    expect(submittedId).toBe('review-1');
+  });
+
+  it('renders grouped sheets and confirms one type group via Popconfirm', async () => {
+    let submittedGroup: { reviewId: string; type: string } | null = null;
+    const review: AiReviewSchema = {
+      id: 'review-2',
+      title: '入住分表',
+      status: 'pending',
+      sections: [
+        {
+          key: 'checkins_girls_4',
+          type: 'checkins',
+          title: '四人间女',
+          kind: 'table',
+          columns: [
+            { key: 'name', title: '姓名' },
+            { key: 'roomNumber', title: '宿舍号' },
+          ],
+          rows: [{ name: '张三', roomNumber: '4-401' }],
+          issues: [],
+        },
+        {
+          key: 'checkins_boys_4',
+          type: 'checkins',
+          title: '四人间男',
+          kind: 'table',
+          columns: [
+            { key: 'name', title: '姓名' },
+            { key: 'roomNumber', title: '宿舍号' },
+          ],
+          rows: [{ name: '李四', roomNumber: '4-402' }],
+          issues: [],
+        },
+      ],
+    };
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(
+        <DynamicReview
+          review={review}
+          onSubmit={() => undefined}
+          onConfirmGroup={(_, reviewId, type) => {
+            submittedGroup = { reviewId, type };
+          }}
+        />,
+      );
+    });
+
+    expect(container.textContent).toContain('入住记录 · 共 2 张表');
+    expect(container.textContent).toContain('确认本组 2 张表');
+    const groupButton = Array.from(container.querySelectorAll('button')).find((item) =>
+      item.textContent?.includes('确认本组 2 张表'),
+    ) as HTMLButtonElement | undefined;
+    expect(groupButton).not.toBeNull();
+    await act(async () => {
+      groupButton?.click();
+    });
+    const confirmButton = Array.from(document.body.querySelectorAll('button')).find(
+      (item) => item.textContent?.trim() === '确认导入',
+    ) as HTMLButtonElement | undefined;
+    expect(confirmButton).toBeDefined();
+    await act(async () => {
+      confirmButton?.click();
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    });
+    expect(submittedGroup).toEqual({ reviewId: 'review-2', type: 'checkins' });
+  });
+
+  it('renders legacy review sections missing type by inferring from key', async () => {
+    const review: AiReviewSchema = {
+      id: 'review-3',
+      title: '旧数据预览',
+      status: 'pending',
+      sections: [
+        {
+          key: 'checkins_legacy',
+          title: '旧入住表',
+          kind: 'table',
+          columns: [{ key: 'name', title: '姓名' }],
+          rows: [{ name: '张三' }],
+          issues: [],
+        },
+      ],
+    };
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    await act(async () => {
+      root?.render(<DynamicReview review={review} onSubmit={() => undefined} />);
+    });
+    expect(container.textContent).toContain('入住记录 · 共 1 张表');
+    expect(container.textContent).toContain('旧入住表');
+  });
+
+  it('renders an expired review card with table content but disabled actions', async () => {
+    let confirmed = false;
+    const review: AiReviewSchema = {
+      id: 'review-4',
+      title: '已被替代的预览',
+      status: 'expired',
+      sections: [
+        {
+          key: 'checkins_old',
+          type: 'checkins',
+          title: '旧入住表',
+          kind: 'table',
+          columns: [{ key: 'name', title: '姓名' }],
+          rows: [{ name: '张三' }],
+          issues: [],
+        },
+      ],
+    };
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    await act(async () => {
+      root?.render(
+        <DynamicReview
+          review={review}
+          onSubmit={() => {
+            confirmed = true;
+          }}
+          onConfirmStep={() => {
+            confirmed = true;
+          }}
+        />,
+      );
+    });
+    expect(container.textContent).toContain('已失效');
+    expect(container.textContent).toContain('已被新的预览替代');
+    expect(container.textContent).toContain('张三');
+    expect(container.textContent).not.toContain('全部确认并入库');
+    const disabledButton = Array.from(container.querySelectorAll('button')).find(
+      (item) => item.textContent?.trim() === '已失效',
+    ) as HTMLButtonElement | undefined;
+    expect(disabledButton).toBeDefined();
+    expect(disabledButton?.disabled).toBe(true);
+    await act(async () => {
+      disabledButton?.click();
+    });
+    expect(confirmed).toBe(false);
+  });
+
+  it('renders an A2UI chart card with title and chart container', async () => {
+    const chart: AiChartSchema = {
+      id: 'chart-1',
+      title: '各班级人数',
+      chartType: 'bar',
+      columns: [
+        { key: 'className', title: '班级' },
+        { key: 'count', title: '人数' },
+      ],
+      rows: [
+        { className: '一班', count: 20 },
+        { className: '二班', count: 15 },
+      ],
+    };
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(<DynamicChart chart={chart} />);
+    });
+
+    expect(container.textContent).toContain('各班级人数');
+    expect(container.textContent).toContain('柱状图');
+    expect(container.querySelector('.ai-chat-chart-card canvas')).not.toBeNull();
+    expect(container.querySelector('.ai-chat-chart-card__download')).not.toBeNull();
+  });
+
+  it('renders charts persisted on an assistant message', async () => {
+    const message: AiChatMessage = {
+      role: 'assistant',
+      content: '这是学生性别比例图',
+      reasoningContent: '',
+      toolRuns: [],
+      attachments: [],
+      charts: [
+        {
+          id: 'chart-9',
+          title: '学生性别比例',
+          chartType: 'pie',
+          columns: [
+            { key: 'gender', title: '性别' },
+            { key: 'count', title: '人数' },
+          ],
+          rows: [
+            { gender: '男', count: 2 },
+            { gender: '女', count: 0 },
+            { gender: '未填写', count: 61 },
+          ],
+        },
+      ],
+    };
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(<AiMessageContent message={message} />);
+    });
+
+    expect(container.textContent).toContain('学生性别比例');
+    expect(container.querySelector('.ai-chat-chart-card canvas')).not.toBeNull();
+  });
+
+  it('renders source references from assistant message metadata', async () => {
+    const message: AiChatMessage = {
+      role: 'assistant',
+      content: '这是基于你上传的名单整理的入住统计。',
+      reasoningContent: '',
+      toolRuns: [],
+      attachments: [],
+      metadata: {
+        a2uiSources: [
+          { title: '26暑期文化课宿舍.xlsx', url: '/api/ai/chat/attachments/7', description: 'excel' },
+        ],
+      },
+    };
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(<AiMessageContent message={message} />);
+    });
+
+    expect(container.textContent).toContain('引用来源');
+    expect(container.textContent).toContain('26暑期文化课宿舍.xlsx');
+  });
+
+  it('renders model retrying hint while waiting for the upstream retry', async () => {
+    const message: AiChatMessage = {
+      role: 'assistant',
+      content: '',
+      reasoningContent: '',
+      toolRuns: [],
+      attachments: [],
+      retrying: { attempt: 2, maxRetries: 3, reason: '上游返回 503' },
+    };
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(<AiMessageContent message={message} />);
+    });
+
+    expect(container.textContent).toContain('正在自动重试（第 2 / 3 次）');
+    expect(container.textContent).toContain('上游返回 503');
+  });
+
+  it.each([
+    ['area', '面积图', [{ key: 'month', title: '月份' }, { key: 'amount', title: '金额' }], [
+      { month: '1月', amount: 100 },
+      { month: '2月', amount: 150 },
+    ]],
+    ['scatter', '散点图', [
+      { key: 'room', title: '宿舍' },
+      { key: 'capacity', title: '容量' },
+      { key: 'occupied', title: '入住人数' },
+    ], [
+      { room: '1-101', capacity: 4, occupied: 3 },
+      { room: '1-102', capacity: 6, occupied: 5 },
+    ]],
+    ['radar', '雷达图', [
+      { key: 'className', title: '班级' },
+      { key: 'attendance', title: '考勤' },
+      { key: 'score', title: '成绩' },
+    ], [
+      { className: '一班', attendance: 90, score: 85 },
+      { className: '二班', attendance: 80, score: 92 },
+    ]],
+    ['gauge', '仪表盘', [
+      { key: 'metric', title: '指标' },
+      { key: 'value', title: '数值' },
+      { key: 'max', title: '最大值' },
+    ], [
+      { metric: '入住率', value: 82, max: 100 },
+    ]],
+    ['funnel', '漏斗图', [
+      { key: 'stage', title: '阶段' },
+      { key: 'count', title: '人数' },
+    ], [
+      { stage: '咨询', count: 100 },
+      { stage: '报名', count: 60 },
+    ]],
+  ])('渲染 %s 图表卡片', async (chartType, label, columns, rows) => {
+    const chart: AiChartSchema = {
+      id: `chart-${chartType}`,
+      title: `${label}示例`,
+      chartType: chartType as AiChartSchema['chartType'],
+      columns,
+      rows,
+    };
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    await act(async () => {
+      root?.render(<DynamicChart chart={chart} />);
+    });
+
+    expect(container.textContent).toContain(`${label}示例`);
+    expect(container.textContent).toContain(label);
+    expect(container.querySelector('.ai-chat-chart-card canvas')).not.toBeNull();
+  });
+});

apps/admin/src/components/AiChat/message-mappers.integration.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest';
+import { mapHistoryMessage } from './message-mappers';
+
+describe('AI chat history mapper', () => {
+  it('restores reasoning, tool summaries and completed status', () => {
+    const mapped = mapHistoryMessage({
+      id: 3,
+      role: 'assistant',
+      content: '回答',
+      reasoningContent: '思考',
+      status: 'completed',
+      errorCode: null,
+      createdAt: '2026-07-23T00:00:00.000Z',
+      attachments: [
+        {
+          id: 8,
+          name: '考勤.pdf',
+          mimeType: 'application/pdf',
+          size: 100,
+          status: 'ready',
+          url: '/api/ai/chat/attachments/8',
+          createdAt: '2026-07-24T00:00:00.000Z',
+        },
+      ],
+      toolRuns: [
+        {
+          toolCallId: 'tool-1',
+          toolName: 'search_rooms',
+          status: 'success',
+          resultSummary: '共 4 间',
+        },
+      ],
+    });
+
+    expect(mapped.status).toBe('success');
+    expect(mapped.message.reasoningContent).toBe('思考');
+    expect(mapped.message.toolRuns[0].summary).toBe('共 4 间');
+    expect(mapped.message.attachments).toHaveLength(1);
+  });
+
+  it('maps failed and cancelled history to X SDK statuses', () => {
+    const base = {
+      id: 4,
+      role: 'assistant' as const,
+      content: '',
+      reasoningContent: null,
+      errorCode: 'UPSTREAM_ERROR',
+      createdAt: '2026-07-23T00:00:00.000Z',
+    };
+    expect(mapHistoryMessage({ ...base, status: 'failed' }).status).toBe('error');
+    expect(mapHistoryMessage({ ...base, status: 'cancelled' }).status).toBe('abort');
+  });
+
+  it('restores a persisted A2UI form from message metadata', () => {
+    const mapped = mapHistoryMessage({
+      id: 5,
+      role: 'assistant',
+      content: '请填写表单',
+      reasoningContent: null,
+      status: 'completed',
+      errorCode: null,
+      createdAt: '2026-07-23T00:00:00.000Z',
+      metadata: {
+        a2uiForm: {
+          id: 'form-9',
+          title: '新增学生',
+          submitLabel: '提交创建',
+          status: 'pending',
+          fields: [
+            { name: 'name', label: '姓名', type: 'input', required: true },
+            { name: 'gender', label: '性别', type: 'select', options: [{ label: '男', value: 'male' }] },
+          ],
+        },
+      },
+    });
+
+    expect(mapped.message.forms).toHaveLength(1);
+    expect(mapped.message.forms?.[0]).toMatchObject({ id: 'form-9', title: '新增学生' });
+  });
+
+  it('restores a persisted A2UI review from message metadata', () => {
+    const mapped = mapHistoryMessage({
+      id: 6,
+      role: 'assistant',
+      content: '请审阅导入预览',
+      reasoningContent: null,
+      status: 'completed',
+      errorCode: null,
+      createdAt: '2026-07-23T00:00:00.000Z',
+      metadata: {
+        a2uiReview: {
+          id: 'review-9',
+          title: '批量导入',
+          status: 'pending',
+          sections: [
+            {
+              key: 'transfers',
+              type: 'transfers',
+              title: '换宿',
+              kind: 'table',
+              columns: [{ key: 'newRoom', title: '目标宿舍' }],
+              rows: [{ newRoom: '3-301' }],
+              issues: [],
+            },
+          ],
+        },
+      },
+    });
+
+    expect(mapped.message.reviews).toHaveLength(1);
+    expect(mapped.message.reviews?.[0]).toMatchObject({ id: 'review-9', title: '批量导入' });
+  });
+
+  it('restores persisted A2UI charts from message metadata', () => {
+    const mapped = mapHistoryMessage({
+      id: 7,
+      role: 'assistant',
+      content: '这是图表',
+      reasoningContent: null,
+      status: 'completed',
+      errorCode: null,
+      createdAt: '2026-07-23T00:00:00.000Z',
+      metadata: {
+        a2uiChart: [
+          {
+            id: 'chart-9',
+            title: '各班级人数',
+            chartType: 'bar',
+            columns: [
+              { key: 'className', title: '班级' },
+              { key: 'count', title: '人数' },
+            ],
+            rows: [{ className: '一班', count: 20 }],
+          },
+        ],
+      },
+    });
+
+    expect(mapped.message.charts).toHaveLength(1);
+    expect(mapped.message.charts?.[0]).toMatchObject({ id: 'chart-9', chartType: 'bar' });
+  });
+});

apps/admin/src/components/AiChat/message-mappers.ts

@@ -0,0 +1,73 @@
+import type { MessageInfo } from '@ant-design/x-sdk';
+import type {
+  AiChatMessage,
+  AiChatMessageStatus,
+  AiChartSchema,
+  AiFormSchema,
+  AiMessageRecord,
+  AiReviewSchema,
+  AiToolRun,
+} from './types';
+
+function mapStatus(record: AiMessageRecord): AiChatMessageStatus {
+  if (record.status === 'pending') return 'loading';
+  if (record.status === 'failed') return 'error';
+  if (record.status === 'cancelled') return 'abort';
+  return record.role === 'user' ? 'local' : 'success';
+}
+
+function normalizeToolRun(tool: AiToolRun): AiToolRun {
+  return {
+    ...tool,
+    status: tool.status === 'error' ? 'failed' : tool.status,
+    summary: tool.resultSummary ?? tool.argumentsSummary ?? tool.summary,
+  };
+}
+
+function historyForms(record: AiMessageRecord): AiFormSchema[] | undefined {
+  const a2uiForm = record.metadata?.a2uiForm;
+  if (!a2uiForm || typeof a2uiForm !== 'object' || Array.isArray(a2uiForm)) return undefined;
+  return [a2uiForm as AiFormSchema];
+}
+
+function historyReviews(record: AiMessageRecord): AiReviewSchema[] | undefined {
+  const a2uiReview = record.metadata?.a2uiReview;
+  if (!a2uiReview || typeof a2uiReview !== 'object' || Array.isArray(a2uiReview)) {
+    return undefined;
+  }
+  return [a2uiReview as AiReviewSchema];
+}
+
+function historyCharts(record: AiMessageRecord): AiChartSchema[] | undefined {
+  const a2uiChart = record.metadata?.a2uiChart;
+  if (Array.isArray(a2uiChart)) {
+    return a2uiChart.filter(
+      (item): item is AiChartSchema =>
+        Boolean(item) && typeof item === 'object' && typeof (item as AiChartSchema).id === 'string',
+    );
+  }
+  if (!a2uiChart || typeof a2uiChart !== 'object') return undefined;
+  return [a2uiChart as AiChartSchema];
+}
+
+export function mapHistoryMessage(record: AiMessageRecord): MessageInfo<AiChatMessage> {
+  return {
+    id: record.id,
+    status: mapStatus(record),
+    message: {
+      id: record.id,
+      role: record.role,
+      content: record.content || '',
+      reasoningContent: record.reasoningContent || '',
+      toolRuns: (record.toolRuns || []).map(normalizeToolRun),
+      attachments: record.attachments ?? [],
+      forms: historyForms(record),
+      reviews: historyReviews(record),
+      charts: historyCharts(record),
+      replyToMessageId: record.replyToMessageId,
+      metadata: record.metadata,
+      error: record.status === 'failed' ? record.errorCode || 'AI 回答生成失败' : undefined,
+      cancelled: record.status === 'cancelled',
+    },
+  };
+}

apps/admin/src/components/AiChat/provider.integration.test.ts

@@ -0,0 +1,488 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  authenticatedFetch,
+  GongxueAiChatProvider,
+  parseSsePayload,
+  reduceAiSseMessage,
+} from './provider';
+
+describe('AI chat SSE message reducer', () => {
+  it('separates reasoning and answer deltas', () => {
+    let message = reduceAiSseMessage(undefined, {
+      event: 'reasoning.delta',
+      data: JSON.stringify({ messageId: 8, delta: '分析' }),
+    });
+    message = reduceAiSseMessage(message, {
+      event: 'content.delta',
+      data: JSON.stringify({ delta: '**答案**' }),
+    });
+
+    expect(message.reasoningContent).toBe('分析');
+    expect(message.content).toBe('**答案**');
+  });
+
+  it('tracks tool lifecycle without exposing raw payloads', () => {
+    let message = reduceAiSseMessage(undefined, {
+      event: 'tool.started',
+      data: JSON.stringify({
+        toolCallId: 'call-1',
+        toolName: 'search_students',
+        summary: '姓名条件',
+      }),
+    });
+    message = reduceAiSseMessage(message, {
+      event: 'tool.completed',
+      data: JSON.stringify({
+        toolCallId: 'call-1',
+        toolName: 'search_students',
+        status: 'success',
+        summary: '找到 1 条记录',
+      }),
+    });
+
+    expect(message.toolRuns).toHaveLength(1);
+    expect(message.toolRuns[0]).toMatchObject({ status: 'success', summary: '找到 1 条记录' });
+  });
+
+  it('tracks processed attachments and final message state', () => {
+    let message = reduceAiSseMessage(undefined, {
+      event: 'attachment.processed',
+      data: JSON.stringify({
+        attachment: {
+          id: 4,
+          name: '名单.xlsx',
+          mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+          size: 1200,
+          status: 'ready',
+          url: '/api/ai/chat/attachments/4',
+          createdAt: '2026-07-24T00:00:00.000Z',
+        },
+      }),
+    });
+    message = reduceAiSseMessage(message, {
+      event: 'message.completed',
+      data: JSON.stringify({
+        message: {
+          id: 12,
+          content: '完成',
+          reasoningContent: null,
+          attachments: message.attachments,
+        },
+      }),
+    });
+    expect(message.attachments).toHaveLength(1);
+  });
+
+  it('uses final content and records cancellation and errors', () => {
+    let message = reduceAiSseMessage(undefined, {
+      event: 'message.completed',
+      data: JSON.stringify({
+        message: {
+          id: 12,
+          content: '最终回答',
+          reasoningContent: '完成',
+          status: 'completed',
+          toolRuns: [
+            {
+              toolCallId: 'nested-tool',
+              toolName: 'search_rooms',
+              status: 'success',
+              resultSummary: '共 4 间',
+            },
+          ],
+        },
+      }),
+    });
+    message = reduceAiSseMessage(message, {
+      event: 'error',
+      data: JSON.stringify({ message: '上游服务不可用' }),
+    });
+    message = reduceAiSseMessage(message, {
+      event: 'message.cancelled',
+      data: JSON.stringify({ messageId: 12 }),
+    });
+
+    expect(message).toMatchObject({
+      id: 12,
+      content: '最终回答',
+      reasoningContent: '完成',
+      error: '上游服务不可用',
+      cancelled: true,
+    });
+    expect(message.toolRuns[0]).toMatchObject({ toolCallId: 'nested-tool', status: 'success' });
+  });
+
+  it('reads nested assistant message from message.created', () => {
+    const message = reduceAiSseMessage(undefined, {
+      event: 'message.created',
+      data: JSON.stringify({
+        message: { id: 9, content: '', reasoningContent: null, status: 'pending' },
+      }),
+    });
+
+    expect(message.id).toBe(9);
+  });
+
+  it('merges ui.form events into the assistant message by id', () => {
+    const form = {
+      id: 'form-1',
+      title: '新增学生',
+      submitLabel: '提交创建',
+      fields: [
+        { name: 'name', label: '姓名', type: 'input', required: true },
+        { name: 'gender', label: '性别', type: 'select', options: [{ label: '男', value: 'male' }] },
+      ],
+    };
+    let message = reduceAiSseMessage(undefined, {
+      event: 'ui.form',
+      data: JSON.stringify({ messageId: 8, form }),
+    });
+    message = reduceAiSseMessage(message, {
+      event: 'ui.form',
+      data: JSON.stringify({ messageId: 8, form: { ...form, id: 'form-1' } }),
+    });
+    message = reduceAiSseMessage(message, {
+      event: 'ui.form',
+      data: JSON.stringify({
+        messageId: 8,
+        form: { id: 'form-2', title: '入住确认', fields: [] },
+      }),
+    });
+
+    expect(message.forms).toHaveLength(2);
+    expect(message.forms?.[0]).toMatchObject({ id: 'form-1', title: '新增学生' });
+    expect(message.forms?.[1]).toMatchObject({ id: 'form-2' });
+  });
+
+  it('restores a persisted form from message.completed metadata', () => {
+    const message = reduceAiSseMessage(undefined, {
+      event: 'message.completed',
+      data: JSON.stringify({
+        message: {
+          id: 12,
+          content: '请填写表单',
+          status: 'completed',
+          metadata: {
+            a2uiForm: {
+              id: 'form-9',
+              title: '新增学生',
+              fields: [{ name: 'name', label: '姓名', type: 'input', required: true }],
+            },
+          },
+        },
+      }),
+    });
+
+    expect(message.forms).toHaveLength(1);
+    expect(message.forms?.[0].id).toBe('form-9');
+  });
+
+  it('merges ui.review events into the assistant message and updates by id', () => {
+    const review = {
+      id: 'review-1',
+      title: '开学导入',
+      summary: '来自报名 Excel',
+      status: 'pending',
+      sections: [
+        {
+          key: 'students',
+          type: 'students',
+          title: '学生',
+          kind: 'table',
+          columns: [
+            { key: 'name', title: '姓名' },
+            { key: 'phone', title: '手机号' },
+          ],
+          rows: [{ name: '张三', phone: '13800138000' }],
+          issues: [],
+        },
+      ],
+    };
+    let message = reduceAiSseMessage(undefined, {
+      event: 'ui.review',
+      data: JSON.stringify({ messageId: 8, review }),
+    });
+    message = reduceAiSseMessage(message, {
+      event: 'ui.review',
+      data: JSON.stringify({
+        messageId: 8,
+        review: { ...review, status: 'submitted', resultSummary: '{"students":{"created":1}}' },
+      }),
+    });
+
+    expect(message.reviews).toHaveLength(1);
+    expect(message.reviews?.[0]).toMatchObject({ id: 'review-1', status: 'submitted' });
+  });
+
+  it('shows model retrying state and clears it when content starts', () => {
+    let message = reduceAiSseMessage(undefined, {
+      event: 'model.retrying',
+      data: JSON.stringify({
+        messageId: 8,
+        retry: { attempt: 1, maxRetries: 3, delayMs: 500, reason: '上游返回 503' },
+      }),
+    });
+    expect(message.retrying).toMatchObject({ attempt: 1, maxRetries: 3 });
+    message = reduceAiSseMessage(message, {
+      event: 'content.delta',
+      data: JSON.stringify({ messageId: 8, delta: '你好' }),
+    });
+    expect(message.retrying).toBeNull();
+    expect(message.content).toContain('你好');
+  });
+
+  it('restores a persisted review from message.completed metadata', () => {
+    const message = reduceAiSseMessage(undefined, {
+      event: 'message.completed',
+      data: JSON.stringify({
+        message: {
+          id: 12,
+          content: '请审阅',
+          status: 'completed',
+          metadata: {
+            a2uiReview: {
+              id: 'review-9',
+              title: '批量导入',
+              status: 'pending',
+              sections: [
+                {
+                  key: 'rooms',
+                  type: 'rooms',
+                  title: '宿舍',
+                  kind: 'table',
+                  columns: [{ key: 'roomNumber', title: '房间号' }],
+                  rows: [{ roomNumber: '3-301' }],
+                  issues: [],
+                },
+              ],
+            },
+          },
+        },
+      }),
+    });
+
+    expect(message.reviews).toHaveLength(1);
+    expect(message.reviews?.[0]).toMatchObject({ id: 'review-9', title: '批量导入' });
+  });
+
+  it('merges ui.chart events into the assistant message by id', () => {
+    const chart = {
+      id: 'chart-1',
+      title: '各班级人数',
+      chartType: 'bar',
+      columns: [
+        { key: 'className', title: '班级' },
+        { key: 'count', title: '人数' },
+      ],
+      rows: [
+        { className: '一班', count: 20 },
+        { className: '二班', count: 15 },
+      ],
+    };
+    let message = reduceAiSseMessage(undefined, {
+      event: 'ui.chart',
+      data: JSON.stringify({ messageId: 8, chart }),
+    });
+    message = reduceAiSseMessage(message, {
+      event: 'ui.chart',
+      data: JSON.stringify({
+        messageId: 8,
+        chart: { ...chart, id: 'chart-2', title: '女生人数' },
+      }),
+    });
+
+    expect(message.charts).toHaveLength(2);
+    expect(message.charts?.[0]).toMatchObject({ id: 'chart-1', chartType: 'bar' });
+    expect(message.charts?.[1]).toMatchObject({ id: 'chart-2' });
+  });
+
+  it('restores persisted charts from message.completed metadata', () => {
+    const message = reduceAiSseMessage(undefined, {
+      event: 'message.completed',
+      data: JSON.stringify({
+        message: {
+          id: 12,
+          content: '这是图表',
+          status: 'completed',
+          metadata: {
+            a2uiChart: [
+              {
+                id: 'chart-9',
+                title: '男女比例',
+                chartType: 'pie',
+                columns: [
+                  { key: 'name', title: '性别' },
+                  { key: 'value', title: '人数' },
+                ],
+                rows: [
+                  { name: '男', value: 20 },
+                  { name: '女', value: 15 },
+                ],
+              },
+            ],
+          },
+        },
+      }),
+    });
+
+    expect(message.charts).toHaveLength(1);
+    expect(message.charts?.[0]).toMatchObject({ id: 'chart-9', chartType: 'pie' });
+  });
+
+  it('rewrites review submissions to the review submit stream endpoint', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+    try {
+      await authenticatedFetch('http://x/api/ai/chat/conversations/3/stream', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          message: '确认批量导入',
+          attachmentIds: [],
+          skillKey: null,
+          clientRequestId: '6a8bc680-3cb5-4f2d-85ee-974974e0f194',
+          reasoningEffort: 'high',
+          reviewSubmission: { reviewId: 'review-1', reviewTitle: '开学导入' },
+        }),
+      });
+      expect(String(fetchMock.mock.calls[0][0])).toBe(
+        'http://x/api/ai/chat/reviews/review-1/submit/stream',
+      );
+      const body = JSON.parse(
+        (fetchMock.mock.calls[0][1] as RequestInit).body as string,
+      ) as Record<string, unknown>;
+      expect(body).toEqual({
+        clientRequestId: '6a8bc680-3cb5-4f2d-85ee-974974e0f194',
+        reasoningEffort: 'high',
+      });
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it('keeps reasoningEffort when rewriting regenerate requests', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+    try {
+      await authenticatedFetch('http://x/api/ai/chat/conversations/3/stream', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          message: '',
+          attachmentIds: [],
+          skillKey: null,
+          clientRequestId: '6a8bc680-3cb5-4f2d-85ee-974974e0f194',
+          reasoningEffort: 'high',
+          regenerateMessageId: 99,
+        }),
+      });
+      expect(String(fetchMock.mock.calls[0][0])).toBe(
+        'http://x/api/ai/chat/conversations/3/messages/99/regenerate/stream',
+      );
+      const body = JSON.parse(
+        (fetchMock.mock.calls[0][1] as RequestInit).body as string,
+      ) as Record<string, unknown>;
+      expect(body).toEqual({
+        clientRequestId: '6a8bc680-3cb5-4f2d-85ee-974974e0f194',
+        reasoningEffort: 'high',
+      });
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it('keeps reasoningEffort when rewriting form submissions', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+    try {
+      await authenticatedFetch('http://x/api/ai/chat/conversations/3/stream', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          message: '',
+          attachmentIds: [],
+          skillKey: null,
+          clientRequestId: '6a8bc680-3cb5-4f2d-85ee-974974e0f194',
+          reasoningEffort: 'high',
+          formSubmission: { formId: 'form-1', values: { name: '张三' } },
+        }),
+      });
+      expect(String(fetchMock.mock.calls[0][0])).toBe(
+        'http://x/api/ai/chat/forms/form-1/submit/stream',
+      );
+      const body = JSON.parse(
+        (fetchMock.mock.calls[0][1] as RequestInit).body as string,
+      ) as Record<string, unknown>;
+      expect(body).toEqual({
+        clientRequestId: '6a8bc680-3cb5-4f2d-85ee-974974e0f194',
+        values: { name: '张三' },
+        reasoningEffort: 'high',
+      });
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it('routes submit-time ui.review to the original message instead of the streaming one', () => {
+    const provider = new GongxueAiChatProvider('http://x/api/ai/chat/conversations/3/stream');
+    const onExternalReview = vi.fn();
+    provider.onExternalReview = onExternalReview;
+    const review = {
+      id: 'review-1',
+      title: '批量导入',
+      status: 'submitted',
+      sections: [],
+    };
+    const origin = {
+      id: 13,
+      role: 'assistant' as const,
+      content: '生成中',
+      reasoningContent: '',
+      toolRuns: [],
+      attachments: [],
+      reviews: [],
+    };
+    const next = provider.transformMessage({
+      originMessage: origin,
+      chunk: { event: 'ui.review', data: JSON.stringify({ messageId: 12, review }) },
+      status: 'updating',
+      chunks: [],
+      responseHeaders: {} as Headers,
+    });
+
+    expect(onExternalReview).toHaveBeenCalledWith(12, review);
+    expect(next).toBe(origin);
+    expect(next.reviews ?? []).toHaveLength(0);
+  });
+
+  it('routes ui.review without an origin message to the external handler', () => {
+    const provider = new GongxueAiChatProvider('http://x/api/ai/chat/conversations/3/stream');
+    const onExternalReview = vi.fn();
+    provider.onExternalReview = onExternalReview;
+    const next = provider.transformMessage({
+      chunk: {
+        event: 'ui.review',
+        data: JSON.stringify({
+          messageId: 12,
+          review: { id: 'review-1', title: '批量导入', status: 'submitted', sections: [] },
+        }),
+      },
+      status: 'updating',
+      chunks: [],
+      responseHeaders: {} as Headers,
+    });
+
+    expect(onExternalReview).toHaveBeenCalledWith(
+      12,
+      expect.objectContaining({ id: 'review-1' }),
+    );
+    expect(next.reviews ?? []).toHaveLength(0);
+  });
+
+  it('tolerates non-JSON event data', () => {
+    expect(parseSsePayload({ event: 'content.delta', data: 'plain text' })).toEqual({
+      event: 'content.delta',
+      payload: { delta: 'plain text' },
+    });
+  });
+});

apps/admin/src/components/AiChat/provider.ts

@@ -0,0 +1,416 @@
+import {
+  AbstractChatProvider,
+  XRequest,
+  type TransformMessage,
+  type XRequestOptions,
+} from '@ant-design/x-sdk';
+import { usePermissionStore } from '../../store/permission/permissionStore';
+import { useUserStore } from '../../store/user/userStore';
+import type {
+  AiAttachment,
+  AiChatInput,
+  AiChatMessage,
+  AiChartSchema,
+  AiFormSchema,
+  AiModelRetryInfo,
+  AiReviewSchema,
+  AiSseChunk,
+  AiToolRun,
+} from './types';
+
+interface AiSsePayload {
+  messageId?: number;
+  userMessageId?: number;
+  assistantMessageId?: number;
+  delta?: string;
+  content?: string;
+  reasoningContent?: string | null;
+  toolCallId?: string;
+  toolName?: string;
+  skillKey?: string | null;
+  status?: string;
+  summary?: string | null;
+  durationMs?: number | null;
+  attachment?: AiAttachment;
+  form?: AiFormSchema;
+  review?: AiReviewSchema;
+  chart?: AiChartSchema;
+  wizard?: unknown;
+  retry?: AiModelRetryInfo;
+  message?:
+    | string
+    | {
+        id?: number;
+        content?: string;
+        reasoningContent?: string | null;
+        status?: string;
+        toolRuns?: AiToolRun[];
+        attachments?: AiAttachment[];
+        replyToMessageId?: number | null;
+        metadata?: Record<string, unknown> | null;
+      };
+  error?: string;
+}
+
+function emptyAssistant(): AiChatMessage {
+  return {
+    role: 'assistant',
+    content: '',
+    reasoningContent: '',
+    toolRuns: [],
+    attachments: [],
+    forms: [],
+  };
+}
+
+function mergeForms(
+  current: AiFormSchema[] | undefined,
+  incoming: AiFormSchema | AiFormSchema[] | undefined,
+): AiFormSchema[] {
+  const items = Array.isArray(incoming) ? incoming : incoming ? [incoming] : [];
+  if (!items.length) return current ?? [];
+  const next = [...(current ?? [])];
+  for (const item of items) {
+    if (item && typeof item === 'object' && !next.some((existing) => existing.id === item.id)) {
+      next.push(item);
+    }
+  }
+  return next;
+}
+
+function mergeById<T extends { id: string }>(
+  current: T[] | undefined,
+  incoming: T | T[] | undefined,
+): T[] {
+  const items = Array.isArray(incoming) ? incoming : incoming ? [incoming] : [];
+  if (!items.length) return current ?? [];
+  const next = [...(current ?? [])];
+  for (const item of items) {
+    if (!item || typeof item !== 'object') continue;
+    const index = next.findIndex((existing) => existing.id === item.id);
+    if (index === -1) {
+      next.push(item);
+    } else {
+      next[index] = item;
+    }
+  }
+  return next;
+}
+
+export function parseSsePayload(chunk?: AiSseChunk): {
+  event: string;
+  payload: AiSsePayload;
+} {
+  if (!chunk) return { event: '', payload: {} };
+  const event = chunk.event?.trim() || 'message';
+  if (!chunk.data || chunk.data === '[DONE]') return { event, payload: {} };
+  try {
+    const parsed: unknown = JSON.parse(chunk.data);
+    return {
+      event,
+      payload: parsed && typeof parsed === 'object' ? (parsed as AiSsePayload) : {},
+    };
+  } catch {
+    return { event, payload: { delta: chunk.data } };
+  }
+}
+
+function upsertToolRun(
+  toolRuns: AiToolRun[],
+  payload: AiSsePayload,
+  fallbackStatus: AiToolRun['status'],
+): AiToolRun[] {
+  const toolCallId = payload.toolCallId || `${payload.toolName || 'tool'}-${toolRuns.length}`;
+  const next: AiToolRun = {
+    toolCallId,
+    toolName: payload.toolName || '查询工具',
+    skillKey: payload.skillKey,
+    status: (payload.status as AiToolRun['status']) || fallbackStatus,
+    summary: payload.summary,
+    resultSummary: fallbackStatus === 'running' ? undefined : payload.summary,
+    argumentsSummary: fallbackStatus === 'running' ? payload.summary : undefined,
+    durationMs: payload.durationMs,
+  };
+  const index = toolRuns.findIndex((item) => item.toolCallId === toolCallId);
+  if (index === -1) return [...toolRuns, next];
+  return toolRuns.map((item, itemIndex) => (itemIndex === index ? { ...item, ...next } : item));
+}
+
+function normalizeToolRuns(toolRuns: AiToolRun[] | undefined, fallback: AiToolRun[]): AiToolRun[] {
+  if (!toolRuns) return fallback;
+  return toolRuns.map((tool) => ({
+    ...tool,
+    status: tool.status === 'error' ? 'failed' : tool.status,
+    summary: tool.resultSummary ?? tool.argumentsSummary ?? tool.summary,
+  }));
+}
+
+function applyMessagePayload(
+  message: AiChatMessage,
+  nested: AiSsePayload['message'],
+  payload: AiSsePayload,
+): void {
+  if (typeof nested !== 'object' || nested === null) return;
+  message.forms = mergeForms(
+    message.forms,
+    (nested.metadata?.a2uiForm as AiFormSchema | undefined) ?? payload.form,
+  );
+  message.reviews = mergeById<AiReviewSchema>(
+    message.reviews,
+    (nested.metadata?.a2uiReview as AiReviewSchema | undefined) ?? payload.review,
+  );
+  message.charts = mergeById<AiChartSchema>(
+    message.charts,
+    (nested.metadata?.a2uiChart as AiChartSchema | AiChartSchema[] | undefined) ?? payload.chart,
+  );
+  message.replyToMessageId = nested.replyToMessageId ?? message.replyToMessageId;
+  message.metadata = nested.metadata ?? message.metadata;
+}
+
+export function reduceAiSseMessage(
+  originMessage: AiChatMessage | undefined,
+  chunk?: AiSseChunk,
+): AiChatMessage {
+  const message = originMessage ? { ...originMessage } : emptyAssistant();
+  const { event, payload } = parseSsePayload(chunk);
+
+  if (event === 'message.created') {
+    const nested = typeof payload.message === 'object' ? payload.message : undefined;
+    message.id = nested?.id ?? payload.assistantMessageId ?? payload.messageId ?? message.id;
+    message.content = nested?.content ?? message.content;
+    message.reasoningContent = nested?.reasoningContent ?? message.reasoningContent;
+    message.toolRuns = normalizeToolRuns(nested?.toolRuns, message.toolRuns);
+    message.attachments = nested?.attachments ?? message.attachments;
+    applyMessagePayload(message, nested, payload);
+  } else if (event === 'reasoning.delta') {
+    message.retrying = null;
+    message.reasoningContent += payload.delta ?? payload.reasoningContent ?? '';
+  } else if (event === 'content.delta') {
+    message.retrying = null;
+    message.content += payload.delta ?? payload.content ?? '';
+  } else if (event === 'model.retrying' && payload.retry) {
+    message.retrying = payload.retry;
+  } else if (event === 'ui.form' && payload.form) {
+    message.forms = mergeForms(message.forms, payload.form);
+  } else if (event === 'ui.review' && payload.review) {
+    message.reviews = mergeById<AiReviewSchema>(message.reviews, payload.review);
+  } else if (event === 'ui.chart' && payload.chart) {
+    message.charts = mergeById<AiChartSchema>(message.charts, payload.chart);
+  } else if (event === 'ui.import_wizard' && payload.wizard) {
+    message.metadata = { ...message.metadata, a2uiImportWizard: payload.wizard };
+  } else if (event === 'tool.started') {
+    message.toolRuns = upsertToolRun(message.toolRuns, payload, 'running');
+  } else if (event === 'tool.completed') {
+    message.toolRuns = upsertToolRun(message.toolRuns, payload, 'success');
+  } else if (event === 'tool.failed') {
+    message.toolRuns = upsertToolRun(message.toolRuns, payload, 'failed');
+  } else if (event === 'attachment.processed' && payload.attachment) {
+    if (!message.attachments.some((item) => item.id === payload.attachment?.id)) {
+      message.attachments = [...message.attachments, payload.attachment];
+    }
+  } else if (event === 'message.completed') {
+    const nested = typeof payload.message === 'object' ? payload.message : undefined;
+    message.id = nested?.id ?? payload.messageId ?? message.id;
+    message.content = nested?.content ?? payload.content ?? message.content;
+    message.reasoningContent =
+      nested?.reasoningContent ?? payload.reasoningContent ?? message.reasoningContent;
+    message.toolRuns = normalizeToolRuns(nested?.toolRuns, message.toolRuns);
+    message.attachments = nested?.attachments ?? message.attachments;
+    applyMessagePayload(message, nested, payload);
+    message.retrying = null;
+  } else if (event === 'message.cancelled') {
+    message.id = payload.messageId ?? message.id;
+    message.cancelled = true;
+    message.retrying = null;
+  } else if (event === 'error') {
+    message.retrying = null;
+    message.error =
+      (typeof payload.message === 'string' ? payload.message : undefined) ||
+      payload.error ||
+      'AI 回答生成失败';
+  }
+  return message;
+}
+
+export async function authenticatedFetch(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<Response> {
+  const headers = new Headers(init?.headers);
+  const token = useUserStore.getState().token;
+  if (token) headers.set('Authorization', `Bearer ${token}`);
+  headers.set('Accept', 'text/event-stream');
+  let requestInput = input;
+  let requestInit = init;
+  if (typeof init?.body === 'string') {
+    try {
+      const body = JSON.parse(init.body) as AiChatInput;
+      if (body.regenerateMessageId) {
+        requestInput = `${String(input).replace(/\/stream$/, '')}/messages/${body.regenerateMessageId}/regenerate/stream`;
+        requestInit = {
+          ...init,
+          body: JSON.stringify({
+            clientRequestId: body.clientRequestId,
+            reasoningEffort: body.reasoningEffort,
+          }),
+        };
+      } else if (body.editMessageId) {
+        requestInput = `${String(input).replace(/\/stream$/, '')}/messages/${body.editMessageId}/edit/stream`;
+        requestInit = {
+          ...init,
+          body: JSON.stringify({
+            content: body.message,
+            clientRequestId: body.clientRequestId,
+            reasoningEffort: body.reasoningEffort,
+          }),
+        };
+      } else if (body.formSubmission) {
+        requestInput = `${String(input).replace(/\/conversations\/\d+\/stream$/, '')}/forms/${body.formSubmission.formId}/submit/stream`;
+        requestInit = {
+          ...init,
+          body: JSON.stringify({
+            clientRequestId: body.clientRequestId,
+            values: body.formSubmission.values,
+            reasoningEffort: body.reasoningEffort,
+          }),
+        };
+      } else if (body.reviewSubmission) {
+        requestInput = `${String(input).replace(/\/conversations\/\d+\/stream$/, '')}/reviews/${body.reviewSubmission.reviewId}/submit/stream`;
+        requestInit = {
+          ...init,
+          body: JSON.stringify({
+            clientRequestId: body.clientRequestId,
+            reasoningEffort: body.reasoningEffort,
+          }),
+        };
+      } else {
+        const {
+          localAttachments: _localAttachments,
+          reloadMessage: _reloadMessage,
+          regenerateMessageId: _regenerateMessageId,
+          editMessageId: _editMessageId,
+          formSubmission: _formSubmission,
+          reviewSubmission: _reviewSubmission,
+          ...payload
+        } = body;
+        requestInit = { ...init, body: JSON.stringify(payload) };
+      }
+    } catch {
+      requestInit = init;
+    }
+  }
+  const response = await fetch(requestInput, { ...requestInit, headers });
+  if (response.status === 401) {
+    useUserStore.getState().logout();
+    usePermissionStore.getState().clearPermissions();
+    window.location.href = '/login';
+  }
+  return response;
+}
+
+export class GongxueAiChatProvider extends AbstractChatProvider<
+  AiChatMessage,
+  AiChatInput,
+  AiSseChunk
+> {
+  /** Routes events that target another (already streamed) message. */
+  onExternalReview?: (messageId: number, review: AiReviewSchema) => void;
+
+  constructor(url: string, onSettled?: (result?: { ok: boolean; aborted?: boolean }) => void) {
+    super({
+      request: XRequest<AiChatInput, AiSseChunk, AiChatMessage>(url, {
+        manual: true,
+        fetch: authenticatedFetch,
+        timeout: 15_000,
+        streamTimeout: 1_800_000,
+        callbacks: {
+          onUpdate: () => undefined,
+          onSuccess: () => onSettled?.({ ok: true }),
+          onError: (error) =>
+            onSettled?.({
+              ok: false,
+              aborted: error?.name === 'AbortError',
+            }),
+        },
+      }),
+    });
+  }
+
+  transformParams(
+    requestParams: Partial<AiChatInput>,
+    options: XRequestOptions<AiChatInput, AiSseChunk, AiChatMessage>,
+  ): AiChatInput {
+    return {
+      ...options.params,
+      message: requestParams.message?.trim() || '',
+      attachmentIds: requestParams.attachmentIds ?? [],
+      skillKey: requestParams.skillKey ?? null,
+      clientRequestId: requestParams.clientRequestId || crypto.randomUUID(),
+      reasoningEffort: requestParams.reasoningEffort,
+      localAttachments: requestParams.localAttachments,
+      formSubmission: requestParams.formSubmission,
+      reviewSubmission: requestParams.reviewSubmission,
+      regenerateMessageId: requestParams.regenerateMessageId,
+      editMessageId: requestParams.editMessageId,
+      reloadMessage: requestParams.reloadMessage,
+    };
+  }
+
+  transformLocalMessage(requestParams: Partial<AiChatInput>): AiChatMessage | AiChatMessage[] {
+    if (requestParams.editMessageId) {
+      // 编辑消息不需要新增用户气泡，store 里已原位更新原消息。
+      return [];
+    }
+    if (requestParams.formSubmission) {
+      return {
+        role: 'user',
+        content: '',
+        reasoningContent: '',
+        toolRuns: [],
+        attachments: requestParams.localAttachments ?? [],
+        metadata: {
+          a2uiSubmit: {
+            formTitle: requestParams.formSubmission.formTitle,
+          },
+        },
+      };
+    }
+    if (requestParams.reviewSubmission) {
+      return {
+        role: 'user',
+        content: '',
+        reasoningContent: '',
+        toolRuns: [],
+        attachments: requestParams.localAttachments ?? [],
+        metadata: {
+          a2uiReviewSubmit: {
+            reviewTitle: requestParams.reviewSubmission.reviewTitle,
+          },
+        },
+      };
+    }
+    return {
+      role: 'user',
+      content: requestParams.message?.trim() || '',
+      reasoningContent: '',
+      toolRuns: [],
+      attachments: requestParams.localAttachments ?? [],
+    };
+  }
+
+  transformMessage(info: TransformMessage<AiChatMessage, AiSseChunk>): AiChatMessage {
+    const { event, payload } = parseSsePayload(info.chunk);
+    if (
+      event === 'ui.review' &&
+      payload.review &&
+      typeof payload.messageId === 'number' &&
+      info.originMessage?.id !== payload.messageId
+    ) {
+      // The submitted review belongs to the original assistant message;
+      // do not merge it into the message currently being streamed.
+      this.onExternalReview?.(payload.messageId, payload.review);
+      return info.originMessage ?? emptyAssistant();
+    }
+    return reduceAiSseMessage(info.originMessage, info.chunk);
+  }
+}

apps/admin/src/components/AiChat/reviewSection.ts

@@ -0,0 +1,115 @@
+import type { AiReviewSection, AiReviewSectionStatus, AiReviewSectionType } from './types';
+
+export const SECTION_TYPE_LABELS: Record<AiReviewSectionType, string> = {
+  students: '学生',
+  rooms: '宿舍',
+  transfers: '换宿',
+  checkins: '入住记录',
+};
+
+export const SECTION_ORDER: AiReviewSectionType[] = ['students', 'rooms', 'transfers', 'checkins'];
+
+const SECTION_DEPENDENCIES: Record<AiReviewSectionType, AiReviewSectionType[]> = {
+  students: [],
+  rooms: [],
+  transfers: ['students', 'rooms'],
+  checkins: [],
+};
+
+export function sectionType(section: Pick<AiReviewSection, 'key' | 'type'>): AiReviewSectionType {
+  if (
+    section.type === 'students' ||
+    section.type === 'rooms' ||
+    section.type === 'transfers' ||
+    section.type === 'checkins'
+  ) {
+    return section.type;
+  }
+  const key = section.key as AiReviewSectionType;
+  if (key === 'students' || key === 'rooms' || key === 'transfers' || key === 'checkins') {
+    return key;
+  }
+  const prefix = SECTION_ORDER.find((type) => section.key.startsWith(`${type}_`));
+  return prefix ?? 'students';
+}
+
+export function sectionCount(section: AiReviewSection): number {
+  return section.rows.length;
+}
+
+export function sectionStatus(section: AiReviewSection): AiReviewSectionStatus {
+  return section.status ?? 'pending';
+}
+
+export function sectionResultText(section: AiReviewSection): string {
+  if (!section.resultSummary) return '';
+  try {
+    const parsed = JSON.parse(section.resultSummary) as { message?: unknown };
+    if (typeof parsed.message === 'string') return parsed.message;
+  } catch {
+    // Older data may store a plain text summary.
+  }
+  return section.resultSummary;
+}
+
+export const SECTION_STATUS_LABELS: Record<AiReviewSectionStatus, string> = {
+  pending: '待确认',
+  submitted: '已导入',
+  failed: '失败',
+  skipped: '已跳过',
+};
+
+export type GroupStatus = 'pending' | 'partial' | 'submitted' | 'failed' | 'importing';
+
+export const GROUP_STATUS_LABELS: Record<GroupStatus, string> = {
+  pending: '待确认',
+  partial: '部分完成',
+  submitted: '已导入',
+  failed: '失败',
+  importing: '导入中',
+};
+
+export function groupSections(
+  sections: AiReviewSection[],
+  type: AiReviewSectionType,
+): AiReviewSection[] {
+  return sections.filter((section) => sectionType(section) === type);
+}
+
+export function groupStatus(
+  sections: AiReviewSection[],
+  type: AiReviewSectionType,
+  submittingKey: string | null,
+  submittingGroup: boolean,
+  activeType?: AiReviewSectionType,
+): GroupStatus {
+  const items = groupSections(sections, type);
+  if (items.length === 0) return 'pending';
+  if (
+    (submittingGroup && type === activeType) ||
+    items.some((item) => submittingKey === item.key)
+  ) {
+    return 'importing';
+  }
+  if (items.some((item) => sectionStatus(item) === 'failed')) return 'failed';
+  if (items.every((item) => sectionStatus(item) === 'submitted')) return 'submitted';
+  return 'partial';
+}
+
+export function dependencyHint(
+  sections: AiReviewSection[],
+  type: AiReviewSectionType,
+): { step: number; title: string } | null {
+  for (const dependencyType of SECTION_DEPENDENCIES[type] ?? []) {
+    const matches = groupSections(sections, dependencyType);
+    if (matches.length === 0) {
+      return { step: -1, title: SECTION_TYPE_LABELS[dependencyType] };
+    }
+    for (const section of matches) {
+      if (sectionStatus(section) !== 'submitted') {
+        return { step: sections.indexOf(section), title: section.title };
+      }
+    }
+  }
+  return null;
+}

apps/admin/src/components/AiChat/style.css

@@ -0,0 +1,496 @@
+.ai-chat-drawer .ant-drawer-body {
+  overflow: hidden;
+}
+
+.ai-chat-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.ai-chat-sender-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.ai-chat-sender-footer {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.ai-chat-sender-footer .ant-sender-switch {
+  margin-inline: 0;
+}
+
+.ai-chat-layout {
+  position: relative;
+  display: flex;
+  height: 100%;
+  min-height: 0;
+  background: #fff;
+}
+
+.ai-chat-sidebar {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  flex: 0 0 0;
+  width: 0;
+  min-width: 0;
+  overflow: hidden;
+  background: #f7f7f8;
+  border-right: 1px solid #e5e5e7;
+  transition: flex-basis 180ms ease;
+}
+
+.ai-chat-sidebar.is-open {
+  flex-basis: 248px;
+  width: 248px;
+  padding: 12px 8px;
+}
+
+.ai-chat-sidebar .ant-conversations {
+  width: 232px;
+  flex: 1;
+  min-height: 0;
+  height: auto;
+  overflow-y: auto;
+}
+
+.ai-chat-sidebar .ant-conversations-creation {
+  margin-bottom: 8px;
+}
+
+.ai-chat-conversation-label {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+}
+
+.ai-chat-conversation-label__title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ai-chat-conversation-check {
+  flex: none;
+  pointer-events: none;
+  margin-inline-end: 2px;
+}
+
+/* 运行中指示：使用 antd LoadingOutlined 旋转图标 */
+.ai-chat-conversation-loading {
+  color: #007aff;
+  font-size: 12px;
+  flex: none;
+}
+
+.ai-chat-streaming-placeholder {
+  display: inline-flex;
+  align-items: center;
+  color: #007aff;
+  font-size: 16px;
+  padding: 4px 2px;
+}
+
+/* 失败 / 已停止：极简状态文字，不再使用 Tag */
+.ai-chat-conversation-state {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  flex: none;
+  font-size: 12px;
+  line-height: 1;
+}
+
+.ai-chat-conversation-state i {
+  width: 5px;
+  height: 5px;
+  border-radius: 50%;
+}
+
+.ai-chat-conversation-state.is-error {
+  color: #ff4d4f;
+}
+
+.ai-chat-conversation-state.is-error i {
+  background: #ff4d4f;
+}
+
+.ai-chat-conversation-state.is-stopped {
+  color: #8c8c8c;
+}
+
+.ai-chat-conversation-state.is-stopped i {
+  background: #bfbfbf;
+}
+
+.ai-chat-sidebar__loading {
+  position: absolute;
+  inset: 68px 0 auto;
+}
+
+.ai-chat-sidebar__footer {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding-top: 8px;
+  margin-top: 8px;
+  border-top: 1px solid #f0f0f0;
+  min-width: 0;
+}
+
+.ai-chat-sidebar__selected-count {
+  margin-right: auto;
+  padding: 0 4px;
+  font-size: 12px;
+  color: #8c8c8c;
+  white-space: nowrap;
+}
+
+.ai-chat-main {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+}
+
+.ai-chat-toolbar {
+  display: flex;
+  flex: 0 0 48px;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+  padding: 0 12px;
+  border-bottom: 1px solid #ededf0;
+}
+
+.ai-chat-toolbar .ant-typography {
+  flex: 1 1 auto;
+  min-width: 0;
+  font-weight: 600;
+}
+
+.ai-chat-welcome {
+  display: grid;
+  width: min(720px, 100%);
+  gap: 20px;
+  padding: 32px;
+}
+
+.ai-chat-welcome .ant-welcome-icon {
+  color: #007aff;
+}
+
+.ai-chat-messages {
+  display: flex;
+  flex: 1 1 auto;
+  align-items: center;
+  justify-content: center;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.ai-chat-messages > .ant-bubble-list {
+  width: 100%;
+  height: 100%;
+  padding: 20px clamp(16px, 4vw, 48px);
+}
+
+.ai-chat-messages .ant-bubble {
+  position: relative;
+}
+
+.ai-chat-messages .ant-bubble-content {
+  max-width: min(100%, 680px);
+}
+
+.ai-chat-messages .ant-bubble-extra {
+  position: absolute;
+  top: 2px;
+  right: 10px;
+  z-index: 2;
+}
+
+.ai-chat-hover-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  padding: 3px;
+  background: rgba(255, 255, 255, 0.94);
+  border: 1px solid #eceef2;
+  border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.07);
+  opacity: 0;
+  transform: translateY(-3px);
+  transition:
+    opacity 0.15s ease,
+    transform 0.15s ease;
+  pointer-events: none;
+}
+
+.ai-chat-messages .ant-bubble:hover .ai-chat-hover-actions,
+.ai-chat-hover-actions:focus-within {
+  opacity: 1;
+  transform: translateY(0);
+  pointer-events: auto;
+}
+
+.ai-chat-hover-action {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  border-radius: 6px;
+  color: #5f6672;
+  font-size: 14px;
+  cursor: pointer;
+  user-select: none;
+}
+
+.ai-chat-hover-action:hover {
+  background: #f0f2f5;
+  color: #1f2329;
+}
+
+.ai-chat-hover-action.is-danger:hover {
+  background: #fff1f0;
+  color: #cf1322;
+}
+
+.ai-chat-user-text {
+  max-width: 100%;
+  overflow-wrap: anywhere;
+  white-space: pre-wrap;
+}
+
+.ai-chat-user-content {
+  max-width: 100%;
+}
+
+.ai-chat-user-edit {
+  width: min(520px, 100%);
+}
+
+.ai-chat-answer {
+  width: 100%;
+  min-width: 0;
+}
+
+.ai-chat-answer .ant-space-item,
+.ai-chat-answer .ant-x-markdown {
+  min-width: 0;
+  max-width: 100%;
+}
+
+.ai-chat-answer pre,
+.ai-chat-answer table {
+  max-width: 100%;
+  overflow-x: auto;
+}
+
+.ai-chat-answer .ant-thought-chain {
+  padding: 10px 12px;
+  background: #f7f8fa;
+  border: 1px solid #eceef2;
+  border-radius: 10px;
+}
+
+.ai-chat-composer {
+  flex: 0 0 auto;
+  padding: 12px clamp(12px, 3vw, 32px) 14px;
+  background: #fff;
+  border-top: 1px solid #ededf0;
+}
+
+.ai-chat-composer > .ant-sender {
+  max-width: 820px;
+  margin: 0 auto;
+}
+
+.ai-chat-composer .ant-attachments {
+  max-width: 820px;
+}
+
+.ai-chat-composer .ant-sender-input:focus,
+.ai-chat-composer .ant-sender-input:focus-visible,
+.ai-chat-composer .ant-sender-input:focus-within {
+  outline: none;
+  box-shadow: none;
+}
+
+.ai-chat-composer .ant-sender-prefix {
+  display: flex;
+  align-items: center;
+  align-self: center;
+}
+
+.ai-chat-composer .ant-sender-prefix .ant-btn {
+  color: #8a8f99;
+}
+
+.ai-chat-disclaimer {
+  display: block;
+  margin-top: 6px;
+  font-size: 11px;
+  text-align: center;
+}
+
+@media (max-width: 575px) {
+  .ai-chat-sidebar {
+    position: absolute;
+    z-index: 2;
+    inset: 0 auto 0 0;
+    box-shadow: 8px 0 24px rgba(0, 0, 0, 0.08);
+  }
+
+  .ai-chat-sidebar.is-open {
+    width: min(82vw, 300px);
+    flex-basis: min(82vw, 300px);
+  }
+
+  .ai-chat-sidebar .ant-conversations {
+    width: calc(min(82vw, 300px) - 16px);
+  }
+
+  .ai-chat-messages > .ant-bubble-list {
+    padding: 14px 12px;
+  }
+
+  .ai-chat-messages .ant-bubble-content {
+    max-width: 92%;
+  }
+}
+
+.ai-chat-dynamic-form {
+  margin-top: 10px;
+  padding: 12px 14px;
+  border: 1px solid #e5e7eb;
+  border-radius: 10px;
+  background: #fafafa;
+  max-width: 420px;
+}
+
+.ai-chat-dynamic-form__desc {
+  font-size: 12px;
+}
+
+.ai-chat-dynamic-form .ant-form-item {
+  margin-bottom: 10px;
+}
+
+.ai-chat-dynamic-form__number,
+.ai-chat-dynamic-form__date {
+  width: 100%;
+}
+
+.ai-chat-dynamic-form__error {
+  margin-bottom: 10px;
+}
+
+.ai-chat-review {
+  width: 100%;
+  min-width: 0;
+}
+
+.ai-chat-review-card {
+  margin-top: 10px;
+  padding: 12px 14px;
+  border: 1px solid #e5e7eb;
+  border-radius: 12px;
+  background: #fff;
+}
+
+.ai-chat-review-card__title {
+  font-size: 15px;
+}
+
+.ai-chat-review-card__summary {
+  margin: 4px 0 8px !important;
+  font-size: 12px;
+}
+
+.ai-chat-review-card__footer {
+  margin-top: 6px;
+  padding-top: 10px;
+  border-top: 1px dashed #e5e7eb;
+}
+
+.ai-chat-review-card__step {
+  margin-top: 10px;
+}
+
+.ai-chat-review-card__group {
+  margin-top: 12px;
+  padding: 10px;
+  border: 1px solid #e8e8e8;
+  border-radius: 8px;
+  background: #fafafa;
+}
+
+.ai-chat-review-card__sheets {
+  padding: 4px 0;
+}
+
+.ai-chat-review-card__sheet {
+  padding: 8px 10px;
+  border: 1px solid #f0f0f0;
+  border-radius: 6px;
+  background: #fff;
+  cursor: pointer;
+  transition: border-color 0.2s;
+}
+
+.ai-chat-review-card__sheet:hover {
+  border-color: #1677ff;
+}
+
+.ai-chat-review-card__step-result {
+  font-size: 12px;
+}
+
+.ai-chat-review-card__step-error {
+  margin-top: 8px;
+}
+
+.ai-chat-review__issues {
+  margin: 4px 0 0;
+  padding-left: 18px;
+  font-size: 12px;
+}
+
+.ai-chat-review__error {
+  margin-top: 8px;
+}
+
+.ai-chat-chart {
+  width: 100%;
+  min-width: 0;
+}
+
+.ai-chat-chart-card {
+  margin-top: 10px;
+  padding: 12px 14px;
+  border: 1px solid #e5e7eb;
+  border-radius: 12px;
+  background: #fff;
+}
+
+.ai-chat-chart-card__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 6px;
+}

apps/admin/src/components/AiChat/types.ts

@@ -0,0 +1,218 @@
+export interface AiConversation {
+  id: number;
+  title: string;
+  lockedSkillKey: string | null;
+  createdAt: string;
+  updatedAt: string;
+  lastMessageAt: string | null;
+}
+
+export interface AiSkillTool {
+  name: string;
+  description: string;
+}
+
+export interface AiSkill {
+  key: string;
+  name: string;
+  description: string;
+  examples: string[];
+  tools: AiSkillTool[];
+}
+
+export interface AiAttachment {
+  id: number;
+  name: string;
+  mimeType: string;
+  size: number;
+  status: 'processing' | 'ready' | 'failed';
+  error?: string | null;
+  url: string;
+  createdAt: string;
+}
+
+export interface AiFormFieldOption {
+  label: string;
+  value: string;
+}
+
+export interface AiFormField {
+  name: string;
+  label: string;
+  type: 'input' | 'textarea' | 'number' | 'select' | 'date';
+  required?: boolean;
+  placeholder?: string;
+  defaultValue?: string | number;
+  options?: AiFormFieldOption[];
+}
+
+export interface AiFormSchema {
+  id: string;
+  title: string;
+  description?: string | null;
+  submitLabel?: string;
+  fields: AiFormField[];
+  status?: 'pending' | 'submitted';
+}
+
+export interface AiReviewColumn {
+  key: string;
+  title: string;
+}
+
+export interface AiReviewRow {
+  [key: string]: string | number | boolean | null;
+}
+
+export type AiReviewSectionStatus = 'pending' | 'submitted' | 'failed' | 'skipped';
+export type AiReviewSectionType = 'students' | 'rooms' | 'transfers' | 'checkins';
+
+export interface AiReviewSection {
+  key: string;
+  type?: AiReviewSectionType;
+  title: string;
+  kind: 'table';
+  sheet?: string;
+  columns: AiReviewColumn[];
+  rows: AiReviewRow[];
+  issues: string[];
+  status?: AiReviewSectionStatus;
+  resultSummary?: string | null;
+  submittedAt?: string | null;
+}
+
+export interface AiReviewSchema {
+  id: string;
+  title: string;
+  summary?: string | null;
+  sections: AiReviewSection[];
+  status?: 'pending' | 'submitted' | 'expired';
+  resultSummary?: string | null;
+}
+
+export interface AiChartSchema {
+  id: string;
+  title: string;
+  chartType: 'line' | 'bar' | 'pie' | 'area' | 'scatter' | 'radar' | 'gauge' | 'funnel';
+  columns: AiReviewColumn[];
+  rows: AiReviewRow[];
+}
+
+export interface AiImportWizard {
+  runId: string;
+  fileName: string;
+  sheets: Array<{
+    name: string;
+    suggestedStepKey?: AiReviewSectionType | null;
+    headers: string[];
+    rowCount: number;
+  }>;
+  steps: Array<{
+    stepKey: AiReviewSectionType;
+    label: string;
+    sheets: string[];
+    status: string;
+  }>;
+}
+
+export type AiToolRunStatus =
+  | 'running'
+  | 'success'
+  | 'error'
+  | 'failed'
+  | 'denied'
+  | 'not_found';
+
+export interface AiToolRun {
+  id?: number;
+  toolCallId: string;
+  toolName: string;
+  skillKey?: string | null;
+  status: AiToolRunStatus;
+  summary?: string | null;
+  argumentsSummary?: string | null;
+  resultSummary?: string | null;
+  durationMs?: number | null;
+}
+
+export interface AiModelRetryInfo {
+  attempt: number;
+  maxRetries: number;
+  delayMs?: number;
+  reason?: string;
+}
+
+export type AiMessageRole = 'user' | 'assistant';
+
+export interface AiChatMessage {
+  id?: number | string;
+  role: AiMessageRole;
+  content: string;
+  reasoningContent: string;
+  toolRuns: AiToolRun[];
+  attachments: AiAttachment[];
+  forms?: AiFormSchema[];
+  reviews?: AiReviewSchema[];
+  charts?: AiChartSchema[];
+  replyToMessageId?: number | null;
+  metadata?: Record<string, unknown> | null;
+  retrying?: AiModelRetryInfo | null;
+  error?: string;
+  cancelled?: boolean;
+}
+
+export interface AiMessageRecord {
+  id: number;
+  role: AiMessageRole;
+  content: string;
+  reasoningContent: string | null;
+  status: 'pending' | 'completed' | 'failed' | 'cancelled';
+  errorCode: string | null;
+  replyToMessageId?: number | null;
+  metadata?: Record<string, unknown> | null;
+  attachments?: AiAttachment[];
+  createdAt: string;
+  toolRuns?: AiToolRun[];
+}
+
+export interface AiMessagePage {
+  items: AiMessageRecord[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+export interface AiChatInput {
+  message: string;
+  attachmentIds: number[];
+  skillKey: string | null;
+  clientRequestId: string;
+  reasoningEffort?: string | null;
+  editMessageId?: number;
+  localAttachments?: AiAttachment[];
+  formSubmission?: {
+    formId: string;
+    values: Record<string, unknown>;
+    formTitle?: string;
+  };
+  reviewSubmission?: {
+    reviewId: string;
+    reviewTitle?: string;
+  };
+  regenerateMessageId?: number;
+  reloadMessage?: AiChatMessage;
+}
+
+export type AiChatMessageStatus = 'local' | 'loading' | 'updating' | 'success' | 'error' | 'abort';
+
+export interface AiApiResponse<T> {
+  success: boolean;
+  data: T;
+  message?: string;
+}
+
+export interface AiSseChunk {
+  event?: string;
+  data?: string;
+  id?: string;
+}

apps/admin/src/components/AiChat/useAiChatMessageActions.tsx

@@ -0,0 +1,574 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type MutableRefObject } from 'react';
+import { CopyOutlined, DeleteOutlined, EditOutlined, ReloadOutlined } from '@ant-design/icons';
+import type { BubbleItemType, PromptsItemType } from '@ant-design/x';
+import { useXChat, type MessageInfo } from '@ant-design/x-sdk';
+import { App } from 'antd';
+import type { UploadFile, UploadProps } from 'antd';
+import { message } from '../../ui/app-message';
+import { useSettingsStore } from '../../store/settings/settingsStore';
+import { aiChatApi } from './api';
+import { AiMessageContent } from './AiMessageContent';
+import { mapHistoryMessage } from './message-mappers';
+import { GongxueAiChatProvider } from './provider';
+import {
+  emptyAssistant,
+  MessageHoverActions,
+  resolveUserMessageId,
+  toConversationData,
+  toUploadFile,
+  type ConversationData,
+} from './AiChatDrawer.helpers';
+import type {
+  AiAttachment,
+  AiChatInput,
+  AiChatMessage,
+  AiChatMessageStatus,
+  AiFormSchema,
+  AiReviewSchema,
+  AiReviewSection,
+  AiReviewSectionType,
+  AiSkill,
+  AiSseChunk,
+} from './types';
+
+interface UseAiChatMessageActionsParams {
+  activeConversation: ConversationData | undefined;
+  activeId: number | null;
+  provider: GongxueAiChatProvider | undefined;
+  requestAbortRef: MutableRefObject<Map<number, () => void>>;
+  markConversationRunning: (conversationId: number) => void;
+  addConversation: (conversation: ConversationData, placement?: 'prepend' | 'append') => boolean;
+  setActiveConversationKey: (key: string) => boolean;
+  refreshConversations: () => Promise<void>;
+  skills: AiSkill[];
+  lockedSkill: AiSkill | undefined;
+  setImportWizardRunId: (runId: string | null) => void;
+}
+
+export function useAiChatMessageActions({
+  activeConversation,
+  activeId,
+  provider,
+  requestAbortRef,
+  markConversationRunning,
+  addConversation,
+  setActiveConversationKey,
+  refreshConversations,
+  skills,
+  lockedSkill,
+  setImportWizardRunId,
+}: UseAiChatMessageActionsParams) {
+  const { modal } = App.useApp();
+  const [input, setInput] = useState('');
+  const [attachments, setAttachments] = useState<AiAttachment[]>([]);
+  const [editingMessageId, setEditingMessageId] = useState<number | string | null>(null);
+  const deepThinking = useSettingsStore((state) => state.aiChat.deepThinking);
+  const setDeepThinking = useSettingsStore((state) => state.setAiChatDeepThinking);
+  const requestingRef = useRef(false);
+  const abortRef = useRef<() => void>(() => undefined);
+  const attachmentsRef = useRef<AiAttachment[]>([]);
+  const pendingDraftConversationIdRef = useRef<number | null>(null);
+  const messagesRef = useRef<MessageInfo<AiChatMessage>[]>([]);
+
+  const {
+    messages,
+    onRequest,
+    onReload,
+    isRequesting,
+    abort,
+    setMessage,
+    removeMessage,
+    queueRequest,
+  } = useXChat<AiChatMessage, AiChatMessage, AiChatInput, AiSseChunk>({
+    provider,
+    conversationKey: activeConversation?.key || 'no-conversation',
+    defaultMessages: async () => {
+      if (!activeId) return [];
+      const page = await aiChatApi.listMessages(activeId);
+      return page.items.map(mapHistoryMessage);
+    },
+    requestPlaceholder: emptyAssistant(),
+    requestFallback: (
+      params: Partial<AiChatInput>,
+      { error, messageInfo }: { error: Error; messageInfo: MessageInfo<AiChatMessage> },
+    ) => ({
+      ...(params.reloadMessage || messageInfo?.message || emptyAssistant()),
+      error: error.name === 'AbortError' ? undefined : '连接中断，请稍后重试',
+      cancelled: error.name === 'AbortError',
+    }),
+  });
+
+  useEffect(() => {
+    if (!provider) return;
+    provider.onExternalReview = (messageId, review) => {
+      setMessage(messageId, (info) => ({
+        message: {
+          ...info.message,
+          reviews: (info.message.reviews ?? []).some((item) => item.id === review.id)
+            ? (info.message.reviews ?? []).map((item) => (item.id === review.id ? review : item))
+            : [...(info.message.reviews ?? []), review],
+        },
+      }));
+    };
+  }, [provider, setMessage]);
+
+  requestingRef.current = isRequesting;
+  abortRef.current = abort;
+  attachmentsRef.current = attachments;
+  messagesRef.current = messages;
+
+  const stopRequest = useCallback(() => {
+    if (requestingRef.current) abortRef.current();
+  }, []);
+
+  const requestWithStatus = useCallback(
+    (params: AiChatInput) => {
+      if (!activeId || !provider) return;
+      requestAbortRef.current.set(activeId, () => provider.request.abort());
+      markConversationRunning(activeId);
+      onRequest(params);
+    },
+    [activeId, markConversationRunning, onRequest, provider, requestAbortRef],
+  );
+
+  const reloadWithStatus = useCallback(
+    (messageInfo: MessageInfo<AiChatMessage>) => {
+      if (!activeId || !provider || typeof messageInfo.message.id !== 'number') return;
+      requestAbortRef.current.set(activeId, () => provider.request.abort());
+      markConversationRunning(activeId);
+      onReload(messageInfo.id, {
+        message: '',
+        attachmentIds: [],
+        skillKey: activeConversation?.lockedSkillKey ?? null,
+        clientRequestId: crypto.randomUUID(),
+        reasoningEffort: deepThinking ? 'high' : null,
+        regenerateMessageId: messageInfo.message.id,
+        reloadMessage: messageInfo.message,
+      });
+    },
+    [
+      activeConversation?.lockedSkillKey,
+      activeId,
+      deepThinking,
+      markConversationRunning,
+      onReload,
+      provider,
+      requestAbortRef,
+    ],
+  );
+
+  const discardPendingAttachments = useCallback(() => {
+    const pending = attachmentsRef.current;
+    attachmentsRef.current = [];
+    setAttachments([]);
+    for (const attachment of pending) {
+      void aiChatApi.deleteAttachment(attachment.id).catch(() => undefined);
+    }
+  }, []);
+
+  const submit = useCallback(
+    (value: string) => {
+      const text = value.trim();
+      if (!text || isRequesting) return;
+      const submittedAttachments = attachmentsRef.current;
+      attachmentsRef.current = [];
+      setAttachments([]);
+      setInput('');
+      const params: AiChatInput = {
+        message: text,
+        attachmentIds: submittedAttachments.map((item) => item.id),
+        skillKey: activeConversation?.lockedSkillKey ?? null,
+        clientRequestId: crypto.randomUUID(),
+        reasoningEffort: deepThinking ? 'high' : null,
+        localAttachments: submittedAttachments,
+      };
+      if (activeId != null) {
+        requestWithStatus(params);
+        return;
+      }
+      // 草稿态：先创建 session，再发送第一条消息
+      void (async () => {
+        try {
+          const created = toConversationData(await aiChatApi.createConversation());
+          addConversation(created, 'prepend');
+          pendingDraftConversationIdRef.current = created.id;
+          markConversationRunning(created.id);
+          // 通过 XChat 的队列机制发送：等会话 key 切换并加载完成后再真正发出，
+          // 保证消息写入新会话的 store，界面能正常显示对话内容。
+          queueRequest(created.key, params);
+          setActiveConversationKey(created.key);
+        } catch {
+          message.error('创建会话失败，请重试');
+          attachmentsRef.current = submittedAttachments;
+          setAttachments(submittedAttachments);
+          setInput(text);
+        }
+      })();
+    },
+    [
+      activeConversation?.lockedSkillKey,
+      activeId,
+      addConversation,
+      deepThinking,
+      isRequesting,
+      markConversationRunning,
+      queueRequest,
+      requestWithStatus,
+      setActiveConversationKey,
+    ],
+  );
+
+  // 草稿 session 创建完成、provider 就绪后注册中止句柄
+  useEffect(() => {
+    if (activeId == null || !provider) return;
+    if (activeId !== pendingDraftConversationIdRef.current) return;
+    pendingDraftConversationIdRef.current = null;
+    requestAbortRef.current.set(activeId, () => provider.request.abort());
+  }, [activeId, provider, requestAbortRef]);
+
+  const reloadMessage = useCallback(
+    (messageInfo: MessageInfo<AiChatMessage>) => {
+      reloadWithStatus(messageInfo);
+    },
+    [reloadWithStatus],
+  );
+
+  const copyMessage = useCallback((message: AiChatMessage) => {
+    if (!message.content) return;
+    void navigator.clipboard.writeText(message.content);
+  }, []);
+
+  const confirmDeleteMessage = useCallback(
+    (messageInfo: MessageInfo<AiChatMessage>) => {
+      if (!activeId || isRequesting) return;
+      const messageId = resolveUserMessageId(messageInfo, messagesRef.current);
+      if (messageId == null) return;
+      const scopeLabel =
+        messageInfo.message.role === 'user' ? '这条消息及其 AI 回答' : '这条 AI 回答';
+      modal.confirm({
+        title: '删除消息',
+        content: `将删除${scopeLabel}，此操作不可恢复。`,
+        okText: '删除',
+        okButtonProps: { danger: true },
+        cancelText: '取消',
+        onOk: async () => {
+          try {
+            const result = await aiChatApi.deleteMessage(activeId, messageId);
+            const storeIds = new Map<number, number | string>();
+            for (const item of messagesRef.current) {
+              if (typeof item.message.id === 'number') {
+                storeIds.set(item.message.id, item.id);
+              }
+            }
+            // 当前会话内新发送的用户消息没有服务端 ID，但可映射到本地 msg_N key
+            storeIds.set(messageId, messageInfo.id);
+            for (const id of result.deletedIds) removeMessage(storeIds.get(id) ?? id);
+            void refreshConversations();
+          } catch (error) {
+            console.error('删除消息失败', error);
+            message.error('删除消息失败');
+          }
+        },
+      });
+    },
+    [activeId, isRequesting, refreshConversations, removeMessage],
+  );
+
+  const confirmEditMessage = useCallback(
+    (messageInfo: MessageInfo<AiChatMessage>, value: string) => {
+      if (!activeId) return;
+      const content = value.trim();
+      if (!content) {
+        message.warning('消息内容不能为空');
+        return;
+      }
+      const messageId = resolveUserMessageId(messageInfo, messagesRef.current);
+      if (messageId == null) {
+        message.warning('消息尚未同步，请稍后重试');
+        return;
+      }
+      setEditingMessageId(null);
+      if (content === messageInfo.message.content) return;
+
+      setMessage(messageInfo.id, (info) => ({
+        message: {
+          ...info.message,
+          content,
+          metadata: { ...info.message.metadata, edited: true },
+        },
+      }));
+      const index = messagesRef.current.findIndex((item) => item.id === messageInfo.id);
+      if (index >= 0) {
+        for (const item of messagesRef.current.slice(index + 1)) removeMessage(item.id);
+      }
+      requestWithStatus({
+        message: content,
+        attachmentIds: [],
+        skillKey: activeConversation?.lockedSkillKey ?? null,
+        clientRequestId: crypto.randomUUID(),
+        reasoningEffort: deepThinking ? 'high' : null,
+        editMessageId: messageId,
+      });
+    },
+    [
+      activeConversation?.lockedSkillKey,
+      activeId,
+      deepThinking,
+      removeMessage,
+      requestWithStatus,
+      setMessage,
+    ],
+  );
+
+  const submitForm = useCallback(
+    (form: AiFormSchema, values: Record<string, unknown>) => {
+      if (!activeId || isRequesting) return;
+      requestWithStatus({
+        message: '表单提交',
+        attachmentIds: [],
+        skillKey: activeConversation?.lockedSkillKey ?? null,
+        clientRequestId: crypto.randomUUID(),
+        reasoningEffort: deepThinking ? 'high' : null,
+        formSubmission: { formId: form.id, values, formTitle: form.title },
+      });
+    },
+    [activeConversation?.lockedSkillKey, activeId, deepThinking, isRequesting, requestWithStatus],
+  );
+
+  const submitReview = useCallback(
+    (reviewId: string, reviewTitle?: string) => {
+      if (!activeId || isRequesting) return;
+      requestWithStatus({
+        message: '确认批量导入',
+        attachmentIds: [],
+        skillKey: activeConversation?.lockedSkillKey ?? null,
+        clientRequestId: crypto.randomUUID(),
+        reasoningEffort: deepThinking ? 'high' : null,
+        reviewSubmission: { reviewId, reviewTitle },
+      });
+    },
+    [activeConversation?.lockedSkillKey, activeId, deepThinking, isRequesting, requestWithStatus],
+  );
+
+  const confirmReviewStep = useCallback(
+    async (
+      messageId: number | undefined,
+      reviewId: string,
+      sectionKey: AiReviewSection['key'],
+    ): Promise<AiReviewSchema> => {
+      const updated = await aiChatApi.confirmReviewStep(reviewId, sectionKey);
+      const apply = (review: AiReviewSchema) => {
+        if (provider?.onExternalReview && typeof messageId === 'number') {
+          provider.onExternalReview(messageId, review);
+        } else if (typeof messageId === 'number') {
+          setMessage(messageId, (info) => {
+            const reviews = info.message.reviews ?? [];
+            const exists = reviews.some((item) => item.id === review.id);
+            return {
+              message: {
+                ...info.message,
+                reviews: exists
+                  ? reviews.map((item) => (item.id === review.id ? review : item))
+                  : [...reviews, review],
+              },
+            };
+          });
+        }
+      };
+      apply(updated);
+      return updated;
+    },
+    [provider, setMessage],
+  );
+
+  const confirmReviewGroup = useCallback(
+    async (
+      messageId: number | undefined,
+      reviewId: string,
+      type: AiReviewSectionType,
+    ): Promise<AiReviewSchema> => {
+      const updated = await aiChatApi.confirmReviewGroup(reviewId, type);
+      if (provider?.onExternalReview && typeof messageId === 'number') {
+        provider.onExternalReview(messageId, updated);
+      } else if (typeof messageId === 'number') {
+        setMessage(messageId, (info) => {
+          const reviews = info.message.reviews ?? [];
+          const exists = reviews.some((item) => item.id === updated.id);
+          return {
+            message: {
+              ...info.message,
+              reviews: exists
+                ? reviews.map((item) => (item.id === updated.id ? updated : item))
+                : [...reviews, updated],
+            },
+          };
+        });
+      }
+      return updated;
+    },
+    [provider, setMessage],
+  );
+
+  const customUpload = useCallback<NonNullable<UploadProps['customRequest']>>(async (options) => {
+    const file = options.file as File;
+    if (attachmentsRef.current.length >= 5) {
+      const error = new Error('每条消息最多添加 5 个附件');
+      options.onError?.(error);
+      message.warning(error.message);
+      return;
+    }
+    try {
+      const uploaded = await aiChatApi.uploadAttachment(file);
+      setAttachments((items) => [...items, uploaded]);
+      options.onSuccess?.(uploaded, file);
+    } catch (error) {
+      options.onError?.(error instanceof Error ? error : new Error('附件上传失败'));
+      message.error('附件上传失败');
+    }
+  }, []);
+
+  const removeAttachment = useCallback(async (file: UploadFile<AiAttachment>) => {
+    const attachment = file.response;
+    if (!attachment) return true;
+    try {
+      await aiChatApi.deleteAttachment(attachment.id);
+      setAttachments((items) => items.filter((item) => item.id !== attachment.id));
+      return true;
+    } catch {
+      message.error('删除附件失败');
+      return false;
+    }
+  }, []);
+
+  const uploadItems = useMemo(() => attachments.map(toUploadFile), [attachments]);
+  const promptItems = useMemo<PromptsItemType[]>(
+    () =>
+      (lockedSkill ? [lockedSkill] : skills)
+        .flatMap((skill) =>
+          skill.examples.slice(0, lockedSkill ? 4 : 1).map((example) => ({ skill, example })),
+        )
+        .slice(0, 5)
+        .map(({ skill, example }) => ({
+          key: `${skill.key}-${example}`,
+          label: example,
+          description: skill.name,
+        })),
+    [lockedSkill, skills],
+  );
+
+  const bubbleItems = useMemo<BubbleItemType[]>(
+    () =>
+      messages.map((info) => ({
+        key: info.id,
+        role: info.message.role === 'assistant' ? 'assistant' : 'user',
+        status: info.status,
+        content: info.message,
+        extra:
+          info.status !== 'loading' && info.status !== 'updating' && !isRequesting ? (
+            info.message.role === 'user' ? (
+              editingMessageId === info.id ? undefined : (
+                <MessageHoverActions
+                  items={[
+                    {
+                      key: 'copy',
+                      title: '复制',
+                      icon: <CopyOutlined />,
+                      onClick: () => copyMessage(info.message),
+                    },
+                    {
+                      key: 'edit',
+                      title: '编辑',
+                      icon: <EditOutlined />,
+                      onClick: () => setEditingMessageId(info.id),
+                    },
+                    {
+                      key: 'delete',
+                      title: '删除',
+                      icon: <DeleteOutlined />,
+                      danger: true,
+                      onClick: () => void confirmDeleteMessage(info),
+                    },
+                  ]}
+                />
+              )
+            ) : (
+              <MessageHoverActions
+                items={[
+                  {
+                    key: 'copy',
+                    title: '复制',
+                    icon: <CopyOutlined />,
+                    onClick: () => copyMessage(info.message),
+                  },
+                  {
+                    key: 'reload',
+                    title: '重新生成',
+                    icon: <ReloadOutlined />,
+                    onClick: () => reloadMessage(info),
+                  },
+                ]}
+              />
+            )
+          ) : undefined,
+        contentRender: (content: AiChatMessage) => (
+          <AiMessageContent
+            message={content}
+            status={info.status as AiChatMessageStatus}
+            editing={content.role === 'user' && editingMessageId === info.id}
+            onEditConfirm={
+              content.role === 'user' ? (value) => confirmEditMessage(info, value) : undefined
+            }
+            onEditCancel={content.role === 'user' ? () => setEditingMessageId(null) : undefined}
+            onSubmitForm={submitForm}
+            onSubmitReview={submitReview}
+            onConfirmReviewStep={confirmReviewStep}
+            onConfirmReviewGroup={confirmReviewGroup}
+            onOpenImportWizard={setImportWizardRunId}
+          />
+        ),
+      })),
+    [
+      copyMessage,
+      confirmDeleteMessage,
+      confirmEditMessage,
+      confirmReviewGroup,
+      confirmReviewStep,
+      editingMessageId,
+      isRequesting,
+      messages,
+      reloadMessage,
+      setImportWizardRunId,
+      submitForm,
+      submitReview,
+    ],
+  );
+
+  return {
+    input,
+    setInput,
+    attachments,
+    setAttachments,
+    editingMessageId,
+    setEditingMessageId,
+    deepThinking,
+    setDeepThinking,
+    isRequesting,
+    messages,
+    stopRequest,
+    submit,
+    reloadMessage,
+    copyMessage,
+    confirmDeleteMessage,
+    confirmEditMessage,
+    submitForm,
+    submitReview,
+    confirmReviewStep,
+    confirmReviewGroup,
+    customUpload,
+    removeAttachment,
+    discardPendingAttachments,
+    uploadItems,
+    promptItems,
+    bubbleItems,
+  };
+}

apps/admin/src/components/BrandLogo.tsx

@@ -0,0 +1,24 @@
+import { ReadOutlined } from '@ant-design/icons';
+
+const BRAND_COLOR = '#7e14ff';
+
+/** 全局品牌标识：登录页 / 侧边栏 / 页头统一使用 */
+export function BrandLogo({ size = 32 }: { size?: number }) {
+  return (
+    <span
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: size,
+        height: size,
+        borderRadius: 8,
+        background: BRAND_COLOR,
+        color: '#fff',
+        flexShrink: 0,
+      }}
+    >
+      <ReadOutlined style={{ fontSize: size * 0.55 }} />
+    </span>
+  );
+}

apps/admin/src/components/DefaultRoute.tsx

@@ -1,21 +1,16 @@
 import React from 'react';
-import { Navigate } from 'react-router-dom';
+import { Navigate } from 'react-router';
 import { Result, Spin } from 'antd';
 import { usePermission } from '../hooks/usePermission';
 import { findRoleAwareLandingPath } from '../auth/menu-policy';
+import { useUserStore } from '../store/user/userStore';
 
 const DefaultRoute: React.FC = () => {
   const { permissions, permissionsReady } = usePermission();
+  const roles = useUserStore((state) => state.user?.roles ?? []);
   if (!permissionsReady) {
     return <Spin size="large" style={{ display: 'block', margin: '80px auto' }} />;
   }
-  const roles = (() => {
-    try {
-      return JSON.parse(localStorage.getItem('user') || '{}').roles || [];
-    } catch {
-      return [];
-    }
-  })();
   const firstPath = findRoleAwareLandingPath(roles, permissions);
   if (firstPath) return <Navigate to={firstPath} replace />;
   return (

apps/admin/src/components/ECharts.tsx

@@ -1,11 +1,22 @@
 import React, { useEffect, useRef } from 'react';
 import * as echarts from 'echarts/core';
+import type { EChartsType } from 'echarts/core';
 export type EChartsOption = Record<string, unknown>;
-import { BarChart, CustomChart, LineChart, PieChart } from 'echarts/charts';
+import {
+  BarChart,
+  CustomChart,
+  FunnelChart,
+  GaugeChart,
+  LineChart,
+  PieChart,
+  RadarChart,
+  ScatterChart,
+} from 'echarts/charts';
 import {
   DataZoomComponent,
   GridComponent,
   LegendComponent,
+  RadarComponent,
   TooltipComponent,
   VisualMapComponent,
 } from 'echarts/components';
@@ -14,11 +25,16 @@ import { CanvasRenderer } from 'echarts/renderers';
 echarts.use([
   BarChart,
   CustomChart,
+  FunnelChart,
+  GaugeChart,
   LineChart,
   PieChart,
+  RadarChart,
+  ScatterChart,
   DataZoomComponent,
   GridComponent,
   LegendComponent,
+  RadarComponent,
   TooltipComponent,
   VisualMapComponent,
   CanvasRenderer,
@@ -28,15 +44,20 @@ interface EChartsProps {
   option: EChartsOption;
   style?: React.CSSProperties;
   className?: string;
+  /** 图表实例就绪回调（用于导出图片等场景） */
+  onReady?: (chart: EChartsType) => void;
 }
 
-const ECharts: React.FC<EChartsProps> = ({ option, style, className }) => {
+const ECharts: React.FC<EChartsProps> = ({ option, style, className, onReady }) => {
   const containerRef = useRef<HTMLDivElement>(null);
+  const onReadyRef = useRef(onReady);
+  onReadyRef.current = onReady;
 
   useEffect(() => {
     if (!containerRef.current) return;
     const chart = echarts.init(containerRef.current);
     chart.setOption(option);
+    onReadyRef.current?.(chart);
     const observer = new ResizeObserver(() => chart.resize());
     observer.observe(containerRef.current);
     return () => {

apps/admin/src/components/EditableCell/index.tsx

@@ -1,10 +1,11 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { DatePicker, Input, InputNumber, Select, Spin, Tooltip } from 'antd';
-import type { Dayjs } from 'dayjs';
-import dayjs from 'dayjs';
+import dayjs, { type Dayjs } from 'dayjs';
+import equal from 'fast-deep-equal';
 import { usePermission } from '../../hooks/usePermission';
 import { message } from '../../ui/app-message';
 import './style.css';
+import { getErrorMessage } from '../../utils/error';
 
 export type EditableCellEditor =
   | 'text'
@@ -66,7 +67,7 @@ export function serializeEditableValue(value: unknown, editor: EditableCellEdito
 }
 
 export function editableValuesEqual(left: unknown, right: unknown) {
-  return JSON.stringify(left ?? null) === JSON.stringify(right ?? null);
+  return equal(left ?? null, right ?? null);
 }
 
 function isEditorOverlay(target: EventTarget | null) {
@@ -112,43 +113,40 @@ const EditableCell = <Value,>({
     [editor, formatValue, value],
   );
 
-  useEffect(() => {
-    if (!editing) {
-      setDraft(normalizeEditableValue(formatValue ? formatValue(value) : value, editor));
-    }
-  }, [editing, editor, formatValue, value]);
-
   const cancel = useCallback(() => {
     setDraft(normalizeEditableValue(formatValue ? formatValue(value) : value, editor));
     if (activeCell?.id === idRef.current) activeCell = null;
     setEditing(false);
   }, [editor, formatValue, value]);
 
-  const saveValue = useCallback(async (nextDraft: unknown) => {
-    if (saving) return false;
-    const serialized = serializeEditableValue(nextDraft, editor);
-    if (required && (serialized === '' || serialized === undefined || serialized === null)) {
-      message.error('该字段不能为空');
-      return false;
-    }
-    if (editableValuesEqual(serialized, original)) {
-      if (activeCell?.id === idRef.current) activeCell = null;
-      setEditing(false);
-      return true;
-    }
-    setSaving(true);
-    try {
-      await onSave(parseValue ? parseValue(serialized) : (serialized as Value));
-      if (activeCell?.id === idRef.current) activeCell = null;
-      setEditing(false);
-      return true;
-    } catch (error) {
-      message.error((error as { message?: string })?.message || '保存失败');
-      return false;
-    } finally {
-      setSaving(false);
-    }
-  }, [editor, onSave, original, parseValue, required, saving]);
+  const saveValue = useCallback(
+    async (nextDraft: unknown) => {
+      if (saving) return false;
+      const serialized = serializeEditableValue(nextDraft, editor);
+      if (required && (serialized === '' || serialized === undefined || serialized === null)) {
+        message.error('该字段不能为空');
+        return false;
+      }
+      if (editableValuesEqual(serialized, original)) {
+        if (activeCell?.id === idRef.current) activeCell = null;
+        setEditing(false);
+        return true;
+      }
+      setSaving(true);
+      try {
+        await onSave(parseValue ? parseValue(serialized) : (serialized as Value));
+        if (activeCell?.id === idRef.current) activeCell = null;
+        setEditing(false);
+        return true;
+      } catch (error) {
+        message.error(getErrorMessage(error, '保存失败'));
+        return false;
+      } finally {
+        setSaving(false);
+      }
+    },
+    [editor, onSave, original, parseValue, required, saving],
+  );
 
   const save = useCallback(() => saveValue(draft), [draft, saveValue]);
 
@@ -199,6 +197,7 @@ const EditableCell = <Value,>({
       if (!saved) return;
     }
     activeCell = { id: idRef.current, save };
+    setDraft(normalizeEditableValue(formatValue ? formatValue(value) : value, editor));
     setEditing(true);
   };
 

apps/admin/src/components/ImportWizard/ImportWizardModal.tsx

@@ -0,0 +1,616 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  CheckCircleOutlined,
+  CloseCircleOutlined,
+  DownloadOutlined,
+  InboxOutlined,
+  ReloadOutlined,
+  StepForwardOutlined,
+} from '@ant-design/icons';
+import {
+  Alert,
+  Button,
+  Checkbox,
+  Descriptions,
+  Flex,
+  Modal,
+  Select,
+  Space,
+  Spin,
+  Steps,
+  Table,
+  Tag,
+  Tooltip,
+  Typography,
+  Upload,
+} from 'antd';
+import type { UploadProps } from 'antd';
+import { message } from '../../ui/app-message';
+import { useUserStore } from '../../store/user/userStore';
+import {
+  commitImportStep,
+  createImportRun,
+  getImportRun,
+  importErrorReportUrl,
+  previewImportStep,
+} from '../../api/imports';
+import {
+  STEP_FIELDS,
+  type ImportPreviewResult,
+  type ImportReceipt,
+  type ImportRunDetail,
+  type ImportStepKey,
+} from './types';
+
+interface ImportWizardModalProps {
+  open: boolean;
+  /** AI 对话生成的导入任务；为空时向导从上传文件开始。 */
+  runId?: string | null;
+  onClose: () => void;
+}
+
+type RowAction = 'create' | 'update' | 'skip';
+
+const ACTION_META: Record<RowAction, { label: string; color: string }> = {
+  create: { label: '新建', color: 'blue' },
+  update: { label: '更新', color: 'orange' },
+  skip: { label: '跳过', color: 'default' },
+};
+
+function guessMapping(stepKey: ImportStepKey, headers: string[]): Record<string, string> {
+  const mapping: Record<string, string> = {};
+  for (const field of STEP_FIELDS[stepKey]) {
+    const hit = headers.find((header) => {
+      const normalizedHeader = header.replace(/[\s（）()]/g, '').toLowerCase();
+      const normalizedLabel = field.label.replace(/[\s（）()]/g, '').toLowerCase();
+      return (
+        normalizedHeader === normalizedLabel ||
+        normalizedHeader.includes(normalizedLabel) ||
+        normalizedLabel.includes(normalizedHeader)
+      );
+    });
+    if (hit) mapping[field.key] = hit;
+  }
+  return mapping;
+}
+
+function keyInfo(stepKey: ImportStepKey, row: ImportPreviewResult['rows'][number]): string {
+  const fields = row.fields;
+  if (stepKey === 'students') {
+    return [fields.name, fields.studentNo, fields.phone].filter(Boolean).join(' / ');
+  }
+  if (stepKey === 'rooms') {
+    return [fields.roomNumber, fields.building, fields.floor].filter(Boolean).join(' / ');
+  }
+  if (stepKey === 'checkins') {
+    return [fields.name, fields.studentNo, fields.phone, fields.roomNumber, fields.checkInDate]
+      .filter(Boolean)
+      .join(' / ');
+  }
+  return [fields.studentNo, fields.phone, fields.oldRoom, fields.newRoom, fields.transferDate]
+    .filter(Boolean)
+    .join(' / ');
+}
+
+async function downloadErrorReport(runId: string, stepKey?: ImportStepKey): Promise<void> {
+  const token = useUserStore.getState().token;
+  const response = await fetch(importErrorReportUrl(runId, stepKey), {
+    headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+  });
+  if (!response.ok) throw new Error('错误报告下载失败');
+  const blob = await response.blob();
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = `导入错误报告-${runId.slice(0, 8)}.csv`;
+  anchor.click();
+  window.setTimeout(() => URL.revokeObjectURL(url), 60_000);
+}
+
+export const ImportWizardModal: React.FC<ImportWizardModalProps> = ({
+  open,
+  runId: initialRunId,
+  onClose,
+}) => {
+  const [run, setRun] = useState<ImportRunDetail | null>(null);
+  const [loadingRun, setLoadingRun] = useState(false);
+  const [uploading, setUploading] = useState(false);
+  const [activeStepKey, setActiveStepKey] = useState<ImportStepKey | null>(null);
+  const [sheetSelection, setSheetSelection] = useState<Record<string, string[]>>({});
+  const [mappingDraft, setMappingDraft] = useState<Record<string, Record<string, string>>>({});
+  const [previewByStep, setPreviewByStep] = useState<Record<string, ImportPreviewResult>>({});
+  const [previewLoading, setPreviewLoading] = useState(false);
+  const [onlyErrors, setOnlyErrors] = useState(false);
+  const [rowActions, setRowActions] = useState<Record<number, RowAction>>({});
+  const [commitLoading, setCommitLoading] = useState(false);
+  const [receipt, setReceipt] = useState<ImportReceipt | null>(null);
+  const [reportDownloading, setReportDownloading] = useState(false);
+  const requestSeq = useRef(0);
+
+  const loadRun = useCallback(async (runId: string) => {
+    const seq = ++requestSeq.current;
+    setLoadingRun(true);
+    try {
+      const detail = await getImportRun(runId);
+      if (seq !== requestSeq.current) return;
+      setRun(detail);
+      const selections: Record<string, string[]> = {};
+      const mappings: Record<string, Record<string, string>> = {};
+      const sheetHeaders = new Map(detail.sheets.map((sheet) => [sheet.name, sheet.headers]));
+      for (const step of detail.steps) {
+        selections[step.stepKey] = step.sheets;
+        const mapped =
+          step.mapping && Object.keys(step.mapping).length > 0
+            ? step.mapping
+            : guessMapping(step.stepKey, sheetHeaders.get(step.sheets[0] ?? '') ?? []);
+        mappings[step.stepKey] = mapped;
+      }
+      setSheetSelection(selections);
+      setMappingDraft(mappings);
+      setPreviewByStep({});
+      setRowActions({});
+      setReceipt(null);
+      const firstActive =
+        detail.steps.find((step) => step.status !== 'skipped' && step.status !== 'committed') ??
+        detail.steps.find((step) => step.status !== 'skipped');
+      setActiveStepKey(firstActive?.stepKey ?? detail.currentStepKey);
+    } catch (error) {
+      if (seq !== requestSeq.current) return;
+      message.error(error instanceof Error ? error.message : '导入任务加载失败');
+      setRun(null);
+    } finally {
+      if (seq === requestSeq.current) setLoadingRun(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!open || !initialRunId) return;
+    void loadRun(initialRunId);
+  }, [open, initialRunId, loadRun]);
+
+  const activeStep = useMemo(
+    () => run?.steps.find((step) => step.stepKey === activeStepKey) ?? null,
+    [run, activeStepKey],
+  );
+  const preview = activeStepKey ? (previewByStep[activeStepKey] ?? null) : null;
+
+  const sheetOptions = useMemo(() => (run?.sheets ?? []).map((sheet) => sheet.name), [run]);
+  const headerOptions = useMemo(() => {
+    if (!run || !activeStepKey) return [];
+    const names = sheetSelection[activeStepKey] ?? [];
+    const headers = new Set<string>();
+    for (const sheet of run.sheets) {
+      if (names.includes(sheet.name)) sheet.headers.forEach((header) => headers.add(header));
+    }
+    return [...headers];
+  }, [run, activeStepKey, sheetSelection]);
+
+  const handleUpload: UploadProps['customRequest'] = async (options) => {
+    const file = options.file as File;
+    setUploading(true);
+    try {
+      const detail = await createImportRun(file, { source: 'manual' });
+      await loadRun(detail.id);
+      message.success(`已识别 ${detail.sheets.length} 个工作表`);
+    } catch (error) {
+      message.error(error instanceof Error ? error.message : '文件上传失败');
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  const handlePreview = async () => {
+    if (!run || !activeStepKey || !activeStep) return;
+    const mapping = mappingDraft[activeStepKey] ?? {};
+    const required = STEP_FIELDS[activeStepKey]
+      .filter((field) => field.required)
+      .map((field) => field.key);
+    const missing = required.filter((key) => !mapping[key]);
+    if (missing.length > 0) {
+      message.warning('请先完成必填列的映射');
+      return;
+    }
+    setPreviewLoading(true);
+    try {
+      const result = await previewImportStep(run.id, activeStepKey, {
+        sheets: sheetSelection[activeStepKey] ?? [],
+        mapping,
+      });
+      setPreviewByStep((prev) => ({ ...prev, [activeStepKey]: result }));
+      setRowActions({});
+    } catch (error) {
+      message.error(error instanceof Error ? error.message : '预览失败');
+    } finally {
+      setPreviewLoading(false);
+    }
+  };
+
+  const handleCommit = async () => {
+    if (!run || !activeStepKey || !preview) return;
+    setCommitLoading(true);
+    try {
+      const decisions = preview.rows
+        .filter((row) => row.status === 'valid')
+        .map((row) => ({ rowId: row.id, action: rowActions[row.id] ?? row.action ?? 'create' }));
+      const result = await commitImportStep(run.id, activeStepKey, decisions);
+      setReceipt(result);
+      const refreshed = await getImportRun(run.id);
+      setRun(refreshed);
+      setPreviewByStep({});
+      setRowActions({});
+      if (result.nextStepKey) {
+        setActiveStepKey(result.nextStepKey);
+        const nextStep = refreshed.steps.find((step) => step.stepKey === result.nextStepKey);
+        setMappingDraft((prev) => ({
+          ...prev,
+          [result.nextStepKey as string]: nextStep?.mapping ?? {},
+        }));
+      }
+    } catch (error) {
+      message.error(error instanceof Error ? error.message : '提交失败');
+    } finally {
+      setCommitLoading(false);
+    }
+  };
+
+  const handleReupload = async (file: File) => {
+    if (!run || !activeStepKey) return;
+    setUploading(true);
+    try {
+      const detail = await createImportRun(file, {
+        source: 'manual',
+        stages: [{ stepKey: activeStepKey, sheet: sheetSelection[activeStepKey]?.[0] }],
+        mapping: { [activeStepKey]: mappingDraft[activeStepKey] ?? {} },
+      });
+      await loadRun(detail.id);
+      message.success('已重新上传，并保留原列映射');
+    } catch (error) {
+      message.error(error instanceof Error ? error.message : '重新上传失败');
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  const previewRows = useMemo(() => {
+    if (!preview) return [];
+    return onlyErrors ? preview.rows.filter((row) => row.status === 'error') : preview.rows;
+  }, [preview, onlyErrors]);
+
+  const columns = useMemo(() => {
+    if (!activeStepKey) return [];
+    return [
+      { title: '行号', dataIndex: 'rowNumber', width: 70 },
+      { title: '工作表', dataIndex: 'sheetName', width: 120, ellipsis: true },
+      {
+        title: '数据',
+        key: 'data',
+        render: (_: unknown, row: ImportPreviewResult['rows'][number]) =>
+          keyInfo(activeStepKey, row),
+      },
+      {
+        title: '判定',
+        key: 'action',
+        width: 90,
+        render: (_: unknown, row: ImportPreviewResult['rows'][number]) => {
+          const action = rowActions[row.id] ?? row.action;
+          return action ? (
+            <Tag color={ACTION_META[action].color}>{ACTION_META[action].label}</Tag>
+          ) : (
+            '-'
+          );
+        },
+      },
+      {
+        title: '状态',
+        key: 'status',
+        width: 90,
+        render: (_: unknown, row: ImportPreviewResult['rows'][number]) =>
+          row.status === 'error' ? (
+            <Tag color="red" icon={<CloseCircleOutlined />}>
+              错误
+            </Tag>
+          ) : (
+            <Tag color="green" icon={<CheckCircleOutlined />}>
+              有效
+            </Tag>
+          ),
+      },
+      {
+        title: '错误信息',
+        key: 'errors',
+        ellipsis: true,
+        render: (_: unknown, row: ImportPreviewResult['rows'][number]) =>
+          row.errors.length > 0 ? (
+            <Tooltip title={row.errors.join('；')}>
+              <Typography.Text type="danger" style={{ maxWidth: 320 }}>
+                {row.errors.join('；')}
+              </Typography.Text>
+            </Tooltip>
+          ) : null,
+      },
+      {
+        title: '处理方式',
+        key: 'decision',
+        width: 120,
+        render: (_: unknown, row: ImportPreviewResult['rows'][number]) =>
+          row.status === 'valid' ? (
+            <Select
+              size="small"
+              value={rowActions[row.id] ?? row.action ?? 'create'}
+              options={
+                row.action === 'update'
+                  ? [
+                      { value: 'update', label: '更新' },
+                      { value: 'skip', label: '跳过' },
+                    ]
+                  : [
+                      { value: 'create', label: '新建' },
+                      { value: 'skip', label: '跳过' },
+                    ]
+              }
+              onChange={(value: RowAction) =>
+                setRowActions((prev) => ({ ...prev, [row.id]: value }))
+              }
+            />
+          ) : null,
+      },
+    ];
+  }, [activeStepKey, rowActions]);
+
+  const stageItems = useMemo(
+    () =>
+      (run?.steps ?? [])
+        .filter((step) => step.status !== 'skipped')
+        .map((step) => ({
+          key: step.stepKey,
+          title: step.label,
+          status:
+            step.status === 'committed'
+              ? ('finish' as const)
+              : step.stepKey === activeStepKey
+                ? ('process' as const)
+                : ('wait' as const),
+        })),
+    [run, activeStepKey],
+  );
+
+  const allCommitted = run?.status === 'committed';
+
+  return (
+    <Modal
+      open={open}
+      onCancel={onClose}
+      footer={null}
+      width={980}
+      title="Excel 批量导入向导"
+      destroyOnHidden={false}
+    >
+      {!run && !loadingRun ? (
+        <Space orientation="vertical" size={16} style={{ width: '100%' }}>
+          <Alert
+            type="info"
+            showIcon
+            message="上传 Excel 后，系统会自动识别工作表并按业务依赖分阶段（学生/宿舍 → 入住/换宿）。每一阶段都需要先预览、再确认，确认后才会写入数据库。"
+          />
+          <Upload.Dragger
+            accept=".xlsx,.csv"
+            maxCount={1}
+            showUploadList={false}
+            disabled={uploading}
+            customRequest={handleUpload}
+          >
+            <p className="ant-upload-drag-icon">
+              <InboxOutlined />
+            </p>
+            <p className="ant-upload-text">点击或拖拽 .xlsx / .csv 文件到此区域</p>
+            <p className="ant-upload-hint">单文件不超过 10MB；.xls 请先另存为 .xlsx</p>
+          </Upload.Dragger>
+        </Space>
+      ) : (
+        <Space orientation="vertical" size={16} style={{ width: '100%' }}>
+          <Flex justify="space-between" align="center" wrap gap={8}>
+            <Space wrap>
+              <Typography.Text strong>{run?.fileName}</Typography.Text>
+              <Tag color={allCommitted ? 'success' : 'processing'}>
+                {allCommitted ? '已完成' : '待处理'}
+              </Tag>
+              <Tag>当前阶段：{activeStep?.label ?? '—'}</Tag>
+            </Space>
+            <Space>
+              {preview && preview.summary.error > 0 && (
+                <Button
+                  size="small"
+                  icon={<DownloadOutlined />}
+                  loading={reportDownloading}
+                  onClick={() => {
+                    setReportDownloading(true);
+                    void downloadErrorReport(run?.id ?? '', activeStepKey ?? undefined)
+                      .then(() => message.success('错误报告已下载'))
+                      .catch((error: unknown) =>
+                        message.error(error instanceof Error ? error.message : '下载失败'),
+                      )
+                      .finally(() => setReportDownloading(false));
+                  }}
+                >
+                  下载错误报告
+                </Button>
+              )}
+              <Button size="small" onClick={onClose}>
+                关闭
+              </Button>
+            </Space>
+          </Flex>
+
+          <Steps
+            size="small"
+            items={stageItems}
+            onChange={(index) => {
+              const step = (run?.steps ?? []).filter((s) => s.status !== 'skipped')[index];
+              if (step) setActiveStepKey(step.stepKey);
+            }}
+          />
+
+          {loadingRun ? (
+            <Flex justify="center" style={{ padding: 32 }}>
+              <Spin description="正在加载导入任务..." />
+            </Flex>
+          ) : allCommitted ? (
+            <Space orientation="vertical" size={12} style={{ width: '100%' }}>
+              <Alert type="success" showIcon message="全部阶段已提交完成" />
+              <Descriptions
+                bordered
+                size="small"
+                column={2}
+                items={(run?.steps ?? [])
+                  .filter((step) => step.status !== 'skipped')
+                  .map((step) => ({
+                    key: step.stepKey,
+                    label: step.label,
+                    children: step.summary
+                      ? `新建 ${step.summary.create} / 更新 ${step.summary.update} / 跳过 ${step.summary.skip} / 失败 ${step.summary.error}`
+                      : '—',
+                  }))}
+              />
+              <Button type="primary" onClick={onClose}>
+                完成
+              </Button>
+            </Space>
+          ) : activeStep ? (
+            <Space orientation="vertical" size={12} style={{ width: '100%' }}>
+              {receipt && (
+                <Alert
+                  type={receipt.status === 'committed' ? 'success' : 'warning'}
+                  showIcon
+                  title={receipt.message}
+                  closable
+                  onClose={() => setReceipt(null)}
+                />
+              )}
+              {activeStep.status === 'committed' ? (
+                <Alert
+                  type="success"
+                  showIcon
+                  title={`「${activeStep.label}」已提交`}
+                  description={
+                    activeStep.summary
+                      ? `新建 ${activeStep.summary.create} / 更新 ${activeStep.summary.update} / 跳过 ${activeStep.summary.skip} / 失败 ${activeStep.summary.error}`
+                      : undefined
+                  }
+                />
+              ) : preview ? (
+                <Space orientation="vertical" size={12} style={{ width: '100%' }}>
+                  <Flex wrap gap={12} align="center">
+                    <Space size={4}>
+                      <Tag color="blue">共 {preview.summary.total} 行</Tag>
+                      <Tag color="green">有效 {preview.summary.valid}</Tag>
+                      <Tag color="red">错误 {preview.summary.error}</Tag>
+                      <Tag color="blue">新建 {preview.summary.create}</Tag>
+                      <Tag color="orange">更新 {preview.summary.update}</Tag>
+                    </Space>
+                    <Checkbox
+                      checked={onlyErrors}
+                      onChange={(e) => setOnlyErrors(e.target.checked)}
+                    >
+                      只看错误行
+                    </Checkbox>
+                  </Flex>
+                  <Table
+                    size="small"
+                    rowKey="id"
+                    columns={columns}
+                    dataSource={previewRows}
+                    pagination={{ pageSize: 10, showSizeChanger: false }}
+                    scroll={{ x: 900 }}
+                  />
+                  <Flex justify="end" gap={8}>
+                    <Upload
+                      accept=".xlsx,.csv"
+                      showUploadList={false}
+                      beforeUpload={(file) => {
+                        void handleReupload(file);
+                        return false;
+                      }}
+                    >
+                      <Button icon={<ReloadOutlined />} loading={uploading}>
+                        重新上传并保留映射
+                      </Button>
+                    </Upload>
+                    <Button
+                      type="primary"
+                      icon={<StepForwardOutlined />}
+                      loading={commitLoading}
+                      onClick={() => void handleCommit()}
+                    >
+                      确认提交本阶段
+                    </Button>
+                  </Flex>
+                </Space>
+              ) : (
+                <Space orientation="vertical" size={12} style={{ width: '100%' }}>
+                  <Alert
+                    type="info"
+                    showIcon
+                    title={`配置「${activeStep.label}」阶段`}
+                    description="选择该阶段使用的工作表，并确认列映射；系统会按“学号/手机号/宿舍号”自动区分新建或更新。"
+                  />
+                  <Flex align="center" gap={8}>
+                    <Typography.Text style={{ width: 120 }}>工作表</Typography.Text>
+                    <Select
+                      mode="multiple"
+                      style={{ minWidth: 320, flex: 1 }}
+                      placeholder="选择该阶段的工作表"
+                      value={sheetSelection[activeStepKey ?? ''] ?? []}
+                      options={sheetOptions.map((name) => ({ value: name, label: name }))}
+                      onChange={(values: string[]) =>
+                        setSheetSelection((prev) => ({
+                          ...prev,
+                          [activeStepKey ?? '']: values,
+                        }))
+                      }
+                    />
+                  </Flex>
+                  {STEP_FIELDS[activeStep.stepKey].map((field) => (
+                    <Flex key={field.key} align="center" gap={8}>
+                      <Typography.Text style={{ width: 120 }}>
+                        {field.label}
+                        {field.required ? <span style={{ color: '#ff4d4f' }}> *</span> : null}
+                        {field.identity ? <Tag style={{ marginLeft: 4 }}>匹配键</Tag> : null}
+                      </Typography.Text>
+                      <Select
+                        allowClear
+                        showSearch
+                        style={{ minWidth: 320, flex: 1 }}
+                        placeholder="选择对应列（留空则自动识别）"
+                        value={mappingDraft[activeStepKey ?? '']?.[field.key]}
+                        options={headerOptions.map((header) => ({ value: header, label: header }))}
+                        onChange={(value?: string) =>
+                          setMappingDraft((prev) => {
+                            const current = { ...prev[activeStepKey ?? ''] };
+                            if (value) current[field.key] = value;
+                            else delete current[field.key];
+                            return { ...prev, [activeStepKey ?? '']: current };
+                          })
+                        }
+                      />
+                    </Flex>
+                  ))}
+                  <Flex justify="end">
+                    <Button
+                      type="primary"
+                      loading={previewLoading}
+                      onClick={() => void handlePreview()}
+                    >
+                      开始校验预览
+                    </Button>
+                  </Flex>
+                </Space>
+              )}
+            </Space>
+          ) : (
+            <Alert type="warning" showIcon message="当前没有可处理的阶段" />
+          )}
+        </Space>
+      )}
+    </Modal>
+  );
+};

apps/admin/src/components/ImportWizard/types.ts

@@ -0,0 +1,122 @@
+export type ImportStepKey = 'students' | 'rooms' | 'checkins' | 'transfers';
+
+export interface ImportSheetMeta {
+  name: string;
+  headers: string[];
+  rowCount: number;
+  suggestedStepKey: ImportStepKey | null;
+}
+
+export interface ImportStepSummary {
+  total: number;
+  valid: number;
+  error: number;
+  create: number;
+  update: number;
+  skip: number;
+}
+
+export interface ImportStepDetail {
+  id: number;
+  stepKey: ImportStepKey;
+  label: string;
+  sheets: string[];
+  status: 'pending' | 'ready' | 'committing' | 'committed' | 'failed' | 'skipped';
+  mapping: Record<string, string>;
+  summary: ImportStepSummary | null;
+  committedAt: string | null;
+}
+
+export interface ImportRunDetail {
+  id: string;
+  fileName: string;
+  source: 'ai' | 'manual';
+  status: 'preparing' | 'ready' | 'committing' | 'committed' | 'failed' | 'expired';
+  currentStepKey: ImportStepKey | null;
+  createdAt: string;
+  sheets: ImportSheetMeta[];
+  steps: ImportStepDetail[];
+}
+
+export interface ImportStageRequest {
+  stepKey: ImportStepKey;
+  sheet?: string;
+  headerRow?: number;
+}
+
+export interface ImportPreviewRow {
+  id: number;
+  rowNumber: number;
+  sheetName: string;
+  raw: Record<string, string | number | boolean | null>;
+  fields: Record<string, string | number | boolean | null>;
+  action: 'create' | 'update' | 'skip' | null;
+  status: 'pending' | 'valid' | 'error' | 'committed' | 'skipped';
+  errors: string[];
+}
+
+export interface ImportPreviewResult {
+  stepKey: ImportStepKey;
+  sheetNames: string[];
+  headers: string[];
+  mapping: Record<string, string>;
+  rows: ImportPreviewRow[];
+  summary: ImportStepSummary;
+}
+
+export interface ImportReceipt {
+  runId: string;
+  stepKey: ImportStepKey;
+  status: 'committed' | 'already_committed' | 'conflict';
+  created: number;
+  updated: number;
+  skipped: number;
+  failed: number;
+  total: number;
+  nextStepKey: ImportStepKey | null;
+  runStatus: 'preparing' | 'ready' | 'committing' | 'committed' | 'failed' | 'expired';
+  message: string;
+}
+
+export const STEP_FIELDS: Record<
+  ImportStepKey,
+  Array<{ key: string; label: string; required?: boolean; identity?: boolean }>
+> = {
+  students: [
+    { key: 'name', label: '姓名', required: true },
+    { key: 'studentNo', label: '学号', identity: true },
+    { key: 'phone', label: '手机号', identity: true },
+    { key: 'gender', label: '性别' },
+    { key: 'idNumber', label: '身份证号' },
+    { key: 'ethnicity', label: '民族' },
+    { key: 'emergencyContact', label: '紧急联系人' },
+    { key: 'emergencyPhone', label: '紧急联系电话' },
+    { key: 'organization', label: '校区' },
+    { key: 'status', label: '状态' },
+  ],
+  rooms: [
+    { key: 'roomNumber', label: '宿舍号', required: true },
+    { key: 'building', label: '楼栋' },
+    { key: 'floor', label: '楼层' },
+    { key: 'capacity', label: '容量', required: true },
+    { key: 'roomType', label: '房型' },
+    { key: 'rentalCategory', label: '租期类型' },
+    { key: 'monthlyRate', label: '月租' },
+  ],
+  checkins: [
+    { key: 'name', label: '姓名' },
+    { key: 'studentNo', label: '学号', identity: true },
+    { key: 'phone', label: '手机号', identity: true },
+    { key: 'roomNumber', label: '宿舍号', required: true },
+    { key: 'checkInDate', label: '入住日期', required: true },
+    { key: 'stayType', label: '住宿类型' },
+  ],
+  transfers: [
+    { key: 'studentNo', label: '学号', identity: true },
+    { key: 'phone', label: '手机号', identity: true },
+    { key: 'oldRoom', label: '原宿舍', required: true },
+    { key: 'newRoom', label: '新宿舍', required: true },
+    { key: 'transferDate', label: '换宿日期', required: true },
+    { key: 'reason', label: '原因/备注' },
+  ],
+};

apps/admin/src/components/JinshujuMatchModal.tsx

@@ -1,310 +1,28 @@
-import React, { useEffect, useRef, useState } from 'react';
-import { Button, Form, Input, Modal, Popconfirm, Select, Spin, Steps, Tag, Typography } from 'antd';
-import {
-  CloudUploadOutlined,
-  DeleteOutlined,
-  EditOutlined,
-  LinkOutlined,
-  PlusOutlined,
-  SaveOutlined,
-  SearchOutlined,
-} from '@ant-design/icons';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { useImmer } from 'use-immer';
+import { Button, Form, Input, Modal, Select, Spin, Steps, Typography } from 'antd';
+import { CloudUploadOutlined, EditOutlined, PlusOutlined, SearchOutlined } from '@ant-design/icons';
 import api from '../api';
 import { message } from '../ui/app-message';
 import { usePermission } from '../hooks/usePermission';
 import PermissionButton from './PermissionButton';
+import { useQuery } from '@tanstack/react-query';
+import { useApiMutation } from '../hooks/useApiMutation';
+import { validateResponse } from '../utils/validate';
+import { jinshujuRulesSchema } from '../api/schemas';
+import MatchStep from './MatchStep';
+import RuleEditor from './RuleEditor';
+import type {
+  JinshujuEntryRow,
+  JinshujuFormField,
+  MatchDecision,
+  MatchRule,
+  PreviewResponse,
+  StudentOption,
+} from './JinshujuMatchModal.types';
 
 const { Text } = Typography;
 
-// ── Types ──
-
-interface JinshujuEntryRow {
-  serialNumber: number;
-  name: string;
-  phone: string | null;
-  suggestedStudent: {
-    id: number;
-    name: string;
-    phone: string | null;
-    studentNo: string | null;
-  } | null;
-}
-
-interface StudentOption {
-  id: number;
-  name: string;
-  phone: string | null;
-  studentNo: string | null;
-}
-
-interface PreviewResponse {
-  success: boolean;
-  entries: JinshujuEntryRow[];
-  students: StudentOption[];
-}
-
-interface MatchRule {
-  id: number;
-  name: string;
-  formToken: string;
-  mappings: Record<string, string>;
-  createdAt: string;
-}
-
-interface JinshujuFormField {
-  key: string;
-  label: string;
-  type: string;
-}
-
-type MatchDecision =
-  | { action: 'match'; matchStudentId: number }
-  | { action: 'create'; createName: string; createPhone: string }
-  | { action: 'skip' };
-
-// ── Constants ──
-
-const ROW_HEIGHT = 72;
-const LEFT_WIDTH = 260;
-const GAP = 80;
-
-const STUDENT_FIELDS = [
-  { key: 'name', label: '姓名' },
-  { key: 'phone', label: '手机号' },
-  { key: 'idNumber', label: '身份证号' },
-  { key: 'gender', label: '性别' },
-  { key: 'ethnicity', label: '民族' },
-  { key: 'emergencyContact', label: '紧急联系人' },
-  { key: 'emergencyPhone', label: '紧急联系电话' },
-  { key: 'studentNo', label: '学号' },
-];
-
-// ── MatchSelector sub-component ──
-
-interface MatchSelectorProps {
-  entry: JinshujuEntryRow;
-  decision: MatchDecision | undefined;
-  studentOptions: StudentOption[];
-  onChange: (d: MatchDecision) => void;
-}
-
-const MatchSelector: React.FC<MatchSelectorProps> = ({
-  entry,
-  decision,
-  studentOptions,
-  onChange,
-}) => {
-  const action = decision?.action ?? 'skip';
-
-  if (action === 'match') {
-    const matchD = decision as { action: 'match'; matchStudentId: number };
-    const matchedStudent = studentOptions.find((s) => s.id === matchD.matchStudentId);
-    return (
-      <div style={{ display: 'flex', alignItems: 'center', gap: 8, width: '100%' }}>
-        <Tag color="blue" icon={<LinkOutlined />}>
-          已匹配
-        </Tag>
-        <Text style={{ flex: 1 }}>
-          {matchedStudent?.name ?? '未知'}
-          {matchedStudent?.studentNo && (
-            <Text type="secondary" style={{ fontSize: 12, marginLeft: 4 }}>
-              ({matchedStudent.studentNo})
-            </Text>
-          )}
-        </Text>
-        <Button size="small" type="link" danger onClick={() => onChange({ action: 'skip' })}>
-          取消
-        </Button>
-      </div>
-    );
-  }
-
-  if (action === 'create') {
-    const createD = decision as { action: 'create'; createName: string; createPhone: string };
-    return (
-      <div style={{ display: 'flex', alignItems: 'center', gap: 8, width: '100%' }}>
-        <Tag color="green" icon={<PlusOutlined />}>
-          将新建
-        </Tag>
-        <Input
-          size="small"
-          value={createD.createName}
-          placeholder="姓名"
-          style={{ width: 100 }}
-          onChange={(e) =>
-            onChange({
-              action: 'create',
-              createName: e.target.value,
-              createPhone: createD.createPhone,
-            })
-          }
-        />
-        <Input
-          size="small"
-          value={createD.createPhone}
-          placeholder="手机号"
-          style={{ width: 120 }}
-          onChange={(e) =>
-            onChange({
-              action: 'create',
-              createName: createD.createName,
-              createPhone: e.target.value,
-            })
-          }
-        />
-        <Button size="small" type="link" danger onClick={() => onChange({ action: 'skip' })}>
-          取消
-        </Button>
-      </div>
-    );
-  }
-
-  return (
-    <div style={{ display: 'flex', alignItems: 'center', gap: 8, width: '100%' }}>
-      <Select
-        showSearch
-        size="small"
-        placeholder="搜索学生…"
-        style={{ flex: 1 }}
-        value={undefined}
-        filterOption={(input, option) =>
-          ((option?.label as string) || '').toLowerCase().includes(input.toLowerCase())
-        }
-        options={studentOptions.map((s) => ({
-          value: s.id,
-          label: `${s.name}${s.phone ? ` (${s.phone})` : ''}${s.studentNo ? ` [${s.studentNo}]` : ''}`,
-        }))}
-        onChange={(studentId: number) => onChange({ action: 'match', matchStudentId: studentId })}
-      />
-      <Button
-        size="small"
-        type="dashed"
-        icon={<PlusOutlined />}
-        onClick={() =>
-          onChange({
-            action: 'create',
-            createName: entry.name || '',
-            createPhone: entry.phone || '',
-          })
-        }
-      >
-        新建
-      </Button>
-      <Button size="small" type="link" onClick={() => onChange({ action: 'skip' })}>
-        跳过
-      </Button>
-    </div>
-  );
-};
-
-// ── Rule Editor sub-component ──
-
-interface RuleEditorProps {
-  rule: MatchRule | null;
-  formToken: string;
-  fields: JinshujuFormField[];
-  onSave: () => void;
-  onDelete: (id: number) => void;
-  onCancel: () => void;
-}
-
-const RuleEditor: React.FC<RuleEditorProps> = ({
-  rule,
-  formToken,
-  fields,
-  onSave,
-  onDelete,
-  onCancel,
-}) => {
-  const [name, setName] = useState(rule?.name ?? '');
-  const [mappings, setMappings] = useState<Record<string, string>>(
-    rule?.mappings ?? { name: 'field_1', phone: 'field_2' },
-  );
-  const [saving, setSaving] = useState(false);
-
-  const handleSave = async () => {
-    if (!name.trim()) {
-      message.warning('请输入规则名称');
-      return;
-    }
-    setSaving(true);
-    try {
-      if (rule) {
-        await api.put(`/sync/jinshuju/rules/${rule.id}`, { name, mappings });
-      } else {
-        await api.post('/sync/jinshuju/rules', { name, formToken, mappings });
-      }
-      message.success('规则已保存');
-      onSave();
-    } catch (e: unknown) {
-      const err = e as { message?: string };
-      if (err?.message) message.error(err.message);
-    } finally {
-      setSaving(false);
-    }
-  };
-
-  return (
-    <div style={{ padding: '12px 0' }}>
-      <Input
-        placeholder="规则名称"
-        value={name}
-        onChange={(e) => setName(e.target.value)}
-        style={{ marginBottom: 12 }}
-      />
-      <Text type="secondary" style={{ display: 'block', marginBottom: 8 }}>
-        选择金数据字段映射到学生资料
-      </Text>
-      {STUDENT_FIELDS.map((sf) => (
-        <div
-          key={sf.key}
-          style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 6 }}
-        >
-          <Text style={{ width: 100, textAlign: 'right', fontSize: 13 }}>{sf.label}</Text>
-          <Text type="secondary" style={{ fontSize: 12 }}>
-            ←
-          </Text>
-          <Select
-            allowClear
-            showSearch
-            optionFilterProp="label"
-            placeholder="选择金数据字段"
-            value={mappings[sf.key]}
-            style={{ flex: 1 }}
-            options={fields.map((field) => ({
-              value: field.key,
-              label: `${field.label}（${field.key}）`,
-            }))}
-            onChange={(value) =>
-              setMappings((prev) => {
-                const next = { ...prev };
-                if (value) next[sf.key] = value;
-                else delete next[sf.key];
-                return next;
-              })
-            }
-          />
-        </div>
-      ))}
-      <div style={{ marginTop: 12, display: 'flex', gap: 8 }}>
-        <Button type="primary" icon={<SaveOutlined />} loading={saving} onClick={handleSave}>
-          保存
-        </Button>
-        {rule && (
-          <Popconfirm title="确定删除此规则？" onConfirm={() => onDelete(rule.id)}>
-            <Button danger icon={<DeleteOutlined />}>
-              删除
-            </Button>
-          </Popconfirm>
-        )}
-        <Button onClick={onCancel}>取消</Button>
-      </div>
-    </div>
-  );
-};
-
-// ── Main MatchModal ──
-
 interface MatchModalProps {
   open: boolean;
   onClose: () => void;
@@ -312,12 +30,12 @@ interface MatchModalProps {
 }
 
 const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplied }) => {
-  const { hasPermission } = usePermission();
+  const { hasPermission, hasAllPermissions, permissionsReady } = usePermission();
   const canTriggerSync = hasPermission('sync:trigger');
+  const canEnterModal = permissionsReady && hasAllPermissions('sync:read', 'sync:trigger');
   const [step, setStep] = useState<'connection' | 'rule' | 'match' | 'applying'>('connection');
   const [loading, setLoading] = useState(false);
   const [selectedRuleId, setSelectedRuleId] = useState<number | undefined>();
-  const [rules, setRules] = useState<MatchRule[]>([]);
   const [editingRule, setEditingRule] = useState<MatchRule | null>(null);
   const [showRuleEditor, setShowRuleEditor] = useState(false);
   const [credForm] = Form.useForm();
@@ -325,28 +43,38 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
 
   const [entries, setEntries] = useState<JinshujuEntryRow[]>([]);
   const [studentOptions, setStudentOptions] = useState<StudentOption[]>([]);
-  const [decisions, setDecisions] = useState<Map<number, MatchDecision>>(new Map());
+  const [decisions, setDecisions] = useImmer<Map<number, MatchDecision>>(new Map());
   const leftRef = useRef<HTMLDivElement>(null);
   const rightRef = useRef<HTMLDivElement>(null);
   const [formFields, setFormFields] = useState<JinshujuFormField[]>([]);
   const [formName, setFormName] = useState('');
   const [scrollTop, setScrollTop] = useState(0);
 
-  // Load rules on open
-  useEffect(() => {
-    if (open) loadRules();
-  }, [open]);
-
-  const loadRules = async () => {
-    try {
-      const res = await api.get<{ success: boolean; data: MatchRule[] }>('/sync/jinshuju/rules');
-      if (res.success) setRules(res.data);
-    } catch {
-      /* ignore */
-    }
-  };
+  const {
+    data: rules = [],
+    refetch: refetchRules,
+  } = useQuery<MatchRule[]>({
+    queryKey: ['sync', 'jinshuju', 'rules'],
+    enabled: open && canEnterModal,
+    queryFn: async () => {
+      try {
+        const res = await api.get<{ success: boolean; data: MatchRule[] }>(
+          '/sync/jinshuju/rules',
+        );
+        return res.success ? validateResponse<MatchRule[]>(jinshujuRulesSchema, res.data) : [];
+      } catch {
+        return [];
+      }
+    },
+  });
+  const loadRules = useCallback(() => refetchRules(), [refetchRules]);
+  const deleteRuleMutation = useApiMutation(
+    async (id: number) => api.delete(`/sync/jinshuju/rules/${id}`),
+    { invalidate: [['sync', 'jinshuju', 'rules']] },
+  );
 
   const handleConnectionNext = async () => {
+    if (!canTriggerSync) return;
     try {
       const values = await credForm.validateFields();
       setLoading(true);
@@ -366,6 +94,7 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
   };
 
   const handlePreview = async () => {
+    if (!canTriggerSync) return;
     try {
       const values = await credForm.validateFields();
       setLoading(true);
@@ -454,7 +183,9 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
 
   const getDecision = (serial: number): MatchDecision | undefined => decisions.get(serial);
   const setDecision = (serial: number, d: MatchDecision) =>
-    setDecisions((prev) => new Map(prev).set(serial, d));
+    setDecisions((draft) => {
+      draft.set(serial, d);
+    });
   const total = entries.length;
   const matched = [...decisions.values()].filter((d) => d.action !== 'skip').length;
 
@@ -549,11 +280,14 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
             loadRules();
           }}
           onDelete={async (id) => {
-            await api.delete(`/sync/jinshuju/rules/${id}`);
-            message.success('规则已删除');
-            if (selectedRuleId === id) setSelectedRuleId(undefined);
-            setShowRuleEditor(false);
-            loadRules();
+            try {
+              await deleteRuleMutation.mutateAsync(id);
+              message.success('规则已删除');
+              if (selectedRuleId === id) setSelectedRuleId(undefined);
+              setShowRuleEditor(false);
+            } catch {
+              // 错误提示由 useApiMutation 统一处理
+            }
           }}
           onCancel={() => setShowRuleEditor(false)}
         />
@@ -562,134 +296,37 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
   );
 
   const renderMatchStep = () => {
-    const svgHeight = entries.length * ROW_HEIGHT;
-    const lines: React.ReactNode[] = [];
-    entries.forEach((entry, i) => {
-      const y = i * ROW_HEIGHT + ROW_HEIGHT / 2;
-      const d = getDecision(entry.serialNumber);
-      const isMatched = d?.action === 'match';
-      const color = isMatched ? '#1677ff' : '#d9d9d9';
-      lines.push(
-        <line
-          key={entry.serialNumber}
-          x1={LEFT_WIDTH}
-          y1={y}
-          x2={LEFT_WIDTH + GAP}
-          y2={y}
-          stroke={color}
-          strokeWidth={isMatched ? 2 : 1}
-          strokeDasharray={isMatched ? undefined : '4 4'}
-          opacity={isMatched ? 0.7 : 0.3}
-        />,
-      );
-    });
-
     return (
-      <div style={{ position: 'relative' }}>
-        <div
-          style={{
-            marginBottom: 12,
-            display: 'flex',
-            justifyContent: 'space-between',
-            alignItems: 'center',
-          }}
-        >
-          <Text type="secondary">
-            共 {total} 条，已匹配 {matched} 条
-          </Text>
-          <Button size="small" onClick={() => setDecisions(new Map())}>
-            清除全部匹配
-          </Button>
-        </div>
-        <div style={{ display: 'flex', position: 'relative' }}>
-          <svg
-            style={{
-              position: 'absolute',
-              top: 0,
-              left: 0,
-              width: LEFT_WIDTH + GAP,
-              height: svgHeight,
-              pointerEvents: 'none',
-              zIndex: 1,
-            }}
-          >
-            {lines}
-          </svg>
-          <div
-            ref={leftRef}
-            onScroll={() => handleScroll('left')}
-            style={{ width: LEFT_WIDTH, maxHeight: 480, overflowY: 'auto', flexShrink: 0 }}
-          >
-            {entries.map((entry, i) => {
-              const d = getDecision(entry.serialNumber);
-              const isMatched = d?.action === 'match';
-              return (
-                <div
-                  key={entry.serialNumber}
-                  style={{
-                    height: ROW_HEIGHT,
-                    padding: '8px 12px',
-                    borderBottom: '1px solid #f0f0f0',
-                    display: 'flex',
-                    flexDirection: 'column',
-                    justifyContent: 'center',
-                    background: isMatched ? '#f6ffed' : i % 2 === 0 ? '#fafafa' : '#fff',
-                    borderLeft: isMatched ? '3px solid #1677ff' : '3px solid transparent',
-                  }}
-                >
-                  <Text strong style={{ fontSize: 13 }}>
-                    {entry.name || <Text type="secondary">无姓名</Text>}
-                  </Text>
-                  {entry.phone && (
-                    <Text type="secondary" style={{ fontSize: 12 }}>
-                      {entry.phone}
-                    </Text>
-                  )}
-                  <Text type="secondary" style={{ fontSize: 11 }}>
-                    #{entry.serialNumber}
-                  </Text>
-                </div>
-              );
-            })}
-          </div>
-          <div style={{ width: GAP, flexShrink: 0 }} />
-          <div
-            ref={rightRef}
-            onScroll={() => handleScroll('right')}
-            style={{ flex: 1, maxHeight: 480, overflowY: 'auto' }}
-          >
-            {entries.map((entry) => (
-              <div
-                key={entry.serialNumber}
-                style={{
-                  height: ROW_HEIGHT,
-                  padding: '8px 12px',
-                  borderBottom: '1px solid #f0f0f0',
-                  display: 'flex',
-                  alignItems: 'center',
-                  gap: 8,
-                }}
-              >
-                <MatchSelector
-                  entry={entry}
-                  decision={getDecision(entry.serialNumber)}
-                  studentOptions={studentOptions}
-                  onChange={(newD) => setDecision(entry.serialNumber, newD)}
-                />
-              </div>
-            ))}
-          </div>
-        </div>
-      </div>
+      <MatchStep
+        entries={entries}
+        studentOptions={studentOptions}
+        getDecision={getDecision}
+        onDecisionChange={setDecision}
+        onClear={() => setDecisions(new Map())}
+        leftRef={leftRef}
+        rightRef={rightRef}
+        onScroll={handleScroll}
+        total={total}
+        matched={matched}
+      />
     );
   };
 
+  const backCancelButtons = (onBack: () => void) => [
+    <Button key="back" onClick={onBack}>
+      上一步
+    </Button>,
+    <Button key="cancel" onClick={handleClose}>
+      取消
+    </Button>,
+  ];
+
   const currentStep = step === 'connection' ? 0 : step === 'rule' ? 1 : 2;
 
   return (
     <Modal
       title="同步金数据"
-      open={open}
+      open={open && canEnterModal}
       onCancel={handleClose}
       width={step === 'match' || step === 'applying' ? 900 : 640}
       maskClosable={false}
@@ -705,12 +342,7 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
             ]
           : step === 'rule'
             ? [
-                <Button key="back" onClick={() => setStep('connection')}>
-                  上一步
-                </Button>,
-                <Button key="cancel" onClick={handleClose}>
-                  取消
-                </Button>,
+                ...backCancelButtons(() => setStep('connection')),
                 <Button
                   key="next"
                   type="primary"
@@ -723,12 +355,7 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
               ]
             : step === 'match'
               ? [
-                  <Button key="back" onClick={() => setStep('rule')}>
-                    上一步
-                  </Button>,
-                  <Button key="cancel" onClick={handleClose}>
-                    取消
-                  </Button>,
+                  ...backCancelButtons(() => setStep('rule')),
                   canTriggerSync ? (
                     <PermissionButton
                       key="apply"
@@ -753,7 +380,7 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
       {step === 'rule' ? renderRuleStep() : null}
       {step === 'match' ? renderMatchStep() : null}
       {step === 'applying' ? (
-        <Spin tip="正在同步..." style={{ display: 'block', margin: '48px auto' }} />
+        <Spin description="正在同步..." style={{ display: 'block', margin: '48px auto' }} />
       ) : null}
     </Modal>
   );

apps/admin/src/components/JinshujuMatchModal.types.ts

@@ -0,0 +1,58 @@
+export interface JinshujuEntryRow {
+  serialNumber: number;
+  name: string;
+  phone: string | null;
+  suggestedStudent: {
+    id: number;
+    name: string;
+    phone: string | null;
+    studentNo: string | null;
+  } | null;
+}
+
+export interface StudentOption {
+  id: number;
+  name: string;
+  phone: string | null;
+  studentNo: string | null;
+}
+
+export interface PreviewResponse {
+  success: boolean;
+  entries: JinshujuEntryRow[];
+  students: StudentOption[];
+}
+
+export interface MatchRule {
+  id: number;
+  name: string;
+  formToken: string;
+  mappings: Record<string, string>;
+  createdAt: string;
+}
+
+export interface JinshujuFormField {
+  key: string;
+  label: string;
+  type: string;
+}
+
+export type MatchDecision =
+  | { action: 'match'; matchStudentId: number }
+  | { action: 'create'; createName: string; createPhone: string }
+  | { action: 'skip' };
+
+export const ROW_HEIGHT = 72;
+export const LEFT_WIDTH = 260;
+export const GAP = 80;
+
+export const STUDENT_FIELDS = [
+  { key: 'name', label: '姓名' },
+  { key: 'phone', label: '手机号' },
+  { key: 'idNumber', label: '身份证号' },
+  { key: 'gender', label: '性别' },
+  { key: 'ethnicity', label: '民族' },
+  { key: 'emergencyContact', label: '紧急联系人' },
+  { key: 'emergencyPhone', label: '紧急联系电话' },
+  { key: 'studentNo', label: '学号' },
+];

apps/admin/src/components/MatchSelector.tsx

@@ -0,0 +1,124 @@
+import React from 'react';
+import { Button, Input, Select, Tag, Typography } from 'antd';
+import { LinkOutlined, PlusOutlined } from '@ant-design/icons';
+import type { JinshujuEntryRow, MatchDecision, StudentOption } from './JinshujuMatchModal.types';
+
+const { Text } = Typography;
+
+interface MatchSelectorProps {
+  entry: JinshujuEntryRow;
+  decision: MatchDecision | undefined;
+  studentOptions: StudentOption[];
+  onChange: (d: MatchDecision) => void;
+}
+
+const MatchSelector: React.FC<MatchSelectorProps> = ({
+  entry,
+  decision,
+  studentOptions,
+  onChange,
+}) => {
+  const action = decision?.action ?? 'skip';
+
+  if (action === 'match') {
+    const matchD = decision as { action: 'match'; matchStudentId: number };
+    const matchedStudent = studentOptions.find((s) => s.id === matchD.matchStudentId);
+    return (
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8, width: '100%' }}>
+        <Tag color="blue" icon={<LinkOutlined />}>
+          已匹配
+        </Tag>
+        <Text style={{ flex: 1 }}>
+          {matchedStudent?.name ?? '未知'}
+          {matchedStudent?.studentNo && (
+            <Text type="secondary" style={{ fontSize: 12, marginLeft: 4 }}>
+              ({matchedStudent.studentNo})
+            </Text>
+          )}
+        </Text>
+        <Button size="small" type="link" danger onClick={() => onChange({ action: 'skip' })}>
+          取消
+        </Button>
+      </div>
+    );
+  }
+
+  if (action === 'create') {
+    const createD = decision as { action: 'create'; createName: string; createPhone: string };
+    return (
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8, width: '100%' }}>
+        <Tag color="green" icon={<PlusOutlined />}>
+          将新建
+        </Tag>
+        <Input
+          size="small"
+          value={createD.createName}
+          placeholder="姓名"
+          style={{ width: 100 }}
+          onChange={(e) =>
+            onChange({
+              action: 'create',
+              createName: e.target.value,
+              createPhone: createD.createPhone,
+            })
+          }
+        />
+        <Input
+          size="small"
+          value={createD.createPhone}
+          placeholder="手机号"
+          style={{ width: 120 }}
+          onChange={(e) =>
+            onChange({
+              action: 'create',
+              createName: createD.createName,
+              createPhone: e.target.value,
+            })
+          }
+        />
+        <Button size="small" type="link" danger onClick={() => onChange({ action: 'skip' })}>
+          取消
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 8, width: '100%' }}>
+      <Select
+        showSearch
+        size="small"
+        placeholder="搜索学生…"
+        style={{ flex: 1 }}
+        value={undefined}
+        filterOption={(input, option) =>
+          ((option?.label as string) || '').toLowerCase().includes(input.toLowerCase())
+        }
+        options={studentOptions.map((s) => ({
+          value: s.id,
+          label: `${s.name}${s.phone ? ` (${s.phone})` : ''}${s.studentNo ? ` [${s.studentNo}]` : ''}`,
+        }))}
+        onChange={(studentId: number) => onChange({ action: 'match', matchStudentId: studentId })}
+      />
+      <Button
+        size="small"
+        type="dashed"
+        icon={<PlusOutlined />}
+        onClick={() =>
+          onChange({
+            action: 'create',
+            createName: entry.name || '',
+            createPhone: entry.phone || '',
+          })
+        }
+      >
+        新建
+      </Button>
+      <Button size="small" type="link" onClick={() => onChange({ action: 'skip' })}>
+        跳过
+      </Button>
+    </div>
+  );
+};
+
+export default MatchSelector;

apps/admin/src/components/MatchStep.tsx

@@ -0,0 +1,156 @@
+import React from 'react';
+import { Button, Typography } from 'antd';
+import MatchSelector from './MatchSelector';
+import { GAP, LEFT_WIDTH, ROW_HEIGHT } from './JinshujuMatchModal.types';
+import type { JinshujuEntryRow, MatchDecision, StudentOption } from './JinshujuMatchModal.types';
+
+const { Text } = Typography;
+
+interface MatchStepProps {
+  entries: JinshujuEntryRow[];
+  studentOptions: StudentOption[];
+  getDecision: (serial: number) => MatchDecision | undefined;
+  onDecisionChange: (serial: number, d: MatchDecision) => void;
+  onClear: () => void;
+  leftRef: React.RefObject<HTMLDivElement | null>;
+  rightRef: React.RefObject<HTMLDivElement | null>;
+  onScroll: (source: 'left' | 'right') => void;
+  total: number;
+  matched: number;
+}
+
+const MatchStep: React.FC<MatchStepProps> = ({
+  entries,
+  studentOptions,
+  getDecision,
+  onDecisionChange,
+  onClear,
+  leftRef,
+  rightRef,
+  onScroll,
+  total,
+  matched,
+}) => {
+  const svgHeight = entries.length * ROW_HEIGHT;
+  const lines: React.ReactNode[] = [];
+  entries.forEach((entry, i) => {
+    const y = i * ROW_HEIGHT + ROW_HEIGHT / 2;
+    const d = getDecision(entry.serialNumber);
+    const isMatched = d?.action === 'match';
+    const color = isMatched ? '#1677ff' : '#d9d9d9';
+    lines.push(
+      <line
+        key={entry.serialNumber}
+        x1={LEFT_WIDTH}
+        y1={y}
+        x2={LEFT_WIDTH + GAP}
+        y2={y}
+        stroke={color}
+        strokeWidth={isMatched ? 2 : 1}
+        strokeDasharray={isMatched ? undefined : '4 4'}
+        opacity={isMatched ? 0.7 : 0.3}
+      />,
+    );
+  });
+
+  return (
+    <div style={{ position: 'relative' }}>
+      <div
+        style={{
+          marginBottom: 12,
+          display: 'flex',
+          justifyContent: 'space-between',
+          alignItems: 'center',
+        }}
+      >
+        <Text type="secondary">
+          共 {total} 条，已匹配 {matched} 条
+        </Text>
+        <Button size="small" onClick={onClear}>
+          清除全部匹配
+        </Button>
+      </div>
+      <div style={{ display: 'flex', position: 'relative' }}>
+        <svg
+          style={{
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            width: LEFT_WIDTH + GAP,
+            height: svgHeight,
+            pointerEvents: 'none',
+            zIndex: 1,
+          }}
+        >
+          {lines}
+        </svg>
+        <div
+          ref={leftRef}
+          onScroll={() => onScroll('left')}
+          style={{ width: LEFT_WIDTH, maxHeight: 480, overflowY: 'auto', flexShrink: 0 }}
+        >
+          {entries.map((entry, i) => {
+            const d = getDecision(entry.serialNumber);
+            const isMatched = d?.action === 'match';
+            return (
+              <div
+                key={entry.serialNumber}
+                style={{
+                  height: ROW_HEIGHT,
+                  padding: '8px 12px',
+                  borderBottom: '1px solid #f0f0f0',
+                  display: 'flex',
+                  flexDirection: 'column',
+                  justifyContent: 'center',
+                  background: isMatched ? '#f6ffed' : i % 2 === 0 ? '#fafafa' : '#fff',
+                  borderLeft: isMatched ? '3px solid #1677ff' : '3px solid transparent',
+                }}
+              >
+                <Text strong style={{ fontSize: 13 }}>
+                  {entry.name || <Text type="secondary">无姓名</Text>}
+                </Text>
+                {entry.phone && (
+                  <Text type="secondary" style={{ fontSize: 12 }}>
+                    {entry.phone}
+                  </Text>
+                )}
+                <Text type="secondary" style={{ fontSize: 11 }}>
+                  #{entry.serialNumber}
+                </Text>
+              </div>
+            );
+          })}
+        </div>
+        <div style={{ width: GAP, flexShrink: 0 }} />
+        <div
+          ref={rightRef}
+          onScroll={() => onScroll('right')}
+          style={{ flex: 1, maxHeight: 480, overflowY: 'auto' }}
+        >
+          {entries.map((entry) => (
+            <div
+              key={entry.serialNumber}
+              style={{
+                height: ROW_HEIGHT,
+                padding: '8px 12px',
+                borderBottom: '1px solid #f0f0f0',
+                display: 'flex',
+                alignItems: 'center',
+                gap: 8,
+              }}
+            >
+              <MatchSelector
+                entry={entry}
+                decision={getDecision(entry.serialNumber)}
+                studentOptions={studentOptions}
+                onChange={(newD) => onDecisionChange(entry.serialNumber, newD)}
+              />
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default MatchStep;

apps/admin/src/components/NotificationBell.tsx

@@ -1,9 +1,12 @@
 import React, { useState, useEffect, useRef } from 'react';
 import { Badge, Popover, Button, List, Typography, Empty } from 'antd';
 import { BellOutlined } from '@ant-design/icons';
-import { useNavigate } from 'react-router-dom';
+import { useNavigate } from 'react-router';
+import dayjs from 'dayjs';
+import { useInterval } from 'usehooks-ts';
 import api from '../api';
 import { formatNotificationText, notificationTypeLabels } from '../utils/notification-display';
+import { useUserStore } from '../store/user/userStore';
 
 interface NotificationItem {
   id: number;
@@ -16,25 +19,19 @@ interface NotificationItem {
 }
 
 function timeAgo(dateStr: string): string {
-  const diff = Date.now() - new Date(dateStr).getTime();
-  const mins = Math.floor(diff / 60000);
-  if (mins < 1) return '刚刚';
-  if (mins < 60) return `${mins}分钟前`;
-  const hours = Math.floor(mins / 60);
-  if (hours < 24) return `${hours}小时前`;
-  const days = Math.floor(hours / 24);
-  return `${days}天前`;
+  return dayjs(dateStr).fromNow();
 }
 
 const NotificationBell: React.FC = () => {
   const [unreadCount, setUnreadCount] = useState(0);
   const [notifications, setNotifications] = useState<NotificationItem[]>([]);
   const [open, setOpen] = useState(false);
+  const [sseDown, setSseDown] = useState(false);
   const navigate = useNavigate();
 
   const fetchNotifications = async () => {
     try {
-      const data = (await api.get('/notifications?limit=20')) as unknown as NotificationItem[];
+      const data = await api.get<NotificationItem[]>('/notifications?limit=20');
       setNotifications(data);
     } catch {
       /* ignore */
@@ -43,7 +40,7 @@ const NotificationBell: React.FC = () => {
 
   const fetchUnread = async () => {
     try {
-      const data = (await api.get('/notifications/unread-count')) as unknown as { count: number };
+      const data = await api.get<{ count: number }>('/notifications/unread-count');
       setUnreadCount(data.count);
     } catch {
       /* ignore */
@@ -51,14 +48,17 @@ const NotificationBell: React.FC = () => {
   };
   const openRef = useRef(open);
   openRef.current = open;
-  const retryRef = useRef<number | null>(null);
+  useInterval(() => {
+    void fetchUnread();
+  }, sseDown ? 60_000 : null);
 
   // SSE connection — decoupled from popover open state
   useEffect(() => {
     fetchUnread();
-    const token = localStorage.getItem('token');
+    const token = useUserStore.getState().token;
     if (!token) return;
     const es = new EventSource(`/api/notifications/stream?token=${encodeURIComponent(token)}`);
+    es.onopen = () => setSseDown(false);
     es.onmessage = (event) => {
       try {
         JSON.parse(event.data);
@@ -69,14 +69,12 @@ const NotificationBell: React.FC = () => {
       }
     };
     es.onerror = () => {
-      es.close();
-      if (retryRef.current !== null) clearInterval(retryRef.current);
-      retryRef.current = window.setInterval(fetchUnread, 60_000);
+      // 不主动关闭：EventSource 会自动重连，主动关闭会导致一次超时后实时通知永久断流
+      setSseDown(true);
     };
     return () => {
       es.close();
-      clearInterval(retryRef.current ?? undefined);
-      retryRef.current = null;
+      setSseDown(false);
     };
   }, []);
 

apps/admin/src/components/PermissionButton.tsx

@@ -1,6 +1,5 @@
 import React from 'react';
-import { Button } from 'antd';
-import type { ButtonProps } from 'antd';
+import { Button, type ButtonProps } from 'antd';
 import { usePermission } from '../hooks/usePermission';
 
 interface PermissionButtonProps extends ButtonProps {

apps/admin/src/components/PermissionRoute.tsx

@@ -1,8 +1,9 @@
 import React from 'react';
 import { Result, Button, Spin } from 'antd';
-import { useNavigate } from 'react-router-dom';
+import { useNavigate } from 'react-router';
 import { findRoleAwareLandingPath } from '../auth/menu-policy';
 import { usePermission } from '../hooks/usePermission';
+import { useUserStore } from '../store/user/userStore';
 
 interface PermissionRouteProps {
   permission: string;
@@ -11,17 +12,12 @@ interface PermissionRouteProps {
 
 const PermissionRoute: React.FC<PermissionRouteProps> = ({ permission, children }) => {
   const { permissions, permissionsReady, hasPermission } = usePermission();
+  const roles = useUserStore((state) => state.user?.roles ?? []);
   const navigate = useNavigate();
   if (!permissionsReady) {
     return <Spin size="large" style={{ display: 'block', margin: '80px auto' }} />;
   }
   if (!hasPermission(permission)) {
-    let roles: string[] = [];
-    try {
-      roles = JSON.parse(localStorage.getItem('user') || '{}').roles || [];
-    } catch {
-      roles = [];
-    }
     const firstPath = findRoleAwareLandingPath(roles, permissions);
     return (
       <Result

apps/admin/src/components/RouteDock/index.tsx

@@ -1,6 +1,12 @@
-import React, { useEffect, useMemo, useState } from 'react';
-import type { DragEndEvent } from '@dnd-kit/core';
-import { closestCenter, DndContext, PointerSensor, useSensor, useSensors } from '@dnd-kit/core';
+import React, { useEffect, useMemo } from 'react';
+import {
+  closestCenter,
+  DndContext,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+} from '@dnd-kit/core';
 import {
   arrayMove,
   horizontalListSortingStrategy,
@@ -8,17 +14,10 @@ import {
   useSortable,
 } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
-import { Tabs } from 'antd';
-import type { TabsProps } from 'antd';
-import type { Location } from 'react-router-dom';
+import { Tabs, type TabsProps } from 'antd';
+import type { Location } from 'react-router';
 import type { AppMenuItem } from '../../auth/menu-policy';
-
-const STORAGE_KEY = 'gongxue-route-dock';
-
-interface DockTab {
-  key: string;
-  label: string;
-}
+import { useAppStore } from '../../store';
 
 interface RouteDockProps {
   location: Location;
@@ -50,19 +49,6 @@ function getRouteLabel(items: readonly AppMenuItem[], pathname: string): string
   return pathname === '/' ? '首页' : '页面';
 }
 
-function readStoredTabs(): DockTab[] {
-  try {
-    const parsed = JSON.parse(localStorage.getItem(STORAGE_KEY) || '[]');
-    if (!Array.isArray(parsed)) return [];
-    return parsed.filter(
-      (tab): tab is DockTab =>
-        typeof tab?.key === 'string' && tab.key.startsWith('/') && typeof tab?.label === 'string',
-    );
-  } catch {
-    return [];
-  }
-}
-
 const DraggableTabNode: React.FC<Readonly<DraggableTabNodeProps>> = ({ ...props }) => {
   const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
     id: props['data-node-key'],
@@ -87,28 +73,20 @@ const DraggableTabNode: React.FC<Readonly<DraggableTabNodeProps>> = ({ ...props
 
 const RouteDock: React.FC<RouteDockProps> = ({ location, menuItems, onNavigate, draggable }) => {
   const activeKey = `${location.pathname}${location.search}`;
-  const [tabs, setTabs] = useState<DockTab[]>(() => {
-    const storedTabs = readStoredTabs();
-    if (location.pathname === '/') return storedTabs;
-    if (storedTabs.some((tab) => tab.key === activeKey)) return storedTabs;
-    return [...storedTabs, { key: activeKey, label: getRouteLabel(menuItems, location.pathname) }];
-  });
+  const tabs = useAppStore((state) => state.routeDockTabs);
+  const setRouteDockTabs = useAppStore((state) => state.setRouteDockTabs);
   const sensors = useSensors(useSensor(PointerSensor, { activationConstraint: { distance: 8 } }));
 
   useEffect(() => {
     if (location.pathname === '/') return;
-    setTabs((currentTabs) => {
+    setRouteDockTabs((currentTabs) => {
       const label = getRouteLabel(menuItems, location.pathname);
       const existing = currentTabs.find((tab) => tab.key === activeKey);
       if (!existing) return [...currentTabs, { key: activeKey, label }];
       if (existing.label === label) return currentTabs;
       return currentTabs.map((tab) => (tab.key === activeKey ? { ...tab, label } : tab));
     });
-  }, [activeKey, location.pathname, menuItems]);
-
-  useEffect(() => {
-    localStorage.setItem(STORAGE_KEY, JSON.stringify(tabs));
-  }, [tabs]);
+  }, [activeKey, location.pathname, menuItems, setRouteDockTabs]);
 
   const tabItems = useMemo<NonNullable<TabsProps['items']>>(
     () =>
@@ -124,7 +102,7 @@ const RouteDock: React.FC<RouteDockProps> = ({ location, menuItems, onNavigate,
     const targetIndex = tabs.findIndex((tab) => tab.key === targetKey);
     if (targetIndex < 0 || tabs.length === 1) return;
     const nextTabs = tabs.filter((tab) => tab.key !== targetKey);
-    setTabs(nextTabs);
+    setRouteDockTabs(nextTabs);
     if (targetKey === activeKey) {
       const nextActiveTab = nextTabs[Math.min(targetIndex, nextTabs.length - 1)];
       if (nextActiveTab) onNavigate(nextActiveTab.key);
@@ -133,7 +111,7 @@ const RouteDock: React.FC<RouteDockProps> = ({ location, menuItems, onNavigate,
 
   const handleDragEnd = ({ active, over }: DragEndEvent) => {
     if (!over || active.id === over.id) return;
-    setTabs((currentTabs) => {
+    setRouteDockTabs((currentTabs) => {
       const activeIndex = currentTabs.findIndex((tab) => tab.key === active.id);
       const overIndex = currentTabs.findIndex((tab) => tab.key === over.id);
       return activeIndex < 0 || overIndex < 0

apps/admin/src/components/RouteKeeper.integration.test.tsx

@@ -0,0 +1,96 @@
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { MemoryRouter, Route, Routes, useNavigate } from 'react-router';
+import { afterEach, describe, expect, it } from 'vitest';
+import { RouteKeeper } from './RouteKeeper';
+
+let container: HTMLDivElement | null = null;
+let root: ReturnType<typeof createRoot> | null = null;
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  container?.remove();
+  root = null;
+  container = null;
+});
+
+function PageA() {
+  const navigate = useNavigate();
+  return (
+    <div>
+      <input data-testid="input-a" aria-label="A 输入" />
+      <button data-testid="go-b" onClick={() => navigate('/b')}>
+        去B
+      </button>
+    </div>
+  );
+}
+
+function PageB() {
+  const navigate = useNavigate();
+  return (
+    <div>
+      <input data-testid="input-b" aria-label="B 输入" />
+      <button data-testid="go-a" onClick={() => navigate('/')}>
+        去A
+      </button>
+    </div>
+  );
+}
+
+function Harness() {
+  return (
+    <MemoryRouter initialEntries={['/']}>
+      <Routes>
+        <Route path="/" element={<RouteKeeper />}>
+          <Route index element={<PageA />} />
+          <Route path="b" element={<PageB />} />
+        </Route>
+      </Routes>
+    </MemoryRouter>
+  );
+}
+
+function type(target: HTMLInputElement, value: string) {
+  const setter = Object.getOwnPropertyDescriptor(
+    window.HTMLInputElement.prototype,
+    'value',
+  )?.set;
+  setter?.call(target, value);
+  target.dispatchEvent(new Event('input', { bubbles: true }));
+}
+
+describe('RouteKeeper', () => {
+  it('keeps page instances and input values alive across navigation', async () => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    await act(async () => root?.render(<Harness />));
+
+    const inputA = document.querySelector('[data-testid="input-a"]') as HTMLInputElement;
+    expect(inputA).not.toBeNull();
+    await act(async () => type(inputA, '待保存的学生姓名'));
+
+    await act(async () => {
+      (document.querySelector('[data-testid="go-b"]') as HTMLButtonElement).click();
+    });
+    const inputB = document.querySelector('[data-testid="input-b"]') as HTMLInputElement;
+    expect(inputB).not.toBeNull();
+    await act(async () => type(inputB, '待保存的宿舍号'));
+
+    await act(async () => {
+      (document.querySelector('[data-testid="go-a"]') as HTMLButtonElement).click();
+    });
+
+    const keptA = document.querySelector('[data-testid="input-a"]') as HTMLInputElement;
+    expect(keptA).not.toBeNull();
+    expect(keptA.value).toBe('待保存的学生姓名');
+    const keptB = document.querySelector('[data-testid="input-b"]') as HTMLInputElement;
+    expect(keptB.value).toBe('待保存的宿舍号');
+
+    const pages = document.querySelectorAll('.route-keeper-page');
+    expect(pages.length).toBe(2);
+    const hidden = pages[1] as HTMLElement;
+    expect(hidden.style.display).toBe('none');
+  });
+});

apps/admin/src/components/RouteKeeper.tsx

@@ -0,0 +1,43 @@
+import React, { useRef } from 'react';
+import { useLocation, useOutlet } from 'react-router';
+
+const MAX_CACHED_PAGES = 30;
+
+/**
+ * 路由保活：切换页面时保留已访问页面的组件实例（输入、滚动、弹窗状态不丢失）。
+ * 隐藏页面仍挂载在 DOM 中，仅通过 display:none 隐藏。
+ */
+export const RouteKeeper: React.FC = () => {
+  const location = useLocation();
+  const outlet = useOutlet();
+  const cacheRef = useRef<Map<string, React.ReactNode>>(new Map());
+  const orderRef = useRef<string[]>([]);
+  // 仅以 pathname 作为缓存键：页面内部通过 URL 参数同步状态时不会
+  // 产生第二个实例，切回时也不会因此重挂载。
+  const pageKey = location.pathname;
+
+  if (outlet && !cacheRef.current.has(pageKey)) {
+    cacheRef.current.set(pageKey, outlet);
+    orderRef.current.push(pageKey);
+    if (orderRef.current.length > MAX_CACHED_PAGES) {
+      const oldest = orderRef.current.shift();
+      if (oldest && oldest !== pageKey) cacheRef.current.delete(oldest);
+    }
+  }
+
+  return (
+    <>
+      {Array.from(cacheRef.current.entries()).map(([key, node]) => (
+        <div
+          key={key}
+          className="route-keeper-page"
+          style={{ display: key === pageKey ? undefined : 'none' }}
+        >
+          {node}
+        </div>
+      ))}
+    </>
+  );
+};
+
+export default RouteKeeper;

apps/admin/src/components/RuleEditor.tsx

@@ -0,0 +1,123 @@
+import React, { useState } from 'react';
+import { Button, Input, Popconfirm, Select, Typography } from 'antd';
+import { DeleteOutlined, SaveOutlined } from '@ant-design/icons';
+import api from '../api';
+import { message } from '../ui/app-message';
+import { useApiMutation } from '../hooks/useApiMutation';
+import { STUDENT_FIELDS } from './JinshujuMatchModal.types';
+import type { JinshujuFormField, MatchRule } from './JinshujuMatchModal.types';
+
+const { Text } = Typography;
+
+interface RuleEditorProps {
+  rule: MatchRule | null;
+  formToken: string;
+  fields: JinshujuFormField[];
+  onSave: () => void;
+  onDelete: (id: number) => void;
+  onCancel: () => void;
+}
+
+const RuleEditor: React.FC<RuleEditorProps> = ({
+  rule,
+  formToken,
+  fields,
+  onSave,
+  onDelete,
+  onCancel,
+}) => {
+  const [name, setName] = useState(rule?.name ?? '');
+  const [mappings, setMappings] = useState<Record<string, string>>(
+    rule?.mappings ?? { name: 'field_1', phone: 'field_2' },
+  );
+  const [saving, setSaving] = useState(false);
+
+  const saveMutation = useApiMutation(
+    async (payload: { name: string; mappings: Record<string, string> }) =>
+      rule
+        ? api.put(`/sync/jinshuju/rules/${rule.id}`, payload)
+        : api.post('/sync/jinshuju/rules', { ...payload, formToken }),
+    {
+      invalidate: [['sync', 'jinshuju', 'rules']],
+      onSuccess: () => {
+        message.success('规则已保存');
+        onSave();
+      },
+    },
+  );
+
+  const handleSave = async () => {
+    if (!name.trim()) {
+      message.warning('请输入规则名称');
+      return;
+    }
+    setSaving(true);
+    try {
+      await saveMutation.mutateAsync({ name, mappings });
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <div style={{ padding: '12px 0' }}>
+      <Input
+        placeholder="规则名称"
+        value={name}
+        onChange={(e) => setName(e.target.value)}
+        style={{ marginBottom: 12 }}
+      />
+      <Text type="secondary" style={{ display: 'block', marginBottom: 8 }}>
+        选择金数据字段映射到学生资料
+      </Text>
+      {STUDENT_FIELDS.map((sf) => (
+        <div
+          key={sf.key}
+          style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 6 }}
+        >
+          <Text style={{ width: 100, textAlign: 'right', fontSize: 13 }}>{sf.label}</Text>
+          <Text type="secondary" style={{ fontSize: 12 }}>
+            ←
+          </Text>
+          <Select
+            allowClear
+            showSearch
+            optionFilterProp="label"
+            placeholder="选择金数据字段"
+            value={mappings[sf.key]}
+            style={{ flex: 1 }}
+            options={fields.map((field) => ({
+              value: field.key,
+              label: `${field.label}（${field.key}）`,
+            }))}
+            onChange={(value) =>
+              setMappings((prev) => {
+                const next = { ...prev };
+                if (value) next[sf.key] = value;
+                else delete next[sf.key];
+                return next;
+              })
+            }
+          />
+        </div>
+      ))}
+      <div style={{ marginTop: 12, display: 'flex', gap: 8 }}>
+        <Button type="primary" icon={<SaveOutlined />} loading={saving} onClick={handleSave}>
+          保存
+        </Button>
+        {rule && (
+          <Popconfirm title="确定删除此规则？" onConfirm={() => onDelete(rule.id)}>
+            <Button danger icon={<DeleteOutlined />}>
+              删除
+            </Button>
+          </Popconfirm>
+        )}
+        <Button onClick={onCancel}>取消</Button>
+      </div>
+    </div>
+  );
+};
+
+export default RuleEditor;

apps/admin/src/components/StudentProfileContent/AttachmentsTab.tsx

@@ -0,0 +1,156 @@
+import React, { useState } from 'react';
+import { App, Button, Popconfirm, Space, Table, Upload } from 'antd';
+import type { ColumnsType } from 'antd/es/table';
+import { EyeOutlined, InboxOutlined, UploadOutlined } from '@ant-design/icons';
+import api from '../../api';
+import { message } from '../../ui/app-message';
+import { useApiMutation } from '../../hooks/useApiMutation';
+import { usePermission } from '../../hooks/usePermission';
+import { getErrorMessage } from '../../utils/error';
+import { ATTACHMENT_CATEGORY_OPTIONS, formatFileSize } from './shared';
+import type { AttachmentRecord, TabProps } from './shared';
+
+export const AttachmentsTab: React.FC<TabProps & { data: AttachmentRecord[] }> = ({
+  data,
+  studentId,
+}) => {
+  const { modal } = App.useApp();
+  const { hasPermission } = usePermission();
+  const canPurgeArchive = hasPermission('archive:purge');
+  const [uploading, setUploading] = useState(false);
+
+  const deleteAttachmentMutation = useApiMutation(
+    async (attachmentId: number) => api.delete(`/archive/attachments/${attachmentId}`),
+    { invalidate: [['archive', studentId]] },
+  );
+  const purgeAttachmentMutation = useApiMutation(
+    async (id: number) => api.delete(`/archive/attachments/${id}/permanent`),
+    { invalidate: [['archive', studentId]] },
+  );
+  const uploadAttachmentMutation = useApiMutation(
+    async (formData: FormData) =>
+      api.post(`/archive/${studentId}/attachments`, formData, {
+        headers: { 'Content-Type': 'multipart/form-data' },
+      }),
+    { invalidate: [['archive', studentId]] },
+  );
+
+  const handleDelete = async (attachmentId: number) => {
+    try {
+      await deleteAttachmentMutation.mutateAsync(attachmentId);
+      message.success('已归档');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    }
+  };
+
+  const handlePurge = (record: AttachmentRecord) => {
+    modal.confirm({
+      title: `永久删除附件「${record.fileName}」？`,
+      content: '删除后不可恢复，磁盘上的附件文件将被清除。确定继续？',
+      okText: '永久删除',
+      okButtonProps: { danger: true },
+      cancelText: '取消',
+      onOk: async () => {
+        try {
+          await purgeAttachmentMutation.mutateAsync(record.id);
+          message.success('已永久删除（不可恢复）');
+        } catch {
+          // 错误提示由 useApiMutation 统一处理
+        }
+      },
+    });
+  };
+
+  const columns: ColumnsType<AttachmentRecord> = [
+    {
+      title: '类别',
+      dataIndex: 'category',
+      render: (v: string) => ATTACHMENT_CATEGORY_OPTIONS.find((o) => o.value === v)?.label || v,
+    },
+    { title: '文件名', dataIndex: 'fileName' },
+    { title: '大小', dataIndex: 'fileSize', render: formatFileSize },
+    {
+      title: '操作',
+      render: (_: unknown, record: AttachmentRecord) => (
+        <Space>
+          <Button
+            size="small"
+            icon={<EyeOutlined />}
+            onClick={async () => {
+              try {
+                const blob = await api.get<Blob>(`/archive/${studentId}/attachments/${record.id}`, {
+                  responseType: 'blob',
+                });
+                const url = URL.createObjectURL(blob);
+                window.open(url, '_blank');
+                setTimeout(() => URL.revokeObjectURL(url), 60_000);
+              } catch (e: unknown) {
+                message.error(getErrorMessage(e, '查看失败'));
+              }
+            }}
+          >
+            查看
+          </Button>
+          {hasPermission('student:edit') && record.status !== 'archived' ? (
+            <Popconfirm title="确定归档该附件？" onConfirm={() => handleDelete(record.id)}>
+              <Button size="small" danger icon={<InboxOutlined />}>
+                归档
+              </Button>
+            </Popconfirm>
+          ) : null}
+          {record.status === 'archived' && canPurgeArchive ? (
+            <Button size="small" danger type="link" onClick={() => handlePurge(record)}>
+              删除
+            </Button>
+          ) : null}
+        </Space>
+      ),
+    },
+  ];
+
+  return (
+    <div>
+      {hasPermission('student:edit') ? (
+        <Upload
+          showUploadList={false}
+          customRequest={async (options) => {
+            const formData = new FormData();
+            formData.append(
+              'file',
+              options.file instanceof File
+                ? options.file
+                : new File([options.file as Blob], 'attachment'),
+            );
+            setUploading(true);
+            try {
+              await uploadAttachmentMutation.mutateAsync(formData);
+              message.success('上传成功');
+              options.onSuccess?.({});
+            } catch (e) {
+              options.onError?.(e instanceof Error ? e : new Error('上传失败'));
+            } finally {
+              setUploading(false);
+            }
+          }}
+        >
+          <Button icon={<UploadOutlined />} loading={uploading}>
+            上传附件
+          </Button>
+        </Upload>
+      ) : null}
+      <Table<AttachmentRecord>
+        columns={columns}
+        dataSource={data}
+        rowKey="id"
+        rowClassName={(record) => (record.status === 'archived' ? 'archived-row' : '')}
+        pagination={{
+          defaultPageSize: 15,
+          showSizeChanger: true,
+          pageSizeOptions: [15, 30, 50],
+        }}
+        style={{ marginTop: 16 }}
+      />
+    </div>
+  );
+};

apps/admin/src/components/StudentProfileContent/EditableArchiveCell.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import EditableCell from '../EditableCell';
+
+/**
+ * 学生档案模块统一的可编辑单元格：
+ * 固定 student:edit 权限，配合各 Tab 的 saveCell 使用。
+ */
+export const EditableArchiveCell = <R extends { id: number }>({
+  value,
+  field,
+  record,
+  editor,
+  min,
+  max,
+  required,
+  options,
+  onSave,
+  children,
+}: {
+  value: unknown;
+  field: string;
+  record: R;
+  editor?: React.ComponentProps<typeof EditableCell>['editor'];
+  min?: number;
+  max?: number;
+  required?: boolean;
+  options?: Array<{ value: string | number; label: string }>;
+  onSave: (record: R, field: string, value: unknown) => Promise<void> | void;
+  children?: React.ReactNode;
+}) => (
+  <EditableCell
+    value={value}
+    editor={editor}
+    min={min}
+    max={max}
+    required={required}
+    options={options}
+    permission="student:edit"
+    onSave={async (next) => {
+      await onSave(record, field, next);
+    }}
+  >
+    {children ?? String(value ?? '-')}
+  </EditableCell>
+);

apps/admin/src/components/StudentProfileContent/EnrollmentsTab.tsx

@@ -0,0 +1,260 @@
+import React, { useState } from 'react';
+import { App, Button, DatePicker, Form, Input, Modal, Select, Table, Tag } from 'antd';
+import type { ColumnsType } from 'antd/es/table';
+import { PlusOutlined } from '@ant-design/icons';
+import api from '../../api';
+import { message } from '../../ui/app-message';
+import { useApiMutation } from '../../hooks/useApiMutation';
+import { usePermission } from '../../hooks/usePermission';
+import PermissionButton from '../PermissionButton';
+import { EditableArchiveCell } from './EditableArchiveCell';
+import { CLASS_TYPE_OPTIONS, COURSE_CATEGORY_OPTIONS, ENROLLMENT_STATUS_MAP, formatEnrollmentDisplayName, getClassTypeLabel, getCourseCategoryLabel, getEnrollmentStatus } from './shared';
+import type { EnrollmentRecord, TabProps } from './shared';
+
+const ENROLLMENT_FIELDS = {
+  courseCategory: 'courseCategory',
+  classType: 'classType',
+  className: 'className',
+  headTeacher: 'headTeacher',
+  subjectTeacher: 'subjectTeacher',
+  startDate: 'startDate',
+  endDate: 'endDate',
+  status: 'status',
+} as const;
+
+export const EnrollmentsTab: React.FC<TabProps & { data: EnrollmentRecord[] }> = ({
+  data,
+  studentId,
+}) => {
+  const { modal } = App.useApp();
+  const { hasPermission } = usePermission();
+  const canPurgeArchive = hasPermission('archive:purge');
+  const [modalOpen, setModalOpen] = useState(false);
+  const [form] = Form.useForm();
+  const [saving, setSaving] = useState(false);
+
+  const addEnrollmentMutation = useApiMutation(
+    async (payload: Record<string, unknown>) =>
+      api.post(`/archive/${studentId}/enrollments`, payload),
+    { invalidate: [['archive', studentId]] },
+  );
+  const saveEnrollmentCellMutation = useApiMutation(
+    async ({ id, field, value }: { id: number; field: string; value: unknown }) =>
+      api.put(`/archive/enrollments/${id}`, { [field]: value }),
+    { invalidate: [['archive', studentId]] },
+  );
+  const purgeEnrollmentMutation = useApiMutation(
+    async (id: number) => api.delete(`/archive/enrollments/${id}/permanent`),
+    { invalidate: [['archive', studentId]] },
+  );
+
+  const handleAdd = async () => {
+    try {
+      const values = await form.validateFields();
+      setSaving(true);
+      await addEnrollmentMutation.mutateAsync({
+        ...values,
+        startDate: values.startDate?.format('YYYY-MM-DD'),
+        endDate: values.endDate?.format('YYYY-MM-DD'),
+      });
+      message.success('报读记录已添加');
+      setModalOpen(false);
+      form.resetFields();
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const saveCell = async (record: EnrollmentRecord, field: string, value: unknown) => {
+    try {
+      await saveEnrollmentCellMutation.mutateAsync({ id: record.id, field, value });
+      message.success('报读记录已保存');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    }
+  };
+
+  const handlePurge = (record: EnrollmentRecord) => {
+    modal.confirm({
+      title: `永久删除报读记录（${formatEnrollmentDisplayName(record)}）？`,
+      content: '删除后不可恢复，被考试成绩引用时将无法删除。确定继续？',
+      okText: '永久删除',
+      okButtonProps: { danger: true },
+      cancelText: '取消',
+      onOk: async () => {
+        try {
+          await purgeEnrollmentMutation.mutateAsync(record.id);
+          message.success('已永久删除（不可恢复）');
+        } catch {
+          // 错误提示由 useApiMutation 统一处理
+        }
+      },
+    });
+  };
+
+  const columns: ColumnsType<EnrollmentRecord> = [
+    {
+      title: '课程类别',
+      dataIndex: 'courseCategory',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={ENROLLMENT_FIELDS.courseCategory} record={r} editor="select"           options={COURSE_CATEGORY_OPTIONS} onSave={saveCell}>
+          {getCourseCategoryLabel(v)}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '班型',
+      dataIndex: 'classType',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={ENROLLMENT_FIELDS.classType} record={r} editor="select"           options={CLASS_TYPE_OPTIONS} onSave={saveCell}>
+          {getClassTypeLabel(v)}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '班级名称',
+      dataIndex: 'className',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={ENROLLMENT_FIELDS.className} record={r} onSave={saveCell}>
+          {v || '-'}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '班主任',
+      dataIndex: 'headTeacher',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={ENROLLMENT_FIELDS.headTeacher} record={r} onSave={saveCell}>
+          {v || '-'}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '任课教师',
+      dataIndex: 'subjectTeacher',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={ENROLLMENT_FIELDS.subjectTeacher} record={r} onSave={saveCell}>
+          {v || '-'}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '开始日期',
+      dataIndex: 'startDate',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={ENROLLMENT_FIELDS.startDate} record={r} editor="date" onSave={saveCell}>
+          {v || '-'}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '结束日期',
+      dataIndex: 'endDate',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={ENROLLMENT_FIELDS.endDate} record={r} editor="date" onSave={saveCell}>
+          {v || '-'}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '状态',
+      dataIndex: 'status',
+      render: (v: string, r) => {
+        const status = getEnrollmentStatus(v);
+        return (
+          <EditableArchiveCell
+            value={v}
+            field={ENROLLMENT_FIELDS.status}
+            record={r}
+            editor="select"
+            options={Object.entries(ENROLLMENT_STATUS_MAP).map(([value, item]) => ({
+              value,
+              label: item.text,
+            }))}
+            onSave={saveCell}
+          >
+            <Tag color={status.color}>{status.text}</Tag>
+          </EditableArchiveCell>
+        );
+      },
+    },
+    {
+      title: '操作',
+      render: (_: unknown, r: EnrollmentRecord) =>
+        r.status === 'archived' && canPurgeArchive ? (
+          <Button size="small" danger type="link" onClick={() => handlePurge(r)}>
+            删除
+          </Button>
+        ) : null,
+    },
+  ];
+
+  return (
+    <div>
+      <PermissionButton
+        permission="student:edit"
+        icon={<PlusOutlined />}
+        type="primary"
+        onClick={() => {
+          form.resetFields();
+          setModalOpen(true);
+        }}
+        style={{ marginBottom: 16 }}
+      >
+        添加报读记录
+      </PermissionButton>
+      <Table<EnrollmentRecord>
+        columns={columns}
+        dataSource={data}
+        rowKey="id"
+        rowClassName={(record) => (record.status === 'archived' ? 'archived-row' : '')}
+        pagination={{
+          defaultPageSize: 15,
+          showSizeChanger: true,
+          pageSizeOptions: [15, 30, 50],
+        }}
+      />
+      <Modal
+        title="添加报读记录"
+        open={modalOpen && hasPermission('student:edit')}
+        onOk={hasPermission('student:edit') ? handleAdd : undefined}
+        onCancel={() => setModalOpen(false)}
+        confirmLoading={saving}
+      >
+        <Form form={form} layout="vertical">
+          <Form.Item
+            name="courseCategory"
+            label="课程类别"
+            rules={[{ required: true, message: '请选择课程类别' }]}
+          >
+            <Select options={COURSE_CATEGORY_OPTIONS} placeholder="请选择" />
+          </Form.Item>
+          <Form.Item
+            name="classType"
+            label="班型"
+            rules={[{ required: true, message: '请选择班型' }]}
+          >
+            <Select options={CLASS_TYPE_OPTIONS} placeholder="请选择" />
+          </Form.Item>
+          <Form.Item name="className" label="班级名称">
+            <Input placeholder="如：2024届冲刺班" />
+          </Form.Item>
+          <Form.Item name="headTeacher" label="班主任">
+            <Input placeholder="班主任姓名" />
+          </Form.Item>
+          <Form.Item name="subjectTeacher" label="任课教师">
+            <Input placeholder="任课教师姓名" />
+          </Form.Item>
+          <Form.Item name="startDate" label="开始日期">
+            <DatePicker style={{ width: '100%' }} />
+          </Form.Item>
+          <Form.Item name="endDate" label="结束日期">
+            <DatePicker style={{ width: '100%' }} />
+          </Form.Item>
+        </Form>
+      </Modal>
+    </div>
+  );
+};

apps/admin/src/components/StudentProfileContent/ExamScoresTab.tsx

@@ -0,0 +1,260 @@
+import React, { useState } from 'react';
+import { App, Button, DatePicker, Form, Input, InputNumber, Modal, Select, Table } from 'antd';
+import type { ColumnsType } from 'antd/es/table';
+import { PlusOutlined } from '@ant-design/icons';
+import api from '../../api';
+import { message } from '../../ui/app-message';
+import { useApiMutation } from '../../hooks/useApiMutation';
+import { usePermission } from '../../hooks/usePermission';
+import PermissionButton from '../PermissionButton';
+import { EditableArchiveCell } from './EditableArchiveCell';
+import { EXAM_TYPE_OPTIONS, formatEnrollmentDisplayName, getClassTypeLabel } from './shared';
+import type { EnrollmentRecord, ExamScoreRecord, TabProps } from './shared';
+
+const EXAM_SCORE_FIELDS = {
+  examType: 'examType',
+  examName: 'examName',
+  subject: 'subject',
+  score: 'score',
+  classAvg: 'classAvg',
+  rank: 'rank',
+  examDate: 'examDate',
+  enrollmentId: 'enrollmentId',
+} as const;
+
+export const ExamScoresTab: React.FC<
+  TabProps & { data: ExamScoreRecord[]; enrollments: EnrollmentRecord[] }
+> = ({ data, studentId, enrollments }) => {
+  const { modal } = App.useApp();
+  const { hasPermission } = usePermission();
+  const canPurgeArchive = hasPermission('archive:purge');
+  const [modalOpen, setModalOpen] = useState(false);
+  const [form] = Form.useForm();
+  const [saving, setSaving] = useState(false);
+
+  const addExamScoreMutation = useApiMutation(
+    async (payload: Record<string, unknown>) =>
+      api.post(`/archive/${studentId}/exam-scores`, payload),
+    { invalidate: [['archive', studentId]] },
+  );
+  const saveExamScoreCellMutation = useApiMutation(
+    async ({ id, field, value }: { id: number; field: string; value: unknown }) =>
+      api.put(`/archive/exam-scores/${id}`, { [field]: value }),
+    { invalidate: [['archive', studentId]] },
+  );
+  const purgeExamScoreMutation = useApiMutation(
+    async (id: number) => api.delete(`/archive/exam-scores/${id}/permanent`),
+    { invalidate: [['archive', studentId]] },
+  );
+
+  const handleAdd = async () => {
+    try {
+      const values = await form.validateFields();
+      setSaving(true);
+      await addExamScoreMutation.mutateAsync({
+        ...values,
+        examDate: values.examDate?.format('YYYY-MM-DD'),
+      });
+      message.success('考试成绩已添加');
+      setModalOpen(false);
+      form.resetFields();
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const saveCell = async (record: ExamScoreRecord, field: string, value: unknown) => {
+    try {
+      await saveExamScoreCellMutation.mutateAsync({ id: record.id, field, value });
+      message.success('考试成绩已保存');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    }
+  };
+
+  const handlePurge = (record: ExamScoreRecord) => {
+    modal.confirm({
+      title: `永久删除考试成绩（${record.examName || record.subject || `记录${record.id}`}）？`,
+      content: '删除后不可恢复，成绩记录将被物理删除。确定继续？',
+      okText: '永久删除',
+      okButtonProps: { danger: true },
+      cancelText: '取消',
+      onOk: async () => {
+        try {
+          await purgeExamScoreMutation.mutateAsync(record.id);
+          message.success('已永久删除（不可恢复）');
+        } catch {
+          // 错误提示由 useApiMutation 统一处理
+        }
+      },
+    });
+  };
+
+  const columns: ColumnsType<ExamScoreRecord> = [
+    {
+      title: '考试类型',
+      dataIndex: 'examType',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={EXAM_SCORE_FIELDS.examType} record={r} editor="select"           options={EXAM_TYPE_OPTIONS} onSave={saveCell}>
+          {EXAM_TYPE_OPTIONS.find((o) => o.value === v)?.label || v}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '考试名称',
+      dataIndex: 'examName',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={EXAM_SCORE_FIELDS.examName} record={r} onSave={saveCell}>
+          {v || '-'}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '科目',
+      dataIndex: 'subject',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={EXAM_SCORE_FIELDS.subject} record={r} required onSave={saveCell}>
+          {v}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '成绩',
+      dataIndex: 'score',
+      render: (v: number | null, r) => (
+        <EditableArchiveCell value={v ?? undefined} field={EXAM_SCORE_FIELDS.score} record={r} editor="number"           min={0} onSave={saveCell}>
+          {v ?? '-'}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '班级均分',
+      dataIndex: 'classAvg',
+      render: (v: number | undefined, r) => (
+        <EditableArchiveCell value={v} field={EXAM_SCORE_FIELDS.classAvg} record={r} editor="number"           min={0} onSave={saveCell}>
+          {v !== undefined ? v : '-'}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '排名',
+      dataIndex: 'rank',
+      render: (v: number | undefined, r) => (
+        <EditableArchiveCell value={v} field={EXAM_SCORE_FIELDS.rank} record={r} editor="number"           min={1} onSave={saveCell}>
+          {v !== undefined ? v : '-'}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '考试日期',
+      dataIndex: 'examDate',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={EXAM_SCORE_FIELDS.examDate} record={r} editor="date" onSave={saveCell}>
+          {v || '-'}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '关联报读',
+      dataIndex: 'enrollmentId',
+      render: (v: number | undefined, r) => (
+        <EditableArchiveCell value={v} field={EXAM_SCORE_FIELDS.enrollmentId} record={r} editor="select"           options={enrollments.map((item) => ({             value: item.id,             label: formatEnrollmentDisplayName(item),           }))} onSave={saveCell}>
+          {(() => {
+            if (r.examId) return r.exam?.class?.name || '-';
+            if (v === undefined) return '-';
+            const enr = enrollments.find((e) => e.id === v);
+            return enr ? formatEnrollmentDisplayName(enr) : String(v);
+          })()}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '操作',
+      render: (_: unknown, r: ExamScoreRecord) =>
+        r.status === 'archived' && canPurgeArchive ? (
+          <Button size="small" danger type="link" onClick={() => handlePurge(r)}>
+            删除
+          </Button>
+        ) : null,
+    },
+  ];
+
+  return (
+    <div>
+      <PermissionButton
+        permission="student:edit"
+        icon={<PlusOutlined />}
+        type="primary"
+        onClick={() => {
+          form.resetFields();
+          setModalOpen(true);
+        }}
+        style={{ marginBottom: 16 }}
+      >
+        添加考试成绩
+      </PermissionButton>
+      <Table<ExamScoreRecord>
+        columns={columns}
+        dataSource={data}
+        rowKey="id"
+        rowClassName={(record) => (record.status === 'archived' ? 'archived-row' : '')}
+        pagination={{
+          defaultPageSize: 15,
+          showSizeChanger: true,
+          pageSizeOptions: [15, 30, 50],
+        }}
+      />
+      <Modal
+        title="添加考试成绩"
+        open={modalOpen && hasPermission('student:edit')}
+        onOk={hasPermission('student:edit') ? handleAdd : undefined}
+        onCancel={() => setModalOpen(false)}
+        confirmLoading={saving}
+      >
+        <Form form={form} layout="vertical">
+          <Form.Item
+            name="examType"
+            label="考试类型"
+            rules={[{ required: true, message: '请选择考试类型' }]}
+          >
+            <Select options={EXAM_TYPE_OPTIONS} placeholder="请选择" />
+          </Form.Item>
+          <Form.Item name="examName" label="考试名称">
+            <Input placeholder="如：2024第一次月考" />
+          </Form.Item>
+          <Form.Item
+            name="subject"
+            label="科目"
+            rules={[{ required: true, message: '请输入科目' }]}
+          >
+            <Input placeholder="如：数学" />
+          </Form.Item>
+          <Form.Item name="score" label="成绩" rules={[{ required: true, message: '请输入成绩' }]}>
+            <InputNumber min={0} style={{ width: '100%' }} />
+          </Form.Item>
+          <Form.Item name="classAvg" label="班级均分">
+            <InputNumber min={0} style={{ width: '100%' }} />
+          </Form.Item>
+          <Form.Item name="rank" label="排名">
+            <InputNumber min={1} style={{ width: '100%' }} />
+          </Form.Item>
+          <Form.Item name="examDate" label="考试日期">
+            <DatePicker style={{ width: '100%' }} />
+          </Form.Item>
+          <Form.Item name="enrollmentId" label="关联报读">
+            <Select
+              allowClear
+              placeholder="选择关联的报读记录"
+              options={enrollments.map((e) => ({
+                value: e.id,
+                label: `${formatEnrollmentDisplayName(e)}（${getClassTypeLabel(e.classType)}）`,
+              }))}
+            />
+          </Form.Item>
+        </Form>
+      </Modal>
+    </div>
+  );
+};

apps/admin/src/components/StudentProfileContent/LearningTab.tsx

@@ -0,0 +1,215 @@
+import React, { useState } from 'react';
+import { App, Button, DatePicker, Form, Input, Modal, Select, Table } from 'antd';
+import type { ColumnsType } from 'antd/es/table';
+import { PlusOutlined } from '@ant-design/icons';
+import api from '../../api';
+import { message } from '../../ui/app-message';
+import { useApiMutation } from '../../hooks/useApiMutation';
+import { usePermission } from '../../hooks/usePermission';
+import PermissionButton from '../PermissionButton';
+import { EditableArchiveCell } from './EditableArchiveCell';
+import { RECORD_TYPE_OPTIONS } from './shared';
+import type { LearningRecord, TabProps } from './shared';
+
+const LEARNING_FIELDS = {
+  recordDate: 'recordDate',
+  recordType: 'recordType',
+  content: 'content',
+  followUpMethod: 'followUpMethod',
+  nextStep: 'nextStep',
+} as const;
+
+export const LearningTab: React.FC<TabProps & { data: LearningRecord[] }> = ({
+  data,
+  studentId,
+}) => {
+  const { modal } = App.useApp();
+  const { hasPermission } = usePermission();
+  const canPurgeArchive = hasPermission('archive:purge');
+  const [modalOpen, setModalOpen] = useState(false);
+  const [form] = Form.useForm();
+  const [saving, setSaving] = useState(false);
+
+  const addLearningMutation = useApiMutation(
+    async (payload: Record<string, unknown>) =>
+      api.post(`/archive/${studentId}/learning-records`, payload),
+    { invalidate: [['archive', studentId]] },
+  );
+  const saveLearningCellMutation = useApiMutation(
+    async ({ id, field, value }: { id: number; field: string; value: unknown }) =>
+      api.put(`/archive/learning-records/${id}`, { [field]: value }),
+    { invalidate: [['archive', studentId]] },
+  );
+  const purgeLearningMutation = useApiMutation(
+    async (id: number) => api.delete(`/archive/learning-records/${id}/permanent`),
+    { invalidate: [['archive', studentId]] },
+  );
+
+  const handleAdd = async () => {
+    try {
+      const values = await form.validateFields();
+      setSaving(true);
+      await addLearningMutation.mutateAsync({
+        ...values,
+        recordDate: values.recordDate?.format('YYYY-MM-DD'),
+      });
+      message.success('学情记录已添加');
+      setModalOpen(false);
+      form.resetFields();
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const saveCell = async (record: LearningRecord, field: string, value: unknown) => {
+    try {
+      await saveLearningCellMutation.mutateAsync({ id: record.id, field, value });
+      message.success('学情记录已保存');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    }
+  };
+
+  const handlePurge = (record: LearningRecord) => {
+    modal.confirm({
+      title: `永久删除学情记录（${record.recordType || `记录${record.id}`}）？`,
+      content: '删除后不可恢复，学习记录将被物理删除。确定继续？',
+      okText: '永久删除',
+      okButtonProps: { danger: true },
+      cancelText: '取消',
+      onOk: async () => {
+        try {
+          await purgeLearningMutation.mutateAsync(record.id);
+          message.success('已永久删除（不可恢复）');
+        } catch {
+          // 错误提示由 useApiMutation 统一处理
+        }
+      },
+    });
+  };
+
+  const columns: ColumnsType<LearningRecord> = [
+    {
+      title: '记录日期',
+      dataIndex: 'recordDate',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={LEARNING_FIELDS.recordDate} record={r} editor="date" onSave={saveCell}>
+          {v}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '记录类型',
+      dataIndex: 'recordType',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={LEARNING_FIELDS.recordType} record={r} editor="select"           options={RECORD_TYPE_OPTIONS} onSave={saveCell}>
+          {RECORD_TYPE_OPTIONS.find((o) => o.value === v)?.label || v}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '内容',
+      dataIndex: 'content',
+      ellipsis: true,
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={LEARNING_FIELDS.content} record={r} editor="textarea" onSave={saveCell}>
+          {v}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '跟进方式',
+      dataIndex: 'followUpMethod',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={LEARNING_FIELDS.followUpMethod} record={r} onSave={saveCell}>
+          {v || '-'}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '下一步计划',
+      dataIndex: 'nextStep',
+      render: (v: string, r) => (
+        <EditableArchiveCell value={v} field={LEARNING_FIELDS.nextStep} record={r} editor="textarea" onSave={saveCell}>
+          {v || '-'}
+        </EditableArchiveCell>
+          ),
+    },
+    {
+      title: '操作',
+      render: (_: unknown, r: LearningRecord) =>
+        r.status === 'archived' && canPurgeArchive ? (
+          <Button size="small" danger type="link" onClick={() => handlePurge(r)}>
+            删除
+          </Button>
+        ) : null,
+    },
+  ];
+
+  return (
+    <div>
+      <PermissionButton
+        permission="student:edit"
+        icon={<PlusOutlined />}
+        type="primary"
+        onClick={() => {
+          form.resetFields();
+          setModalOpen(true);
+        }}
+        style={{ marginBottom: 16 }}
+      >
+        添加学情记录
+      </PermissionButton>
+      <Table<LearningRecord>
+        columns={columns}
+        dataSource={data}
+        rowKey="id"
+        rowClassName={(record) => (record.status === 'archived' ? 'archived-row' : '')}
+        pagination={{
+          defaultPageSize: 15,
+          showSizeChanger: true,
+          pageSizeOptions: [15, 30, 50],
+        }}
+      />
+      <Modal
+        title="添加学情记录"
+        open={modalOpen && hasPermission('student:edit')}
+        onOk={hasPermission('student:edit') ? handleAdd : undefined}
+        onCancel={() => setModalOpen(false)}
+        confirmLoading={saving}
+      >
+        <Form form={form} layout="vertical">
+          <Form.Item
+            name="recordDate"
+            label="记录日期"
+            rules={[{ required: true, message: '请选择日期' }]}
+          >
+            <DatePicker style={{ width: '100%' }} />
+          </Form.Item>
+          <Form.Item
+            name="recordType"
+            label="记录类型"
+            rules={[{ required: true, message: '请选择记录类型' }]}
+          >
+            <Select options={RECORD_TYPE_OPTIONS} placeholder="请选择" />
+          </Form.Item>
+          <Form.Item
+            name="content"
+            label="内容"
+            rules={[{ required: true, message: '请输入内容' }]}
+          >
+            <Input.TextArea rows={4} placeholder="请记录学情内容" />
+          </Form.Item>
+          <Form.Item name="followUpMethod" label="跟进方式">
+            <Input placeholder="如：电话、微信、面谈" />
+          </Form.Item>
+          <Form.Item name="nextStep" label="下一步计划">
+            <Input placeholder="后续跟进计划" />
+          </Form.Item>
+        </Form>
+      </Modal>
+    </div>
+  );
+};

apps/admin/src/components/StudentProfileContent/shared.ts

@@ -0,0 +1,216 @@
+export interface StudentInfo {
+  id: number;
+  name: string;
+  phone: string;
+  idNumber: string;
+  studentNo: string;
+  gender?: string;
+  ethnicity?: string;
+  emergencyContact?: string;
+  emergencyPhone?: string;
+  organizationId?: number;
+  organization?: { id?: number; name?: string } | null;
+  supervisor?: string;
+  status: string;
+}
+
+export interface ProfileData {
+  targetCollege?: string;
+  targetMajor?: string;
+  collegeSchool?: string;
+  collegeMajor?: string;
+  subjectDirection?: string;
+  grade?: string;
+  profileDate?: string;
+  notes?: string;
+}
+
+export interface EnrollmentRecord {
+  id: number;
+  courseCategory: string;
+  classType: string;
+  className?: string;
+  headTeacher?: string;
+  subjectTeacher?: string;
+  startDate?: string;
+  endDate?: string;
+  status: string;
+}
+
+export interface ExamScoreRecord {
+  id: number;
+  status?: string;
+  examId?: number;
+  exam?: { class?: { name?: string } };
+  examType: string;
+  examName?: string;
+  subject: string;
+  score: number | null;
+  classAvg?: number;
+  rank?: number;
+  examDate?: string;
+  enrollmentId?: number;
+}
+
+export interface LearningRecord {
+  id: number;
+  status?: string;
+  recordDate: string;
+  recordType: string;
+  content: string;
+  followUpMethod?: string;
+  nextStep?: string;
+}
+
+export interface ResultData {
+  cultureFinalScore?: number;
+  professionalFinalScore?: number;
+  admissionStatus?: string;
+  admittedCollege?: string;
+  admittedMajor?: string;
+}
+
+export interface AttachmentRecord {
+  id: number;
+  status?: string;
+  category: string;
+  fileName: string;
+  fileSize: number;
+}
+
+export interface AttendanceRecordItem {
+  id: number;
+  attendanceDate: string;
+  session: string;
+  status: string;
+  source?: string;
+  remark?: string | null;
+  punchTime?: string | null;
+  punchDeviceName?: string | null;
+  punchDeviceId?: string | null;
+  schedule?: { subject?: string } | null;
+  class?: { name?: string } | null;
+}
+
+export interface StudentProfileAggregate {
+  student: StudentInfo;
+  profile: ProfileData | null;
+  enrollments: EnrollmentRecord[];
+  examScores: ExamScoreRecord[];
+  learningRecords: LearningRecord[];
+  result: ResultData | null;
+  attachments: AttachmentRecord[];
+  attendances: AttendanceRecordItem[];
+}
+
+export interface StudentProfileContentProps {
+  studentId: number;
+  inDrawer?: boolean;
+  onClose?: () => void;
+}
+
+export const ADMISSION_STATUS_MAP: Record<string, { text: string; color: string }> = {
+  admitted: { text: '已录取', color: 'green' },
+  pending: { text: '待录取', color: 'orange' },
+  rejected: { text: '未录取', color: 'red' },
+  withdrawn: { text: '放弃', color: '#999' },
+};
+
+export const EXAM_TYPE_OPTIONS = [
+  { value: 'monthly', label: '月考' },
+  { value: 'midterm', label: '期中' },
+  { value: 'final', label: '期末' },
+  { value: 'mock', label: '模拟考' },
+  { value: 'entrance', label: '入学测试' },
+  { value: 'other', label: '其他' },
+];
+
+export const RECORD_TYPE_OPTIONS = [
+  { value: 'study_feedback', label: '学习反馈' },
+  { value: 'parent_communication', label: '家长沟通' },
+  { value: 'behavior_note', label: '行为记录' },
+  { value: 'meeting', label: '会议记录' },
+  { value: 'other', label: '其他' },
+];
+
+export const ENROLLMENT_STATUS_MAP: Record<string, { text: string; color: string }> = {
+  active: { text: '报读中', color: 'green' },
+  completed: { text: '已结课', color: 'blue' },
+  withdrawn: { text: '已退训', color: 'red' },
+  archived: { text: '已归档', color: '#999' },
+};
+
+export const COURSE_CATEGORY_OPTIONS = [
+  { value: 'culture', label: '文化课' },
+  { value: 'professional', label: '专业课' },
+  { value: 'comprehensive', label: '综合' },
+];
+
+export const CLASS_TYPE_OPTIONS = [
+  { value: 'one_on_one', label: '一对一' },
+  { value: 'small_group', label: '小班' },
+  { value: 'large_class', label: '大班' },
+  { value: 'online', label: '线上' },
+  { value: 'offline', label: '线下' },
+];
+
+export const getOptionLabel = (
+  options: Array<{ value: string; label: string }>,
+  value?: string | null,
+): string => {
+  if (!value) return '-';
+  return options.find((option) => option.value === value)?.label || value;
+};
+
+export const getCourseCategoryLabel = (value?: string | null): string =>
+  getOptionLabel(COURSE_CATEGORY_OPTIONS, value);
+
+export const getClassTypeLabel = (value?: string | null): string =>
+  getOptionLabel(CLASS_TYPE_OPTIONS, value);
+
+export const getEnrollmentStatus = (value?: string | null): { text: string; color: string } => {
+  if (!value) return { text: '-', color: 'default' };
+  return ENROLLMENT_STATUS_MAP[value] || { text: value, color: 'default' };
+};
+
+export const formatEnrollmentDisplayName = (enrollment: EnrollmentRecord): string =>
+  enrollment.className ||
+  (enrollment.courseCategory
+    ? getCourseCategoryLabel(enrollment.courseCategory)
+    : String(enrollment.id));
+
+export const ATTACHMENT_CATEGORY_OPTIONS = [
+  { value: 'id_card', label: '身份证' },
+  { value: 'transcript', label: '成绩单' },
+  { value: 'certificate', label: '证书' },
+  { value: 'contract', label: '合同' },
+  { value: 'photo', label: '照片' },
+  { value: 'other', label: '其他' },
+];
+
+export const formatFileSize = (bytes: number): string => {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+};
+
+export const ATTENDANCE_STATUS_MAP: Record<string, { text: string; color: string }> = {
+  present: { text: '出勤', color: 'green' },
+  late: { text: '迟到', color: 'orange' },
+  absent: { text: '缺勤', color: 'red' },
+  leave: { text: '请假', color: 'blue' },
+  pending: { text: '待确认', color: 'default' },
+};
+
+export const SESSION_LABELS: Record<string, string> = {
+  morning_reading: '早自习',
+  morning: '上午',
+  afternoon: '下午',
+  evening_study: '晚自习',
+  night_check: '晚寝',
+};
+
+export interface TabProps {
+  studentId: number;
+  onRefresh: () => void;
+}

apps/admin/src/hooks/useApiMutation.ts

@@ -0,0 +1,39 @@
+import { useMutation, useQueryClient, type QueryKey } from '@tanstack/react-query';
+import { message } from '../ui/app-message';
+import { getErrorMessage } from '../utils/error';
+
+interface UseApiMutationOptions<TData, TVars> {
+  /** 成功后自动失效的查询 key（触发列表/详情刷新） */
+  invalidate?: QueryKey[];
+  /** 成功后回调（例如关闭弹窗） */
+  onSuccess?: (data: TData, vars: TVars) => void;
+  /** 失败回调；默认统一用 getErrorMessage 弹错误提示 */
+  onError?: (error: unknown) => void;
+}
+
+/**
+ * useMutation 的轻量封装：统一错误提示 + 成功后 invalidateQueries，
+ * 消除手写 `await api.xxx(); await fetchData();` 样板。
+ */
+export function useApiMutation<TData = unknown, TVars = void>(
+  mutationFn: (vars: TVars) => Promise<TData>,
+  options: UseApiMutationOptions<TData, TVars> = {},
+) {
+  const queryClient = useQueryClient();
+  return useMutation<TData, Error, TVars>({
+    mutationFn,
+    onSuccess: (data, vars) => {
+      for (const key of options.invalidate ?? []) {
+        void queryClient.invalidateQueries({ queryKey: key });
+      }
+      options.onSuccess?.(data, vars);
+    },
+    onError: (error) => {
+      if (options.onError) {
+        options.onError(error);
+      } else {
+        message.error(getErrorMessage(error));
+      }
+    },
+  });
+}

apps/admin/src/hooks/usePermission.ts

@@ -1,19 +1,10 @@
-import { useCallback, useEffect, useState } from 'react';
-import { PERMISSIONS_UPDATED_EVENT, readPermissionState } from '../auth/permission-store';
+import { useCallback } from 'react';
+import { usePermissionStore } from '../store/permission/permissionStore';
 
 export function usePermission() {
-  const [state, setState] = useState(readPermissionState);
-
-  useEffect(() => {
-    const refresh = () => setState(readPermissionState());
-    window.addEventListener(PERMISSIONS_UPDATED_EVENT, refresh);
-    return () => {
-      window.removeEventListener(PERMISSIONS_UPDATED_EVENT, refresh);
-    };
-  }, []);
-
-  const permissions = state.permissions;
-  const permissionsReady = state.status === 'ready';
+  const permissions = usePermissionStore((state) => state.permissions);
+  const permissionStatus = usePermissionStore((state) => state.status);
+  const permissionsReady = permissionStatus === 'ready';
   const hasPermission = useCallback(
     (code: string): boolean => permissionsReady && permissions.includes(code),
     [permissions, permissionsReady],
@@ -31,7 +22,7 @@ export function usePermission() {
 
   return {
     permissions,
-    permissionStatus: state.status,
+    permissionStatus,
     permissionsReady,
     hasPermission,
     hasAnyPermission,

apps/admin/src/hooks/useViewSensitive.ts

@@ -1,5 +1,5 @@
-import { useCallback } from 'react';
-import { Modal } from 'antd';
+import { useCallback, useEffect, useRef } from 'react';
+import { App } from 'antd';
 import api from '../api';
 import { message } from '../ui/app-message';
 
@@ -9,16 +9,36 @@ import { message } from '../ui/app-message';
  *
  * @param studentId - The student whose data is being viewed
  * @param module - Audit module label (e.g. '学生管理', '学生档案')
+ * @param canLog - Whether the current user has log:create; when false any
+ *   already-open confirm modal is destroyed.
  */
-export function useViewSensitive(studentId: number, module: string) {
+export function useViewSensitive(studentId: number, module: string, canLog: boolean) {
+  const { modal } = App.useApp();
+  const canLogRef = useRef(canLog);
+  const modalRef = useRef<ReturnType<typeof modal.confirm> | null>(null);
+  canLogRef.current = canLog;
+
+  useEffect(() => {
+    if (!canLogRef.current && modalRef.current) {
+      modalRef.current.destroy();
+      modalRef.current = null;
+    }
+    return () => {
+      modalRef.current?.destroy();
+      modalRef.current = null;
+    };
+  }, []);
+
   return useCallback(
     (field: string, value: string) => {
-      Modal.confirm({
+      if (!canLogRef.current) return;
+      modalRef.current = modal.confirm({
         title: '查看敏感信息',
         content: `您即将查看 "${field}" 的完整信息。此操作将被记录。`,
         okText: '确认查看',
         cancelText: '取消',
         onOk: async () => {
+          if (!canLogRef.current) return;
           try {
             await api.post('/operation-logs/audit', {
               module,
@@ -31,12 +51,15 @@ export function useViewSensitive(studentId: number, module: string) {
             message.error('操作日志记录失败，请稍后重试');
             return;
           }
-          Modal.info({
+          modal.info({
             title: field,
             content: value,
             okText: '关闭',
           });
         },
+        afterClose: () => {
+          modalRef.current = null;
+        },
       });
     },
     [studentId, module],

apps/admin/src/layouts/MainLayout.tsx

@@ -1,6 +1,7 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { Outlet, useNavigate, useLocation } from 'react-router-dom';
-import { Layout, Menu, Button, Avatar, Dropdown, Drawer, Grid } from 'antd';
+import React, { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useNavigate, useLocation } from 'react-router';
+import { Layout, Menu, Button, Avatar, Badge, Dropdown, Drawer, Grid, Tooltip } from 'antd';
+import { BrandLogo } from '../components/BrandLogo';
 import {
   DashboardOutlined,
   TeamOutlined,
@@ -28,18 +29,20 @@ import {
   TrophyOutlined,
   ApiOutlined,
   RobotOutlined,
+  LoadingOutlined,
 } from '@ant-design/icons';
 import { usePermission } from '../hooks/usePermission';
 import api from '../api';
-import {
-  beginPermissionVerification,
-  clearPermissions,
-  writePermissions,
-} from '../auth/permission-store';
+import { useAppStore } from '../store/app/appStore';
+import { usePermissionStore } from '../store/permission/permissionStore';
+import { useUserStore } from '../store/user/userStore';
 import NotificationBell from '../components/NotificationBell';
 import RouteDock from '../components/RouteDock';
+import RouteKeeper from '../components/RouteKeeper';
 import { buildMenu, type AppMenuItem } from '../auth/menu-policy';
 
+const AiChatDrawer = React.lazy(() => import('../components/AiChat/AiChatDrawer'));
+
 const { Header, Sider, Content } = Layout;
 
 const iconMap: Record<string, React.ReactNode> = {
@@ -73,40 +76,76 @@ const iconMap: Record<string, React.ReactNode> = {
 };
 
 const MainLayout: React.FC = () => {
-  const [collapsed, setCollapsed] = useState(false);
-  const [drawerOpen, setDrawerOpen] = useState(false);
-  const [openKeys, setOpenKeys] = useState<string[]>([]);
   const prevPathname = useRef('');
   const navigate = useNavigate();
   const location = useLocation();
-  const [user, setUser] = useState<{ name?: string; username?: string; roles?: string[] }>(() =>
-    JSON.parse(localStorage.getItem('user') || '{}'),
-  );
+  const user = useUserStore((state) => state.user);
+  const updateUser = useUserStore((state) => state.updateUser);
+  const logoutUser = useUserStore((state) => state.logout);
+  const collapsed = useAppStore((state) => state.sidebarCollapsed);
+  const drawerOpen = useAppStore((state) => state.mobileDrawerOpen);
+  const aiChatOpen = useAppStore((state) => state.aiChatOpen);
+  const aiWorking = useAppStore((state) => state.aiWorking);
+  const openKeys = useAppStore((state) => state.menuOpenKeys);
+  const toggleSidebar = useAppStore((state) => state.toggleSidebar);
+  const setDrawerOpen = useAppStore((state) => state.setMobileDrawerOpen);
+  const setAiChatOpen = useAppStore((state) => state.setAiChatOpen);
+  const setAiWorking = useAppStore((state) => state.setAiWorking);
+  const setOpenKeys = useAppStore((state) => state.setMenuOpenKeys);
   const { permissions, hasPermission } = usePermission();
 
   useEffect(() => {
     let cancelled = false;
-    beginPermissionVerification();
-    api
-      .get<{ id: number; username: string; permissions: string[]; roles?: string[] }>(
-        '/auth/profile',
-      )
-      .then((profile) => {
-        if (cancelled) return;
-        writePermissions(profile.permissions || []);
-        const cachedUser = JSON.parse(localStorage.getItem('user') || '{}');
-        const nextUser = { ...cachedUser, ...profile };
-        localStorage.setItem('user', JSON.stringify(nextUser));
-        setUser(nextUser);
-      })
-      .catch(() => {
-        if (!cancelled) clearPermissions('ready');
-        // The API interceptor handles expired/invalid sessions.
-      });
+    let retryTimer: number | undefined;
+    let verificationInFlight = false;
+
+    const verifyPermissions = () => {
+      if (cancelled || verificationInFlight || !useUserStore.getState().token) return;
+      if (retryTimer !== undefined) {
+        window.clearTimeout(retryTimer);
+        retryTimer = undefined;
+      }
+      verificationInFlight = true;
+      usePermissionStore.getState().beginPermissionVerification();
+      api
+        .get<{ id: number; username: string; permissions: string[]; roles?: string[] }>(
+          '/auth/profile',
+        )
+        .then((profile) => {
+          if (cancelled) return;
+          verificationInFlight = false;
+          usePermissionStore.getState().writePermissions(profile.permissions || []);
+          updateUser(profile);
+        })
+        .catch(() => {
+          verificationInFlight = false;
+          if (cancelled || !useUserStore.getState().token) return;
+          retryTimer = window.setTimeout(verifyPermissions, 5_000);
+        });
+    };
+
+    const handleStorage = (event: StorageEvent) => {
+      if (event.key !== 'token' && event.key !== 'permissions') return;
+      usePermissionStore.getState().beginPermissionVerification();
+      window.location.reload();
+    };
+    const handleOnline = () => verifyPermissions();
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === 'visible') verifyPermissions();
+    };
+
+    verifyPermissions();
+    window.addEventListener('storage', handleStorage);
+    window.addEventListener('online', handleOnline);
+    document.addEventListener('visibilitychange', handleVisibilityChange);
     return () => {
       cancelled = true;
+      if (retryTimer !== undefined) window.clearTimeout(retryTimer);
+      window.removeEventListener('storage', handleStorage);
+      window.removeEventListener('online', handleOnline);
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
     };
-  }, []);
+  }, [updateUser]);
 
   const screens = Grid.useBreakpoint();
   const isMobile = !screens.sm; // < 576px (仅 xs)
@@ -115,16 +154,15 @@ const MainLayout: React.FC = () => {
   const usesDrawer = !isDesktop;
 
   const menuItems = useMemo(
-    () => buildMenu(user.roles ?? [], permissions),
-    [user.roles, permissions],
+    () => buildMenu(user?.roles ?? [], permissions),
+    [user, permissions],
   );
 
   const handleLogout = useCallback(() => {
-    localStorage.removeItem('token');
-    localStorage.removeItem('user');
-    clearPermissions();
+    logoutUser();
+    usePermissionStore.getState().clearPermissions();
     navigate('/login');
-  }, [navigate]);
+  }, [logoutUser, navigate]);
 
   const handleMenuClick = useCallback(
     (key: string) => {
@@ -225,7 +263,17 @@ const MainLayout: React.FC = () => {
               borderBottom: '1px solid #e5e5e7',
             }}
           >
-            {collapsed ? '学' : '学生管理系统'}
+            <div
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                gap: 8,
+              }}
+            >
+              <BrandLogo size={collapsed ? 26 : 30} />
+              {!collapsed && <span>学生管理系统</span>}
+            </div>
           </div>
           {menuContent}
         </Sider>
@@ -238,7 +286,12 @@ const MainLayout: React.FC = () => {
           size={240}
           styles={{ body: { padding: 0 } }}
           className="app-navigation-drawer"
-          title="学生管理系统"
+          title={
+            <span style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}>
+              <BrandLogo size={24} />
+              学生管理系统
+            </span>
+          }
         >
           {menuContent}
         </Drawer>
@@ -268,9 +321,27 @@ const MainLayout: React.FC = () => {
                 <MenuFoldOutlined />
               )
             }
-            onClick={() => (usesDrawer ? setDrawerOpen(true) : setCollapsed(!collapsed))}
+            onClick={() => (usesDrawer ? setDrawerOpen(true) : toggleSidebar())}
           />
           <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+            {hasPermission('ai:chat:use') && (
+              <Tooltip title={aiWorking ? 'AI 处理中' : 'AI 助理'}>
+                <Badge dot={aiWorking} color="#007AFF" offset={[-3, 5]}>
+                  <Button
+                    type="text"
+                    aria-label={aiWorking ? 'AI 助理处理中' : '打开 AI 助理'}
+                    icon={
+                      aiWorking ? (
+                        <LoadingOutlined style={{ fontSize: 17, color: '#007AFF' }} spin />
+                      ) : (
+                        <RobotOutlined style={{ fontSize: 17 }} />
+                      )
+                    }
+                    onClick={() => setAiChatOpen(true)}
+                  />
+                </Badge>
+              </Tooltip>
+            )}
             {hasPermission('notification:view') && <NotificationBell />}
             <Dropdown
               menu={{
@@ -291,7 +362,7 @@ const MainLayout: React.FC = () => {
                 style={{ cursor: 'pointer', display: 'flex', alignItems: 'center', gap: 8 }}
               >
                 <Avatar icon={<UserOutlined />} />
-                {isDesktop && <span>{user.name || user.username || '用户'}</span>}
+                {isDesktop && <span>{user?.name || user?.username || '用户'}</span>}
               </div>
             </Dropdown>
           </div>
@@ -311,9 +382,18 @@ const MainLayout: React.FC = () => {
             borderRadius: 12,
           }}
         >
-          <Outlet />
+          <RouteKeeper />
         </Content>
       </Layout>
+      {hasPermission('ai:chat:use') && (
+        <React.Suspense fallback={null}>
+          <AiChatDrawer
+            open={aiChatOpen}
+            onClose={() => setAiChatOpen(false)}
+            onRequestingChange={setAiWorking}
+          />
+        </React.Suspense>
+      )}
     </Layout>
   );
 };

apps/admin/src/main.tsx

@@ -1,11 +1,14 @@
 import React from 'react';
 import ReactDOM from 'react-dom/client';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 import App from './App';
 import './index.css';
 import dayjs from 'dayjs';
 import 'dayjs/locale/zh-cn';
 import customParseFormat from 'dayjs/plugin/customParseFormat';
 import advancedFormat from 'dayjs/plugin/advancedFormat';
+import relativeTime from 'dayjs/plugin/relativeTime';
 import weekday from 'dayjs/plugin/weekday';
 import localeData from 'dayjs/plugin/localeData';
 import weekOfYear from 'dayjs/plugin/weekOfYear';
@@ -15,6 +18,7 @@ import updateLocale from 'dayjs/plugin/updateLocale';
 // 扩展 antd DatePicker/RangePicker 面板所需的 dayjs 插件，否则中文 locale 无法生效
 dayjs.extend(customParseFormat);
 dayjs.extend(advancedFormat);
+dayjs.extend(relativeTime);
 dayjs.extend(weekday);
 dayjs.extend(localeData);
 dayjs.extend(weekOfYear);
@@ -24,8 +28,20 @@ dayjs.extend(updateLocale);
 // 必须在所有插件加载后设置 locale
 dayjs.locale('zh-cn');
 
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: 1,
+      staleTime: 30_000,
+    },
+  },
+});
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
-    <App />
+    <QueryClientProvider client={queryClient}>
+      <App />
+      {import.meta.env.DEV && <ReactQueryDevtools initialIsOpen={false} />}
+    </QueryClientProvider>
   </React.StrictMode>,
 );

apps/admin/src/pages/AiConfig/AiConfigSteps.tsx

@@ -0,0 +1,415 @@
+import React from 'react';
+import {
+  ApiOutlined,
+  CheckCircleOutlined,
+  CloseCircleOutlined,
+  CloudServerOutlined,
+  ReloadOutlined,
+  RobotOutlined,
+  SafetyOutlined,
+  SaveOutlined,
+  WarningOutlined,
+} from '@ant-design/icons';
+import {
+  Alert,
+  AutoComplete,
+  Button,
+  Card,
+  Descriptions,
+  Form,
+  Input,
+  InputNumber,
+  Select,
+  Space,
+  Switch,
+  Tag,
+  Typography,
+} from 'antd';
+import type { AiProvider } from './helpers';
+import {
+  PROVIDER_OPTIONS,
+  PROVIDER_DEFAULTS,
+  formatDateTime,
+  sourceColor,
+  sourceLabel,
+} from './helpers';
+import styles from './index.module.css';
+
+export interface AiConfigData {
+  id: number;
+  provider: AiProvider;
+  baseUrl: string;
+  hasApiKey: boolean;
+  hasDatabaseKey: boolean;
+  maskedApiKey: string | null;
+  keySource: 'database' | 'environment' | 'none';
+  defaultModel: string | null;
+  enabled: boolean;
+  supportsVision: boolean;
+  timeoutMs: number;
+  reasoningEffort: string | null;
+  verified: boolean;
+  lastTestedAt: string | null;
+  lastTestLatencyMs: number | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TestResult {
+  success: boolean;
+  latencyMs: number | null;
+  modelCount: number | null;
+  modelAvailable: boolean;
+  testedAt: string;
+  message: string;
+}
+
+export interface FormValues {
+  provider: AiProvider;
+  baseUrl: string;
+  apiKey: string;
+  defaultModel: string;
+  timeoutMs: number;
+  supportsVision: boolean;
+  reasoningEffort: string;
+}
+
+export const ProviderStep: React.FC<{
+  canWrite: boolean;
+  isFixedProvider: boolean;
+  config?: AiConfigData | null;
+  onProviderChange: (provider: AiProvider) => void;
+}> = ({ canWrite, isFixedProvider, config, onProviderChange }) => {
+  return (
+    <Card title={<span className={styles.cardTitle}>服务商配置</span>} extra={<CloudServerOutlined />}>
+      <Form.Item
+        name="provider"
+        label="Provider"
+        rules={[{ required: true, message: '请选择 Provider' }]}
+        preserve
+      >
+        <Select
+          options={PROVIDER_OPTIONS}
+          onChange={onProviderChange}
+          disabled={!canWrite}
+          size="large"
+        />
+      </Form.Item>
+
+      <Form.Item
+        name="baseUrl"
+        label="Base URL"
+        rules={[
+          { required: true, message: '请输入 Base URL' },
+          { type: 'url', message: '请输入合法的 URL' },
+        ]}
+        preserve
+      >
+        <Input
+          placeholder={
+            config?.provider ? PROVIDER_DEFAULTS[config.provider] : PROVIDER_DEFAULTS.DEEPSEEK
+          }
+          disabled={!canWrite || (isFixedProvider && canWrite)}
+          size="large"
+        />
+      </Form.Item>
+
+      <Form.Item
+        name="timeoutMs"
+        label="请求超时 (毫秒)"
+        rules={[
+          { required: true, message: '请输入超时时间' },
+          { type: 'number', min: 1000, max: 120000, message: '范围: 1000-120000' },
+        ]}
+        preserve
+      >
+        <InputNumber
+          min={1000}
+          max={120000}
+          step={1000}
+          style={{ width: '100%' }}
+          disabled={!canWrite}
+          size="large"
+        />
+      </Form.Item>
+    </Card>
+  );
+};
+
+export const KeyStep: React.FC<{
+  canWrite: boolean;
+  config?: AiConfigData | null;
+  onClearKey: () => void;
+}> = ({ canWrite, config, onClearKey }) => {
+  return (
+    <Card title={<span className={styles.cardTitle}>密钥配置</span>} extra={<SafetyOutlined />}>
+      <Form.Item name="apiKey" label="API Key" preserve>
+        <Input.Password
+          placeholder={config?.hasApiKey ? '已安全保存，留空则保持不变' : '请输入 API Key'}
+          disabled={!canWrite}
+          autoComplete="new-password"
+          size="large"
+        />
+      </Form.Item>
+
+      {config && (
+        <Descriptions column={1} size="small" style={{ marginBottom: 12 }}>
+          <Descriptions.Item label="状态">
+            {config.hasApiKey ? (
+              <Tag color="green">{config.maskedApiKey || '••••'}</Tag>
+            ) : (
+              <Tag color="default">未配置</Tag>
+            )}
+          </Descriptions.Item>
+          <Descriptions.Item label="来源">
+            <Tag color={sourceColor(config.keySource)}>{sourceLabel(config.keySource)}</Tag>
+            {config.keySource === 'environment' && (
+              <span style={{ marginLeft: 8, fontSize: 12, color: '#999' }}>
+                由环境变量托管，需在服务器修改
+              </span>
+            )}
+          </Descriptions.Item>
+          <Descriptions.Item label="最后更新">{formatDateTime(config.updatedAt)}</Descriptions.Item>
+        </Descriptions>
+      )}
+
+      {config?.hasDatabaseKey && canWrite && (
+        <div style={{ marginBottom: 8 }}>
+          <Button danger size="small" onClick={onClearKey}>
+            清除服务器保存密钥
+          </Button>
+        </div>
+      )}
+
+      {config?.keySource === 'environment' && !config.hasDatabaseKey && (
+        <div style={{ marginBottom: 8, fontSize: 12, color: '#999' }}>
+          密钥由环境变量提供，无法通过页面清除
+        </div>
+      )}
+
+      <div className={styles.safetyNote}>
+        API Key 使用 AES-256-GCM 加密存储，每次保存使用随机 IV。传输层通过 HTTPS
+        保护，服务端日志不记录密钥。
+      </div>
+      <div className={styles.safetyNoteKey}>
+        也可通过环境变量 <Typography.Text code>AI_API_KEY</Typography.Text> 注入密钥，环境变量优先级高于数据库存储。
+      </div>
+    </Card>
+  );
+};
+
+export const ModelStep: React.FC<{
+  canWrite: boolean;
+  config?: AiConfigData | null;
+  onFetchModels: () => void;
+  fetchingModels: boolean;
+  modelOptions: Array<{ value: string; label: string }>;
+}> = ({ canWrite, config, onFetchModels, fetchingModels, modelOptions }) => {
+  return (
+    <Card title={<span className={styles.cardTitle}>模型选择</span>} extra={<RobotOutlined />}>
+      <div className={styles.modelFetchRow}>
+        <Button
+          icon={<ReloadOutlined />}
+          onClick={onFetchModels}
+          loading={fetchingModels}
+          disabled={!canWrite}
+        >
+          获取模型列表
+        </Button>
+        {modelOptions.length > 0 && <Tag color="blue">{modelOptions.length} 个可用模型</Tag>}
+      </div>
+
+      <Form.Item
+        name="defaultModel"
+        label="默认模型"
+        rules={[{ required: true, message: '请选择或输入默认模型' }]}
+        style={{ marginTop: 16 }}
+        preserve
+      >
+        <AutoComplete
+          options={modelOptions}
+          placeholder="选择或输入模型名称，如 deepseek-chat, gpt-4"
+          disabled={!canWrite}
+          size="large"
+          filterOption={(inputValue, option) =>
+            option?.value?.toLowerCase().includes(inputValue.toLowerCase()) ?? false
+          }
+        />
+      </Form.Item>
+
+      <Form.Item
+        name="supportsVision"
+        label="图片理解"
+        valuePropName="checked"
+        extra="仅当所选模型确实支持图片输入时开启；关闭时 AI 助手会阻止发送图片。"
+        preserve
+      >
+        <Switch disabled={!canWrite} checkedChildren="已启用" unCheckedChildren="未启用" />
+      </Form.Item>
+
+      <Form.Item
+        name="reasoningEffort"
+        label="推理强度 (reasoning_effort)"
+        extra="OpenAI o 系列等支持该参数的模型生效；DeepSeek 官方接口不支持，选择后也不会发送。"
+        preserve
+      >
+        <Select
+          disabled={!canWrite}
+          size="large"
+          options={[
+            { value: '', label: '不设置（跟随模型默认）' },
+            { value: 'low', label: '低 (low)' },
+            { value: 'medium', label: '中 (medium)' },
+            { value: 'high', label: '高 (high)' },
+            { value: 'xhigh', label: '极高 (xhigh)' },
+          ]}
+        />
+      </Form.Item>
+
+      {config?.verified && (
+        <div style={{ marginTop: 8 }}>
+          <Tag icon={<CheckCircleOutlined />} color="success">
+            上次验证通过
+          </Tag>
+          {config.lastTestLatencyMs != null && (
+            <span style={{ marginLeft: 8, fontSize: 12, color: '#999' }}>
+              延迟: {config.lastTestLatencyMs}ms
+            </span>
+          )}
+        </div>
+      )}
+    </Card>
+  );
+};
+
+export const TestResultCard: React.FC<{ testResult: TestResult | null }> = ({ testResult }) =>
+  testResult ? (
+    <Card size="small" className={styles.testResult}>
+      <Descriptions column={{ xs: 1, sm: 2 }} size="small">
+        <Descriptions.Item label="结果">
+          {testResult.success ? (
+            testResult.modelAvailable ? (
+              <Tag icon={<CheckCircleOutlined />} color="success">
+                成功
+              </Tag>
+            ) : (
+              <Tag icon={<WarningOutlined />} color="warning">
+                模型未找到
+              </Tag>
+            )
+          ) : (
+            <Tag icon={<CloseCircleOutlined />} color="error">
+              失败
+            </Tag>
+          )}
+        </Descriptions.Item>
+        <Descriptions.Item label="延迟">
+          {testResult.latencyMs != null ? `${testResult.latencyMs} ms` : '-'}
+        </Descriptions.Item>
+        <Descriptions.Item label="模型数量">
+          {testResult.modelCount != null ? testResult.modelCount : '-'}
+        </Descriptions.Item>
+        <Descriptions.Item label="测试时间">{formatDateTime(testResult.testedAt)}</Descriptions.Item>
+      </Descriptions>
+      <Alert
+        type={
+          testResult.success
+            ? testResult.modelAvailable
+              ? 'success'
+              : 'warning'
+            : 'error'
+        }
+        title={testResult.message}
+        style={{ marginTop: 8 }}
+      />
+    </Card>
+  ) : null;
+
+export const SaveTestStep: React.FC<{
+  canWrite: boolean;
+  canTest: boolean;
+  config?: AiConfigData | null;
+  currentProvider: AiProvider;
+  formValues: FormValues;
+  onSave: () => void;
+  saving: boolean;
+  onTest: () => void;
+  testing: boolean;
+  testResult: TestResult | null;
+}> = ({
+  canWrite,
+  canTest,
+  config,
+  currentProvider,
+  formValues,
+  onSave,
+  saving,
+  onTest,
+  testing,
+  testResult,
+}) => {
+  const providerLabel =
+    PROVIDER_OPTIONS.find((o) => o.value === currentProvider)?.label ?? currentProvider ?? '-';
+  const hasFormKey = formValues.apiKey && formValues.apiKey !== '••••';
+  return (
+    <Card title={<span className={styles.cardTitle}>保存并测试</span>} extra={<CheckCircleOutlined />}>
+      <Alert
+        type="info"
+        message="配置预览"
+        description={
+          <Descriptions column={1} size="small" style={{ marginTop: 8 }}>
+            <Descriptions.Item label="服务商">
+              <Tag color="blue">{providerLabel}</Tag>
+            </Descriptions.Item>
+            <Descriptions.Item label="Base URL">
+              <Typography.Text code>{formValues.baseUrl || '-'}</Typography.Text>
+            </Descriptions.Item>
+            <Descriptions.Item label="默认模型">
+              <Tag>{formValues.defaultModel || '未设置'}</Tag>
+            </Descriptions.Item>
+            <Descriptions.Item label="密钥">
+              {config?.hasApiKey ? (
+                <Tag color="green">{config.maskedApiKey || '••••'}</Tag>
+              ) : hasFormKey ? (
+                <Tag color="blue">已填写（未保存）</Tag>
+              ) : (
+                <Tag color="red">未配置</Tag>
+              )}
+            </Descriptions.Item>
+            <Descriptions.Item label="超时">{formValues.timeoutMs}ms</Descriptions.Item>
+            <Descriptions.Item label="图片理解">
+              <Tag color={formValues.supportsVision ? 'blue' : 'default'}>
+                {formValues.supportsVision ? '已启用' : '未启用'}
+              </Tag>
+            </Descriptions.Item>
+            <Descriptions.Item label="状态">
+              <Tag color={config?.enabled ? 'green' : 'default'}>
+                {config?.enabled ? '已启用' : '未启用'}
+              </Tag>
+            </Descriptions.Item>
+          </Descriptions>
+        }
+        style={{ marginBottom: 16 }}
+      />
+      <Space>
+        {canWrite && (
+          <Button
+            type="primary"
+            icon={<SaveOutlined />}
+            onClick={onSave}
+            loading={saving}
+            size="large"
+          >
+            保存配置
+          </Button>
+        )}
+        {canTest && (
+          <Button icon={<ApiOutlined />} onClick={onTest} loading={testing} size="large">
+            测试连接
+          </Button>
+        )}
+      </Space>
+      <TestResultCard testResult={testResult} />
+    </Card>
+  );
+};

apps/admin/src/pages/AiConfig/helpers.integration.test.ts

@@ -5,8 +5,8 @@ import {
   sourceLabel,
   sourceColor,
   PROVIDER_DEFAULTS,
-  extractErrorMessage,
 } from './helpers';
+import { getErrorMessage } from '../../utils/error';
 
 describe('AiConfig helpers', () => {
   describe('shouldAutoSwapBaseUrl', () => {
@@ -60,48 +60,48 @@ describe('AiConfig helpers', () => {
     });
   });
 
-  describe('extractErrorMessage', () => {
+  describe('getErrorMessage', () => {
     it('extracts message from server error response (interceptor unwraps to { message })', () => {
       // The Axios interceptor at api/index.ts does Promise.reject(err.response?.data || err).
       // For server errors, the rejection value is err.response.data — typically { message: '...' }.
       const err = { message: 'API出错' };
-      expect(extractErrorMessage(err)).toBe('API出错');
+      expect(getErrorMessage(err)).toBe('API出错');
     });
 
     it('falls back to message property', () => {
       const err = { message: 'Network error' };
-      expect(extractErrorMessage(err)).toBe('Network error');
+      expect(getErrorMessage(err)).toBe('Network error');
     });
 
-    it('falls back to default on unknown type', () => {
-      expect(extractErrorMessage('unknown string')).toBe('操作失败');
-      expect(extractErrorMessage(null)).toBe('操作失败');
-      expect(extractErrorMessage(undefined)).toBe('操作失败');
+    it('uses string errors and falls back on unknown types', () => {
+      expect(getErrorMessage('unknown string')).toBe('unknown string');
+      expect(getErrorMessage(null)).toBe('操作失败');
+      expect(getErrorMessage(undefined)).toBe('操作失败');
     });
 
     it('sanitizes: newlines replaced with spaces', () => {
       const err = { message: 'line1\nline2\r\nline3' };
-      expect(extractErrorMessage(err)).toBe('line1 line2 line3');
+      expect(getErrorMessage(err)).toBe('line1 line2 line3');
     });
 
     it('sanitizes: message > 120 chars truncated with ellipsis', () => {
       const long = 'x'.repeat(200);
       const err = { message: long };
-      const result = extractErrorMessage(err);
+      const result = getErrorMessage(err);
       expect(result).toHaveLength(121); // 120 + '…' (1 char)
       expect(result.endsWith('\u2026')).toBe(true);
     });
 
     it('sanitizes: empty trimmed message falls back', () => {
       const err = { message: '   ' };
-      expect(extractErrorMessage(err)).toBe('操作失败');
+      expect(getErrorMessage(err)).toBe('操作失败');
     });
 
     it('sanitizes: plain object message property sanitized', () => {
       const err = {
         message: '  some \n\nerror  \r\nmessage  ',
       };
-      expect(extractErrorMessage(err)).toBe('some error message');
+      expect(getErrorMessage(err)).toBe('some error message');
     });
   });
 });

apps/admin/src/pages/AiConfig/helpers.ts

@@ -1,18 +1,21 @@
-// ---------------------------------------------------------------------------
-// AiConfig helpers — pure functions, no React / DOM dependencies
-// ---------------------------------------------------------------------------
+import dayjs from 'dayjs';
 
 export type AiProvider = 'OPENAI' | 'DEEPSEEK' | 'OPENAI_COMPATIBLE';
 
 export const PROVIDER_OPTIONS: { value: AiProvider; label: string }[] = [
-  { value: 'OPENAI', label: 'OpenAI' },
   { value: 'DEEPSEEK', label: 'DeepSeek' },
+  { value: 'OPENAI', label: 'OpenAI' },
   { value: 'OPENAI_COMPATIBLE', label: 'OpenAI 兼容' },
 ];
 
+// aislop-ignore-next-line: hardcoded-url -- OpenAI 官方 API 固定端点
+export const OPENAI_DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+// aislop-ignore-next-line: hardcoded-url -- DeepSeek 官方 API 固定端点
+export const DEEPSEEK_DEFAULT_BASE_URL = 'https://api.deepseek.com';
+
 export const PROVIDER_DEFAULTS: Record<AiProvider, string> = {
-  OPENAI: 'https://api.openai.com/v1',
-  DEEPSEEK: 'https://api.deepseek.com',
+  OPENAI: OPENAI_DEFAULT_BASE_URL,
+  DEEPSEEK: DEEPSEEK_DEFAULT_BASE_URL,
   OPENAI_COMPATIBLE: '',
 } as const;
 
@@ -20,7 +23,7 @@ export const FIXED_PROVIDERS: AiProvider[] = ['OPENAI', 'DEEPSEEK'];
 
 export function formatDateTime(iso: string | null): string {
   if (!iso) return '-';
-  return new Date(iso).toLocaleString('zh-CN');
+  return dayjs(iso).format('YYYY-MM-DD HH:mm:ss');
 }
 
 export function sourceLabel(source: string): string {
@@ -59,25 +62,3 @@ export function shouldAutoSwapBaseUrl(
   }
   return { baseUrl: currentBaseUrl, shouldSwap: false };
 }
-
-/** Extract a safe user-facing error message from any caught value.
- *
- * The Axios interceptor at `api/index.ts` unwraps errors before rejection:
- * `Promise.reject(err.response?.data || err)`. So server errors arrive as
- * `{ message: '...' }` (the unwrapped data) and network errors as the raw
- * `Error` object — never as a raw AxiosError with a `.response` property. */
-export function extractErrorMessage(err: unknown, fallback: string = '操作失败'): string {
-  let msg = '';
-
-  // standard Error or any object with a string message property
-  if (err && typeof err === 'object' && 'message' in err && typeof err.message === 'string') {
-    msg = err.message;
-  }
-
-  // sanitize: trim, collapse whitespace, strip newlines, truncate
-  const trimmed = msg.trim();
-  if (!trimmed) return fallback;
-
-  const singleLine = trimmed.replace(/[\n\r]+/g, ' ').replace(/ {2,}/g, ' ');
-  return singleLine.length > 120 ? singleLine.slice(0, 120) + '\u2026' : singleLine;
-}

apps/admin/src/pages/AiConfig/index.module.css

@@ -1,11 +1,11 @@
 .container {
-  max-width: 1200px;
+  max-width: 900px;
   margin: 0 auto;
   padding: 16px;
 }
 
 .header {
-  margin-bottom: 16px;
+  margin-bottom: 20px;
 }
 
 .header h2 {
@@ -24,17 +24,13 @@
   margin-top: 8px;
 }
 
-.grid {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: 16px;
-  margin-bottom: 16px;
+.steps {
+  margin-bottom: 24px;
 }
 
-@media (max-width: 768px) {
-  .grid {
-    grid-template-columns: 1fr;
-  }
+.stepContent {
+  min-height: 320px;
+  margin-bottom: 16px;
 }
 
 .cardTitle {
@@ -42,10 +38,17 @@
   font-weight: 600;
 }
 
-.actions {
+.stepNav {
   display: flex;
-  gap: 8px;
-  flex-wrap: wrap;
+  justify-content: space-between;
+  padding-top: 8px;
+  border-top: 1px solid #f0f0f0;
+}
+
+.modelFetchRow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
 }
 
 .testResult {

apps/admin/src/pages/AiConfig/index.tsx

@@ -1,226 +1,269 @@
 import React, { useEffect, useState, useCallback, useRef } from 'react';
-import {
-  App,
-  Card,
-  Form,
-  Input,
-  Button,
-  Select,
-  Switch,
-  InputNumber,
-  Tag,
-  Descriptions,
-  Spin,
-  Alert,
-  Typography,
-  Space,
-} from 'antd';
-import {
-  SaveOutlined,
-  ApiOutlined,
-  CheckCircleOutlined,
-  CloseCircleOutlined,
-  KeyOutlined,
-  WarningOutlined,
-} from '@ant-design/icons';
+import { useQuery } from '@tanstack/react-query';
+import { useApiMutation } from '../../hooks/useApiMutation';
+import { validateResponse } from '../../utils/validate';
+import { aiConfigEnvelopeSchema } from '../../api/schemas';
+import { App, Alert, Button, Form, Space, Spin, Steps, Tag } from 'antd';
 import api from '../../api';
 import { message } from '../../ui/app-message';
 import { usePermission } from '../../hooks/usePermission';
 import type { AiProvider } from './helpers';
 import {
-  PROVIDER_OPTIONS,
   PROVIDER_DEFAULTS,
   FIXED_PROVIDERS,
-  formatDateTime,
   sourceLabel,
   sourceColor,
   shouldAutoSwapBaseUrl,
-  extractErrorMessage,
 } from './helpers';
+import { getErrorMessage } from '../../utils/error';
+import {
+  ProviderStep,
+  KeyStep,
+  ModelStep,
+  SaveTestStep,
+} from './AiConfigSteps';
+import type { AiConfigData, FormValues, TestResult } from './AiConfigSteps';
 import styles from './index.module.css';
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-interface AiConfigData {
-  id: number;
-  provider: AiProvider;
-  baseUrl: string;
-  hasApiKey: boolean;
-  hasDatabaseKey: boolean;
-  maskedApiKey: string | null;
-  keySource: 'database' | 'environment' | 'none';
-  defaultModel: string | null;
-  enabled: boolean;
-  timeoutMs: number;
-  verified: boolean;
-  lastTestedAt: string | null;
-  lastTestLatencyMs: number | null;
-  createdAt: string;
-  updatedAt: string;
-}
-
-interface TestResult {
-  success: boolean;
-  latencyMs: number | null;
-  modelCount: number | null;
-  modelAvailable: boolean;
-  testedAt: string;
-  message: string;
-}
-
 interface ApiResponse<T> {
   success: boolean;
   data: T;
   message?: string;
 }
 
-// ---------------------------------------------------------------------------
-// Page Component
-// ---------------------------------------------------------------------------
+interface FetchModelsResult {
+  success: boolean;
+  models: Array<{ id: string }>;
+  message?: string;
+}
+
+const DEFAULT_FORM_VALUES: FormValues = {
+  provider: 'DEEPSEEK',
+  baseUrl: PROVIDER_DEFAULTS['DEEPSEEK'],
+  apiKey: '',
+  defaultModel: '',
+  timeoutMs: 30000,
+  supportsVision: false,
+  reasoningEffort: '',
+};
+
+const STEP_ITEMS = [
+  { title: '服务商', description: '选择 AI 服务商' },
+  { title: '密钥', description: '配置 API 密钥' },
+  { title: '模型', description: '获取并选择模型' },
+  { title: '完成', description: '保存并测试连接' },
+];
 
 const AiConfigPage: React.FC = () => {
   const { hasPermission } = usePermission();
   const { modal } = App.useApp();
   const [form] = Form.useForm();
 
-  const [loading, setLoading] = useState(true);
+  const [currentStep, setCurrentStep] = useState(0);
   const [saving, setSaving] = useState(false);
   const [testing, setTesting] = useState(false);
-  const [config, setConfig] = useState<AiConfigData | null>(null);
+  const [fetchingModels, setFetchingModels] = useState(false);
   const [testResult, setTestResult] = useState<TestResult | null>(null);
+  const [modelOptions, setModelOptions] = useState<Array<{ value: string; label: string }>>([]);
   const [error, setError] = useState<string | null>(null);
 
+  // Central form state — survives Step transitions when Form.Items unmount
+  const [formValues, setFormValues] = useState<FormValues>(DEFAULT_FORM_VALUES);
+
   const lastProviderRef = useRef<AiProvider | null>(null);
+  const skipNextSyncRef = useRef(false);
+  const appliedConfigRef = useRef<AiConfigData | null>(null);
+
+  const {
+    data: config,
+    isLoading: configLoading,
+    isFetching: configFetching,
+    refetch: refetchConfig,
+  } = useQuery<AiConfigData | null>({
+    queryKey: ['ai', 'config'],
+    queryFn: async () => {
+      try {
+        const res = await api.get<ApiResponse<AiConfigData>>('/ai/config');
+        return validateResponse<ApiResponse<AiConfigData>>(aiConfigEnvelopeSchema, res).data;
+      } catch (err: unknown) {
+        setError(getErrorMessage(err, '加载配置失败'));
+        return null;
+      }
+    },
+  });
+  const loading = configLoading || configFetching;
+  const refreshConfig = useCallback(() => {
+    skipNextSyncRef.current = true;
+    return refetchConfig();
+  }, [refetchConfig]);
+  const saveMutation = useApiMutation(
+    async (body: Record<string, unknown>) => api.put('/ai/config', body),
+    { invalidate: [['ai', 'config']] },
+  );
+  const clearKeyMutation = useApiMutation(
+    async () => api.post('/ai/config/clear-key'),
+    { invalidate: [['ai', 'config']] },
+  );
 
   const canWrite = hasPermission('ai:config:write');
   const canTest = hasPermission('ai:config:test');
   const canRead = hasPermission('ai:config:read');
 
-  // ── Load config ──
+  // ── Sync form → state ──
 
-  const loadConfig = useCallback(async () => {
-    setLoading(true);
-    setError(null);
-    try {
-      const res = await api.get<ApiResponse<AiConfigData>>('/ai/config');
-      setConfig(res.data);
-      form.setFieldsValue({
-        provider: res.data.provider,
-        baseUrl: res.data.baseUrl,
-        defaultModel: res.data.defaultModel ?? undefined,
-        enabled: res.data.enabled,
-        timeoutMs: res.data.timeoutMs,
-      });
-      lastProviderRef.current = res.data.provider;
-    } catch (err: unknown) {
-      setError(extractErrorMessage(err, '加载配置失败'));
-    } finally {
-      setLoading(false);
-    }
-  }, [form]);
+  const handleFormChange = useCallback(
+    (_changed: Partial<FormValues>, all: Partial<FormValues>) => {
+      setFormValues((prev) => ({ ...prev, ...all }));
+    },
+    [],
+  );
 
+  // 配置数据到位后同步进表单（antd Form 属于外部系统）；
+  // refreshConfig（测试/拉模型后）只刷新展示，不覆盖用户表单输入。
   useEffect(() => {
-    loadConfig();
-  }, [loadConfig]);
+    if (!config) return;
+    if (skipNextSyncRef.current) {
+      skipNextSyncRef.current = false;
+      appliedConfigRef.current = config;
+      return;
+    }
+    if (appliedConfigRef.current === config) return;
+    appliedConfigRef.current = config;
+    const initial: FormValues = {
+      provider: config.provider,
+      baseUrl: config.baseUrl,
+      apiKey: '',
+      defaultModel: config.defaultModel ?? '',
+      timeoutMs: config.timeoutMs,
+      supportsVision: config.supportsVision,
+      reasoningEffort: config.reasoningEffort ?? '',
+    };
+    form.setFieldsValue(initial);
+    setFormValues(initial);
+    lastProviderRef.current = config.provider;
+    if (config.defaultModel) {
+      setModelOptions([{ value: config.defaultModel, label: config.defaultModel }]);
+    }
+    setError(null);
+  }, [config, form]);
 
   // ── Provider change → swap baseUrl ──
 
   const handleProviderChange = useCallback(
     (provider: AiProvider) => {
-      const currentBaseUrl = form.getFieldValue('baseUrl') || '';
-      const result = shouldAutoSwapBaseUrl(provider, currentBaseUrl, lastProviderRef.current);
+      const result = shouldAutoSwapBaseUrl(provider, formValues.baseUrl, lastProviderRef.current);
       if (result.shouldSwap) {
         form.setFieldValue('baseUrl', result.baseUrl);
       }
       lastProviderRef.current = provider;
     },
-    [form],
+    [form, formValues.baseUrl],
   );
 
-  const currentProvider = Form.useWatch('provider', form) as AiProvider | undefined;
-  const isFixedProvider = currentProvider ? FIXED_PROVIDERS.includes(currentProvider) : false;
+  const currentProvider = formValues.provider;
+  const isFixedProvider = FIXED_PROVIDERS.includes(currentProvider);
+
+  // ── Fetch models from provider ──
+
+  const handleFetchModels = useCallback(async () => {
+    setFetchingModels(true);
+    try {
+      await form.validateFields(['provider', 'baseUrl']);
+
+      const { provider, baseUrl, apiKey: formKey } = formValues;
+      const body: Record<string, unknown> = { provider };
+      if (baseUrl) body.baseUrl = baseUrl;
+      if (formKey && formKey !== '••••') body.apiKey = formKey;
+
+      const res = await api.post<FetchModelsResult>('/ai/config/models', body);
+      if (res.success && res.models.length > 0) {
+        const options = res.models.map((m) => ({ value: m.id, label: m.id }));
+        setModelOptions(options);
+        message.success(`获取到 ${res.models.length} 个模型`);
+      } else {
+        message.warning(res.message || '未获取到可用模型');
+      }
+    } catch (err: unknown) {
+      message.error(getErrorMessage(err, '获取模型列表失败'));
+    } finally {
+      setFetchingModels(false);
+    }
+  }, [form, formValues]);
 
   // ── Save ──
 
   const handleSave = useCallback(async () => {
     try {
-      const values = await form.validateFields();
-      setSaving(true);
+      // Validate fields (for UI error display) — actual values come from state
+      await form.validateFields(['provider', 'baseUrl', 'timeoutMs']);
 
-      // Validate baseUrl for OPENAI_COMPATIBLE
-      if (values.provider === 'OPENAI_COMPATIBLE' && !values.baseUrl) {
+      const {
+        provider,
+        baseUrl,
+        defaultModel,
+        apiKey,
+        timeoutMs,
+        supportsVision,
+        reasoningEffort,
+      } = formValues;
+
+      if (provider === 'OPENAI_COMPATIBLE' && !baseUrl) {
         message.error('OPENAI_COMPATIBLE 模式必须填写 Base URL');
-        setSaving(false);
         return;
       }
 
+      setSaving(true);
+
+      const resolvedBaseUrl = baseUrl || PROVIDER_DEFAULTS[provider] || '';
+
       const body: Record<string, unknown> = {
-        provider: values.provider,
-        baseUrl: values.baseUrl,
-        defaultModel: values.defaultModel || undefined,
-        enabled: values.enabled,
-        timeoutMs: values.timeoutMs,
+        provider,
+        baseUrl: resolvedBaseUrl,
+        defaultModel: defaultModel || undefined,
+        enabled: true,
+        supportsVision,
+        timeoutMs,
+        reasoningEffort: reasoningEffort || null,
       };
 
-      if (values.apiKey && values.apiKey !== '••••') {
-        body.apiKey = values.apiKey;
+      if (apiKey && apiKey !== '••••') {
+        body.apiKey = apiKey;
       }
 
-      await api.put('/ai/config', body);
+      await saveMutation.mutateAsync(body);
       message.success('配置已保存');
       form.setFieldValue('apiKey', '');
-    } catch (err: unknown) {
-      message.error(extractErrorMessage(err, '保存失败'));
-      setSaving(false);
-      return;
-    }
-
-    // Reload config from server (non-fatal if it fails)
-    try {
-      await loadConfig();
-    } catch (err: unknown) {
-      message.warning(extractErrorMessage(err, '配置已保存，但刷新失败'));
+      setFormValues((prev) => ({ ...prev, apiKey: '' }));
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     } finally {
       setSaving(false);
     }
-  }, [form, loadConfig]);
+  }, [formValues, form, saveMutation]);
 
   // ── Test connection ──
 
   const handleTest = useCallback(async () => {
     try {
-      // Validated fields: compatible requires baseUrl
       const fieldsToValidate = ['provider', 'timeoutMs'] as string[];
       if (currentProvider === 'OPENAI_COMPATIBLE') {
         fieldsToValidate.push('baseUrl');
       }
-      const values = await form.validateFields(fieldsToValidate);
+      await form.validateFields(fieldsToValidate);
 
       setTesting(true);
       setTestResult(null);
 
-      const body: Record<string, unknown> = {
-        timeoutMs: values.timeoutMs,
-      };
-
-      // Always send provider if form has it
-      if (currentProvider) body.provider = currentProvider;
-      if (values.baseUrl) body.baseUrl = values.baseUrl;
-
-      // Include defaultModel so backend checks target model
-      const defaultModel = form.getFieldValue('defaultModel');
+      const { provider, baseUrl, defaultModel, apiKey, timeoutMs, reasoningEffort } = formValues;
+      const body: Record<string, unknown> = { provider, timeoutMs };
+      if (baseUrl) body.baseUrl = baseUrl;
       if (defaultModel) body.defaultModel = defaultModel;
-
-      const typedKey = form.getFieldValue('apiKey');
-      if (typedKey && typedKey !== '••••') {
-        body.apiKey = typedKey;
-      }
+      if (apiKey && apiKey !== '••••') body.apiKey = apiKey;
+      if (reasoningEffort) body.reasoningEffort = reasoningEffort;
 
       const res = await api.post<TestResult>('/ai/config/test', body);
       setTestResult(res);
-      await loadConfig();
+      await refreshConfig();
     } catch (err: unknown) {
       setTestResult({
         success: false,
@@ -228,12 +271,12 @@ const AiConfigPage: React.FC = () => {
         modelCount: null,
         modelAvailable: false,
         testedAt: new Date().toISOString(),
-        message: extractErrorMessage(err, '测试请求失败'),
+        message: getErrorMessage(err, '测试请求失败'),
       });
     } finally {
       setTesting(false);
     }
-  }, [form, loadConfig, currentProvider]);
+  }, [formValues, form, currentProvider]);
 
   // ── Clear key ──
 
@@ -249,15 +292,33 @@ const AiConfigPage: React.FC = () => {
       cancelText: '取消',
       onOk: async () => {
         try {
-          await api.post('/ai/config/clear-key');
+          await clearKeyMutation.mutateAsync();
           message.success('密钥已清除');
-          await loadConfig();
-        } catch (err: unknown) {
-          message.error(extractErrorMessage(err, '清除失败'));
+        } catch {
+          // 错误提示由 useApiMutation 统一处理
         }
       },
     });
-  }, [config, loadConfig, modal]);
+  }, [config, modal]);
+
+  // ── Step navigation ──
+
+  const goNext = useCallback(async () => {
+    try {
+      if (currentStep === 0) {
+        await form.validateFields(['provider', 'baseUrl', 'timeoutMs']);
+      } else if (currentStep === 2) {
+        await form.validateFields(['defaultModel']);
+      }
+      setCurrentStep((s) => Math.min(s + 1, STEP_ITEMS.length - 1));
+    } catch {
+      // Validation failed — form will show errors
+    }
+  }, [currentStep, form]);
+
+  const goPrev = useCallback(() => {
+    setCurrentStep((s) => Math.max(s - 1, 0));
+  }, []);
 
   // ── No read permission ──
 
@@ -285,6 +346,49 @@ const AiConfigPage: React.FC = () => {
     );
   }
 
+  const renderStepContent = () => {
+    switch (currentStep) {
+      case 0:
+        return (
+          <ProviderStep
+            canWrite={canWrite}
+            isFixedProvider={isFixedProvider}
+            config={config}
+            onProviderChange={handleProviderChange}
+          />
+        );
+      case 1:
+        return <KeyStep canWrite={canWrite} config={config} onClearKey={handleClearKey} />;
+      case 2:
+        return (
+          <ModelStep
+            canWrite={canWrite}
+            config={config}
+            onFetchModels={handleFetchModels}
+            fetchingModels={fetchingModels}
+            modelOptions={modelOptions}
+          />
+        );
+      case 3:
+        return (
+          <SaveTestStep
+            canWrite={canWrite}
+            canTest={canTest}
+            config={config}
+            currentProvider={currentProvider}
+            formValues={formValues}
+            onSave={handleSave}
+            saving={saving}
+            onTest={handleTest}
+            testing={testing}
+            testResult={testResult}
+          />
+        );
+      default:
+        return null;
+    }
+  };
+
   // ── Render ──
 
   return (
@@ -307,193 +411,33 @@ const AiConfigPage: React.FC = () => {
         </div>
       </div>
 
-      <Form form={form} layout="vertical" initialValues={{ timeoutMs: 30000, enabled: false }}>
-        <div className={styles.grid}>
-          {/* Left: 模型路由 */}
-          <Card title={<span className={styles.cardTitle}>模型路由</span>} extra={<ApiOutlined />}>
-            <Form.Item
-              name="provider"
-              label="Provider"
-              rules={[{ required: true, message: '请选择 Provider' }]}
-            >
-              <Select
-                options={PROVIDER_OPTIONS}
-                onChange={handleProviderChange}
-                disabled={!canWrite}
-              />
-            </Form.Item>
+      <Steps
+        current={currentStep}
+        items={STEP_ITEMS}
+        onChange={setCurrentStep}
+        className={styles.steps}
+        size="small"
+      />
 
-            <Form.Item
-              name="baseUrl"
-              label="Base URL"
-              rules={[
-                { required: true, message: '请输入 Base URL' },
-                { type: 'url', message: '请输入合法的 URL' },
-              ]}
-            >
-              <Input
-                placeholder={
-                  config?.provider
-                    ? PROVIDER_DEFAULTS[config.provider]
-                    : 'https://api.openai.com/v1'
-                }
-                disabled={!canWrite || (isFixedProvider && canWrite)}
-              />
-            </Form.Item>
+      <Form
+        form={form}
+        layout="vertical"
+        initialValues={{ timeoutMs: 30000 }}
+        onValuesChange={handleFormChange}
+      >
+        <div className={styles.stepContent}>{renderStepContent()}</div>
 
-            <Form.Item noStyle shouldUpdate={(prev, curr) => prev.enabled !== curr.enabled}>
-              {({ getFieldValue }) => {
-                const enabled = getFieldValue('enabled');
-                return (
-                  <Form.Item
-                    name="defaultModel"
-                    label="默认模型"
-                    rules={enabled ? [{ required: true, message: '启用时默认模型为必填项' }] : []}
-                  >
-                    <Input placeholder="例如: gpt-4, deepseek-chat" disabled={!canWrite} />
-                  </Form.Item>
-                );
-              }}
-            </Form.Item>
-
-            <Form.Item name="enabled" label="启用" valuePropName="checked">
-              <Switch disabled={!canWrite} />
-            </Form.Item>
-
-            <Form.Item
-              name="timeoutMs"
-              label="请求超时 (毫秒)"
-              rules={[
-                { required: true, message: '请输入超时时间' },
-                { type: 'number', min: 1000, max: 120000, message: '范围: 1000-120000' },
-              ]}
-            >
-              <InputNumber
-                min={1000}
-                max={120000}
-                step={1000}
-                style={{ width: '100%' }}
-                disabled={!canWrite}
-              />
-            </Form.Item>
-          </Card>
-
-          {/* Right: 密钥保险库 */}
-          <Card
-            title={<span className={styles.cardTitle}>密钥保险库</span>}
-            extra={<KeyOutlined />}
-          >
-            <Form.Item name="apiKey" label="API Key">
-              <Input.Password
-                placeholder={config?.hasApiKey ? '已安全保存，留空则保持不变' : '请输入 API Key'}
-                disabled={!canWrite}
-                autoComplete="new-password"
-              />
-            </Form.Item>
-
-            {config && (
-              <Descriptions column={1} size="small" style={{ marginBottom: 12 }}>
-                <Descriptions.Item label="状态">
-                  {config.hasApiKey ? (
-                    <Tag color="green">{config.maskedApiKey || '••••'}</Tag>
-                  ) : (
-                    <Tag color="default">未配置</Tag>
-                  )}
-                </Descriptions.Item>
-                <Descriptions.Item label="来源">
-                  <Tag color={sourceColor(config.keySource)}>{sourceLabel(config.keySource)}</Tag>
-                  {config.keySource === 'environment' && (
-                    <span style={{ marginLeft: 8, fontSize: 12, color: '#999' }}>
-                      由环境变量托管，需在服务器修改
-                    </span>
-                  )}
-                </Descriptions.Item>
-                <Descriptions.Item label="最后更新">
-                  {formatDateTime(config.updatedAt)}
-                </Descriptions.Item>
-              </Descriptions>
-            )}
-
-            {config?.hasDatabaseKey && canWrite && (
-              <div style={{ marginBottom: 8 }}>
-                <Button danger size="small" onClick={handleClearKey}>
-                  清除服务器保存密钥
-                </Button>
-              </div>
-            )}
-
-            {config?.keySource === 'environment' && !config.hasDatabaseKey && (
-              <div style={{ marginBottom: 8, fontSize: 12, color: '#999' }}>
-                密钥由环境变量提供，无法通过页面清除
-              </div>
-            )}
-
-            <div className={styles.safetyNote}>
-              API Key 使用 AES-256-GCM 加密存储，每次保存使用随机 IV。 传输层通过 HTTPS
-              保护，服务端日志不记录密钥。
-            </div>
-            <div className={styles.safetyNoteKey}>
-              也可通过环境变量 <Typography.Text code>AI_API_KEY</Typography.Text> 注入密钥，
-              环境变量优先级高于数据库存储。
-            </div>
-          </Card>
-        </div>
-
-        {/* Actions */}
-        <div className={styles.actions}>
-          {canWrite ? (
-            <Button type="primary" icon={<SaveOutlined />} onClick={handleSave} loading={saving}>
-              保存配置
-            </Button>
-          ) : null}
-          {canTest ? (
-            <Button icon={<ApiOutlined />} onClick={handleTest} loading={testing}>
-              测试连接
+        <div className={styles.stepNav}>
+          <Button onClick={goPrev} disabled={currentStep === 0} icon={<span>←</span>}>
+            上一步
+          </Button>
+          {currentStep < STEP_ITEMS.length - 1 ? (
+            <Button type="primary" onClick={goNext} icon={<span>→</span>}>
+              下一步
             </Button>
           ) : null}
         </div>
       </Form>
-
-      {/* Test result */}
-      {testResult && (
-        <Card size="small" className={styles.testResult}>
-          <Descriptions column={{ xs: 1, sm: 2 }} size="small">
-            <Descriptions.Item label="结果">
-              {testResult.success ? (
-                testResult.modelAvailable ? (
-                  <Tag icon={<CheckCircleOutlined />} color="success">
-                    成功
-                  </Tag>
-                ) : (
-                  <Tag icon={<WarningOutlined />} color="warning">
-                    模型未找到
-                  </Tag>
-                )
-              ) : (
-                <Tag icon={<CloseCircleOutlined />} color="error">
-                  失败
-                </Tag>
-              )}
-            </Descriptions.Item>
-            <Descriptions.Item label="延迟">
-              {testResult.latencyMs != null ? `${testResult.latencyMs} ms` : '-'}
-            </Descriptions.Item>
-            <Descriptions.Item label="模型数量">
-              {testResult.modelCount != null ? testResult.modelCount : '-'}
-            </Descriptions.Item>
-            <Descriptions.Item label="测试时间">
-              {formatDateTime(testResult.testedAt)}
-            </Descriptions.Item>
-          </Descriptions>
-          <Alert
-            type={
-              testResult.success ? (testResult.modelAvailable ? 'success' : 'warning') : 'error'
-            }
-            title={testResult.message}
-            style={{ marginTop: 8 }}
-          />
-        </Card>
-      )}
     </div>
   );
 };

apps/admin/src/pages/Attendance/AttendanceAdmin.helpers.tsx

@@ -0,0 +1,199 @@
+import dayjs from 'dayjs';
+import type { AttendanceSummary } from './attendance-workspace';
+import type { LessonAttendanceRecord } from './types';
+
+export type { AttendanceSummary } from './attendance-workspace';
+
+export const DEFAULT_ATTENDANCE_PERIODS = [
+  { periodKey: 'morning_reading', label: '早自习', startTime: '07:30', endTime: '08:30', sortOrder: 1, enabled: true },
+  { periodKey: 'morning', label: '早课', startTime: '09:00', endTime: '12:00', sortOrder: 2, enabled: true },
+  { periodKey: 'afternoon', label: '晚课', startTime: '14:00', endTime: '17:00', sortOrder: 3, enabled: true },
+  { periodKey: 'evening_study', label: '晚自习', startTime: '18:30', endTime: '21:00', sortOrder: 4, enabled: true },
+];
+
+export const STATUS_META: Record<
+  string,
+  { label: string; color: string; className: string; short: string }
+> = {
+  present: { label: '出勤', color: 'success', className: 'is-present', short: '勤' },
+  absent: { label: '缺勤', color: 'error', className: 'is-absent', short: '缺' },
+  leave: { label: '请假', color: 'processing', className: 'is-leave', short: '假' },
+  pending: { label: '待确认', color: 'default', className: 'is-pending', short: '待' },
+};
+
+export const ADMIN_CORRECTION_OPTIONS = [
+  { value: 'present', label: '正常' },
+  { value: 'leave', label: '请假' },
+  { value: 'absent', label: '缺勤' },
+];
+
+export interface ClassTeacherOption {
+  userId: number;
+  username: string | null;
+  name: string | null;
+  roleType: string;
+  subject: string | null;
+}
+
+export interface ClassOption {
+  classId: number;
+  className: string;
+  teachers?: ClassTeacherOption[];
+}
+
+export type AttendanceRecordItem = LessonAttendanceRecord;
+
+export interface HistoryScheduleOption {
+  id: number;
+  classId: number;
+  weekDay: number;
+  startTime: string;
+  endTime: string;
+  startDate: string;
+  endDate: string;
+  subject: string;
+  teacherId: number | null;
+  teacherName?: string | null;
+  teacherUsername?: string | null;
+  status: string;
+}
+
+export interface AlertItem {
+  studentId: number;
+  studentName: string;
+  studentNo: string;
+  className: string;
+  type: string;
+  count: number;
+  lastDate: string;
+}
+
+export interface AttendancePeriodConfigItem {
+  id?: number;
+  periodKey: string;
+  label: string;
+  startTime: string;
+  endTime: string;
+  sortOrder: number;
+  enabled: boolean;
+}
+
+export interface DingTalkSyncStatus {
+  lastPulledAt: string | null;
+  action: string | null;
+  username: string | null;
+  detail: string | null;
+}
+
+export const EMPTY_SUMMARY: AttendanceSummary = {
+  total: 0,
+  present: 0,
+  late: 0,
+  absent: 0,
+  leave: 0,
+  pending: 0,
+};
+
+export function displayAttendanceStatus(status?: string | null): string {
+  return status === 'pending' || !status ? 'absent' : status;
+}
+
+export function getTeacherDisplayName(teacher?: {
+  name?: string | null;
+  username?: string | null;
+}): string {
+  const name = teacher?.name?.trim();
+  if (name) return name;
+  return teacher?.username?.trim() || '未设置';
+}
+
+export function formatTeacherNames(
+  teachers: readonly { name?: string | null; username?: string | null }[],
+): string {
+  const names = [
+    ...new Set(
+      teachers
+        .map((teacher) => getTeacherDisplayName(teacher))
+        .filter((name) => name && name !== '未设置'),
+    ),
+  ];
+  return names.length > 0 ? names.join('、') : '未设置';
+}
+
+export function AttendanceStatusTag({ status }: { status: string }) {
+  const displayStatus = displayAttendanceStatus(status);
+  const meta = STATUS_META[displayStatus] ?? {
+    label: displayStatus,
+    color: 'default',
+    className: 'is-absent',
+    short: '?',
+  };
+  return (
+    <span className={`attendance-status ${meta.className}`}>
+      <span className="attendance-status__dot" />
+      {meta.label}
+    </span>
+  );
+}
+
+export interface AdminStudentPanel {
+  key: string;
+  studentId: number;
+  studentName: string;
+  studentNo: string;
+  className: string;
+  records: AttendanceRecordItem[];
+  statusBySession: Partial<Record<string, AttendanceRecordItem>>;
+  primaryStatus: string;
+  rate: number;
+  latestDate: string;
+}
+
+export const ADMIN_METRIC_META = [
+  { key: 'all', label: '出勤率', short: '率' },
+  { key: 'present', label: '正常', short: '正常' },
+  { key: 'leave', label: '请假', short: '请假' },
+  { key: 'absent', label: '缺勤', short: '缺勤' },
+];
+
+function pickPrimaryStatus(records: AttendanceRecordItem[]) {
+  const priority = ['absent', 'leave', 'present'];
+  return (
+    priority.find((item) =>
+      records.some((record) => displayAttendanceStatus(record.status) === item),
+    ) || 'absent'
+  );
+}
+
+export function buildAdminStudentPanels(records: AttendanceRecordItem[]): AdminStudentPanel[] {
+  const map = new Map<number, AdminStudentPanel>();
+  for (const record of records) {
+    const current = map.get(record.studentId) ?? {
+      key: String(record.studentId),
+      studentId: record.studentId,
+      studentName: record.student?.name || '未知学生',
+      studentNo: record.student?.studentNo?.trim() || '',
+      className: record.class?.name || '未关联班级',
+      records: [],
+      statusBySession: {},
+      primaryStatus: 'absent',
+      rate: 0,
+      latestDate: record.attendanceDate,
+    };
+    current.records.push(record);
+    if (!current.statusBySession[record.session]) current.statusBySession[record.session] = record;
+    if (dayjs(record.attendanceDate).isAfter(dayjs(current.latestDate))) {
+      current.latestDate = record.attendanceDate;
+    }
+    map.set(record.studentId, current);
+  }
+
+  return Array.from(map.values()).map((item) => {
+    const checked = item.records.filter((record) => record.status === 'present').length;
+    return {
+      ...item,
+      primaryStatus: pickPrimaryStatus(item.records),
+      rate: item.records.length > 0 ? Math.round((checked / item.records.length) * 100) : 0,
+    };
+  });
+}

apps/admin/src/pages/Attendance/AttendanceAdminColumns.tsx

@@ -0,0 +1,131 @@
+import { Avatar, Segmented, Tag } from 'antd';
+import type { ColumnsType } from 'antd/es/table';
+import dayjs from 'dayjs';
+import EditableCell from '../../components/EditableCell';
+import { getPunchDisplayInfo } from './attendance-workspace';
+import {
+  ADMIN_CORRECTION_OPTIONS,
+  AttendanceStatusTag,
+  displayAttendanceStatus,
+  type AttendanceRecordItem,
+} from './AttendanceAdmin.helpers';
+
+export interface AttendanceAdminColumnContext {
+  isMobile: boolean;
+  canEdit: boolean;
+  sessionMap: Record<string, string>;
+  correctingRecordId: number | null;
+  onSaveAdminRecordCell: (
+    record: AttendanceRecordItem,
+    field: 'status' | 'remark',
+    value: unknown,
+  ) => void;
+  onUpdateAdminRecordStatus: (record: AttendanceRecordItem, nextStatus: string) => void;
+}
+
+const buildAttendanceAdminDataColumns = (ctx: AttendanceAdminColumnContext) => {
+  const { isMobile, canEdit, sessionMap, onSaveAdminRecordCell } = ctx;
+  return [
+    {
+      title: '学生',
+      dataIndex: ['student', 'name'],
+      fixed: (isMobile ? undefined : 'left') as 'left' | undefined,
+      width: 150,
+      render: (name: string, record: AttendanceRecordItem) => (
+        <div className="student-cell">
+          <Avatar size={34}>{name?.slice(0, 1)}</Avatar>
+          <div>
+            <strong>{name || '-'}</strong>
+            <span>{record.class?.name || '未关联班级'}</span>
+          </div>
+        </div>
+      ),
+    },
+    { title: '日期', dataIndex: 'attendanceDate', width: 120 },
+    {
+      title: '时段',
+      dataIndex: 'session',
+      width: 110,
+      render: (value: string) => sessionMap[value] || value,
+    },
+    {
+      title: '状态',
+      dataIndex: 'status',
+      width: 105,
+      render: (value: string, record: AttendanceRecordItem) => (
+        <EditableCell
+          value={displayAttendanceStatus(value)}
+          editor="select"
+          options={ADMIN_CORRECTION_OPTIONS.map((item) => ({
+            value: String(item.value),
+            label: item.label,
+          }))}
+          disabled={!canEdit}
+          onSave={async (next) => {
+            onSaveAdminRecordCell(record, 'status', next);
+          }}
+        >
+          <AttendanceStatusTag status={displayAttendanceStatus(value)} />
+        </EditableCell>
+      ),
+    },
+    {
+      title: '签到来源',
+      width: 220,
+      render: (_: unknown, record: AttendanceRecordItem) => {
+        const info = getPunchDisplayInfo(record);
+        if (!info) return <span className="muted-text">—</span>;
+        return (
+          <div className="punch-device-cell">
+            <Tag color={info.machine ? 'green' : 'blue'}>{info.label}</Tag>
+            {info.detail && <strong>{info.detail}</strong>}
+            {info.time && <span>{dayjs(info.time).format('HH:mm:ss')}</span>}
+          </div>
+        );
+      },
+    },
+    {
+      title: '备注',
+      dataIndex: 'remark',
+      ellipsis: true,
+      render: (value: string | null, record: AttendanceRecordItem) => (
+        <EditableCell
+          value={value}
+          editor="textarea"
+          disabled={!canEdit}
+          onSave={async (next) => {
+            onSaveAdminRecordCell(record, 'remark', next);
+          }}
+        >
+          {value || <span className="muted-text">—</span>}
+        </EditableCell>
+      ),
+    },
+  ] as ColumnsType<AttendanceRecordItem>;
+};
+
+const buildAttendanceAdminActionColumn = (ctx: AttendanceAdminColumnContext) => {
+  const { isMobile, correctingRecordId, onUpdateAdminRecordStatus } = ctx;
+  return {
+    title: '操作',
+    key: 'action',
+    fixed: (isMobile ? undefined : 'right') as 'right' | undefined,
+    width: 220,
+    render: (_: unknown, record: AttendanceRecordItem) => (
+      <Segmented
+        size="small"
+        className="attendance-correction-segment"
+        options={ADMIN_CORRECTION_OPTIONS}
+        value={displayAttendanceStatus(record.status)}
+        disabled={correctingRecordId === record.id}
+        onChange={(value) => void onUpdateAdminRecordStatus(record, String(value))}
+      />
+    ),
+  };
+};
+
+export const buildAttendanceAdminColumns = (ctx: AttendanceAdminColumnContext) => {
+  const dataColumns = buildAttendanceAdminDataColumns(ctx);
+  const actionColumn = ctx.canEdit ? [buildAttendanceAdminActionColumn(ctx)] : [];
+  return [...dataColumns, ...actionColumn] as ColumnsType<AttendanceRecordItem>;
+};

apps/admin/src/pages/Attendance/AttendanceAdminHeader.tsx

@@ -0,0 +1,275 @@
+import React from 'react';
+import {
+  Avatar,
+  Button,
+  DatePicker,
+  Select,
+  Spin,
+  Tooltip,
+} from 'antd';
+import {
+  ExportOutlined,
+  FileSearchOutlined,
+  ReloadOutlined,
+  ScheduleOutlined,
+  UndoOutlined,
+  WarningFilled,
+} from '@ant-design/icons';
+import dayjs, { type Dayjs } from 'dayjs';
+import PermissionButton from '../../components/PermissionButton';
+import {
+  ADMIN_METRIC_META,
+  STATUS_META,
+  type AlertItem,
+  type AttendanceSummary,
+  type ClassOption,
+  type DingTalkSyncStatus,
+  type HistoryScheduleOption,
+} from './AttendanceAdmin.helpers';
+
+export const AttendanceAdminHeader: React.FC<{
+  syncStatus: DingTalkSyncStatus | null;
+  canEdit: boolean;
+  refreshingDingTalk: boolean;
+  onOpenPeriodConfig: () => void;
+  onRefreshDingTalk: () => void;
+  onExport: () => void;
+  attendanceDate: Dayjs | null;
+  onDateChange: (date: Dayjs | null) => void;
+  classId?: number;
+  onClassChange: (value?: number) => void;
+  classOptions: ClassOption[];
+  effectiveScheduleId?: number;
+  onScheduleChange: (value?: number) => void;
+  scheduleOptions: HistoryScheduleOption[];
+  scheduleOptionsLoading: boolean;
+  session?: string;
+  onSessionChange: (value?: string) => void;
+  sessionOptions: Array<{ value: string; label: string }>;
+  onReset: () => void;
+  onQuery: () => void;
+  selectedClass: string;
+  dateLabel: string;
+  visibleStudentCount: number;
+  total: number;
+  headTeacherNames: string;
+  lifeTeacherNames: string;
+  subjectTeacherNames: string;
+  attendanceRate: number;
+  summary: AttendanceSummary;
+  metricFilter: string;
+  onMetricFilterChange: (key: string) => void;
+  alerts: AlertItem[];
+}> = ({
+  syncStatus,
+  canEdit,
+  refreshingDingTalk,
+  onOpenPeriodConfig,
+  onRefreshDingTalk,
+  onExport,
+  attendanceDate,
+  onDateChange,
+  classId,
+  onClassChange,
+  classOptions,
+  effectiveScheduleId,
+  onScheduleChange,
+  scheduleOptions,
+  scheduleOptionsLoading,
+  session,
+  onSessionChange,
+  sessionOptions,
+  onReset,
+  onQuery,
+  selectedClass,
+  dateLabel,
+  visibleStudentCount,
+  total,
+  headTeacherNames,
+  lifeTeacherNames,
+  subjectTeacherNames,
+  attendanceRate,
+  summary,
+  metricFilter,
+  onMetricFilterChange,
+  alerts,
+}) => {
+  return (
+    <>
+      <header className="student-center-topbar">
+        <div className="student-center-title">
+          <h1>学生考勤中心</h1>
+          <span>班级考勤总览</span>
+        </div>
+        <div className="student-center-actions">
+          <Tooltip title={syncStatus?.detail || syncStatus?.action || '暂无钉钉拉取记录'}>
+            <span className="student-sync-status">
+              <i />
+              {syncStatus?.lastPulledAt
+                ? `最近拉取钉钉 ${dayjs(syncStatus.lastPulledAt).format('YYYY-MM-DD HH:mm')}`
+                : '暂无钉钉拉取记录'}
+            </span>
+          </Tooltip>
+          {canEdit && (
+            <Button icon={<ScheduleOutlined />} onClick={onOpenPeriodConfig}>
+              时段配置
+            </Button>
+          )}
+          <PermissionButton
+            permission="attendance:create"
+            icon={<ReloadOutlined />}
+            loading={refreshingDingTalk}
+            onClick={onRefreshDingTalk}
+          >
+            刷新钉钉考勤
+          </PermissionButton>
+          <PermissionButton permission="attendance:export" icon={<ExportOutlined />} onClick={onExport}>
+            导出当前报表
+          </PermissionButton>
+        </div>
+      </header>
+
+      <section className="student-filter-panel" aria-label="考勤筛选">
+        <div className="student-filter-field student-filter-field--date">
+          <label>日期</label>
+          <DatePicker
+            allowClear={false}
+            value={attendanceDate}
+            disabledDate={(current) => current.isAfter(dayjs(), 'day')}
+            onChange={onDateChange}
+          />
+        </div>
+        <div className="student-filter-field">
+          <label>班级</label>
+          <Select
+            allowClear
+            showSearch
+            optionFilterProp="label"
+            placeholder="全部班级"
+            value={classId}
+            onChange={onClassChange}
+            options={classOptions.map((item) => ({ value: item.classId, label: item.className }))}
+          />
+        </div>
+        <div className="student-filter-field">
+          <label>科目</label>
+          <Select
+            allowClear
+            showSearch
+            optionFilterProp="label"
+            placeholder={classId ? '全部科目' : '请先选择班级'}
+            value={effectiveScheduleId}
+            loading={scheduleOptionsLoading}
+            disabled={!classId || !attendanceDate}
+            notFoundContent={scheduleOptionsLoading ? <Spin size="small" /> : '当前日期没有排课'}
+            onChange={onScheduleChange}
+            options={scheduleOptions.map((schedule) => ({
+              value: schedule.id,
+              label: `${schedule.subject}（${schedule.startTime}-${schedule.endTime}）`,
+            }))}
+          />
+        </div>
+        <div className="student-filter-field">
+          <label>任课老师</label>
+          <Select disabled placeholder="全部老师" />
+        </div>
+        <div className="student-filter-field">
+          <label>时段</label>
+          <Select
+            allowClear
+            placeholder="全部时段"
+            value={session}
+            onChange={onSessionChange}
+            options={sessionOptions}
+          />
+        </div>
+        <div className="student-filter-actions">
+          <Button icon={<UndoOutlined />} onClick={onReset}>
+            重置
+          </Button>
+          <Button type="primary" icon={<FileSearchOutlined />} onClick={onQuery}>
+            查询
+          </Button>
+        </div>
+      </section>
+
+      <section className="student-class-overview" aria-label="班级考勤汇总">
+        <div className="student-class-identity">
+          <div className="student-class-heading">
+            <span className="student-overview-kicker">班级考勤概览</span>
+            <h2>{selectedClass}</h2>
+            <p>
+              {dateLabel} · 当前展示 {visibleStudentCount} 名学生 / {total} 条记录
+            </p>
+          </div>
+          <div className="student-teacher-list" aria-label="筛选上下文">
+            <div className="student-teacher-item">
+              <Avatar>班</Avatar>
+              <div>
+                <span>班主任</span>
+                <strong>{headTeacherNames}</strong>
+              </div>
+            </div>
+            <div className="student-teacher-item">
+              <Avatar>生</Avatar>
+              <div>
+                <span>生活老师</span>
+                <strong>{lifeTeacherNames}</strong>
+              </div>
+            </div>
+            <div className="student-teacher-item">
+              <Avatar>任</Avatar>
+              <div>
+                <span>任课老师</span>
+                <strong>{subjectTeacherNames}</strong>
+              </div>
+            </div>
+          </div>
+        </div>
+        <div className="student-metric-strip">
+          {ADMIN_METRIC_META.map((metric) => {
+            const value =
+              metric.key === 'all'
+                ? `${attendanceRate}%`
+                : metric.key === 'absent'
+                  ? summary.absent + summary.pending
+                  : (summary[metric.key as keyof AttendanceSummary] ?? 0);
+            const meta = STATUS_META[metric.key] ?? { className: 'is-present' };
+            return (
+              <button
+                type="button"
+                key={metric.key}
+                className={`student-metric-card ${metricFilter === metric.key ? 'active' : ''}`}
+                onClick={() => onMetricFilterChange(metric.key)}
+              >
+                <span className={`student-metric-icon ${meta.className}`}>{metric.short}</span>
+                <span className="student-metric-copy">
+                  <strong>{value}</strong>
+                  <small>{metric.label}</small>
+                </span>
+              </button>
+            );
+          })}
+        </div>
+      </section>
+
+      {alerts.length > 0 && (
+        <div className="archive-alert">
+          <WarningFilled />
+          <div>
+            <strong>{alerts.length} 名学生存在连续异常</strong>
+            <span>建议优先核查最近 14 天的缺勤记录</span>
+          </div>
+          <Tooltip
+            title={alerts
+              .slice(0, 5)
+              .map((item) => `${item.studentName}：${item.type}${item.count}次`)
+              .join('；')}
+          >
+            <Button type="link">查看摘要</Button>
+          </Tooltip>
+        </div>
+      )}
+    </>
+  );
+};

apps/admin/src/pages/Attendance/AttendanceAdminModals.tsx

@@ -0,0 +1,194 @@
+import React from 'react';
+import {
+  Alert,
+  Avatar,
+  Button,
+  Drawer,
+  Form,
+  Input,
+  Modal,
+  Segmented,
+  Select,
+} from 'antd';
+import { UndoOutlined } from '@ant-design/icons';
+import dayjs from 'dayjs';
+import {
+  ADMIN_CORRECTION_OPTIONS,
+  AttendanceStatusTag,
+  displayAttendanceStatus,
+  type AdminStudentPanel,
+  type AttendancePeriodConfigItem,
+  type AttendanceRecordItem,
+} from './AttendanceAdmin.helpers';
+
+export const PeriodConfigModal: React.FC<{
+  open: boolean;
+  form: ReturnType<typeof Form.useForm<{ periods: AttendancePeriodConfigItem[] }>>[0];
+  onOk: () => void;
+  onCancel: () => void;
+  onReset: () => void;
+}> = ({ open, form, onOk, onCancel, onReset }) => {
+  return (
+    <Modal
+      open={open}
+      title="考勤时段配置"
+      okText="保存配置"
+      width={860}
+      className="attendance-period-modal"
+      onOk={onOk}
+      onCancel={onCancel}
+      footer={(_, { OkBtn, CancelBtn }) => (
+        <>
+          <Button icon={<UndoOutlined />} onClick={onReset}>
+            恢复默认
+          </Button>
+          <CancelBtn />
+          <OkBtn />
+        </>
+      )}
+    >
+      <Alert
+        type="info"
+        showIcon
+        title="按课程开始时间自动匹配时段"
+        description="默认：07:30-08:30 早自习，09:00-12:00 早课，14:00-17:00 晚课，18:30-21:00 晚自习。"
+        style={{ marginBottom: 16 }}
+      />
+      <Form form={form} layout="vertical">
+        <Form.List name="periods">
+          {(fields, { add, remove }) => (
+            <div className="attendance-period-editor">
+              {fields.map((field) => (
+                <div className="attendance-period-row" key={field.key}>
+                  <Form.Item name={[field.name, 'label']} label="显示名称" rules={[{ required: true, message: '请输入名称' }]}>
+                    <Input placeholder="早课" />
+                  </Form.Item>
+                  <Form.Item name={[field.name, 'periodKey']} label="类型标识" rules={[{ required: true, message: '请输入标识' }]}>
+                    <Input placeholder="morning" />
+                  </Form.Item>
+                  <Form.Item name={[field.name, 'startTime']} label="开始时间" rules={[{ required: true, message: '请选择开始时间' }]}>
+                    <Input type="time" />
+                  </Form.Item>
+                  <Form.Item name={[field.name, 'endTime']} label="结束时间" rules={[{ required: true, message: '请选择结束时间' }]}>
+                    <Input type="time" />
+                  </Form.Item>
+                  <Form.Item name={[field.name, 'enabled']} label="状态">
+                    <Select
+                      options={[
+                        { value: true, label: '启用' },
+                        { value: false, label: '停用' },
+                      ]}
+                    />
+                  </Form.Item>
+                  <Button danger className="attendance-period-row__delete" onClick={() => remove(field.name)}>
+                    删除
+                  </Button>
+                </div>
+              ))}
+              <Button
+                block
+                type="dashed"
+                className="attendance-period-add"
+                onClick={() =>
+                  add({
+                    periodKey: '',
+                    label: '',
+                    startTime: '00:00',
+                    endTime: '00:30',
+                    enabled: true,
+                  })
+                }
+              >
+                添加时段
+              </Button>
+            </div>
+          )}
+        </Form.List>
+      </Form>
+    </Modal>
+  );
+};
+
+export const StudentDetailDrawer: React.FC<{
+  student: AdminStudentPanel | null;
+  isMobile: boolean;
+  canEdit: boolean;
+  sessionMap: Record<string, string>;
+  correctingRecordId: number | null;
+  sortAttendanceRecords: (items: readonly AttendanceRecordItem[]) => AttendanceRecordItem[];
+  onClose: () => void;
+  onUpdateAdminRecordStatus: (record: AttendanceRecordItem, nextStatus: string) => void;
+}> = ({
+  student,
+  isMobile,
+  canEdit,
+  sessionMap,
+  correctingRecordId,
+  sortAttendanceRecords,
+  onClose,
+  onUpdateAdminRecordStatus,
+}) => {
+  return (
+    <Drawer
+      open={Boolean(student)}
+      onClose={onClose}
+      size={isMobile ? '100%' : 520}
+      title="学生考勤明细"
+      className="student-detail-drawer"
+    >
+      {student && (
+        <div className="student-detail-panel">
+          <section className="student-detail-profile">
+            <Avatar size={54}>{student.studentName.slice(0, 1)}</Avatar>
+            <div>
+              <h4>{student.studentName}</h4>
+              <p>
+                {student.className}
+                {student.studentNo ? ` · 学号 ${student.studentNo}` : ''}
+              </p>
+            </div>
+            <div className="student-detail-rate">
+              <strong>{student.rate}%</strong>
+              <span>累计出勤率</span>
+            </div>
+          </section>
+          <section className="student-detail-rates">
+            {sortAttendanceRecords(student.records).map((record) => {
+              const normal = record.status === 'present';
+              return (
+                <div key={record.id}>
+                  <strong>{normal ? '100%' : '0%'}</strong>
+                  <span>{sessionMap[record.session] || record.session}</span>
+                </div>
+              );
+            })}
+          </section>
+          <section className="student-detail-section">
+            <h5>当天打卡时间</h5>
+            <div className="student-detail-timeline">
+              {sortAttendanceRecords(student.records).map((record) => (
+                <div key={record.id}>
+                  <span>{sessionMap[record.session] || record.session}</span>
+                  <AttendanceStatusTag status={displayAttendanceStatus(record.status)} />
+                  <strong>
+                    {record.punchTime ? dayjs(record.punchTime).format('HH:mm:ss') : '未记录'}
+                  </strong>
+                  {canEdit && (
+                    <Segmented
+                      size="small"
+                      className="attendance-correction-segment"
+                      options={ADMIN_CORRECTION_OPTIONS}
+                      value={displayAttendanceStatus(record.status)}
+                      disabled={correctingRecordId === record.id}
+                      onChange={(value) => void onUpdateAdminRecordStatus(record, String(value))}
+                    />
+                  )}
+                </div>
+              ))}
+            </div>
+          </section>
+        </div>
+      )}
+    </Drawer>
+  );
+};

apps/admin/src/pages/Attendance/AttendanceAdminWorkspace.tsx

@@ -0,0 +1,164 @@
+import React from 'react';
+import { Card, Empty, Input, Spin, Table } from 'antd';
+import { ExportOutlined } from '@ant-design/icons';
+import PermissionButton from '../../components/PermissionButton';
+import {
+  ADMIN_METRIC_META,
+  STATUS_META,
+  displayAttendanceStatus,
+  type AdminStudentPanel,
+  type AttendanceRecordItem,
+} from './AttendanceAdmin.helpers';
+
+export const AttendanceAdminWorkspace: React.FC<{
+  metricFilter: string;
+  studentSearch: string;
+  onSearchChange: (value: string) => void;
+  onExport: () => void;
+  visibleStudents: AdminStudentPanel[];
+  loading: boolean;
+  selectedStudentId?: number;
+  onSelectStudent: (student: AdminStudentPanel) => void;
+  sortAttendanceRecords: (items: readonly AttendanceRecordItem[]) => AttendanceRecordItem[];
+  sessionMap: Record<string, string>;
+  records: AttendanceRecordItem[];
+  columns: any[];
+  page: number;
+  pageSize: number;
+  total: number;
+  onPageChange: (page: number, pageSize: number) => void;
+}> = ({
+  metricFilter,
+  studentSearch,
+  onSearchChange,
+  onExport,
+  visibleStudents,
+  loading,
+  selectedStudentId,
+  onSelectStudent,
+  sortAttendanceRecords,
+  sessionMap,
+  records,
+  columns,
+  page,
+  pageSize,
+  total,
+  onPageChange,
+}) => {
+  return (
+    <>
+      <section className="student-workspace">
+        <header className="student-workspace-header">
+          <div>
+            <h3>班级学生考勤</h3>
+            <span>
+              {metricFilter === 'all'
+                ? `显示全部 ${visibleStudents.length} 名学生`
+                : `筛出 ${
+                    ADMIN_METRIC_META.find((item) => item.key === metricFilter)?.label || ''
+                  }相关 ${visibleStudents.length} 名学生`}
+            </span>
+          </div>
+          <div className="student-workspace-tools">
+            <Input.Search
+              allowClear
+              placeholder="搜索姓名或学号"
+              value={studentSearch}
+              onChange={(event) => onSearchChange(event.target.value)}
+            />
+            <PermissionButton
+              permission="attendance:export"
+              icon={<ExportOutlined />}
+              onClick={onExport}
+            >
+              导出
+            </PermissionButton>
+          </div>
+        </header>
+        <div className="student-legend">
+          <span>
+            <i className="is-present" />
+            正常
+          </span>
+          <span>
+            <i className="is-leave" />
+            请假
+          </span>
+          <span>
+            <i className="is-absent" />
+            缺勤
+          </span>
+          <em>仅显示当天已生成考勤的课程/时段，不再为无课时段补默认缺勤</em>
+        </div>
+        <Spin spinning={loading}>
+          {visibleStudents.length === 0 ? (
+            <Empty
+              image={Empty.PRESENTED_IMAGE_SIMPLE}
+              description="未找到匹配学生，请调整筛选条件或搜索关键词"
+            />
+          ) : (
+            <div className="student-card-grid">
+              {visibleStudents.map((student) => (
+                <button
+                  type="button"
+                  key={student.key}
+                  className={`student-attendance-card ${
+                    selectedStudentId === student.studentId ? 'selected' : ''
+                  }`}
+                  onClick={() => onSelectStudent(student)}
+                >
+                  <span className="student-attendance-head">
+                    <strong>{student.studentName}</strong>
+                    {student.studentNo && <small>学号 {student.studentNo}</small>}
+                  </span>
+                  <span className="student-status-blocks">
+                    {sortAttendanceRecords(student.records).map((record) => {
+                      const currentStatus = displayAttendanceStatus(record.status);
+                      const meta = STATUS_META[currentStatus] ?? STATUS_META.absent;
+                      const sessionLabel = sessionMap[record.session] || record.session;
+                      return (
+                        <span
+                          key={record.id}
+                          className={`student-status-block ${meta.className}`}
+                          title={`${sessionLabel}：${meta.label}`}
+                        >
+                          {meta.label === '出勤' ? '正常' : meta.label}
+                        </span>
+                      );
+                    })}
+                  </span>
+                </button>
+              ))}
+            </div>
+          )}
+        </Spin>
+      </section>
+
+      <Card className="student-record-card" bordered={false} title="原始考勤明细">
+        <Table<AttendanceRecordItem>
+          rowKey="id"
+          columns={columns}
+          dataSource={records}
+          loading={loading}
+          scroll={{ x: 'max-content' }}
+          pagination={{
+            current: page,
+            pageSize,
+            total,
+            showSizeChanger: true,
+            showTotal: (value) => `共 ${value} 条历史记录`,
+            onChange: onPageChange,
+          }}
+          locale={{
+            emptyText: (
+              <Empty
+                image={Empty.PRESENTED_IMAGE_SIMPLE}
+                description="当前条件下没有历史考勤记录"
+              />
+            ),
+          }}
+        />
+      </Card>
+    </>
+  );
+};

apps/admin/src/pages/Attendance/LessonAttendanceDetail.tsx

@@ -11,6 +11,7 @@ import {
 } from './attendance-workspace';
 import type { LessonAttendanceRecord, LessonAttendanceSchedule } from './types';
 import { usePermission } from '../../hooks/usePermission';
+import { getErrorMessage } from '../../utils/error';
 
 interface LessonAttendanceSession {
   id: number;
@@ -90,10 +91,6 @@ const LessonAttendanceDetail: React.FC<LessonAttendanceDetailProps> = ({
     if (!schedule) return;
     let cancelled = false;
     setLoadedSchedule(schedule);
-    setSession(null);
-    setRecords([]);
-    setKeyword('');
-    setFilter('all');
     setLoading(true);
     const date = dayjs().format('YYYY-MM-DD');
     void api
@@ -109,7 +106,7 @@ const LessonAttendanceDetail: React.FC<LessonAttendanceDetailProps> = ({
       })
       .catch((error: unknown) => {
         if (cancelled) return;
-        message.error((error as { message?: string })?.message || '加载本节课考勤失败');
+        message.error(getErrorMessage(error, '加载本节课考勤失败'));
       })
       .finally(() => {
         if (!cancelled) setLoading(false);
@@ -130,7 +127,7 @@ const LessonAttendanceDetail: React.FC<LessonAttendanceDetailProps> = ({
       setRecords((items) =>
         items.map((item) => (item.id === record.id ? { ...item, status: previous } : item)),
       );
-      message.error((error as { message?: string })?.message || '更新考勤失败');
+      message.error(getErrorMessage(error, '更新考勤失败'));
     }
   }, []);
 

apps/admin/src/pages/Attendance/admin.tsx

@@ -0,0 +1,580 @@
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { useApiMutation } from '../../hooks/useApiMutation';
+import { validateResponse } from '../../utils/validate';
+import {
+  attendanceAlertsSchema,
+  attendanceClassOptionsSchema,
+  attendanceRecordsResponseSchema,
+  attendanceScheduleOptionsSchema,
+  attendancePeriodsSchema,
+  attendanceSummarySchema,
+  dingTalkSyncStatusSchema,
+} from '../../api/schemas';
+import { Form, Grid } from 'antd';
+import dayjs, { type Dayjs } from 'dayjs';
+import api from '../../api';
+import { message } from '../../ui/app-message';
+import { useUserStore } from '../../store/user/userStore';
+import type { AttendanceSummary } from './attendance-workspace';
+import { getErrorMessage } from '../../utils/error';
+import { AttendanceAdminHeader } from './AttendanceAdminHeader';
+import { buildAttendanceAdminColumns } from './AttendanceAdminColumns';
+import { PeriodConfigModal, StudentDetailDrawer } from './AttendanceAdminModals';
+import { AttendanceAdminWorkspace } from './AttendanceAdminWorkspace';
+import {
+  DEFAULT_ATTENDANCE_PERIODS,
+  EMPTY_SUMMARY,
+  buildAdminStudentPanels,
+  displayAttendanceStatus,
+  formatTeacherNames,
+  getTeacherDisplayName,
+  type AdminStudentPanel,
+  type AlertItem,
+  type AttendancePeriodConfigItem,
+  type AttendanceRecordItem,
+  type ClassOption,
+  type DingTalkSyncStatus,
+  type HistoryScheduleOption,
+} from './AttendanceAdmin.helpers';
+
+export const AdminAttendanceArchive: React.FC<{ canEdit: boolean }> = ({ canEdit }) => {
+  const screens = Grid.useBreakpoint();
+  const isMobile = !screens.sm;
+  const [periodModalOpen, setPeriodModalOpen] = useState(false);
+  const [periodForm] = Form.useForm<{ periods: AttendancePeriodConfigItem[] }>();
+  const [refreshingDingTalk, setRefreshingDingTalk] = useState(false);
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(48);
+  const [classId, setClassId] = useState<number>();
+  const [attendanceDate, setAttendanceDate] = useState<Dayjs | null>(dayjs());
+  const [status, setStatus] = useState<string>();
+  const [session, setSession] = useState<string>();
+  const [scheduleId, setScheduleId] = useState<number>();
+  const [metricFilter, setMetricFilter] = useState('all');
+  const [studentSearch, setStudentSearch] = useState('');
+  const [selectedStudent, setSelectedStudent] = useState<AdminStudentPanel | null>(null);
+  const [correctingRecordId, setCorrectingRecordId] = useState<number | null>(null);
+  const queryClient = useQueryClient();
+  const recordQueryKey = [
+    'attendance',
+    'records',
+    page,
+    pageSize,
+    classId,
+    attendanceDate,
+    status,
+    session,
+    scheduleId,
+  ] as const;
+
+  const { data: classOptions = [] } = useQuery<ClassOption[]>({
+    queryKey: ['attendance', 'meta', 'classes'],
+    queryFn: async () => {
+      try {
+        return validateResponse<ClassOption[]>(
+          attendanceClassOptionsSchema,
+          await api.get<ClassOption[]>('/attendance-records/classes'),
+        );
+      } catch {
+        return [];
+      }
+    },
+  });
+  const { data: alerts = [] } = useQuery<AlertItem[]>({
+    queryKey: ['attendance', 'meta', 'alerts'],
+    queryFn: async () => {
+      try {
+        return validateResponse<AlertItem[]>(
+          attendanceAlertsSchema,
+          await api.get<AlertItem[]>('/attendance-records/alerts'),
+        );
+      } catch {
+        return [];
+      }
+    },
+  });
+  const { data: periods = DEFAULT_ATTENDANCE_PERIODS } = useQuery<AttendancePeriodConfigItem[]>({
+    queryKey: ['attendance', 'meta', 'periods'],
+    queryFn: async () => {
+      try {
+        return validateResponse<AttendancePeriodConfigItem[]>(
+          attendancePeriodsSchema,
+          await api.get<AttendancePeriodConfigItem[]>('/attendance-period-configs'),
+        );
+      } catch {
+        return DEFAULT_ATTENDANCE_PERIODS;
+      }
+    },
+  });
+  const {
+    data: scheduleOptions = [],
+    isFetching: scheduleOptionsFetching,
+  } = useQuery<HistoryScheduleOption[]>({
+    queryKey: ['attendance', 'schedules', classId, attendanceDate],
+    enabled: !!classId && !!attendanceDate,
+    queryFn: async () => {
+      try {
+        return validateResponse<HistoryScheduleOption[]>(
+          attendanceScheduleOptionsSchema,
+          await api.get<HistoryScheduleOption[]>('/attendance-records/schedules', {
+            params: { classId, date: attendanceDate!.format('YYYY-MM-DD') },
+          }),
+        );
+      } catch (error: unknown) {
+        message.error(getErrorMessage(error, '加载班级科目失败'));
+        return [];
+      }
+    },
+  });
+  const scheduleOptionsLoading = scheduleOptionsFetching;
+  const effectiveScheduleId =
+    scheduleId && scheduleOptions.some((schedule) => schedule.id === scheduleId)
+      ? scheduleId
+      : undefined;
+
+  useEffect(() => {
+    periodForm.setFieldsValue({ periods });
+  }, [periods, periodForm]);
+
+  const enabledPeriods = useMemo(
+    () => periods.filter((period) => period.enabled).sort((a, b) => a.sortOrder - b.sortOrder),
+    [periods],
+  );
+  const sessionOptions = useMemo(
+    () => enabledPeriods.map((period) => ({ value: period.periodKey, label: period.label })),
+    [enabledPeriods],
+  );
+  const sessionMap = useMemo(
+    () => Object.fromEntries(periods.map((period) => [period.periodKey, period.label])),
+    [periods],
+  );
+  const periodOrder = useMemo(
+    () => new Map(periods.map((period, index) => [period.periodKey, index])),
+    [periods],
+  );
+  const sortAttendanceRecords = useCallback(
+    (items: readonly AttendanceRecordItem[]) =>
+      [...items].sort((a, b) => {
+        const periodDiff =
+          (periodOrder.get(a.session) ?? Number.MAX_SAFE_INTEGER) -
+          (periodOrder.get(b.session) ?? Number.MAX_SAFE_INTEGER);
+        if (periodDiff !== 0) return periodDiff;
+        return (a.punchTime || a.createdAt || '').localeCompare(b.punchTime || b.createdAt || '');
+      }),
+    [periodOrder],
+  );
+  const openPeriodConfig = () => {
+    periodForm.setFieldsValue({ periods });
+    setPeriodModalOpen(true);
+  };
+
+  const savePeriodConfig = async () => {
+    try {
+      const values = await periodForm.validateFields();
+      const payload = {
+        periods: values.periods.map((period, index) => ({
+          ...period,
+          sortOrder: index + 1,
+          enabled: period.enabled ?? true,
+        })),
+      };
+      const data = await savePeriodConfigMutation.mutateAsync(payload);
+      setPeriodModalOpen(false);
+      message.success('考勤时段配置已保存');
+      if (session && !data.some((period) => period.enabled && period.periodKey === session)) {
+        setSession(undefined);
+      }
+    } catch {
+      // 校验错误静默，接口错误由 useApiMutation 统一提示
+    }
+  };
+
+  const resetPeriodConfig = async () => {
+    try {
+      await resetPeriodConfigMutation.mutateAsync();
+      message.success('已恢复默认考勤时段');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    }
+  };
+
+  const buildParams = useCallback(
+    (withPagination = true) => {
+      const params: Record<string, string | number> = {};
+      if (withPagination) Object.assign(params, { page, pageSize });
+      if (classId) params.classId = classId;
+      if (attendanceDate) {
+        const selectedDate = attendanceDate.format('YYYY-MM-DD');
+        params.dateFrom = selectedDate;
+        params.dateTo = selectedDate;
+      }
+      if (status) params.status = status;
+      if (session) params.session = session;
+      if (effectiveScheduleId) params.scheduleId = effectiveScheduleId;
+      return params;
+    },
+    [page, pageSize, classId, attendanceDate, status, session, scheduleId],
+  );
+
+  const { data: syncStatus = null, refetch: refetchSyncStatus } = useQuery<DingTalkSyncStatus | null>({
+    queryKey: ['attendance', 'sync-status'],
+    queryFn: async () => {
+      try {
+        return validateResponse<DingTalkSyncStatus>(
+          dingTalkSyncStatusSchema,
+          await api.get<DingTalkSyncStatus>('/attendance-records/dingtalk-sync-status'),
+        );
+      } catch {
+        return null;
+      }
+    },
+  });
+  const loadSyncStatus = useCallback(() => refetchSyncStatus(), [refetchSyncStatus]);
+
+  const {
+    data: recordQuery = { records: [], total: 0, summary: EMPTY_SUMMARY },
+    isFetching: recordsFetching,
+    refetch: refetchRecords,
+  } = useQuery<{
+    records: AttendanceRecordItem[];
+    total: number;
+    summary: AttendanceSummary;
+  }>({
+    queryKey: recordQueryKey,
+    queryFn: async () => {
+      try {
+        const [recordData, summaryData] = await Promise.all([
+          api.get<{ list: AttendanceRecordItem[]; total: number }>('/attendance-records', {
+            params: buildParams(true),
+          }),
+          api.get<AttendanceSummary>('/attendance-records/summary', {
+            params: buildParams(false),
+          }),
+        ]);
+        const validatedRecords = validateResponse<{
+          list: AttendanceRecordItem[];
+          total: number;
+        }>(attendanceRecordsResponseSchema, recordData);
+        const validatedSummary = validateResponse<AttendanceSummary>(
+          attendanceSummarySchema,
+          summaryData,
+        );
+        return {
+          records: validatedRecords.list,
+          total: validatedRecords.total,
+          summary: { ...EMPTY_SUMMARY, ...validatedSummary },
+        };
+      } catch (error: unknown) {
+        message.error(getErrorMessage(error, '加载学生考勤失败'));
+        return { records: [], total: 0, summary: EMPTY_SUMMARY };
+      }
+    },
+  });
+  const records = recordQuery.records;
+  const total = recordQuery.total;
+  const summary = recordQuery.summary;
+  const loading = recordsFetching;
+  const loadRecords = useCallback(() => refetchRecords(), [refetchRecords]);
+
+  const savePeriodConfigMutation = useApiMutation(
+    async (payload: Record<string, unknown>) =>
+      api.put<AttendancePeriodConfigItem[]>('/attendance-period-configs', payload),
+    { invalidate: [['attendance', 'meta', 'periods']] },
+  );
+  const resetPeriodConfigMutation = useApiMutation(
+    async () => api.post<AttendancePeriodConfigItem[]>('/attendance-period-configs/reset'),
+    { invalidate: [['attendance', 'meta', 'periods']] },
+  );
+  const refreshDingTalkMutation = useApiMutation(
+    async (payload: Record<string, unknown>) =>
+      api.post<{
+        refreshed: number;
+        imported: number;
+        matched: number;
+        errors: string[];
+      }>('/attendance-records/refresh-dingtalk', payload),
+    { invalidate: [['attendance', 'records'], ['attendance', 'sync-status']] },
+  );
+  const updateStatusMutation = useApiMutation(
+    async ({ id, status }: { id: number; status: string }) =>
+      api.put(`/attendance-records/${id}`, { status }),
+    { invalidate: [['attendance', 'records']] },
+  );
+  const saveRecordCellMutation = useApiMutation(
+    async ({ id, field, value }: { id: number; field: string; value: unknown }) =>
+      api.put(`/attendance-records/${id}`, { [field]: value }),
+    { invalidate: [['attendance', 'records']] },
+  );
+
+  const refreshDingTalkAttendance = useCallback(async () => {
+    if (!attendanceDate) {
+      message.warning('请先选择日期');
+      return;
+    }
+    if (attendanceDate.isAfter(dayjs(), 'day')) {
+      message.warning('不能查看或刷新未来日期的考勤');
+      return;
+    }
+    setRefreshingDingTalk(true);
+    try {
+      const result = await refreshDingTalkMutation.mutateAsync({
+        date: attendanceDate.format('YYYY-MM-DD'),
+        classId,
+        session,
+      });
+      if (result.errors.length > 0) {
+        message.warning(result.errors[0]);
+      } else {
+        message.success(`已刷新 ${result.refreshed} 节课程考勤`);
+      }
+      await Promise.all([loadRecords(), loadSyncStatus()]);
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    } finally {
+      setRefreshingDingTalk(false);
+    }
+  }, [attendanceDate, classId, loadRecords, loadSyncStatus, session]);
+
+  const resetFilters = () => {
+    setClassId(undefined);
+    setAttendanceDate(dayjs());
+    setStatus(undefined);
+    setSession(undefined);
+    setScheduleId(undefined);
+    setMetricFilter('all');
+    setStudentSearch('');
+    setPage(1);
+  };
+
+  const handleExport = useCallback(() => {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(buildParams(false))) params.set(key, String(value));
+    const token = useUserStore.getState().token;
+    fetch(`/api/attendance-records/export?${params.toString()}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+      .then((response) => {
+        if (!response.ok) throw new Error('导出失败');
+        return response.blob();
+      })
+      .then((blob) => {
+        const url = URL.createObjectURL(blob);
+        const anchor = document.createElement('a');
+        anchor.href = url;
+        anchor.download = `学生考勤-${dayjs().format('YYYYMMDD')}.xlsx`;
+        anchor.click();
+        URL.revokeObjectURL(url);
+      })
+      .catch(() => message.error('导出失败'));
+  }, [buildParams]);
+
+  const patchRecordStatus = (recordId: number, nextStatus: string) => {
+    queryClient.setQueryData<{
+      records: AttendanceRecordItem[];
+      total: number;
+      summary: AttendanceSummary;
+    }>(recordQueryKey, (prev) =>
+      prev
+        ? {
+            ...prev,
+            records: prev.records.map((item) =>
+              item.id === recordId ? { ...item, status: nextStatus } : item,
+            ),
+          }
+        : prev,
+    );
+    setSelectedStudent((student) => {
+      if (!student) return student;
+      return {
+        ...student,
+        records: student.records.map((item) =>
+          item.id === recordId ? { ...item, status: nextStatus } : item,
+        ),
+        statusBySession: Object.fromEntries(
+          Object.entries(student.statusBySession).map(([key, item]) => [
+            key,
+            item?.id === recordId ? { ...item, status: nextStatus } : item,
+          ]),
+        ),
+      };
+    });
+  };
+
+  const updateAdminRecordStatus = async (record: AttendanceRecordItem, nextStatus: string) => {
+    const previousStatus = record.status;
+    const normalizedPrevious = displayAttendanceStatus(previousStatus);
+    if (normalizedPrevious === nextStatus && previousStatus !== 'pending') return;
+
+    patchRecordStatus(record.id, nextStatus);
+    setCorrectingRecordId(record.id);
+    try {
+      await updateStatusMutation.mutateAsync({ id: record.id, status: nextStatus });
+      message.success('考勤结果已更新');
+    } catch {
+      patchRecordStatus(record.id, previousStatus);
+    } finally {
+      setCorrectingRecordId(null);
+    }
+  };
+
+  const saveAdminRecordCell = async (
+    record: AttendanceRecordItem,
+    field: 'status' | 'remark',
+    value: unknown,
+  ) => {
+    try {
+      await saveRecordCellMutation.mutateAsync({ id: record.id, field, value });
+      message.success('考勤记录已保存');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    }
+  };
+
+  const studentPanels = useMemo(() => buildAdminStudentPanels(records), [records]);
+  const visibleStudents = useMemo(() => {
+    const query = studentSearch.trim().toLocaleLowerCase('zh-CN');
+    return studentPanels.filter((student) => {
+      const matchesQuery =
+        !query ||
+        student.studentName.toLocaleLowerCase('zh-CN').includes(query) ||
+        student.studentNo.toLocaleLowerCase('zh-CN').includes(query);
+      const matchesMetric =
+        metricFilter === 'all' ||
+        student.records.some((record) => displayAttendanceStatus(record.status) === metricFilter);
+      return matchesQuery && matchesMetric;
+    });
+  }, [metricFilter, studentPanels, studentSearch]);
+
+  const selectedClassOption = classId
+    ? classOptions.find((item) => item.classId === classId)
+    : undefined;
+  const selectedClass =
+    selectedClassOption?.className || (classId ? `班级 ${classId}` : '全部班级');
+  const overviewTeachers = selectedClassOption?.teachers ?? [];
+  const headTeacherNames = classId
+    ? formatTeacherNames(overviewTeachers.filter((teacher) => teacher.roleType === 'head_teacher'))
+    : '请选择班级';
+  const lifeTeacherNames = classId
+    ? formatTeacherNames(overviewTeachers.filter((teacher) => teacher.roleType === 'life_teacher'))
+    : '请选择班级';
+  const currentSchedule = scheduleId
+    ? scheduleOptions.find((item) => item.id === scheduleId)
+    : undefined;
+  const subjectTeacherNames = currentSchedule
+    ? getTeacherDisplayName({
+        name: currentSchedule.teacherName,
+        username: currentSchedule.teacherUsername,
+      })
+    : classId
+      ? formatTeacherNames(
+          overviewTeachers.filter((teacher) => teacher.roleType === 'subject_teacher'),
+        )
+      : '请选择班级';
+  const attendanceRate =
+    summary.total > 0 ? Math.round((summary.present / summary.total) * 100) : 0;
+  const dateLabel = attendanceDate?.format('YYYY-MM-DD') || '未选择日期';
+
+  const columns = buildAttendanceAdminColumns({
+    isMobile,
+    canEdit,
+    sessionMap,
+    correctingRecordId,
+    onSaveAdminRecordCell: saveAdminRecordCell,
+    onUpdateAdminRecordStatus: updateAdminRecordStatus,
+  });
+
+  return (
+    <div className="attendance-page admin-attendance student-attendance-center">
+      <AttendanceAdminHeader
+        syncStatus={syncStatus}
+        canEdit={canEdit}
+        refreshingDingTalk={refreshingDingTalk}
+        onOpenPeriodConfig={openPeriodConfig}
+        onRefreshDingTalk={() => void refreshDingTalkAttendance()}
+        onExport={handleExport}
+        attendanceDate={attendanceDate}
+        onDateChange={(value) => {
+          setAttendanceDate(value);
+          setScheduleId(undefined);
+          setPage(1);
+        }}
+        classId={classId}
+        onClassChange={(value) => {
+          setClassId(value);
+          setScheduleId(undefined);
+          setPage(1);
+        }}
+        classOptions={classOptions}
+        effectiveScheduleId={effectiveScheduleId}
+        onScheduleChange={(value) => {
+          setScheduleId(value);
+          setPage(1);
+        }}
+        scheduleOptions={scheduleOptions}
+        scheduleOptionsLoading={scheduleOptionsLoading}
+        session={session}
+        onSessionChange={(value) => {
+          setSession(value);
+          setPage(1);
+        }}
+        sessionOptions={sessionOptions}
+        onReset={resetFilters}
+        onQuery={() => void loadRecords()}
+        selectedClass={selectedClass}
+        dateLabel={dateLabel}
+        visibleStudentCount={visibleStudents.length}
+        total={total}
+        headTeacherNames={headTeacherNames}
+        lifeTeacherNames={lifeTeacherNames}
+        subjectTeacherNames={subjectTeacherNames}
+        attendanceRate={attendanceRate}
+        summary={summary}
+        metricFilter={metricFilter}
+        onMetricFilterChange={setMetricFilter}
+        alerts={alerts}
+      />
+
+      <AttendanceAdminWorkspace
+        metricFilter={metricFilter}
+        studentSearch={studentSearch}
+        onSearchChange={setStudentSearch}
+        onExport={handleExport}
+        visibleStudents={visibleStudents}
+        loading={loading}
+        selectedStudentId={selectedStudent?.studentId}
+        onSelectStudent={setSelectedStudent}
+        sortAttendanceRecords={sortAttendanceRecords}
+        sessionMap={sessionMap}
+        records={records}
+        columns={columns}
+        page={page}
+        pageSize={pageSize}
+        total={total}
+        onPageChange={(nextPage, nextPageSize) => {
+          setPage(nextPage);
+          setPageSize(nextPageSize);
+        }}
+      />
+
+      <StudentDetailDrawer
+        student={selectedStudent}
+        isMobile={isMobile}
+        canEdit={canEdit}
+        sessionMap={sessionMap}
+        correctingRecordId={correctingRecordId}
+        sortAttendanceRecords={sortAttendanceRecords}
+        onClose={() => setSelectedStudent(null)}
+        onUpdateAdminRecordStatus={updateAdminRecordStatus}
+      />
+
+      <PeriodConfigModal
+        open={periodModalOpen}
+        form={periodForm}
+        onOk={savePeriodConfig}
+        onCancel={() => setPeriodModalOpen(false)}
+        onReset={() => void resetPeriodConfig()}
+      />
+    </div>
+  );
+};

apps/admin/src/pages/Attendance/teacher.tsx

@@ -0,0 +1,218 @@
+import React, { useCallback, useMemo, useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { Button, Card, Col, Empty, Row, Spin, Tag, Tooltip } from 'antd';
+import {
+  ArrowRightOutlined,
+  CheckCircleFilled,
+  ClockCircleOutlined,
+  ReloadOutlined,
+  ScheduleOutlined,
+  TeamOutlined,
+} from '@ant-design/icons';
+import dayjs from 'dayjs';
+import api from '../../api';
+import { message } from '../../ui/app-message';
+import { getErrorMessage } from '../../utils/error';
+import {
+  canPullAttendance,
+  getSchedulePhase,
+  type SchedulePhase,
+} from './attendance-workspace';
+import LessonAttendanceDetail from './LessonAttendanceDetail';
+import type { LessonAttendanceSchedule } from './types';
+
+type TodaySchedule = LessonAttendanceSchedule;
+
+interface AssignedClass {
+  classId: number;
+  className: string;
+  classCode: string;
+  roleType: string;
+  subject: string;
+}
+
+interface TeacherWorkspaceData {
+  assignedClasses: AssignedClass[];
+  todaySchedules: TodaySchedule[];
+}
+
+export const TeacherAttendanceWorkspace: React.FC<{ canCreate: boolean }> = ({ canCreate }) => {
+  const [selectedSchedule, setSelectedSchedule] = useState<TodaySchedule | null>(null);
+
+  const {
+    data: workspace,
+    isLoading,
+    isFetching,
+    refetch,
+  } = useQuery<TeacherWorkspaceData | null>({
+    queryKey: ['attendance', 'workspace'],
+    queryFn: async () => {
+      try {
+        return await api.get<TeacherWorkspaceData>('/rbac/teacher-workspace');
+      } catch (error: unknown) {
+        message.error(getErrorMessage(error, '加载今日课程失败'));
+        return null;
+      }
+    },
+  });
+  const loading = isLoading || isFetching;
+  const loadWorkspace = useCallback(() => refetch(), [refetch]);
+
+  const classNameById = useMemo(
+    () => new Map(workspace?.assignedClasses.map((item) => [item.classId, item.className]) ?? []),
+    [workspace],
+  );
+
+  const openAttendance = useCallback((schedule: TodaySchedule) => {
+    setSelectedSchedule(schedule);
+  }, []);
+
+  const now = new Date();
+  const schedules = workspace?.todaySchedules ?? [];
+  const startedCount = schedules.filter((item) =>
+    canPullAttendance(getSchedulePhase(item.startTime, item.endTime, now)),
+  ).length;
+  const nextSchedule = schedules.find(
+    (item) => getSchedulePhase(item.startTime, item.endTime, now) !== 'ended',
+  );
+
+  return (
+    <div className="attendance-page teacher-attendance">
+      <section className="attendance-hero attendance-hero--teacher">
+        <div>
+          <span className="attendance-eyebrow">
+            TEACHING DAY · {dayjs().format('MM月DD日 dddd')}
+          </span>
+          <h1>今天，从课程开始</h1>
+          <p>课程开始后可查看最新打卡结果；课程截止时系统自动拉取并结算缺勤。</p>
+        </div>
+        <Button icon={<ReloadOutlined />} onClick={() => void loadWorkspace()}>
+          刷新
+        </Button>
+      </section>
+
+      <Row gutter={[16, 16]} className="teacher-overview">
+        <Col xs={24} md={8}>
+          <div className="teacher-kpi">
+            <span>今日课程</span>
+            <strong>{schedules.length}</strong>
+            <small>节</small>
+          </div>
+        </Col>
+        <Col xs={24} md={8}>
+          <div className="teacher-kpi">
+            <span>已开始</span>
+            <strong>{startedCount}</strong>
+            <small>节，可查看考勤</small>
+          </div>
+        </Col>
+        <Col xs={24} md={8}>
+          <div className="teacher-kpi teacher-kpi--next">
+            <span>下一节</span>
+            <strong>{nextSchedule ? nextSchedule.startTime : '—'}</strong>
+            <small>{nextSchedule?.subject || '今天没有更多课程'}</small>
+          </div>
+        </Col>
+      </Row>
+
+      <div className="attendance-section-heading">
+        <div>
+          <span>今日教学节奏</span>
+          <h2>我的课程</h2>
+        </div>
+        <span className="attendance-section-note">课程开始后可拉取钉钉考勤记录</span>
+      </div>
+
+      <Spin spinning={loading}>
+        {schedules.length === 0 ? (
+          <Card className="attendance-empty-card">
+            <Empty
+              image={Empty.PRESENTED_IMAGE_SIMPLE}
+              description={
+                <div>
+                  <strong>今天还没有课程</strong>
+                  <p>请联系教务管理员安排课程。</p>
+                </div>
+              }
+            />
+          </Card>
+        ) : (
+          <div className="lesson-timeline">
+            {schedules.map((schedule, index) => {
+              const phase = getSchedulePhase(schedule.startTime, schedule.endTime, now);
+              return (
+                <LessonCard
+                  key={schedule.id}
+                  schedule={schedule}
+                  phase={phase}
+                  className={classNameById.get(schedule.classId) || `班级 ${schedule.classId}`}
+                  index={index + 1}
+                  onOpen={canCreate ? () => openAttendance(schedule) : undefined}
+                />
+              );
+            })}
+          </div>
+        )}
+      </Spin>
+
+      {canCreate ? (
+        <LessonAttendanceDetail
+          key={selectedSchedule?.id ?? 'closed'}
+          schedule={selectedSchedule}
+          className={
+            selectedSchedule
+              ? classNameById.get(selectedSchedule.classId) || `班级 ${selectedSchedule.classId}`
+              : ''
+          }
+          onClose={() => setSelectedSchedule(null)}
+        />
+      ) : null}
+    </div>
+  );
+};
+
+export const LessonCard: React.FC<{
+  schedule: TodaySchedule;
+  phase: SchedulePhase;
+  className: string;
+  index: number;
+  onOpen?: () => void;
+}> = ({ schedule, phase, className, index, onOpen }) => {
+  const phaseMeta = {
+    upcoming: { label: '待上课', icon: <ClockCircleOutlined />, tone: 'upcoming' },
+    ongoing: { label: '进行中', icon: <ScheduleOutlined />, tone: 'ongoing' },
+    ended: { label: '已结束', icon: <CheckCircleFilled />, tone: 'ended' },
+  }[phase];
+
+  return (
+    <article className={`lesson-card lesson-card--${phaseMeta.tone}`}>
+      <div className="lesson-sequence">{String(index).padStart(2, '0')}</div>
+      <div className="lesson-time">
+        <strong>{schedule.startTime}</strong>
+        <span />
+        <strong>{schedule.endTime}</strong>
+      </div>
+      <div className="lesson-main">
+        <div className="lesson-title-row">
+          <h3>{schedule.subject}</h3>
+          <Tag icon={phaseMeta.icon}>{phaseMeta.label}</Tag>
+        </div>
+        <p>
+          <TeamOutlined /> {className}
+          <span>教室 {schedule.classroomId}</span>
+        </p>
+      </div>
+      <div className="lesson-action">
+        {phase === 'upcoming' ? (
+          <Tooltip title="课程尚未开始">
+            <Button disabled>等待上课</Button>
+          </Tooltip>
+        ) : onOpen ? (
+          <Button type="primary" onClick={onOpen}>
+            {phase === 'ongoing' ? '查看当前考勤' : '拉取 / 查看考勤'} <ArrowRightOutlined />
+          </Button>
+        ) : null}
+      </div>
+    </article>
+  );
+};

apps/admin/src/pages/AttendanceDevices.tsx

@@ -1,4 +1,8 @@
-import React, { useEffect, useMemo, useState } from 'react';
+import React, { useMemo, useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { useApiMutation } from '../hooks/useApiMutation';
+import { validateResponse } from '../utils/validate';
+import { attendanceDevicesSchema, classroomOptionsSchema } from '../api/schemas';
 import { Empty, Form, Input, Modal, Popconfirm, Select, Space, Table, Tag } from 'antd';
 import type { ColumnsType } from 'antd/es/table';
 import { PlusOutlined } from '@ant-design/icons';
@@ -30,34 +34,57 @@ const statusMeta = {
 } as const;
 
 const AttendanceDevicesPage: React.FC = () => {
-  const [data, setData] = useState<AttendanceDeviceRow[]>([]);
-  const [classrooms, setClassrooms] = useState<ClassroomOption[]>([]);
-  const [loading, setLoading] = useState(false);
   const [modalOpen, setModalOpen] = useState(false);
   const [editing, setEditing] = useState<AttendanceDeviceRow | null>(null);
   const [saving, setSaving] = useState(false);
   const [keyword, setKeyword] = useState('');
   const [form] = Form.useForm();
 
-  const loadData = async () => {
-    setLoading(true);
-    try {
-      const [devices, classroomList] = await Promise.all([
-        api.get<AttendanceDeviceRow[]>('/attendance-devices'),
-        api.get<ClassroomOption[]>('/classrooms'),
-      ]);
-      setData(devices);
-      setClassrooms(classroomList.filter((item: any) => item.status !== 'archived'));
-    } catch (error: any) {
-      message.error(error?.message || '加载考勤机绑定失败');
-    } finally {
-      setLoading(false);
-    }
-  };
+  const {
+    data: fetchResult = { devices: [], classrooms: [] },
+    isLoading,
+    isFetching,
+  } = useQuery<{ devices: AttendanceDeviceRow[]; classrooms: ClassroomOption[] }>({
+    queryKey: ['attendance-devices'],
+    queryFn: async () => {
+      try {
+        const [devices, classroomList] = await Promise.all([
+          api.get<AttendanceDeviceRow[]>('/attendance-devices'),
+          api.get<ClassroomOption[]>('/classrooms'),
+        ]);
+        return {
+          devices: validateResponse<AttendanceDeviceRow[]>(attendanceDevicesSchema, devices),
+          classrooms: validateResponse<ClassroomOption[]>(
+            classroomOptionsSchema,
+            classroomList,
+          ).filter((item: any) => item.status !== 'archived'),
+        };
+      } catch (error: any) {
+        message.error(error?.message || '加载考勤机绑定失败');
+        return { devices: [], classrooms: [] };
+      }
+    },
+  });
+  const data = fetchResult.devices;
+  const classrooms = fetchResult.classrooms;
+  const loading = isLoading || isFetching;
 
-  useEffect(() => {
-    void loadData();
-  }, []);
+  const saveMutation = useApiMutation(
+    async (values: Record<string, unknown>) =>
+      editing
+        ? api.put(`/attendance-devices/${editing.id}`, values)
+        : api.post('/attendance-devices', values),
+    { invalidate: [['attendance-devices']] },
+  );
+  const saveCellMutation = useApiMutation(
+    async ({ record, field, value }: { record: AttendanceDeviceRow; field: string; value: unknown }) =>
+      api.put(`/attendance-devices/${record.id}`, { [field]: value }),
+    { invalidate: [['attendance-devices']] },
+  );
+  const deleteMutation = useApiMutation(
+    async (id: number) => api.delete(`/attendance-devices/${id}`),
+    { invalidate: [['attendance-devices']] },
+  );
 
   const classroomOptions = useMemo(
     () =>
@@ -102,37 +129,33 @@ const AttendanceDevicesPage: React.FC = () => {
     const values = await form.validateFields();
     setSaving(true);
     try {
-      if (editing) {
-        await api.put(`/attendance-devices/${editing.id}`, values);
-        message.success('考勤机绑定已更新');
-      } else {
-        await api.post('/attendance-devices', values);
-        message.success('考勤机绑定已创建');
-      }
+      await saveMutation.mutateAsync(values);
+      message.success(editing ? '考勤机绑定已更新' : '考勤机绑定已创建');
       setModalOpen(false);
       setEditing(null);
       form.resetFields();
-      await loadData();
-    } catch (error: any) {
-      message.error(error?.message || '保存失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     } finally {
       setSaving(false);
     }
   };
 
   const saveCell = async (record: AttendanceDeviceRow, field: string, value: unknown) => {
-    await api.put(`/attendance-devices/${record.id}`, { [field]: value });
-    message.success('已保存');
-    await loadData();
+    try {
+      await saveCellMutation.mutateAsync({ record, field, value });
+      message.success('已保存');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    }
   };
 
   const handleDelete = async (id: number) => {
     try {
-      await api.delete(`/attendance-devices/${id}`);
+      await deleteMutation.mutateAsync(id);
       message.success('已停用绑定');
-      await loadData();
-    } catch (error: any) {
-      message.error(error?.message || '停用失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     }
   };
 

apps/admin/src/pages/Bills/bill-print.ts

@@ -27,13 +27,21 @@ const statusLabels: Record<string, string> = {
   cancelled: '已取消',
 };
 
-const escapeHtml = (value: unknown) =>
-  String(value ?? '')
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&#039;');
+const HTML_ESCAPE_PAIRS: ReadonlyArray<readonly [string, string]> = [
+  ['&', '&amp;'],
+  ['<', '&lt;'],
+  ['>', '&gt;'],
+  ['"', '&quot;'],
+  ["'", '&#039;'],
+];
+
+const escapeHtml = (value: unknown) => {
+  let text = String(value ?? '');
+  for (const [from, to] of HTML_ESCAPE_PAIRS) {
+    text = text.replaceAll(from, to);
+  }
+  return text;
+};
 
 const money = (value: unknown) => `¥${Number(value || 0).toFixed(2)}`;
 

apps/admin/src/pages/Bills/index.tsx

@@ -1,6 +1,8 @@
-import React, { useEffect, useState, useMemo, useCallback } from 'react';
+import React, { useState, useMemo } from 'react';
 import {
+  App,
   Table,
+  Button,
   Modal,
   Form,
   DatePicker,
@@ -26,6 +28,11 @@ import { downloadBlob } from '../../utils/download';
 import { message } from '../../ui/app-message';
 import { buildBillPrintHtml, type BillPrintData } from './bill-print';
 import { newOperationId } from '../../utils/operation-id';
+import { usePermission } from '../../hooks/usePermission';
+import { useQuery } from '@tanstack/react-query';
+import { useApiMutation } from '../../hooks/useApiMutation';
+import { validateResponse } from '../../utils/validate';
+import { billsSchema } from '../../api/schemas';
 
 const statusMap: Record<string, { text: string; color: string }> = {
   unpaid: { text: '待支付', color: 'orange' },
@@ -44,8 +51,9 @@ const typeMap: Record<string, string> = {
 };
 
 const BillsPage: React.FC = () => {
-  const [bills, setBills] = useState<any[]>([]);
-  const [loading, setLoading] = useState(false);
+  const { modal } = App.useApp();
+  const { hasPermission } = usePermission();
+  const canPurgeBill = hasPermission('bill:purge');
   const [generateModal, setGenerateModal] = useState(false);
   const [detailModal, setDetailModal] = useState<any>(null);
   const [selectedRows, setSelectedRows] = useState<number[]>([]);
@@ -57,23 +65,48 @@ const BillsPage: React.FC = () => {
   const [detailLoading, setDetailLoading] = useState(false);
   const [batchLoading, setBatchLoading] = useState(false);
 
-  const fetchData = useCallback(async () => {
-    setLoading(true);
-    try {
-      const params: Record<string, string | undefined> = {};
-      if (filterStatus) params.status = filterStatus;
-      if (filterExpenseType) params.expenseType = filterExpenseType;
-      const res = (await api.get('/bills', { params })) as unknown[];
-      setBills(res);
-    } catch (e: any) {
-      message.error(e?.message || '加载失败，请稍后重试');
-    }
-    setLoading(false);
-  }, [filterStatus, filterExpenseType]);
+  const {
+    data: bills = [],
+    isLoading,
+    isFetching,
+  } = useQuery({
+    queryKey: ['bills', filterStatus, filterExpenseType],
+    queryFn: async () => {
+      try {
+        const params: Record<string, string | undefined> = {};
+        if (filterStatus) params.status = filterStatus;
+        if (filterExpenseType) params.expenseType = filterExpenseType;
+        return validateResponse<unknown[]>(billsSchema, await api.get('/bills', { params }));
+      } catch (e: any) {
+        message.error(e?.message || '加载失败，请稍后重试');
+        return [];
+      }
+    },
+  });
+  const loading = isLoading || isFetching;
 
-  useEffect(() => {
-    fetchData();
-  }, [fetchData]);
+  const generateMutation = useApiMutation(
+    async (payload: { operationId: string; billingMonth: string }) =>
+      api.post('/bills/generate', payload),
+    { invalidate: [['bills']] },
+  );
+  const cancelMutation = useApiMutation(
+    async ({ id, reason }: { id: number; reason: string }) =>
+      api.post(`/bills/${id}/cancel`, { operationId: newOperationId(), reason }),
+    { invalidate: [['bills']] },
+  );
+  const archiveMutation = useApiMutation(
+    async (id: number) => api.delete(`/bills/${id}`),
+    { invalidate: [['bills']] },
+  );
+  const purgeMutation = useApiMutation(
+    async (id: number) => api.delete(`/bills/${id}/permanent`),
+    { invalidate: [['bills']] },
+  );
+  const batchArchiveMutation = useApiMutation(
+    async (ids: number[]) => api.post('/bills/batch/delete', { ids }),
+    { invalidate: [['bills']] },
+  );
 
   const filteredBills = useMemo(() => {
     return bills.filter((b: any) => {
@@ -92,16 +125,15 @@ const BillsPage: React.FC = () => {
     setSaving(true);
     const values = await generateForm.validateFields();
     try {
-      const res: any = await api.post('/bills/generate', {
+      const res: any = await generateMutation.mutateAsync({
         operationId: newOperationId(),
         billingMonth: values.billingMonth.format('YYYY-MM'),
       });
       message.success(res.message || '生成成功');
       setGenerateModal(false);
       generateForm.resetFields();
-      fetchData();
-    } catch (e: any) {
-      message.error(e?.message || '生成失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     } finally {
       setSaving(false);
     }
@@ -121,7 +153,7 @@ const BillsPage: React.FC = () => {
 
   const handleCancel = async (id: number) => {
     let reason = '';
-    Modal.confirm({
+    modal.confirm({
       title: '取消账单并退回已扣余额',
       content: (
         <Input.TextArea
@@ -139,37 +171,49 @@ const BillsPage: React.FC = () => {
           message.error('请输入取消原因');
           throw new Error('reason required');
         }
-        await api.post(`/bills/${id}/cancel`, {
-          operationId: newOperationId(),
-          reason: reason.trim(),
-        });
+        await cancelMutation.mutateAsync({ id, reason: reason.trim() });
         message.success('账单已取消，已扣余额已冲正退回');
-        fetchData();
       },
     });
   };
 
   const handleArchive = async (id: number) => {
     try {
-      await api.delete(`/bills/${id}`);
+      await archiveMutation.mutateAsync(id);
       message.success('账单已归档');
-      fetchData();
-    } catch (error: any) {
-      message.error(error?.message || '归档失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     }
   };
 
+  const handlePurge = (id: number, studentName: string, period: string) => {
+    modal.confirm({
+      title: `永久删除账单（${studentName} ${period}）？`,
+      content: '删除后不可恢复，该账单及其明细将被物理删除。确定继续？',
+      okText: '永久删除',
+      okButtonProps: { danger: true },
+      cancelText: '取消',
+      onOk: async () => {
+        try {
+          await purgeMutation.mutateAsync(id);
+          message.success('已永久删除（不可恢复）');
+        } catch {
+          // 错误提示由 useApiMutation 统一处理
+        }
+      },
+    });
+  };
+
   const batchArchive = async () => {
     if (selectedRows.length === 0) return message.warning('请先选择账单');
     if (batchLoading) return;
     setBatchLoading(true);
     try {
-      await api.post('/bills/batch/delete', { ids: selectedRows });
+      await batchArchiveMutation.mutateAsync(selectedRows);
       message.success(`已归档 ${selectedRows.length} 条账单`);
       setSelectedRows([]);
-      fetchData();
-    } catch (e: any) {
-      message.error(e?.message || '操作失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     } finally {
       setBatchLoading(false);
     }
@@ -216,28 +260,28 @@ const BillsPage: React.FC = () => {
         dataIndex: 'sharedAmount',
         width: 120,
         align: 'right' as const,
-        render: (v: number) => `¥${Number(v).toFixed(2)}`,
+        render: (v: number) => `¥${v.toFixed(2)}`,
       },
       {
         title: '个人费用',
         dataIndex: 'personalAmount',
         width: 120,
         align: 'right' as const,
-        render: (v: number) => `¥${Number(v).toFixed(2)}`,
+        render: (v: number) => `¥${v.toFixed(2)}`,
       },
       {
         title: '总计',
         dataIndex: 'totalAmount',
         width: 100,
         align: 'right' as const,
-        render: (v: number) => <strong>¥{Number(v).toFixed(2)}</strong>,
+        render: (v: number) => <strong>¥{v.toFixed(2)}</strong>,
       },
       {
         title: '已扣余额',
         dataIndex: 'paidAmount',
         width: 110,
         render: (value: number) => (
-          <span style={{ color: '#389e0d' }}>¥{Number(value || 0).toFixed(2)}</span>
+          <span style={{ color: '#389e0d' }}>¥{(value ?? 0).toFixed(2)}</span>
         ),
       },
       {
@@ -245,8 +289,8 @@ const BillsPage: React.FC = () => {
         dataIndex: 'outstandingAmount',
         width: 110,
         render: (value: number) => (
-          <strong style={{ color: Number(value) > 0 ? '#cf1322' : '#389e0d' }}>
-            ¥{Number(value || 0).toFixed(2)}
+          <strong style={{ color: value > 0 ? '#cf1322' : '#389e0d' }}>
+            ¥{(value ?? 0).toFixed(2)}
           </strong>
         ),
       },
@@ -289,6 +333,22 @@ const BillsPage: React.FC = () => {
             >
               PDF
             </PermissionButton>
+            {record.status === 'cancelled' && canPurgeBill ? (
+              <Button
+                size="small"
+                danger
+                type="link"
+                onClick={() =>
+                  handlePurge(
+                    record.id,
+                    record.student?.name || '-',
+                    `${record.periodStart}~${record.periodEnd}`,
+                  )
+                }
+              >
+                删除
+              </Button>
+            ) : null}
             {record.status !== 'cancelled' && (
               <PermissionButton
                 permission="bill:delete"
@@ -320,7 +380,7 @@ const BillsPage: React.FC = () => {
         ),
       },
     ],
-    [showDetail, handleArchive, handleCancel, handleExportPdf],
+    [showDetail, handleArchive, handleCancel, handleExportPdf, canPurgeBill, handlePurge],
   );
 
   return (
@@ -511,12 +571,12 @@ const BillsPage: React.FC = () => {
                 {
                   title: '宿舍总费用',
                   dataIndex: 'roomTotalAmount',
-                  render: (v: number) => `¥${Number(v).toFixed(2)}`,
+                  render: (v: number) => `¥${v.toFixed(2)}`,
                 },
                 {
                   title: '应分摊',
                   dataIndex: 'studentAmount',
-                  render: (v: number) => <strong>¥{Number(v).toFixed(2)}</strong>,
+                  render: (v: number) => <strong>¥{v.toFixed(2)}</strong>,
                 },
               ]}
             />

apps/admin/src/pages/Classes/ClassDetailTabs.tsx

@@ -0,0 +1,557 @@
+import React from 'react';
+import {
+  Button,
+  Card,
+  Col,
+  DatePicker,
+  Descriptions,
+  Form,
+  Input,
+  InputNumber,
+  Modal,
+  Popconfirm,
+  Row,
+  Select,
+  Space,
+  Statistic,
+  Table,
+  Tag,
+} from 'antd';
+import type { ColumnsType } from 'antd/es/table';
+import { DownloadOutlined, PlusOutlined } from '@ant-design/icons';
+import dayjs from 'dayjs';
+import { useUserStore } from '../../store/user/userStore';
+import PermissionButton from '../../components/PermissionButton';
+import { message } from '../../ui/app-message';
+import { buildTeacherCandidateOptions, type TeacherCandidateUser } from './teacher-candidate';
+
+export interface ClassStudent {
+  id: number;
+  studentId: number;
+  studentName: string;
+  studentNo: string;
+  joinDate: string;
+  leaveDate: string | null;
+  status: string;
+}
+
+export interface ClassTeacher {
+  id: number;
+  userId: number;
+  username: string;
+  roleType: string;
+  subject: string | null;
+}
+
+export interface ClassScheduleItem {
+  id: number;
+  classId: number;
+  classroomId: number;
+  classroomName: string;
+  weekDay: number;
+  startTime: string;
+  endTime: string;
+  attendanceAdvanceMinutes: number;
+  startDate: string;
+  endDate: string;
+  subject: string;
+  teacherId: number | null;
+  scheduleType: string;
+  status: string;
+  notes: string | null;
+}
+
+export interface AttendanceSummary {
+  total: number;
+  present: number;
+  late: number;
+  absent: number;
+  leave: number;
+  presentRate: number;
+  absentRate: number;
+  lateRate: number;
+  leaveRate: number;
+}
+
+export interface ClassDetail {
+  id: number;
+  name: string;
+  code: string;
+  classType: string;
+  startDate: string | null;
+  endDate: string | null;
+  status: string;
+  maxStudents: number;
+  notes: string | null;
+  studentCount: number;
+  students?: ClassStudent[];
+  teachers?: ClassTeacher[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface StudentItem {
+  id: number;
+  name: string;
+  studentNo?: string;
+}
+
+export const STATUS_MAP: Record<string, { color: string; text: string }> = {
+  enrolling: { color: 'blue', text: '招生中' },
+  active: { color: 'green', text: '在读' },
+  ended: { color: 'default', text: '结课' },
+  suspended: { color: 'orange', text: '停课' },
+};
+
+export const TYPE_MAP: Record<string, string> = {
+  culture: '文化课',
+  professional: '专业课',
+  bootcamp: '集训营',
+  sprint: '冲刺营',
+};
+
+export const ROLE_MAP: Record<string, string> = {
+  subject_teacher: '任课老师',
+  head_teacher: '班主任',
+  life_teacher: '生活老师',
+  academic_teacher: '学服老师',
+};
+
+export const WEEK_DAY_MAP: Record<number, string> = {
+  1: '周一',
+  2: '周二',
+  3: '周三',
+  4: '周四',
+  5: '周五',
+  6: '周六',
+  7: '周日',
+};
+
+export const SCHEDULE_TYPE_MAP: Record<string, string> = {
+  INTERNAL: '内部排课',
+  RENTAL: '租赁',
+};
+
+export const ClassInfoTab: React.FC<{
+  detail: ClassDetail;
+  teachers: ClassTeacher[];
+  editingInfo: boolean;
+  editForm: ReturnType<typeof Form.useForm>[0];
+  onSave: () => void;
+  onEdit: () => void;
+  onCancel: () => void;
+  getTeacherName: (teacher: ClassTeacher) => string;
+}> = ({ detail, teachers, editingInfo, editForm, onSave, onEdit, onCancel, getTeacherName }) => {
+  return (
+    <div>
+      {editingInfo ? (
+        <Form
+          form={editForm}
+          layout="vertical"
+          initialValues={{
+            name: detail.name,
+            code: detail.code,
+            classType: detail.classType,
+            startDate: detail.startDate ? dayjs(detail.startDate) : undefined,
+            endDate: detail.endDate ? dayjs(detail.endDate) : undefined,
+            maxStudents: detail.maxStudents,
+            status: detail.status,
+            notes: detail.notes,
+          }}
+        >
+          <Space wrap>
+            <Form.Item name="name" label="名称" rules={[{ required: true }]}>
+              <Input />
+            </Form.Item>
+            <Form.Item name="code" label="编码">
+              <Input />
+            </Form.Item>
+            <Form.Item name="classType" label="班型">
+              <Select
+                options={Object.entries(TYPE_MAP).map(([k, v]) => ({
+                  value: k,
+                  label: v,
+                }))}
+              />
+            </Form.Item>
+            <Form.Item name="startDate" label="开班">
+              <DatePicker />
+            </Form.Item>
+            <Form.Item name="endDate" label="结课">
+              <DatePicker />
+            </Form.Item>
+            <Form.Item name="maxStudents" label="人数上限">
+              <InputNumber min={1} />
+            </Form.Item>
+            <Form.Item name="status" label="状态">
+              <Select
+                options={Object.entries(STATUS_MAP).map(([k, v]) => ({
+                  value: k,
+                  label: v.text,
+                }))}
+              />
+            </Form.Item>
+          </Space>
+          <Form.Item name="notes" label="备注">
+            <Input.TextArea rows={3} />
+          </Form.Item>
+          <Space>
+            <PermissionButton permission="class:edit" type="primary" onClick={onSave}>
+              保存
+            </PermissionButton>
+            <Button onClick={onCancel}>取消</Button>
+          </Space>
+        </Form>
+      ) : (
+        <div>
+          <Descriptions column={3} bordered size="small">
+            <Descriptions.Item label="班型">{TYPE_MAP[detail.classType]}</Descriptions.Item>
+            <Descriptions.Item label="开班日期">
+              {detail.startDate ? dayjs(detail.startDate).format('YYYY-MM-DD') : '-'}
+            </Descriptions.Item>
+            <Descriptions.Item label="结课日期">
+              {detail.endDate ? dayjs(detail.endDate).format('YYYY-MM-DD') : '-'}
+            </Descriptions.Item>
+            <Descriptions.Item label="学员">
+              {detail.studentCount}/{detail.maxStudents || '-'}
+            </Descriptions.Item>
+            <Descriptions.Item label="班主任">
+              {(() => {
+                const headTeacher = teachers.find(
+                  (teacher) => teacher.roleType === 'head_teacher',
+                );
+                return headTeacher ? getTeacherName(headTeacher) : '-';
+              })()}
+            </Descriptions.Item>
+            <Descriptions.Item label="备注">{detail.notes || '-'}</Descriptions.Item>
+          </Descriptions>
+          <PermissionButton permission="class:edit" style={{ marginTop: 16 }} onClick={onEdit}>
+            编辑
+          </PermissionButton>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export const ClassStudentsTab: React.FC<{
+  id?: string;
+  detail?: ClassDetail | null;
+  students: ClassStudent[];
+  allStudents: StudentItem[];
+  selectedStudentIds: number[];
+  modalOpen: boolean;
+  onOpen: () => void;
+  onAdd: () => void;
+  onClose: () => void;
+  onRemove: (studentId: number) => void;
+  onSelect: (ids: number[]) => void;
+}> = ({
+  id,
+  detail,
+  students,
+  allStudents,
+  selectedStudentIds,
+  modalOpen,
+  onOpen,
+  onAdd,
+  onClose,
+  onRemove,
+  onSelect,
+}) => {
+  const studentColumns: ColumnsType<ClassStudent> = [
+    { title: '姓名', dataIndex: 'studentName' },
+    { title: '学号', dataIndex: 'studentNo' },
+    { title: '加入日期', dataIndex: 'joinDate' },
+    { title: '离班日期', dataIndex: 'leaveDate', render: (v: string | null) => v || '-' },
+    {
+      title: '状态',
+      dataIndex: 'status',
+      render: (v: string) => (
+        <Tag color={v === 'active' ? 'green' : 'default'}>{v === 'active' ? '在读' : '已离班'}</Tag>
+      ),
+    },
+    {
+      title: '操作',
+      render: (_: unknown, r: ClassStudent) =>
+        r.status === 'active' ? (
+          <Popconfirm title="确认移除？" onConfirm={() => onRemove(r.studentId)}>
+            <PermissionButton permission="class:edit" size="small" danger>
+              移除
+            </PermissionButton>
+          </Popconfirm>
+        ) : null,
+    },
+  ];
+  return (
+    <div>
+      <PermissionButton
+        permission="class:edit"
+        icon={<PlusOutlined />}
+        type="primary"
+        onClick={onOpen}
+        style={{ marginBottom: 16, marginRight: 8 }}
+      >
+        添加学员
+      </PermissionButton>
+      <PermissionButton
+        permission="class:view"
+        icon={<DownloadOutlined />}
+        onClick={() => {
+          const token = useUserStore.getState().token;
+          fetch(`/api/classes/${id}/roster/export`, {
+            headers: { Authorization: `Bearer ${token}` },
+          })
+            .then((res) => {
+              if (!res.ok) throw new Error('导出失败');
+              return res.blob();
+            })
+            .then((blob) => {
+              const url = URL.createObjectURL(blob);
+              const a = document.createElement('a');
+              a.href = url;
+              a.download = `班级花名册-${detail?.name || id}.xlsx`;
+              a.click();
+              URL.revokeObjectURL(url);
+              message.success('花名册导出成功');
+            })
+            .catch(() => message.error('花名册导出失败'));
+        }}
+      >
+        导出花名册
+      </PermissionButton>
+      <Table<ClassStudent>
+        columns={studentColumns}
+        dataSource={students}
+        rowKey="id"
+        pagination={{
+          defaultPageSize: 20,
+          showSizeChanger: true,
+          pageSizeOptions: [20, 50, 100],
+        }}
+      />
+      <Modal title="添加学员" open={modalOpen} onOk={onAdd} onCancel={onClose}>
+        <Select
+          mode="multiple"
+          style={{ width: '100%' }}
+          placeholder="选择学员"
+          value={selectedStudentIds}
+          onChange={onSelect}
+          options={allStudents.map((s) => ({
+            value: s.id,
+            label: `${s.name} (${s.studentNo || s.id})`,
+          }))}
+          filterOption={(input, option) =>
+            (option?.label as string)?.toLowerCase().includes(input.toLowerCase())
+          }
+        />
+      </Modal>
+    </div>
+  );
+};
+
+export const ClassTeachersTab: React.FC<{
+  teachers: ClassTeacher[];
+  allUsers: TeacherCandidateUser[];
+  teacherRole: string;
+  teacherSubject: string;
+  teacherUserId?: number;
+  modalOpen: boolean;
+  onOpen: () => void;
+  onAdd: () => void;
+  onClose: () => void;
+  onRemove: (userId: number) => void;
+  onRoleChange: (role: string) => void;
+  onSubjectChange: (subject: string) => void;
+  onUserChange: (userId?: number) => void;
+  getTeacherName: (teacher: ClassTeacher) => string;
+}> = ({
+  teachers,
+  allUsers,
+  teacherRole,
+  teacherSubject,
+  teacherUserId,
+  modalOpen,
+  onOpen,
+  onAdd,
+  onClose,
+  onRemove,
+  onRoleChange,
+  onSubjectChange,
+  onUserChange,
+  getTeacherName,
+}) => {
+  const teacherColumns: ColumnsType<ClassTeacher> = [
+    { title: '姓名', render: (_: unknown, teacher) => getTeacherName(teacher) },
+    {
+      title: '角色',
+      dataIndex: 'roleType',
+      render: (v: string) => <Tag>{ROLE_MAP[v] || v}</Tag>,
+    },
+    {
+      title: '科目',
+      dataIndex: 'subject',
+      render: (v: string | null) => v || '-',
+    },
+    {
+      title: '操作',
+      render: (_: unknown, r: ClassTeacher) => (
+        <Popconfirm title="确认移除？" onConfirm={() => onRemove(r.userId)}>
+          <PermissionButton permission="class:edit" size="small" danger>
+            移除
+          </PermissionButton>
+        </Popconfirm>
+      ),
+    },
+  ];
+  return (
+    <div>
+      <PermissionButton
+        permission="class:edit"
+        icon={<PlusOutlined />}
+        type="primary"
+        onClick={onOpen}
+        style={{ marginBottom: 16 }}
+      >
+        添加教师
+      </PermissionButton>
+      <Table<ClassTeacher>
+        columns={teacherColumns}
+        dataSource={teachers}
+        rowKey="id"
+        pagination={{
+          defaultPageSize: 20,
+          showSizeChanger: true,
+          pageSizeOptions: [20, 50, 100],
+        }}
+      />
+      <Modal title="添加教师" open={modalOpen} onOk={onAdd} onCancel={onClose}>
+        <Space orientation="vertical" style={{ width: '100%' }}>
+          <Select
+            style={{ width: '100%' }}
+            showSearch
+            optionFilterProp="label"
+            placeholder="搜索姓名、用户名、角色或学科"
+            value={teacherUserId}
+            onChange={onUserChange}
+            options={buildTeacherCandidateOptions(allUsers)}
+            notFoundContent="没有可分配的工作人员账号"
+          />
+          <Select
+            style={{ width: '100%' }}
+            value={teacherRole}
+            onChange={onRoleChange}
+            options={Object.entries(ROLE_MAP).map(([k, v]) => ({
+              value: k,
+              label: v,
+            }))}
+          />
+          {teacherRole === 'subject_teacher' && (
+            <Input
+              placeholder="任教科目"
+              value={teacherSubject}
+              onChange={(e) => onSubjectChange(e.target.value)}
+            />
+          )}
+        </Space>
+      </Modal>
+    </div>
+  );
+};
+
+export const ClassScheduleTab: React.FC<{
+  schedules: ClassScheduleItem[];
+  scheduleDateRange: [dayjs.Dayjs | null, dayjs.Dayjs | null];
+  onRangeChange: (dates: [dayjs.Dayjs | null, dayjs.Dayjs | null]) => void;
+}> = ({ schedules, scheduleDateRange, onRangeChange }) => {
+  const scheduleColumns: ColumnsType<ClassScheduleItem> = [
+    { title: '教室', dataIndex: 'classroomName', render: (v: string | null) => v || '-' },
+    { title: '星期', dataIndex: 'weekDay', render: (v: number) => WEEK_DAY_MAP[v] || v },
+    {
+      title: '时间',
+      render: (_: unknown, r: ClassScheduleItem) => `${r.startTime} - ${r.endTime}`,
+    },
+    {
+      title: '签到窗口',
+      render: (_: unknown, r: ClassScheduleItem) =>
+        `课前 ${r.attendanceAdvanceMinutes ?? 30} 分钟至下课`,
+    },
+    {
+      title: '日期范围',
+      render: (_: unknown, r: ClassScheduleItem) => `${r.startDate} ~ ${r.endDate}`,
+    },
+    { title: '科目', dataIndex: 'subject' },
+    { title: '类型', dataIndex: 'scheduleType', render: (v: string) => SCHEDULE_TYPE_MAP[v] || v },
+    {
+      title: '状态',
+      dataIndex: 'status',
+      render: (v: string) => (
+        <Tag color={v === 'active' ? 'green' : 'default'}>{v === 'active' ? '启用' : v}</Tag>
+      ),
+    },
+  ];
+  return (
+    <div>
+      <Space style={{ marginBottom: 16, maxWidth: '100%' }} wrap>
+        <DatePicker.RangePicker
+          value={scheduleDateRange}
+          onChange={(dates) => onRangeChange(dates as [dayjs.Dayjs | null, dayjs.Dayjs | null])}
+          placeholder={['开始日期', '结束日期']}
+        />
+      </Space>
+      <Table<ClassScheduleItem>
+        columns={scheduleColumns}
+        dataSource={schedules}
+        rowKey="id"
+        scroll={{ x: 'max-content' }}
+        pagination={{
+          defaultPageSize: 20,
+          showSizeChanger: true,
+          pageSizeOptions: [20, 50, 100],
+        }}
+      />
+    </div>
+  );
+};
+
+export const ClassAttendanceTab: React.FC<{
+  attendanceSummary: AttendanceSummary | null;
+  attendanceDateRange: [dayjs.Dayjs | null, dayjs.Dayjs | null];
+  onRangeChange: (dates: [dayjs.Dayjs | null, dayjs.Dayjs | null]) => void;
+}> = ({ attendanceSummary, attendanceDateRange, onRangeChange }) => {
+  return (
+    <div>
+      <Space style={{ marginBottom: 16, maxWidth: '100%' }} wrap>
+        <DatePicker.RangePicker
+          value={attendanceDateRange}
+          onChange={(dates) => onRangeChange(dates as [dayjs.Dayjs | null, dayjs.Dayjs | null])}
+          placeholder={['开始日期', '结束日期']}
+        />
+      </Space>
+      {attendanceSummary && (
+        <Row gutter={[16, 16]}>
+          <Col xs={12} md={6}>
+            <Card bordered={false}>
+              <Statistic title="总记录" value={attendanceSummary.total} />
+            </Card>
+          </Col>
+          <Col xs={12} md={6}>
+            <Card bordered={false}>
+              <Statistic title="出勤率" value={attendanceSummary.presentRate} suffix="%" />
+            </Card>
+          </Col>
+          <Col xs={12} md={6}>
+            <Card bordered={false}>
+              <Statistic title="缺勤率" value={attendanceSummary.absentRate} suffix="%" />
+            </Card>
+          </Col>
+          <Col xs={12} md={6}>
+            <Card bordered={false}>
+              <Statistic title="迟到率" value={attendanceSummary.lateRate} suffix="%" />
+            </Card>
+          </Col>
+        </Row>
+      )}
+    </div>
+  );
+};

apps/admin/src/pages/Classes/detail.tsx

@@ -1,154 +1,30 @@
-import React, { useEffect, useState, useCallback } from 'react';
-import { useParams, useNavigate } from 'react-router-dom';
-import {
-  Card,
-  Tabs,
-  Descriptions,
-  Table,
-  Button,
-  Space,
-  Select,
-  Modal,
-  Tag,
-  Popconfirm,
-  Form,
-  Input,
-  DatePicker,
-  InputNumber,
-  Row,
-  Col,
-  Statistic,
-} from 'antd';
-import type { ColumnsType } from 'antd/es/table';
-import { ArrowLeftOutlined, PlusOutlined, DownloadOutlined } from '@ant-design/icons';
+import React, { useState, useCallback } from 'react';
+import { useParams, useNavigate } from 'react-router';
+import { Button, Card, Form, Space, Tabs, Tag } from 'antd';
+import { ArrowLeftOutlined } from '@ant-design/icons';
 import dayjs from 'dayjs';
 import api from '../../api';
-import PermissionButton from '../../components/PermissionButton';
 import { message } from '../../ui/app-message';
-import { buildTeacherCandidateOptions, type TeacherCandidateUser } from './teacher-candidate';
-
-// ---- Types ----
-
-interface ClassStudent {
-  id: number;
-  studentId: number;
-  studentName: string;
-  studentNo: string;
-  joinDate: string;
-  leaveDate: string | null;
-  status: string;
-}
-
-interface ClassTeacher {
-  id: number;
-  userId: number;
-  username: string;
-  roleType: string;
-  subject: string | null;
-}
-
-interface ClassScheduleItem {
-  id: number;
-  classId: number;
-  classroomId: number;
-  classroomName: string;
-  weekDay: number;
-  startTime: string;
-  endTime: string;
-  attendanceAdvanceMinutes: number;
-  startDate: string;
-  endDate: string;
-  subject: string;
-  teacherId: number | null;
-  scheduleType: string;
-  status: string;
-  notes: string | null;
-}
-
-interface AttendanceSummary {
-  total: number;
-  present: number;
-  late: number;
-  absent: number;
-  leave: number;
-  presentRate: number;
-  absentRate: number;
-  lateRate: number;
-  leaveRate: number;
-}
-
-interface ClassDetail {
-  id: number;
-  name: string;
-  code: string;
-  classType: string;
-  startDate: string | null;
-  endDate: string | null;
-  status: string;
-  maxStudents: number;
-  notes: string | null;
-  studentCount: number;
-  students?: ClassStudent[];
-  teachers?: ClassTeacher[];
-  createdAt: string;
-  updatedAt: string;
-}
-
-interface StudentItem {
-  id: number;
-  name: string;
-  studentNo?: string;
-}
-
-type UserItem = TeacherCandidateUser;
-
-// ---- Constants ----
-
-const STATUS_MAP: Record<string, { color: string; text: string }> = {
-  enrolling: { color: 'blue', text: '招生中' },
-  active: { color: 'green', text: '在读' },
-  ended: { color: 'default', text: '结课' },
-  suspended: { color: 'orange', text: '停课' },
-};
-
-const TYPE_MAP: Record<string, string> = {
-  culture: '文化课',
-  professional: '专业课',
-  bootcamp: '集训营',
-  sprint: '冲刺营',
-};
-
-const ROLE_MAP: Record<string, string> = {
-  subject_teacher: '任课老师',
-  head_teacher: '班主任',
-  life_teacher: '生活老师',
-  academic_teacher: '学服老师',
-};
-
-const WEEK_DAY_MAP: Record<number, string> = {
-  1: '周一',
-  2: '周二',
-  3: '周三',
-  4: '周四',
-  5: '周五',
-  6: '周六',
-  7: '周日',
-};
-
-const SCHEDULE_TYPE_MAP: Record<string, string> = {
-  INTERNAL: '内部排课',
-  RENTAL: '租赁',
-};
-
-// ---- Component ----
+import { useQuery } from '@tanstack/react-query';
+import type { TeacherCandidateUser } from './teacher-candidate';
+import { getErrorMessage } from '../../utils/error';
+import {
+  ClassAttendanceTab,
+  ClassInfoTab,
+  ClassScheduleTab,
+  ClassStudentsTab,
+  ClassTeachersTab,
+  STATUS_MAP,
+  type ClassDetail,
+  type ClassTeacher,
+  type StudentItem,
+  type AttendanceSummary,
+  type ClassScheduleItem,
+} from './ClassDetailTabs';
 
 const ClassDetailPage: React.FC = () => {
   const { id } = useParams<{ id: string }>();
   const navigate = useNavigate();
-  const [detail, setDetail] = useState<ClassDetail | null>(null);
-  const [students, setStudents] = useState<ClassStudent[]>([]);
-  const [teachers, setTeachers] = useState<ClassTeacher[]>([]);
-  const [loading, setLoading] = useState(false);
   const [editForm] = Form.useForm();
   const [editingInfo, setEditingInfo] = useState(false);
 
@@ -159,75 +35,93 @@ const ClassDetailPage: React.FC = () => {
 
   // Teacher modal state
   const [teacherModalOpen, setTeacherModalOpen] = useState(false);
-  const [allUsers, setAllUsers] = useState<UserItem[]>([]);
   const [teacherRole, setTeacherRole] = useState('subject_teacher');
   const [teacherSubject, setTeacherSubject] = useState('');
   const [teacherUserId, setTeacherUserId] = useState<number>();
 
   // Schedule & attendance state
-  const [schedules, setSchedules] = useState<ClassScheduleItem[]>([]);
   const [scheduleDateRange, setScheduleDateRange] = useState<
     [dayjs.Dayjs | null, dayjs.Dayjs | null]
   >([null, null]);
-  const [attendanceSummary, setAttendanceSummary] = useState<AttendanceSummary | null>(null);
   const [attendanceDateRange, setAttendanceDateRange] = useState<
     [dayjs.Dayjs | null, dayjs.Dayjs | null]
   >([null, null]);
 
-  const fetchDetail = useCallback(async () => {
-    setLoading(true);
-    try {
-      const res = (await api.get(`/classes/${id}`)) as ClassDetail;
-      setDetail(res);
-      setStudents(res.students || []);
-      setTeachers(res.teachers || []);
-    } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '加载失败');
-    } finally {
-      setLoading(false);
-    }
-  }, [id]);
+  const {
+    data: detailResult = { detail: null, students: [], teachers: [] },
+    isLoading: detailLoading,
+    isFetching: detailFetching,
+    refetch: refetchDetail,
+  } = useQuery<{
+    detail: ClassDetail | null;
+    students: ClassDetail['students'];
+    teachers: ClassDetail['teachers'];
+  }>({
+    queryKey: ['classes', 'detail', id],
+    queryFn: async () => {
+      try {
+        const res = (await api.get(`/classes/${id}`)) as ClassDetail;
+        return { detail: res, students: res.students || [], teachers: res.teachers || [] };
+      } catch (e: unknown) {
+        message.error(getErrorMessage(e, '加载失败'));
+        return { detail: null, students: [], teachers: [] };
+      }
+    },
+  });
+  const detail = detailResult.detail;
+  const students = detailResult.students ?? [];
+  const teachers = detailResult.teachers ?? [];
+  const loading = detailLoading || detailFetching;
+  const fetchDetail = useCallback(() => refetchDetail(), [refetchDetail]);
 
-  useEffect(() => {
-    fetchDetail();
-  }, [fetchDetail]);
+  const { data: allUsers = [], refetch: refetchUsers } = useQuery<TeacherCandidateUser[]>({
+    queryKey: ['rbac', 'users', 'all'],
+    queryFn: async () => {
+      try {
+        return (await api.get('/rbac/users')) as TeacherCandidateUser[];
+      } catch {
+        return [];
+      }
+    },
+  });
+  const fetchUsers = useCallback(() => refetchUsers(), [refetchUsers]);
 
-  const fetchSchedules = useCallback(async () => {
-    if (!id) return;
-    try {
-      const params: Record<string, string> = {};
-      if (scheduleDateRange?.[0]) params.startDate = scheduleDateRange[0].format('YYYY-MM-DD');
-      if (scheduleDateRange?.[1]) params.endDate = scheduleDateRange[1].format('YYYY-MM-DD');
-      const res = await api.get<ClassScheduleItem[]>(`/classes/${id}/schedule`, { params });
-      setSchedules(res || []);
-    } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '加载课表失败');
-    }
-  }, [id, scheduleDateRange]);
+  const { data: schedules = [] } = useQuery<ClassScheduleItem[]>({
+    queryKey: ['classes', 'schedule', id, scheduleDateRange],
+    queryFn: async () => {
+      if (!id) return [];
+      try {
+        const params: Record<string, string> = {};
+        if (scheduleDateRange?.[0]) params.startDate = scheduleDateRange[0].format('YYYY-MM-DD');
+        if (scheduleDateRange?.[1]) params.endDate = scheduleDateRange[1].format('YYYY-MM-DD');
+        return (await api.get<ClassScheduleItem[]>(`/classes/${id}/schedule`, { params })) || [];
+      } catch (e: unknown) {
+        message.error(getErrorMessage(e, '加载课表失败'));
+        return [];
+      }
+    },
+  });
 
-  useEffect(() => {
-    fetchSchedules();
-  }, [fetchSchedules]);
-
-  const fetchAttendanceSummary = useCallback(async () => {
-    if (!id) return;
-    try {
-      const params: Record<string, string> = {};
-      if (attendanceDateRange?.[0]) params.startDate = attendanceDateRange[0].format('YYYY-MM-DD');
-      if (attendanceDateRange?.[1]) params.endDate = attendanceDateRange[1].format('YYYY-MM-DD');
-      const res = await api.get<AttendanceSummary>(`/classes/${id}/attendance-summary`, { params });
-      setAttendanceSummary(res || null);
-    } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '加载出勤汇总失败');
-    }
-  }, [id, attendanceDateRange]);
-
-  useEffect(() => {
-    fetchAttendanceSummary();
-  }, [fetchAttendanceSummary]);
+  const { data: attendanceSummary = null } = useQuery<AttendanceSummary | null>({
+    queryKey: ['classes', 'attendance-summary', id, attendanceDateRange],
+    queryFn: async () => {
+      if (!id) return null;
+      try {
+        const params: Record<string, string> = {};
+        if (attendanceDateRange?.[0])
+          params.startDate = attendanceDateRange[0].format('YYYY-MM-DD');
+        if (attendanceDateRange?.[1]) params.endDate = attendanceDateRange[1].format('YYYY-MM-DD');
+        return (
+          (await api.get<AttendanceSummary>(`/classes/${id}/attendance-summary`, {
+            params,
+          })) || null
+        );
+      } catch (e: unknown) {
+        message.error(getErrorMessage(e, '加载出勤汇总失败'));
+        return null;
+      }
+    },
+  });
 
   const handleSaveInfo = async () => {
     try {
@@ -246,8 +140,7 @@ const ClassDetailPage: React.FC = () => {
       fetchDetail();
       message.success('已更新');
     } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '更新失败');
+      message.error(getErrorMessage(e, '更新失败'));
     }
   };
 
@@ -257,8 +150,7 @@ const ClassDetailPage: React.FC = () => {
       fetchDetail();
       message.success('已移除');
     } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '移除失败');
+      message.error(getErrorMessage(e, '移除失败'));
     }
   };
 
@@ -271,8 +163,7 @@ const ClassDetailPage: React.FC = () => {
       fetchDetail();
       message.success('已添加');
     } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '添加失败');
+      message.error(getErrorMessage(e, '添加失败'));
     }
   };
 
@@ -288,8 +179,7 @@ const ClassDetailPage: React.FC = () => {
       fetchDetail();
       message.success('已添加');
     } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '添加失败');
+      message.error(getErrorMessage(e, '添加失败'));
     }
   };
 
@@ -299,8 +189,7 @@ const ClassDetailPage: React.FC = () => {
       fetchDetail();
       message.success('已移除');
     } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '移除失败');
+      message.error(getErrorMessage(e, '移除失败'));
     }
   };
 
@@ -313,103 +202,27 @@ const ClassDetailPage: React.FC = () => {
       setSelectedStudentIds([]);
       setStudentModalOpen(true);
     } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '加载学员列表失败');
+      message.error(getErrorMessage(e, '加载学员列表失败'));
     }
   };
 
   const openTeacherModal = async () => {
     try {
-      const res = (await api.get('/rbac/users')) as UserItem[];
-      setAllUsers(res || []);
+      await fetchUsers();
       setTeacherUserId(undefined);
       setTeacherRole('subject_teacher');
       setTeacherSubject('');
       setTeacherModalOpen(true);
     } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '加载用户列表失败');
+      message.error(getErrorMessage(e, '加载用户列表失败'));
     }
   };
 
+  const getTeacherName = (teacher: ClassTeacher) =>
+    allUsers.find((user) => user.id === teacher.userId)?.name?.trim() || '-';
+
   if (!detail) return null;
 
-  const studentColumns: ColumnsType<ClassStudent> = [
-    { title: '姓名', dataIndex: 'studentName' },
-    { title: '学号', dataIndex: 'studentNo' },
-    { title: '加入日期', dataIndex: 'joinDate' },
-    { title: '离班日期', dataIndex: 'leaveDate', render: (v: string | null) => v || '-' },
-    {
-      title: '状态',
-      dataIndex: 'status',
-      render: (v: string) => (
-        <Tag color={v === 'active' ? 'green' : 'default'}>{v === 'active' ? '在读' : '已离班'}</Tag>
-      ),
-    },
-    {
-      title: '操作',
-      render: (_: unknown, r: ClassStudent) =>
-        r.status === 'active' ? (
-          <Popconfirm title="确认移除？" onConfirm={() => handleRemoveStudent(r.studentId)}>
-            <PermissionButton permission="class:edit" size="small" danger>
-              移除
-            </PermissionButton>
-          </Popconfirm>
-        ) : null,
-    },
-  ];
-
-  const teacherColumns: ColumnsType<ClassTeacher> = [
-    { title: '姓名', dataIndex: 'username' },
-    {
-      title: '角色',
-      dataIndex: 'roleType',
-      render: (v: string) => <Tag>{ROLE_MAP[v] || v}</Tag>,
-    },
-    {
-      title: '科目',
-      dataIndex: 'subject',
-      render: (v: string | null) => v || '-',
-    },
-    {
-      title: '操作',
-      render: (_: unknown, r: ClassTeacher) => (
-        <Popconfirm title="确认移除？" onConfirm={() => handleRemoveTeacher(r.userId)}>
-          <PermissionButton permission="class:edit" size="small" danger>
-            移除
-          </PermissionButton>
-        </Popconfirm>
-      ),
-    },
-  ];
-
-  const scheduleColumns: ColumnsType<ClassScheduleItem> = [
-    { title: '教室', dataIndex: 'classroomName', render: (v: string | null) => v || '-' },
-    { title: '星期', dataIndex: 'weekDay', render: (v: number) => WEEK_DAY_MAP[v] || v },
-    {
-      title: '时间',
-      render: (_: unknown, r: ClassScheduleItem) => `${r.startTime} - ${r.endTime}`,
-    },
-    {
-      title: '签到窗口',
-      render: (_: unknown, r: ClassScheduleItem) =>
-        `课前 ${r.attendanceAdvanceMinutes ?? 30} 分钟至下课`,
-    },
-    {
-      title: '日期范围',
-      render: (_: unknown, r: ClassScheduleItem) => `${r.startDate} ~ ${r.endDate}`,
-    },
-    { title: '科目', dataIndex: 'subject' },
-    { title: '类型', dataIndex: 'scheduleType', render: (v: string) => SCHEDULE_TYPE_MAP[v] || v },
-    {
-      title: '状态',
-      dataIndex: 'status',
-      render: (v: string) => (
-        <Tag color={v === 'active' ? 'green' : 'default'}>{v === 'active' ? '启用' : v}</Tag>
-      ),
-    },
-  ];
-
   return (
     <Card
       title={
@@ -430,320 +243,91 @@ const ClassDetailPage: React.FC = () => {
             key: 'info',
             label: '基本信息',
             children: (
-              <div>
-                {editingInfo ? (
-                  <Form
-                    form={editForm}
-                    layout="vertical"
-                    initialValues={{
-                      name: detail.name,
-                      code: detail.code,
-                      classType: detail.classType,
-                      startDate: detail.startDate ? dayjs(detail.startDate) : undefined,
-                      endDate: detail.endDate ? dayjs(detail.endDate) : undefined,
-                      maxStudents: detail.maxStudents,
-                      status: detail.status,
-                      notes: detail.notes,
-                    }}
-                  >
-                    <Space wrap>
-                      <Form.Item name="name" label="名称" rules={[{ required: true }]}>
-                        <Input />
-                      </Form.Item>
-                      <Form.Item name="code" label="编码">
-                        <Input />
-                      </Form.Item>
-                      <Form.Item name="classType" label="班型">
-                        <Select
-                          options={Object.entries(TYPE_MAP).map(([k, v]) => ({
-                            value: k,
-                            label: v,
-                          }))}
-                        />
-                      </Form.Item>
-                      <Form.Item name="startDate" label="开班">
-                        <DatePicker />
-                      </Form.Item>
-                      <Form.Item name="endDate" label="结课">
-                        <DatePicker />
-                      </Form.Item>
-                      <Form.Item name="maxStudents" label="人数上限">
-                        <InputNumber min={1} />
-                      </Form.Item>
-                      <Form.Item name="status" label="状态">
-                        <Select
-                          options={Object.entries(STATUS_MAP).map(([k, v]) => ({
-                            value: k,
-                            label: v.text,
-                          }))}
-                        />
-                      </Form.Item>
-                    </Space>
-                    <Form.Item name="notes" label="备注">
-                      <Input.TextArea rows={3} />
-                    </Form.Item>
-                    <Space>
-                      <PermissionButton
-                        permission="class:edit"
-                        type="primary"
-                        onClick={handleSaveInfo}
-                      >
-                        保存
-                      </PermissionButton>
-                      <Button onClick={() => setEditingInfo(false)}>取消</Button>
-                    </Space>
-                  </Form>
-                ) : (
-                  <div>
-                    <Descriptions column={3} bordered size="small">
-                      <Descriptions.Item label="班型">
-                        {TYPE_MAP[detail.classType]}
-                      </Descriptions.Item>
-                      <Descriptions.Item label="开班日期">
-                        {detail.startDate ? dayjs(detail.startDate).format('YYYY-MM-DD') : '-'}
-                      </Descriptions.Item>
-                      <Descriptions.Item label="结课日期">
-                        {detail.endDate ? dayjs(detail.endDate).format('YYYY-MM-DD') : '-'}
-                      </Descriptions.Item>
-                      <Descriptions.Item label="学员">
-                        {detail.studentCount}/{detail.maxStudents || '-'}
-                      </Descriptions.Item>
-                      <Descriptions.Item label="班主任">
-                        {teachers.find((t) => t.roleType === 'head_teacher')?.username || '-'}
-                      </Descriptions.Item>
-                      <Descriptions.Item label="备注">{detail.notes || '-'}</Descriptions.Item>
-                    </Descriptions>
-                    <PermissionButton
-                      permission="class:edit"
-                      style={{ marginTop: 16 }}
-                      onClick={() => {
-                        editForm.setFieldsValue({
-                          name: detail.name,
-                          code: detail.code,
-                          classType: detail.classType,
-                          startDate: detail.startDate ? dayjs(detail.startDate) : undefined,
-                          endDate: detail.endDate ? dayjs(detail.endDate) : undefined,
-                          maxStudents: detail.maxStudents,
-                          status: detail.status,
-                          notes: detail.notes,
-                        });
-                        setEditingInfo(true);
-                      }}
-                    >
-                      编辑
-                    </PermissionButton>
-                  </div>
-                )}
-              </div>
+              <ClassInfoTab
+                detail={detail}
+                teachers={teachers}
+                editingInfo={editingInfo}
+                editForm={editForm}
+                onSave={handleSaveInfo}
+                onEdit={() => {
+                  editForm.setFieldsValue({
+                    name: detail.name,
+                    code: detail.code,
+                    classType: detail.classType,
+                    startDate: detail.startDate ? dayjs(detail.startDate) : undefined,
+                    endDate: detail.endDate ? dayjs(detail.endDate) : undefined,
+                    maxStudents: detail.maxStudents,
+                    status: detail.status,
+                    notes: detail.notes,
+                  });
+                  setEditingInfo(true);
+                }}
+                onCancel={() => setEditingInfo(false)}
+                getTeacherName={getTeacherName}
+              />
             ),
           },
           {
             key: 'students',
             label: `花名册 (${students.filter((s) => s.status === 'active').length})`,
             children: (
-              <div>
-                <PermissionButton
-                  permission="class:edit"
-                  icon={<PlusOutlined />}
-                  type="primary"
-                  onClick={openStudentModal}
-                  style={{ marginBottom: 16, marginRight: 8 }}
-                >
-                  添加学员
-                </PermissionButton>
-                <PermissionButton
-                  permission="class:view"
-                  icon={<DownloadOutlined />}
-                  onClick={() => {
-                    const token = localStorage.getItem('token');
-                    fetch(`/api/classes/${id}/roster/export`, {
-                      headers: { Authorization: `Bearer ${token}` },
-                    })
-                      .then((res) => {
-                        if (!res.ok) throw new Error('导出失败');
-                        return res.blob();
-                      })
-                      .then((blob) => {
-                        const url = URL.createObjectURL(blob);
-                        const a = document.createElement('a');
-                        a.href = url;
-                        a.download = `班级花名册-${detail?.name || id}.xlsx`;
-                        a.click();
-                        URL.revokeObjectURL(url);
-                        message.success('花名册导出成功');
-                      })
-                      .catch(() => message.error('花名册导出失败'));
-                  }}
-                >
-                  导出花名册
-                </PermissionButton>
-                <Table<ClassStudent>
-                  columns={studentColumns}
-                  dataSource={students}
-                  rowKey="id"
-                  pagination={{
-                    defaultPageSize: 20,
-                    showSizeChanger: true,
-                    pageSizeOptions: [20, 50, 100],
-                  }}
-                />
-                <Modal
-                  title="添加学员"
-                  open={studentModalOpen}
-                  onOk={handleAddStudents}
-                  onCancel={() => setStudentModalOpen(false)}
-                >
-                  <Select
-                    mode="multiple"
-                    style={{ width: '100%' }}
-                    placeholder="选择学员"
-                    value={selectedStudentIds}
-                    onChange={setSelectedStudentIds}
-                    options={allStudents.map((s) => ({
-                      value: s.id,
-                      label: `${s.name} (${s.studentNo || s.id})`,
-                    }))}
-                    filterOption={(input, option) =>
-                      (option?.label as string)?.toLowerCase().includes(input.toLowerCase())
-                    }
-                  />
-                </Modal>
-              </div>
+              <ClassStudentsTab
+                id={id}
+                detail={detail}
+                students={students}
+                allStudents={allStudents}
+                selectedStudentIds={selectedStudentIds}
+                modalOpen={studentModalOpen}
+                onOpen={openStudentModal}
+                onAdd={handleAddStudents}
+                onClose={() => setStudentModalOpen(false)}
+                onRemove={handleRemoveStudent}
+                onSelect={setSelectedStudentIds}
+              />
             ),
           },
           {
             key: 'teachers',
             label: `教师 (${teachers.length})`,
             children: (
-              <div>
-                <PermissionButton
-                  permission="class:edit"
-                  icon={<PlusOutlined />}
-                  type="primary"
-                  onClick={openTeacherModal}
-                  style={{ marginBottom: 16 }}
-                >
-                  添加教师
-                </PermissionButton>
-                <Table<ClassTeacher>
-                  columns={teacherColumns}
-                  dataSource={teachers}
-                  rowKey="id"
-                  pagination={{
-                    defaultPageSize: 20,
-                    showSizeChanger: true,
-                    pageSizeOptions: [20, 50, 100],
-                  }}
-                />
-                <Modal
-                  title="添加教师"
-                  open={teacherModalOpen}
-                  onOk={handleAddTeacher}
-                  onCancel={() => setTeacherModalOpen(false)}
-                >
-                  <Space direction="vertical" style={{ width: '100%' }}>
-                    <Select
-                      style={{ width: '100%' }}
-                      showSearch
-                      optionFilterProp="label"
-                      placeholder="搜索姓名、用户名、角色或学科"
-                      value={teacherUserId}
-                      onChange={setTeacherUserId}
-                      options={buildTeacherCandidateOptions(allUsers)}
-                      notFoundContent="没有可分配的工作人员账号"
-                    />
-                    <Select
-                      style={{ width: '100%' }}
-                      value={teacherRole}
-                      onChange={setTeacherRole}
-                      options={Object.entries(ROLE_MAP).map(([k, v]) => ({
-                        value: k,
-                        label: v,
-                      }))}
-                    />
-                    {teacherRole === 'subject_teacher' && (
-                      <Input
-                        placeholder="任教科目"
-                        value={teacherSubject}
-                        onChange={(e) => setTeacherSubject(e.target.value)}
-                      />
-                    )}
-                  </Space>
-                </Modal>
-              </div>
+              <ClassTeachersTab
+                teachers={teachers}
+                allUsers={allUsers}
+                teacherRole={teacherRole}
+                teacherSubject={teacherSubject}
+                teacherUserId={teacherUserId}
+                modalOpen={teacherModalOpen}
+                onOpen={openTeacherModal}
+                onAdd={handleAddTeacher}
+                onClose={() => setTeacherModalOpen(false)}
+                onRemove={handleRemoveTeacher}
+                onRoleChange={setTeacherRole}
+                onSubjectChange={setTeacherSubject}
+                onUserChange={setTeacherUserId}
+                getTeacherName={getTeacherName}
+              />
             ),
           },
           {
             key: 'schedule',
             label: '课表',
             children: (
-              <div>
-                <Space style={{ marginBottom: 16, maxWidth: '100%' }} wrap>
-                  <DatePicker.RangePicker
-                    value={scheduleDateRange}
-                    onChange={(dates) =>
-                      setScheduleDateRange(dates as [dayjs.Dayjs | null, dayjs.Dayjs | null])
-                    }
-                    placeholder={['开始日期', '结束日期']}
-                  />
-                </Space>
-                <Table<ClassScheduleItem>
-                  columns={scheduleColumns}
-                  dataSource={schedules}
-                  rowKey="id"
-                  scroll={{ x: 'max-content' }}
-                  pagination={{
-                    defaultPageSize: 20,
-                    showSizeChanger: true,
-                    pageSizeOptions: [20, 50, 100],
-                  }}
-                />
-              </div>
+              <ClassScheduleTab
+                schedules={schedules}
+                scheduleDateRange={scheduleDateRange}
+                onRangeChange={setScheduleDateRange}
+              />
             ),
           },
           {
             key: 'attendance-summary',
             label: '出勤汇总',
             children: (
-              <div>
-                <Space style={{ marginBottom: 16, maxWidth: '100%' }} wrap>
-                  <DatePicker.RangePicker
-                    value={attendanceDateRange}
-                    onChange={(dates) =>
-                      setAttendanceDateRange(dates as [dayjs.Dayjs | null, dayjs.Dayjs | null])
-                    }
-                    placeholder={['开始日期', '结束日期']}
-                  />
-                </Space>
-                {attendanceSummary && (
-                  <Row gutter={[16, 16]}>
-                    <Col xs={12} md={6}>
-                      <Card bordered={false}>
-                        <Statistic title="总记录" value={attendanceSummary.total} />
-                      </Card>
-                    </Col>
-                    <Col xs={12} md={6}>
-                      <Card bordered={false}>
-                        <Statistic
-                          title="出勤率"
-                          value={attendanceSummary.presentRate}
-                          suffix="%"
-                        />
-                      </Card>
-                    </Col>
-                    <Col xs={12} md={6}>
-                      <Card bordered={false}>
-                        <Statistic title="缺勤率" value={attendanceSummary.absentRate} suffix="%" />
-                      </Card>
-                    </Col>
-                    <Col xs={12} md={6}>
-                      <Card bordered={false}>
-                        <Statistic title="迟到率" value={attendanceSummary.lateRate} suffix="%" />
-                      </Card>
-                    </Col>
-                  </Row>
-                )}
-              </div>
+              <ClassAttendanceTab
+                attendanceSummary={attendanceSummary}
+                attendanceDateRange={attendanceDateRange}
+                onRangeChange={setAttendanceDateRange}
+              />
             ),
           },
         ]}

apps/admin/src/pages/Classes/index.tsx

@@ -1,5 +1,11 @@
-import React, { useEffect, useState, useMemo, useCallback } from 'react';
+// aislop-ignore-file: duplicate-block -- 表格/表单声明结构相似且参数不同，渲染逻辑已共享组件化
+import React, { useState, useMemo, useCallback } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { useApiMutation } from '../../hooks/useApiMutation';
+import { validateResponse } from '../../utils/validate';
+import { classesSchema } from '../../api/schemas';
 import {
+  App,
   Table,
   Button,
   Input,
@@ -17,14 +23,13 @@ import {
 } from 'antd';
 import type { ColumnsType } from 'antd/es/table';
 import { PlusOutlined, SearchOutlined, TeamOutlined, InboxOutlined } from '@ant-design/icons';
-import { useNavigate } from 'react-router-dom';
+import { useNavigate } from 'react-router';
 import dayjs from 'dayjs';
 import api from '../../api';
 import PermissionButton from '../../components/PermissionButton';
 import EditableCell from '../../components/EditableCell';
 import { message } from '../../ui/app-message';
-
-// ---- Types ----
+import { usePermission } from '../../hooks/usePermission';
 
 interface ClassItem {
   id: number;
@@ -56,8 +61,6 @@ interface ClassFormValues {
   notes?: string;
 }
 
-// ---- Constants ----
-
 const STATUS_MAP: Record<string, { color: string; text: string }> = {
   enrolling: { color: 'blue', text: '招生中' },
   active: { color: 'green', text: '在读' },
@@ -72,12 +75,11 @@ const TYPE_MAP: Record<string, string> = {
   sprint: '冲刺营',
 };
 
-// ---- Component ----
-
 const ClassesPage: React.FC = () => {
+  const { modal } = App.useApp();
   const navigate = useNavigate();
-  const [data, setData] = useState<ClassItem[]>([]);
-  const [loading, setLoading] = useState(false);
+  const { hasPermission } = usePermission();
+  const canPurgeClass = hasPermission('class:purge');
   const [modalOpen, setModalOpen] = useState(false);
   const [editing, setEditing] = useState<ClassItem | null>(null);
   const [searchText, setSearchText] = useState('');
@@ -89,34 +91,74 @@ const ClassesPage: React.FC = () => {
 
   const handleArchive = async (id: number, archive: boolean) => {
     try {
-      await api.put(`/classes/${id}/${archive ? 'archive' : 'restore'}`);
+      await archiveMutation.mutateAsync({ id, archive });
       message.success(archive ? '已归档' : '已恢复');
-      fetchData();
-    } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '操作失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     }
   };
 
-  const fetchData = useCallback(async () => {
-    setLoading(true);
-    try {
-      const params: Record<string, string | boolean | undefined> = {};
-      if (filterStatus) params.status = filterStatus;
-      if (filterType) params.classType = filterType;
-      params.isArchived = showArchived;
-      const res = await api.get<ClassItem[]>('/classes', { params } as Record<string, unknown>);
-      setData(res);
-    } catch (e: any) {
-      message.error(e?.message || '加载失败，请稍后重试');
-    } finally {
-      setLoading(false);
-    }
-  }, [filterStatus, filterType, showArchived]);
+  const handlePurge = (record: ClassItem) => {
+    modal.confirm({
+      title: `永久删除班级「${record.name}」？`,
+      content: '删除后不可恢复，存在学生、教师、排课、考试或考勤关联时将无法删除。确定继续？',
+      okText: '永久删除',
+      okButtonProps: { danger: true },
+      cancelText: '取消',
+      onOk: async () => {
+        try {
+          await purgeMutation.mutateAsync(record.id);
+          message.success('已永久删除（不可恢复）');
+        } catch {
+          // 错误提示由 useApiMutation 统一处理
+        }
+      },
+    });
+  };
 
-  useEffect(() => {
-    fetchData();
-  }, [fetchData]);
+  const {
+    data = [],
+    isLoading,
+    isFetching,
+  } = useQuery<ClassItem[]>({
+    queryKey: ['classes', filterStatus, filterType, showArchived],
+    queryFn: async () => {
+      try {
+        const params: Record<string, string | boolean | undefined> = {};
+        if (filterStatus) params.status = filterStatus;
+        if (filterType) params.classType = filterType;
+        params.isArchived = showArchived;
+        return validateResponse<ClassItem[]>(
+          classesSchema,
+          await api.get<ClassItem[]>('/classes', { params } as Record<string, unknown>),
+        );
+      } catch (e: any) {
+        message.error(e?.message || '加载失败，请稍后重试');
+        return [];
+      }
+    },
+  });
+  const loading = isLoading || isFetching;
+
+  const saveMutation = useApiMutation(
+    async (payload: Record<string, unknown>) =>
+      editing ? api.put(`/classes/${editing.id}`, payload) : api.post('/classes', payload),
+    { invalidate: [['classes']] },
+  );
+  const saveCellMutation = useApiMutation(
+    async ({ record, field, value }: { record: ClassItem; field: string; value: unknown }) =>
+      api.put(`/classes/${record.id}`, { [field]: value }),
+    { invalidate: [['classes']] },
+  );
+  const archiveMutation = useApiMutation(
+    async ({ id, archive }: { id: number; archive: boolean }) =>
+      api.put(`/classes/${id}/${archive ? 'archive' : 'restore'}`),
+    { invalidate: [['classes']] },
+  );
+  const purgeMutation = useApiMutation(
+    async (id: number) => api.delete(`/classes/${id}/permanent`),
+    { invalidate: [['classes']] },
+  );
 
   const filtered = useMemo(() => {
     if (!searchText) return data;
@@ -152,17 +194,11 @@ const ClassesPage: React.FC = () => {
         startDate: values.startDate?.format('YYYY-MM-DD'),
         endDate: values.endDate?.format('YYYY-MM-DD'),
       };
-      if (editing) {
-        await api.put(`/classes/${editing.id}`, payload);
-        message.success('更新成功');
-      } else {
-        await api.post('/classes', payload);
-        message.success('创建成功');
-      }
+      await saveMutation.mutateAsync(payload);
+      message.success(editing ? '更新成功' : '创建成功');
       setModalOpen(false);
-      fetchData();
-    } catch (e: any) {
-      message.error(e?.message || '操作失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     } finally {
       setSaving(false);
     }
@@ -170,11 +206,14 @@ const ClassesPage: React.FC = () => {
 
   const saveCell = useCallback(
     async (record: ClassItem, field: string, value: unknown) => {
-      await api.put(`/classes/${record.id}`, { [field]: value });
-      message.success('已保存');
-      await fetchData();
+      try {
+        await saveCellMutation.mutateAsync({ record, field, value });
+        message.success('已保存');
+      } catch {
+        // 错误提示由 useApiMutation 统一处理
+      }
     },
-    [fetchData],
+    [saveCellMutation],
   );
 
   const columns: ColumnsType<ClassItem> = useMemo(
@@ -196,6 +235,7 @@ const ClassesPage: React.FC = () => {
           </EditableCell>
         ),
       },
+
       {
         title: '编码',
         dataIndex: 'code',
@@ -212,6 +252,7 @@ const ClassesPage: React.FC = () => {
           </EditableCell>
         ),
       },
+
       {
         title: '班型',
         dataIndex: 'classType',
@@ -229,6 +270,7 @@ const ClassesPage: React.FC = () => {
           </EditableCell>
         ),
       },
+
       {
         title: '开班日期',
         dataIndex: 'startDate',
@@ -245,6 +287,7 @@ const ClassesPage: React.FC = () => {
           </EditableCell>
         ),
       },
+
       {
         title: '学员',
         width: 100,
@@ -259,6 +302,7 @@ const ClassesPage: React.FC = () => {
           >{`${r.studentCount || 0}/${r.maxStudents || '-'}`}</EditableCell>
         ),
       },
+
       {
         title: '状态',
         dataIndex: 'status',
@@ -282,6 +326,7 @@ const ClassesPage: React.FC = () => {
           </EditableCell>
         ),
       },
+
       {
         title: '操作',
         width: 280,
@@ -298,11 +343,18 @@ const ClassesPage: React.FC = () => {
               编辑
             </PermissionButton>
             {r.isArchived ? (
-              <Popconfirm title="确认恢复？" onConfirm={() => handleArchive(r.id, false)}>
-                <PermissionButton permission="class:edit" size="small">
-                  恢复
-                </PermissionButton>
-              </Popconfirm>
+              <>
+                <Popconfirm title="确认恢复？" onConfirm={() => handleArchive(r.id, false)}>
+                  <PermissionButton permission="class:edit" size="small">
+                    恢复
+                  </PermissionButton>
+                </Popconfirm>
+                {canPurgeClass ? (
+                  <Button size="small" danger type="link" onClick={() => handlePurge(r)}>
+                    删除
+                  </Button>
+                ) : null}
+              </>
             ) : (
               <Popconfirm
                 title="归档后可恢复，确认归档？"
@@ -317,7 +369,7 @@ const ClassesPage: React.FC = () => {
         ),
       },
     ],
-    [saveCell],
+    [saveCell, canPurgeClass, handlePurge],
   );
 
   return (

apps/admin/src/pages/Classes/teacher-candidate.integration.test.ts

@@ -10,7 +10,6 @@ const baseUser = (overrides: Partial<TeacherCandidateUser> = {}): TeacherCandida
   id: 1,
   username: 'teacher',
   name: '测试老师',
-  isActive: true,
   isArchived: false,
   studentStatus: null,
   roles: [{ code: 'teacher', name: '任课老师' }],
@@ -29,13 +28,12 @@ describe('class teacher candidates', () => {
     expect(isTeacherCandidate(baseUser({ studentStatus: 'staff' }))).toBe(true);
   });
 
-  it('excludes active students, disabled, archived, and super-admin accounts', () => {
+  it('excludes active students, archived, and super-admin accounts', () => {
     const users = [
       baseUser({ id: 1, studentStatus: 'active' }),
-      baseUser({ id: 2, isActive: false }),
-      baseUser({ id: 3, isArchived: true }),
+      baseUser({ id: 2, isArchived: true }),
       baseUser({
-        id: 4,
+        id: 3,
         roles: [{ code: 'super_admin', name: '超级管理员' }],
       }),
     ];

apps/admin/src/pages/Classes/teacher-candidate.ts

@@ -7,7 +7,6 @@ export interface TeacherCandidateUser {
   id: number;
   username: string;
   name?: string | null;
-  isActive: boolean;
   isArchived: boolean;
   studentStatus?: string | null;
   roles?: TeacherCandidateRole[];
@@ -18,7 +17,7 @@ const isSuperAdminRole = (role: TeacherCandidateRole) =>
   role.code === 'super_admin' || role.name === '超级管理员' || role.name === '超管';
 
 export const isTeacherCandidate = (user: TeacherCandidateUser) => {
-  if (!user.isActive || user.isArchived) return false;
+  if (user.isArchived) return false;
   if (user.studentStatus && user.studentStatus !== 'staff') return false;
   return !(user.roles || []).some(isSuperAdminRole);
 };
@@ -29,9 +28,16 @@ export const buildTeacherCandidateLabel = (user: TeacherCandidateUser) => {
     displayName && displayName !== user.username
       ? `${displayName}（${user.username}）`
       : user.username;
-  const roleNames = [...new Set((user.roles || []).map((role) => role.name).filter(Boolean))];
+  const roleNames = [
+    ...new Set((user.roles || []).flatMap((role) => (role.name ? [role.name] : []))),
+  ];
   const subjects = [
-    ...new Set((user.profile?.subjects || []).map((subject) => subject.trim()).filter(Boolean)),
+    ...new Set(
+      (user.profile?.subjects || []).flatMap((subject) => {
+        const trimmed = subject.trim();
+        return trimmed ? [trimmed] : [];
+      }),
+    ),
   ];
 
   return [identity, roleNames.join('/'), subjects.join('/')].filter(Boolean).join(' · ');

apps/admin/src/pages/ClassroomRentals/RentalTable.tsx

@@ -0,0 +1,340 @@
+import React from 'react';
+import {
+  Button,
+  Empty,
+  Popconfirm,
+  Space,
+  Table,
+  Tag,
+  Tooltip,
+  Upload,
+} from 'antd';
+import {
+  CheckOutlined,
+  FileTextOutlined,
+  StopOutlined,
+  UploadOutlined,
+} from '@ant-design/icons';
+import dayjs from 'dayjs';
+import PermissionButton from '../../components/PermissionButton';
+import EditableCell from '../../components/EditableCell';
+import { message } from '../../ui/app-message';
+
+const RENTAL_FIELDS = {
+  classroomId: 'classroomId',
+  lesseeOrganizationId: 'lesseeOrganizationId',
+  startDate: 'startDate',
+  endDate: 'endDate',
+  dailyRate: 'dailyRate',
+  totalAmount: 'totalAmount',
+} as const;
+
+export interface RentalTableProps {
+  data: any[];
+  loading: boolean;
+  classrooms: any[];
+  organizations: any[];
+  canPurgeRental: boolean;
+  hasPermission: (permission: string) => boolean;
+  onSaveCell: (record: any, field: string, value: unknown) => Promise<void> | void;
+  onEdit: (record: any) => void;
+  onAction: (id: number, action: 'cancel' | 'end') => void;
+  onArchive: (id: number) => void;
+  onPurge: (id: number, name: string) => void;
+  onDownloadContract: (id: number, filename?: string) => void;
+  onDeleteContract: (id: number) => void;
+  onUploadContract: (id: number, formData: FormData) => Promise<unknown>;
+}
+
+export const RentalTable: React.FC<RentalTableProps> = ({
+  data,
+  loading,
+  classrooms,
+  organizations,
+  canPurgeRental,
+  hasPermission,
+  onSaveCell,
+  onEdit,
+  onAction,
+  onArchive,
+  onPurge,
+  onDownloadContract,
+  onDeleteContract,
+  onUploadContract,
+}) => {
+  const EditableRentalCell = <R extends { id: number; effectiveStatus?: string }>({
+    value,
+    field,
+    record,
+    editor,
+    min,
+    required,
+    options,
+    children,
+  }: {
+    value: unknown;
+    field: string;
+    record: R;
+    editor?: React.ComponentProps<typeof EditableCell>['editor'];
+    min?: number;
+    required?: boolean;
+    options?: Array<{ value: string | number; label: string }>;
+    children?: React.ReactNode;
+  }) => (
+    <EditableCell
+      value={value}
+      editor={editor}
+      min={min}
+      required={required}
+      options={options}
+      permission="rental:edit"
+      disabled={record.effectiveStatus !== 'active'}
+      onSave={async (next) => {
+        await onSaveCell(record, field, next);
+      }}
+    >
+      {children ?? String(value ?? '-')}
+    </EditableCell>
+  );
+
+  const columns = [
+    {
+      title: '教室',
+      width: 120,
+      dataIndex: 'classroom',
+      render: (c: any, r: any) => (
+        <EditableRentalCell
+          value={r.classroomId}
+          field={RENTAL_FIELDS.classroomId}
+          record={r}
+          editor="select"
+          options={classrooms
+            .filter((item) => item.status !== 'archived')
+            .map((item) => ({
+              value: item.id,
+              label: item.building ? `${item.building} · ${item.name}` : item.name,
+            }))}
+          required
+        >
+          {c ? (
+            <span>
+              {c.building ? `${c.building} · ` : ''}
+              {c.name}
+            </span>
+          ) : (
+            '-'
+          )}
+        </EditableRentalCell>
+      ),
+    },
+    {
+      title: '承租机构',
+      width: 100,
+      dataIndex: 'lesseeOrganization',
+      render: (t: any, r: any) => (
+        <EditableRentalCell
+          value={r.lesseeOrganizationId}
+          field={RENTAL_FIELDS.lesseeOrganizationId}
+          record={r}
+          editor="select"
+          options={organizations
+            .filter((item) => item.status !== 'archived')
+            .map((item) => ({ value: item.id, label: item.name }))}
+          required
+        >
+          {t ? (
+            <Tag
+              color={t.color}
+              style={{ background: t.color, color: '#fff', borderColor: t.color }}
+            >
+              {t.name}
+            </Tag>
+          ) : (
+            '-'
+          )}
+        </EditableRentalCell>
+      ),
+    },
+    {
+      title: '开始日期',
+      dataIndex: 'startDate',
+      width: 110,
+      render: (v: string, r: any) => (
+        <EditableRentalCell value={v} field={RENTAL_FIELDS.startDate} record={r} editor="date" required>
+          {v}
+        </EditableRentalCell>
+      ),
+    },
+    {
+      title: '结束日期',
+      dataIndex: 'endDate',
+      width: 110,
+      render: (v: string, r: any) => (
+        <EditableRentalCell value={v} field={RENTAL_FIELDS.endDate} record={r} editor="date" required>
+          {v}
+        </EditableRentalCell>
+      ),
+    },
+    {
+      title: '时长',
+      width: 80,
+      render: (_: any, r: any) => {
+        const d = dayjs(r.endDate).diff(dayjs(r.startDate), 'day') + 1;
+        return `${d}天`;
+      },
+    },
+    {
+      title: '日租金',
+      dataIndex: 'dailyRate',
+      width: 100,
+      render: (v: any, r: any) => (
+        <EditableRentalCell value={v} field={RENTAL_FIELDS.dailyRate} record={r} editor="money" min={0.01}>
+          {v ? `¥${v}` : '-'}
+        </EditableRentalCell>
+      ),
+    },
+    {
+      title: '总额',
+      dataIndex: 'totalAmount',
+      width: 100,
+      render: (v: any, r: any) => (
+        <EditableRentalCell value={v} field={RENTAL_FIELDS.totalAmount} record={r} editor="money" min={0.01}>
+          {v ? `¥${v}` : '-'}
+        </EditableRentalCell>
+      ),
+    },
+    {
+      title: '状态',
+      dataIndex: 'effectiveStatus',
+      width: 90,
+      render: (status: string) => {
+        const config: Record<string, { text: string; color: string }> = {
+          active: { text: '进行中', color: 'green' },
+          ended: { text: '已结束', color: 'default' },
+          cancelled: { text: '已取消', color: 'red' },
+        };
+        return <Tag color={config[status]?.color}>{config[status]?.text || status}</Tag>;
+      },
+    },
+    {
+      title: '合同',
+      width: 120,
+      dataIndex: 'contractPath',
+      render: (v: string, r: any) =>
+        v ? (
+          <Space>
+            <Tooltip title={r.contractOriginalName}>
+              <Button
+                size="small"
+                icon={<FileTextOutlined />}
+                onClick={() => onDownloadContract(r.id, r.contractOriginalName)}
+              >
+                下载
+              </Button>
+            </Tooltip>
+            {hasPermission('rental:edit') ? (
+              <Popconfirm title="移除合同文件？" onConfirm={() => onDeleteContract(r.id)}>
+                <Button size="small" danger icon={<StopOutlined />} aria-label="移除合同文件" />
+              </Popconfirm>
+            ) : null}
+          </Space>
+        ) : hasPermission('rental:edit') ? (
+          <Upload
+            accept="application/pdf"
+            showUploadList={false}
+            customRequest={async ({ file, onSuccess, onError }: any) => {
+              if (file.size > 10 * 1024 * 1024) {
+                message.error('文件不能超过 10MB');
+                onError?.(new Error('size'));
+                return;
+              }
+              const formData = new FormData();
+              formData.append('file', file);
+              try {
+                await onUploadContract(r.id, formData);
+                message.success('合同已上传');
+                onSuccess?.({});
+              } catch (e) {
+                onError?.(e as Error);
+              }
+            }}
+          >
+            <Button size="small" icon={<UploadOutlined />}>
+              上传PDF
+            </Button>
+          </Upload>
+        ) : (
+          '-'
+        ),
+    },
+    {
+      title: '操作',
+      width: 150,
+      render: (_: any, record: any) => (
+        <Space>
+          {record.effectiveStatus === 'active' && (
+            <>
+              <PermissionButton permission="rental:edit" size="small" onClick={() => onEdit(record)}>
+                编辑
+              </PermissionButton>
+              <Popconfirm title="确定取消该租赁？" onConfirm={() => onAction(record.id, 'cancel')}>
+                <PermissionButton
+                  permission="rental:edit"
+                  size="small"
+                  danger
+                  icon={<StopOutlined />}
+                >
+                  取消
+                </PermissionButton>
+              </Popconfirm>
+              {!dayjs(record.startDate).isAfter(dayjs(), 'day') && (
+                <Popconfirm title="确定今天结束该租赁？" onConfirm={() => onAction(record.id, 'end')}>
+                  <PermissionButton permission="rental:edit" size="small" icon={<CheckOutlined />}>
+                    结束
+                  </PermissionButton>
+                </Popconfirm>
+              )}
+            </>
+          )}
+          {record.effectiveStatus !== 'active' && (
+            <Popconfirm
+              title="确定归档该租赁订单？合同文件会保留。"
+              onConfirm={() => onArchive(record.id)}
+            >
+              <PermissionButton permission="rental:delete" size="small" danger>
+                归档
+              </PermissionButton>
+            </Popconfirm>
+          )}
+          {record.status === 'cancelled' && canPurgeRental ? (
+            <Button
+              size="small"
+              danger
+              type="link"
+              onClick={() => onPurge(record.id, record.lesseeOrganization?.name || `订单${record.id}`)}
+            >
+              删除
+            </Button>
+          ) : null}
+        </Space>
+      ),
+    },
+  ];
+
+  return (
+    <Table
+      columns={columns}
+      dataSource={data}
+      rowKey="id"
+      loading={loading}
+      locale={{ emptyText: <Empty description="暂无数据" /> }}
+      pagination={{
+        defaultPageSize: 15,
+        showSizeChanger: true,
+        pageSizeOptions: [15, 30, 50, 100],
+        showTotal: (total) => `共 ${total} 条`,
+      }}
+      scroll={{ x: 1200 }}
+    />
+  );
+};

apps/admin/src/pages/ClassroomRentals/index.tsx

@@ -1,7 +1,7 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import React, { useCallback, useMemo, useRef, useState } from 'react';
+import { useImmer } from 'use-immer';
 import {
-  Table,
-  Button,
+  App,
   Modal,
   Form,
   Select,
@@ -9,39 +9,32 @@ import {
   InputNumber,
   Input,
   Space,
-  Tag,
-  Popconfirm,
-  Upload,
-  Tooltip,
-  Empty,
 } from 'antd';
-import {
-  PlusOutlined,
-  UploadOutlined,
-  FileTextOutlined,
-  StopOutlined,
-  CheckOutlined,
-} from '@ant-design/icons';
+import { PlusOutlined } from '@ant-design/icons';
 import dayjs, { Dayjs } from 'dayjs';
 import api from '../../api';
 import { downloadBlob } from '../../utils/download';
 import PermissionButton from '../../components/PermissionButton';
-import EditableCell from '../../components/EditableCell';
 import { message } from '../../ui/app-message';
 import { usePermission } from '../../hooks/usePermission';
+import { useQuery } from '@tanstack/react-query';
+import { useApiMutation } from '../../hooks/useApiMutation';
+import { getErrorMessage } from '../../utils/error';
+import { validateResponse } from '../../utils/validate';
+import { classroomsSchema, organizationsSchema, rentalsSchema } from '../../api/schemas';
+import { RentalTable } from './RentalTable';
 
 interface UnavailableDatesResponse {
   dates: string[];
 }
+
 export const unavailableDatesCacheKey = (classroomId: number, date: Dayjs) =>
   `${classroomId}:${date.format('YYYY-MM')}`;
 
 const ClassroomRentalsPage: React.FC = () => {
+  const { modal } = App.useApp();
   const { hasPermission, hasAnyPermission } = usePermission();
-  const [data, setData] = useState<any[]>([]);
-  const [classrooms, setClassrooms] = useState<any[]>([]);
-  const [organizations, setOrganizations] = useState<any[]>([]);
-  const [loading, setLoading] = useState(false);
+  const canPurgeRental = hasPermission('rental:purge');
   const [modalOpen, setModalOpen] = useState(false);
   const [editing, setEditing] = useState<any>(null);
   const [form] = Form.useForm();
@@ -49,12 +42,110 @@ const ClassroomRentalsPage: React.FC = () => {
   const [filterStatus, setFilterStatus] = useState<string | undefined>();
   const [searchText, setSearchText] = useState('');
   const [saving, setSaving] = useState(false);
-  const [unavailableDates, setUnavailableDates] = useState<Set<string>>(new Set());
+  const [unavailableDates, setUnavailableDates] = useImmer<Set<string>>(new Set());
   const loadedUnavailableMonths = useRef<Set<string>>(new Set());
   const unavailableRequestVersion = useRef(0);
   const [unavailableDatesLoading, setUnavailableDatesLoading] = useState(false);
   const selectedClassroomId = Form.useWatch('classroomId', form);
 
+  const {
+    data = [],
+    isLoading,
+    isFetching,
+  } = useQuery<any[]>({
+    queryKey: ['classroom-rentals', filterMonth],
+    queryFn: async () => {
+      try {
+        const params: any = {};
+        if (filterMonth) params.month = filterMonth.format('YYYY-MM');
+        params.includeEnded = true;
+        return validateResponse<any[]>(
+          rentalsSchema,
+          await api.get('/classroom-rentals', { params }),
+        );
+      } catch (e: any) {
+        message.error(e?.message || '加载失败，请稍后重试');
+        return [];
+      }
+    },
+  });
+  const {
+    data: meta = { classrooms: [], organizations: [] },
+  } = useQuery<{ classrooms: any[]; organizations: any[] }>({
+    queryKey: ['classroom-rentals', 'meta'],
+    enabled: hasAnyPermission('rental:create', 'rental:edit'),
+    queryFn: async () => {
+      try {
+        const [cr, tn]: any = await Promise.all([
+          api.get('/classrooms'),
+          api.get('/organizations', { params: { scope: 'all' } }),
+        ]);
+        return {
+          classrooms: validateResponse<any[]>(classroomsSchema, cr),
+          organizations: validateResponse<any[]>(organizationsSchema, tn),
+        };
+      } catch (e: any) {
+        message.error(e?.message || '加载教室列表失败');
+        return { classrooms: [], organizations: [] };
+      }
+    },
+  });
+  const classrooms = meta.classrooms;
+  const organizations = meta.organizations;
+  const loading = isLoading || isFetching;
+
+  const saveMutation = useApiMutation(
+    async (payload: Record<string, unknown>) =>
+      editing
+        ? api.put(`/classroom-rentals/${editing.id}`, payload)
+        : api.post('/classroom-rentals', payload),
+    {
+      invalidate: [['classroom-rentals']],
+      onError: (error: unknown) => {
+        const e = error as {
+          conflicts?: Array<{ organizationName?: string; startDate?: string; endDate?: string }>;
+        };
+        if (e?.conflicts?.length) {
+          const list = e.conflicts
+            .map((c) => `${c.organizationName}(${c.startDate}~${c.endDate})`)
+            .join('、');
+          message.error(`时间段冲突：${list}`);
+        } else {
+          message.error(getErrorMessage(error, '操作失败'));
+        }
+      },
+    },
+  );
+  const saveCellMutation = useApiMutation(
+    async ({ record, field, value }: { record: any; field: string; value: unknown }) =>
+      api.put(`/classroom-rentals/${record.id}`, { [field]: value }),
+    { invalidate: [['classroom-rentals']] },
+  );
+  const deleteMutation = useApiMutation(
+    async (id: number) => api.delete(`/classroom-rentals/${id}`),
+    { invalidate: [['classroom-rentals']] },
+  );
+  const purgeMutation = useApiMutation(
+    async (id: number) => api.delete(`/classroom-rentals/${id}/permanent`),
+    { invalidate: [['classroom-rentals']] },
+  );
+  const actionMutation = useApiMutation(
+    async ({ id, action }: { id: number; action: 'cancel' | 'end' }) =>
+      api.put(`/classroom-rentals/${id}/${action}`),
+    { invalidate: [['classroom-rentals']] },
+  );
+  const deleteContractMutation = useApiMutation(
+    async (id: number) => api.delete(`/classroom-rentals/${id}/contract`),
+    { invalidate: [['classroom-rentals']] },
+  );
+  const uploadContractMutation = useApiMutation(
+    async ({ id, formData }: { id: number; formData: FormData }) =>
+      api.post(`/classroom-rentals/${id}/contract`, formData, {
+        headers: { 'Content-Type': 'multipart/form-data' },
+      }),
+    { invalidate: [['classroom-rentals']] },
+  );
+
   const filteredData = useMemo(() => {
     return data.filter((r: any) => {
       if (filterStatus && r.effectiveStatus !== filterStatus) return false;
@@ -66,40 +157,6 @@ const ClassroomRentalsPage: React.FC = () => {
     });
   }, [data, searchText, filterStatus]);
 
-  const fetchData = async () => {
-    setLoading(true);
-    try {
-      const params: any = {};
-      if (filterMonth) params.month = filterMonth.format('YYYY-MM');
-      params.includeEnded = true;
-      const res: any = await api.get('/classroom-rentals', { params });
-      setData(res);
-    } catch (e: any) {
-      message.error(e?.message || '加载失败，请稍后重试');
-    }
-    setLoading(false);
-  };
-
-  const fetchMeta = async () => {
-    try {
-      const [cr, tn]: any = await Promise.all([
-        api.get('/classrooms'),
-        api.get('/organizations', { params: { scope: 'all' } }),
-      ]);
-      setClassrooms(cr);
-      setOrganizations(tn);
-    } catch (e: any) {
-      message.error(e?.message || '加载教室列表失败');
-    }
-  };
-
-  useEffect(() => {
-    if (hasAnyPermission('rental:create', 'rental:edit')) fetchMeta();
-  }, [hasAnyPermission]);
-  useEffect(() => {
-    fetchData();
-  }, [filterMonth]);
-
   const resetUnavailableDates = () => {
     unavailableRequestVersion.current += 1;
     loadedUnavailableMonths.current.clear();
@@ -127,10 +184,8 @@ const ClassroomRentalsPage: React.FC = () => {
           },
         );
         if (requestVersion !== unavailableRequestVersion.current) return;
-        setUnavailableDates((current) => {
-          const next = new Set(current);
-          response.dates.forEach((item) => next.add(item));
-          return next;
+        setUnavailableDates((draft) => {
+          response.dates.forEach((item) => draft.add(item));
         });
       } catch (e: any) {
         loadedUnavailableMonths.current.delete(key);
@@ -190,75 +245,85 @@ const ClassroomRentalsPage: React.FC = () => {
       notes: values.notes,
     };
     try {
-      if (editing) {
-        await api.put(`/classroom-rentals/${editing.id}`, payload);
-        message.success('更新成功');
-      } else {
-        await api.post('/classroom-rentals', payload);
-        message.success('创建成功');
-      }
+      await saveMutation.mutateAsync(payload);
+      message.success(editing ? '更新成功' : '创建成功');
       setModalOpen(false);
       form.resetFields();
       setEditing(null);
-      fetchData();
-    } catch (e: any) {
-      if (e?.conflicts?.length) {
-        const list = e.conflicts
-          .map((c: any) => `${c.organizationName}(${c.startDate}~${c.endDate})`)
-          .join('、');
-        message.error(`时间段冲突：${list}`);
-      } else {
-        message.error(e?.message || '操作失败');
-      }
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     } finally {
       setSaving(false);
     }
   };
 
   const saveCell = async (record: any, field: string, value: unknown) => {
-    await api.put(`/classroom-rentals/${record.id}`, { [field]: value });
-    message.success('已保存');
-    await fetchData();
+    try {
+      await saveCellMutation.mutateAsync({ record, field, value });
+      message.success('已保存');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    }
   };
 
   const handleDelete = async (id: number) => {
     try {
-      await api.delete(`/classroom-rentals/${id}`);
+      await deleteMutation.mutateAsync(id);
       message.success('已归档');
-      fetchData();
-    } catch (e: any) {
-      message.error(e?.message || '归档失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     }
   };
 
+  const handlePurge = (id: number, name: string) => {
+    modal.confirm({
+      title: `永久删除租赁订单（${name}）？`,
+      content: '删除后不可恢复，排课与合同文件将被清除（存在考勤记录时将无法删除）。确定继续？',
+      okText: '永久删除',
+      okButtonProps: { danger: true },
+      cancelText: '取消',
+      onOk: async () => {
+        try {
+          await purgeMutation.mutateAsync(id);
+          message.success('已永久删除（不可恢复）');
+        } catch {
+          // 错误提示由 useApiMutation 统一处理
+        }
+      },
+    });
+  };
+
   const handleRentalAction = async (id: number, action: 'cancel' | 'end') => {
     try {
-      await api.put(`/classroom-rentals/${id}/${action}`);
+      await actionMutation.mutateAsync({ id, action });
       message.success(action === 'cancel' ? '租赁已取消' : '租赁已结束');
-      fetchData();
-    } catch (e: any) {
-      message.error(e?.message || '操作失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     }
   };
 
   const handleDownloadContract = async (id: number, filename?: string) => {
     try {
       await downloadBlob(`/classroom-rentals/${id}/contract`, filename || `contract-${id}.pdf`);
-    } catch {
+    } catch (e) {
+      console.error('下载合同失败', e);
       message.error('下载失败（可能文件已丢失）');
     }
   };
 
   const handleDeleteContract = async (id: number) => {
     try {
-      await api.delete(`/classroom-rentals/${id}/contract`);
+      await deleteContractMutation.mutateAsync(id);
       message.success('合同已移除');
-      fetchData();
-    } catch (e: any) {
-      message.error(e?.message || '移除失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     }
   };
 
+  const handleUploadContract = async (id: number, formData: FormData) => {
+    return uploadContractMutation.mutateAsync({ id, formData });
+  };
+
   const openEdit = (record: any) => {
     setEditing(record);
     resetUnavailableDates();
@@ -280,271 +345,6 @@ const ClassroomRentalsPage: React.FC = () => {
     );
   };
 
-  const columns = useMemo(
-    () => [
-      {
-        title: '教室',
-        width: 120,
-        dataIndex: 'classroom',
-        render: (c: any, r: any) => (
-          <EditableCell
-            value={r.classroomId}
-            editor="select"
-            options={classrooms
-              .filter((item) => item.status !== 'archived')
-              .map((item) => ({
-                value: item.id,
-                label: item.building ? `${item.building} · ${item.name}` : item.name,
-              }))}
-            permission="rental:edit"
-            disabled={r.effectiveStatus !== 'active'}
-            required
-            onSave={(next) => saveCell(r, 'classroomId', next)}
-          >
-            {c ? (
-              <span>
-                {c.building ? `${c.building} · ` : ''}
-                {c.name}
-              </span>
-            ) : (
-              '-'
-            )}
-          </EditableCell>
-        ),
-      },
-      {
-        title: '承租机构',
-        width: 100,
-        dataIndex: 'lesseeOrganization',
-        render: (t: any, r: any) => (
-          <EditableCell
-            value={r.lesseeOrganizationId}
-            editor="select"
-            options={organizations
-              .filter((item) => item.status !== 'archived')
-              .map((item) => ({ value: item.id, label: item.name }))}
-            permission="rental:edit"
-            disabled={r.effectiveStatus !== 'active'}
-            required
-            onSave={(next) => saveCell(r, 'lesseeOrganizationId', next)}
-          >
-            {t ? (
-              <Tag
-                color={t.color}
-                style={{ background: t.color, color: '#fff', borderColor: t.color }}
-              >
-                {t.name}
-              </Tag>
-            ) : (
-              '-'
-            )}
-          </EditableCell>
-        ),
-      },
-      {
-        title: '开始日期',
-        dataIndex: 'startDate',
-        width: 110,
-        render: (v: string, r: any) => (
-          <EditableCell
-            value={v}
-            editor="date"
-            permission="rental:edit"
-            disabled={r.effectiveStatus !== 'active'}
-            required
-            onSave={(next) => saveCell(r, 'startDate', next)}
-          >
-            {v}
-          </EditableCell>
-        ),
-      },
-      {
-        title: '结束日期',
-        dataIndex: 'endDate',
-        width: 110,
-        render: (v: string, r: any) => (
-          <EditableCell
-            value={v}
-            editor="date"
-            permission="rental:edit"
-            disabled={r.effectiveStatus !== 'active'}
-            required
-            onSave={(next) => saveCell(r, 'endDate', next)}
-          >
-            {v}
-          </EditableCell>
-        ),
-      },
-      {
-        title: '时长',
-        width: 80,
-        render: (_: any, r: any) => {
-          const d = dayjs(r.endDate).diff(dayjs(r.startDate), 'day') + 1;
-          return `${d}天`;
-        },
-      },
-      {
-        title: '日租金',
-        dataIndex: 'dailyRate',
-        width: 100,
-        render: (v: any, r: any) => (
-          <EditableCell
-            value={v}
-            editor="money"
-            min={0.01}
-            permission="rental:edit"
-            disabled={r.effectiveStatus !== 'active'}
-            onSave={(next) => saveCell(r, 'dailyRate', next)}
-          >
-            {v ? `¥${v}` : '-'}
-          </EditableCell>
-        ),
-      },
-      {
-        title: '总额',
-        dataIndex: 'totalAmount',
-        width: 100,
-        render: (v: any, r: any) => (
-          <EditableCell
-            value={v}
-            editor="money"
-            min={0.01}
-            permission="rental:edit"
-            disabled={r.effectiveStatus !== 'active'}
-            onSave={(next) => saveCell(r, 'totalAmount', next)}
-          >
-            {v ? `¥${v}` : '-'}
-          </EditableCell>
-        ),
-      },
-      {
-        title: '状态',
-        dataIndex: 'effectiveStatus',
-        width: 90,
-        render: (status: string) => {
-          const config: Record<string, { text: string; color: string }> = {
-            active: { text: '进行中', color: 'green' },
-            ended: { text: '已结束', color: 'default' },
-            cancelled: { text: '已取消', color: 'red' },
-          };
-          return <Tag color={config[status]?.color}>{config[status]?.text || status}</Tag>;
-        },
-      },
-      {
-        title: '合同',
-        width: 120,
-        dataIndex: 'contractPath',
-        render: (v: string, r: any) =>
-          v ? (
-            <Space>
-              <Tooltip title={r.contractOriginalName}>
-                <Button
-                  size="small"
-                  icon={<FileTextOutlined />}
-                  onClick={() => handleDownloadContract(r.id, r.contractOriginalName)}
-                >
-                  下载
-                </Button>
-              </Tooltip>
-              {hasPermission('rental:edit') ? (
-                <Popconfirm title="移除合同文件？" onConfirm={() => handleDeleteContract(r.id)}>
-                  <Button size="small" danger icon={<StopOutlined />} aria-label="移除合同文件" />
-                </Popconfirm>
-              ) : null}
-            </Space>
-          ) : hasPermission('rental:edit') ? (
-            <Upload
-              accept="application/pdf"
-              showUploadList={false}
-              customRequest={async ({ file, onSuccess, onError }: any) => {
-                if (file.size > 10 * 1024 * 1024) {
-                  message.error('文件不能超过 10MB');
-                  onError?.(new Error('size'));
-                  return;
-                }
-                const formData = new FormData();
-                formData.append('file', file);
-                try {
-                  await api.post(`/classroom-rentals/${r.id}/contract`, formData, {
-                    headers: { 'Content-Type': 'multipart/form-data' },
-                  });
-                  message.success('合同已上传');
-                  onSuccess?.({});
-                  fetchData();
-                } catch (e: any) {
-                  message.error(e?.message || '上传失败');
-                  onError?.(e);
-                }
-              }}
-            >
-              <Button size="small" icon={<UploadOutlined />}>
-                上传PDF
-              </Button>
-            </Upload>
-          ) : (
-            '-'
-          ),
-      },
-      {
-        title: '操作',
-        width: 150,
-        render: (_: any, record: any) => (
-          <Space>
-            {record.effectiveStatus === 'active' && (
-              <>
-                <PermissionButton
-                  permission="rental:edit"
-                  size="small"
-                  onClick={() => openEdit(record)}
-                >
-                  编辑
-                </PermissionButton>
-                <Popconfirm
-                  title="确定取消该租赁？"
-                  onConfirm={() => handleRentalAction(record.id, 'cancel')}
-                >
-                  <PermissionButton
-                    permission="rental:edit"
-                    size="small"
-                    danger
-                    icon={<StopOutlined />}
-                  >
-                    取消
-                  </PermissionButton>
-                </Popconfirm>
-                {!dayjs(record.startDate).isAfter(dayjs(), 'day') && (
-                  <Popconfirm
-                    title="确定今天结束该租赁？"
-                    onConfirm={() => handleRentalAction(record.id, 'end')}
-                  >
-                    <PermissionButton
-                      permission="rental:edit"
-                      size="small"
-                      icon={<CheckOutlined />}
-                    >
-                      结束
-                    </PermissionButton>
-                  </Popconfirm>
-                )}
-              </>
-            )}
-            {record.effectiveStatus !== 'active' && (
-              <Popconfirm
-                title="确定归档该租赁订单？合同文件会保留。"
-                onConfirm={() => handleDelete(record.id)}
-              >
-                <PermissionButton permission="rental:delete" size="small" danger>
-                  归档
-                </PermissionButton>
-              </Popconfirm>
-            )}
-          </Space>
-        ),
-      },
-    ],
-    [classrooms, organizations, hasPermission],
-  );
-
   return (
     <div>
       <div
@@ -601,19 +401,21 @@ const ClassroomRentalsPage: React.FC = () => {
           新增租赁
         </PermissionButton>
       </div>
-      <Table
-        columns={columns}
-        dataSource={filteredData}
-        rowKey="id"
+      <RentalTable
+        data={filteredData}
         loading={loading}
-        locale={{ emptyText: <Empty description="暂无数据" /> }}
-        pagination={{
-          defaultPageSize: 15,
-          showSizeChanger: true,
-          pageSizeOptions: [15, 30, 50, 100],
-          showTotal: (total) => `共 ${total} 条`,
-        }}
-        scroll={{ x: 1200 }}
+        classrooms={classrooms}
+        organizations={organizations}
+        canPurgeRental={canPurgeRental}
+        hasPermission={hasPermission}
+        onSaveCell={saveCell}
+        onEdit={openEdit}
+        onAction={handleRentalAction}
+        onArchive={handleDelete}
+        onPurge={handlePurge}
+        onDownloadContract={handleDownloadContract}
+        onDeleteContract={handleDeleteContract}
+        onUploadContract={handleUploadContract}
       />
       <Modal
         title={editing ? '编辑租赁' : '新增租赁'}

apps/admin/src/pages/ClassroomSchedule/index.tsx

@@ -1,4 +1,7 @@
-import React, { useEffect, useState, useMemo, useCallback } from 'react';
+import React, { useState, useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { validateResponse } from '../../utils/validate';
+import { classroomScheduleSchema } from '../../api/schemas';
 import {
   DatePicker,
   Card,
@@ -18,6 +21,7 @@ import dayjs, { Dayjs } from 'dayjs';
 import api from '../../api';
 import { downloadBlob } from '../../utils/download';
 import { message } from '../../ui/app-message';
+import { getErrorMessage } from '../../utils/error';
 
 interface ScheduleData {
   year: number;
@@ -34,27 +38,25 @@ interface ScheduleData {
 
 const ClassroomSchedulePage: React.FC = () => {
   const [month, setMonth] = useState<Dayjs>(dayjs());
-  const [loading, setLoading] = useState(false);
-  const [data, setData] = useState<ScheduleData | null>(null);
   const [detailModal, setDetailModal] = useState<any>(null);
 
-  const fetchData = useCallback(async () => {
-    setLoading(true);
-    try {
-      const res: any = await api.get('/classroom-rentals/schedule', {
-        params: { year: month.year(), month: month.month() + 1 },
-      });
-      setData(res);
-    } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '加载失败，请稍后重试');
-    }
-    setLoading(false);
-  }, [month]);
-
-  useEffect(() => {
-    fetchData();
-  }, [fetchData]);
+  const { data, isLoading, isFetching } = useQuery<ScheduleData | null>({
+    queryKey: ['classroom-rentals', 'schedule', month.year(), month.month()],
+    queryFn: async () => {
+      try {
+        return validateResponse<ScheduleData | null>(
+          classroomScheduleSchema,
+          await api.get('/classroom-rentals/schedule', {
+            params: { year: month.year(), month: month.month() + 1 },
+          }),
+        );
+      } catch (e: unknown) {
+        message.error(getErrorMessage(e, '加载失败，请稍后重试'));
+        return null;
+      }
+    },
+  });
+  const loading = isLoading || isFetching;
 
   // 按楼栋+楼层分组教室
   const groups = useMemo(() => {
@@ -88,8 +90,7 @@ const ClassroomSchedulePage: React.FC = () => {
       const res: any = await api.get(`/classroom-rentals/${rentalId}`);
       setDetailModal(res);
     } catch (e: unknown) {
-      const err = e as { message?: string };
-      message.error(err?.message || '加载详情失败');
+      message.error(getErrorMessage(e, '加载详情失败'));
     }
   };
 
@@ -368,12 +369,12 @@ const ClassroomSchedulePage: React.FC = () => {
               {detailModal.startDate} ~ {detailModal.endDate}（
               {dayjs(detailModal.endDate).diff(dayjs(detailModal.startDate), 'day') + 1}天）
             </div>
-            {detailModal.dailyRate && (
+            {detailModal.dailyRate != null && (
               <div>
                 <strong>日租金：</strong>¥{detailModal.dailyRate}
               </div>
             )}
-            {detailModal.totalAmount && (
+            {detailModal.totalAmount != null && (
               <div>
                 <strong>合同总额：</strong>¥{detailModal.totalAmount}
               </div>

apps/admin/src/pages/Classrooms/index.tsx

@@ -1,5 +1,10 @@
-import React, { useEffect, useState, useMemo } from 'react';
+import React, { useState, useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { useApiMutation } from '../../hooks/useApiMutation';
+import { validateResponse } from '../../utils/validate';
+import { classroomsSchema } from '../../api/schemas';
 import {
+  App,
   Table,
   Button,
   Modal,
@@ -26,6 +31,7 @@ import PermissionButton from '../../components/PermissionButton';
 import EditableCell from '../../components/EditableCell';
 import { message } from '../../ui/app-message';
 import { usePermission } from '../../hooks/usePermission';
+import { useUserStore } from '../../store/user/userStore';
 
 const statusMap: Record<string, { text: string; color: string }> = {
   available: { text: '可用', color: 'green' },
@@ -49,9 +55,8 @@ const typeColor: Record<string, string> = {
 };
 
 const ClassroomsPage: React.FC = () => {
+  const { modal } = App.useApp();
   const { hasPermission } = usePermission();
-  const [data, setData] = useState<any[]>([]);
-  const [loading, setLoading] = useState(false);
   const [modalOpen, setModalOpen] = useState(false);
   const [editing, setEditing] = useState<any>(null);
   const [showArchived, setShowArchived] = useState(false);
@@ -61,6 +66,56 @@ const ClassroomsPage: React.FC = () => {
 
   const [saving, setSaving] = useState(false);
 
+  const {
+    data = [],
+    isLoading,
+    isFetching,
+  } = useQuery<any[]>({
+    queryKey: ['classrooms', showArchived],
+    queryFn: async () => {
+      try {
+        return validateResponse<any[]>(
+          classroomsSchema,
+          await api.get('/classrooms', { params: { includeArchived: showArchived } }),
+        );
+      } catch (e: any) {
+        message.error(e?.message || '加载失败，请稍后重试');
+        return [];
+      }
+    },
+  });
+  const loading = isLoading || isFetching;
+
+  const saveMutation = useApiMutation(
+    async (values: Record<string, unknown>) =>
+      editing ? api.put(`/classrooms/${editing.id}`, values) : api.post('/classrooms', values),
+    { invalidate: [['classrooms']] },
+  );
+  const saveCellMutation = useApiMutation(
+    async ({ record, field, value }: { record: any; field: string; value: unknown }) =>
+      api.put(`/classrooms/${record.id}`, { [field]: value }),
+    { invalidate: [['classrooms']] },
+  );
+  const archiveMutation = useApiMutation(
+    async (id: number) => api.delete(`/classrooms/${id}`),
+    { invalidate: [['classrooms']] },
+  );
+  const restoreMutation = useApiMutation(
+    async (id: number) => api.put(`/classrooms/${id}/restore`),
+    { invalidate: [['classrooms']] },
+  );
+  const purgeMutation = useApiMutation(
+    async (id: number) => api.delete(`/classrooms/${id}/permanent`),
+    { invalidate: [['classrooms']] },
+  );
+  const importMutation = useApiMutation(
+    async (formData: FormData) =>
+      api.post('/classrooms/import', formData, {
+        headers: { 'Content-Type': 'multipart/form-data' },
+      }),
+    { invalidate: [['classrooms']] },
+  );
+
   const filteredData = useMemo(() => {
     let result = data;
     if (searchText) {
@@ -76,74 +131,72 @@ const ClassroomsPage: React.FC = () => {
     return result;
   }, [data, searchText, filterStatus]);
 
-  const fetchData = async () => {
-    setLoading(true);
-    try {
-      const res: any = await api.get('/classrooms', { params: { includeArchived: showArchived } });
-      setData(res);
-    } catch (e: any) {
-      message.error(e?.message || '加载失败，请稍后重试');
-    }
-    setLoading(false);
-  };
-
-  useEffect(() => {
-    fetchData();
-  }, [showArchived]);
-
   const handleSave = async () => {
     const values = await form.validateFields();
     setSaving(true);
     try {
-      if (editing) {
-        await api.put(`/classrooms/${editing.id}`, values);
-        message.success('更新成功');
-      } else {
-        await api.post('/classrooms', values);
-        message.success('创建成功');
-      }
+      await saveMutation.mutateAsync(values);
+      message.success(editing ? '更新成功' : '创建成功');
       setModalOpen(false);
       form.resetFields();
       setEditing(null);
-      fetchData();
-    } catch (e: any) {
-      message.error(e?.message || '操作失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     } finally {
       setSaving(false);
     }
   };
 
   const saveCell = async (record: any, field: string, value: unknown) => {
-    await api.put(`/classrooms/${record.id}`, { [field]: value });
-    message.success('已保存');
-    await fetchData();
+    try {
+      await saveCellMutation.mutateAsync({ record, field, value });
+      message.success('已保存');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
+    }
   };
 
   const handleArchive = async (id: number) => {
     try {
-      await api.delete(`/classrooms/${id}`);
+      await archiveMutation.mutateAsync(id);
       message.success('已归档');
-      fetchData();
-    } catch (e: any) {
-      message.error(e?.message || '归档失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     }
   };
 
   const handleRestore = async (id: number) => {
     try {
-      await api.put(`/classrooms/${id}/restore`);
+      await restoreMutation.mutateAsync(id);
       message.success('已恢复');
-      fetchData();
-    } catch (e: any) {
-      message.error(e?.message || '恢复失败');
+    } catch {
+      // 错误提示由 useApiMutation 统一处理
     }
   };
 
+  const handlePurge = (id: number, name: string) => {
+    modal.confirm({
+      title: `永久删除教室「${name}」？`,
+      content: '删除后不可恢复，该教室及其排课、租赁、考勤机关联将被清除（存在关联数据时将无法删除）。确定继续？',
+      okText: '永久删除',
+      okButtonProps: { danger: true },
+      cancelText: '取消',
+      onOk: async () => {
+        try {
+          await purgeMutation.mutateAsync(id);
+          message.success('已永久删除（不可恢复）');
+        } catch {
+          // 错误提示由 useApiMutation 统一处理
+        }
+      },
+    });
+  };
+
   const handleDownloadTemplate = () => {
     const baseURL = import.meta.env.PROD
       ? '/api'
       : `http://localhost:${import.meta.env.VITE_API_PORT || 3002}/api`;
-    const token = localStorage.getItem('token');
+    const token = useUserStore.getState().token;
     fetch(`${baseURL}/classrooms/template`, { headers: { Authorization: `Bearer ${token}` } })
       .then((res) => res.blob())
       .then((blob) => {
@@ -176,6 +229,7 @@ const ClassroomsPage: React.FC = () => {
           </EditableCell>
         ),
       },
+
       {
         title: '楼栋',
         dataIndex: 'building',
@@ -191,6 +245,7 @@ const ClassroomsPage: React.FC = () => {
           </EditableCell>
         ),
       },
+
       {
         title: '楼层',
         dataIndex: 'floor',
@@ -207,6 +262,7 @@ const ClassroomsPage: React.FC = () => {
           </EditableCell>
         ),
       },
+
       {
         title: '类型',
         width: 90,
@@ -224,6 +280,7 @@ const ClassroomsPage: React.FC = () => {
           </EditableCell>
         ),
       },
+
       {
         title: '容量',
         dataIndex: 'capacity',
@@ -241,6 +298,7 @@ const ClassroomsPage: React.FC = () => {
           </EditableCell>
         ),
       },
+
       {
         title: '状态',
         width: 100,
@@ -277,22 +335,35 @@ const ClassroomsPage: React.FC = () => {
           );
         },
       },
+
       {
         title: '操作',
         width: 180,
         render: (_: any, record: any) => (
           <Space>
             {record.status === 'archived' ? (
-              <Popconfirm title="确定恢复此教室？" onConfirm={() => handleRestore(record.id)}>
-                <PermissionButton
-                  permission="classroom:edit"
-                  size="small"
-                  icon={<UndoOutlined />}
-                  type="link"
-                >
-                  恢复
-                </PermissionButton>
-              </Popconfirm>
+              <>
+                <Popconfirm title="确定恢复此教室？" onConfirm={() => handleRestore(record.id)}>
+                  <PermissionButton
+                    permission="classroom:edit"
+                    size="small"
+                    icon={<UndoOutlined />}
+                    type="link"
+                  >
+                    恢复
+                  </PermissionButton>
+                </Popconfirm>
+                {hasPermission('classroom:purge') ? (
+                  <Button
+                    size="small"
+                    danger
+                    type="link"
+                    onClick={() => handlePurge(record.id, record.name)}
+                  >
+                    删除
+                  </Button>
+                ) : null}
+              </>
             ) : (
               <>
                 <PermissionButton
@@ -326,7 +397,7 @@ const ClassroomsPage: React.FC = () => {
         ),
       },
     ],
-    [],
+    [handlePurge, hasPermission],
   );
 
   return (
@@ -389,7 +460,7 @@ const ClassroomsPage: React.FC = () => {
             icon={<DownloadOutlined />}
             onClick={() => {
               const baseURL = '/api';
-              const token = localStorage.getItem('token');
+              const token = useUserStore.getState().token;
               fetch(`${baseURL}/classrooms/export`, {
                 headers: { Authorization: `Bearer ${token}` },
               })
@@ -412,15 +483,11 @@ const ClassroomsPage: React.FC = () => {
                 const formData = new FormData();
                 formData.append('file', file);
                 try {
-                  const res: any = await api.post('/classrooms/import', formData, {
-                    headers: { 'Content-Type': 'multipart/form-data' },
-                  });
+                  const res: any = await importMutation.mutateAsync(formData);
                   message.success(res.message);
                   onSuccess?.(res);
-                  fetchData();
-                } catch (e: any) {
-                  message.error(e?.message || '导入失败');
-                  onError?.(e);
+                } catch (e) {
+                  onError?.(e as Error);
                 }
               }}
             >

apps/admin/src/pages/Dashboard/Dashboard.types.ts

@@ -0,0 +1,128 @@
+import React from 'react';
+
+export const COLORS = [
+  '#007AFF',
+  '#34C759',
+  '#FF9500',
+  '#FF3B30',
+  '#5AC8FA',
+  '#AF52DE',
+  '#FF2D55',
+  '#FFCC00',
+];
+
+export interface BillStatRow {
+  status: string;
+  count: string;
+  total: string;
+}
+export interface ClassAttendanceRank {
+  className: string;
+  present: number;
+  total: number;
+  rate: number;
+}
+export interface ClassroomOccupancy {
+  name: string;
+  building: string;
+  capacity: number;
+  scheduleDays: number;
+  rentalCount: number;
+  occupancy: number;
+}
+export interface ClassroomUtilStats {
+  totalClassrooms: number;
+  inUseCount: number;
+  utilizationRate: string;
+  scheduleCount: number;
+  rentalCount: number;
+}
+export interface AttendanceTrendRow {
+  date: string;
+  rate: string;
+}
+export interface IncomeTrendRow {
+  month: string;
+  amount: number;
+}
+export interface OccupancyByBuildingRow {
+  building: string;
+  count: string;
+}
+export interface ExpenseByTypeRow {
+  type: string;
+  total: string;
+}
+export interface GanttOccupancy {
+  studentName: string;
+  studentId?: string;
+  checkInDate: string;
+  checkOutDate: string | null;
+  billingStartDate?: string;
+  billingEndDate?: string;
+}
+export interface GanttRoom {
+  roomNumber: string;
+  occupancies: GanttOccupancy[];
+}
+
+export interface DashboardStats {
+  totalRooms: number;
+  totalStudents: number;
+  occupiedBeds: number;
+  totalCapacity: number;
+  occupancyRate: string;
+  billStats: BillStatRow[];
+  classroomCount: number;
+  classroomOccupancyRate: string;
+  todayAttendanceRate?: string;
+  monthlyIncome: number;
+  classCount: number;
+  teacherCount: number;
+  pendingDeposits: number;
+  activeRentals: number;
+  todayPresent: number;
+  occupancyByBuilding: OccupancyByBuildingRow[];
+  attendanceByStatus: Record<string, number>;
+  expenseByType: ExpenseByTypeRow[];
+  attendanceTrend: AttendanceTrendRow[];
+  incomeTrend: IncomeTrendRow[];
+}
+
+export const attendanceLabelMap: Record<string, string> = {
+  present: '出勤',
+  absent: '缺勤',
+  late: '迟到',
+  early: '早退',
+  leave: '请假',
+};
+
+export const SECTION_ROW_STYLE: React.CSSProperties = { marginBottom: 24 };
+export const MARGIN_BOTTOM_16_STYLE: React.CSSProperties = { marginBottom: 16 };
+
+export const TODO_CARD_BASE: React.CSSProperties = {
+  cursor: 'pointer',
+  transition: 'box-shadow 0.2s, transform 0.2s',
+  borderRadius: 8,
+  height: '100%',
+};
+export const TODO_CARD_WARN: React.CSSProperties = {
+  ...TODO_CARD_BASE,
+  borderLeft: '4px solid #FF9500',
+  background: '#fff7e6',
+};
+export const TODO_CARD_DANGER: React.CSSProperties = {
+  ...TODO_CARD_BASE,
+  borderLeft: '4px solid #FF3B30',
+  background: '#fff1f0',
+};
+export const TODO_CARD_OK: React.CSSProperties = {
+  ...TODO_CARD_BASE,
+  borderLeft: '4px solid #34C759',
+  background: '#f0fff4',
+};
+export const TODO_CARD_DRAFT: React.CSSProperties = {
+  ...TODO_CARD_BASE,
+  borderLeft: '4px solid #AF52DE',
+  background: '#f9f0ff',
+};

apps/admin/src/pages/Dashboard/DashboardCharts.ts

@@ -0,0 +1,262 @@
+import type { EChartsOption } from '../../components/ECharts';
+import {
+  attendanceLabelMap,
+  COLORS,
+  type AttendanceTrendRow,
+  type ClassAttendanceRank,
+  type ClassroomOccupancy,
+  type DashboardStats,
+  type ExpenseByTypeRow,
+  type GanttRoom,
+  type IncomeTrendRow,
+} from './Dashboard.types';
+
+export function buildAttendanceRingOption(stats: DashboardStats | null): EChartsOption {
+  return {
+    tooltip: { trigger: 'item' },
+    legend: { bottom: 0 },
+    series: [
+      {
+        type: 'pie',
+        radius: ['40%', '70%'],
+        center: ['50%', '45%'],
+        data: Object.entries(stats?.attendanceByStatus ?? {}).map(([status, count]) => ({
+          name: attendanceLabelMap[status] ?? status,
+          value: count,
+        })),
+        itemStyle: { borderRadius: 4, borderColor: '#fff', borderWidth: 2 },
+      },
+    ],
+    color: COLORS,
+  };
+}
+
+export function buildRoomRankingBarOption(
+  roomRanking: Array<{ roomNumber: string; total: string }>,
+): EChartsOption {
+  return {
+    tooltip: {},
+    grid: { left: 80, right: 20, bottom: 30, top: 10 },
+    xAxis: { type: 'value' },
+    yAxis: {
+      type: 'category',
+      data: roomRanking.map((r) => r.roomNumber).reverse(),
+      inverse: false,
+    },
+    series: [
+      {
+        type: 'bar',
+        data: roomRanking.map((r) => Number(r.total)).reverse(),
+        itemStyle: { color: '#007AFF', borderRadius: [0, 4, 4, 0] },
+      },
+    ],
+  };
+}
+
+export function buildClassRankingOption(
+  rows: ClassAttendanceRank[],
+  color: string,
+): EChartsOption {
+  return {
+    tooltip: {
+      trigger: 'axis',
+      axisPointer: { type: 'shadow' },
+      valueFormatter: (v: number) => `${v}%`,
+    },
+    grid: { left: 80, right: 30, bottom: 30, top: 10 },
+    xAxis: { type: 'value', max: 100, axisLabel: { formatter: '{value}%' } },
+    yAxis: {
+      type: 'category',
+      data: rows.map((r) => r.className),
+      inverse: true,
+    },
+    series: [
+      {
+        type: 'bar',
+        data: rows.map((r) => r.rate),
+        itemStyle: { color, borderRadius: [0, 4, 4, 0] },
+        label: { show: true, position: 'right', formatter: '{c}%' },
+      },
+    ],
+  };
+}
+
+export function buildAttendanceLineOption(rows: AttendanceTrendRow[]): EChartsOption {
+  return {
+    tooltip: { trigger: 'axis' },
+    grid: { left: 50, right: 20, bottom: 30, top: 10 },
+    xAxis: {
+      type: 'category',
+      data: rows.map((d) => d.date),
+      axisLabel: { rotate: 45, fontSize: 10 },
+    },
+    yAxis: { type: 'value', min: 0, max: 100, axisLabel: { formatter: '{value}%' } },
+    series: [
+      {
+        type: 'line',
+        data: rows.map((d) => parseFloat(d.rate) || 0),
+        smooth: true,
+        lineStyle: { color: '#007AFF', width: 2 },
+        itemStyle: { color: '#007AFF' },
+        areaStyle: { color: 'rgba(0,122,255,0.1)' },
+      },
+    ],
+  };
+}
+
+export function buildIncomeLineOption(rows: IncomeTrendRow[]): EChartsOption {
+  return {
+    tooltip: { trigger: 'axis', valueFormatter: (v: number) => `¥${v.toLocaleString()}` },
+    grid: { left: 70, right: 20, bottom: 30, top: 10 },
+    xAxis: {
+      type: 'category',
+      data: rows.map((d) => d.month),
+    },
+    yAxis: {
+      type: 'value',
+      axisLabel: { formatter: (v: number) => `¥${(v / 10000).toFixed(0)}万` },
+    },
+    series: [
+      {
+        type: 'line',
+        data: rows.map((d) => d.amount),
+        smooth: true,
+        lineStyle: { color: '#34C759', width: 2 },
+        itemStyle: { color: '#34C759' },
+        areaStyle: { color: 'rgba(52,199,89,0.1)' },
+      },
+    ],
+  };
+}
+
+export function buildExpensePieOption(
+  rows: ExpenseByTypeRow[],
+  expenseTypeMap: Record<string, string>,
+): EChartsOption {
+  return {
+    tooltip: { trigger: 'item' },
+    legend: { bottom: 0 },
+    color: COLORS,
+    series: [
+      {
+        type: 'pie',
+        radius: ['40%', '70%'],
+        center: ['50%', '45%'],
+        data: rows.map((e) => ({
+          name: expenseTypeMap[e.type] ?? e.type,
+          value: Number(e.total),
+        })),
+      },
+    ],
+  };
+}
+
+export function buildClassroomHeatmapOption(
+  classroomOccupancy: ClassroomOccupancy[],
+): EChartsOption {
+  return {
+    tooltip: {
+      formatter: (p: {
+        name: string;
+        data: { scheduleDays: number; rentalCount: number; occupancy: number };
+      }) =>
+        `${p.name}<br/>排课: ${p.data.scheduleDays}天 租赁: ${p.data.rentalCount}个 占用率: ${(p.data.occupancy * 100).toFixed(0)}%`,
+    },
+    grid: { left: 100, right: 20, bottom: 30, top: 10 },
+    xAxis: { type: 'value', max: 1 },
+    yAxis: {
+      type: 'category',
+      data: classroomOccupancy.map((r) => r.name),
+      inverse: true,
+    },
+    visualMap: {
+      min: 0,
+      max: 1,
+      orient: 'horizontal',
+      left: 'center',
+      bottom: 0,
+      inRange: {
+        color: ['#e6f4ff', '#91caff', '#40a9ff', '#0050b3', '#002c8c'],
+      },
+    },
+    series: [
+      {
+        type: 'bar',
+        data: classroomOccupancy.map((r) => ({
+          name: r.name,
+          value: r.occupancy,
+          scheduleDays: r.scheduleDays,
+          rentalCount: r.rentalCount,
+          occupancy: r.occupancy,
+        })),
+        itemStyle: { borderRadius: [0, 4, 4, 0] },
+        label: {
+          show: true,
+          position: 'right',
+          formatter: (p: { data: { occupancy: number } }) =>
+            `${(p.data.occupancy * 100).toFixed(0)}%`,
+        },
+      },
+    ],
+  };
+}
+
+export function buildGanttOption(ganttData: GanttRoom[]): EChartsOption {
+  return {
+    tooltip: {
+      formatter: (p: { data: { name: string; value: [string, string, string, boolean] } }) =>
+        `${p.data.name}<br/>入住: ${p.data.value[1]}<br/>退宿: ${p.data.value[2]}`,
+    },
+    grid: { left: 100, right: 30, bottom: 40, top: 20 },
+    xAxis: { type: 'time' },
+    yAxis: { type: 'category', data: ganttData.map((r) => r.roomNumber), inverse: true },
+    dataZoom: [
+      { type: 'slider', xAxisIndex: 0, bottom: 10, height: 20 },
+      { type: 'inside', xAxisIndex: 0 },
+    ],
+    series: [
+      {
+        type: 'custom',
+        renderItem: (
+          _params: unknown,
+          api: {
+            value: (i: number) => string | boolean;
+            coord: (p: [string | number, string | number]) => [number, number];
+            size: (p: [number, number]) => [number, number];
+          },
+        ) => {
+          const cat = String(api.value(0));
+          const startDate = String(api.value(1));
+          const endDate = String(api.value(2));
+          const isActive = Boolean(api.value(3));
+          const start = api.coord([startDate, cat]);
+          const end = api.coord([endDate, cat]);
+          const height = api.size([0, 1])[1] * 0.6;
+          const rectShape = {
+            x: start[0],
+            y: start[1] - height / 2,
+            width: Math.max(end[0] - start[0], 2),
+            height,
+          };
+          return {
+            type: 'rect' as const,
+            shape: rectShape,
+            style: { fill: isActive ? '#34C759' : '#FF9500', stroke: '#fff', lineWidth: 1 },
+          };
+        },
+        encode: { x: [1, 2], y: 0 },
+        data: ganttData.flatMap((r) =>
+          (r.occupancies || []).map((o) => ({
+            name: o.studentName,
+            value: [
+              r.roomNumber,
+              o.checkInDate,
+              o.checkOutDate || new Date().toISOString().slice(0, 10),
+              !o.checkOutDate,
+            ] as [string, string, string, boolean],
+          })),
+        ),
+      },
+    ],
+  };
+}

apps/admin/src/pages/Dashboard/DashboardLazyCards.tsx

@@ -0,0 +1,85 @@
+import React, { type CSSProperties } from 'react';
+import { Card, Col, Row } from 'antd';
+import { useIntersectionObserver } from 'usehooks-ts';
+import ReactECharts from '../../components/ECharts';
+import type { ClassroomOccupancy, GanttRoom } from './Dashboard.types';
+import { buildClassroomHeatmapOption, buildGanttOption } from './DashboardCharts';
+
+const useInViewport = (rootMargin = '200px') => {
+  const { ref, isIntersecting } = useIntersectionObserver({
+    rootMargin,
+    freezeOnceVisible: true,
+  });
+  return { ref, inView: isIntersecting };
+};
+
+const LazySection: React.FC<{
+  title: string;
+  vp: { ref: (node?: Element | null) => void; inView: boolean };
+  minHeight: number;
+  style?: CSSProperties;
+  children: React.ReactNode;
+}> = ({ title, vp, minHeight, style, children }) => {
+  return (
+    <div ref={vp.ref} style={style}>
+      {vp.inView ? (
+        <Row gutter={[16, 16]}>
+          <Col xs={24}>
+            <Card title={title}>{children}</Card>
+          </Col>
+        </Row>
+      ) : (
+        <Card title={title} style={{ minHeight }}>
+          <div style={{ textAlign: 'center', padding: 40, color: '#999' }}>加载中…</div>
+        </Card>
+      )}
+    </div>
+  );
+};
+
+export const ClassroomHeatmapCard: React.FC<{
+  data: ClassroomOccupancy[];
+  isMobile: boolean;
+}> = ({ data, isMobile }) => {
+  const vp = useInViewport('200px');
+  return (
+    <LazySection
+      title="教室占用热力图"
+      vp={vp}
+      minHeight={isMobile ? 340 : 440}
+      style={{ marginBottom: 24 }}
+    >
+      {data.length > 0 ? (
+        <ReactECharts
+          option={buildClassroomHeatmapOption(data)}
+          style={{ width: '100%', height: isMobile ? 300 : 400 }}
+        />
+      ) : (
+        <div style={{ textAlign: 'center', padding: 40, color: '#999' }}>暂无教室数据</div>
+      )}
+    </LazySection>
+  );
+};
+
+export const GanttCard: React.FC<{ data: GanttRoom[]; isMobile: boolean }> = ({
+  data,
+  isMobile,
+}) => {
+  const vp = useInViewport('200px');
+  return (
+    <LazySection
+      title="入住时间线（甘特图）"
+      vp={vp}
+      minHeight={isMobile ? 340 : 490}
+    >
+      {data.length > 0 ? (
+        <ReactECharts
+          option={buildGanttOption(data)}
+          style={{ width: '100%', height: isMobile ? 300 : 450 }}
+        />
+      ) : (
+        <div style={{ textAlign: 'center', padding: 40, color: '#999' }}>暂无入住数据</div>
+      )}
+    </LazySection>
+  );
+};

apps/admin/src/pages/Dashboard/DashboardTodoCards.tsx

@@ -0,0 +1,124 @@
+import React from 'react';
+import { Card, Col, Row } from 'antd';
+import {
+  ArrowRightOutlined,
+  BankOutlined,
+  DollarOutlined,
+  ExclamationCircleOutlined,
+} from '@ant-design/icons';
+import { useNavigate } from 'react-router';
+import { MARGIN_BOTTOM_16_STYLE, TODO_CARD_DANGER, TODO_CARD_DRAFT, TODO_CARD_OK, TODO_CARD_WARN } from './Dashboard.types';
+
+export const DashboardTodoCards: React.FC<{
+  absentCount: number;
+  draftCount: number;
+  draftTotal: number;
+  pendingDeposits: number;
+}> = ({ absentCount, draftCount, draftTotal, pendingDeposits }) => {
+  const navigate = useNavigate();
+  return (
+    <Card title="待办与异常" style={MARGIN_BOTTOM_16_STYLE}>
+      <Row gutter={[16, 16]}>
+        <Col xs={24} sm={8}>
+          <Card
+            style={absentCount > 0 ? TODO_CARD_WARN : TODO_CARD_OK}
+            styles={{ body: { padding: 16 } }}
+            onClick={() => navigate('/attendance')}
+          >
+            <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+              <ExclamationCircleOutlined
+                style={{ fontSize: 28, color: absentCount > 0 ? '#FF9500' : '#999' }}
+              />
+              <ArrowRightOutlined style={{ color: '#bbb' }} />
+            </div>
+            <div style={{ marginTop: 8 }}>
+              <div
+                style={{
+                  fontSize: 24,
+                  fontWeight: 700,
+                  color: absentCount > 0 ? '#FF9500' : '#999',
+                }}
+              >
+                {absentCount}
+              </div>
+              <div style={{ fontSize: 13, color: '#666', marginTop: 2 }}>今日缺勤人数</div>
+              {absentCount > 0 ? (
+                <div style={{ fontSize: 12, color: '#FF9500', marginTop: 4 }}>需要关注</div>
+              ) : (
+                <div style={{ fontSize: 12, color: '#34C759', marginTop: 4 }}>全员到齐</div>
+              )}
+            </div>
+          </Card>
+        </Col>
+
+        <Col xs={24} sm={8}>
+          <Card
+            style={draftCount > 0 ? TODO_CARD_DRAFT : TODO_CARD_OK}
+            styles={{ body: { padding: 16 } }}
+            onClick={() => navigate('/bills')}
+          >
+            <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+              <DollarOutlined
+                style={{ fontSize: 28, color: draftCount > 0 ? '#AF52DE' : '#999' }}
+              />
+              <ArrowRightOutlined style={{ color: '#bbb' }} />
+            </div>
+            <div style={{ marginTop: 8 }}>
+              <div
+                style={{
+                  fontSize: 24,
+                  fontWeight: 700,
+                  color: draftCount > 0 ? '#AF52DE' : '#999',
+                }}
+              >
+                {draftCount}
+              </div>
+              <div style={{ fontSize: 13, color: '#666', marginTop: 2 }}>待处理账单</div>
+              <div
+                style={{ fontSize: 12, color: draftCount > 0 ? '#AF52DE' : '#999', marginTop: 4 }}
+              >
+                {draftCount > 0 ? `合计 ¥${draftTotal.toLocaleString()}` : '暂无待处理'}
+              </div>
+            </div>
+          </Card>
+        </Col>
+
+        <Col xs={24} sm={8}>
+          <Card
+            style={pendingDeposits > 0 ? TODO_CARD_DANGER : TODO_CARD_OK}
+            styles={{ body: { padding: 16 } }}
+            onClick={() => navigate('/deposits')}
+          >
+            <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+              <BankOutlined
+                style={{ fontSize: 28, color: pendingDeposits > 0 ? '#FF3B30' : '#999' }}
+              />
+              <ArrowRightOutlined style={{ color: '#bbb' }} />
+            </div>
+            <div style={{ marginTop: 8 }}>
+              <div
+                style={{
+                  fontSize: 24,
+                  fontWeight: 700,
+                  color: pendingDeposits > 0 ? '#FF3B30' : '#999',
+                }}
+              >
+                ¥{pendingDeposits.toLocaleString()}
+              </div>
+              <div style={{ fontSize: 13, color: '#666', marginTop: 2 }}>待退押金</div>
+              <div
+                style={{
+                  fontSize: 12,
+                  color: pendingDeposits > 0 ? '#FF3B30' : '#999',
+                  marginTop: 4,
+                }}
+              >
+                {pendingDeposits > 0 ? '需要处理' : '暂无待退'}
+              </div>
+            </div>
+          </Card>
+        </Col>
+      </Row>
+    </Card>
+  );
+};

apps/admin/src/pages/Dashboard/index.tsx

@@ -1,4 +1,15 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import React, { useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { validateResponse } from '../../utils/validate';
+import {
+  classAttendanceRankingSchema,
+  classroomOccupanciesSchema,
+  classroomUtilStatsSchema,
+  dashboardStatsSchema,
+  expenseTypesSchema,
+  ganttRoomsSchema,
+  roomRankingSchema,
+} from '../../api/schemas';
 import { Row, Col, Card, Statistic, DatePicker, Spin, Grid, Collapse } from 'antd';
 import {
   TeamOutlined,
@@ -11,460 +22,142 @@ import {
   FileProtectOutlined,
   ReadOutlined,
   CalendarOutlined,
-  ArrowRightOutlined,
-  ExclamationCircleOutlined,
-  DollarOutlined,
 } from '@ant-design/icons';
-import ReactECharts, { type EChartsOption } from '../../components/ECharts';
+import ReactECharts from '../../components/ECharts';
 import dayjs from 'dayjs';
-import { useNavigate } from 'react-router-dom';
 import api from '../../api';
 import { message } from '../../ui/app-message';
+import {
+  buildAttendanceLineOption,
+  buildAttendanceRingOption,
+  buildClassRankingOption,
+  buildExpensePieOption,
+  buildIncomeLineOption,
+  buildRoomRankingBarOption,
+} from './DashboardCharts';
+import { ClassroomHeatmapCard, GanttCard } from './DashboardLazyCards';
+import {
+  MARGIN_BOTTOM_16_STYLE,
+  SECTION_ROW_STYLE,
+  type ClassAttendanceRank,
+  type ClassroomOccupancy,
+  type ClassroomUtilStats,
+  type DashboardStats,
+  type GanttRoom,
+} from './Dashboard.types';
+import { DashboardTodoCards } from './DashboardTodoCards';
 
 const { RangePicker } = DatePicker;
 
-const COLORS = [
-  '#007AFF',
-  '#34C759',
-  '#FF9500',
-  '#FF3B30',
-  '#5AC8FA',
-  '#AF52DE',
-  '#FF2D55',
-  '#FFCC00',
-];
-
-interface BillStatRow {
-  status: string;
-  count: string;
-  total: string;
-}
-interface ClassAttendanceRank {
-  className: string;
-  present: number;
-  total: number;
-  rate: number;
-}
-interface ClassroomOccupancy {
-  name: string;
-  building: string;
-  capacity: number;
-  scheduleDays: number;
-  rentalCount: number;
-  occupancy: number;
-}
-interface ClassroomUtilStats {
-  totalClassrooms: number;
-  inUseCount: number;
-  utilizationRate: string;
-  scheduleCount: number;
-  rentalCount: number;
-}
-interface AttendanceTrendRow {
-  date: string;
-  rate: string;
-}
-interface IncomeTrendRow {
-  month: string;
-  amount: number;
-}
-interface OccupancyByBuildingRow {
-  building: string;
-  count: string;
-}
-interface ExpenseByTypeRow {
-  type: string;
-  total: string;
-}
-interface GanttOccupancy {
-  studentName: string;
-  studentId?: string;
-  checkInDate: string;
-  checkOutDate: string | null;
-  billingStartDate?: string;
-  billingEndDate?: string;
-}
-interface GanttRoom {
-  roomNumber: string;
-  occupancies: GanttOccupancy[];
-}
-
-interface DashboardStats {
-  totalRooms: number;
-  totalStudents: number;
-  occupiedBeds: number;
-  totalCapacity: number;
-  occupancyRate: string;
-  billStats: BillStatRow[];
-  classroomCount: number;
-  classroomOccupancyRate: string;
-  todayAttendanceRate: string;
-  monthlyIncome: number;
-  classCount: number;
-  teacherCount: number;
-  pendingDeposits: number;
-  activeRentals: number;
-  todayPresent: number;
-  occupancyByBuilding: OccupancyByBuildingRow[];
-  attendanceByStatus: Record<string, number>;
-  expenseByType: ExpenseByTypeRow[];
-  attendanceTrend: AttendanceTrendRow[];
-  incomeTrend: IncomeTrendRow[];
-}
-
-const attendanceLabelMap: Record<string, string> = {
-  present: '出勤',
-  absent: '缺勤',
-  late: '迟到',
-  early: '早退',
-  leave: '请假',
-};
-
-const SECTION_ROW_STYLE: React.CSSProperties = { marginBottom: 24 };
-const MARGIN_BOTTOM_16_STYLE: React.CSSProperties = { marginBottom: 16 };
-
-// ─── 待办卡片样式 ───
-const TODO_CARD_BASE: React.CSSProperties = {
-  cursor: 'pointer',
-  transition: 'box-shadow 0.2s, transform 0.2s',
-  borderRadius: 8,
-  height: '100%',
-};
-const TODO_CARD_WARN: React.CSSProperties = {
-  ...TODO_CARD_BASE,
-  borderLeft: '4px solid #FF9500',
-  background: '#fff7e6',
-};
-const TODO_CARD_DANGER: React.CSSProperties = {
-  ...TODO_CARD_BASE,
-  borderLeft: '4px solid #FF3B30',
-  background: '#fff1f0',
-};
-const TODO_CARD_OK: React.CSSProperties = {
-  ...TODO_CARD_BASE,
-  borderLeft: '4px solid #34C759',
-  background: '#f0fff4',
-};
-const TODO_CARD_DRAFT: React.CSSProperties = {
-  ...TODO_CARD_BASE,
-  borderLeft: '4px solid #AF52DE',
-  background: '#f9f0ff',
-};
-
-// ─── IntersectionObserver 自定义 hook ───
-// 用 callback ref 注册 observer，避免元素在首屏 loading 后才挂载、
-// 而 effect 因依赖不变不再重跑导致 observer 从未注册的问题。
-const useInViewport = (rootMargin = '200px') => {
-  const [inView, setInView] = useState(false);
-  const observerRef = useRef<IntersectionObserver | null>(null);
-
-  const ref = useCallback(
-    (el: HTMLDivElement | null) => {
-      observerRef.current?.disconnect();
-      if (!el) return;
-      const observer = new IntersectionObserver(
-        ([entry]) => {
-          if (entry.isIntersecting) {
-            setInView(true);
-            observer.disconnect();
-          }
-        },
-        { rootMargin },
-      );
-      observer.observe(el);
-      observerRef.current = observer;
-    },
-    [rootMargin],
-  );
-
-  return { ref, inView };
-};
-
 const DashboardPage: React.FC = () => {
   const screens = Grid.useBreakpoint();
   const isMobile = !screens.sm;
-  const navigate = useNavigate();
-  const [stats, setStats] = useState<DashboardStats | null>(null);
-  const [classRanking, setClassRanking] = useState<{
-    top: ClassAttendanceRank[];
-    bottom: ClassAttendanceRank[];
-  }>({ top: [], bottom: [] });
-  const [classroomOccupancy, setClassroomOccupancy] = useState<ClassroomOccupancy[]>([]);
-  const [ganttData, setGanttData] = useState<GanttRoom[]>([]);
-  const [roomRanking, setRoomRanking] = useState<Array<{ roomNumber: string; total: string }>>([]);
-  const [classroomUtil, setClassroomUtil] = useState<ClassroomUtilStats | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [refreshLoading, setRefreshLoading] = useState(false);
-  const loadedRef = useRef(false);
   const [period, setPeriod] = useState<[string, string]>([
     dayjs().startOf('month').format('YYYY-MM-DD'),
     dayjs().endOf('month').format('YYYY-MM-DD'),
   ]);
 
-  const fetchData = useCallback(async () => {
-    const isRefresh = loadedRef.current;
-    if (isRefresh) {
-      setRefreshLoading(true);
-    } else {
-      setLoading(true);
-    }
-    try {
-      const [s, rr, cr, g] = await Promise.all([
-        api.get<DashboardStats>('/dashboard/stats'),
-        api.get<Array<{ roomNumber: string; total: string }>>('/dashboard/room-ranking', {
-          params: { periodStart: period[0], periodEnd: period[1] },
-        }),
-        api.get<{ top: ClassAttendanceRank[]; bottom: ClassAttendanceRank[] }>(
-          '/dashboard/class-attendance-ranking',
-        ),
-        api.get<GanttRoom[]>('/dashboard/gantt', {
-          params: { periodStart: period[0], periodEnd: period[1] },
-        }),
-      ]);
-      setStats(s);
-      setRoomRanking(rr);
-      setClassRanking(cr);
-      setGanttData(g);
-      const co = await api.get<ClassroomOccupancy[]>('/dashboard/classroom-occupancy');
-      setClassroomOccupancy(co);
-      const cu = await api.get<ClassroomUtilStats>('/dashboard/classroom-utilization');
-      setClassroomUtil(cu);
-      loadedRef.current = true;
-    } catch (e) {
-      console.error(e);
-      message.error('数据加载失败，请稍后重试');
-    }
-    setLoading(false);
-    setRefreshLoading(false);
-  }, [period]);
+  const {
+    data: fetchResult = {
+      stats: null,
+      classRanking: { top: [], bottom: [] },
+      classroomOccupancy: [],
+      ganttData: [],
+      roomRanking: [],
+      classroomUtil: null,
+    },
+    isLoading,
+    isFetching,
+  } = useQuery<{
+    stats: DashboardStats | null;
+    classRanking: { top: ClassAttendanceRank[]; bottom: ClassAttendanceRank[] };
+    classroomOccupancy: ClassroomOccupancy[];
+    ganttData: GanttRoom[];
+    roomRanking: Array<{ roomNumber: string; total: string }>;
+    classroomUtil: ClassroomUtilStats | null;
+  }>({
+    queryKey: ['dashboard', period],
+    queryFn: async () => {
+      try {
+        const [s, rr, cr, g, co, cu] = await Promise.all([
+          api.get<DashboardStats>('/dashboard/stats'),
+          api.get<Array<{ roomNumber: string; total: string }>>('/dashboard/room-ranking', {
+            params: { periodStart: period[0], periodEnd: period[1] },
+          }),
+          api.get<{ top: ClassAttendanceRank[]; bottom: ClassAttendanceRank[] }>(
+            '/dashboard/class-attendance-ranking',
+          ),
+          api.get<GanttRoom[]>('/dashboard/gantt', {
+            params: { periodStart: period[0], periodEnd: period[1] },
+          }),
+          api.get<ClassroomOccupancy[]>('/dashboard/classroom-occupancy'),
+          api.get<ClassroomUtilStats>('/dashboard/classroom-utilization'),
+        ]);
+        return {
+          stats: validateResponse<DashboardStats>(dashboardStatsSchema, s),
+          roomRanking: validateResponse<Array<{ roomNumber: string; total: string }>>(
+            roomRankingSchema,
+            rr,
+          ),
+          classRanking: validateResponse<{
+            top: ClassAttendanceRank[];
+            bottom: ClassAttendanceRank[];
+          }>(classAttendanceRankingSchema, cr),
+          ganttData: validateResponse<GanttRoom[]>(ganttRoomsSchema, g),
+          classroomOccupancy: validateResponse<ClassroomOccupancy[]>(
+            classroomOccupanciesSchema,
+            co,
+          ),
+          classroomUtil: validateResponse<ClassroomUtilStats>(classroomUtilStatsSchema, cu),
+        };
+      } catch (e) {
+        console.error(e);
+        message.error('数据加载失败，请稍后重试');
+        return {
+          stats: null,
+          classRanking: { top: [], bottom: [] },
+          classroomOccupancy: [],
+          ganttData: [],
+          roomRanking: [],
+          classroomUtil: null,
+        };
+      }
+    },
+  });
+  const stats = fetchResult.stats;
+  const classRanking = fetchResult.classRanking;
+  const classroomOccupancy = fetchResult.classroomOccupancy;
+  const ganttData = fetchResult.ganttData;
+  const roomRanking = fetchResult.roomRanking;
+  const classroomUtil = fetchResult.classroomUtil;
+  const loading = isLoading;
+  const refreshLoading = isFetching && !isLoading;
 
-  useEffect(() => {
-    fetchData();
-  }, [fetchData]);
-
-  const [expenseTypeMap, setExpenseTypeMap] = useState<Record<string, string>>({});
-
-  useEffect(() => {
-    api
-      .get<Array<{ code: string; name: string }>>('/expense-types')
-      .then((types) => {
+  const { data: expenseTypeMap = {} } = useQuery<Record<string, string>>({
+    queryKey: ['expense-types', 'map'],
+    queryFn: async () => {
+      try {
+        const types = validateResponse<Array<{ code: string; name: string }>>(
+          expenseTypesSchema,
+          await api.get<Array<{ code: string; name: string }>>('/expense-types'),
+        );
         const map: Record<string, string> = {};
         for (const t of types) map[t.code] = t.name;
-        setExpenseTypeMap(map);
-      })
-      .catch(() => {});
-  }, []);
-
-  // ─── 图表 option 计算（保留全部原有逻辑） ───
-
-  // 今日出勤状态分布环图
-  const attendanceRingOption = useMemo<EChartsOption>(
-    () => ({
-      tooltip: { trigger: 'item' },
-      legend: { bottom: 0 },
-      series: [
-        {
-          type: 'pie',
-          radius: ['40%', '70%'],
-          center: ['50%', '45%'],
-          data: Object.entries(stats?.attendanceByStatus ?? {}).map(([status, count]) => ({
-            name: attendanceLabelMap[status] ?? status,
-            value: count,
-          })),
-          itemStyle: { borderRadius: 4, borderColor: '#fff', borderWidth: 2 },
-        },
-      ],
-      color: COLORS,
-    }),
-    [stats?.attendanceByStatus],
-  );
-
-  // 宿舍费用排行
-  const barOption = useMemo<EChartsOption>(
-    () => ({
-      tooltip: {},
-      grid: { left: 80, right: 20, bottom: 30, top: 10 },
-      xAxis: { type: 'value' },
-      yAxis: {
-        type: 'category',
-        data: roomRanking.map((r) => r.roomNumber).reverse(),
-        inverse: false,
-      },
-      series: [
-        {
-          type: 'bar',
-          data: roomRanking.map((r) => Number(r.total)).reverse(),
-          itemStyle: { color: '#007AFF', borderRadius: [0, 4, 4, 0] },
-        },
-      ],
-    }),
-    [roomRanking],
-  );
-
-  // 班级考勤排行 - 前5
-  const classRankingTopOption: EChartsOption = {
-    tooltip: {
-      trigger: 'axis',
-      axisPointer: { type: 'shadow' },
-      valueFormatter: (v: number) => `${v}%`,
+        return map;
+      } catch {
+        return {};
+      }
     },
-    grid: { left: 80, right: 30, bottom: 30, top: 10 },
-    xAxis: { type: 'value', max: 100, axisLabel: { formatter: '{value}%' } },
-    yAxis: {
-      type: 'category',
-      data: classRanking.top.map((r) => r.className),
-      inverse: true,
-    },
-    series: [
-      {
-        type: 'bar',
-        data: classRanking.top.map((r) => r.rate),
-        itemStyle: { color: '#34C759', borderRadius: [0, 4, 4, 0] },
-        label: { show: true, position: 'right', formatter: '{c}%' },
-      },
-    ],
-  };
+  });
 
-  // 班级考勤排行 - 后5
-  const classRankingBottomOption: EChartsOption = {
-    tooltip: {
-      trigger: 'axis',
-      axisPointer: { type: 'shadow' },
-      valueFormatter: (v: number) => `${v}%`,
-    },
-    grid: { left: 80, right: 30, bottom: 30, top: 10 },
-    xAxis: { type: 'value', max: 100, axisLabel: { formatter: '{value}%' } },
-    yAxis: {
-      type: 'category',
-      data: classRanking.bottom.map((r) => r.className),
-      inverse: true,
-    },
-    series: [
-      {
-        type: 'bar',
-        data: classRanking.bottom.map((r) => r.rate),
-        itemStyle: { color: '#FF3B30', borderRadius: [0, 4, 4, 0] },
-        label: { show: true, position: 'right', formatter: '{c}%' },
-      },
-    ],
-  };
-
-  // 考勤趋势折线图
-  const attendanceLineOption: EChartsOption = {
-    tooltip: { trigger: 'axis' },
-    grid: { left: 50, right: 20, bottom: 30, top: 10 },
-    xAxis: {
-      type: 'category',
-      data: (stats?.attendanceTrend || []).map((d: { date: string }) => d.date),
-      axisLabel: { rotate: 45, fontSize: 10 },
-    },
-    yAxis: { type: 'value', min: 0, max: 100, axisLabel: { formatter: '{value}%' } },
-    series: [
-      {
-        type: 'line',
-        data: (stats?.attendanceTrend || []).map((d: { rate: string }) => parseFloat(d.rate) || 0),
-        smooth: true,
-        lineStyle: { color: '#007AFF', width: 2 },
-        itemStyle: { color: '#007AFF' },
-        areaStyle: { color: 'rgba(0,122,255,0.1)' },
-      },
-    ],
-  };
-
-  // 收入趋势折线图
-  const incomeLineOption: EChartsOption = {
-    tooltip: { trigger: 'axis', valueFormatter: (v: number) => `¥${v.toLocaleString()}` },
-    grid: { left: 70, right: 20, bottom: 30, top: 10 },
-    xAxis: {
-      type: 'category',
-      data: (stats?.incomeTrend || []).map((d: { month: string }) => d.month),
-    },
-    yAxis: {
-      type: 'value',
-      axisLabel: { formatter: (v: number) => `¥${(v / 10000).toFixed(0)}万` },
-    },
-    series: [
-      {
-        type: 'line',
-        data: (stats?.incomeTrend || []).map((d: { amount: number }) => d.amount),
-        smooth: true,
-        lineStyle: { color: '#34C759', width: 2 },
-        itemStyle: { color: '#34C759' },
-        areaStyle: { color: 'rgba(52,199,89,0.1)' },
-      },
-    ],
-  };
-
-  // 入住时间线（甘特图）
-  const ganttOption = useMemo<EChartsOption>(
-    () => ({
-      tooltip: {
-        formatter: (p: { data: { name: string; value: [string, string, string, boolean] } }) =>
-          `${p.data.name}<br/>入住: ${p.data.value[1]}<br/>退宿: ${p.data.value[2]}`,
-      },
-      grid: { left: 100, right: 30, bottom: 40, top: 20 },
-      xAxis: { type: 'time' },
-      yAxis: { type: 'category', data: ganttData.map((r) => r.roomNumber), inverse: true },
-      dataZoom: [
-        { type: 'slider', xAxisIndex: 0, bottom: 10, height: 20 },
-        { type: 'inside', xAxisIndex: 0 },
-      ],
-      series: [
-        {
-          type: 'custom',
-          renderItem: (
-            _params: unknown,
-            api: {
-              value: (i: number) => string | boolean;
-              coord: (p: [string | number, string | number]) => [number, number];
-              size: (p: [number, number]) => [number, number];
-            },
-          ) => {
-            const [cat, startDate, endDate, isActive] = [
-              api.value(0),
-              api.value(1),
-              api.value(2),
-              api.value(3),
-            ] as unknown as [string, string, string, boolean];
-            const start = api.coord([startDate, cat]);
-            const end = api.coord([endDate, cat]);
-            const height = api.size([0, 1])[1] * 0.6;
-            const rectShape = {
-              x: start[0],
-              y: start[1] - height / 2,
-              width: Math.max(end[0] - start[0], 2),
-              height,
-            };
-            return {
-              type: 'rect' as const,
-              shape: rectShape,
-              style: { fill: isActive ? '#34C759' : '#FF9500', stroke: '#fff', lineWidth: 1 },
-            };
-          },
-          encode: { x: [1, 2], y: 0 },
-          data: ganttData.flatMap((r) =>
-            (r.occupancies || []).map((o) => ({
-              name: o.studentName,
-              value: [
-                r.roomNumber,
-                o.checkInDate,
-                o.checkOutDate || new Date().toISOString().slice(0, 10),
-                !o.checkOutDate,
-              ] as [string, string, string, boolean],
-            })),
-          ),
-        },
-      ],
-    }),
-    [ganttData],
-  );
-
-  // ─── 懒加载 hooks ───
-  const classroomHeatmapVp = useInViewport('200px');
-  const ganttVp = useInViewport('200px');
-
-  // ─── 待办卡片数据 ───
   const absentCount = stats?.attendanceByStatus?.['absent'] ?? 0;
+  const attendanceTotal = stats
+    ? Object.values(stats.attendanceByStatus).reduce((sum, n) => sum + Number(n || 0), 0)
+    : 0;
+  const presentCount = stats?.attendanceByStatus?.present ?? 0;
+  const todayAttendanceRate =
+    stats?.todayAttendanceRate ??
+    (attendanceTotal > 0 ? ((presentCount / attendanceTotal) * 100).toFixed(1) : '0');
   const draftBill = (stats?.billStats ?? []).find((b) => b.status === 'draft');
   const draftCount = draftBill ? Number(draftBill.count) : 0;
   const draftTotal = draftBill ? Number(draftBill.total) : 0;
@@ -499,118 +192,12 @@ const DashboardPage: React.FC = () => {
       </div>
 
       {/* ═══════════ 待办与异常 ═══════════ */}
-      <Card title="待办与异常" style={MARGIN_BOTTOM_16_STYLE}>
-        <Row gutter={[16, 16]}>
-          {/* 今日缺勤 */}
-          <Col xs={24} sm={8}>
-            <Card
-              style={absentCount > 0 ? TODO_CARD_WARN : TODO_CARD_OK}
-              styles={{ body: { padding: 16 } }}
-              onClick={() => navigate('/attendance')}
-            >
-              <div
-                style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}
-              >
-                <ExclamationCircleOutlined
-                  style={{ fontSize: 28, color: absentCount > 0 ? '#FF9500' : '#999' }}
-                />
-                <ArrowRightOutlined style={{ color: '#bbb' }} />
-              </div>
-              <div style={{ marginTop: 8 }}>
-                <div
-                  style={{
-                    fontSize: 24,
-                    fontWeight: 700,
-                    color: absentCount > 0 ? '#FF9500' : '#999',
-                  }}
-                >
-                  {absentCount}
-                </div>
-                <div style={{ fontSize: 13, color: '#666', marginTop: 2 }}>今日缺勤人数</div>
-                {absentCount > 0 ? (
-                  <div style={{ fontSize: 12, color: '#FF9500', marginTop: 4 }}>需要关注</div>
-                ) : (
-                  <div style={{ fontSize: 12, color: '#34C759', marginTop: 4 }}>全员到齐</div>
-                )}
-              </div>
-            </Card>
-          </Col>
-
-          {/* 待处理账单 */}
-          <Col xs={24} sm={8}>
-            <Card
-              style={draftCount > 0 ? TODO_CARD_DRAFT : TODO_CARD_OK}
-              styles={{ body: { padding: 16 } }}
-              onClick={() => navigate('/bills')}
-            >
-              <div
-                style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}
-              >
-                <DollarOutlined
-                  style={{ fontSize: 28, color: draftCount > 0 ? '#AF52DE' : '#999' }}
-                />
-                <ArrowRightOutlined style={{ color: '#bbb' }} />
-              </div>
-              <div style={{ marginTop: 8 }}>
-                <div
-                  style={{
-                    fontSize: 24,
-                    fontWeight: 700,
-                    color: draftCount > 0 ? '#AF52DE' : '#999',
-                  }}
-                >
-                  {draftCount}
-                </div>
-                <div style={{ fontSize: 13, color: '#666', marginTop: 2 }}>待处理账单</div>
-                <div
-                  style={{ fontSize: 12, color: draftCount > 0 ? '#AF52DE' : '#999', marginTop: 4 }}
-                >
-                  {draftCount > 0 ? `合计 ¥${draftTotal.toLocaleString()}` : '暂无待处理'}
-                </div>
-              </div>
-            </Card>
-          </Col>
-
-          {/* 待退押金 */}
-          <Col xs={24} sm={8}>
-            <Card
-              style={pendingDeposits > 0 ? TODO_CARD_DANGER : TODO_CARD_OK}
-              styles={{ body: { padding: 16 } }}
-              onClick={() => navigate('/deposits')}
-            >
-              <div
-                style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}
-              >
-                <BankOutlined
-                  style={{ fontSize: 28, color: pendingDeposits > 0 ? '#FF3B30' : '#999' }}
-                />
-                <ArrowRightOutlined style={{ color: '#bbb' }} />
-              </div>
-              <div style={{ marginTop: 8 }}>
-                <div
-                  style={{
-                    fontSize: 24,
-                    fontWeight: 700,
-                    color: pendingDeposits > 0 ? '#FF3B30' : '#999',
-                  }}
-                >
-                  ¥{pendingDeposits.toLocaleString()}
-                </div>
-                <div style={{ fontSize: 13, color: '#666', marginTop: 2 }}>待退押金</div>
-                <div
-                  style={{
-                    fontSize: 12,
-                    color: pendingDeposits > 0 ? '#FF3B30' : '#999',
-                    marginTop: 4,
-                  }}
-                >
-                  {pendingDeposits > 0 ? '需要处理' : '暂无待退'}
-                </div>
-              </div>
-            </Card>
-          </Col>
-        </Row>
-      </Card>
+      <DashboardTodoCards
+        absentCount={absentCount}
+        draftCount={draftCount}
+        draftTotal={draftTotal}
+        pendingDeposits={pendingDeposits}
+      />
 
       {/* ═══════════ 核心 KPI ═══════════ */}
       <Row gutter={[16, 16]} style={SECTION_ROW_STYLE}>
@@ -638,7 +225,7 @@ const DashboardPage: React.FC = () => {
           <Card>
             <Statistic
               title="今日出勤率"
-              value={stats?.todayAttendanceRate || 0}
+              value={todayAttendanceRate}
               suffix="%"
               prefix={<UserSwitchOutlined />}
             />
@@ -809,7 +396,7 @@ const DashboardPage: React.FC = () => {
           <Card title="考勤趋势（近30天）">
             {(stats?.attendanceTrend || []).length > 0 ? (
               <ReactECharts
-                option={attendanceLineOption}
+                option={buildAttendanceLineOption(stats?.attendanceTrend ?? [])}
                 style={{ width: '100%', height: isMobile ? 250 : 300 }}
               />
             ) : (
@@ -821,7 +408,7 @@ const DashboardPage: React.FC = () => {
           <Card title="今日出勤状态分布">
             {Object.keys(stats?.attendanceByStatus ?? {}).length > 0 ? (
               <ReactECharts
-                option={attendanceRingOption}
+                option={buildAttendanceRingOption(stats)}
                 style={{ width: '100%', height: isMobile ? 250 : 300 }}
               />
             ) : (
@@ -837,7 +424,7 @@ const DashboardPage: React.FC = () => {
           <Card title="班级出勤率 TOP 5">
             {classRanking.top.length > 0 ? (
               <ReactECharts
-                option={classRankingTopOption}
+                option={buildClassRankingOption(classRanking.top, '#34C759')}
                 style={{ width: '100%', height: isMobile ? 250 : 300 }}
               />
             ) : (
@@ -849,7 +436,7 @@ const DashboardPage: React.FC = () => {
           <Card title="班级出勤率 末位 5">
             {classRanking.bottom.length > 0 ? (
               <ReactECharts
-                option={classRankingBottomOption}
+                option={buildClassRankingOption(classRanking.bottom, '#FF3B30')}
                 style={{ width: '100%', height: isMobile ? 250 : 300 }}
               />
             ) : (
@@ -865,24 +452,7 @@ const DashboardPage: React.FC = () => {
           <Card title="费用类型分布">
             {(stats?.expenseByType ?? []).length > 0 ? (
               <ReactECharts
-                option={
-                  {
-                    tooltip: { trigger: 'item' },
-                    legend: { bottom: 0 },
-                    color: COLORS,
-                    series: [
-                      {
-                        type: 'pie',
-                        radius: ['40%', '70%'],
-                        center: ['50%', '45%'],
-                        data: (stats?.expenseByType ?? []).map((e) => ({
-                          name: expenseTypeMap[e.type] ?? e.type,
-                          value: Number(e.total),
-                        })),
-                      },
-                    ],
-                  } satisfies EChartsOption
-                }
+                option={buildExpensePieOption(stats?.expenseByType ?? [], expenseTypeMap)}
                 style={{ width: '100%', height: isMobile ? 250 : 300 }}
               />
             ) : (
@@ -894,7 +464,7 @@ const DashboardPage: React.FC = () => {
           <Card title="宿舍费用排行 TOP 20">
             {roomRanking.length > 0 ? (
               <ReactECharts
-                option={barOption}
+                option={buildRoomRankingBarOption(roomRanking)}
                 style={{ width: '100%', height: isMobile ? 250 : 300 }}
               />
             ) : (
@@ -910,7 +480,7 @@ const DashboardPage: React.FC = () => {
           <Card title="月度收入趋势">
             {(stats?.incomeTrend || []).length > 0 ? (
               <ReactECharts
-                option={incomeLineOption}
+                option={buildIncomeLineOption(stats?.incomeTrend ?? [])}
                 style={{ width: '100%', height: isMobile ? 250 : 300 }}
               />
             ) : (
@@ -921,102 +491,10 @@ const DashboardPage: React.FC = () => {
       </Row>
 
       {/* ═══════════ 图表：教室占用热力图（懒加载） ═══════════ */}
-      <div ref={classroomHeatmapVp.ref} style={SECTION_ROW_STYLE}>
-        {classroomHeatmapVp.inView ? (
-          <Row gutter={[16, 16]}>
-            <Col xs={24}>
-              <Card title="教室占用热力图">
-                {classroomOccupancy.length > 0 ? (
-                  <ReactECharts
-                    option={
-                      {
-                        tooltip: {
-                          formatter: (p: {
-                            name: string;
-                            data: { scheduleDays: number; rentalCount: number; occupancy: number };
-                          }) =>
-                            `${p.name}<br/>排课: ${p.data.scheduleDays}天 租赁: ${p.data.rentalCount}个 占用率: ${(p.data.occupancy * 100).toFixed(0)}%`,
-                        },
-                        grid: { left: 100, right: 20, bottom: 30, top: 10 },
-                        xAxis: { type: 'value', max: 1 },
-                        yAxis: {
-                          type: 'category',
-                          data: classroomOccupancy.map((r) => r.name),
-                          inverse: true,
-                        },
-                        visualMap: {
-                          min: 0,
-                          max: 1,
-                          orient: 'horizontal',
-                          left: 'center',
-                          bottom: 0,
-                          inRange: {
-                            color: ['#e6f4ff', '#91caff', '#40a9ff', '#0050b3', '#002c8c'],
-                          },
-                        },
-                        series: [
-                          {
-                            type: 'bar',
-                            data: classroomOccupancy.map((r) => ({
-                              name: r.name,
-                              value: r.occupancy,
-                              scheduleDays: r.scheduleDays,
-                              rentalCount: r.rentalCount,
-                              occupancy: r.occupancy,
-                            })),
-                            itemStyle: { borderRadius: [0, 4, 4, 0] },
-                            label: {
-                              show: true,
-                              position: 'right',
-                              formatter: (p: { data: { occupancy: number } }) =>
-                                `${(p.data.occupancy * 100).toFixed(0)}%`,
-                            },
-                          },
-                        ],
-                      } satisfies EChartsOption
-                    }
-                    style={{ width: '100%', height: isMobile ? 300 : 400 }}
-                  />
-                ) : (
-                  <div style={{ textAlign: 'center', padding: 40, color: '#999' }}>
-                    暂无教室数据
-                  </div>
-                )}
-              </Card>
-            </Col>
-          </Row>
-        ) : (
-          <Card title="教室占用热力图" style={{ minHeight: isMobile ? 340 : 440 }}>
-            <div style={{ textAlign: 'center', padding: 40, color: '#999' }}>加载中…</div>
-          </Card>
-        )}
-      </div>
+      <ClassroomHeatmapCard data={classroomOccupancy} isMobile={isMobile} />
 
       {/* ═══════════ 图表：入住时间线甘特图（懒加载） ═══════════ */}
-      <div ref={ganttVp.ref}>
-        {ganttVp.inView ? (
-          <Row gutter={[16, 16]}>
-            <Col xs={24}>
-              <Card title="入住时间线（甘特图）">
-                {ganttData.length > 0 ? (
-                  <ReactECharts
-                    option={ganttOption}
-                    style={{ width: '100%', height: isMobile ? 300 : 450 }}
-                  />
-                ) : (
-                  <div style={{ textAlign: 'center', padding: 40, color: '#999' }}>
-                    暂无入住数据
-                  </div>
-                )}
-              </Card>
-            </Col>
-          </Row>
-        ) : (
-          <Card title="入住时间线（甘特图）" style={{ minHeight: isMobile ? 340 : 490 }}>
-            <div style={{ textAlign: 'center', padding: 40, color: '#999' }}>加载中…</div>
-          </Card>
-        )}
-      </div>
+      <GanttCard data={ganttData} isMobile={isMobile} />
     </div>
   );
 };

apps/admin/src/pages/Deposits/DepositModals.tsx

@@ -0,0 +1,423 @@
+import React from 'react';
+import {
+  Card,
+  DatePicker,
+  Empty,
+  Form,
+  Input,
+  InputNumber,
+  Modal,
+  Popconfirm,
+  Select,
+  Space,
+  Table,
+  Tag,
+} from 'antd';
+import { DollarOutlined, InboxOutlined, PlusOutlined } from '@ant-design/icons';
+import PermissionButton from '../../components/PermissionButton';
+import EditableCell from '../../components/EditableCell';
+import type { DepositStudentLookup } from './deposit-student-option';
+
+export interface DepositRecord {
+  id: number;
+  studentId: number;
+  amount: number;
+  status: string;
+  paidDate: string;
+  refundDate?: string | null;
+  notes?: string | null;
+  installments?: Array<{
+    id: number;
+    amount: number;
+    dueDate: string;
+    paidDate?: string | null;
+    status: string;
+  }>;
+  student?: DepositStudentLookup;
+}
+
+export interface EligibleStudent {
+  studentId: number;
+  studentName: string;
+  studentNo?: string | null;
+  roomId: number;
+  roomNumber: string;
+  building?: string | null;
+  roomType?: string | null;
+  capacity: number;
+  depositAmount: number;
+}
+
+export const statusMap: Record<string, { text: string; color: string }> = {
+  paid: { text: '有余额', color: 'green' },
+  refunded: { text: '已全退', color: 'blue' },
+  depleted: { text: '已扣完', color: 'red' },
+};
+
+export const installmentStatusMap: Record<string, { text: string; color: string }> = {
+  pending: { text: '待缴', color: 'orange' },
+  paid: { text: '已缴', color: 'green' },
+};
+
+export const roomTypeOptions = [
+  { value: '单人间', label: '单人间' },
+  { value: '四人间', label: '四人间' },
+];
+
+export const suggestedDepositByRoomType: Record<string, number> = {
+  单人间: 200,
+  四人间: 100,
+};
+
+export interface DepositModalsProps {
+  batchModal: boolean;
+  createModal: boolean;
+  refundModal: DepositRecord | null;
+  detailModal: DepositRecord | null;
+  installmentModal: number | null;
+  batchForm: ReturnType<typeof Form.useForm>[0];
+  createForm: ReturnType<typeof Form.useForm>[0];
+  refundForm: ReturnType<typeof Form.useForm>[0];
+  installmentForm: ReturnType<typeof Form.useForm>[0];
+  saving: boolean;
+  batchRoomType: string;
+  effectiveSelectedEligibleIds: number[];
+  eligibleStudents: EligibleStudent[];
+  eligibleLoading: boolean;
+  eligibleColumns: Array<{ title: string; render?: unknown; dataIndex?: string }>;
+  studentOptions: Array<{ value: number; label: string }>;
+  onBatchRoomTypeChange: (roomType: string) => void;
+  onBatchCreate: () => void;
+  onCreate: () => void;
+  onRefund: () => void;
+  onAddInstallment: () => void;
+  onPayInstallment: (installmentId: number) => void;
+  onSaveInstallmentCell: (
+    installmentId: number,
+    field: 'status' | 'paidDate',
+    value: unknown,
+  ) => void;
+  onDeleteInstallment: (installmentId: number) => void;
+  onCloseBatch: () => void;
+  onCloseCreate: () => void;
+  onCloseRefund: () => void;
+  onCloseDetail: () => void;
+  onCloseInstallment: () => void;
+  onOpenInstallment: (id: number) => void;
+  onSelectEligible: (ids: number[]) => void;
+}
+
+export const DepositModals: React.FC<DepositModalsProps> = ({
+  batchModal,
+  createModal,
+  refundModal,
+  detailModal,
+  installmentModal,
+  batchForm,
+  createForm,
+  refundForm,
+  installmentForm,
+  saving,
+  batchRoomType,
+  effectiveSelectedEligibleIds,
+  eligibleStudents,
+  eligibleLoading,
+  eligibleColumns,
+  studentOptions,
+  onBatchRoomTypeChange,
+  onBatchCreate,
+  onCreate,
+  onRefund,
+  onAddInstallment,
+  onPayInstallment,
+  onSaveInstallmentCell,
+  onDeleteInstallment,
+  onCloseBatch,
+  onCloseCreate,
+  onCloseRefund,
+  onCloseDetail,
+  onCloseInstallment,
+  onOpenInstallment,
+  onSelectEligible,
+}) => {
+  return (
+    <>
+      <Modal
+        title="按房型批量收取押金"
+        open={batchModal}
+        onOk={onBatchCreate}
+        onCancel={onCloseBatch}
+        okText="确认批量收取"
+        confirmLoading={saving}
+        okButtonProps={{ disabled: effectiveSelectedEligibleIds.length === 0 }}
+        width={760}
+      >
+        <Form form={batchForm} layout="vertical">
+          <Space style={{ width: '100%' }} align="start" wrap>
+            <Form.Item
+              name="roomType"
+              label="房型"
+              rules={[{ required: true, message: '请选择房型' }]}
+            >
+              <Select
+                style={{ width: 140 }}
+                options={roomTypeOptions}
+                onChange={onBatchRoomTypeChange}
+              />
+            </Form.Item>
+            <Form.Item
+              name="amount"
+              label="每人收取金额（元）"
+              rules={[{ required: true, message: '请输入金额' }]}
+            >
+              <InputNumber min={0.01} precision={2} style={{ width: 180 }} />
+            </Form.Item>
+            <Form.Item
+              name="paidDate"
+              label="收取日期"
+              rules={[{ required: true, message: '请选择日期' }]}
+            >
+              <DatePicker style={{ width: 180 }} placeholder="选择收取日期" format="YYYY-MM-DD" />
+            </Form.Item>
+          </Space>
+          <Form.Item name="notes" label="备注">
+            <Input.TextArea rows={2} placeholder={`${batchRoomType}押金`} />
+          </Form.Item>
+        </Form>
+        <div style={{ marginBottom: 8 }}>
+          已选择 <strong>{effectiveSelectedEligibleIds.length}</strong> / {eligibleStudents.length}{' '}
+          人
+          {suggestedDepositByRoomType[batchRoomType] && (
+            <span style={{ color: '#999', marginLeft: 8 }}>
+              建议金额：¥{suggestedDepositByRoomType[batchRoomType]}
+            </span>
+          )}
+        </div>
+        <Table
+          size="small"
+          columns={eligibleColumns as never}
+          dataSource={eligibleStudents}
+          rowKey="studentId"
+          loading={eligibleLoading}
+          locale={{ emptyText: <Empty description="暂无符合条件的在住人员" /> }}
+          pagination={{ pageSize: 6, showSizeChanger: false }}
+          rowSelection={{
+            selectedRowKeys: effectiveSelectedEligibleIds,
+            onChange: (keys) => onSelectEligible(keys as number[]),
+          }}
+        />
+      </Modal>
+
+      <Modal
+        title="收取押金"
+        open={createModal}
+        onOk={onCreate}
+        onCancel={onCloseCreate}
+        okText="确认"
+        confirmLoading={saving}
+      >
+        <Form form={createForm} layout="vertical">
+          <Form.Item
+            name="studentId"
+            label="学生"
+            rules={[{ required: true, message: '请选择学生' }]}
+          >
+            <Select
+              showSearch
+              optionFilterProp="label"
+              placeholder="搜索并选择学生"
+              options={studentOptions}
+            />
+          </Form.Item>
+          <Form.Item name="amount" label="本次收取金额（元）" rules={[{ required: true }]}>
+            <InputNumber min={0.01} precision={2} style={{ width: '100%' }} />
+          </Form.Item>
+          <Form.Item name="paidDate" label="收取日期" rules={[{ required: true }]}>
+            <DatePicker style={{ width: '100%' }} placeholder="选择收取日期" format="YYYY-MM-DD" />
+          </Form.Item>
+          <Form.Item name="notes" label="备注">
+            <Input.TextArea rows={2} />
+          </Form.Item>
+        </Form>
+      </Modal>
+
+      <Modal
+        title={`退还押金 - ${refundModal?.student?.name}`}
+        open={!!refundModal}
+        onOk={onRefund}
+        onCancel={onCloseRefund}
+        okText="确认退还"
+        confirmLoading={saving}
+      >
+        <Form form={refundForm} layout="vertical">
+          <div style={{ marginBottom: 16, padding: 12, background: '#f5f5f5', borderRadius: 8 }}>
+            当前可用押金: <strong>¥{Number(refundModal?.amount || 0).toFixed(2)}</strong>
+          </div>
+          <Form.Item name="refundDate" label="退还日期" rules={[{ required: true }]}>
+            <DatePicker style={{ width: '100%' }} placeholder="选择退还日期" format="YYYY-MM-DD" />
+          </Form.Item>
+          <Form.Item name="notes" label="备注">
+            <Input.TextArea rows={2} />
+          </Form.Item>
+        </Form>
+      </Modal>
+
+      <Modal
+        title={`押金详情 - ${detailModal?.student?.name}`}
+        open={!!detailModal}
+        onCancel={onCloseDetail}
+        footer={null}
+        width={640}
+      >
+        {detailModal && (
+          <div>
+            <Card size="small" style={{ marginBottom: 16 }}>
+              <p>
+                <strong>当前可用押金:</strong> ¥{Number(detailModal.amount).toFixed(2)}
+              </p>
+              <p>
+                <strong>最近收取日期:</strong> {detailModal.paidDate}
+              </p>
+              <p>
+                <strong>状态:</strong>{' '}
+                <Tag color={statusMap[detailModal.status]?.color}>
+                  {statusMap[detailModal.status]?.text || detailModal.status}
+                </Tag>
+              </p>
+              {detailModal.notes && (
+                <p>
+                  <strong>备注:</strong> {detailModal.notes}
+                </p>
+              )}
+            </Card>
+
+            <div
+              style={{
+                display: 'flex',
+                justifyContent: 'space-between',
+                alignItems: 'center',
+                marginBottom: 8,
+              }}
+            >
+              <h4 style={{ margin: 0 }}>分期记录</h4>
+              <PermissionButton
+                permission="deposit:edit"
+                size="small"
+                type="primary"
+                icon={<PlusOutlined />}
+                onClick={() => onOpenInstallment(detailModal.id)}
+              >
+                添加分期
+              </PermissionButton>
+            </div>
+            {detailModal.installments && detailModal.installments.length > 0 ? (
+              <Table
+                size="small"
+                pagination={false}
+                rowKey="id"
+                dataSource={detailModal.installments}
+                columns={[
+                  {
+                    title: '金额',
+                    dataIndex: 'amount',
+                    render: (value: number) => `¥${value.toFixed(2)}`,
+                  },
+                  { title: '到期日', dataIndex: 'dueDate' },
+                  {
+                    title: '实付日',
+                    dataIndex: 'paidDate',
+                    render: (value: string, item: any) => (
+                      <EditableCell
+                        value={value}
+                        editor="date"
+                        permission="deposit:edit"
+                        onSave={async (next) =>
+                          onSaveInstallmentCell(item.id, 'paidDate', next)
+                        }
+                      >
+                        {value || '-'}
+                      </EditableCell>
+                    ),
+                  },
+                  {
+                    title: '状态',
+                    dataIndex: 'status',
+                    render: (value: string, item: any) => (
+                      <EditableCell
+                        value={value}
+                        editor="select"
+                        options={[
+                          { value: 'pending', label: '待缴' },
+                          { value: 'paid', label: '已缴' },
+                          { value: 'overdue', label: '逾期' },
+                        ]}
+                        permission="deposit:edit"
+                        onSave={async (next) =>
+                          onSaveInstallmentCell(item.id, 'status', next)
+                        }
+                      >
+                        <Tag color={installmentStatusMap[value]?.color}>
+                          {installmentStatusMap[value]?.text || value}
+                        </Tag>
+                      </EditableCell>
+                    ),
+                  },
+                  {
+                    title: '操作',
+                    render: (_: unknown, item: any) => (
+                      <Space>
+                        {item.status === 'pending' && (
+                          <PermissionButton
+                            permission="deposit:edit"
+                            size="small"
+                            type="primary"
+                            icon={<DollarOutlined />}
+                            onClick={() => onPayInstallment(item.id)}
+                          >
+                            标记已缴
+                          </PermissionButton>
+                        )}
+                        <Popconfirm
+                          title="确定归档？"
+                          onConfirm={() => onDeleteInstallment(item.id)}
+                        >
+                          <PermissionButton
+                            permission="deposit:delete"
+                            size="small"
+                            danger
+                            icon={<InboxOutlined />}
+                          >
+                            归档
+                          </PermissionButton>
+                        </Popconfirm>
+                      </Space>
+                    ),
+                  },
+                ]}
+              />
+            ) : (
+              <p style={{ color: '#999' }}>暂无分期记录</p>
+            )}
+          </div>
+        )}
+      </Modal>
+
+      <Modal
+        title="添加分期"
+        open={installmentModal != null}
+        onOk={onAddInstallment}
+        onCancel={onCloseInstallment}
+        okText="确认"
+      >
+        <Form form={installmentForm} layout="vertical">
+          <Form.Item name="amount" label="分期金额（元）" rules={[{ required: true }]}>
+            <InputNumber min={0.01} precision={2} style={{ width: '100%' }} />
+          </Form.Item>
+          <Form.Item name="dueDate" label="到期日期" rules={[{ required: true }]}>
+            <DatePicker style={{ width: '100%' }} placeholder="选择到期日期" format="YYYY-MM-DD" />
+          </Form.Item>
+        </Form>
+      </Modal>
+    </>
+  );
+};