Merge pull request 'ci: 部署工作流改为本地 runner 直跑版（免 SSH/Secrets）' (#65) from ci/local-runner-deploy into main

- 移除 SSH/rsync 步骤与 SSH 相关 Secrets 依赖，runs-on: self-hosted 本机直跑
- 步骤：git pull → npm ci → build → migration:run → pm2 startOrReload --update-env → 健康检查
- 新增可选输入 seed_roles：首次部署/新增权限码时强制播种 RBAC，跑完自动去掉
- .env 无需配置到 Gitea，仅放服务器部署目录
- 注释说明 runner 在 docker 容器时的挂载与宿主 pm2 要求

.env.example

@@ -33,3 +33,11 @@ AI_CONFIG_ENCRYPTION_KEY=
 
 # 允许内网地址作为 OPENAI_COMPATIBLE 的 baseUrl（仅内网部署使用）
 # AI_ALLOW_PRIVATE_BASE_URL=true
+
+# ---- 安全 ----
+# 是否信任反向代理的 X-Forwarded-For / X-Real-IP（仅当部署在可信代理/Nginx 后时才设 true；
+# 不设置时服务端只用 TCP socket 地址，防止伪造客户端 IP）
+# TRUST_PROXY=true
+
+# 说明：第三方集成配置（钉钉/企微 appSecret）的静态加密复用 AI_CONFIG_ENCRYPTION_KEY，
+# 存量明文可用 `cd apps/server && npm run encrypt:integration-secrets` 一次性加密。

.gitea/workflows/deploy.yml

@@ -1,80 +1,83 @@
-# PM2 手动部署工作流
-# 手动触发 → 构建 → rsync → 安装依赖 → 数据库迁移 → PM2 重载
+# PM2 本地 runner 手动部署工作流
+# 手动触发 → 服务器本地 git pull → 构建 → 依赖安装 → 数据库迁移 → PM2 重载
+#
+# 适用场景：Gitea runner 与生产服务器同机（本机直跑，不需要 SSH/Secrets）。
 #
 # 前置准备：
-#   1. 服务器 MySQL 已在运行
-#   2. 服务器已安装 PM2: npm i -g pm2
-#   3. Gitea 仓库 Settings → Secrets 配置：
-#      - SSH_PRIVATE_KEY : 部署用 SSH 私钥
-#      - SSH_HOST        : 服务器地址
-#      - SSH_USER        : SSH 用户名
-#      - SSH_PORT        : SSH 端口（默认 22，可选）
-#      - REMOTE_DIR      : 服务器项目目录，如 /opt/gongxue
+#   1. Gitea Actions 已开启，且已注册 self-hosted runner（runs-on 标签与下面一致）
+#   2. 服务器已 clone 仓库到部署目录（默认 /opt/gongxue，可用仓库 Variable REMOTE_DIR 覆盖）
+#   3. 服务器已安装 Node 22 + PM2（npm i -g pm2），MySQL 已运行
+#   4. runner 运行账户对部署目录有写权限、可执行 npm/pm2
+#
+# 关于 .env：不需要配置在 Gitea 界面。.env 只放在服务器部署目录下，
+#   git pull 不会覆盖它，PM2/Nest 启动时直接读取服务器上的 .env。
+#
+# 关于“在 docker 里构建/迁移”：
+#   - 如果 runner 以“宿主机进程”方式运行（推荐，最省事）：本 workflow 的
+#     npm ci / build / migration 直接在宿主机执行，pm2 直接操作宿主 pm2。
+#   - 如果 runner 跑在 docker 容器里：需要把部署目录挂载进容器
+#     （如 -v /opt/gongxue:/opt/gongxue），构建/迁移在容器内完成；
+#     PM2 重载则必须打到宿主机（挂载 docker.sock 后 docker exec 到宿主，
+#     或在宿主机单独跑 pm2 服务端）——容器里的 pm2 管理不了宿主进程。
 
-name: PM2 部署
+name: PM2 本地部署
 
 on:
   workflow_dispatch:
+    inputs:
+      seed_roles:
+        description: '强制播种 RBAC 权限码（首次部署或新增权限码时勾选，跑完会自动去掉）'
+        required: false
+        default: false
+        type: boolean
+
+concurrency:
+  group: deploy-local
+  cancel-in-progress: false
 
 jobs:
   deploy:
-    runs-on: ubuntu-latest
+    runs-on: self-hosted   # 改为你注册 runner 时使用的 label（如 ubuntu-latest）
     steps:
-      - name: 检出代码
-        uses: actions/checkout@v4
-
-      - name: 安装 Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
+      - name: 拉取最新代码
+        run: |
+          cd ${{ vars.REMOTE_DIR || '/opt/gongxue' }}
+          git fetch origin
+          git checkout main
+          git pull origin main
 
       - name: 安装依赖 & 构建
         run: |
+          cd ${{ vars.REMOTE_DIR || '/opt/gongxue' }}
           npm ci
           npm run build -w @gongxue/server
           npm run build -w @gongxue/admin
 
-      - name: 配置 SSH
+      - name: 执行数据库迁移
         run: |
-          mkdir -p ~/.ssh
-          echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/deploy_key
-          chmod 600 ~/.ssh/deploy_key
-          cat >> ~/.ssh/config <<'EOF'
-          Host deploy-server
-            HostName ${{ secrets.SSH_HOST }}
-            User ${{ secrets.SSH_USER }}
-            Port ${{ secrets.SSH_PORT || '22' }}
-            IdentityFile ~/.ssh/deploy_key
-            StrictHostKeyChecking accept-new
-          EOF
+          cd ${{ vars.REMOTE_DIR || '/opt/gongxue' }}
+          npm run migration:run -w @gongxue/server
 
-      - name: 同步代码到服务器
+      - name: PM2 重载
         run: |
-          rsync -avz --delete \
-            --exclude='node_modules' \
-            --exclude='.git' \
-            --exclude='*.db' \
-            --exclude='.DS_Store' \
-            --exclude='logs/' \
-            --exclude='.turbo/' \
-            --exclude='.claude/' \
-            --exclude='.codegraph/' \
-            ./ deploy-server:${{ secrets.REMOTE_DIR }}/
-
-      - name: 安装依赖 → 迁移 → PM2 重载
-        run: |
-          ssh deploy-server "
-            cd ${{ secrets.REMOTE_DIR }}
-            mkdir -p logs
-            if [ ! -d node_modules ]; then
-              echo '首次部署，安装生产依赖...'
-              npm ci --omit=dev
-            fi
-            echo '执行数据库迁移...'
-            npm run migration:run -w @gongxue/server
-            echo 'PM2 重载...'
+          cd ${{ vars.REMOTE_DIR || '/opt/gongxue' }}
+          if [ "${{ github.event.inputs.seed_roles }}" = "true" ]; then
+            echo '>>> 强制播种 RBAC 权限码（本次进程带 SEED_ROLES=true）'
+            SEED_ROLES=true pm2 startOrReload ecosystem.config.cjs --only gongxue-backend --update-env
+            pm2 restart gongxue-backend --update-env   # 去掉 SEED_ROLES 正常重启
+          else
             pm2 startOrReload ecosystem.config.cjs --update-env
-            pm2 save
-            echo '=== PM2 状态 ==='
-            pm2 status
-          "
+          fi
+          pm2 save
+          pm2 status
+
+      - name: 健康检查
+        run: |
+          cd ${{ vars.REMOTE_DIR || '/opt/gongxue' }}
+          sleep 3
+          code="$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3000/api/dashboard/stats || true)"
+          echo "后端 HTTP 状态: ${code}（401=正常，接口需登录）"
+          if [ "${code}" != "401" ] && [ "${code}" != "200" ]; then
+            echo "健康检查失败：后端未按预期响应" >&2
+            exit 1
+          fi

.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

@@ -16,6 +16,11 @@
 | 账单导出 | Excel（汇总+明细双Sheet）、单条PDF账单 |
 | 教室管理 | 教室信息维护、教室租赁记录 |
 | 押金管理 | 押金收取与退还 |
+| 班级/排课 | 班级档案、分班、教室日程与排课 |
+| 考勤管理 | 手工考勤、钉钉考勤同步、自动匹配 |
+| 教室租赁 | 租赁订单、合同、租赁日程 |
+| AI 助手 | 对话式查询、表单/导入向导/图表、业务待办引导 |
+| 组织/校区 | 组织机构与数据范围 |
 | 操作日志 | 所有涉及钱的操作自动审计留痕 |
 | 账号管理 | 用户增删改查、角色区分、启用/禁用、重置密码 |
 
@@ -24,10 +29,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,11 +42,12 @@
 
 - Node.js >= 18
 - npm >= 9
+- MySQL 8.0
 
 ### 后端启动
 
 ```bash
-cd backend
+cd apps/server
 cp .env.example .env   # 复制并修改环境配置
 npm install
 npm run start:dev      # 开发模式启动，默认端口 3000
@@ -50,50 +56,52 @@ npm run start:dev      # 开发模式启动，默认端口 3000
 ### 前端启动
 
 ```bash
-cd frontend
+cd apps/admin
 npm install
 npm run dev            # 开发模式启动，默认端口 5173
 ```
 
-### Docker 部署
+### 常用命令
 
 ```bash
-docker-compose up -d   # 一键启动 MySQL + 后端 + 前端
+npm run typecheck      # 全仓类型检查
+npm run lint           # 全仓 lint
+npm run test           # 全仓测试
+npm run build          # 全仓构建
 ```
 
 ## 项目结构
 
 ```
-├── backend/            # 后端 NestJS 服务
+├── apps/server/        # 后端 NestJS 服务
 │   ├── src/
-│   │   ├── auth/       # 认证模块 (JWT)
+│   │   ├── ai-chat/    # AI 对话、表单/导入向导/图表
+│   │   ├── attendance/ # 考勤与钉钉同步
 │   │   ├── bills/      # 账单模块
-│   │   ├── classrooms/ # 教室管理
 │   │   ├── dashboard/  # 数据面板
-│   │   ├── deposits/   # 押金管理
 │   │   ├── entities/   # 数据实体
-│   │   ├── expenses/   # 费用录入
 │   │   ├── occupancies/# 入住管理
+│   │   ├── rbac/       # 角色权限
 │   │   ├── rooms/      # 宿舍管理
-│   │   ├── students/   # 学生管理
-│   │   └── tenants/    # 租户管理
+│   │   └── students/   # 学生管理
 │   └── .env.example    # 环境配置模板
-├── frontend/           # 前端 React 应用
+├── apps/admin/         # 前端 React 应用
 │   └── src/
 │       ├── api/        # API 请求封装
+│       ├── components/ # 通用组件
 │       ├── layouts/    # 布局组件
 │       └── pages/      # 页面组件
-├── docker-compose.yml  # Docker 编排配置
+├── packages/           # 共享配置包
 └── 技术文档.md          # 详细技术文档
 ```
 
 ## 环境配置
 
-复制 `backend/.env.example` 为 `backend/.env`，按需修改：
+复制 `apps/server/.env.example` 为 `apps/server/.env`，按需修改：
 
 | 配置项 | 说明 | 默认值 |
 |--------|------|--------|
-| `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,45 @@
   },
   "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",
+    "react-syntax-highlighter": "^16.1.1",
+    "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,15 @@
 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 ScrollToTop from './components/ScrollToTop';
 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 +44,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 +62,20 @@ 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>
+          <ScrollToTop />
           <Suspense
             fallback={
               <div style={{ minHeight: '40vh', display: 'grid', placeItems: 'center' }}>
@@ -330,8 +345,9 @@ const App: React.FC = () => {
               </Route>
             </Routes>
           </Suspense>
-        </BrowserRouter>
-      </AntdApp>
+          </BrowserRouter>
+        </AntdApp>
+      </XProvider>
     </ConfigProvider>
   );
 };

apps/admin/src/api/imports.ts

@@ -0,0 +1,84 @@
+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>>;
+    /** 上传进度回调（0-100） */
+    onProgress?: (percent: number) => void;
+  },
+): 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, {
+    onUploadProgress: (event) => {
+      if (!options.onProgress || !event.total) return;
+      options.onProgress(Math.min(Math.round((event.loaded / event.total) * 100), 100));
+    },
+  });
+  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,4 +1,6 @@
 import axios, { type AxiosRequestConfig } from 'axios';
+import { usePermissionStore } from '../store/permission/permissionStore';
+import { useUserStore } from '../store/user/userStore';
 
 const instance = axios.create({
   baseURL: '/api',
@@ -6,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}`;
   }
@@ -19,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');
-      localStorage.removeItem('permissions');
+      useUserStore.getState().logout();
+      usePermissionStore.getState().clearPermissions();
       window.location.href = '/login';
     }
     if (err.response?.status === 403) {

apps/admin/src/api/queryClient.ts

@@ -0,0 +1,20 @@
+import { QueryClient } from '@tanstack/react-query';
+
+/**
+ * 全局 QueryClient：统一缓存/重试策略。
+ * - retry 1：接口失败最多重试 1 次，避免瞬时错误直接白屏
+ * - staleTime 30s：30 秒内重复请求走缓存
+ * - gcTime 5min：不活跃缓存 5 分钟后回收
+ * - refetchOnWindowFocus false：切回窗口不自动全量刷新，
+ *   保活页面由 useVisibleRefetch 按需刷新，避免重复请求
+ */
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: 1,
+      staleTime: 30_000,
+      gcTime: 5 * 60_000,
+      refetchOnWindowFocus: false,
+    },
+  },
+});

apps/admin/src/api/queryKeys.ts

@@ -0,0 +1,145 @@
+/**
+ * 统一 QueryKey 工厂。
+ *
+ * 每个模块一个命名空间，key 由工厂函数生成：
+ * - 避免散落字符串字面量导致拼写不一致、缓存串扰
+ * - invalidate / refetch / prefetch 与 useQuery 使用同一来源，不会对不上
+ *
+ * 约定：
+ * - `all` 是该模块的「根 key」，用于整体失效（invalidateQueries 会匹配前缀）
+ * - 列表 key 按过滤条件展开；详情/子资源用固定段 + 参数
+ */
+export const queryKeys = {
+  students: {
+    all: ['students'] as const,
+    list: (filters: {
+      search?: string;
+      status?: string;
+      archived?: boolean;
+      organizationId?: number;
+      classId?: number;
+      teacherId?: number;
+    }) => ['students', filters] as const,
+    organizations: (canView: boolean) => ['students', 'organizations', canView] as const,
+    filterLookups: () => ['students', 'filter-lookups'] as const,
+  },
+  classes: {
+    all: ['classes'] as const,
+    list: (filters: { status?: string; type?: string; archived?: boolean }) =>
+      ['classes', filters] as const,
+    detail: (id: number) => ['classes', 'detail', id] as const,
+    schedule: (id: number, dateRange: unknown) => ['classes', 'schedule', id, dateRange] as const,
+    attendanceSummary: (id: number, dateRange: unknown) =>
+      ['classes', 'attendance-summary', id, dateRange] as const,
+  },
+  classSchedules: {
+    all: ['class-schedules'] as const,
+    list: (params: { startDate?: string; endDate?: string; classroomIds?: unknown[] }) =>
+      ['class-schedules', params] as const,
+  },
+  classrooms: {
+    all: ['classrooms'] as const,
+    list: (archived: boolean) => ['classrooms', archived] as const,
+  },
+  classroomRentals: {
+    all: ['classroom-rentals'] as const,
+    list: (month?: string) => ['classroom-rentals', month] as const,
+    schedule: (year: number, month: number) =>
+      ['classroom-rentals', 'schedule', year, month] as const,
+    meta: () => ['classroom-rentals', 'meta'] as const,
+  },
+  organizations: {
+    all: ['organizations'] as const,
+    list: () => ['organizations'] as const,
+    options: () => ['organizations', 'options'] as const,
+  },
+  rbac: {
+    all: ['rbac'] as const,
+    users: (archived: boolean) => ['rbac', 'users', archived] as const,
+    allUsers: () => ['rbac', 'users', 'all'] as const,
+    teachers: (params: { page: number; pageSize: number; search?: string }) =>
+      ['rbac', 'teachers', params] as const,
+    teacherWorkspace: () => ['rbac', 'teacher-workspace'] as const,
+    roles: () => ['rbac', 'roles'] as const,
+    permissionTree: () => ['rbac', 'roles', 'permission-tree'] as const,
+    permissionsTree: () => ['rbac', 'permissions', 'tree'] as const,
+  },
+  expenses: {
+    all: ['expenses'] as const,
+    list: (archived: boolean) => ['expenses', archived ? 'archived' : 'active'] as const,
+  },
+  expenseTypes: {
+    map: () => ['expense-types', 'map'] as const,
+  },
+  expenseLookups: {
+    all: ['expense-lookups'] as const,
+  },
+  bills: {
+    all: ['bills'] as const,
+    list: (filters: { status?: string; expenseType?: string }) => ['bills', filters] as const,
+  },
+  wallets: {
+    all: ['wallets'] as const,
+    list: (params: { keyword?: string; debtOnly?: boolean; roomType?: string }) =>
+      ['wallets', params] as const,
+    transactions: (studentId: number) => ['wallets', 'transactions', studentId] as const,
+    roomTypes: () => ['wallets', 'room-types'] as const,
+  },
+  deposits: {
+    all: ['deposits'] as const,
+    list: () => ['deposits'] as const,
+    eligible: (roomType?: string) => ['deposits', 'eligible', roomType] as const,
+  },
+  occupancies: {
+    all: ['occupancies'] as const,
+    list: (params: { viewMode?: string; dateRange?: unknown }) => ['occupancies', params] as const,
+  },
+  rooms: {
+    all: ['rooms'] as const,
+    overview: (archived: boolean) => ['rooms', 'overview', archived] as const,
+    visual: (params: { historical: boolean; asOf?: unknown }) =>
+      ['rooms', 'visual', params] as const,
+  },
+  exams: {
+    all: ['exams'] as const,
+    detail: (id: number) => ['exams', 'detail', id] as const,
+    classes: () => ['exams', 'classes'] as const,
+  },
+  operationLogs: {
+    all: ['operation-logs'] as const,
+    list: (params: { page: number; pageSize: number; module?: string; dateRange?: unknown }) =>
+      ['operation-logs', params] as const,
+  },
+  attendance: {
+    all: ['attendance'] as const,
+    workspace: () => ['attendance', 'workspace'] as const,
+    syncStatus: () => ['attendance', 'sync-status'] as const,
+    schedules: (classId: number, date: string) => ['attendance', 'schedules', classId, date] as const,
+    meta: {
+      periods: () => ['attendance', 'meta', 'periods'] as const,
+      classes: () => ['attendance', 'meta', 'classes'] as const,
+      alerts: () => ['attendance', 'meta', 'alerts'] as const,
+    },
+  },
+  attendanceDevices: {
+    all: ['attendance-devices'] as const,
+  },
+  dashboard: {
+    all: ['dashboard'] as const,
+    summary: (period: unknown) => ['dashboard', period] as const,
+  },
+  integration: {
+    config: () => ['integration', 'config'] as const,
+  },
+  sync: {
+    jinshujuRules: () => ['sync', 'jinshuju', 'rules'] as const,
+  },
+  archive: {
+    detail: (studentId: number) => ['archive', studentId] as const,
+  },
+  ai: {
+    config: () => ['ai', 'config'] as const,
+  },
+} as const;
+
+export type QueryKeys = typeof queryKeys;

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,346 @@
+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().nullable().optional(),
+    status: z.string().nullable().optional(),
+  })
+  .passthrough();
+
+export const classroomsSchema = z.array(classroomSchema);
+
+/** 学生 */
+export const studentSchema = z
+  .object({
+    id: z.number(),
+    name: z.string(),
+    studentNo: z.string().nullable().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({
+    id: z.number(),
+    name: z.string().nullable().optional(),
+    studentNo: z.string().nullable().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 expenseStudentLookupSchema = z
+  .object({
+    id: z.number(),
+    name: z.string().nullable().optional(),
+    studentNo: z.string().nullable().optional(),
+  })
+  .passthrough();
+
+export const expenseStudentLookupsSchema = z.array(expenseStudentLookupSchema);
+
+export const expenseRoomsListSchema = z.array(z.record(z.string(), z.unknown()));
+
+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.integration.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { ganttRoomsSchema } from './dashboard';
+
+describe('ganttRoomsSchema 接口校验', () => {
+  const validPayload = [
+    {
+      roomNumber: 'A101',
+      occupancies: [
+        {
+          studentName: '张三',
+          studentId: 3,
+          checkInDate: '2026-05-01',
+          checkOutDate: null,
+          billingStartDate: '2026-05-01',
+          billingEndDate: null,
+        },
+      ],
+    },
+  ];
+
+  it('接受合法的甘特图数据（studentId 为数字）', () => {
+    expect(ganttRoomsSchema.safeParse(validPayload).success).toBe(true);
+  });
+
+  it('拒绝缺少 checkInDate 的入住记录', () => {
+    const payload = [
+      {
+        roomNumber: 'A101',
+        occupancies: [{ studentName: '张三', checkOutDate: null }],
+      },
+    ];
+    expect(ganttRoomsSchema.safeParse(payload).success).toBe(false);
+  });
+
+  it('拒绝缺少 studentName 的入住记录', () => {
+    const payload = [
+      {
+        roomNumber: 'A101',
+        occupancies: [{ checkInDate: '2026-05-01', checkOutDate: null }],
+      },
+    ];
+    expect(ganttRoomsSchema.safeParse(payload).success).toBe(false);
+  });
+});

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

@@ -0,0 +1,91 @@
+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: 教室 id → 日期 → 单条排课/租赁记录（对象，非数组）
+    matrix: z.record(z.string(), z.record(z.string(), 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.object({
+          studentName: z.string(),
+          studentId: z.union([z.string(), z.number()]).optional(),
+          checkInDate: z.string(),
+          checkOutDate: z.string().nullable(),
+          billingStartDate: z.string().optional(),
+          billingEndDate: z.string().nullable().optional(),
+        }),
+      ),
+    }),
+);
+
+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,71 @@
+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 importRunSettingsSchema = z
+  .object({
+    mapping: z.record(z.string(), z.record(z.string(), z.string())).optional(),
+    organization: z.string().nullable().optional(),
+    updateExisting: z.boolean().optional(),
+    duplicatePolicy: z.enum(['error', 'skip']).optional(),
+    skipUnmatched: z.boolean().optional(),
+  })
+  .passthrough()
+  .nullable()
+  .optional();
+
+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),
+    settings: importRunSettingsSchema,
+  })
+  .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

@@ -0,0 +1,67 @@
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+import PermissionButton from '../components/PermissionButton';
+import { usePermissionStore } from '../store/permission/permissionStore';
+
+let container: HTMLDivElement | null = null;
+let root: ReturnType<typeof createRoot> | null = null;
+
+beforeAll(() => {
+  (
+    globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }
+  ).IS_REACT_ACT_ENVIRONMENT = true;
+});
+
+async function renderPermissionButton() {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+  await act(async () => {
+    root?.render(<PermissionButton permission="student:edit">编辑学生</PermissionButton>);
+  });
+}
+
+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;
+  usePermissionStore.getState().clearPermissions();
+});
+
+describe('permission state', () => {
+  it('ignores cached localStorage permissions until profile verification succeeds', async () => {
+    localStorage.setItem('permissions', JSON.stringify(['student:edit']));
+    usePermissionStore.getState().beginPermissionVerification();
+
+    expect(readPermissionState()).toEqual({ permissions: [], status: 'loading' });
+    await renderPermissionButton();
+    expect(container?.textContent).not.toContain('编辑学生');
+  });
+
+  it('renders permission actions only after verified permissions are written', async () => {
+    usePermissionStore.getState().beginPermissionVerification();
+    await renderPermissionButton();
+    expect(container?.textContent).not.toContain('编辑学生');
+
+    await act(async () => usePermissionStore.getState().writePermissions(['student:edit']));
+    expect(container?.textContent).toContain('编辑学生');
+  });
+
+  it('keeps verified permissions while profile verification refreshes in the background', async () => {
+    usePermissionStore.getState().writePermissions(['student:edit']);
+    usePermissionStore.getState().beginPermissionVerification();
+
+    expect(readPermissionState()).toEqual({ permissions: ['student:edit'], status: 'ready' });
+    await renderPermissionButton();
+    expect(container?.textContent).toContain('编辑学生');
+  });
+});

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

@@ -1,17 +0,0 @@
-export const PERMISSIONS_UPDATED_EVENT = 'permissions-updated';
-
-export function readPermissions(): string[] {
-  try {
-    const value = JSON.parse(localStorage.getItem('permissions') || '[]');
-    return Array.isArray(value)
-      ? value.filter((item): item is string => typeof item === 'string')
-      : [];
-  } catch {
-    return [];
-  }
-}
-
-export function writePermissions(permissions: string[]): void {
-  localStorage.setItem('permissions', JSON.stringify([...new Set(permissions)]));
-  window.dispatchEvent(new Event(PERMISSIONS_UPDATED_EVENT));
-}

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,240 @@
+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" />}
+      {!loadingList && !selectionMode && conversationCount === 0 ? (
+        <div className="ai-chat-sidebar__empty">
+          <Typography.Text type="secondary">暂无会话</Typography.Text>
+          <Typography.Text type="secondary" style={{ fontSize: 12 }}>
+            点击「新对话」开始提问
+          </Typography.Text>
+        </div>
+      ) : null}
+      <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,589 @@
+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 { useUserStore } from '../../store/user/userStore';
+import { usePermissionStore } from '../../store/permission/permissionStore';
+import { aiChatApi, conversationStreamUrl } from './api';
+import { GongxueAiChatProvider } from './provider';
+import { welcomeDescription, workflowPromptExamples } from './welcomeCopy';
+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 user = useUserStore((state) => state.user);
+  const permissions = usePermissionStore((state) => state.permissions);
+  const screens = Grid.useBreakpoint();
+  const isMobile = !screens.sm;
+  const [loadingList, setLoadingList] = useState(false);
+  // 断点首帧可能尚未解析（isMobile 误判为 true），桌面端默认展开会话侧边栏，
+  // 移动端通过 effectiveSidebarOpen 统一隐藏。
+  const [sidebarOpen, setSidebarOpen] = useState(true);
+  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) => {
+      const doSwitch = () => {
+        discardPendingAttachments();
+        if (isMobile) setSidebarOpen(false);
+        setActiveConversationKey(key);
+      };
+      // 有待发送的附件时先确认，避免静默删除已上传文件
+      if (uploadItems.length > 0) {
+        modal.confirm({
+          title: '切换会话将丢弃未发送的附件',
+          content: `当前有 ${uploadItems.length} 个已上传但未发送的附件，切换会话后将被删除，此操作不可恢复。`,
+          okText: '切换并丢弃',
+          okButtonProps: { danger: true },
+          cancelText: '留在当前会话',
+          onOk: doSwitch,
+        });
+        return;
+      }
+      doSwitch();
+    },
+    [
+      discardPendingAttachments,
+      isMobile,
+      modal,
+      setActiveConversationKey,
+      uploadItems.length,
+    ],
+  );
+
+  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, modal],
+  );
+
+  /** 删除单个会话时中止请求并清理会话运行时状态 */
+  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,
+        modal,
+      ],
+  );
+
+  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,
+      modal,
+    ]);
+
+  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 ||
+                    welcomeDescription(user?.roles ?? [], permissions)
+                  }
+                />
+                <Prompts
+                  title="你可以这样问"
+                  items={[
+                    ...promptItems,
+                    ...workflowPromptExamples(user?.roles ?? [], permissions).map(
+                      (item, index) => ({
+                        key: `workflow-${index}`,
+                        label: item.label,
+                        description: item.description,
+                      }),
+                    ),
+                  ]}
+                  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,412 @@
+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 { message } from '../../ui/app-message';
+import { DynamicChart } from './DynamicChart';
+import { DynamicForm } from './DynamicForm';
+import { DynamicReview } from './DynamicReview';
+import { deriveCharts, deriveForms, deriveReviews } from './uiArtifacts';
+import { ArtifactErrorBoundary } from './ArtifactErrorBoundary';
+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_chart: '生成图表',
+  start_import_wizard: '生成导入向导',
+  create_student: '创建学生',
+  search_exams: '查询考试',
+  search_schedules: '查询课表',
+  search_deposits: '查询押金',
+  search_expenses: '查询费用',
+  search_classrooms: '查询教室',
+  search_classroom_rentals: '查询教室租用',
+  get_sync_status: '查询同步状态',
+  get_business_context: '读取业务流程',
+  get_entity_schema: '读取实体字典',
+  get_pending_tasks: '查询业务待办',
+};
+
+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);
+}
+
+/** 打开附件，失败时给出明确提示（避免「点了没反应」） */
+async function handleOpenAttachment(attachment: AiAttachment): Promise<void> {
+  try {
+    await openAttachment(attachment);
+  } catch (error: unknown) {
+    message.error(error instanceof Error ? error.message : '附件打开失败，请重试');
+  }
+}
+
+/** 打出来源链接，失败时给出明确提示 */
+async function handleOpenSource(item: { url?: string }): Promise<void> {
+  try {
+    await openSourceUrl(item);
+  } catch (error: unknown) {
+    message.error(error instanceof Error ? error.message : '来源打开失败，请重试');
+  }
+}
+
+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;
+  // 统一 artifact 优先，历史消息（仅 legacy 字段）回退
+  const forms = deriveForms(message).length > 0 ? deriveForms(message) : (message.forms ?? []);
+  const reviews =
+    deriveReviews(message).length > 0 ? deriveReviews(message) : (message.reviews ?? []);
+  const charts = deriveCharts(message).length > 0 ? deriveCharts(message) : (message.charts ?? []);
+  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 handleOpenAttachment(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 handleOpenSource(item as { url?: string })}
+        />
+      )}
+      {(forms ?? []).map((form) => (
+        <ArtifactErrorBoundary key={form.id} title="表单">
+          <DynamicForm
+            form={form}
+            disabled={streaming}
+            onSubmit={(values) => onSubmitForm?.(form, values)}
+          />
+        </ArtifactErrorBoundary>
+      ))}
+      {(reviews ?? []).map((review: AiReviewSchema) => (
+        <ArtifactErrorBoundary key={review.id} title="导入预览">
+          <DynamicReview
+            review={review}
+            messageId={typeof message.id === 'number' ? message.id : undefined}
+            disabled={streaming}
+            onSubmit={(reviewId) => onSubmitReview?.(reviewId, review.title)}
+            onConfirmStep={onConfirmReviewStep}
+            onConfirmGroup={onConfirmReviewGroup}
+          />
+        </ArtifactErrorBoundary>
+      ))}
+      {(charts ?? []).map((chart: AiChartSchema) => (
+        <ArtifactErrorBoundary key={chart.id} title="图表">
+          <DynamicChart chart={chart} />
+        </ArtifactErrorBoundary>
+      ))}
+      {message.error && <Alert type="error" showIcon title={message.error} />}
+      {message.cancelled && <Typography.Text type="secondary">回答已停止</Typography.Text>}
+    </Space>
+  );
+};

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

@@ -0,0 +1,47 @@
+import React from 'react';
+import { Alert } from 'antd';
+
+interface ArtifactErrorBoundaryProps {
+  children: React.ReactNode;
+  /** 制品标题（用于错误提示文案） */
+  title?: string;
+}
+
+interface ArtifactErrorBoundaryState {
+  hasError: boolean;
+}
+
+/**
+ * A2UI 制品（表单/审查卡/图表）渲染错误兜底：单个制品渲染失败只降级为
+ * 错误占位卡片，不影响同气泡内其他消息与制品。
+ */
+export class ArtifactErrorBoundary extends React.Component<
+  ArtifactErrorBoundaryProps,
+  ArtifactErrorBoundaryState
+> {
+  state: ArtifactErrorBoundaryState = { hasError: false };
+
+  static getDerivedStateFromError(): ArtifactErrorBoundaryState {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo): void {
+    console.error('[ArtifactErrorBoundary] 制品渲染异常:', error, info.componentStack);
+  }
+
+  render(): React.ReactNode {
+    if (this.state.hasError) {
+      return (
+        <Alert
+          type="warning"
+          showIcon
+          title={this.props.title ? `${this.props.title}渲染失败` : '此内容渲染失败'}
+          description="请让 AI 重新生成，或刷新后重试。"
+        />
+      );
+    }
+    return this.props.children;
+  }
+}
+
+export default ArtifactErrorBoundary;

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

@@ -0,0 +1,321 @@
+import React, { lazy, Suspense, useEffect, useMemo, useState } from 'react';
+import { saveAs } from 'file-saver';
+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';
+import { useXCardSurface } from './useSubmissionState';
+
+// 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 }) => {
+  // 空/无数据时先短路，避免 buildOption 在空数据集上执行
+  const hasData = !!chart && !!chart.rows && chart.rows.length > 0;
+  const option = useMemo<EChartsOption>(
+    () => (chart && hasData ? buildOption(chart) : {}),
+    [chart, hasData],
+  );
+  const [instance, setInstance] = useState<EChartsType | null>(null);
+  if (!chart) return null;
+  // 空数据集：渲染明确占位，而不是一张空白图
+  if (!hasData) {
+    return (
+      <div className="ai-chat-chart-card">
+        <div className="ai-chat-chart-card__header">
+          <Typography.Text strong>{chart.title}</Typography.Text>
+          <Tag color="blue">{CHART_TYPE_LABELS[chart.chartType] ?? chart.chartType}</Tag>
+        </div>
+        <div
+          style={{
+            height: 120,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+          }}
+        >
+          <Typography.Text type="secondary">暂无数据</Typography.Text>
+        </div>
+      </div>
+    );
+  }
+
+  const downloadImage = () => {
+    if (!instance) return;
+    const url = instance.getDataURL({
+      type: 'png',
+      pixelRatio: 2,
+      backgroundColor: '#fff',
+    });
+    saveAs(url, `${chart.title || '图表'}.png`);
+  };
+
+  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 sid = surfaceId(chart.id);
+  const { commands, pushCommands } = useXCardSurface(sid);
+
+  useEffect(() => {
+    const cmds: XAgentCommand_v0_9[] = [
+      {
+        version: 'v0.9',
+        createSurface: { surfaceId: sid, catalogId: CHART_CATALOG_ID },
+      },
+      {
+        version: 'v0.9',
+        updateDataModel: {
+          surfaceId: sid,
+          path: '/chart',
+          value: chart,
+        },
+      },
+      {
+        version: 'v0.9',
+        updateComponents: {
+          surfaceId: sid,
+          components: [
+            {
+              id: 'root',
+              component: 'ChartPreview',
+              chart: { path: '/chart' },
+            },
+          ],
+        },
+      },
+    ];
+    pushCommands(cmds);
+  }, [chart, pushCommands, sid]);
+
+  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,241 @@
+import React, { useEffect, useMemo } 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';
+import { useSubmissionState, useXCardSurface } from './useSubmissionState';
+
+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 expired = form.status === 'expired';
+
+  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>
+      )}
+      {expired ? (
+        <Alert type="warning" showIcon title="表单已失效" description="此表单已被新的请求替代，请让助手重新生成。" />
+      ) : finished ? (
+        <Alert type="success" showIcon title="已提交，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 sid = surfaceId(form.id);
+  const { submitting, submitted, error, run } = useSubmissionState();
+  const { commands, pushCommands } = useXCardSurface(sid);
+
+  useEffect(() => {
+    const cmds: XAgentCommand_v0_9[] = [
+      {
+        version: 'v0.9',
+        createSurface: { surfaceId: sid, catalogId: FORM_CATALOG_ID },
+      },
+      {
+        version: 'v0.9',
+        updateDataModel: {
+          surfaceId: sid,
+          path: '/form',
+          value: { ...form, submitting, submitted, error },
+        },
+      },
+      {
+        version: 'v0.9',
+        updateComponents: {
+          surfaceId: sid,
+          components: [
+            {
+              id: 'root',
+              component: 'FormPreview',
+              form: { path: '/form' },
+              disabled: Boolean(disabled),
+            },
+          ],
+        },
+      },
+    ];
+    pushCommands(cmds);
+  }, [disabled, error, form, pushCommands, sid, submitted, submitting]);
+
+  const handleSubmit = (values: Record<string, unknown>) => {
+    void run(async () => {
+      await onSubmit(values);
+    });
+  };
+
+  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,596 @@
+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 { useXCardSurface } from './useSubmissionState';
+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
+          title="此导入预览已被新的预览替代，已失效"
+          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 title="本步导入失败，可重试" />
+              )}
+              {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 title="已确认导入，数据已入库" />}
+      {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 sid = surfaceId(localReview.id);
+  const { commands, pushCommands } = useXCardSurface(sid);
+
+  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 cmds: XAgentCommand_v0_9[] = [
+      {
+        version: 'v0.9',
+        createSurface: { surfaceId: sid, catalogId: REVIEW_CATALOG_ID },
+      },
+      {
+        version: 'v0.9',
+        updateDataModel: {
+          surfaceId: sid,
+          path: '/review',
+          value: {
+            ...localReview,
+            submitting,
+            activeKey,
+            activeType,
+            submittingKey,
+            submittingGroup,
+            error,
+          },
+        },
+      },
+      {
+        version: 'v0.9',
+        updateComponents: {
+          surfaceId: sid,
+          components: [
+            {
+              id: 'root',
+              component: 'ReviewPreview',
+              review: { path: '/review' },
+              disabled: Boolean(disabled),
+            },
+          ],
+        },
+      },
+    ];
+    pushCommands(cmds);
+  }, [
+    activeKey,
+    activeType,
+    disabled,
+    error,
+    localReview,
+    pushCommands,
+    sid,
+    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,45 @@
+import { useEffect, useRef, useState } from 'react';
+import { useIsMounted } from 'usehooks-ts';
+
+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);
+  const isMounted = useIsMounted();
+
+  useEffect(() => {
+    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 (isMounted()) {
+          const doc = new DOMParser().parseFromString(svg, 'image/svg+xml');
+          container.replaceChildren(doc.documentElement);
+          setError(null);
+        }
+      } catch (e) {
+        if (isMounted()) {
+          setError(e instanceof Error ? e.message : '图表渲染失败');
+        }
+      }
+    })();
+  }, [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,91 @@
+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,
+    onProgress?: (percent: number) => void,
+  ): Promise<AiAttachment> => {
+    const form = new FormData();
+    form.append('file', file);
+    return (
+      await api.post<AiApiResponse<AiAttachment>>('/ai/chat/attachments', form, {
+        timeout: 120_000,
+        onUploadProgress: (event) => {
+          if (!onProgress || !event.total) return;
+          onProgress(Math.min(Math.round((event.loaded / event.total) * 100), 100));
+        },
+      })
+    ).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,553 @@
+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 { ArtifactErrorBoundary } from './ArtifactErrorBoundary';
+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 expired A2UI form as disabled without submit action', async () => {
+    let submitted = false;
+    const el = document.createElement('div');
+    container = el;
+    document.body.appendChild(el);
+    root = createRoot(el);
+
+    await act(async () => {
+      root?.render(
+        <DynamicForm
+          form={{
+            id: 'form-expired',
+            title: '已失效的表单',
+            status: 'expired',
+            fields: [{ name: 'name', label: '姓名', type: 'input', required: true }],
+          }}
+          onSubmit={() => {
+            submitted = true;
+          }}
+        />,
+      );
+    });
+
+    expect(el.textContent).toContain('已失效');
+    expect(el.querySelector('button[type="submit"]')).toBeNull();
+    await act(async () => {
+      const buttons = Array.from(el.querySelectorAll('button'));
+      buttons.forEach((button) => button.click());
+    });
+    expect(submitted).toBe(false);
+  });
+
+  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();
+  });
+
+  it('renders an empty-data placeholder instead of a blank chart', async () => {
+    const chart: AiChartSchema = {
+      id: 'chart-empty',
+      title: '空图表',
+      chartType: 'bar',
+      columns: [{ key: 'name', title: '名称' }],
+      rows: [],
+    };
+    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('canvas')).toBeNull();
+  });
+
+  it('degrades a single failing artifact to an error card without crashing the bubble', async () => {
+    const Bomb: React.FC = () => {
+      throw new Error('boom');
+    };
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+
+    // 用无错误边界的兄弟节点 + 错误边界内的炸弹组件验证隔离
+    await act(async () => {
+      root?.render(
+        <div>
+          <div className="neighbor">正常内容</div>
+          <ArtifactErrorBoundary title="表单">
+            <Bomb />
+          </ArtifactErrorBoundary>
+        </div>,
+      );
+    });
+
+    expect(container.querySelector('.neighbor')?.textContent).toContain('正常内容');
+    expect(container.textContent).toContain('表单渲染失败');
+  });
+});

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

@@ -0,0 +1,195 @@
+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 uiArtifacts from message metadata (统一协议)', () => {
+    const mapped = mapHistoryMessage({
+      id: 8,
+      role: 'assistant',
+      content: '请处理',
+      reasoningContent: null,
+      status: 'completed',
+      errorCode: null,
+      createdAt: '2026-07-23T00:00:00.000Z',
+      metadata: {
+        uiArtifacts: [
+          {
+            id: 'form-10',
+            type: 'form',
+            status: 'submitted',
+            messageId: 8,
+            conversationId: 3,
+            payload: {
+              id: 'form-10',
+              title: '新增学生',
+              status: 'submitted',
+              fields: [],
+            },
+          },
+          {
+            id: 'review-10',
+            type: 'review',
+            status: 'expired',
+            messageId: 8,
+            conversationId: 3,
+            payload: {
+              id: 'review-10',
+              title: '旧预览',
+              status: 'expired',
+              sections: [],
+            },
+          },
+        ],
+      },
+    });
+
+    expect(mapped.message.uiArtifacts).toHaveLength(2);
+    expect(mapped.message.uiArtifacts?.[0].payload).toMatchObject({
+      id: 'form-10',
+      status: 'submitted',
+    });
+    expect(mapped.message.uiArtifacts?.[1].payload).toMatchObject({
+      id: 'review-10',
+      status: 'expired',
+    });
+  });
+
+  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,91 @@
+import type { MessageInfo } from '@ant-design/x-sdk';
+import type {
+  AiChatMessage,
+  AiChatMessageStatus,
+  AiChartSchema,
+  AiArtifactSchema,
+  AiFormSchema,
+  AiMessageRecord,
+  AiReviewSchema,
+  AiToolRun,
+} from './types';
+import { mergeArtifactIntoMessage } from './uiArtifacts';
+
+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];
+}
+
+function historyArtifacts(record: AiMessageRecord) {
+  const artifacts = record.metadata?.uiArtifacts;
+  if (!Array.isArray(artifacts)) return undefined;
+  return artifacts.filter(
+    (item): item is AiArtifactSchema =>
+      Boolean(item) && typeof item === 'object' && typeof (item as AiArtifactSchema).id === 'string',
+  );
+}
+
+export function mapHistoryMessage(record: AiMessageRecord): MessageInfo<AiChatMessage> {
+  const artifacts = historyArtifacts(record);
+  const baseMessage = {
+    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',
+  };
+  if (artifacts) {
+    for (const artifact of artifacts) {
+      mergeArtifactIntoMessage(baseMessage as AiChatMessage, artifact);
+    }
+  }
+  return {
+    id: record.id,
+    status: mapStatus(record),
+    message: baseMessage as AiChatMessage,
+  };
+}

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

@@ -0,0 +1,432 @@
+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.artifact events into uiArtifacts by id', () => {
+    let message = reduceAiSseMessage(undefined, {
+      event: 'ui.artifact',
+      data: JSON.stringify({
+        messageId: 12,
+        artifact: {
+          id: 'form-1',
+          type: 'form',
+          status: 'pending',
+          messageId: 12,
+          conversationId: 3,
+          payload: { id: 'form-1', title: '新增学生', fields: [] },
+        },
+      }),
+    });
+    message = reduceAiSseMessage(message, {
+      event: 'ui.artifact',
+      data: JSON.stringify({
+        messageId: 12,
+        artifact: {
+          id: 'review-1',
+          type: 'review',
+          status: 'expired',
+          messageId: 12,
+          conversationId: 3,
+          payload: { id: 'review-1', title: '旧导入预览', status: 'expired', sections: [] },
+        },
+      }),
+    });
+
+    expect(message.uiArtifacts).toHaveLength(2);
+    expect(message.uiArtifacts?.[0].payload).toMatchObject({ id: 'form-1', title: '新增学生' });
+    expect(message.uiArtifacts?.[1].payload).toMatchObject({ id: 'review-1', status: 'expired' });
+  });
+
+
+  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('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('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 ui.artifact targeting another message to the external handler', () => {
+    const provider = new GongxueAiChatProvider('http://x/api/ai/chat/conversations/3/stream');
+    const onExternalArtifact = vi.fn();
+    provider.onExternalArtifact = onExternalArtifact;
+    const artifact = {
+      id: 'artifact-1',
+      type: 'form',
+      status: 'submitted',
+      messageId: 12,
+      payload: { id: 'form-1', title: '批量导入', status: 'submitted' },
+    };
+    const origin = {
+      id: 13,
+      role: 'assistant' as const,
+      content: '生成中',
+      reasoningContent: '',
+      toolRuns: [],
+      attachments: [],
+      uiArtifacts: [],
+    };
+    const next = provider.transformMessage({
+      originMessage: origin,
+      chunk: { event: 'ui.artifact', data: JSON.stringify({ messageId: 12, artifact }) },
+      status: 'updating',
+      chunks: [],
+      responseHeaders: {} as Headers,
+    });
+
+    expect(onExternalArtifact).toHaveBeenCalledWith(12, artifact);
+    expect(next).toBe(origin);
+    expect(next.uiArtifacts ?? []).toHaveLength(0);
+  });
+
+  it('routes ui.artifact without an origin message to the external handler', () => {
+    const provider = new GongxueAiChatProvider('http://x/api/ai/chat/conversations/3/stream');
+    const onExternalArtifact = vi.fn();
+    provider.onExternalArtifact = onExternalArtifact;
+    const next = provider.transformMessage({
+      chunk: {
+        event: 'ui.artifact',
+        data: JSON.stringify({
+          messageId: 12,
+          artifact: {
+            id: 'artifact-1',
+            type: 'review',
+            status: 'submitted',
+            messageId: 12,
+            payload: { id: 'review-1', title: '批量导入', status: 'submitted', sections: [] },
+          },
+        }),
+      },
+      status: 'updating',
+      chunks: [],
+      responseHeaders: {} as Headers,
+    });
+
+    expect(onExternalArtifact).toHaveBeenCalledWith(
+      12,
+      expect.objectContaining({ id: 'artifact-1' }),
+    );
+    expect(next.uiArtifacts ?? []).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,196 @@
+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 { AiArtifactSchema, AiChatInput, AiChatMessage, AiReviewSchema, AiSseChunk } from './types';
+import { emptyAssistant, parseSsePayload, reduceAiSseMessage } from './sseReducer';
+
+export { parseSsePayload, reduceAiSseMessage };
+
+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) {
+    // 提示由登录页读取展示：直接弹 toast 会被跳转销毁
+    sessionStorage.setItem('login_expired_hint', '1');
+    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;
+  onExternalArtifact?: (messageId: number, artifact: AiArtifactSchema) => 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.artifact' &&
+      payload.artifact &&
+      typeof payload.messageId === 'number' &&
+      info.originMessage?.id !== payload.messageId
+    ) {
+      this.onExternalArtifact?.(payload.messageId, payload.artifact);
+      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/sseReducer.ts

@@ -0,0 +1,197 @@
+import type {
+  AiArtifactSchema,
+  AiAttachment,
+  AiChartSchema,
+  AiChatMessage,
+  AiFormSchema,
+  AiModelRetryInfo,
+  AiReviewSchema,
+  AiSseChunk,
+  AiToolRun,
+} from './types';
+import { mergeArtifactIntoMessage, mergeById } from './uiArtifacts';
+
+export 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;
+  artifact?: AiArtifactSchema;
+  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;
+}
+
+export function emptyAssistant(): AiChatMessage {
+  return {
+    role: 'assistant',
+    content: '',
+    reasoningContent: '',
+    toolRuns: [],
+    attachments: [],
+    forms: [],
+    uiArtifacts: [],
+  };
+}
+
+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'],
+): void {
+  if (typeof nested !== 'object' || nested === null) return;
+  // 历史消息兼容：老数据只有 metadata.a2uiForm/a2uiReview/a2uiChart，
+  // 恢复为 legacy 字段供渲染层在 uiArtifacts 为空时回退使用。
+  message.forms = mergeById<AiFormSchema>(
+    message.forms,
+    nested.metadata?.a2uiForm as AiFormSchema | undefined,
+  );
+  message.reviews = mergeById<AiReviewSchema>(
+    message.reviews,
+    nested.metadata?.a2uiReview as AiReviewSchema | undefined,
+  );
+  message.charts = mergeById<AiChartSchema>(
+    message.charts,
+    nested.metadata?.a2uiChart as AiChartSchema | AiChartSchema[] | undefined,
+  );
+  const artifacts = nested.metadata?.uiArtifacts;
+  if (Array.isArray(artifacts)) {
+    for (const artifact of artifacts) {
+      if (artifact && typeof artifact === 'object' && typeof artifact.id === 'string') {
+        mergeArtifactIntoMessage(message, artifact as AiArtifactSchema);
+      }
+    }
+  }
+  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);
+  } 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.artifact' && payload.artifact) {
+    // 统一 artifact 事件；legacy 列表由渲染层从 uiArtifacts 派生。
+    mergeArtifactIntoMessage(message, payload.artifact);
+  } 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);
+    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;
+}

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

@@ -0,0 +1,518 @@
+.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__empty {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  padding: 24px 16px;
+}
+
+.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-main .ai-chat-toolbar {
+  order: 0;
+}
+
+.ai-chat-main .ai-chat-messages {
+  order: 1;
+}
+
+.ai-chat-main .ai-chat-composer {
+  order: 2;
+}
+
+.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,243 @@
+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' | 'expired';
+}
+
+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 type AiArtifactType =
+  | 'form'
+  | 'review'
+  | 'chart'
+  | 'import_wizard';
+
+export type AiArtifactStatus = 'rendering' | 'pending' | 'submitted' | 'expired' | 'cancelled';
+
+export interface AiArtifactSchema<T = unknown> {
+  id: string;
+  type: AiArtifactType;
+  status: AiArtifactStatus;
+  messageId: number;
+  conversationId?: number;
+  payload: T;
+  createdAt?: string | null;
+  submittedAt?: string | null;
+  supersededBy?: string | null;
+}
+
+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[];
+  /** @deprecated 仅历史消息兼容读取（metadata.a2uiForm）；新数据统一走 uiArtifacts */
+  forms?: AiFormSchema[];
+  /** @deprecated 仅历史消息兼容读取（metadata.a2uiReview）；新数据统一走 uiArtifacts */
+  reviews?: AiReviewSchema[];
+  /** @deprecated 仅历史消息兼容读取（metadata.a2uiChart）；新数据统一走 uiArtifacts */
+  charts?: AiChartSchema[];
+  /** 统一 A2UI 制品协议（唯一事实源） */
+  uiArtifacts?: AiArtifactSchema[];
+  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/uiArtifacts.ts

@@ -0,0 +1,68 @@
+import type {
+  AiArtifactSchema,
+  AiChartSchema,
+  AiChatMessage,
+  AiFormSchema,
+  AiReviewSchema,
+} from './types';
+
+export 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;
+}
+
+/**
+ * 将统一 artifact 归入 uiArtifacts。
+ *
+ * 注意：不再派发到 legacy 列表（forms/reviews/charts）——渲染层从
+ * uiArtifacts 派生，legacy 字段仅保留给历史消息（metadata 中只有
+ * a2uiForm/a2uiReview/a2uiChart 的老数据）作兼容读取。
+ */
+export function mergeArtifactIntoMessage(
+  message: AiChatMessage,
+  artifact: AiArtifactSchema,
+): AiChatMessage {
+  message.uiArtifacts = mergeById<AiArtifactSchema>(message.uiArtifacts, artifact);
+  return message;
+}
+
+/**
+ * 从 uiArtifacts 派生 legacy 列表（渲染用）。
+ * 仅当 message 上没有显式 legacy 数据（历史消息）时，渲染层回退到 message.forms 等。
+ */
+export function deriveForms(message: AiChatMessage): AiFormSchema[] {
+  return (message.uiArtifacts ?? [])
+    .filter((artifact) => artifact.type === 'form')
+    .map((artifact) => artifact.payload)
+    .filter((payload): payload is AiFormSchema => Boolean(payload) && typeof payload === 'object');
+}
+
+export function deriveReviews(message: AiChatMessage): AiReviewSchema[] {
+  return (message.uiArtifacts ?? [])
+    .filter((artifact) => artifact.type === 'review')
+    .map((artifact) => artifact.payload)
+    .filter(
+      (payload): payload is AiReviewSchema => Boolean(payload) && typeof payload === 'object',
+    );
+}
+
+export function deriveCharts(message: AiChatMessage): AiChartSchema[] {
+  return (message.uiArtifacts ?? [])
+    .filter((artifact) => artifact.type === 'chart')
+    .map((artifact) => artifact.payload)
+    .filter((payload): payload is AiChartSchema => Boolean(payload) && typeof payload === 'object');
+}

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

@@ -0,0 +1,600 @@
+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 { mergeArtifactIntoMessage } from './uiArtifacts';
+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.onExternalArtifact = (messageId, artifact) => {
+      setMessage(messageId, (info) => ({
+        message: mergeArtifactIntoMessage(info.message, artifact),
+      }));
+    };
+  }, [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, modal],
+  );
+
+  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;
+
+      // 编辑旧消息会删除其后的全部消息并重新生成，需先告知用户
+      const index = messagesRef.current.findIndex((item) => item.id === messageInfo.id);
+      const followingCount = index >= 0 ? messagesRef.current.length - index - 1 : 0;
+      const doEdit = () => {
+        setMessage(messageInfo.id, (info) => ({
+          message: {
+            ...info.message,
+            content,
+            metadata: { ...info.message.metadata, edited: true },
+          },
+        }));
+        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,
+        });
+      };
+      if (followingCount > 0) {
+        modal.confirm({
+          title: '编辑消息将删除后续内容',
+          content: `编辑这条消息会删除其后的 ${followingCount} 条消息并重新生成回答，此操作不可恢复。`,
+          okText: '继续编辑',
+          cancelText: '取消',
+          onOk: doEdit,
+        });
+        return;
+      }
+      doEdit();
+    },
+    [
+      activeConversation?.lockedSkillKey,
+      activeId,
+      deepThinking,
+      modal,
+      removeMessage,
+      requestWithStatus,
+      setMessage,
+    ],
+  );
+
+  const submitForm = useCallback(
+    async (form: AiFormSchema, values: Record<string, unknown>): Promise<void> => {
+      if (!activeId) throw new Error('当前会话不可用，请稍后重试');
+      if (isRequesting) throw new Error('请等待当前 AI 回复完成后再提交表单');
+      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(
+    async (reviewId: string, reviewTitle?: string): Promise<void> => {
+      if (!activeId) throw new Error('当前会话不可用，请稍后重试');
+      if (isRequesting) throw new Error('请等待当前 AI 回复完成后再确认导入');
+      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, (percent) => {
+        options.onProgress?.({ percent });
+      });
+      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/AiChat/useSubmissionState.test.tsx

@@ -0,0 +1,161 @@
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, describe, expect, it } from 'vitest';
+import { useSubmissionState, useXCardSurface } from './useSubmissionState';
+
+// 项目未安装 @testing-library/react，用 createRoot + harness 组件暴露 hook API
+let container: HTMLDivElement | null = null;
+let root: ReturnType<typeof createRoot> | null = null;
+let api: ReturnType<typeof useSubmissionState> | null = null;
+let surface: ReturnType<typeof useXCardSurface> | null = null;
+let surfaceId = 'surface-test';
+
+function Harness() {
+  api = useSubmissionState();
+  surface = useXCardSurface(surfaceId);
+  return null;
+}
+
+function renderHarness(): void {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+  act(() => {
+    root?.render(<Harness />);
+  });
+}
+
+afterEach(async () => {
+  if (root) await act(async () => root?.unmount());
+  container?.remove();
+  root = null;
+  container = null;
+  api = null;
+  surface = null;
+  surfaceId = 'surface-test';
+});
+
+describe('useSubmissionState', () => {
+  it('tracks submitting during the task and succeeds afterwards', async () => {
+    renderHarness();
+    let resolveTask: () => void = () => undefined;
+    const task = () =>
+      new Promise<void>((resolve) => {
+        resolveTask = resolve;
+      });
+
+    let promise: Promise<void> | undefined;
+    act(() => {
+      promise = api?.run(task);
+    });
+    expect(api?.submitting).toBe(true);
+    expect(api?.error).toBeNull();
+
+    await act(async () => {
+      resolveTask();
+      await promise;
+    });
+    expect(api?.submitting).toBe(false);
+    expect(api?.submitted).toBe(true);
+    expect(api?.error).toBeNull();
+  });
+
+  it('captures the error message and keeps submitted false on failure', async () => {
+    renderHarness();
+    const failing = () => {
+      throw new Error('接口 500');
+    };
+
+    await act(async () => {
+      await api?.run(failing);
+    });
+    expect(api?.submitting).toBe(false);
+    expect(api?.submitted).toBe(false);
+    expect(api?.error).toBe('接口 500');
+  });
+
+  it('normalizes non-Error rejections to a generic message', async () => {
+    renderHarness();
+    const failing = () => Promise.reject('raw string');
+
+    await act(async () => {
+      await api?.run(failing);
+    });
+    expect(api?.error).toBe('提交失败，请稍后重试');
+  });
+
+  it('ignores re-entrant calls while a task is in flight', async () => {
+    renderHarness();
+    let resolveTask: () => void = () => undefined;
+    const task = () =>
+      new Promise<void>((resolve) => {
+        resolveTask = resolve;
+      });
+    let secondRan = false;
+
+    act(() => {
+      void api?.run(task);
+      void api?.run(() => {
+        secondRan = true;
+      });
+    });
+    expect(secondRan).toBe(false);
+
+    await act(async () => {
+      resolveTask();
+    });
+    expect(api?.submitted).toBe(true);
+  });
+
+  it('reset clears submitted and error states', async () => {
+    renderHarness();
+    await act(async () => {
+      await api?.run(() => undefined);
+    });
+    expect(api?.submitted).toBe(true);
+
+    act(() => {
+      api?.reset();
+    });
+    expect(api?.submitted).toBe(false);
+    expect(api?.error).toBeNull();
+  });
+});
+
+describe('useXCardSurface', () => {
+  it('deduplicates createSurface commands for the same surface id', () => {
+    renderHarness();
+    act(() => {
+      surface?.pushCommands([
+        { version: 'v0.9', createSurface: { surfaceId: 'surface-test', catalogId: 'catalog' } },
+        { version: 'v0.9', updateDataModel: { surfaceId: 'surface-test', path: '/x', value: 1 } },
+      ]);
+      surface?.pushCommands([
+        { version: 'v0.9', createSurface: { surfaceId: 'surface-test', catalogId: 'catalog' } },
+        { version: 'v0.9', updateDataModel: { surfaceId: 'surface-test', path: '/x', value: 2 } },
+      ]);
+    });
+    const createCommands = surface?.commands.filter((command) => 'createSurface' in command);
+    expect(createCommands).toHaveLength(1);
+    expect(surface?.commands).toHaveLength(3);
+  });
+
+  it('resets the command stream when the surface id changes', () => {
+    renderHarness();
+    act(() => {
+      surface?.pushCommands([
+        { version: 'v0.9', createSurface: { surfaceId: 'surface-test', catalogId: 'c' } },
+      ]);
+    });
+    expect(surface?.commands).toHaveLength(1);
+
+    surfaceId = 'surface-other';
+    act(() => {
+      root?.render(<Harness />);
+      surface?.pushCommands([
+        { version: 'v0.9', createSurface: { surfaceId: 'surface-other', catalogId: 'c' } },
+      ]);
+    });
+    expect(surface?.commands).toHaveLength(1);
+  });
+});

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

@@ -0,0 +1,89 @@
+import { useCallback, useRef, useState } from 'react';
+import { useLayoutEffect } from 'react';
+import type { XAgentCommand_v0_9 } from '@ant-design/x-card';
+
+/**
+ * 提交状态管理：收敛 DynamicForm / DynamicReview 中重复的
+ * submitting / submitted / error 状态与「防重复提交 + 失败可重试」逻辑。
+ *
+ * 用法：
+ *   const { submitting, submitted, error, run } = useSubmissionState();
+ *   const handleSubmit = (values) => run(async () => { await onSubmit(values); });
+ */
+export function useSubmissionState() {
+  const [submitting, setSubmitting] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const submittingRef = useRef(false);
+
+  const run = useCallback(async (task: () => Promise<void> | void) => {
+    if (submittingRef.current) return;
+    submittingRef.current = true;
+    setSubmitting(true);
+    setError(null);
+    try {
+      await task();
+      setSubmitted(true);
+    } catch (reason) {
+      setError(reason instanceof Error ? reason.message : '提交失败，请稍后重试');
+    } finally {
+      submittingRef.current = false;
+      setSubmitting(false);
+    }
+  }, []);
+
+  const reset = useCallback(() => {
+    setSubmitted(false);
+    setError(null);
+  }, []);
+
+  return { submitting, submitted, error, run, reset };
+}
+
+/**
+ * A2UI surface 的 XCard commands 增量更新生命周期：
+ * 每个 surface 只创建一次，后续通过 updateDataModel / updateComponents 增量更新。
+ *
+ * 用法：
+ *   const { pushCommands } = useXCardSurface(surfaceId);
+ *   useEffect(() => {
+ *     pushCommands([
+ *       { version: 'v0.9', createSurface: { surfaceId, catalogId } },
+ *       { version: 'v0.9', updateDataModel: { surfaceId, path: '/x', value } },
+ *       { version: 'v0.9', updateComponents: { surfaceId, components } },
+ *     ]);
+ *   }, [value]);
+ */
+export function useXCardSurface(surfaceId: string) {
+  const commandsRef = useRef<XAgentCommand_v0_9[]>([]);
+  const [commands, setCommands] = useState<XAgentCommand_v0_9[]>([]);
+  const idRef = useRef<string>('');
+
+  const pushCommands = useCallback(
+    (cmds: XAgentCommand_v0_9[]) => {
+      if (cmds.length === 0) return;
+      // 同一 surface 的 createSurface 命令只允许出现一次，自动去重
+      const hasSurface = commandsRef.current.some(
+        (c) => 'createSurface' in c && c.createSurface.surfaceId === surfaceId,
+      );
+      const filtered = hasSurface
+        ? cmds.filter((c) => !('createSurface' in c))
+        : cmds;
+      commandsRef.current = [...commandsRef.current, ...filtered];
+      setCommands([...commandsRef.current]);
+    },
+    [surfaceId],
+  );
+
+  const surfaceKey = surfaceId;
+  // 渲染期保持纯函数：ref 变更放到 layout effect 里
+  useLayoutEffect(() => {
+    if (idRef.current !== surfaceKey) {
+      // 组件复用到新 surface 时，清空历史命令重新初始化
+      commandsRef.current = [];
+      idRef.current = surfaceKey;
+    }
+  }, [surfaceKey]);
+
+  return { commands, pushCommands };
+}

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

@@ -0,0 +1,69 @@
+import { getRoleDomains } from '../../auth/menu-policy';
+
+/**
+ * 按用户角色生成 AI 助手欢迎语，引导用户使用与其岗位匹配的业务闭环。
+ * 优先级：教师 > 住宿运营 > 教务 > 教室运营 > 系统/超管 > 兜底。
+ */
+export function welcomeDescription(roles: readonly string[], permissions: readonly string[]): string {
+  const domains = getRoleDomains(roles, permissions);
+
+  if (domains.has('teacher')) {
+    return '我可以帮你查询今日课程、拉取钉钉考勤、查看排课。课程开始后就能看到打卡结果。';
+  }
+  if (domains.has('accommodation')) {
+    return '我可以帮你完成「宿舍档案 → 学生 → 入住 → 费用 → 账单」的住宿计费闭环，先告诉我你手头有什么数据。';
+  }
+  if (domains.has('academic')) {
+    return '我可以帮你完成「学生档案 → 分班 → 排课 → 考勤」的教学闭环，支持 Excel 批量导入与预览确认。';
+  }
+  if (domains.has('classroom')) {
+    return '我可以帮你管理教室排期与租赁订单，查询占用情况，避免时间冲突。';
+  }
+  if (domains.has('system') || domains.has('super')) {
+    return '我是恭学 AI 助手。我可以查询经营数据、管理业务数据、生成批量导入预览——所有写操作都会先经你确认。';
+  }
+  return '我会在你的权限范围内查询数据，也能通过表单帮你录入学生等业务信息。';
+}
+
+/**
+ * 与角色匹配的业务闭环引导示例（用于 Prompts 建议话术）。
+ * 返回空数组表示当前角色无匹配示例。
+ */
+export function workflowPromptExamples(
+  roles: readonly string[],
+  permissions: readonly string[],
+): { label: string; description: string }[] {
+  const domains = getRoleDomains(roles, permissions);
+  const examples: { label: string; description: string }[] = [];
+
+  if (domains.has('academic')) {
+    examples.push(
+      { label: '帮我从 Excel 导入学生并完成分班', description: '教学闭环' },
+      { label: '查一下这周有哪些班级还没排课', description: '教学闭环' },
+    );
+  }
+  if (domains.has('accommodation')) {
+    examples.push(
+      { label: '帮我从 Excel 导入学生并安排入住', description: '住宿计费闭环' },
+      { label: '查一下本月还没生成账单的入住学生', description: '住宿计费闭环' },
+    );
+  }
+  if (domains.has('classroom')) {
+    examples.push(
+      { label: '查一下这间教室本周的占用情况', description: '教室运营' },
+    );
+  }
+  if (domains.has('teacher')) {
+    examples.push(
+      { label: '今天我有哪几节课？', description: '今日教学' },
+    );
+  }
+  if (domains.has('system') || domains.has('super')) {
+    examples.push(
+      { label: '看一下本月的经营概览', description: '数据面板' },
+      { label: '帮我梳理宿舍计费的完整流程', description: '业务流程' },
+    );
+  }
+
+  return examples;
+}

apps/admin/src/components/AppErrorBoundary.tsx

@@ -0,0 +1,52 @@
+import React from 'react';
+import { Button, Result } from 'antd';
+
+interface AppErrorBoundaryProps {
+  children: React.ReactNode;
+  /** 自定义降级内容；不传则使用默认错误卡片 */
+  fallback?: React.ReactNode;
+}
+
+interface AppErrorBoundaryState {
+  hasError: boolean;
+}
+
+/**
+ * 全局渲染错误兜底：捕获子树内的渲染异常，展示可恢复的错误卡片，
+ * 避免单个页面/组件崩溃导致整个应用白屏。
+ */
+export class AppErrorBoundary extends React.Component<
+  AppErrorBoundaryProps,
+  AppErrorBoundaryState
+> {
+  state: AppErrorBoundaryState = { hasError: false };
+
+  static getDerivedStateFromError(): AppErrorBoundaryState {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo): void {
+    console.error('[AppErrorBoundary] 渲染异常:', error, info.componentStack);
+  }
+
+  render(): React.ReactNode {
+    if (this.state.hasError) {
+      if (this.props.fallback) return this.props.fallback;
+      return (
+        <Result
+          status="error"
+          title="页面出现异常"
+          subTitle="请刷新页面重试；若问题持续，请联系管理员。"
+          extra={
+            <Button type="primary" onClick={() => window.location.reload()}>
+              刷新页面
+            </Button>
+          }
+        />
+      );
+    }
+    return this.props.children;
+  }
+}
+
+export default AppErrorBoundary;

apps/admin/src/components/BackTop.tsx

@@ -0,0 +1,41 @@
+import { useEffect, useState } from 'react';
+import { Button, Tooltip } from 'antd';
+import { VerticalAlignTopOutlined } from '@ant-design/icons';
+import { useEventCallback, useEventListener } from 'usehooks-ts';
+
+/**
+ * 全局「回到顶部」浮动按钮：长列表滚动超过 400px 后出现。
+ * 尊重系统「减少动态效果」偏好，平滑滚动仅在未开启该偏好时使用。
+ */
+export const BackTop: React.FC<{ threshold?: number }> = ({ threshold = 400 }) => {
+  const [visible, setVisible] = useState(false);
+  const updateVisible = useEventCallback(() => setVisible(window.scrollY > threshold));
+
+  useEffect(() => {
+    updateVisible();
+  }, [threshold, updateVisible]);
+
+  useEventListener('scroll', updateVisible, undefined, { passive: true });
+
+  if (!visible) return null;
+
+  const scrollToTop = () => {
+    const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    window.scrollTo({ top: 0, behavior: reduceMotion ? 'auto' : 'smooth' });
+  };
+
+  return (
+    <Tooltip title="回到顶部">
+      <Button
+        type="primary"
+        shape="circle"
+        icon={<VerticalAlignTopOutlined />}
+        aria-label="回到顶部"
+        onClick={scrollToTop}
+        style={{ position: 'fixed', right: 24, bottom: 48, zIndex: 1000 }}
+      />
+    </Tooltip>
+  );
+};
+
+export default BackTop;

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,18 +1,16 @@
 import React from 'react';
-import { Navigate } from 'react-router-dom';
-import { Result } from 'antd';
+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 } = usePermission();
-  const roles = (() => {
-    try {
-      return JSON.parse(localStorage.getItem('user') || '{}').roles || [];
-    } catch {
-      return [];
-    }
-  })();
+  const { permissions, permissionsReady } = usePermission();
+  const roles = useUserStore((state) => state.user?.roles ?? []);
+  if (!permissionsReady) {
+    return <Spin size="large" style={{ display: 'block', margin: '80px auto' }} />;
+  }
   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,22 @@ 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 optionRef = useRef(option);
+  optionRef.current = option;
+  const onReadyRef = useRef(onReady);
+  onReadyRef.current = onReady;
 
   useEffect(() => {
     if (!containerRef.current) return;
     const chart = echarts.init(containerRef.current);
-    chart.setOption(option);
+    chart.setOption(optionRef.current);
+    onReadyRef.current?.(chart);
     const observer = new ResizeObserver(() => chart.resize());
     observer.observe(containerRef.current);
     return () => {

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

@@ -1,10 +1,13 @@
 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 { useTimeout } from 'usehooks-ts';
+import { useEditableCellStore } from '../../store/editableCell/editableCellStore';
 import { message } from '../../ui/app-message';
 import './style.css';
+import { getErrorMessage } from '../../utils/error';
 
 export type EditableCellEditor =
   | 'text'
@@ -38,9 +41,6 @@ export interface EditableCellProps<Value = unknown> {
   onSave: (value: Value) => Promise<void>;
 }
 
-let activeCell: { id: string; save: () => Promise<boolean> } | null = null;
-let replayingOutsideAction = false;
-
 export function normalizeEditableValue(value: unknown, editor: EditableCellEditor) {
   if (editor === 'date') return value ? dayjs(value as string) : null;
   if (editor === 'date-range')
@@ -66,7 +66,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) {
@@ -101,6 +101,10 @@ const EditableCell = <Value,>({
   const [draft, setDraft] = useState<unknown>(() =>
     normalizeEditableValue(formatValue ? formatValue(value) : value, editor),
   );
+  // 保存成功后短暂显示「撤销」入口：记录保存前的序列化旧值
+  const [undoMeta, setUndoMeta] = useState<{ serializedPrevious: unknown } | null>(null);
+  // 撤销入口 6 秒后自动消失；useTimeout 在 undoMeta 置空/组件卸载时自动清理
+  useTimeout(() => setUndoMeta(null), undoMeta ? 6_000 : null);
   const enabled = !disabled && (!permission || hasPermission(permission));
 
   const original = useMemo(
@@ -112,58 +116,56 @@ 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;
+    useEditableCellStore.getState().clearIfActive(idRef.current);
     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)) {
+        useEditableCellStore.getState().clearIfActive(idRef.current);
+        setEditing(false);
+        return true;
+      }
+      setSaving(true);
+      const previousValue = original;
+      try {
+        await onSave(parseValue ? parseValue(serialized) : (serialized as Value));
+        useEditableCellStore.getState().clearIfActive(idRef.current);
+        setEditing(false);
+        // 提供 6 秒内的撤销入口（把旧值再保存一次）；useTimeout 负责到时自动清除
+        setUndoMeta({ serializedPrevious: previousValue });
+        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]);
 
   useEffect(() => {
     const cellId = idRef.current;
-    if (editing && activeCell?.id === cellId) activeCell.save = save;
-    return () => {
-      if (activeCell?.id === cellId) activeCell = null;
-    };
+    if (editing) useEditableCellStore.getState().updateActiveSave(cellId, save);
+    return () => useEditableCellStore.getState().clearIfActive(cellId);
   }, [editing, save]);
 
   useEffect(() => {
     if (!editing) return;
     const onPointerDown = (event: PointerEvent) => {
-      if (replayingOutsideAction) return;
+      if (useEditableCellStore.getState().replayingOutsideAction) return;
       if (rootRef.current?.contains(event.target as Node) || isEditorOverlay(event.target)) return;
       const actionTarget =
         event.target instanceof Element
@@ -179,10 +181,10 @@ const EditableCell = <Value,>({
       event.stopPropagation();
       void save().then((saved) => {
         if (!saved) return;
-        replayingOutsideAction = true;
+        useEditableCellStore.getState().setReplayingOutsideAction(true);
         actionTarget.click();
         queueMicrotask(() => {
-          replayingOutsideAction = false;
+          useEditableCellStore.getState().setReplayingOutsideAction(false);
         });
       });
     };
@@ -194,14 +196,33 @@ const EditableCell = <Value,>({
 
   const beginEdit = async () => {
     if (!enabled || saving) return;
+    const { activeCell } = useEditableCellStore.getState();
     if (activeCell && activeCell.id !== idRef.current) {
       const saved = await activeCell.save();
       if (!saved) return;
     }
-    activeCell = { id: idRef.current, save };
+    useEditableCellStore.getState().setActiveCell({ id: idRef.current, save });
+    // 重新进入编辑时清掉上一次的撤销入口
+    setUndoMeta(null);
+    setDraft(normalizeEditableValue(formatValue ? formatValue(value) : value, editor));
     setEditing(true);
   };
 
+  const handleUndo = async () => {
+    if (!undoMeta) return;
+    setUndoMeta(null);
+    try {
+      await onSave(
+        parseValue
+          ? parseValue(undoMeta.serializedPrevious)
+          : (undoMeta.serializedPrevious as Value),
+      );
+      message.success('已撤销修改');
+    } catch (error) {
+      message.error(getErrorMessage(error, '撤销失败'));
+    }
+  };
+
   const onPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
     if (event.pointerType !== 'touch' || editing) return;
     touchStartRef.current = {
@@ -242,6 +263,16 @@ const EditableCell = <Value,>({
       return;
     }
     if (event.key === 'Enter' && editor !== 'textarea') {
+      // 这些编辑器会自己消费 Enter（确认/提交选中值），不重复触发单元格保存
+      if (
+        editor === 'select' ||
+        editor === 'multi-select' ||
+        editor === 'tags' ||
+        editor === 'date' ||
+        editor === 'date-range'
+      ) {
+        return;
+      }
       event.preventDefault();
       await save();
       return;
@@ -309,7 +340,23 @@ const EditableCell = <Value,>({
       {editing ? (
         <Spin spinning={saving}>{control}</Spin>
       ) : (
-        <Tooltip title={enabled ? '双击编辑，触屏双击编辑' : undefined}>{children}</Tooltip>
+        <Tooltip title={enabled ? '双击编辑，触屏双击编辑' : undefined}>
+          <span className="editable-cell-display">
+            {children}
+            {undoMeta ? (
+              <button
+                type="button"
+                className="editable-cell-undo"
+                onClick={(event) => {
+                  event.stopPropagation();
+                  void handleUndo();
+                }}
+              >
+                撤销
+              </button>
+            ) : null}
+          </span>
+        </Tooltip>
       )}
     </div>
   );

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

@@ -5,6 +5,29 @@
   align-items: center;
 }
 
+.editable-cell-display {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  width: 100%;
+}
+
+.editable-cell-undo {
+  flex: none;
+  border: none;
+  background: transparent;
+  color: #1677ff;
+  font-size: 12px;
+  padding: 0;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.editable-cell-undo:hover {
+  text-decoration: underline;
+}
+
 .editable-cell--enabled {
   cursor: cell;
   touch-action: manipulation;

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

@@ -0,0 +1,646 @@
+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,
+  Progress,
+  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 { saveAs } from 'file-saver';
+import {
+  STEP_FIELDS,
+  type ImportPreviewResult,
+  type ImportReceipt,
+  type ImportRunDetail,
+  type ImportStageRequest,
+  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();
+  saveAs(blob, `导入错误报告-${runId.slice(0, 8)}.csv`);
+}
+
+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 [uploadPercent, setUploadPercent] = useState(0);
+  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]);
+
+  /** 创建导入任务并加载详情：统一处理上传进度与 loading 状态。成功返回 run 详情，失败返回 null */
+  const uploadRun = async (
+    file: File,
+    options: {
+      source: 'ai' | 'manual';
+      conversationId?: number;
+      stages?: ImportStageRequest[];
+      mapping?: Record<string, Record<string, string>>;
+    },
+    errorMessage: string,
+  ): Promise<ImportRunDetail | null> => {
+    setUploading(true);
+    setUploadPercent(0);
+    try {
+      const detail = await createImportRun(file, {
+        ...options,
+        onProgress: (percent) => setUploadPercent(percent),
+      });
+      await loadRun(detail.id);
+      return detail;
+    } catch (error) {
+      message.error(error instanceof Error ? error.message : errorMessage);
+      return null;
+    } finally {
+      setUploading(false);
+      setUploadPercent(0);
+    }
+  };
+
+  const handleUpload: UploadProps['customRequest'] = async (options) => {
+    const file = options.file as File;
+    const detail = await uploadRun(file, { source: 'manual' }, '文件上传失败');
+    if (detail) message.success(`已识别 ${detail.sheets.length} 个工作表`);
+  };
+
+  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;
+    const detail = await uploadRun(
+      file,
+      {
+        source: 'manual',
+        stages: [{ stepKey: activeStepKey, sheets: sheetSelection[activeStepKey] ?? [] }],
+        mapping: { [activeStepKey]: mappingDraft[activeStepKey] ?? {} },
+      },
+      '重新上传失败',
+    );
+    if (detail) message.success('已重新上传，并保留原列映射');
+  };
+
+  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
+            title="上传 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>
+          {uploading ? (
+            <Flex vertical gap={4} style={{ marginTop: 8 }}>
+              <Progress
+                percent={uploadPercent}
+                size="small"
+                status={uploadPercent > 0 && uploadPercent < 100 ? 'active' : 'normal'}
+              />
+              <Typography.Text type="secondary" style={{ fontSize: 12, textAlign: 'center' }}>
+                {uploadPercent > 0 && uploadPercent < 100
+                  ? `正在上传 ${uploadPercent}%...`
+                  : '正在上传并解析文件...'}
+              </Typography.Text>
+            </Flex>
+          ) : null}
+        </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 title="全部阶段已提交完成" />
+              <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 title="当前没有可处理的阶段" />
+          )}
+        </Space>
+      )}
+    </Modal>
+  );
+};

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

@@ -0,0 +1,132 @@
+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[];
+  settings?: {
+    mapping?: Partial<Record<ImportStepKey, Record<string, string>>>;
+    organization?: string | null;
+    updateExisting?: boolean;
+    duplicatePolicy?: 'error' | 'skip';
+    skipUnmatched?: boolean;
+  };
+}
+
+export interface ImportStageRequest {
+  stepKey: ImportStepKey;
+  /** 兼容旧调用：单个工作表名。 */
+  sheet?: string;
+  /** 一个阶段可包含多张工作表；与 sheet 二选一（sheets 优先）。 */
+  sheets?: 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,222 +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 { App, 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;
@@ -224,10 +30,13 @@ interface MatchModalProps {
 }
 
 const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplied }) => {
+  const { modal } = App.useApp();
+  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();
@@ -235,26 +44,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);
@@ -274,6 +95,7 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
   };
 
   const handlePreview = async () => {
+    if (!canTriggerSync) return;
     try {
       const values = await credForm.validateFields();
       setLoading(true);
@@ -286,7 +108,10 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
       const initial = new Map<number, MatchDecision>();
       for (const entry of res.entries) {
         if (entry.suggestedStudent) {
-          initial.set(entry.serialNumber, { action: 'match', matchStudentId: entry.suggestedStudent.id });
+          initial.set(entry.serialNumber, {
+            action: 'match',
+            matchStudentId: entry.suggestedStudent.id,
+          });
         }
       }
       setDecisions(initial);
@@ -294,32 +119,45 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
     } catch (e: unknown) {
       const err = e as { message?: string };
       if (err?.message) message.error(err.message);
-    } finally { setLoading(false); }
+    } finally {
+      setLoading(false);
+    }
   };
 
   const handleApply = async () => {
+    if (!canTriggerSync) return;
     setLoading(true);
     setStep('applying');
     try {
-      const decisionList = [...decisions.entries()].map(([serialNumber, d]) => ({ serialNumber, ...d }));
+      const decisionList = [...decisions.entries()].map(([serialNumber, d]) => ({
+        serialNumber,
+        ...d,
+      }));
       const body: Record<string, unknown> = {
         ...credForm.getFieldsValue(),
         decisions: decisionList,
       };
       if (selectedRuleId) body.ruleId = selectedRuleId;
-      const res = await api.post<{ success: boolean; log: { recordsCount: number; message?: string } }>(
-        '/sync/jinshuju/apply', body,
-      );
+      const res = await api.post<{
+        success: boolean;
+        log: { recordsCount: number; message?: string };
+      }>('/sync/jinshuju/apply', body);
       if (res.success) {
         message.success(res.log.message || `处理 ${res.log.recordsCount} 条记录`);
         onApplied();
         reset();
+      } else {
+        // 接口返回 success:false 时也要结束「处理中」并给出错误提示
+        message.error(res.log?.message || '处理失败，请检查后重试');
+        setStep('match');
       }
     } catch (e: unknown) {
       const err = e as { message?: string };
       if (err?.message) message.error(err.message);
       setStep('match');
-    } finally { setLoading(false); }
+    } finally {
+      setLoading(false);
+    }
   };
 
   const reset = () => {
@@ -334,7 +172,26 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
     credForm.resetFields();
   };
 
-  const handleClose = () => { reset(); onClose(); };
+  const handleClose = () => {
+    // 已进入匹配步骤且存在待处理数据时，关闭会丢失全部决策，需先确认
+    const hasPendingWork = step === 'match' && (entries.length > 0 || decisions.size > 0);
+    if (hasPendingWork) {
+      modal.confirm({
+        title: '放弃当前匹配？',
+        content: '已确认的匹配决策将全部丢失，且不会写入系统。',
+        okText: '放弃',
+        okButtonProps: { danger: true },
+        cancelText: '继续匹配',
+        onOk: () => {
+          reset();
+          onClose();
+        },
+      });
+      return;
+    }
+    reset();
+    onClose();
+  };
   const handleScroll = (source: 'left' | 'right') => {
     const el = source === 'left' ? leftRef.current : rightRef.current;
     if (el) setScrollTop(el.scrollTop);
@@ -346,7 +203,10 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
   }, [scrollTop]);
 
   const getDecision = (serial: number): MatchDecision | undefined => decisions.get(serial);
-  const setDecision = (serial: number, d: MatchDecision) => setDecisions((prev) => new Map(prev).set(serial, d));
+  const setDecision = (serial: number, d: MatchDecision) =>
+    setDecisions((draft) => {
+      draft.set(serial, d);
+    });
   const total = entries.length;
   const matched = [...decisions.values()].filter((d) => d.action !== 'skip').length;
 
@@ -401,7 +261,7 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
           onChange={(value) => setSelectedRuleId(value)}
           options={visibleRules.map((rule) => ({ value: rule.id, label: rule.name }))}
         />
-        {selectedRule ? (
+        {canTriggerSync && selectedRule ? (
           <Button
             icon={<EditOutlined />}
             onClick={() => {
@@ -412,15 +272,17 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
             编辑
           </Button>
         ) : null}
-        <Button
-          icon={<PlusOutlined />}
-          onClick={() => {
-            setEditingRule(null);
-            setShowRuleEditor(true);
-          }}
-        >
-          新建规则
-        </Button>
+        {canTriggerSync ? (
+          <Button
+            icon={<PlusOutlined />}
+            onClick={() => {
+              setEditingRule(null);
+              setShowRuleEditor(true);
+            }}
+          >
+            新建规则
+          </Button>
+        ) : null}
       </div>
 
       {visibleRules.length === 0 && !showRuleEditor ? (
@@ -429,7 +291,7 @@ const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplie
         </Text>
       ) : null}
 
-      {showRuleEditor ? (
+      {canTriggerSync && showRuleEditor ? (
         <RuleEditor
           rule={editingRule}
           formToken={formToken}
@@ -439,11 +301,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)}
         />
@@ -452,112 +317,98 @@ 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}
+      mask={{ closable: false }}
+      closable={step !== 'applying'}
       footer={
         step === 'connection'
           ? [
-              <Button key="cancel" onClick={handleClose}>取消</Button>,
-              <Button key="next" type="primary" onClick={handleConnectionNext}>下一步</Button>,
+              <Button key="cancel" onClick={handleClose}>
+                取消
+              </Button>,
+              <Button key="next" type="primary" onClick={handleConnectionNext}>
+                下一步
+              </Button>,
             ]
           : step === 'rule'
             ? [
-                <Button key="back" onClick={() => setStep('connection')}>上一步</Button>,
-                <Button key="cancel" onClick={handleClose}>取消</Button>,
-                <Button key="next" type="primary" icon={<SearchOutlined />} loading={loading} onClick={handlePreview}>
+                ...backCancelButtons(() => setStep('connection')),
+                <Button
+                  key="next"
+                  type="primary"
+                  icon={<SearchOutlined />}
+                  loading={loading}
+                  onClick={handlePreview}
+                >
                   获取数据并下一步
                 </Button>,
               ]
             : step === 'match'
               ? [
-                  <Button key="back" onClick={() => setStep('rule')}>上一步</Button>,
-                  <Button key="cancel" onClick={handleClose}>取消</Button>,
-                  <Button key="apply" type="primary" icon={<CloudUploadOutlined />} loading={loading} onClick={handleApply}>
-                    应用匹配
-                  </Button>,
+                  ...backCancelButtons(() => setStep('rule')),
+                  canTriggerSync ? (
+                    <PermissionButton
+                      key="apply"
+                      permission="sync:trigger"
+                      type="primary"
+                      icon={<CloudUploadOutlined />}
+                      loading={loading}
+                      onClick={handleApply}
+                    >
+                      应用匹配
+                    </PermissionButton>
+                  ) : null,
                 ]
               : null
       }
     >
       <Steps
         current={currentStep}
-        items={[
-          { title: '连接表单' },
-          { title: '匹配规则' },
-          { title: '确认匹配' },
-        ]}
+        items={[{ title: '连接表单' }, { title: '匹配规则' }, { title: '确认匹配' }]}
       />
       {step === 'connection' ? renderConnectionStep() : null}
       {step === 'rule' ? renderRuleStep() : null}
       {step === 'match' ? renderMatchStep() : null}
-      {step === 'applying' ? <Spin tip="正在同步..." style={{ display: 'block', margin: '48px auto' }} /> : null}
+      {step === 'applying' ? (
+        <>
+          <Spin description="正在同步，请勿关闭窗口..." style={{ display: 'block', margin: '48px auto' }} />
+          <Typography.Text type="secondary" style={{ display: 'block', textAlign: 'center' }}>
+            数据正在写入，关闭窗口不会中断同步
+          </Typography.Text>
+        </>
+      ) : 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/NextStepHint.tsx

@@ -0,0 +1,69 @@
+import React, { useState } from 'react';
+import { Button, Card, Flex, Typography } from 'antd';
+import { CloseOutlined, RightOutlined, StepForwardOutlined } from '@ant-design/icons';
+
+export interface NextStepHintProps {
+  /** 提示标题，如「下一步：分班」 */
+  title: string;
+  /** 补充说明 */
+  description?: string;
+  /** 主操作按钮（跳转到下一步） */
+  action?: { label: string; onClick: () => void };
+  /** 是否可关闭，默认 true */
+  closable?: boolean;
+  /** 关闭回调 */
+  onClose?: () => void;
+}
+
+/**
+ * 「下一步」引导卡片：在操作成功后或空状态下提示用户业务闭环的下一步，
+ * 让用户始终知道接下来该做什么。
+ */
+export const NextStepHint: React.FC<NextStepHintProps> = ({
+  title,
+  description,
+  action,
+  closable = true,
+  onClose,
+}) => {
+  const [dismissed, setDismissed] = useState(false);
+  if (dismissed) return null;
+
+  return (
+    <Card
+      size="small"
+      className="next-step-hint"
+      style={{ marginBottom: 16, borderColor: '#b7d4ff', background: '#f0f7ff' }}
+      styles={{ body: { padding: '10px 16px' } }}
+    >
+      <Flex align="center" justify="space-between" gap={8} wrap>
+        <Flex align="center" gap={8} wrap>
+          <StepForwardOutlined style={{ color: '#1677ff' }} />
+          <Typography.Text strong>{title}</Typography.Text>
+          {description ? <Typography.Text type="secondary">{description}</Typography.Text> : null}
+        </Flex>
+        <Flex gap={4} align="center">
+          {action ? (
+            <Button type="primary" size="small" onClick={action.onClick}>
+              {action.label} <RightOutlined />
+            </Button>
+          ) : null}
+          {closable ? (
+            <Button
+              type="text"
+              size="small"
+              icon={<CloseOutlined />}
+              aria-label="关闭提示"
+              onClick={() => {
+                setDismissed(true);
+                onClose?.();
+              }}
+            />
+          ) : null}
+        </Flex>
+      </Flex>
+    </Card>
+  );
+};
+
+export default NextStepHint;

apps/admin/src/components/NotificationBell.tsx

@@ -1,9 +1,13 @@
 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 { message } from '../ui/app-message';
 import { formatNotificationText, notificationTypeLabels } from '../utils/notification-display';
+import { useUserStore } from '../store/user/userStore';
 
 interface NotificationItem {
   id: number;
@@ -16,34 +20,29 @@ 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 */
+    } catch (error) {
+      console.error('全部已读失败', error);
+      message.error('全部已读失败，请重试');
     }
   };
 
   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 +50,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 +71,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);
     };
   }, []);
 
@@ -120,7 +120,7 @@ const NotificationBell: React.FC = () => {
         }}
       >
         <Typography.Text strong>通知中心</Typography.Text>
-        <Button type="link" size="small" onClick={handleMarkAll}>
+        <Button type="link" size="small" disabled={unreadCount === 0} onClick={handleMarkAll}>
           全部已读
         </Button>
       </div>
@@ -201,7 +201,12 @@ const NotificationBell: React.FC = () => {
       placement="bottomRight"
     >
       <Badge count={unreadCount} size="small" offset={[-2, 2]}>
-        <BellOutlined style={{ fontSize: 18, cursor: 'pointer' }} />
+        <Button
+          type="text"
+          shape="circle"
+          icon={<BellOutlined />}
+          aria-label="通知中心"
+        />
       </Badge>
     </Popover>
   );

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 } from 'antd';
-import { useNavigate } from 'react-router-dom';
+import { Result, Button, Spin } from 'antd';
+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;
@@ -10,15 +11,13 @@ interface PermissionRouteProps {
 }
 
 const PermissionRoute: React.FC<PermissionRouteProps> = ({ permission, children }) => {
-  const { permissions, hasPermission } = usePermission();
+  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/QueryState/QueryEmpty.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { Button, Empty } from 'antd';
+
+export interface QueryEmptyAction {
+  label: string;
+  onClick: () => void;
+  type?: 'primary' | 'default';
+  icon?: React.ReactNode;
+}
+
+export interface QueryEmptyProps {
+  /** 空状态描述，默认「暂无数据」 */
+  description?: string;
+  /** 主操作按钮（如「添加学生」「导入 Excel」） */
+  action?: QueryEmptyAction;
+  /** 自定义空态插图 */
+  image?: React.ReactNode;
+}
+
+/**
+ * 统一空状态：数据确实为空时渲染本组件，并附带主操作按钮引导用户开始。
+ */
+export const QueryEmpty: React.FC<QueryEmptyProps> = ({ description = '暂无数据', action, image }) => {
+  return (
+    <Empty image={image} description={description}>
+      {action ? (
+        <Button type={action.type ?? 'primary'} icon={action.icon} onClick={action.onClick}>
+          {action.label}
+        </Button>
+      ) : null}
+    </Empty>
+  );
+};
+
+export default QueryEmpty;

apps/admin/src/components/QueryState/QueryErrorState.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import { Button, Result, Typography } from 'antd';
+
+export interface QueryErrorStateProps {
+  /** 错误标题，默认「数据加载失败」 */
+  title?: string;
+  /** 错误描述，默认「请检查网络后重试」 */
+  description?: string;
+  /** 点击重试回调；不传则不显示重试按钮 */
+  onRetry?: () => void;
+  /** 紧凑模式：用于表格内部、弹窗等空间受限场景 */
+  compact?: boolean;
+}
+
+/**
+ * 统一查询错误态：任何数据加载失败都应渲染本组件（而非伪装成空状态），
+ * 并提供重试入口，让用户明确知道「加载失败」而非「没有数据」。
+ */
+export const QueryErrorState: React.FC<QueryErrorStateProps> = ({
+  title = '数据加载失败',
+  description = '请检查网络后重试。',
+  onRetry,
+  compact = false,
+}) => {
+  if (compact) {
+    return (
+      <div style={{ padding: '32px 16px', textAlign: 'center' }}>
+        <Typography.Text type="secondary">{title}</Typography.Text>
+        {description ? (
+          <div>
+            <Typography.Text type="secondary" style={{ fontSize: 12 }}>
+              {description}
+            </Typography.Text>
+          </div>
+        ) : null}
+        {onRetry ? (
+          <div style={{ marginTop: 12 }}>
+            <Button size="small" onClick={onRetry}>
+              重试
+            </Button>
+          </div>
+        ) : null}
+      </div>
+    );
+  }
+  return (
+    <Result
+      status="warning"
+      title={title}
+      subTitle={description}
+      extra={onRetry ? <Button type="primary" onClick={onRetry}>重试</Button> : undefined}
+    />
+  );
+};
+
+export default QueryErrorState;

apps/admin/src/components/QueryState/index.ts

@@ -0,0 +1,4 @@
+export { QueryErrorState } from './QueryErrorState';
+export type { QueryErrorStateProps } from './QueryErrorState';
+export { QueryEmpty } from './QueryEmpty';
+export type { QueryEmptyProps, QueryEmptyAction } from './QueryEmpty';

apps/admin/src/components/RefreshButton.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import { Button, Tooltip } from 'antd';
+import { ReloadOutlined } from '@ant-design/icons';
+
+interface RefreshButtonProps {
+  onRefresh: () => void;
+  loading?: boolean;
+}
+
+/** 列表工具栏刷新入口：手动重新拉取当前数据，带加载反馈。 */
+export const RefreshButton: React.FC<RefreshButtonProps> = ({ onRefresh, loading }) => (
+  <Tooltip title="刷新">
+    <Button icon={<ReloadOutlined />} loading={loading} onClick={onRefresh} aria-label="刷新" />
+  </Tooltip>
+);
+
+export default RefreshButton;

apps/admin/src/components/RouteDock/dockTabs.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import type { DockTab } from '../../store/app/appTypes';
+import { MAX_DOCK_TABS, upsertDockTab } from './dockTabs';
+
+const tab = (key: string, label = key): DockTab => ({ key, label });
+
+describe('upsertDockTab', () => {
+  it('追加新页签', () => {
+    expect(upsertDockTab([], '/students', '学生管理')).toEqual([tab('/students', '学生管理')]);
+  });
+
+  it('标题未变时保持原引用，避免无谓渲染', () => {
+    const tabs = [tab('/students', '学生管理')];
+    expect(upsertDockTab(tabs, '/students', '学生管理')).toBe(tabs);
+  });
+
+  it('菜单标题变化时更新页签标题', () => {
+    const tabs = [tab('/students', '学生管理')];
+    expect(upsertDockTab(tabs, '/students', '学生档案')).toEqual([tab('/students', '学生档案')]);
+  });
+
+  it('超过上限时保留当前页签 + 最新页签（LRU 淘汰最旧）', () => {
+    const tabs = Array.from({ length: MAX_DOCK_TABS }, (_, i) => tab(`/p${i + 1}`));
+    const next = upsertDockTab(tabs, '/new', '新页');
+    expect(next).toHaveLength(MAX_DOCK_TABS);
+    expect(next[0]).toEqual(tab('/new', '新页'));
+    expect(next[next.length - 1]).toEqual(tab(`/p${MAX_DOCK_TABS}`));
+    expect(next.some((t) => t.key === '/p1')).toBe(false);
+  });
+
+  it('恢复持久化的超量页签时压缩到上限，并保留当前页', () => {
+    const tabs = Array.from({ length: 25 }, (_, i) => tab(`/p${i + 1}`));
+    tabs.push(tab('/wallets', '学生余额'));
+    const next = upsertDockTab(tabs, '/wallets', '学生余额');
+    expect(next).toHaveLength(MAX_DOCK_TABS);
+    expect(next[0]).toEqual(tab('/wallets', '学生余额'));
+    expect(next.some((t) => t.key === '/p1')).toBe(false);
+    expect(next.some((t) => t.key === '/p6')).toBe(false);
+    expect(next.some((t) => t.key === '/p7')).toBe(true);
+  });
+});

apps/admin/src/components/RouteDock/dockTabs.ts

@@ -0,0 +1,31 @@
+import type { DockTab } from '../../store/app/appTypes';
+
+/** 页签数量上限：超出后淘汰最旧的非当前页签（LRU 式），避免无限堆积。 */
+export const MAX_DOCK_TABS = 20;
+
+function clampToLimit(list: readonly DockTab[], activeKey: string): DockTab[] {
+  // 未超限时保留原引用，避免触发无谓的 tab 列表重渲染
+  if (list.length <= MAX_DOCK_TABS) return list as DockTab[];
+  // 恢复/迁移或新增后超出上限：保留当前页签 + 最新的其余页签（LRU 式淘汰）
+  const active = list.find((tab) => tab.key === activeKey);
+  const rest = list.filter((tab) => tab.key !== activeKey);
+  const keptRest = rest.slice(rest.length - (MAX_DOCK_TABS - 1));
+  return active ? [active, ...keptRest] : keptRest.slice(-MAX_DOCK_TABS);
+}
+
+/**
+ * 路由页签合并：按 pathname 建 tab，重复时更新标题，并始终把列表压回上限。
+ */
+export function upsertDockTab(
+  tabs: readonly DockTab[],
+  activeKey: string,
+  label: string,
+): DockTab[] {
+  const existing = tabs.find((tab) => tab.key === activeKey);
+  if (existing) {
+    const updated =
+      existing.label === label ? tabs : tabs.map((tab) => (tab.key === activeKey ? { ...tab, label } : tab));
+    return clampToLimit(updated, activeKey);
+  }
+  return clampToLimit([...tabs, { key: activeKey, label }], activeKey);
+}

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,12 @@ 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 { Button, Dropdown, Tabs, type TabsProps } from 'antd';
+import { DownOutlined } from '@ant-design/icons';
+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';
+import { upsertDockTab } from './dockTabs';
 
 interface RouteDockProps {
   location: Location;
@@ -50,19 +51,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'],
@@ -86,29 +74,17 @@ 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) }];
-  });
+  // 与 RouteKeeper 缓存 key 保持一致：只按 pathname 建 tab，避免 query 变化产生重复页签。
+  const activeKey = 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) => {
-      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]);
+    const label = getRouteLabel(menuItems, location.pathname);
+    setRouteDockTabs((currentTabs) => upsertDockTab(currentTabs, activeKey, label));
+  }, [activeKey, location.pathname, menuItems, setRouteDockTabs]);
 
   const tabItems = useMemo<NonNullable<TabsProps['items']>>(
     () =>
@@ -124,16 +100,37 @@ 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);
     }
   };
 
+  const closeOthers = () => {
+    setRouteDockTabs(tabs.filter((tab) => tab.key === activeKey));
+  };
+
+  const closeLeft = () => {
+    const index = tabs.findIndex((tab) => tab.key === activeKey);
+    if (index <= 0) return;
+    setRouteDockTabs(tabs.filter((_, i) => i >= index));
+  };
+
+  const closeRight = () => {
+    const index = tabs.findIndex((tab) => tab.key === activeKey);
+    if (index < 0 || index === tabs.length - 1) return;
+    setRouteDockTabs(tabs.filter((_, i) => i <= index));
+  };
+
+  const closeAll = () => {
+    setRouteDockTabs([]);
+    onNavigate('/dashboard');
+  };
+
   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
@@ -188,6 +185,32 @@ const RouteDock: React.FC<RouteDockProps> = ({ location, menuItems, onNavigate,
           if (action === 'remove') closeTab(String(targetKey));
         }}
         renderTabBar={renderTabBar}
+        tabBarExtraContent={
+          tabs.length > 1 ? (
+            <Dropdown
+              trigger={['click']}
+              menu={{
+                items: [
+                  { key: 'close-others', label: '关闭其他' },
+                  { key: 'close-left', label: '关闭左侧' },
+                  { key: 'close-right', label: '关闭右侧' },
+                  { type: 'divider' },
+                  { key: 'close-all', label: '关闭全部' },
+                ],
+                onClick: ({ key }) => {
+                  if (key === 'close-others') closeOthers();
+                  else if (key === 'close-left') closeLeft();
+                  else if (key === 'close-right') closeRight();
+                  else if (key === 'close-all') closeAll();
+                },
+              }}
+            >
+              <Button type="text" size="small" icon={<DownOutlined />} aria-label="更多页签操作">
+                更多
+              </Button>
+            </Dropdown>
+          ) : undefined
+        }
       />
     </nav>
   );

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,48 @@
+import React, { useRef } from 'react';
+import { useLocation, useOutlet } from 'react-router';
+import AppErrorBoundary from './AppErrorBoundary';
+import { ActivePageContext } from './routeKeeperContext';
+
+const MAX_CACHED_PAGES = 30;
+
+/**
+ * 路由保活：切换页面时保留已访问页面的组件实例（输入、滚动、弹窗状态不丢失）。
+ * 隐藏页面仍挂载在 DOM 中，仅通过 display:none 隐藏。
+ *
+ * - 每个缓存页外层包裹 AppErrorBoundary：单页渲染异常不影响其他缓存页。
+ * - 通过 ActivePageContext 向页面暴露「当前激活页路径」，供 usePageVisible 使用。
+ */
+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 (
+    <ActivePageContext.Provider value={pageKey}>
+      {Array.from(cacheRef.current.entries()).map(([key, node]) => (
+        <div
+          key={key}
+          className="route-keeper-page"
+          style={{ display: key === pageKey ? undefined : 'none' }}
+        >
+          <AppErrorBoundary>{node}</AppErrorBoundary>
+        </div>
+      ))}
+    </ActivePageContext.Provider>
+  );
+};
+
+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/ScrollToTop.tsx

@@ -0,0 +1,16 @@
+import { useEffect } from 'react';
+import { useLocation } from 'react-router';
+
+/**
+ * SPA 路由切换后把滚动位置复位到顶部。
+ * 只在 pathname 变化时触发，避免干扰弹窗/抽屉等局部滚动。
+ */
+export const ScrollToTop: React.FC = () => {
+  const { pathname } = useLocation();
+  useEffect(() => {
+    window.scrollTo(0, 0);
+  }, [pathname]);
+  return null;
+};
+
+export default ScrollToTop;

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

@@ -0,0 +1,208 @@
+import React, { useRef, useState } from 'react';
+import { App, Button, Modal, 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';
+
+type AttachmentPreview = {
+  url: string;
+  name: string;
+  kind: 'image' | 'pdf';
+};
+
+/** 根据文件扩展名决定安全展示方式：图片/PDF 内联预览，其余一律下载 */
+function getAttachmentKind(fileName: string, mimeType?: string): 'image' | 'pdf' | 'download' {
+  const ext = fileName.split('.').pop()?.toLowerCase() ?? '';
+  if (['png', 'jpg', 'jpeg', 'webp', 'gif', 'bmp', 'svg'].includes(ext)) return 'image';
+  if (ext === 'pdf' || mimeType === 'application/pdf') return 'pdf';
+  return 'download';
+}
+
+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 [preview, setPreview] = useState<AttachmentPreview | null>(null);
+  // 预览请求序号：快速点不同行「查看」时，慢的旧响应回来直接丢弃，避免覆盖新预览
+  const previewSeqRef = useRef(0);
+
+  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),
+    { invalidate: [['archive', studentId]] },
+  );
+
+  const closePreview = () => {
+    previewSeqRef.current += 1; // 关闭后仍在途的旧响应也不再落地
+    if (preview?.url) URL.revokeObjectURL(preview.url);
+    setPreview(null);
+  };
+
+  const openAttachment = async (record: AttachmentRecord) => {
+    const seq = ++previewSeqRef.current;
+    try {
+      const blob = await api.get<Blob>(`/archive/${studentId}/attachments/${record.id}`, {
+        responseType: 'blob',
+      });
+      if (seq !== previewSeqRef.current) return; // 已有更新的查看请求，丢弃本次慢响应
+      const kind = getAttachmentKind(record.fileName, record.mimeType);
+      const url = URL.createObjectURL(blob);
+      if (kind === 'download') {
+        // 非内联类型通过 download 属性触发下载，避免以页面同源打开可执行内容
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = record.fileName || 'attachment';
+        document.body.appendChild(a);
+        a.click();
+        a.remove();
+        window.setTimeout(() => URL.revokeObjectURL(url), 60_000);
+      } else {
+        if (preview?.url) URL.revokeObjectURL(preview.url);
+        setPreview({ url, name: record.fileName || 'attachment', kind });
+      }
+    } catch (e: unknown) {
+      message.error(getErrorMessage(e, '查看失败'));
+    }
+  };
+
+  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={() => openAttachment(record)}>
+            查看
+          </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> scroll={{ x: 'max-content' }}
+        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 }}
+      />
+      <Modal
+        title={preview?.name}
+        open={!!preview}
+        footer={null}
+        onCancel={closePreview}
+        width={preview?.kind === 'pdf' ? 900 : undefined}
+        destroyOnHidden
+      >
+        {preview?.kind === 'image' ? (
+          <img src={preview.url} alt={preview.name} style={{ width: '100%' }} />
+        ) : preview?.kind === 'pdf' ? (
+          <iframe
+            src={preview.url}
+            title={preview.name}
+            sandbox=""
+            style={{ width: '100%', height: '70vh', border: 'none' }}
+          />
+        ) : null}
+      </Modal>
+    </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> scroll={{ x: 'max-content' }}
+        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> scroll={{ x: 'max-content' }}
+        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> scroll={{ x: 'max-content' }}
+        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,217 @@
+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;
+  mimeType?: string;
+}
+
+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/components/routeKeeperContext.ts

@@ -0,0 +1,10 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * 当前激活的页面路径（由 RouteKeeper 提供）。
+ * RouteKeeper 用 display:none 保活已访问页面，页面组件本身不会重新挂载，
+ * 因此需要该上下文让每个缓存页感知「自己是否处于激活状态」。
+ */
+export const ActivePageContext = createContext<string>('');
+
+export const useActivePage = (): string => useContext(ActivePageContext);

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

@@ -0,0 +1,125 @@
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { MemoryRouter, Route, Routes, useNavigate } from 'react-router';
+import { RefreshButton } from './RefreshButton';
+import { BackTop } from './BackTop';
+import { ScrollToTop } from './ScrollToTop';
+import { useSubmitShortcut } from '../hooks/useSubmitShortcut';
+
+let container: HTMLDivElement | null = null;
+let root: ReturnType<typeof createRoot> | null = null;
+
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+const mount = (node: React.ReactNode) => {
+  const host = document.createElement('div');
+  container = host;
+  document.body.appendChild(host);
+  root = createRoot(host);
+  act(() => root?.render(node));
+};
+
+afterEach(async () => {
+  if (root) {
+    await act(async () => root?.unmount());
+  }
+  container?.remove();
+  root = null;
+  container = null;
+  vi.restoreAllMocks();
+});
+
+describe('UX 组件与交互', () => {
+  it('RefreshButton 点击触发 onRefresh，loading 时展示加载态', async () => {
+    const onRefresh = vi.fn();
+    mount(<RefreshButton onRefresh={onRefresh} />);
+    const button = container?.querySelector('button');
+    if (!button) throw new Error('button not rendered');
+    act(() => button.dispatchEvent(new MouseEvent('click', { bubbles: true })));
+    await flush();
+    expect(onRefresh).toHaveBeenCalledTimes(1);
+
+    mount(<RefreshButton onRefresh={onRefresh} loading />);
+    expect(container?.querySelector('.ant-btn-loading')).toBeTruthy();
+  });
+
+  it('useSubmitShortcut 未激活时不响应 Cmd+Enter', async () => {
+    const onSubmit = vi.fn();
+    const Harness = () => {
+      useSubmitShortcut(false, onSubmit);
+      return <button type="button">ok</button>;
+    };
+    mount(<Harness />);
+    window.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'Enter', metaKey: true, bubbles: true }),
+    );
+    await flush();
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('useSubmitShortcut 激活时响应 Cmd/Ctrl+Enter 且阻止默认行为', async () => {
+    const onSubmit = vi.fn();
+    const Harness = () => {
+      useSubmitShortcut(true, onSubmit);
+      return <button type="button">ok</button>;
+    };
+    mount(<Harness />);
+
+    const metaEvent = new KeyboardEvent('keydown', {
+      key: 'Enter',
+      metaKey: true,
+      bubbles: true,
+      cancelable: true,
+    });
+    window.dispatchEvent(metaEvent);
+    expect(metaEvent.defaultPrevented).toBe(true);
+
+    window.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'Enter', ctrlKey: true, bubbles: true }),
+    );
+    await flush();
+    expect(onSubmit).toHaveBeenCalledTimes(2);
+  });
+
+  it('BackTop 超过阈值后出现，点击回到顶部', async () => {
+    const scrollSpy = vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+    mount(<BackTop threshold={-1} />);
+    await flush();
+    const button = container?.querySelector('button');
+    expect(button).toBeTruthy();
+    if (button) {
+      act(() => button.dispatchEvent(new MouseEvent('click', { bubbles: true })));
+    }
+    await flush();
+    expect(scrollSpy).toHaveBeenCalledWith(expect.objectContaining({ top: 0 }));
+  });
+
+  it('ScrollToTop 在路由切换时把滚动位置复位到顶部', async () => {
+    const scrollSpy = vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+    const Nav = () => {
+      const navigate = useNavigate();
+      return (
+        <button type="button" onClick={() => navigate('/other')}>
+          go
+        </button>
+      );
+    };
+    mount(
+      <MemoryRouter initialEntries={['/']}>
+        <ScrollToTop />
+        <Routes>
+          <Route path="/" element={<Nav />} />
+          <Route path="/other" element={<div>other</div>} />
+        </Routes>
+      </MemoryRouter>,
+    );
+    scrollSpy.mockClear();
+
+    const button = container?.querySelector('button');
+    if (!button) throw new Error('button not rendered');
+    act(() => button.dispatchEvent(new MouseEvent('click', { bubbles: true })));
+    await flush();
+    expect(scrollSpy).toHaveBeenCalledWith(0, 0);
+  });
+});

apps/admin/src/hooks/useApiMutation.ts

@@ -0,0 +1,63 @@
+import { useMutation, useQueryClient, type QueryKey } from '@tanstack/react-query';
+import { message } from '../ui/app-message';
+import { getErrorMessage } from '../utils/error';
+
+interface UseApiMutationOptions<TData, TVars, TContext> {
+  /** 成功后自动失效的查询 key（触发列表/详情刷新） */
+  invalidate?: QueryKey[];
+  /** 乐观更新：mutate 前同步改缓存，返回回滚上下文（失败时传给 onError） */
+  onMutate?: (vars: TVars) => Promise<TContext | undefined> | TContext | undefined;
+  /** 成功后回调（例如关闭弹窗） */
+  onSuccess?: (data: TData, vars: TVars, context?: TContext) => void;
+  /** 失败回调；提供时由调用方负责（含乐观更新回滚），否则默认用 getErrorMessage 弹错误提示 */
+  onError?: (error: unknown, vars: TVars, context?: TContext) => void;
+  /** 结束后回调（无论成败） */
+  onSettled?: (data: TData | undefined, error: unknown, vars: TVars, context?: TContext) => void;
+}
+
+/**
+ * useMutation 的轻量封装：统一错误提示 + 成功后 invalidateQueries，
+ * 消除手写 `await api.xxx(); await fetchData();` 样板。
+ *
+ * 乐观更新示例：
+ * ```ts
+ * const mutation = useApiMutation(fn, {
+ *   onMutate: async (vars) => {
+ *     await queryClient.cancelQueries({ queryKey });
+ *     const previous = queryClient.getQueryData(queryKey);
+ *     queryClient.setQueryData(queryKey, updater);
+ *     return previous; // 回滚上下文
+ *   },
+ *   onError: (_e, _v, previous) => queryClient.setQueryData(queryKey, previous),
+ * });
+ * ```
+ */
+export function useApiMutation<TData = unknown, TVars = void, TContext = unknown>(
+  mutationFn: (vars: TVars) => Promise<TData>,
+  options: UseApiMutationOptions<TData, TVars, TContext> = {},
+) {
+  const queryClient = useQueryClient();
+  return useMutation<TData, Error, TVars, TContext>({
+    mutationFn,
+    // 包装 onMutate：允许调用方返回 undefined（无回滚上下文），
+    // React Query 的 onMutate 类型要求返回 TContext
+    onMutate: async (vars) => {
+      const context = await options.onMutate?.(vars);
+      return context as TContext;
+    },
+    onSuccess: (data, vars, context) => {
+      for (const key of options.invalidate ?? []) {
+        void queryClient.invalidateQueries({ queryKey: key });
+      }
+      options.onSuccess?.(data, vars, context);
+    },
+    onError: (error, vars, context) => {
+      if (options.onError) {
+        options.onError(error, vars, context);
+      } else {
+        message.error(getErrorMessage(error));
+      }
+    },
+    onSettled: options.onSettled,
+  });
+}

apps/admin/src/hooks/useApiQuery.ts

@@ -0,0 +1,31 @@
+import { useQuery } from '@tanstack/react-query';
+import type { QueryKey } from '@tanstack/react-query';
+import type { z } from 'zod';
+import { validateResponse } from '../utils/validate';
+
+interface UseApiQueryOptions<T, TSelected = T> {
+  queryKey: QueryKey;
+  queryFn: () => Promise<unknown>;
+  /** zod schema：响应校验失败会抛出带字段路径的错误，由统一错误处理展示 */
+  schema: z.ZodType<unknown>;
+  enabled?: boolean;
+  staleTime?: number;
+  /** 可选的数据转换（React Query select），例如列表原始行 → UI 模型 */
+  select?: (data: T) => TSelected;
+}
+
+/**
+ * useQuery 的类型安全封装：queryFn 返回 unknown，
+ * 由 zod schema 校验并收敛为 T，消除各页面重复的
+ * `validateResponse(schema, await api.get(...))` 样板。
+ */
+export function useApiQuery<T, TSelected = T>(options: UseApiQueryOptions<T, TSelected>) {
+  const { queryKey, queryFn, schema, enabled, staleTime, select } = options;
+  return useQuery<T, Error, TSelected>({
+    queryKey,
+    enabled,
+    staleTime,
+    queryFn: async () => validateResponse<T>(schema, await queryFn()),
+    select,
+  });
+}

apps/admin/src/hooks/useDirtyGuard.ts

@@ -0,0 +1,53 @@
+import { useCallback, useMemo, useRef } from 'react';
+import { App } from 'antd';
+import type { FormInstance } from 'antd';
+import equal from 'fast-deep-equal';
+
+/**
+ * 弹窗「未保存内容」保护：关闭弹窗时若表单值已被修改，先确认再关闭，
+ * 避免用户误关丢失已填内容。
+ *
+ * 用法：
+ *   const { confirmClose, snapshot } = useDirtyGuard(form);
+ *   // 打开弹窗（或编辑回填后）时调用一次 snapshot() 记录初始值
+ *   const openEdit = () => { form.setFieldsValue(record); snapshot(); setOpen(true); };
+ *   // Modal 的 onCancel 改用确认关闭
+ *   <Modal onCancel={() => confirmClose(() => setOpen(false))} ...>
+ */
+export function useDirtyGuard(form: FormInstance) {
+  const { modal } = App.useApp();
+  const pristineRef = useRef<unknown>(null);
+
+  /** 记录当前表单值为「未修改」基准；打开弹窗/回填后调用 */
+  const snapshot = useCallback(() => {
+    pristineRef.current = form.getFieldsValue();
+  }, [form]);
+
+  /** 表单是否有未保存修改（与 snapshot 时对比） */
+  const isDirty = useCallback(() => {
+    return !equal(form.getFieldsValue(), pristineRef.current);
+  }, [form]);
+
+  const confirmClose = useCallback(
+    (close: () => void) => {
+      if (!isDirty()) {
+        close();
+        return;
+      }
+      modal.confirm({
+        title: '放弃未保存的修改？',
+        content: '当前表单有未保存的内容，关闭后修改将丢失。',
+        okText: '放弃修改',
+        okButtonProps: { danger: true },
+        cancelText: '继续编辑',
+        onOk: close,
+      });
+    },
+    [isDirty, modal],
+  );
+
+  // 用 useMemo 稳定返回对象引用，避免消费方 useEffect 依赖每次渲染都变化
+  return useMemo(() => ({ confirmClose, snapshot, isDirty }), [confirmClose, snapshot, isDirty]);
+}
+
+export default useDirtyGuard;

apps/admin/src/hooks/useDownload.ts

@@ -0,0 +1,46 @@
+import { useCallback, useRef, useState } from 'react';
+import { downloadBlob } from '../utils/download';
+import { message } from '../ui/app-message';
+
+export interface DownloadOptions {
+  /** 成功提示文案；默认「下载成功」 */
+  successMsg?: string;
+  /** 失败提示文案；默认使用接口返回的错误信息 */
+  errorMsg?: string;
+}
+
+/**
+ * 统一下载/导出状态：防重复点击 + 成功/失败反馈。
+ *
+ * 用法：
+ *   const { downloading, run } = useDownload();
+ *   <Button loading={downloading} onClick={() => run('/students/export', '名单.xlsx')}>
+ */
+export function useDownload() {
+  const [downloading, setDownloading] = useState(false);
+  const busyRef = useRef(false);
+
+  const run = useCallback(
+    async (endpoint: string, filename: string, options?: DownloadOptions) => {
+      if (busyRef.current) return;
+      busyRef.current = true;
+      setDownloading(true);
+      try {
+        await downloadBlob(endpoint, filename);
+        message.success(options?.successMsg ?? '下载成功');
+      } catch (error: unknown) {
+        message.error(
+          options?.errorMsg ?? (error instanceof Error ? error.message : '下载失败，请重试'),
+        );
+      } finally {
+        busyRef.current = false;
+        setDownloading(false);
+      }
+    },
+    [],
+  );
+
+  return { downloading, run };
+}
+
+export default useDownload;

apps/admin/src/hooks/usePageVisible.ts

@@ -0,0 +1,37 @@
+import { useEffect, useRef } from 'react';
+import { useLocation } from 'react-router';
+import { useQueryClient, type QueryKey } from '@tanstack/react-query';
+import { useActivePage } from '../components/routeKeeperContext';
+
+/**
+ * 当前页面是否处于激活（可见）状态。
+ * RouteKeeper 保活页面始终挂载，只有激活页可见；配合
+ * `useVisibleRefetch` 可在切回页面时刷新数据。
+ */
+export function usePageVisible(): boolean {
+  const activePage = useActivePage();
+  const location = useLocation();
+  return activePage === location.pathname;
+}
+
+/**
+ * 页面重新变为可见时刷新指定 queryKey 的数据。
+ * 解决 RouteKeeper 保活导致的「切回列表页看不到新增/删除数据」问题。
+ *
+ * 用法：`useVisibleRefetch(['students']);`
+ *
+ * 注意：queryKey 通过 ref 持有，effect 只依赖 visible，
+ * 避免调用方每次渲染传入新数组字面量导致频繁重复请求。
+ */
+export function useVisibleRefetch(queryKey: QueryKey | undefined): void {
+  const visible = usePageVisible();
+  const queryClient = useQueryClient();
+  const keyRef = useRef(queryKey);
+  keyRef.current = queryKey;
+
+  useEffect(() => {
+    if (visible && keyRef.current) {
+      void queryClient.refetchQueries({ queryKey: keyRef.current });
+    }
+  }, [visible, queryClient]);
+}

apps/admin/src/hooks/usePermission.ts

@@ -1,31 +1,31 @@
-import { useCallback, useEffect, useState } from 'react';
-import { PERMISSIONS_UPDATED_EVENT, readPermissions } from '../auth/permission-store';
+import { useCallback } from 'react';
+import { usePermissionStore } from '../store/permission/permissionStore';
 
 export function usePermission() {
-  const [permissions, setPermissions] = useState<string[]>(readPermissions);
-
-  useEffect(() => {
-    const refresh = () => setPermissions(readPermissions());
-    window.addEventListener(PERMISSIONS_UPDATED_EVENT, refresh);
-    window.addEventListener('storage', refresh);
-    return () => {
-      window.removeEventListener(PERMISSIONS_UPDATED_EVENT, refresh);
-      window.removeEventListener('storage', refresh);
-    };
-  }, []);
-
+  const permissions = usePermissionStore((state) => state.permissions);
+  const permissionStatus = usePermissionStore((state) => state.status);
+  const permissionsReady = permissionStatus === 'ready';
   const hasPermission = useCallback(
-    (code: string): boolean => permissions.includes(code),
-    [permissions],
+    (code: string): boolean => permissionsReady && permissions.includes(code),
+    [permissions, permissionsReady],
   );
   const hasAnyPermission = useCallback(
-    (...codes: string[]): boolean => codes.some((code) => permissions.includes(code)),
-    [permissions],
+    (...codes: string[]): boolean =>
+      permissionsReady && codes.some((code) => permissions.includes(code)),
+    [permissions, permissionsReady],
   );
   const hasAllPermissions = useCallback(
-    (...codes: string[]): boolean => codes.every((code) => permissions.includes(code)),
-    [permissions],
+    (...codes: string[]): boolean =>
+      permissionsReady && codes.every((code) => permissions.includes(code)),
+    [permissions, permissionsReady],
   );
 
-  return { permissions, hasPermission, hasAnyPermission, hasAllPermissions };
+  return {
+    permissions,
+    permissionStatus,
+    permissionsReady,
+    hasPermission,
+    hasAnyPermission,
+    hasAllPermissions,
+  };
 }

apps/admin/src/hooks/useSubmitShortcut.ts

@@ -0,0 +1,19 @@
+import { useEffect } from 'react';
+
+/**
+ * 弹窗/表单内按 Cmd/Ctrl+Enter 触发表单提交。
+ * 仅在 active（弹窗打开且非保存中）时监听，避免误触。
+ */
+export function useSubmitShortcut(active: boolean, onSubmit: () => void): void {
+  useEffect(() => {
+    if (!active) return;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if ((event.metaKey || event.ctrlKey) && event.key === 'Enter') {
+        event.preventDefault();
+        onSubmit();
+      }
+    };
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [active, onSubmit]);
+}

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,14 +51,17 @@ 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],
+    [studentId, module, modal],
   );
 }

apps/admin/src/index.css

@@ -514,3 +514,68 @@ canvas {
     padding-inline: 0;
   }
 }
+
+/* ─── 全局无障碍与质感增强 ─── */
+html {
+  scroll-behavior: smooth;
+}
+
+::selection {
+  background: rgba(0, 122, 255, 0.18);
+}
+
+/* 键盘导航焦点可见（鼠标点击不显示，符合 WCAG 2.4.7） */
+:focus-visible {
+  outline: 2px solid #007aff;
+  outline-offset: 2px;
+}
+
+/* 细滚动条（macOS/Chromium），降低大面积滚动条对视觉的干扰 */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: rgba(0, 0, 0, 0.16);
+  border: 2px solid transparent;
+  border-radius: 8px;
+  background-clip: content-box;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background-color: rgba(0, 0, 0, 0.28);
+}
+
+/* 尊重系统「减少动态效果」偏好 */
+/* 窄屏下压缩路由标签尺寸，避免横向裁切 */
+@media (max-width: 575px) {
+  .route-dock {
+    padding: 6px 8px;
+  }
+
+  .route-dock .ant-tabs-tab {
+    min-width: 88px;
+    max-width: 160px;
+    padding: 0 8px 0 10px !important;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html {
+    scroll-behavior: auto;
+  }
+
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}

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,14 +29,22 @@ import {
   TrophyOutlined,
   ApiOutlined,
   RobotOutlined,
+  LoadingOutlined,
 } from '@ant-design/icons';
 import { usePermission } from '../hooks/usePermission';
 import api from '../api';
-import { writePermissions } from '../auth/permission-store';
+import { useAppStore } from '../store/app/appStore';
+import { usePermissionStore } from '../store/permission/permissionStore';
+import { useUserStore } from '../store/user/userStore';
+import { AUTH_STORAGE_NAME, PERMISSION_STORAGE_NAME } from '../store/middleware/persist';
 import NotificationBell from '../components/NotificationBell';
 import RouteDock from '../components/RouteDock';
+import RouteKeeper from '../components/RouteKeeper';
+import BackTop from '../components/BackTop';
 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> = {
@@ -69,38 +78,109 @@ 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;
-    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(() => {
-        // 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 === PERMISSION_STORAGE_NAME) {
+        // 其他标签页的权限更新：原地应用，避免整页刷新造成刷新风暴。
+        try {
+          if (event.newValue === null) {
+            usePermissionStore.getState().clearPermissions();
+            return;
+          }
+          const parsed = JSON.parse(event.newValue) as {
+            state?: { permissions?: string[] };
+          };
+          const permissions = parsed?.state?.permissions;
+          if (Array.isArray(permissions)) {
+            usePermissionStore.getState().writePermissions(permissions);
+          }
+        } catch {
+          // 忽略无法解析的跨标签页权限写入
+        }
+        return;
+      }
+      if (event.key === AUTH_STORAGE_NAME) {
+        // 仅当登录态（token）确实变化时才整页刷新：登录、退出或切换账号。
+        const currentToken = useUserStore.getState().token;
+        let otherToken: string | null = null;
+        if (event.newValue) {
+          try {
+            const parsed = JSON.parse(event.newValue) as {
+              state?: { token?: string | null };
+            };
+            otherToken = parsed?.state?.token ?? null;
+          } catch {
+            otherToken = null;
+          }
+        }
+        if (otherToken === currentToken) return;
+        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)
@@ -109,35 +189,38 @@ 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');
-    localStorage.removeItem('permissions');
+    logoutUser();
+    usePermissionStore.getState().clearPermissions();
+    useAppStore.getState().setRouteDockTabs([]);
     navigate('/login');
-  }, [navigate]);
+  }, [logoutUser, navigate]);
 
   const handleMenuClick = useCallback(
     (key: string) => {
       navigate(key);
       if (usesDrawer) setDrawerOpen(false);
     },
-    [navigate, usesDrawer],
+    [navigate, usesDrawer, setDrawerOpen],
   );
 
-  const findSelectedKeys = (items: AppMenuItem[], pathname: string): string[] => {
-    for (const item of items) {
-      if (item.key === pathname) return [item.key];
-      if (item.children) {
-        const found = findSelectedKeys(item.children, pathname);
-        if (found.length > 0) return found;
+  const findSelectedKeys = useCallback(
+    (items: AppMenuItem[], pathname: string): string[] => {
+      for (const item of items) {
+        if (item.key === pathname) return [item.key];
+        if (item.children) {
+          const found = findSelectedKeys(item.children, pathname);
+          if (found.length > 0) return found;
+        }
       }
-    }
-    return [pathname];
-  };
+      return [pathname];
+    },
+    [],
+  );
 
   const findOpenKeys = (items: AppMenuItem[], pathname: string): string[] => {
     for (const item of items) {
@@ -157,7 +240,7 @@ const MainLayout: React.FC = () => {
 
   const selectedKeys = useMemo(
     () => findSelectedKeys(menuItems, location.pathname),
-    [menuItems, location.pathname],
+    [menuItems, location.pathname, findSelectedKeys],
   );
   // 路径变化时同步展开的菜单（不干扰用户手动展开/收起）
   useEffect(() => {
@@ -166,20 +249,20 @@ const MainLayout: React.FC = () => {
       const routeOpenKeys = findOpenKeys(menuItems, location.pathname);
       setOpenKeys((currentKeys) => [...new Set([...currentKeys, ...routeOpenKeys])]);
     }
-  }, [location.pathname, menuItems]);
+  }, [location.pathname, menuItems, setOpenKeys]);
 
   const handleOpenChange = useCallback((keys: string[]) => {
     setOpenKeys(keys);
-  }, []);
+  }, [setOpenKeys]);
 
-  const transformToMenuItems = (items: AppMenuItem[]): any[] => {
+  const transformToMenuItems = useCallback((items: AppMenuItem[]): any[] => {
     return items.map((item) => ({
       key: item.key,
       icon: item.icon ? iconMap[item.icon] : undefined,
       label: item.label,
       children: item.children ? transformToMenuItems(item.children) : undefined,
     }));
-  };
+  }, []);
   const menuContent = useMemo(
     () => (
       <Menu
@@ -193,7 +276,7 @@ const MainLayout: React.FC = () => {
         style={{ border: 'none' }}
       />
     ),
-    [selectedKeys, openKeys, menuItems, handleMenuClick],
+    [selectedKeys, openKeys, menuItems, handleMenuClick, handleOpenChange, transformToMenuItems],
   );
 
   return (
@@ -219,7 +302,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>
@@ -232,7 +325,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>
@@ -262,9 +360,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={{
@@ -285,7 +401,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>
@@ -305,9 +421,19 @@ 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>
+      )}
+      <BackTop />
     </Layout>
   );
 };

apps/admin/src/main.tsx

@@ -1,11 +1,16 @@
 import React from 'react';
 import ReactDOM from 'react-dom/client';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { queryClient } from './api/queryClient';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 import App from './App';
+import AppErrorBoundary from './components/AppErrorBoundary';
 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 +20,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 +30,16 @@ dayjs.extend(updateLocale);
 // 必须在所有插件加载后设置 locale
 dayjs.locale('zh-cn');
 
-ReactDOM.createRoot(document.getElementById('root')!).render(
+const rootElement = document.getElementById('root');
+if (!rootElement) throw new Error('未找到 #root 挂载点');
+
+ReactDOM.createRoot(rootElement).render(
   <React.StrictMode>
-    <App />
+    <AppErrorBoundary>
+      <QueryClientProvider client={queryClient}>
+        <App />
+        {import.meta.env.DEV && <ReactQueryDevtools initialIsOpen={false} />}
+      </QueryClientProvider>
+    </AppErrorBoundary>
   </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"
+        title="配置预览"
+        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');
     });
   });
 });