feat: implement utility recharge feature with CRUD operations and balance management

- Added UtilityRecharge entity to manage utility recharge records.
- Created DTO for utility recharge with validation.
- Developed UtilityBalancesService to handle business logic for utility recharges and balances.
- Implemented UtilityBalancesController for API endpoints related to utility recharges.
- Introduced utility balance management in BillsService to reflect utility charges in bills.
- Updated DepositsService to include personal expense amounts in deposit records.
- Created frontend page for managing utility balances and recharges with Ant Design components.
- Refactored existing bill generation logic to exclude personal expenses and integrate utility charges.
- Updated tests to cover new utility recharge functionality and ensure existing features remain intact.

apps/admin/src/App.tsx

@@ -13,6 +13,7 @@ const StudentsPage = lazy(() => import('./pages/Students'));
 const RoomsPage = lazy(() => import('./pages/Rooms'));
 const OccupanciesPage = lazy(() => import('./pages/Occupancies'));
 const ExpensesPage = lazy(() => import('./pages/Expenses'));
+const UtilityBalancesPage = lazy(() => import('./pages/UtilityBalances'));
 const BillsPage = lazy(() => import('./pages/Bills'));
 const RoomVisualPage = lazy(() => import('./pages/RoomVisual'));
 const OperationLogsPage = lazy(() => import('./pages/OperationLogs'));
@@ -126,6 +127,14 @@ const App: React.FC = () => {
                   </PermissionRoute>
                 }
               />
+              <Route
+                path="utility-balances"
+                element={
+                  <PermissionRoute permission="expense:view">
+                    <UtilityBalancesPage />
+                  </PermissionRoute>
+                }
+              />
               <Route
                 path="deposits"
                 element={

apps/admin/src/api/index.ts

@@ -16,7 +16,10 @@ instance.interceptors.request.use((config) => {
 instance.interceptors.response.use(
   (res) => res.data,
   (err) => {
-    if (err.response?.status === 401) {
+    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');

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

@@ -72,6 +72,7 @@ const SECTIONS: MenuSection[] = [
       { 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: '/utility-balances', label: '水电余额', icon: 'utility', permission: 'expense:view' },
       { key: '/bills', label: '账单管理', icon: 'bill', permission: 'bill:view' },
       { key: '/deposits', label: '押金管理', icon: 'deposit', permission: 'deposit:view' },
     ],

apps/admin/src/components/NotificationBell.tsx

@@ -3,6 +3,7 @@ import { Badge, Popover, Button, List, Typography, Empty } from 'antd';
 import { BellOutlined } from '@ant-design/icons';
 import { useNavigate } from 'react-router-dom';
 import api from '../api';
+import { formatNotificationText, notificationTypeLabels } from '../utils/notification-display';
 
 interface NotificationItem {
   id: number;
@@ -14,18 +15,6 @@ interface NotificationItem {
   createdAt: string;
 }
 
-const typeLabels: Record<string, string> = {
-  bill_generated: '账单',
-  bill_paid: '账单',
-  check_in: '入住',
-  check_out: '退宿',
-  deposit_due: '押金',
-  deposit_refunded: '押金',
-  class_change: '班级',
-  schedule_conflict: '排课',
-  announcement: '公告',
-};
-
 function timeAgo(dateStr: string): string {
   const diff = Date.now() - new Date(dateStr).getTime();
   const mins = Math.floor(diff / 60000);
@@ -163,7 +152,7 @@ const NotificationBell: React.FC = () => {
                     strong={!item.isRead}
                     style={{ fontSize: 14 }}
                   >
-                    [{typeLabels[item.type] || item.type}] {item.title}
+                    [{notificationTypeLabels[item.type] || item.type}] {formatNotificationText(item.title)}
                   </Typography.Text>
                 }
                 description={

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

@@ -321,7 +321,11 @@ const EnrollmentsTab: React.FC<TabProps & { data: EnrollmentRecord[] }> = ({
         columns={columns}
         dataSource={data}
         rowKey="id"
-        pagination={{ pageSize: 15 }}
+        pagination={{
+          defaultPageSize: 15,
+          showSizeChanger: true,
+          pageSizeOptions: [15, 30, 50],
+        }}
       />
       <Modal
         title="添加报读记录"
@@ -428,7 +432,11 @@ const ExamScoresTab: React.FC<TabProps & { data: ExamScoreRecord[]; enrollments:
         columns={columns}
         dataSource={data}
         rowKey="id"
-        pagination={{ pageSize: 15 }}
+        pagination={{
+          defaultPageSize: 15,
+          showSizeChanger: true,
+          pageSizeOptions: [15, 30, 50],
+        }}
       />
       <Modal
         title="添加考试成绩"
@@ -529,7 +537,11 @@ const LearningTab: React.FC<TabProps & { data: LearningRecord[] }> = ({ data, st
         columns={columns}
         dataSource={data}
         rowKey="id"
-        pagination={{ pageSize: 15 }}
+        pagination={{
+          defaultPageSize: 15,
+          showSizeChanger: true,
+          pageSizeOptions: [15, 30, 50],
+        }}
       />
       <Modal
         title="添加学情记录"
@@ -712,7 +724,11 @@ const AttachmentsTab: React.FC<TabProps & { data: AttachmentRecord[] }> = ({ dat
         columns={columns}
         dataSource={data}
         rowKey="id"
-        pagination={{ pageSize: 15 }}
+        pagination={{
+          defaultPageSize: 15,
+          showSizeChanger: true,
+          pageSizeOptions: [15, 30, 50],
+        }}
         style={{ marginTop: 16 }}
       />
     </div>

apps/admin/src/layouts/MainLayout.tsx

@@ -49,6 +49,7 @@ const iconMap: Record<string, React.ReactNode> = {
   overview: <AppstoreOutlined />,
   occupancy: <SwapOutlined />,
   expense: <DollarOutlined />,
+  utility: <WalletOutlined />,
   bill: <FileTextOutlined />,
   deposit: <WalletOutlined />,
   classroom: <ReadOutlined />,

apps/admin/src/pages/Attendance/attendance-workspace.integration.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import {
   canPullAttendance,
   getAttendanceExperience,
+  getPunchDisplayInfo,
   getSchedulePhase,
   summarizeAttendance,
   summarizeLessonCheckins,
@@ -65,3 +66,34 @@ describe('lesson check-in summary', () => {
     ).toEqual({ total: 4, checkedIn: 2, notCheckedIn: 2 });
   });
 });
+
+
+describe('lesson punch device display', () => {
+  it('labels attendance machine punches with the machine name and id', () => {
+    expect(
+      getPunchDisplayInfo({
+        status: 'present',
+        source: 'dingtalk',
+        punchSource: 'ATM',
+        punchDeviceName: '东门考勤机',
+        punchDeviceId: 'ATM-01',
+        punchTime: '2026-07-11T00:55:00.000Z',
+      }),
+    ).toEqual({
+      label: '考勤机打卡',
+      machine: true,
+      detail: '东门考勤机（ATM-01）',
+      time: '2026-07-11T00:55:00.000Z',
+    });
+  });
+
+  it('distinguishes mobile punches and manual teacher markings', () => {
+    expect(
+      getPunchDisplayInfo({ status: 'present', source: 'dingtalk', punchSource: 'USER' }),
+    ).toEqual({ label: '手机打卡', machine: false, detail: undefined, time: undefined });
+    expect(getPunchDisplayInfo({ status: 'present', source: 'manual' })).toEqual({
+      label: '老师手动标记',
+      machine: false,
+    });
+  });
+});

apps/admin/src/pages/Attendance/attendance-workspace.ts

@@ -82,3 +82,56 @@ export function summarizeLessonCheckins(
     notCheckedIn: records.length - checkedIn,
   };
 }
+
+
+export interface PunchDisplayRecord {
+  status: string;
+  source?: string;
+  punchTime?: string | null;
+  punchSource?: string | null;
+  punchDeviceName?: string | null;
+  punchDeviceId?: string | null;
+}
+
+export interface PunchDisplayInfo {
+  label: string;
+  machine: boolean;
+  detail?: string;
+  time?: string;
+}
+
+export function getPunchDisplayInfo(record: PunchDisplayRecord): PunchDisplayInfo | null {
+  if (record.status !== 'present' && record.status !== 'late') return null;
+  if (record.source === 'manual') return { label: '老师手动标记', machine: false };
+
+  const source = (record.punchSource || '').trim().toUpperCase();
+  const machine = ['ATM', 'ATTENDANCE_MACHINE', 'MACHINE', 'DEVICE'].some(
+    (value) => source === value || source.includes(value),
+  );
+  const label = machine
+    ? '考勤机打卡'
+    : source === 'USER'
+      ? '手机打卡'
+      : source.includes('BEACON') || source.includes('BLE')
+        ? '蓝牙打卡'
+        : source.includes('WIFI')
+          ? 'Wi-Fi 打卡'
+          : source.includes('APPROVE')
+            ? '审批补卡'
+            : source
+              ? `其他打卡（${record.punchSource}）`
+              : '打卡来源未知';
+  const device = record.punchDeviceName?.trim();
+  const deviceId = record.punchDeviceId?.trim();
+  const detail = device
+    ? deviceId && deviceId !== device
+      ? `${device}（${deviceId}）`
+      : device
+    : deviceId || undefined;
+  return {
+    label,
+    machine,
+    detail,
+    time: record.punchTime || undefined,
+  };
+}

apps/admin/src/pages/Attendance/attendance.css

@@ -502,3 +502,25 @@
 .attendance-marking-actions .ant-btn {
   min-width: 54px;
 }
+
+
+.punch-device-cell {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 4px;
+}
+
+.punch-device-cell .ant-tag {
+  margin-inline-end: 0;
+}
+
+.punch-device-cell strong {
+  color: #1f2937;
+  font-size: 13px;
+}
+
+.punch-device-cell span {
+  color: #8c8c8c;
+  font-size: 12px;
+}

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

@@ -41,6 +41,7 @@ import { message } from '../../ui/app-message';
 import {
   canPullAttendance,
   getAttendanceExperience,
+  getPunchDisplayInfo,
   getSchedulePhase,
   summarizeLessonCheckins,
   type AttendanceSummary,
@@ -96,6 +97,10 @@ interface AttendanceRecordItem {
   class: { id: number; name: string } | null;
   scheduleId?: number | null;
   attendanceSessionId?: number | null;
+  punchTime?: string | null;
+  punchSource?: string | null;
+  punchDeviceName?: string | null;
+  punchDeviceId?: string | null;
 }
 
 interface AssignedClass {
@@ -288,6 +293,7 @@ const TeacherAttendanceWorkspace: React.FC = () => {
         `/attendance-lessons/schedules/${schedule.id}/pull`,
         { date: today },
       );
+      setSelectedSchedule(data.schedule);
       setLessonSession(data.session);
       setLessonRecords(data.records);
       message.success('钉钉打卡已更新；课程截止后系统将自动结算');
@@ -386,7 +392,7 @@ const TeacherAttendanceWorkspace: React.FC = () => {
         )}
       </Spin>
 
-      <Drawer open={drawerOpen} onClose={() => setDrawerOpen(false)} width={820} title={null} className="attendance-drawer">
+      <Drawer open={drawerOpen} onClose={() => setDrawerOpen(false)} width={960} title={null} className="attendance-drawer">
         <div className="lesson-record-header">
           <span className="attendance-eyebrow">LESSON ATTENDANCE</span>
           <h2>{selectedSchedule?.subject || '课程考勤'}</h2>
@@ -438,6 +444,21 @@ const TeacherAttendanceWorkspace: React.FC = () => {
               },
             },
             { title: '当前状态', dataIndex: 'status', width: 105, render: (value: string) => <AttendanceStatusTag status={value === 'present' || value === 'late' ? 'present' : 'absent'} /> },
+            {
+              title: '打卡设备',
+              width: 220,
+              render: (_: unknown, record: AttendanceRecordItem) => {
+                const info = getPunchDisplayInfo(record);
+                if (!info) return <span className="muted-text">—</span>;
+                return (
+                  <div className="punch-device-cell">
+                    <Tag color={info.machine ? 'green' : 'blue'}>{info.label}</Tag>
+                    {info.detail && <strong>{info.detail}</strong>}
+                    {info.time && <span>{dayjs(info.time).format('HH:mm:ss')}</span>}
+                  </div>
+                );
+              },
+            },
             { title: '备注', dataIndex: 'remark', render: (value: string | null) => value || <span className="muted-text">—</span> },
           ]}
         />

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

@@ -10,7 +10,6 @@ import {
   Popconfirm,
   Input,
   Select,
-  Tooltip,
   Spin,
   Empty,
 } from 'antd';
@@ -35,14 +34,166 @@ const statusMap: Record<string, { text: string; color: string }> = {
 };
 
 const typeMap: Record<string, string> = {
-  water: '水费',
-  electricity: '电费',
+  utility: '水电费',
   cleaning: '保洁费',
+  rent: '租金',
   damage: '损坏赔偿',
   penalty: '罚款',
   other: '其他',
 };
 
+const escapeHtml = (value: unknown) =>
+  String(value ?? '')
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+
+const money = (value: unknown) => `¥${Number(value || 0).toFixed(2)}`;
+
+const buildBillPrintHtml = (bill: any) => {
+  const studentName = bill.student?.name || '-';
+  const status = statusMap[bill.status]?.text || bill.status || '-';
+  const generatedAt = bill.generatedAt
+    ? dayjs(bill.generatedAt).format('YYYY-MM-DD HH:mm')
+    : dayjs().format('YYYY-MM-DD HH:mm');
+  const items = bill.items || [];
+
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8" />
+  <title>账单_${escapeHtml(studentName)}_${escapeHtml(bill.id)}</title>
+  <style>
+    @page { size: A4; margin: 0; }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      color: #000;
+      background: #f5f5f5;
+      font-family: "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", Arial, sans-serif;
+      -webkit-print-color-adjust: exact;
+      print-color-adjust: exact;
+    }
+    .page {
+      width: 210mm;
+      min-height: 297mm;
+      margin: 0 auto;
+      padding: 50px;
+      background: #fff;
+    }
+    h1 { margin: 0; text-align: center; font-size: 20px; line-height: 1.35; font-weight: 700; }
+    .generated-time { margin-top: 8px; text-align: center; color: #666; font-size: 10px; }
+    .basic-info { margin-top: 24px; font-size: 12px; line-height: 1.8; }
+    .section-title { margin: 16px 0 6px; font-size: 14px; font-weight: 700; text-decoration: underline; }
+    .amount-summary { font-size: 12px; line-height: 1.75; }
+    .total { color: #007aff; font-size: 14px; font-weight: 700; }
+    .balance { color: #52c41a; font-size: 11px; }
+    .balance-after { color: #fa541c; font-size: 12px; font-weight: 700; }
+    .shortage { color: #ff4d4f; font-size: 12px; font-weight: 700; }
+    table { width: 100%; border-collapse: collapse; table-layout: fixed; margin-top: 8px; }
+    th, td { padding: 5px 6px; border-bottom: 1px solid #ccc; font-size: 9px; line-height: 1.45; text-align: left; vertical-align: top; word-break: break-word; }
+    th { color: #333; font-weight: 700; }
+    td.amount, th.amount { text-align: right; white-space: nowrap; }
+    .footer { margin-top: 34px; text-align: center; color: #999; font-size: 8px; }
+    .print-actions {
+      position: fixed;
+      right: 18px;
+      top: 18px;
+      display: flex;
+      gap: 8px;
+    }
+    .print-actions button {
+      height: 32px;
+      padding: 0 12px;
+      border: 1px solid #1f6feb;
+      border-radius: 4px;
+      background: #1f6feb;
+      color: #fff;
+      cursor: pointer;
+    }
+    @media print {
+      body { background: #fff; }
+      .page { margin: 0; }
+      .print-actions { display: none; }
+    }
+  </style>
+</head>
+<body>
+  <div class="print-actions">
+    <button onclick="window.print()">打印 / 另存为 PDF</button>
+  </div>
+  <main class="page">
+    <h1>恭学教育基地水电费账单</h1>
+    <div class="generated-time">生成时间: ${escapeHtml(generatedAt)}</div>
+
+    <div class="basic-info">
+      <div>学生姓名: ${escapeHtml(studentName)}</div>
+      <div>计费周期: ${escapeHtml(bill.periodStart)} ~ ${escapeHtml(bill.periodEnd)}</div>
+      <div>账单状态: ${escapeHtml(status)}</div>
+    </div>
+
+    <section>
+      <div class="section-title">费用汇总</div>
+      <div class="amount-summary">
+        <div>分摊费用: ${escapeHtml(money(bill.sharedAmount))}</div>
+        <div class="total">应付总额: ${escapeHtml(money(bill.totalAmount))}</div>
+        <div class="balance">当前水电余额: ${escapeHtml(money(bill.utilityBalance))}</div>
+        <div class="balance-after">扣本账单后余额: ${escapeHtml(money(bill.utilityBalanceAfterBill))}</div>
+        ${
+          Number(bill.utilityShortageAmount || 0) > 0
+            ? `<div class="shortage">需补缴: ${escapeHtml(money(bill.utilityShortageAmount))}</div>`
+            : ''
+        }
+      </div>
+    </section>
+
+    <section>
+      <div class="section-title">费用明细</div>
+      <table>
+        <thead>
+          <tr>
+            <th style="width: 22%;">费用类型</th>
+            <th>说明</th>
+            <th style="width: 11%;">天数</th>
+            <th style="width: 12%;">总人天</th>
+            <th class="amount" style="width: 16%;">金额(元)</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${
+            items.length
+              ? items
+                  .map(
+                    (item: any) => `<tr>
+              <td>${escapeHtml(typeMap[item.expenseType] || item.expenseType || '-')}</td>
+              <td>${escapeHtml(item.description || '-')}</td>
+              <td>${escapeHtml(item.days || 0)}</td>
+              <td>${escapeHtml(item.totalRoomDays || 0)}</td>
+              <td class="amount">${escapeHtml(Number(item.studentAmount || 0).toFixed(2))}</td>
+            </tr>`,
+                  )
+                  .join('')
+              : '<tr><td colspan="5" style="text-align:center; color:#999;">暂无费用明细</td></tr>'
+          }
+        </tbody>
+      </table>
+    </section>
+
+    <div class="footer">
+      本账单由恭学教育基地管理系统自动生成
+    </div>
+  </main>
+  <script>
+    window.addEventListener('load', () => {
+      setTimeout(() => window.print(), 250);
+    });
+  </script>
+</body>
+</html>`;
+};
+
 const BillsPage: React.FC = () => {
   const [bills, setBills] = useState<any[]>([]);
   const [loading, setLoading] = useState(false);
@@ -89,9 +240,11 @@ const BillsPage: React.FC = () => {
   }, [bills, searchText, filterStatus]);
 
   const handleGenerate = async () => {
-    setSaving(true);
-    const values = await generateForm.validateFields();
+    if (saving) return;
+
     try {
+      const values = await generateForm.validateFields();
+      setSaving(true);
       const res: any = await api.post('/bills/generate', {
         periodStart: values.period[0].format('YYYY-MM-DD'),
         periodEnd: values.period[1].format('YYYY-MM-DD'),
@@ -99,9 +252,12 @@ const BillsPage: React.FC = () => {
       message.success(res.message || '生成成功');
       setGenerateModal(false);
       generateForm.resetFields();
-      fetchData();
+      void fetchData();
     } catch (e: any) {
-      message.error(e?.message || '生成失败');
+      // Ant Design 的表单校验失败会 reject；字段本身已展示错误，无需再弹“生成失败”。
+      if (!e?.errorFields) {
+        message.error(e?.message || '生成失败');
+      }
     } finally {
       setSaving(false);
     }
@@ -181,11 +337,24 @@ const BillsPage: React.FC = () => {
     );
   };
 
-  const handleExportPdf = (billId: number) => {
-    downloadBlob(`/bills/export/pdf/${billId}`, `账单_${billId}.pdf`).catch(() =>
-      message.error('导出失败'),
-    );
-  };
+  const handleExportPdf = useCallback(async (billId: number) => {
+    const printWindow = window.open('', '_blank');
+    if (!printWindow) {
+      message.error('无法打开打印窗口，请允许浏览器弹窗后重试');
+      return;
+    }
+
+    printWindow.document.write('<!doctype html><title>账单加载中</title><body>账单加载中...</body>');
+    try {
+      const bill = await api.get(`/bills/${billId}`);
+      printWindow.document.open();
+      printWindow.document.write(buildBillPrintHtml(bill));
+      printWindow.document.close();
+    } catch (e: any) {
+      printWindow.close();
+      message.error(e?.message || '账单数据加载失败');
+    }
+  }, []);
 
   const columns = useMemo(() => [
     { title: '学生', width: 120, render: (_: any, r: any) => r.student?.name || '-' },
@@ -197,13 +366,6 @@ const BillsPage: React.FC = () => {
       align: 'right' as const,
       render: (v: number) => `¥${Number(v).toFixed(2)}`,
     },
-    {
-      title: '个人费用',
-      dataIndex: 'personalAmount',
-      width: 120,
-      align: 'right' as const,
-      render: (v: number) => `¥${Number(v).toFixed(2)}`,
-    },
     {
       title: '总计',
       dataIndex: 'totalAmount',
@@ -212,32 +374,39 @@ const BillsPage: React.FC = () => {
       render: (v: number) => <strong>¥{Number(v).toFixed(2)}</strong>,
     },
     {
-      title: '可用押金',
-      dataIndex: 'availableDeposit',
-      width: 120,
+      title: '当前水电余额',
+      dataIndex: 'utilityBalance',
+      width: 130,
+      align: 'right' as const,
+      render: (v: number) => (
+        <span style={{ color: Number(v || 0) < 0 ? '#ff4d4f' : '#52c41a' }}>
+          ¥{Number(v || 0).toFixed(2)}
+        </span>
+      ),
+    },
+    {
+      title: '扣本账单后余额',
+      dataIndex: 'utilityBalanceAfterBill',
+      width: 150,
+      align: 'right' as const,
+      render: (v: number) => (
+        <strong style={{ color: Number(v || 0) < 0 ? '#ff4d4f' : '#52c41a' }}>
+          ¥{Number(v || 0).toFixed(2)}
+        </strong>
+      ),
+    },
+    {
+      title: '需补缴',
+      dataIndex: 'utilityShortageAmount',
+      width: 110,
+      align: 'right' as const,
       render: (v: number) =>
-        v > 0 ? (
-          <span style={{ color: '#52c41a' }}>¥{Number(v).toFixed(2)}</span>
+        Number(v || 0) > 0 ? (
+          <strong style={{ color: '#ff4d4f' }}>¥{Number(v).toFixed(2)}</strong>
         ) : (
           <span style={{ color: '#999' }}>-</span>
         ),
     },
-    {
-      title: '抵扣后应付',
-      dataIndex: 'amountAfterDeposit',
-      width: 130,
-      render: (v: number, r: any) => {
-        const has = Number(r.availableDeposit || 0) > 0;
-        if (!has) return <span style={{ color: '#999' }}>-</span>;
-        const after = Number(v ?? r.totalAmount).toFixed(2);
-        const applied = Number(r.depositApplied || 0).toFixed(2);
-        return (
-          <Tooltip title={`已抵扣押金 ¥${applied}`}>
-            <strong style={{ color: '#fa541c' }}>¥{after}</strong>
-          </Tooltip>
-        );
-      },
-    },
     {
       title: '状态',
       dataIndex: 'status',
@@ -339,7 +508,7 @@ const BillsPage: React.FC = () => {
             ]}
           />
           <Select placeholder="费用类型" allowClear style={{ width: 120 }} value={filterExpenseType} onChange={setFilterExpenseType}
-            options={[{value:'water',label:'水费'},{value:'electricity',label:'电费'},{value:'cleaning',label:'保洁费'},{value:'rent',label:'租金'},{value:'other',label:'其他'}]} />
+            options={[{value:'utility',label:'水电费'},{value:'cleaning',label:'保洁费'},{value:'rent',label:'租金'},{value:'other',label:'其他'}]} />
           <PermissionButton
             permission="bill:confirm"
             onClick={() => batchUpdateStatus('confirmed')}
@@ -399,7 +568,12 @@ const BillsPage: React.FC = () => {
         dataSource={filteredBills}
         rowKey="id"
         loading={loading}
-        pagination={{ pageSize: 15, showTotal: (total) => `共 ${total} 条` }}
+        pagination={{
+          defaultPageSize: 15,
+          showSizeChanger: true,
+          pageSizeOptions: [15, 30, 50, 100],
+          showTotal: (total) => `共 ${total} 条`,
+        }}
         locale={{ emptyText: <Empty description="暂无数据" /> }}
         rowSelection={{
           selectedRowKeys: selectedRows,
@@ -456,51 +630,45 @@ const BillsPage: React.FC = () => {
               <Descriptions.Item label="分摊费用">
                 ¥{Number(detailModal.sharedAmount).toFixed(2)}
               </Descriptions.Item>
-              <Descriptions.Item label="个人费用">
-                ¥{Number(detailModal.personalAmount).toFixed(2)}
-              </Descriptions.Item>
               <Descriptions.Item label="合计" span={2}>
                 <strong style={{ fontSize: 18, color: '#007AFF' }}>
                   ¥{Number(detailModal.totalAmount).toFixed(2)}
                 </strong>
               </Descriptions.Item>
             </Descriptions>
-            {Number(detailModal.availableDeposit || 0) > 0 && (
-              <div
-                style={{
-                  marginBottom: 16,
-                  padding: 12,
-                  background: '#f6ffed',
-                  border: '1px solid #b7eb8f',
-                  borderRadius: 8,
-                }}
-              >
-                <div style={{ fontSize: 13, color: '#666', marginBottom: 6 }}>
-                  押金联动（不影响实际押金状态，仅作收款参考）
-                </div>
-                <Space size={24} wrap>
+            <div
+              style={{
+                marginBottom: 16,
+                padding: 12,
+                background: '#f6ffed',
+                border: '1px solid #b7eb8f',
+                borderRadius: 8,
+              }}
+            >
+              <div style={{ fontSize: 13, color: '#666', marginBottom: 6 }}>水电余额</div>
+              <Space size={24} wrap>
+                <span>
+                  当前余额：
+                  <strong style={{ color: Number(detailModal.utilityBalance || 0) < 0 ? '#ff4d4f' : '#52c41a' }}>
+                    ¥{Number(detailModal.utilityBalance || 0).toFixed(2)}
+                  </strong>
+                </span>
+                <span>
+                  扣本账单后余额：
+                  <strong style={{ color: Number(detailModal.utilityBalanceAfterBill || 0) < 0 ? '#ff4d4f' : '#52c41a', fontSize: 16 }}>
+                    ¥{Number(detailModal.utilityBalanceAfterBill || 0).toFixed(2)}
+                  </strong>
+                </span>
+                {Number(detailModal.utilityShortageAmount || 0) > 0 && (
                   <span>
-                    当前可用押金：
-                    <strong style={{ color: '#52c41a' }}>
-                      ¥{Number(detailModal.availableDeposit).toFixed(2)}
+                    需补缴：
+                    <strong style={{ color: '#ff4d4f', fontSize: 16 }}>
+                      ¥{Number(detailModal.utilityShortageAmount || 0).toFixed(2)}
                     </strong>
                   </span>
-                  <span>
-                    本账单可抵扣：
-                    <strong style={{ color: '#fa8c16' }}>
-                      -¥{Number(detailModal.depositApplied || 0).toFixed(2)}
-                    </strong>
-                  </span>
-                  <span>
-                    抵扣后实付：
-                    <strong style={{ color: '#fa541c', fontSize: 16 }}>
-                      ¥
-                      {Number(detailModal.amountAfterDeposit ?? detailModal.totalAmount).toFixed(2)}
-                    </strong>
-                  </span>
-                </Space>
-              </div>
-            )}
+                )}
+              </Space>
+            </div>
             <h4>费用明细</h4>
             <Table
               scroll={{ x: 700 }}

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

@@ -19,6 +19,7 @@ interface ClassStudent {
   studentName: string;
   studentNo: string;
   joinDate: string;
+  leaveDate: string | null;
   status: string;
 }
 
@@ -305,6 +306,7 @@ const ClassDetailPage: React.FC = () => {
     { title: '姓名', dataIndex: 'studentName' },
     { title: '学号', dataIndex: 'studentNo' },
     { title: '加入日期', dataIndex: 'joinDate' },
+    { title: '离班日期', dataIndex: 'leaveDate', render: (v: string | null) => v || '-' },
     {
       title: '状态',
       dataIndex: 'status',
@@ -316,11 +318,12 @@ const ClassDetailPage: React.FC = () => {
     },
     {
       title: '操作',
-      render: (_: unknown, r: ClassStudent) => (
-        <Popconfirm title="确认移除？" onConfirm={() => handleRemoveStudent(r.studentId)}>
-          <PermissionButton permission="class:edit" size="small" danger>移除</PermissionButton>
-        </Popconfirm>
-      ),
+      render: (_: unknown, r: ClassStudent) =>
+        r.status === 'active' ? (
+          <Popconfirm title="确认移除？" onConfirm={() => handleRemoveStudent(r.studentId)}>
+            <PermissionButton permission="class:edit" size="small" danger>移除</PermissionButton>
+          </Popconfirm>
+        ) : null,
     },
   ];
 
@@ -527,7 +530,11 @@ const ClassDetailPage: React.FC = () => {
                   columns={studentColumns}
                   dataSource={students}
                   rowKey="id"
-                  pagination={{ pageSize: 20 }}
+                  pagination={{
+                    defaultPageSize: 20,
+                    showSizeChanger: true,
+                    pageSizeOptions: [20, 50, 100],
+                  }}
                 />
                 <Modal
                   title="添加学员"
@@ -571,7 +578,11 @@ const ClassDetailPage: React.FC = () => {
                   columns={teacherColumns}
                   dataSource={teachers}
                   rowKey="id"
-                  pagination={{ pageSize: 20 }}
+                  pagination={{
+                    defaultPageSize: 20,
+                    showSizeChanger: true,
+                    pageSizeOptions: [20, 50, 100],
+                  }}
                 />
                 <Modal
                   title="添加教师"
@@ -630,7 +641,11 @@ const ClassDetailPage: React.FC = () => {
                   columns={scheduleColumns}
                   dataSource={schedules}
                   rowKey="id"
-                  pagination={{ pageSize: 20 }}
+                  pagination={{
+                    defaultPageSize: 20,
+                    showSizeChanger: true,
+                    pageSizeOptions: [20, 50, 100],
+                  }}
                 />
               </div>
             ),

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

@@ -264,7 +264,11 @@ const ClassesPage: React.FC = () => {
         rowKey="id"
         loading={loading}
         locale={{ emptyText: <Empty description="暂无数据" /> }}
-        pagination={{ pageSize: 20 }}
+        pagination={{
+          defaultPageSize: 20,
+          showSizeChanger: true,
+          pageSizeOptions: [20, 50, 100],
+        }}
         scroll={{ x: 1100 }}
       />
 

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

@@ -15,7 +15,7 @@ import {
   Tooltip,
   Empty,
 } from 'antd';
-import { PlusOutlined, UploadOutlined, DeleteOutlined, FileTextOutlined } from '@ant-design/icons';
+import { PlusOutlined, UploadOutlined, DeleteOutlined, FileTextOutlined, StopOutlined, CheckOutlined } from '@ant-design/icons';
 import dayjs, { Dayjs } from 'dayjs';
 import api from '../../api';
 import { downloadBlob } from '../../utils/download';
@@ -39,6 +39,7 @@ const ClassroomRentalsPage: React.FC = () => {
   const [editing, setEditing] = useState<any>(null);
   const [form] = Form.useForm();
   const [filterMonth, setFilterMonth] = useState<Dayjs | null>(null);
+  const [filterStatus, setFilterStatus] = useState<string | undefined>();
   const [searchText, setSearchText] = useState('');
   const [saving, setSaving] = useState(false);
   const [unavailableDates, setUnavailableDates] = useState<Set<string>>(new Set());
@@ -48,20 +49,22 @@ const ClassroomRentalsPage: React.FC = () => {
   const selectedClassroomId = Form.useWatch('classroomId', form);
 
   const filteredData = useMemo(() => {
-    if (!searchText) return data;
-    const s = searchText.toLowerCase();
     return data.filter((r: any) => {
+      if (filterStatus && r.effectiveStatus !== filterStatus) return false;
+      if (!searchText) return true;
+      const s = searchText.toLowerCase();
       const matchClassroom = r.classroom?.name?.toLowerCase().includes(s);
       const matchOrganization = r.lesseeOrganization?.name?.toLowerCase().includes(s);
       return matchClassroom || matchOrganization;
     });
-  }, [data, searchText]);
+  }, [data, searchText, filterStatus]);
 
   const fetchData = async () => {
     setLoading(true);
     try {
       const params: any = {};
       if (filterMonth) params.month = filterMonth.format('YYYY-MM');
+      params.includeEnded = true;
       const res: any = await api.get('/classroom-rentals', { params });
       setData(res);
     } catch (e: any) {
@@ -215,6 +218,16 @@ const ClassroomRentalsPage: React.FC = () => {
     }
   };
 
+  const handleRentalAction = async (id: number, action: 'cancel' | 'end') => {
+    try {
+      await api.put(`/classroom-rentals/${id}/${action}`);
+      message.success(action === 'cancel' ? '租赁已取消' : '租赁已结束');
+      fetchData();
+    } catch (e: any) {
+      message.error(e?.message || '操作失败');
+    }
+  };
+
   const handleDownloadContract = async (id: number, filename?: string) => {
     try {
       await downloadBlob(`/classroom-rentals/${id}/contract`, filename || `contract-${id}.pdf`);
@@ -308,6 +321,19 @@ const ClassroomRentalsPage: React.FC = () => {
         width: 100,
         render: (v: any) => (v ? `¥${v}` : '-'),
       },
+      {
+        title: '状态',
+        dataIndex: 'effectiveStatus',
+        width: 90,
+        render: (status: string) => {
+          const config: Record<string, { text: string; color: string }> = {
+            active: { text: '进行中', color: 'green' },
+            ended: { text: '已结束', color: 'default' },
+            cancelled: { text: '已取消', color: 'red' },
+          };
+          return <Tag color={config[status]?.color}>{config[status]?.text || status}</Tag>;
+        },
+      },
       {
         title: '合同',
         width: 120,
@@ -364,21 +390,30 @@ const ClassroomRentalsPage: React.FC = () => {
         width: 150,
         render: (_: any, record: any) => (
           <Space>
-            <PermissionButton
-              permission="rental:edit"
-              size="small"
-              onClick={() => openEdit(record)}
-            >
-              编辑
-            </PermissionButton>
-            <Popconfirm
-              title="确定删除该租赁订单？合同文件将一并删除。"
-              onConfirm={() => handleDelete(record.id)}
-            >
-              <PermissionButton permission="rental:delete" size="small" danger>
-                删除
-              </PermissionButton>
-            </Popconfirm>
+            {record.effectiveStatus === 'active' && (
+              <>
+                <PermissionButton permission="rental:edit" size="small" onClick={() => openEdit(record)}>
+                  编辑
+                </PermissionButton>
+                <Popconfirm title="确定取消该租赁？" onConfirm={() => handleRentalAction(record.id, 'cancel')}>
+                  <PermissionButton permission="rental:edit" size="small" danger icon={<StopOutlined />}>
+                    取消
+                  </PermissionButton>
+                </Popconfirm>
+                {!dayjs(record.startDate).isAfter(dayjs(), 'day') && (
+                  <Popconfirm title="确定今天结束该租赁？" onConfirm={() => handleRentalAction(record.id, 'end')}>
+                    <PermissionButton permission="rental:edit" size="small" icon={<CheckOutlined />}>
+                      结束
+                    </PermissionButton>
+                  </Popconfirm>
+                )}
+              </>
+            )}
+            {record.effectiveStatus !== 'active' && (
+              <Popconfirm title="确定删除该租赁订单？合同文件将一并删除。" onConfirm={() => handleDelete(record.id)}>
+                <PermissionButton permission="rental:delete" size="small" danger>删除</PermissionButton>
+              </Popconfirm>
+            )}
           </Space>
         ),
       },
@@ -415,6 +450,18 @@ const ClassroomRentalsPage: React.FC = () => {
             allowClear
             format="YYYY-MM"
           />
+          <Select
+            placeholder="状态"
+            allowClear
+            style={{ width: 110 }}
+            value={filterStatus}
+            onChange={setFilterStatus}
+            options={[
+              { value: 'active', label: '进行中' },
+              { value: 'ended', label: '已结束' },
+              { value: 'cancelled', label: '已取消' },
+            ]}
+          />
         </Space>
         <PermissionButton
           permission="rental:create"
@@ -436,7 +483,12 @@ const ClassroomRentalsPage: React.FC = () => {
         rowKey="id"
         loading={loading}
         locale={{ emptyText: <Empty description="暂无数据" /> }}
-        pagination={{ pageSize: 15, showTotal: (total) => `共 ${total} 条` }}
+        pagination={{
+          defaultPageSize: 15,
+          showSizeChanger: true,
+          pageSizeOptions: [15, 30, 50, 100],
+          showTotal: (total) => `共 ${total} 条`,
+        }}
         scroll={{ x: 1200 }}
       />
       <Modal
@@ -459,7 +511,7 @@ const ClassroomRentalsPage: React.FC = () => {
               optionFilterProp="label"
               placeholder="选择教室"
               onChange={handleClassroomChange}
-              options={classrooms.map((c) => ({
+              options={classrooms.filter((c) => c.status === 'available').map((c) => ({
                 value: c.id,
                 label: `${c.building ? c.building + ' · ' : ''}${c.name}（${c.roomType}）`,
               }))}

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

@@ -61,7 +61,7 @@ const ClassroomsPage: React.FC = () => {
   const filteredData = useMemo(() => {
     let result = data;
     if (searchText) { const s = searchText.toLowerCase(); result = result.filter((d: Record<string, unknown>) => (typeof d.name === 'string' && d.name.toLowerCase().includes(s)) || (typeof d.building === 'string' && d.building.toLowerCase().includes(s))); }
-    if (filterStatus) result = result.filter((d: Record<string, unknown>) => d.status === filterStatus);
+    if (filterStatus) result = result.filter((d: Record<string, unknown>) => d.effectiveStatus === filterStatus);
     return result;
   }, [data, searchText, filterStatus]);
 
@@ -157,11 +157,11 @@ const ClassroomsPage: React.FC = () => {
     {
       title: '状态', width: 100,
       dataIndex: 'status',
-      render: (s: string, record: { currentUsage?: CurrentUsage | null }) => {
-        const effectiveStatus = record.currentUsage ? 'in_use' : s;
+      render: (_s: string, record: { effectiveStatus?: string; status: string; currentUsage?: CurrentUsage | null }) => {
+        const effectiveStatus = record.effectiveStatus || record.status;
         return (
           <Tooltip title={record.currentUsage ? `${record.currentUsage.title} (${record.currentUsage.startTime}-${record.currentUsage.endTime})` : undefined}>
-            <Tag color={statusMap[effectiveStatus]?.color}>{statusMap[effectiveStatus]?.text || s}</Tag>
+            <Tag color={statusMap[effectiveStatus]?.color}>{statusMap[effectiveStatus]?.text || effectiveStatus}</Tag>
           </Tooltip>
         );
       },
@@ -228,7 +228,7 @@ const ClassroomsPage: React.FC = () => {
               if (!e.target.value) setSearchText('');
             }}
           />
-          <Select placeholder="状态" allowClear style={{ width: 110 }} value={filterStatus} onChange={setFilterStatus} options={[{value:'available',label:'可用'},{value:'in_use',label:'使用中'},{value:'reserved',label:'已预留'},{value:'maintenance',label:'维护中'}]} />
+          <Select placeholder="状态" allowClear style={{ width: 110 }} value={filterStatus} onChange={setFilterStatus} options={[{value:'available',label:'可用'},{value:'in_use',label:'使用中'},{value:'reserved',label:'已预留'},{value:'maintenance',label:'维护中'},{value:'archived',label:'已归档'}]} />
           <Button
             type={showArchived ? 'primary' : 'default'}
             onClick={() => setShowArchived(!showArchived)}
@@ -287,7 +287,12 @@ const ClassroomsPage: React.FC = () => {
         rowKey="id"
         loading={loading}
         locale={{ emptyText: <Empty description="暂无数据" /> }}
-        pagination={{ pageSize: 20, showTotal: (total) => `共 ${total} 条` }}
+        pagination={{
+          defaultPageSize: 20,
+          showSizeChanger: true,
+          pageSizeOptions: [20, 50, 100],
+          showTotal: (total) => `共 ${total} 条`,
+        }}
       />
       <Modal
         title={editing ? '编辑教室' : '添加教室'}
@@ -323,6 +328,16 @@ const ClassroomsPage: React.FC = () => {
           <Form.Item name="capacity" label="容量">
             <InputNumber min={1} max={500} style={{ width: '100%' }} />
           </Form.Item>
+          {editing && (
+            <Form.Item name="status" label="基础状态">
+              <Select
+                options={[
+                  { value: 'available', label: '可用' },
+                  { value: 'maintenance', label: '维护中' },
+                ]}
+              />
+            </Form.Item>
+          )}
           <Form.Item name="notes" label="备注">
             <Input.TextArea rows={2} />
           </Form.Item>

apps/admin/src/pages/Deposits/deposit-student-option.integration.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { buildDepositStudentOption, buildDepositStudentOptions } from './deposit-student-option';
+
+describe('deposit student option', () => {
+  it('uses the student number as the non-sensitive identifier', () => {
+    expect(
+      buildDepositStudentOption({ id: 23, name: '张三', studentNo: 'S2026001' }),
+    ).toEqual({
+      value: 23,
+      label: '张三 (S2026001)',
+    });
+  });
+
+  it('falls back to the internal id when the student number is missing', () => {
+    expect(buildDepositStudentOption({ id: 23, name: '张三', studentNo: null })).toEqual({
+      value: 23,
+      label: '张三 (#23)',
+    });
+  });
+
+  it('uses lookup rows without requiring a status field', () => {
+    expect(buildDepositStudentOptions([{ id: 23, name: '张三', studentNo: 'S2026001' }])).toEqual([
+      {
+        value: 23,
+        label: '张三 (S2026001)',
+      },
+    ]);
+  });
+});

apps/admin/src/pages/Deposits/deposit-student-option.ts

@@ -0,0 +1,13 @@
+export interface DepositStudentLookup {
+  id: number;
+  name: string;
+  studentNo?: string | null;
+}
+
+export const buildDepositStudentOption = (student: DepositStudentLookup) => ({
+  value: student.id,
+  label: `${student.name} (${student.studentNo || `#${student.id}`})`,
+});
+
+export const buildDepositStudentOptions = (students: DepositStudentLookup[]) =>
+  students.map(buildDepositStudentOption);

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

@@ -17,9 +17,9 @@ import {
 import { PlusOutlined, DeleteOutlined, DollarOutlined } from '@ant-design/icons';
 import dayjs from 'dayjs';
 import api from '../../api';
-import { maskPhone, maskIdNumber } from '../../utils/sensitive';
 import PermissionButton from '../../components/PermissionButton';
 import { message } from '../../ui/app-message';
+import { buildDepositStudentOptions } from './deposit-student-option';
 
 const statusMap: Record<string, { text: string; color: string }> = {
   paid: { text: '已缴', color: 'green' },
@@ -28,18 +28,17 @@ const statusMap: Record<string, { text: string; color: string }> = {
   deducted: { text: '已全扣', color: 'red' },
 };
 
-const refundStatusMap: Record<string, { text: string; color: string }> = {
-  pending: { text: '历史退款处理中', color: 'orange' },
-  head_teacher_approved: { text: '历史退款处理中', color: 'blue' },
-  finance_approved: { text: '已退款', color: 'green' },
-  refunded: { text: '已退款', color: 'green' },
-};
-
 const installmentStatusMap: Record<string, { text: string; color: string }> = {
   pending: { text: '待缴', color: 'orange' },
   paid: { text: '已缴', color: 'green' },
 };
 
+const isFormValidationError = (error: unknown) =>
+  typeof error === 'object'
+  && error !== null
+  && Array.isArray((error as { errorFields?: unknown }).errorFields);
+
+const money = (value: unknown) => Number(Number(value || 0).toFixed(2));
 
 const DepositsPage: React.FC = () => {
   const [data, setData] = useState<any[]>([]);
@@ -89,20 +88,14 @@ const DepositsPage: React.FC = () => {
   }, [data, searchText, filterStatus]);
 
   const studentOptions = useMemo(
-    () =>
-      students
-        .filter((s: any) => s.status === 'active')
-        .map((s: any) => ({
-          value: s.id,
-          label: `${s.name} (${s.idNumber ? maskIdNumber(s.idNumber) : (s.phone ? maskPhone(s.phone) : '')})`,
-        })),
+    () => buildDepositStudentOptions(students),
     [students],
   );
 
   const handleCreate = async () => {
     setSaving(true);
-    const values = await createForm.validateFields();
     try {
+      const values = await createForm.validateFields();
       await api.post('/deposits', {
         studentId: values.studentId,
         amount: values.amount,
@@ -114,7 +107,9 @@ const DepositsPage: React.FC = () => {
       createForm.resetFields();
       fetchData();
     } catch (e: any) {
-      message.error(e?.message || '操作失败');
+      if (!isFormValidationError(e)) {
+        message.error(e?.message || '操作失败');
+      }
     } finally {
       setSaving(false);
     }
@@ -122,8 +117,8 @@ const DepositsPage: React.FC = () => {
 
   const handleRefund = async () => {
     setSaving(true);
-    const values = await refundForm.validateFields();
     try {
+      const values = await refundForm.validateFields();
       await api.put(`/deposits/${refundModal.id}/refund`, {
         refundDate: values.refundDate.format('YYYY-MM-DD'),
         deductionAmount: values.deductionAmount || 0,
@@ -135,7 +130,9 @@ const DepositsPage: React.FC = () => {
       refundForm.resetFields();
       fetchData();
     } catch (e: any) {
-      message.error(e?.message || '操作失败');
+      if (!isFormValidationError(e)) {
+        message.error(e?.message || '操作失败');
+      }
     } finally {
       setSaving(false);
     }
@@ -143,8 +140,8 @@ const DepositsPage: React.FC = () => {
 
   const handleAddInstallment = async () => {
     if (installmentModal == null) return;
-    const values = await installmentForm.validateFields();
     try {
+      const values = await installmentForm.validateFields();
       await api.post(`/deposits/${installmentModal}/installments`, {
         amount: values.amount,
         dueDate: values.dueDate.format('YYYY-MM-DD'),
@@ -154,7 +151,9 @@ const DepositsPage: React.FC = () => {
       installmentForm.resetFields();
       fetchData();
     } catch (e: any) {
-      message.error(e?.message || '操作失败');
+      if (!isFormValidationError(e)) {
+        message.error(e?.message || '操作失败');
+      }
     }
   };
 
@@ -190,12 +189,6 @@ const DepositsPage: React.FC = () => {
       dataIndex: 'status',
       render: (s: string) => <Tag color={statusMap[s]?.color}>{statusMap[s]?.text || s}</Tag>,
     },
-    {
-      title: '退款状态',
-      dataIndex: 'refundStatus',
-      render: (s: string) =>
-        s ? <Tag color={refundStatusMap[s]?.color}>{refundStatusMap[s]?.text || s}</Tag> : '-',
-    },
     {
       title: '退还金额',
       dataIndex: 'refundAmount',
@@ -223,15 +216,20 @@ const DepositsPage: React.FC = () => {
           >
             详情
           </PermissionButton>
-          {record.status === 'paid' && !record.refundStatus && (
+          {record.status === 'paid' && (
             <>
               <PermissionButton
                 permission="deposit:refund"
                 size="small"
                 type="primary"
                 onClick={() => {
+                  const personalExpenseAmount = money(record.personalExpenseAmount);
+                  const depositAmount = money(record.amount);
                   setRefundModal(record);
-                  refundForm.setFieldsValue({ refundDate: dayjs(), deductionAmount: 0 });
+                  refundForm.setFieldsValue({
+                    refundDate: dayjs(),
+                    deductionAmount: Math.min(personalExpenseAmount, depositAmount),
+                  });
                 }}
               >
                 退还
@@ -320,7 +318,12 @@ const DepositsPage: React.FC = () => {
     rowKey="id"
     loading={loading}
     scroll={{ x: 1200 }}
-    pagination={{ pageSize: 15, showTotal: (total) => `共 ${total} 条` }}
+    pagination={{
+      defaultPageSize: 15,
+      showSizeChanger: true,
+      pageSizeOptions: [15, 30, 50, 100],
+      showTotal: (total) => `共 ${total} 条`,
+    }}
     locale={{ emptyText: <Empty description="暂无数据" /> }}
   />
 
@@ -369,15 +372,25 @@ const DepositsPage: React.FC = () => {
       >
         <Form form={refundForm} layout="vertical">
           <div style={{ marginBottom: 16, padding: 12, background: '#f5f5f5', borderRadius: 8 }}>
-            押金金额: <strong>¥{Number(refundModal?.amount || 0).toFixed(2)}</strong>
+            <div>
+              押金金额: <strong>¥{money(refundModal?.amount).toFixed(2)}</strong>
+            </div>
+            <div style={{ marginTop: 4 }}>
+              个人附加费合计:{' '}
+              <strong>¥{money(refundModal?.personalExpenseAmount).toFixed(2)}</strong>
+            </div>
           </div>
           <Form.Item name="refundDate" label="退还日期" rules={[{ required: true }]}>
             <DatePicker style={{ width: '100%' }} placeholder="选择退还日期" format="YYYY-MM-DD" />
           </Form.Item>
-          <Form.Item name="deductionAmount" label="扣除金额（元）" extra="如无扣除填0">
+          <Form.Item
+            name="deductionAmount"
+            label="扣除金额（元）"
+            extra="自动填入该学生个人附加费用总和；超过押金金额时按押金金额封顶"
+          >
             <InputNumber
               min={0}
-              max={Number(refundModal?.amount || 500)}
+              max={money(refundModal?.amount || 500)}
               precision={2}
               style={{ width: '100%' }}
             />
@@ -410,14 +423,6 @@ const DepositsPage: React.FC = () => {
                   {statusMap[detailModal.status]?.text || detailModal.status}
                 </Tag>
               </p>
-              {detailModal.refundStatus && (
-                <p>
-                  <strong>退款状态:</strong>{' '}
-                  <Tag color={refundStatusMap[detailModal.refundStatus]?.color}>
-                    {refundStatusMap[detailModal.refundStatus]?.text || detailModal.refundStatus}
-                  </Tag>
-                </p>
-              )}
               {detailModal.notes && <p><strong>备注:</strong> {detailModal.notes}</p>}
             </Card>
 

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

@@ -31,6 +31,11 @@ import { message } from '../../ui/app-message';
 
 const { RangePicker } = DatePicker;
 
+const isFormValidationError = (error: unknown) =>
+  typeof error === 'object'
+  && error !== null
+  && Array.isArray((error as { errorFields?: unknown }).errorFields);
+
 
 
 const ExpensesPage: React.FC = () => {
@@ -157,16 +162,16 @@ const ExpensesPage: React.FC = () => {
 
   const handleRoomExpense = async () => {
     setSaving(true);
-    const values = await roomForm.validateFields();
-    const payload = {
-      roomId: values.roomId,
-      expenseType: values.expenseType,
-      amount: values.amount,
-      periodStart: values.period[0].format('YYYY-MM-DD'),
-      periodEnd: values.period[1].format('YYYY-MM-DD'),
-      description: values.description,
-    };
     try {
+      const values = await roomForm.validateFields();
+      const payload = {
+        roomId: values.roomId,
+        expenseType: values.expenseType,
+        amount: values.amount,
+        periodStart: values.period[0].format('YYYY-MM-DD'),
+        periodEnd: values.period[1].format('YYYY-MM-DD'),
+        description: values.description,
+      };
       if (editingRoom) {
         await api.put(`/expenses/room/${editingRoom.id}`, payload);
         message.success('更新成功');
@@ -179,7 +184,9 @@ const ExpensesPage: React.FC = () => {
       roomForm.resetFields();
       fetchData();
     } catch (e: any) {
-      message.error(e?.message || '操作失败');
+      if (!isFormValidationError(e)) {
+        message.error(e?.message || '操作失败');
+      }
     } finally {
       setSaving(false);
     }
@@ -187,16 +194,16 @@ const ExpensesPage: React.FC = () => {
 
   const handlePersonalExpense = async () => {
     setSaving(true);
-    const values = await personalForm.validateFields();
-    const payload = {
-      studentId: values.studentId,
-      roomId: values.roomId,
-      expenseType: values.expenseType,
-      amount: values.amount,
-      expenseDate: values.expenseDate.format('YYYY-MM-DD'),
-      description: values.description,
-    };
     try {
+      const values = await personalForm.validateFields();
+      const payload = {
+        studentId: values.studentId,
+        roomId: values.roomId,
+        expenseType: values.expenseType,
+        amount: values.amount,
+        expenseDate: values.expenseDate.format('YYYY-MM-DD'),
+        description: values.description,
+      };
       if (editingPersonal) {
         await api.put(`/expenses/personal/${editingPersonal.id}`, payload);
         message.success('更新成功');
@@ -209,7 +216,9 @@ const ExpensesPage: React.FC = () => {
       personalForm.resetFields();
       fetchData();
     } catch (e: any) {
-      message.error(e?.message || '操作失败');
+      if (!isFormValidationError(e)) {
+        message.error(e?.message || '操作失败');
+      }
     } finally {
       setSaving(false);
     }
@@ -443,7 +452,12 @@ const ExpensesPage: React.FC = () => {
                   rowKey="id"
                   loading={loading}
                   scroll={{ x: 1200 }}
-                  pagination={{ pageSize: 15, showTotal: (total) => `共 ${total} 条` }}
+                  pagination={{
+                    defaultPageSize: 15,
+                    showSizeChanger: true,
+                    pageSizeOptions: [15, 30, 50, 100],
+                    showTotal: (total) => `共 ${total} 条`,
+                  }}
                   locale={{ emptyText: <Empty description="暂无数据" /> }}
                   rowSelection={{
                     selectedRowKeys: selectedRoomKeys,
@@ -566,7 +580,12 @@ const ExpensesPage: React.FC = () => {
                   rowKey="id"
                   loading={loading}
                   scroll={{ x: 1200 }}
-                  pagination={{ pageSize: 15, showTotal: (total) => `共 ${total} 条` }}
+                  pagination={{
+                    defaultPageSize: 15,
+                    showSizeChanger: true,
+                    pageSizeOptions: [15, 30, 50, 100],
+                    showTotal: (total) => `共 ${total} 条`,
+                  }}
                   locale={{ emptyText: <Empty description="暂无数据" /> }}
                   rowSelection={{
                     selectedRowKeys: selectedPersonalKeys,

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

@@ -1,7 +1,7 @@
 import React, { useEffect, useState, useMemo, useCallback } from 'react';
 import {
-  Card, Form, Input, Button, Space, Spin, Switch, Alert, Descriptions, Tag,
-  Tabs, Drawer, Tree, Select, TreeSelect, Modal, DatePicker, InputNumber,
+  Card, Form, Input, Button, Space, Spin, Alert, Descriptions, Tag, Divider,
+  Drawer, Tree, Select, TreeSelect, Modal, DatePicker,
   Row, Col, List,
 } from 'antd';
 import {
@@ -15,12 +15,15 @@ import api from '../../api';
 import { message } from '../../ui/app-message';
 import { usePermission } from '../../hooks/usePermission';
 import PermissionButton from '../../components/PermissionButton';
+import {
+  buildDingTalkConfigPayload,
+  isAppSecretRequired,
+  type DingTalkConfigFormValues,
+} from './integration-config-form';
 
 interface DingTalkConfig {
   agentId: string;
-  appSecret: string;
   corpId: string;
-  startEnable: boolean;
 }
 
 interface DingOrgTreeNodeExt {
@@ -56,7 +59,6 @@ interface ClassItem {
   classType?: string;
   startDate?: string;
   endDate?: string;
-  maxStudents?: number;
   notes?: string;
 }
 
@@ -94,9 +96,9 @@ const IntegrationConfigPage: React.FC = () => {
   const [testing, setTesting] = useState(false);
   const [config, setConfig] = useState<DingTalkConfig | null>(null);
   const [verified, setVerified] = useState<boolean | null>(null);
-  const [form] = Form.useForm<DingTalkConfig>();
+  const [form] = Form.useForm<DingTalkConfigFormValues>();
 
-  // ── Sync Users Tab ──
+  // ── Manual organization sync ──
   const [syncRootDeptId, setSyncRootDeptId] = useState<number | undefined>(undefined);
   const [orgTree, setOrgTree] = useState<DingOrgTreeNodeExt[]>([]);
   const [drawerOpen, setDrawerOpen] = useState(false);
@@ -137,9 +139,10 @@ const IntegrationConfigPage: React.FC = () => {
 
   const handleSave = async () => {
     const values = await form.validateFields();
+    const payload = buildDingTalkConfigPayload(values);
     setSaving(true);
     try {
-      await api.post('/integration/config', { type: 'DINGTALK', config: values });
+      await api.post('/integration/config', { type: 'DINGTALK', config: payload });
       message.success('配置已保存');
       await fetchConfig();
     } catch (e: unknown) {
@@ -152,11 +155,12 @@ const IntegrationConfigPage: React.FC = () => {
 
   const handleTest = async () => {
     const values = await form.validateFields();
+    const payload = buildDingTalkConfigPayload(values);
     setTesting(true);
     try {
       const res = await api.post<{ success: boolean; message: string }>('/integration/config/test', {
         type: 'DINGTALK',
-        config: values,
+        config: payload,
       });
       setVerified(res.success);
       message.success(res.message);
@@ -345,12 +349,8 @@ const IntegrationConfigPage: React.FC = () => {
     }
   };
 
-  const syncTabItems = config && hasAllPermissions('sync:read', 'class:view', 'class:edit')
-    ? [
-        {
-          key: 'sync-users',
-          label: '同步用户',
-          children: (
+  const syncPanel = config && hasAllPermissions('sync:read', 'class:view', 'class:edit')
+    ? (
             <div>
               <Alert
                 type="info"
@@ -476,9 +476,6 @@ const IntegrationConfigPage: React.FC = () => {
                       <Form.Item name="endDate" label="结束日期">
                         <DatePicker style={{ width: '100%' }} />
                       </Form.Item>
-                      <Form.Item name="maxStudents" label="最大人数">
-                        <InputNumber min={0} style={{ width: '100%' }} placeholder="0=不限制" />
-                      </Form.Item>
                       <Form.Item name="notes" label="备注">
                         <Input.TextArea rows={2} />
                       </Form.Item>
@@ -519,77 +516,100 @@ const IntegrationConfigPage: React.FC = () => {
                 />
               </Modal>
             </div>
-          ),
-        },
-      ]
-    : [];
-
-  const tabItems = [
-    {
-      key: 'config',
-      label: '配置',
-      children: (
-        <Spin spinning={loading}>
-          {config && (
-            <Descriptions size="small" column={2} style={{ marginBottom: 24 }}>
-              <Descriptions.Item label="CorpId">{config.corpId || '-'}</Descriptions.Item>
-              <Descriptions.Item label="AppKey">{config.agentId || '-'}</Descriptions.Item>
-              <Descriptions.Item label="启用同步">
-                <Tag color={config.startEnable ? 'green' : 'default'}>
-                  {config.startEnable ? '已启用' : '未启用'}
-                </Tag>
-              </Descriptions.Item>
-            </Descriptions>
-          )}
-
-          <Alert
-            type="info"
-            message="配置钉钉应用凭证后，可使用组织架构同步、考勤导入和排班同步功能。"
-            style={{ marginBottom: 24 }}
-            showIcon
-          />
-
-          <Form form={form} layout="vertical" style={{ maxWidth: 480 }}>
-            <Form.Item name="corpId" label="CorpId（企业ID）" rules={[{ required: true, message: '请输入 CorpId' }]}>
-              <Input placeholder="dingxxxxxxxx" />
-            </Form.Item>
-            <Form.Item name="agentId" label="AppKey（应用凭证）" rules={[{ required: true, message: '请输入 AppKey' }]}>
-              <Input placeholder="从钉钉开放平台获取" />
-            </Form.Item>
-            <Form.Item
-              name="appSecret"
-              label="AppSecret（应用密钥）"
-              rules={[{ required: true, message: '请输入 AppSecret' }]}
-              extra="保存后仅返回脱敏信息，重新编辑时需再次输入完整密钥"
-            >
-              <Input.Password placeholder="从钉钉开放平台获取" />
-            </Form.Item>
-            <Form.Item name="startEnable" label="启用同步" valuePropName="checked">
-              <Switch />
-            </Form.Item>
-            <Space>
-              <PermissionButton permission="integration:trigger" type="primary" icon={<SaveOutlined />} loading={saving} onClick={handleSave}>
-                保存配置
-              </PermissionButton>
-              <Button icon={<ApiOutlined />} loading={testing} onClick={handleTest}>
-                测试连接
-              </Button>
-            </Space>
-          </Form>
-        </Spin>
-      ),
-    },
-    ...syncTabItems,
-  ];
+    )
+    : null;
 
   return (
-    <Card title="钉钉集成配置" extra={
-      <Space>
-        {verified === true && <Tag icon={<CheckCircleOutlined />} color="success">已连接</Tag>}
-        {verified === false && <Tag icon={<CloseCircleOutlined />} color="error">未连接</Tag>}
-      </Space>
-    }>
-      <Tabs items={tabItems} />
+    <Card
+      title="钉钉集成配置"
+      extra={
+        <Space>
+          {verified === true && (
+            <Tag icon={<CheckCircleOutlined />} color="success">
+              已连接
+            </Tag>
+          )}
+          {verified === false && (
+            <Tag icon={<CloseCircleOutlined />} color="error">
+              未连接
+            </Tag>
+          )}
+        </Space>
+      }
+    >
+      <Spin spinning={loading}>
+        {config && (
+          <Descriptions size="small" column={2} style={{ marginBottom: 24 }}>
+            <Descriptions.Item label="CorpId">{config.corpId || '-'}</Descriptions.Item>
+            <Descriptions.Item label="AppKey">{config.agentId || '-'}</Descriptions.Item>
+            <Descriptions.Item label="同步方式">手动触发</Descriptions.Item>
+          </Descriptions>
+        )}
+
+        <Alert
+          type="info"
+          message="配置钉钉应用凭证后，可在本页手动获取组织架构并导入用户。排班同步仍在排课管理中手动触发。"
+          style={{ marginBottom: 24 }}
+          showIcon
+        />
+
+        <Form form={form} layout="vertical" style={{ maxWidth: 520 }}>
+          <Form.Item
+            name="corpId"
+            label="CorpId（企业ID）"
+            rules={[{ required: true, message: '请输入 CorpId' }]}
+          >
+            <Input placeholder="dingxxxxxxxx" />
+          </Form.Item>
+          <Form.Item
+            name="agentId"
+            label="AppKey（应用凭证）"
+            rules={[{ required: true, message: '请输入 AppKey' }]}
+          >
+            <Input placeholder="从钉钉开放平台获取" />
+          </Form.Item>
+          <Form.Item
+            name="appSecret"
+            label="AppSecret（应用密钥）"
+            rules={[
+              {
+                required: isAppSecretRequired(!!config),
+                message: '首次配置请输入 AppSecret',
+              },
+            ]}
+            extra={
+              config
+                ? '已保存密钥；留空保持原值，输入新值将替换原密钥'
+                : '首次配置需要填写完整 AppSecret'
+            }
+          >
+            <Input.Password
+              placeholder={config ? '留空保持已保存的密钥' : '从钉钉开放平台获取'}
+            />
+          </Form.Item>
+          <Space>
+            <PermissionButton
+              permission="integration:trigger"
+              type="primary"
+              icon={<SaveOutlined />}
+              loading={saving}
+              onClick={handleSave}
+            >
+              保存配置
+            </PermissionButton>
+            <Button icon={<ApiOutlined />} loading={testing} onClick={handleTest}>
+              测试连接
+            </Button>
+          </Space>
+        </Form>
+
+        {syncPanel && (
+          <>
+            <Divider titlePlacement="start">组织用户导入</Divider>
+            {syncPanel}
+          </>
+        )}
+      </Spin>
     </Card>
   );
 };

apps/admin/src/pages/IntegrationConfig/integration-config-form.integration.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildDingTalkConfigPayload,
+  isAppSecretRequired,
+} from './integration-config-form';
+
+describe('DingTalk integration config form', () => {
+  it('requires AppSecret only for the first configuration', () => {
+    expect(isAppSecretRequired(false)).toBe(true);
+    expect(isAppSecretRequired(true)).toBe(false);
+  });
+
+  it('builds a manual-sync config without the retired startEnable flag', () => {
+    expect(
+      buildDingTalkConfigPayload({
+        corpId: 'ding-corp',
+        agentId: 'app-key',
+        appSecret: '',
+      }),
+    ).toEqual({
+      corpId: 'ding-corp',
+      agentId: 'app-key',
+      appSecret: undefined,
+    });
+  });
+});

apps/admin/src/pages/IntegrationConfig/integration-config-form.ts

@@ -0,0 +1,13 @@
+export interface DingTalkConfigFormValues {
+  agentId: string;
+  appSecret?: string;
+  corpId: string;
+}
+
+export const isAppSecretRequired = (hasSavedConfig: boolean) => !hasSavedConfig;
+
+export const buildDingTalkConfigPayload = (values: DingTalkConfigFormValues) => ({
+  corpId: values.corpId.trim(),
+  agentId: values.agentId.trim(),
+  appSecret: values.appSecret?.trim() || undefined,
+});

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

@@ -10,6 +10,7 @@ import {
 import { useNavigate } from 'react-router-dom';
 import api from '../../api';
 import { message } from '../../ui/app-message';
+import { formatNotificationText } from '../../utils/notification-display';
 
 const { Sider, Content } = Layout;
 
@@ -169,7 +170,7 @@ const NotificationsPage: React.FC = () => {
                             strong={!item.isRead}
                             style={{ fontSize: 15 }}
                           >
-                            {item.title}
+                            {formatNotificationText(item.title)}
                           </Typography.Text>
                           <Typography.Text type="secondary" style={{ fontSize: 12 }}>
                             {timeAgo(item.createdAt)}
@@ -183,7 +184,7 @@ const NotificationsPage: React.FC = () => {
                             ellipsis={{ rows: 1 }}
                             style={{ marginBottom: 0 }}
                           >
-                            {item.content}
+                            {formatNotificationText(item.content)}
                           </Typography.Paragraph>
                         )
                       }

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

@@ -32,6 +32,7 @@ import { downloadBlob } from '../../utils/download';
 import { maskPhone, maskIdNumber } from '../../utils/sensitive';
 import PermissionButton from '../../components/PermissionButton';
 import { message } from '../../ui/app-message';
+import { buildTransferPayload } from './occupancy-form';
 
 const { RangePicker } = DatePicker;
 
@@ -39,7 +40,6 @@ const OccupanciesPage: React.FC = () => {
   const [data, setData] = useState<any[]>([]);
   const [students, setStudents] = useState<any[]>([]);
   const [rooms, setRooms] = useState<any[]>([]);
-  const [organizations, setOrganizations] = useState<any[]>([]);
   const [loading, setLoading] = useState(false);
   const [checkInModal, setCheckInModal] = useState(false);
   const [checkOutModal, setCheckOutModal] = useState<any>(null);
@@ -59,18 +59,19 @@ const OccupanciesPage: React.FC = () => {
   const [batchCheckOutForm] = Form.useForm();
   const [availableBeds, setAvailableBeds] = useState<any[]>([]);
   const [availableLockers, setAvailableLockers] = useState<any[]>([]);
+  const [transferAvailableBeds, setTransferAvailableBeds] = useState<any[]>([]);
+  const [transferAvailableLockers, setTransferAvailableLockers] = useState<any[]>([]);
 
   const fetchData = useCallback(async () => {
     setLoading(true);
     try {
-      const [occRes, stuRes, rmRes, tnRes] = (await Promise.allSettled([
+      const [occRes, stuRes, rmRes] = (await Promise.allSettled([
         api.get('/occupancies', { params: { active: showActive ? 'true' : undefined, dateFrom: dateRange?.[0]?.format('YYYY-MM-DD'), dateTo: dateRange?.[1]?.format('YYYY-MM-DD') } }),
         api.get('/students/basic-lookups'),
         api.get('/rooms/overview'),
-        api.get('/organizations'),
       ])) as PromiseSettledResult<any>[];
-      const labels = ['入住数据', '学生列表', '房间列表', '机构列表'];
-      [occRes, stuRes, rmRes, tnRes].forEach((res, i) => {
+      const labels = ['入住数据', '学生列表', '房间列表'];
+      [occRes, stuRes, rmRes].forEach((res, i) => {
         if (res.status === 'rejected') {
           message.warning(`${labels[i]}加载失败`);
         }
@@ -78,7 +79,6 @@ const OccupanciesPage: React.FC = () => {
       setData(occRes.status === 'fulfilled' ? occRes.value : []);
       setStudents(stuRes.status === 'fulfilled' ? stuRes.value : []);
       setRooms(rmRes.status === 'fulfilled' ? rmRes.value : []);
-      setOrganizations(tnRes.status === 'fulfilled' ? tnRes.value : []);
     } catch (e) {
       console.error(e);
       message.error('数据加载异常');
@@ -110,6 +110,30 @@ const OccupanciesPage: React.FC = () => {
     } catch (e) { console.error(e); }
   };
 
+  const handleTransferRoomChange = async (roomId: number) => {
+    transferForm.setFieldValue('newBedId', undefined);
+    transferForm.setFieldValue('newLockerId', undefined);
+    if (!roomId) {
+      setTransferAvailableBeds([]);
+      setTransferAvailableLockers([]);
+      return;
+    }
+    try {
+      const [beds, lockers] = await Promise.all([
+        api.get<any[]>(`/rooms/${roomId}/beds/available`),
+        api.get<any[]>(`/rooms/${roomId}/lockers/available`),
+      ]);
+      setTransferAvailableBeds(beds);
+      setTransferAvailableLockers(lockers);
+      if (beds.length === 1) transferForm.setFieldValue('newBedId', beds[0].id);
+    } catch (e) {
+      console.error(e);
+      setTransferAvailableBeds([]);
+      setTransferAvailableLockers([]);
+      message.error('目标宿舍床位和柜子加载失败');
+    }
+  };
+
   const filteredData = useMemo(() => {
     if (!searchText) return data;
     const keyword = searchText.toLowerCase();
@@ -130,7 +154,8 @@ const OccupanciesPage: React.FC = () => {
         checkInDate: values.checkInDate.format('YYYY-MM-DD'),
         billingStartDate: values.billingStartDate?.format('YYYY-MM-DD'),
         stayType: values.stayType,
-        responsibleOrganizationId: values.responsibleOrganizationId,
+        collectDeposit: values.collectDeposit,
+        depositAmount: values.collectDeposit ? values.depositAmount : undefined,
         notes: values.notes,
         bedId: values.bedId,
         lockerId: values.lockerId || undefined,
@@ -170,13 +195,10 @@ const OccupanciesPage: React.FC = () => {
     const values = await transferForm.validateFields();
     setSaving(true);
     try {
-      await api.put(`/occupancies/${transferModal.id}/transfer`, {
-        newRoomId: values.newRoomId,
-        transferDate: values.transferDate.format('YYYY-MM-DD'),
-        oldBillingEndDate: values.oldBillingEndDate?.format('YYYY-MM-DD'),
-        newBillingStartDate: values.newBillingStartDate?.format('YYYY-MM-DD'),
-        reason: values.reason,
-      });
+      await api.put(
+        `/occupancies/${transferModal.id}/transfer`,
+        buildTransferPayload(values),
+      );
       message.success('换房成功');
       setTransferModal(null);
       transferForm.resetFields();
@@ -261,6 +283,9 @@ const OccupanciesPage: React.FC = () => {
               size="small"
               icon={<SwapOutlined />}
               onClick={() => {
+                setTransferAvailableBeds([]);
+                setTransferAvailableLockers([]);
+                transferForm.resetFields();
                 setTransferModal(record);
                 transferForm.setFieldsValue({ transferDate: dayjs() });
               }}
@@ -303,7 +328,7 @@ const OccupanciesPage: React.FC = () => {
     <div>
       <Alert
         title="一站式导入"
-        description="导入入住名单时会自动创建学生和宿舍，无需单独在「学生管理」或「宿舍管理」中手动添加。后续仅需在此页面处理换房/退宿等日常操作即可。"
+        description="导入入住名单时会优先按手机号关联已有学生，所属机构自动取学生档案；未找到学生或宿舍时会自动创建。后续仅需在此页面处理换房/退宿等日常操作即可。"
         type="info"
         showIcon
         closable
@@ -340,7 +365,7 @@ const OccupanciesPage: React.FC = () => {
             icon={<PlusOutlined />}
             onClick={() => {
               checkInForm.resetFields();
-              checkInForm.setFieldsValue({ checkInDate: dayjs() });
+              checkInForm.setFieldsValue({ checkInDate: dayjs(), collectDeposit: true, depositAmount: 500 });
               setCheckInModal(true);
             }}
           >
@@ -380,7 +405,7 @@ const OccupanciesPage: React.FC = () => {
               }
             }}
           >
-            <Tooltip title="导入时自动创建学生、宿舍和入住记录">
+            <Tooltip title="按手机号关联学生，并自动创建缺失的学生、宿舍和入住记录">
               <Button type="primary" ghost icon={<UploadOutlined />}>
                 导入入住名单
               </Button>
@@ -495,7 +520,12 @@ const OccupanciesPage: React.FC = () => {
         loading={loading}
         locale={{ emptyText: <Empty description="暂无数据" /> }}
         scroll={{ x: 1300 }}
-        pagination={{ pageSize: 15, showTotal: (total) => `共 ${total} 条` }}
+        pagination={{
+          defaultPageSize: 15,
+          showSizeChanger: true,
+          pageSizeOptions: [15, 30, 50, 100],
+          showTotal: (total) => `共 ${total} 条`,
+        }}
         rowSelection={rowSelection}
       />
       <Modal
@@ -566,18 +596,6 @@ const OccupanciesPage: React.FC = () => {
               placeholder="默认为短租"
             />
           </Form.Item>
-          <Form.Item name="responsibleOrganizationId" label="负责机构">
-            <Select
-              showSearch
-              allowClear
-              optionFilterProp="label"
-              placeholder="默认取学生所属机构"
-              options={organizations.map((t: { id: number; name: string }) => ({
-                value: t.id,
-                label: t.name,
-              }))}
-            />
-          </Form.Item>
           <Form.Item
             name="bedId"
             label="床位"
@@ -598,7 +616,10 @@ const OccupanciesPage: React.FC = () => {
               空闲 {availableBeds.length} 张床位
             </div>
           )}
-          <Form.Item name="lockerId" label="柜子（可选）">
+          <Form.Item
+            name="lockerId"
+            label="柜子（可选）"
+          >
             <Select
               allowClear
               placeholder="可选分配柜子"
@@ -609,6 +630,32 @@ const OccupanciesPage: React.FC = () => {
               }))}
             />
           </Form.Item>
+          <Form.Item
+            name="collectDeposit"
+            label="押金缴纳"
+            valuePropName="checked"
+            extra="开启后，确认入住时同步生成已缴押金记录；已有已缴押金时不会重复创建"
+          >
+            <Switch checkedChildren="已缴" unCheckedChildren="不缴" />
+          </Form.Item>
+          <Form.Item noStyle shouldUpdate={(prev, current) => prev.collectDeposit !== current.collectDeposit}>
+            {({ getFieldValue }) =>
+              getFieldValue('collectDeposit') ? (
+                <Form.Item
+                  name="depositAmount"
+                  label="押金金额"
+                  rules={[{ required: true, message: '请输入押金金额' }]}
+                >
+                  <InputNumber
+                    min={0.01}
+                    precision={2}
+                    addonAfter="元"
+                    style={{ width: '100%' }}
+                  />
+                </Form.Item>
+              ) : null
+            }
+          </Form.Item>
           <Form.Item name="notes" label="备注">
             <Input.TextArea rows={2} />
           </Form.Item>
@@ -708,7 +755,12 @@ const OccupanciesPage: React.FC = () => {
         title={`换房 - ${transferModal?.student?.name}`}
         open={!!transferModal}
         onOk={handleTransfer}
-        onCancel={() => setTransferModal(null)}
+        onCancel={() => {
+          setTransferModal(null);
+          transferForm.resetFields();
+          setTransferAvailableBeds([]);
+          setTransferAvailableLockers([]);
+        }}
         okText="确认换房"
         confirmLoading={saving}
         width={500}
@@ -719,6 +771,7 @@ const OccupanciesPage: React.FC = () => {
               showSearch
               optionFilterProp="label"
               placeholder="选择目标宿舍"
+              onChange={handleTransferRoomChange}
               options={rooms
                 .filter((r: any) => r.id !== transferModal?.roomId)
                 .map((r: any) => ({
@@ -728,6 +781,38 @@ const OccupanciesPage: React.FC = () => {
                 }))}
             />
           </Form.Item>
+          <Form.Item
+            name="newBedId"
+            label="目标床位"
+            rules={[{ required: true, message: '请选择目标床位' }]}
+          >
+            <Select
+              placeholder="请先选择目标宿舍"
+              disabled={transferAvailableBeds.length === 0}
+              options={transferAvailableBeds.map((bed) => ({
+                value: bed.id,
+                label: bed.bedNumber,
+              }))}
+              notFoundContent="目标宿舍暂无可用床位"
+            />
+          </Form.Item>
+          {transferAvailableBeds.length > 0 && (
+            <div style={{ marginTop: -16, marginBottom: 16, color: '#888', fontSize: 12 }}>
+              空闲 {transferAvailableBeds.length} 张床位
+            </div>
+          )}
+          <Form.Item name="newLockerId" label="目标柜子（可选）">
+            <Select
+              allowClear
+              placeholder="可选分配目标宿舍柜子"
+              disabled={transferAvailableLockers.length === 0}
+              options={transferAvailableLockers.map((locker) => ({
+                value: locker.id,
+                label: locker.lockerNumber,
+              }))}
+              notFoundContent="目标宿舍暂无可用柜子"
+            />
+          </Form.Item>
           <Form.Item name="transferDate" label="换房日期" rules={[{ required: true }]}>
             <DatePicker style={{ width: '100%' }} placeholder="选择换房日期" format="YYYY-MM-DD" />
           </Form.Item>

apps/admin/src/pages/Occupancies/occupancy-form.integration.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import dayjs from 'dayjs';
+import { buildTransferPayload } from './occupancy-form';
+
+describe('occupancy transfer form', () => {
+  it('submits the target room resources with the transfer dates', () => {
+    expect(
+      buildTransferPayload({
+        newRoomId: 5,
+        newBedId: 12,
+        newLockerId: 18,
+        transferDate: dayjs('2026-07-13'),
+        oldBillingEndDate: dayjs('2026-07-13'),
+        newBillingStartDate: dayjs('2026-07-14'),
+        reason: '调整宿舍',
+      }),
+    ).toEqual({
+      newRoomId: 5,
+      newBedId: 12,
+      newLockerId: 18,
+      transferDate: '2026-07-13',
+      oldBillingEndDate: '2026-07-13',
+      newBillingStartDate: '2026-07-14',
+      reason: '调整宿舍',
+    });
+  });
+});

apps/admin/src/pages/Occupancies/occupancy-form.ts

@@ -0,0 +1,21 @@
+import type { Dayjs } from 'dayjs';
+
+export interface TransferFormValues {
+  newRoomId: number;
+  newBedId: number;
+  newLockerId?: number;
+  transferDate: Dayjs;
+  oldBillingEndDate?: Dayjs;
+  newBillingStartDate?: Dayjs;
+  reason?: string;
+}
+
+export const buildTransferPayload = (values: TransferFormValues) => ({
+  newRoomId: values.newRoomId,
+  newBedId: values.newBedId,
+  newLockerId: values.newLockerId || undefined,
+  transferDate: values.transferDate.format('YYYY-MM-DD'),
+  oldBillingEndDate: values.oldBillingEndDate?.format('YYYY-MM-DD'),
+  newBillingStartDate: values.newBillingStartDate?.format('YYYY-MM-DD'),
+  reason: values.reason,
+});

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

@@ -26,13 +26,14 @@ const OperationLogsPage: React.FC = () => {
   const [total, setTotal] = useState(0);
   const [loading, setLoading] = useState(false);
   const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(20);
   const [filterModule, setFilterModule] = useState<string | undefined>();
   const [dateRange, setDateRange] = useState<[string, string] | null>(null);
 
   const fetchData = useCallback(async () => {
     setLoading(true);
     try {
-      const params: any = { page, pageSize: 20 };
+      const params: any = { page, pageSize };
       if (filterModule) params.module = filterModule;
       if (dateRange) {
         params.startDate = dateRange[0];
@@ -46,7 +47,7 @@ const OperationLogsPage: React.FC = () => {
       message.error(err?.message || '加载失败，请稍后重试');
     }
     setLoading(false);
-  }, [page, filterModule, dateRange]);
+  }, [page, pageSize, filterModule, dateRange]);
 
   useEffect(() => {
     fetchData();
@@ -159,8 +160,13 @@ const OperationLogsPage: React.FC = () => {
         pagination={{
           current: page,
           total,
-          pageSize: 20,
-          onChange: setPage,
+          pageSize,
+          showSizeChanger: true,
+          pageSizeOptions: [20, 50, 100],
+          onChange: (nextPage, nextPageSize) => {
+            setPage(nextPage);
+            setPageSize(nextPageSize);
+          },
           showTotal: (t) => `共 ${t} 条`,
         }}
       />

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

@@ -235,7 +235,12 @@ const OrganizationsPage: React.FC = () => {
         loading={loading}
         locale={{ emptyText: <Empty description="暂无机构" /> }}
         scroll={{ x: 1100 }}
-        pagination={{ pageSize: 20, showTotal: (total) => `共 ${total} 个机构` }}
+        pagination={{
+          defaultPageSize: 20,
+          showSizeChanger: true,
+          pageSizeOptions: [20, 50, 100],
+          showTotal: (total) => `共 ${total} 个机构`,
+        }}
       />
       <Modal
         title={editing ? `编辑机构 · ${editing.name}` : '添加外部机构'}

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

@@ -156,17 +156,23 @@ const RoomsPage: React.FC = () => {
     if (filterStatus) result = result.filter((r: Record<string, unknown>) => r.status === filterStatus);
     return result;
   }, [data, searchText, filterBuilding, filterStatus]);
+  const remainingBedSlots = useMemo(() => {
+    const capacity = Number(drawerRoom?.capacity) || 0;
+    return Math.max(capacity - beds.length, 0);
+  }, [drawerRoom?.capacity, beds.length]);
+  const defaultBatchBedCount = Math.min(4, Math.max(remainingBedSlots, 1));
 
   const handleSave = async () => {
     const values = await form.validateFields();
+    const payload = values;
     setSaving(true);
     try {
       if (editing) {
-        await api.put(`/rooms/${editing.id}`, values);
+        await api.put(`/rooms/${editing.id}`, payload);
         message.success('更新成功');
       } else {
-        await api.post('/rooms', values);
-        message.success('创建成功');
+        await api.post('/rooms', payload);
+        message.success(`创建成功，已自动生成 ${values.capacity} 张床位`);
       }
       setModalOpen(false);
       form.resetFields();
@@ -337,12 +343,6 @@ const RoomsPage: React.FC = () => {
           />
         ),
     },
-    {
-      title: '性别',
-      dataIndex: 'gender',
-      width: 80,
-      render: (v: any) => (v ? <Tag color={v === '男' ? 'blue' : 'pink'}>{v}</Tag> : '-'),
-    },
     {
       title: '状态',
       dataIndex: 'status',
@@ -519,7 +519,12 @@ const RoomsPage: React.FC = () => {
         scroll={{ x: 1200 }}
         loading={loading}
         locale={{ emptyText: <Empty description="暂无数据" /> }}
-        pagination={{ pageSize: 20, showTotal: (total) => `共 ${total} 间` }}
+        pagination={{
+          defaultPageSize: 20,
+          showSizeChanger: true,
+          pageSizeOptions: [20, 50, 100],
+          showTotal: (total) => `共 ${total} 间`,
+        }}
         rowClassName={(record) => (record.status === 'archived' ? 'archived-row' : '')}
         rowSelection={{
           selectedRowKeys,
@@ -634,24 +639,26 @@ const RoomsPage: React.FC = () => {
                       type="primary"
                       size="small"
                       icon={<PlusOutlined />}
-                      disabled={drawerRoom?.status === 'archived'}
+                      disabled={drawerRoom?.status === 'archived' || remainingBedSlots === 0}
                       onClick={() => { setBedEditing(null); bedForm.resetFields(); setBedModalOpen(true); }}
                     >
                       添加床位
                     </Button>
                     <Popconfirm
-                      title="批量生成床位"
+                      title={remainingBedSlots > 0 ? '批量生成床位' : '床位已达到额定人数'}
                       description={
-                        <InputNumber min={1} max={20} defaultValue={4} id="batch-bed-count" style={{ width: 80 }} />
+                        remainingBedSlots > 0
+                          ? <InputNumber min={1} max={remainingBedSlots} defaultValue={defaultBatchBedCount} id="batch-bed-count" style={{ width: 80 }} />
+                          : '如需增加床位，请先调整宿舍额定人数'
                       }
                       onConfirm={() => {
                         const input = document.getElementById('batch-bed-count') as HTMLInputElement;
-                        handleBatchBeds(input ? parseInt(input.value) || 4 : 4);
+                        handleBatchBeds(input ? parseInt(input.value) || defaultBatchBedCount : defaultBatchBedCount);
                       }}
                       okText="生成"
-                      disabled={drawerRoom?.status === 'archived'}
+                      disabled={drawerRoom?.status === 'archived' || remainingBedSlots === 0}
                     >
-                      <Button size="small" disabled={drawerRoom?.status === 'archived'}>批量生成</Button>
+                      <Button size="small" disabled={drawerRoom?.status === 'archived' || remainingBedSlots === 0}>批量生成</Button>
                     </Popconfirm>
                   </div>
                   <Table

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

@@ -947,6 +947,19 @@ const SchedulesPage: React.FC = () => {
               />
             </Form.Item>
 
+            <Form.Item
+              name="notes"
+              label="备注"
+              rules={[{ max: 500, message: '备注不能超过500字' }]}
+            >
+              <Input.TextArea
+                rows={3}
+                maxLength={500}
+                showCount
+                placeholder="可填写排课说明、设备需求或临时调整原因"
+              />
+            </Form.Item>
+
             <Form.Item
               name="timeRange"
               label="上课时段"

apps/admin/src/pages/Schedules/schedule-form.integration.test.ts

@@ -15,10 +15,12 @@ describe('schedule edit form mapping', () => {
       endTime: '18:00',
       startDate: '2026-07-01',
       endDate: '2026-07-31',
+      notes: '需要投影设备',
     });
 
     expect(values.classroomId).toBe(1);
     expect(values.weekDay).toBe(5);
+    expect(values.notes).toBe('需要投影设备');
     expect(values.timeRange.map((item) => item.format('HH:mm'))).toEqual(['14:00', '18:00']);
     expect(values.dateRange.map((item) => item.format('YYYY-MM-DD'))).toEqual([
       '2026-07-01',
@@ -36,6 +38,7 @@ describe('schedule edit form mapping', () => {
         teacherId: 4,
         timeRange: [dayjs('2026-01-01 13:30'), dayjs('2026-01-01 17:20')],
         dateRange: [dayjs('2026-08-01'), dayjs('2026-08-31')],
+        notes: '  临时调整教室  ',
       }),
     ).toEqual({
       classId: 1,
@@ -47,6 +50,24 @@ describe('schedule edit form mapping', () => {
       endTime: '17:20',
       startDate: '2026-08-01',
       endDate: '2026-08-31',
+      notes: '临时调整教室',
     });
   });
 });
+
+
+describe('schedule notes normalization', () => {
+  it('omits whitespace-only notes from the payload', () => {
+    expect(
+      buildSchedulePayload({
+        classId: 1,
+        classroomId: 2,
+        weekDay: 6,
+        subject: '作文',
+        timeRange: [dayjs('2026-01-01 13:30'), dayjs('2026-01-01 17:20')],
+        dateRange: [dayjs('2026-08-01'), dayjs('2026-08-31')],
+        notes: '   ',
+      }).notes,
+    ).toBeUndefined();
+  });
+});

apps/admin/src/pages/Schedules/schedule-form.ts

@@ -6,6 +6,7 @@ export interface ScheduleFormValues {
   weekDay: number;
   subject: string;
   teacherId?: number;
+  notes?: string;
   timeRange: [Dayjs, Dayjs];
   dateRange: [Dayjs, Dayjs];
 }
@@ -17,6 +18,7 @@ export interface EditableSchedule {
   weekDay: number;
   subject: string;
   teacherId: number | null;
+  notes?: string | null;
   startTime: string;
   endTime: string;
   startDate: string;
@@ -29,6 +31,7 @@ export const scheduleToFormValues = (schedule: EditableSchedule): ScheduleFormVa
   weekDay: schedule.weekDay,
   subject: schedule.subject,
   teacherId: schedule.teacherId ?? undefined,
+  notes: schedule.notes ?? undefined,
   timeRange: [dayjs(`2000-01-01 ${schedule.startTime}`), dayjs(`2000-01-01 ${schedule.endTime}`)],
   dateRange: [dayjs(schedule.startDate), dayjs(schedule.endDate)],
 });
@@ -39,6 +42,7 @@ export const buildSchedulePayload = (values: ScheduleFormValues) => ({
   weekDay: values.weekDay,
   subject: values.subject,
   teacherId: values.teacherId,
+  notes: values.notes?.trim() || undefined,
   startTime: values.timeRange[0].format('HH:mm'),
   endTime: values.timeRange[1].format('HH:mm'),
   startDate: values.dateRange[0].format('YYYY-MM-DD'),

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

@@ -322,7 +322,28 @@ const StudentsPage: React.FC = () => {
       },
       { title: '民族', dataIndex: 'ethnicity', width: 90 },
       { title: '紧急联系人', dataIndex: 'emergencyContact', width: 100 },
-      { title: '紧急联系人电话', dataIndex: 'emergencyPhone', width: 130 },
+      {
+        title: '紧急联系人电话',
+        dataIndex: 'emergencyPhone',
+        width: 150,
+        render: (v: string, record: any) => {
+          if (!v) return '-';
+          return (
+            <span>
+              <span style={{ marginRight: 4 }}>{maskPhone(v)}</span>
+              <Button
+                type="link"
+                size="small"
+                style={{ padding: '8px 4px' }}
+                onClick={() => handleViewSensitive(record.id, '紧急联系人电话', v)}
+                title="点击查看完整号码"
+              >
+                <EyeOutlined style={{ fontSize: 12, color: '#999' }} />
+              </Button>
+            </span>
+          );
+        },
+      },
       {
         title: '所属机构',
         dataIndex: 'organization',
@@ -556,7 +577,12 @@ const StudentsPage: React.FC = () => {
         loading={loading}
         locale={{ emptyText: <Empty description="暂无数据" /> }}
         scroll={{ x: 1410 }}
-        pagination={{ pageSize: 15, showTotal: (total) => `共 ${total} 人` }}
+        pagination={{
+          defaultPageSize: 15,
+          showSizeChanger: true,
+          pageSizeOptions: [15, 30, 50, 100],
+          showTotal: (total) => `共 ${total} 人`,
+        }}
         rowClassName={(record: any) => (record.status === 'archived' ? 'archived-row' : '')}
         rowSelection={{
           selectedRowKeys,

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

@@ -146,7 +146,12 @@ const TeacherWorkspacePage: React.FC = () => {
                 columns={classColumns}
                 dataSource={data.assignedClasses}
                 rowKey="classId"
-                pagination={{ pageSize: 20, showTotal: (total) => `共 ${total} 个班级` }}
+                pagination={{
+                  defaultPageSize: 20,
+                  showSizeChanger: true,
+                  pageSizeOptions: [20, 50, 100],
+                  showTotal: (total) => `共 ${total} 个班级`,
+                }}
               />
             ) : (
               <Empty description="暂无分配的班级" />
@@ -160,7 +165,12 @@ const TeacherWorkspacePage: React.FC = () => {
                 columns={scheduleColumns}
                 dataSource={data.todaySchedules}
                 rowKey="id"
-                pagination={{ pageSize: 20, showTotal: (total) => `共 ${total} 节` }}
+                pagination={{
+                  defaultPageSize: 20,
+                  showSizeChanger: true,
+                  pageSizeOptions: [20, 50, 100],
+                  showTotal: (total) => `共 ${total} 节`,
+                }}
               />
             ) : (
               <Empty description="今日无排课" />
@@ -174,7 +184,12 @@ const TeacherWorkspacePage: React.FC = () => {
                 columns={studentColumns}
                 dataSource={data.myStudents}
                 rowKey="studentId"
-                pagination={{ pageSize: 20, showTotal: (total) => `共 ${total} 人` }}
+                pagination={{
+                  defaultPageSize: 20,
+                  showSizeChanger: true,
+                  pageSizeOptions: [20, 50, 100],
+                  showTotal: (total) => `共 ${total} 人`,
+                }}
               />
             ) : (
               <Empty description="暂无学生" />

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

@@ -46,13 +46,14 @@ const ROLE_TYPE_LABELS: Record<string, string> = {
   academic_teacher: '教务老师',
 };
 
-const PAGE_SIZE = 20;
+const DEFAULT_PAGE_SIZE = 20;
 
 const TeachersPage: React.FC = () => {
   const [data, setData] = useState<TeacherRow[]>([]);
   const [loading, setLoading] = useState(false);
   const [total, setTotal] = useState(0);
   const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(DEFAULT_PAGE_SIZE);
   const [search, setSearch] = useState('');
   const [profileModal, setProfileModal] = useState<TeacherRow | null>(null);
   const [form] = Form.useForm<ProfileFormValues>();
@@ -62,7 +63,7 @@ const TeachersPage: React.FC = () => {
     setLoading(true);
     try {
       const res = await api.get<TeacherListResponse>('/rbac/teachers', {
-        params: { search: search || undefined, page, pageSize: PAGE_SIZE },
+        params: { search: search || undefined, page, pageSize },
       });
       setData(res.list);
       setTotal(res.total);
@@ -70,7 +71,7 @@ const TeachersPage: React.FC = () => {
       // silent
     }
     setLoading(false);
-  }, [page, search]);
+  }, [page, pageSize, search]);
 
   useEffect(() => {
     fetchData();
@@ -199,9 +200,14 @@ const TeachersPage: React.FC = () => {
         scroll={{ x: 1300 }}
         pagination={{
           current: page,
-          pageSize: PAGE_SIZE,
+          pageSize,
           total,
-          onChange: setPage,
+          showSizeChanger: true,
+          pageSizeOptions: [20, 50, 100],
+          onChange: (nextPage, nextPageSize) => {
+            setPage(nextPage);
+            setPageSize(nextPageSize);
+          },
           showTotal: (t) => `共 ${t} 人`,
         }}
         expandable={{

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

@@ -15,6 +15,10 @@ import dayjs from 'dayjs';
 import api from '../../api';
 import PermissionButton from '../../components/PermissionButton';
 import { message } from '../../ui/app-message';
+import {
+  userProfileResponseToFormValues,
+  type UserProfileResponse,
+} from './user-profile-form';
 
 const UsersPage: React.FC = () => {
   const [data, setData] = useState<any[]>([]);
@@ -36,8 +40,8 @@ const UsersPage: React.FC = () => {
   const handleOpenProfile = async (record: any) => {
     setProfileUser(record);
     try {
-      const res: any = await api.get(`/rbac/users/${record.id}/profile`);
-      profileForm.setFieldsValue(res);
+      const res = await api.get<UserProfileResponse>(`/rbac/users/${record.id}/profile`);
+      profileForm.setFieldsValue(userProfileResponseToFormValues(res));
     } catch {
       profileForm.setFieldsValue({});
     }

apps/admin/src/pages/Users/user-profile-form.integration.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { userProfileResponseToFormValues } from './user-profile-form';
+
+describe('user profile form mapping', () => {
+  it('unwraps the nested profile returned by the user profile endpoint', () => {
+    expect(
+      userProfileResponseToFormValues({
+        id: 9,
+        username: 'teacher01',
+        name: '测试教师',
+        profile: {
+          joinedAt: '2026-07-01',
+          qualifications: '教师资格证',
+          subjects: ['语文', '历史'],
+        },
+      }),
+    ).toEqual({
+      joinedAt: '2026-07-01',
+      qualifications: '教师资格证',
+      subjects: ['语文', '历史'],
+    });
+  });
+
+  it('returns empty form values when the user has no profile', () => {
+    expect(userProfileResponseToFormValues({ profile: null })).toEqual({});
+  });
+});

apps/admin/src/pages/Users/user-profile-form.ts

@@ -0,0 +1,16 @@
+export interface UserProfileFormValues {
+  joinedAt?: string;
+  qualifications?: string;
+  subjects?: string[];
+}
+
+export interface UserProfileResponse {
+  id?: number;
+  username?: string;
+  name?: string;
+  profile?: UserProfileFormValues | null;
+}
+
+export const userProfileResponseToFormValues = (
+  response: UserProfileResponse,
+): UserProfileFormValues => response.profile || {};

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

@@ -0,0 +1,190 @@
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import { DatePicker, Empty, Form, Input, InputNumber, Modal, Popconfirm, Select, Space, Table, Tag } from 'antd';
+import { DeleteOutlined, PlusOutlined } from '@ant-design/icons';
+import dayjs from 'dayjs';
+import api from '../../api';
+import PermissionButton from '../../components/PermissionButton';
+import { message } from '../../ui/app-message';
+
+const money = (value: unknown) => `¥${Number(value || 0).toFixed(2)}`;
+
+const UtilityBalancesPage: React.FC = () => {
+  const [balances, setBalances] = useState<any[]>([]);
+  const [recharges, setRecharges] = useState<any[]>([]);
+  const [students, setStudents] = useState<any[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [modalOpen, setModalOpen] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [studentFilter, setStudentFilter] = useState<number | undefined>();
+  const [form] = Form.useForm();
+
+  const fetchData = useCallback(async () => {
+    setLoading(true);
+    try {
+      const [balanceRows, rechargeRows, studentRows]: any[] = await Promise.all([
+        api.get('/utility-balances/balances'),
+        api.get('/utility-balances/recharges', {
+          params: studentFilter ? { studentId: studentFilter } : undefined,
+        }),
+        api.get('/utility-balances/student-lookups'),
+      ]);
+      setBalances(balanceRows);
+      setRecharges(rechargeRows);
+      setStudents(studentRows);
+    } catch (e: any) {
+      message.error(e?.message || '加载失败，请稍后重试');
+    } finally {
+      setLoading(false);
+    }
+  }, [studentFilter]);
+
+  useEffect(() => {
+    fetchData();
+  }, [fetchData]);
+
+  const handleCreate = async () => {
+    if (saving) return;
+    setSaving(true);
+    try {
+      const values = await form.validateFields();
+      await api.post('/utility-balances/recharges', {
+        studentId: values.studentId,
+        amount: values.amount,
+        rechargeDate: values.rechargeDate.format('YYYY-MM-DD'),
+        notes: values.notes,
+      });
+      message.success('充值成功');
+      setModalOpen(false);
+      form.resetFields();
+      fetchData();
+    } catch (e: any) {
+      if (!e?.errorFields) message.error(e?.message || '充值失败');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const studentOptions = useMemo(
+    () => students.map((s) => ({ value: s.id, label: `${s.name}${s.studentNo ? `（${s.studentNo}）` : ''}` })),
+    [students],
+  );
+
+  return (
+    <div>
+      <div style={{ marginBottom: 16, display: 'flex', justifyContent: 'space-between', gap: 8, flexWrap: 'wrap' }}>
+        <Space wrap>
+          <Select
+            allowClear
+            showSearch
+            optionFilterProp="label"
+            style={{ width: 220 }}
+            placeholder="按学生筛选充值记录"
+            value={studentFilter}
+            onChange={setStudentFilter}
+            options={studentOptions}
+          />
+        </Space>
+        <PermissionButton
+          permission="expense:create"
+          type="primary"
+          icon={<PlusOutlined />}
+          onClick={() => {
+            form.setFieldsValue({ rechargeDate: dayjs() });
+            setModalOpen(true);
+          }}
+        >
+          水电余额充值
+        </PermissionButton>
+      </div>
+
+      <Table
+        title={() => '水电余额汇总'}
+        loading={loading}
+        dataSource={balances}
+        rowKey="studentId"
+        pagination={{ defaultPageSize: 10, showSizeChanger: true }}
+        locale={{ emptyText: <Empty description="暂无余额数据" /> }}
+        columns={[
+          { title: '学生', render: (_: any, r: any) => r.student?.name || '-' },
+          { title: '学号', render: (_: any, r: any) => r.student?.studentNo || '-' },
+          { title: '累计充值', dataIndex: 'totalRecharged', align: 'right' as const, render: money },
+          { title: '账单扣款', dataIndex: 'usedAmount', align: 'right' as const, render: money },
+          {
+            title: '剩余水电余额',
+            dataIndex: 'balance',
+            align: 'right' as const,
+            render: (v: number) => (
+              <strong style={{ color: Number(v) < 0 ? '#ff4d4f' : '#52c41a' }}>{money(v)}</strong>
+            ),
+          },
+        ]}
+      />
+
+      <Table
+        style={{ marginTop: 24 }}
+        title={() => '充值记录'}
+        loading={loading}
+        dataSource={recharges}
+        rowKey="id"
+        pagination={{ defaultPageSize: 15, showSizeChanger: true }}
+        locale={{ emptyText: <Empty description="暂无充值记录" /> }}
+        columns={[
+          { title: '学生', render: (_: any, r: any) => r.student?.name || '-' },
+          { title: '充值金额', dataIndex: 'amount', align: 'right' as const, render: money },
+          { title: '充值日期', dataIndex: 'rechargeDate' },
+          { title: '类型', render: () => <Tag color="green">充值</Tag> },
+          { title: '备注', dataIndex: 'notes' },
+          {
+            title: '录入时间',
+            dataIndex: 'createdAt',
+            render: (v: string) => (v ? dayjs(v).format('YYYY-MM-DD HH:mm') : '-'),
+          },
+          {
+            title: '操作',
+            width: 100,
+            render: (_: any, record: any) => (
+              <Popconfirm
+                title="确定删除这条充值记录？"
+                onConfirm={async () => {
+                  await api.delete(`/utility-balances/recharges/${record.id}`);
+                  message.success('删除成功');
+                  fetchData();
+                }}
+              >
+                <PermissionButton permission="expense:delete" size="small" danger icon={<DeleteOutlined />}>
+                  删除
+                </PermissionButton>
+              </Popconfirm>
+            ),
+          },
+        ]}
+      />
+
+      <Modal
+        title="水电余额充值"
+        open={modalOpen}
+        onOk={handleCreate}
+        onCancel={() => setModalOpen(false)}
+        confirmLoading={saving}
+        okText="确认充值"
+      >
+        <Form form={form} layout="vertical">
+          <Form.Item name="studentId" label="学生" rules={[{ required: true, message: '请选择学生' }]}>
+            <Select showSearch optionFilterProp="label" options={studentOptions} />
+          </Form.Item>
+          <Form.Item name="amount" label="充值金额" rules={[{ required: true, message: '请输入充值金额' }]}>
+            <InputNumber min={0.01} precision={2} style={{ width: '100%' }} />
+          </Form.Item>
+          <Form.Item name="rechargeDate" label="充值日期" rules={[{ required: true, message: '请选择充值日期' }]}>
+            <DatePicker style={{ width: '100%' }} format="YYYY-MM-DD" />
+          </Form.Item>
+          <Form.Item name="notes" label="备注">
+            <Input.TextArea rows={2} />
+          </Form.Item>
+        </Form>
+      </Modal>
+    </div>
+  );
+};
+
+export default UtilityBalancesPage;

apps/admin/src/utils/notification-display.ts

@@ -0,0 +1,25 @@
+export const notificationTypeLabels: Record<string, string> = {
+  bill_generated: '账单',
+  bill_paid: '账单',
+  check_in: '入住',
+  check_out: '退宿',
+  deposit_due: '押金',
+  deposit_refunded: '押金',
+  class_change: '班级',
+  schedule_conflict: '排课',
+  announcement: '公告',
+};
+
+const teacherRoleLabels: Record<string, string> = {
+  subject_teacher: '任课老师',
+  head_teacher: '班主任',
+  life_teacher: '生活老师',
+  academic_teacher: '学服老师',
+};
+
+export function formatNotificationText(text: string): string {
+  return Object.entries(teacherRoleLabels).reduce(
+    (result, [roleType, label]) => result.replaceAll(roleType, label),
+    text,
+  );
+}

apps/server/package.json

@@ -6,7 +6,7 @@
   "license": "UNLICENSED",
   "author": "",
   "scripts": {
-    "dev": "SEED_DEV=true nest start --watch -p tsconfig.build.json",
+    "dev": "cross-env SEED_DEV=true nest start --watch -p tsconfig.build.json",
     "build": "nest build -p tsconfig.build.json",
     "start:dev": "nest start --watch",
     "format": "oxfmt",
@@ -28,6 +28,7 @@
     "@nestjs/core": "^11.0.1",
     "@nestjs/event-emitter": "^3.1.0",
     "@nestjs/jwt": "^11.0.2",
+    "@nestjs/mapped-types": "^2.1.1",
     "@nestjs/passport": "^11.0.5",
     "@nestjs/platform-express": "^11.1.19",
     "@nestjs/schedule": "^6.1.3",
@@ -67,6 +68,7 @@
     "@types/passport-jwt": "^4.0.1",
     "@types/passport-local": "^1.0.38",
     "@types/supertest": "^7.0.0",
+    "cross-env": "^10.1.0",
     "eslint": "^9.18.0",
     "globals": "^17.0.0",
     "jest": "^30.0.0",

apps/server/src/app.module.ts

@@ -19,6 +19,7 @@ import {
   OperationLog,
   Deposit,
   DepositInstallment,
+  UtilityRecharge,
   Classroom,
   Organization,
   ClassroomRental,
@@ -71,6 +72,7 @@ import { ExpenseTypesModule } from './expense-types/expense-types.module';
 import { DatabaseMigrationsModule } from './database/database-migrations.module';
 import { AgentToolsModule } from './agent-tools';
 import { AiConfigModule } from './ai-config/ai-config.module';
+import { UtilityBalancesModule } from './utility-balances/utility-balances.module';
 
 import {
   IntegrationConfig,
@@ -109,6 +111,7 @@ import { IntegrationConfigModule } from './integration/config/config.module';
           OperationLog,
           Deposit,
           DepositInstallment,
+          UtilityRecharge,
           Classroom,
           Organization,
           ClassroomRental,
@@ -181,6 +184,7 @@ import { IntegrationConfigModule } from './integration/config/config.module';
     AgentToolsModule,
     ExpenseTypesModule,
     AiConfigModule,
+    UtilityBalancesModule,
   ],
   providers: [
     { provide: APP_GUARD, useClass: ThrottlerGuard },

apps/server/src/archive/archive-report.service.spec.ts

@@ -0,0 +1,31 @@
+import { ArchiveReportService } from './archive-report.service';
+
+describe('ArchiveReportService retired profile fields', () => {
+  it('does not render the retired campus field in a student report', async () => {
+    const service = new ArchiveReportService(
+      { findOne: jest.fn().mockResolvedValue({ campusLocation: '旧校区', grade: '高三' }) } as never,
+      { find: jest.fn().mockResolvedValue([]) } as never,
+      { find: jest.fn().mockResolvedValue([]) } as never,
+      { find: jest.fn().mockResolvedValue([]) } as never,
+      { findOne: jest.fn().mockResolvedValue(null) } as never,
+      { find: jest.fn().mockResolvedValue([]) } as never,
+      {
+        findOne: jest.fn().mockResolvedValue({
+          id: 1,
+          name: '测试学生',
+          gender: '男',
+          phone: '',
+          ethnicity: '',
+          emergencyContact: '',
+          emergencyPhone: '',
+        }),
+      } as never,
+    );
+
+    const html = await service.generateReportHtml(1);
+
+    expect(html).not.toContain('旧校区');
+    expect(html).not.toContain('<span>校区</span>');
+    expect(html).toContain('高三');
+  });
+});

apps/server/src/archive/archive-report.service.ts

@@ -308,7 +308,6 @@ ${this.buildLearningAndResult(learnings, result, now)}
           <div class="summary-row"><span>民族</span><span>${this.esc(student.ethnicity || '-')}</span></div>
           <div class="summary-row"><span>紧急联系人</span><span>${this.esc(student.emergencyContact || '-')}</span></div>
           <div class="summary-row"><span>紧急电话</span><span>${this.esc(student.emergencyPhone || '-')}</span></div>
-          <div class="summary-row"><span>校区</span><span>${this.esc(profile?.campusLocation || '-')}</span></div>
           <div class="summary-row"><span>年级</span><span>${this.esc(profile?.grade || '-')}</span></div>
         </div>
       </div>`;

apps/server/src/archive/archive.controller.ts

@@ -20,8 +20,11 @@ import { ArchiveService } from './archive.service';
 import {
   UpsertProfileDto,
   CreateEnrollmentDto,
+  UpdateEnrollmentDto,
   CreateExamScoreDto,
+  UpdateExamScoreDto,
   CreateLearningRecordDto,
+  UpdateLearningRecordDto,
   UpsertResultDto,
 } from './dto/archive.dto';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
@@ -110,7 +113,7 @@ export class ArchiveController {
   @RequirePermission('student:edit')
   async updateEnrollment(
     @Param('id') id: string,
-    @Body() dto: Partial<CreateEnrollmentDto>,
+    @Body() dto: UpdateEnrollmentDto,
     @Request() req: AuthenticatedRequest,
   ) {
     const { ipAddress, userAgent } = extractRequestInfo(req);
@@ -174,7 +177,7 @@ export class ArchiveController {
   @RequirePermission('student:edit')
   async updateExamScore(
     @Param('id') id: string,
-    @Body() dto: Partial<CreateExamScoreDto>,
+    @Body() dto: UpdateExamScoreDto,
     @Request() req: AuthenticatedRequest,
   ) {
     const { ipAddress, userAgent } = extractRequestInfo(req);
@@ -238,7 +241,7 @@ export class ArchiveController {
   @RequirePermission('student:edit')
   async updateLearningRecord(
     @Param('id') id: string,
-    @Body() dto: Partial<CreateLearningRecordDto>,
+    @Body() dto: UpdateLearningRecordDto,
     @Request() req: AuthenticatedRequest,
   ) {
     const { ipAddress, userAgent } = extractRequestInfo(req);
@@ -330,12 +333,12 @@ export class ArchiveController {
     @Param('id') id: string,
     @Res() res: Response,
   ) {
-    const { fullPath, fileName, mimeType } = await this.archiveService.getAttachmentFile(+studentId, +id);
-    res.setHeader('Content-Type', mimeType);
-    res.setHeader(
-      'Content-Disposition',
-      `inline; filename="${encodeURIComponent(fileName)}"`,
+    const { fullPath, fileName, mimeType } = await this.archiveService.getAttachmentFile(
+      +studentId,
+      +id,
     );
+    res.setHeader('Content-Type', mimeType);
+    res.setHeader('Content-Disposition', `inline; filename="${encodeURIComponent(fileName)}"`);
     const stream = fs.createReadStream(fullPath);
     stream.pipe(res);
   }
@@ -358,7 +361,6 @@ export class ArchiveController {
     return result;
   }
 
-
   @Get(':studentId/report-html')
   @RequirePermission('student:view')
   async generateReportHtml(

apps/server/src/archive/archive.service.spec.ts

@@ -0,0 +1,37 @@
+import { ArchiveService } from './archive.service';
+
+describe('ArchiveService.getProfile', () => {
+  it('returns the admission archive under the public result field', async () => {
+    const student = { id: 7, name: '测试学生' };
+    const result = {
+      id: 3,
+      studentId: 7,
+      cultureFinalScore: 450,
+      admittedCollege: '测试学院',
+    };
+
+    const studentRepo = { findOne: jest.fn().mockResolvedValue(student) };
+    const profileRepo = { findOne: jest.fn().mockResolvedValue(null) };
+    const enrollmentRepo = { find: jest.fn().mockResolvedValue([]) };
+    const examScoreRepo = { find: jest.fn().mockResolvedValue([]) };
+    const learningRecordRepo = { find: jest.fn().mockResolvedValue([]) };
+    const resultRepo = { findOne: jest.fn().mockResolvedValue(result) };
+    const attachmentRepo = { find: jest.fn().mockResolvedValue([]) };
+
+    const service = new ArchiveService(
+      studentRepo as never,
+      profileRepo as never,
+      enrollmentRepo as never,
+      examScoreRepo as never,
+      learningRecordRepo as never,
+      resultRepo as never,
+      attachmentRepo as never,
+      {} as never,
+    );
+
+    const response = await service.getProfile(7);
+
+    expect(response).toMatchObject({ student, result });
+    expect(response).not.toHaveProperty('resultArchive');
+  });
+});

apps/server/src/archive/archive.service.ts

@@ -15,8 +15,11 @@ import { ArchiveAttachment } from '../entities/archive-attachment.entity';
 import {
   UpsertProfileDto,
   CreateEnrollmentDto,
+  UpdateEnrollmentDto,
   CreateExamScoreDto,
+  UpdateExamScoreDto,
   CreateLearningRecordDto,
+  UpdateLearningRecordDto,
   UpsertResultDto,
 } from './dto/archive.dto';
 
@@ -44,7 +47,9 @@ export class ArchiveService {
       ? path.resolve(process.cwd(), normalizedPath)
       : path.resolve(this.uploadDir, normalizedPath);
     const allowedRoots = [this.uploadDir, path.resolve(process.cwd(), 'uploads', 'archive')];
-    if (!allowedRoots.some((root) => fullPath === root || fullPath.startsWith(`${root}${path.sep}`))) {
+    if (
+      !allowedRoots.some((root) => fullPath === root || fullPath.startsWith(`${root}${path.sep}`))
+    ) {
       throw new BadRequestException('路径非法');
     }
     return fullPath;
@@ -54,21 +59,15 @@ export class ArchiveService {
     const student = await this.studentRepo.findOne({ where: { id: studentId } });
     if (!student) throw new NotFoundException('学生不存在');
 
-    const [
-      profileRaw,
-      enrollments,
-      examScores,
-      learningRecords,
-      resultArchive,
-      attachments,
-    ] = await Promise.all([
-      this.profileRepo.findOne({ where: { studentId } }),
-      this.enrollmentRepo.find({ where: { studentId }, order: { createdAt: 'DESC' } }),
-      this.examScoreRepo.find({ where: { studentId }, order: { examDate: 'DESC' } }),
-      this.learningRecordRepo.find({ where: { studentId }, order: { recordDate: 'DESC' } }),
-      this.resultRepo.findOne({ where: { studentId } }),
-      this.attachmentRepo.find({ where: { studentId }, order: { createdAt: 'DESC' } }),
-    ]);
+    const [profileRaw, enrollments, examScores, learningRecords, resultArchive, attachments] =
+      await Promise.all([
+        this.profileRepo.findOne({ where: { studentId } }),
+        this.enrollmentRepo.find({ where: { studentId }, order: { createdAt: 'DESC' } }),
+        this.examScoreRepo.find({ where: { studentId }, order: { examDate: 'DESC' } }),
+        this.learningRecordRepo.find({ where: { studentId }, order: { recordDate: 'DESC' } }),
+        this.resultRepo.findOne({ where: { studentId } }),
+        this.attachmentRepo.find({ where: { studentId }, order: { createdAt: 'DESC' } }),
+      ]);
 
     return {
       student,
@@ -76,7 +75,7 @@ export class ArchiveService {
       enrollments,
       examScores,
       learningRecords,
-      resultArchive,
+      result: resultArchive,
       attachments,
     };
   }
@@ -102,7 +101,7 @@ export class ArchiveService {
     return this.enrollmentRepo.save(entity);
   }
 
-  async updateEnrollment(id: number, dto: Partial<CreateEnrollmentDto>) {
+  async updateEnrollment(id: number, dto: UpdateEnrollmentDto) {
     const entity = await this.enrollmentRepo.findOne({ where: { id } });
     if (!entity) throw new NotFoundException('报名记录不存在');
     Object.assign(entity, dto);
@@ -124,7 +123,7 @@ export class ArchiveService {
     return this.examScoreRepo.save(entity);
   }
 
-  async updateExamScore(id: number, dto: Partial<CreateExamScoreDto>) {
+  async updateExamScore(id: number, dto: UpdateExamScoreDto) {
     const entity = await this.examScoreRepo.findOne({ where: { id } });
     if (!entity) throw new NotFoundException('考试成绩不存在');
     Object.assign(entity, dto);
@@ -146,7 +145,7 @@ export class ArchiveService {
     return this.learningRecordRepo.save(entity);
   }
 
-  async updateLearningRecord(id: number, dto: Partial<CreateLearningRecordDto>) {
+  async updateLearningRecord(id: number, dto: UpdateLearningRecordDto) {
     const entity = await this.learningRecordRepo.findOne({ where: { id } });
     if (!entity) throw new NotFoundException('学习记录不存在');
     Object.assign(entity, dto);
@@ -225,4 +224,3 @@ export class ArchiveService {
     return { message: '已删除' };
   }
 }
-

apps/server/src/archive/dto/archive.dto.spec.ts

@@ -0,0 +1,57 @@
+import 'reflect-metadata';
+import { ValidationPipe } from '@nestjs/common';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import {
+  UpdateEnrollmentDto,
+  UpdateExamScoreDto,
+  UpdateLearningRecordDto,
+  UpsertProfileDto,
+} from './archive.dto';
+
+const pipe = new ValidationPipe({ transform: true, whitelist: true });
+
+async function transform<T extends object>(metatype: new () => T, value: unknown) {
+  return pipe.transform(value, { type: 'body', metatype });
+}
+
+describe('UpsertProfileDto retired fields', () => {
+  it('removes the retired campusLocation field under whitelist validation', async () => {
+    const dto = plainToInstance(UpsertProfileDto, {
+      grade: '高三',
+      campusLocation: '旧校区',
+    });
+
+    await validate(dto, { whitelist: true });
+
+    expect(dto).toMatchObject({ grade: '高三' });
+    expect(dto).not.toHaveProperty('campusLocation');
+  });
+});
+
+describe('archive update DTOs', () => {
+  it('allows partial enrollment updates and strips unknown fields', async () => {
+    await expect(
+      transform(UpdateEnrollmentDto, { className: '新班级', ignored: 'value' }),
+    ).resolves.toEqual(expect.objectContaining({ className: '新班级' }));
+    const result = await transform(UpdateEnrollmentDto, {
+      className: '新班级',
+      ignored: 'value',
+    });
+    expect(result).not.toHaveProperty('ignored');
+  });
+
+  it('retains create DTO validation rules for exam scores', async () => {
+    await expect(transform(UpdateExamScoreDto, { score: '90' })).rejects.toThrow();
+    await expect(transform(UpdateExamScoreDto, { score: 90 })).resolves.toMatchObject({
+      score: 90,
+    });
+  });
+
+  it('retains create DTO date validation for learning records', async () => {
+    await expect(
+      transform(UpdateLearningRecordDto, { recordDate: 'not-a-date' }),
+    ).rejects.toThrow();
+    await expect(transform(UpdateLearningRecordDto, {})).resolves.toEqual({});
+  });
+});

apps/server/src/archive/dto/archive.dto.ts

@@ -1,3 +1,4 @@
+import { PartialType } from '@nestjs/mapped-types';
 import { IsOptional, IsString, IsNumber, IsDateString } from 'class-validator';
 
 export class UpsertProfileDto {
@@ -5,7 +6,6 @@ export class UpsertProfileDto {
   @IsOptional() @IsString() targetMajor?: string;
   @IsOptional() @IsString() subjectDirection?: string;
   @IsOptional() @IsString() grade?: string;
-  @IsOptional() @IsString() campusLocation?: string;
   @IsOptional() @IsDateString() profileDate?: string;
   @IsOptional() @IsString() notes?: string;
 }
@@ -21,6 +21,8 @@ export class CreateEnrollmentDto {
   @IsOptional() @IsString() status?: string;
 }
 
+export class UpdateEnrollmentDto extends PartialType(CreateEnrollmentDto) {}
+
 export class CreateExamScoreDto {
   @IsString() examType: string;
   @IsOptional() @IsString() examName?: string;
@@ -32,6 +34,8 @@ export class CreateExamScoreDto {
   @IsOptional() @IsNumber() enrollmentId?: number;
 }
 
+export class UpdateExamScoreDto extends PartialType(CreateExamScoreDto) {}
+
 export class CreateLearningRecordDto {
   @IsDateString() recordDate: string;
   @IsString() recordType: string;
@@ -40,6 +44,8 @@ export class CreateLearningRecordDto {
   @IsOptional() @IsString() nextStep?: string;
 }
 
+export class UpdateLearningRecordDto extends PartialType(CreateLearningRecordDto) {}
+
 export class UpsertResultDto {
   @IsOptional() @IsNumber() cultureFinalScore?: number;
   @IsOptional() @IsNumber() professionalFinalScore?: number;

apps/server/src/attendance/attendance-import.service.spec.ts

@@ -93,6 +93,31 @@ describe('AttendanceImportService', () => {
     expect(entity.userName).toBe('张三');
   });
 
+  it('stores DingTalk punch source and attendance machine metadata', async () => {
+    const entity = await (service as any).mapToEntity({
+      userId: 'ding-1',
+      userName: '张三',
+      workDate: '2026-07-01',
+      timeResult: 'Normal',
+      locationResult: '',
+      planCheckTime: '',
+      actualCheckTime: '2026-07-01T08:00:00.000Z',
+      checkId: 'check-1',
+      checkType: 'OnDuty',
+      sourceType: 'ATM',
+      deviceName: '东门考勤机',
+      deviceId: 'ATM-01',
+    });
+
+    expect(entity).toEqual(
+      expect.objectContaining({
+        punchSource: 'ATM',
+        punchDeviceName: '东门考勤机',
+        punchDeviceId: 'ATM-01',
+      }),
+    );
+  });
+
   it('fills the student name from the DingTalk mapping when saving an imported record', async () => {
     dingTalkService.fetchAttendanceResults.mockResolvedValue([
       {
@@ -138,9 +163,19 @@ describe('AttendanceImportService', () => {
         actualCheckTime: '2026-07-01T08:00:00.000Z',
         checkId: 'check-1',
         checkType: 'OnDuty',
+        sourceType: 'ATM',
+        deviceName: '东门考勤机',
+        deviceId: 'ATM-01',
       },
     ]);
-    dingRawRepo.find.mockResolvedValue([{ dingId: 'check-1' }]);
+    dingRawRepo.find.mockResolvedValue([{
+      dingId: 'check-1',
+      punchSource: null,
+      punchDeviceName: null,
+      punchDeviceId: null,
+      rawData: '',
+    }]);
+    dingRawRepo.save.mockImplementation(async (entities) => entities);
     attendanceService.autoMatchDingRecords.mockResolvedValue({ matched: 1, total: 1 });
 
     const result = await service.importFromDingTalk({
@@ -150,10 +185,57 @@ describe('AttendanceImportService', () => {
       autoMatch: true,
     });
 
+    expect(dingRawRepo.save).toHaveBeenCalledWith(
+      [expect.objectContaining({
+        dingId: 'check-1',
+        punchSource: 'ATM',
+        punchDeviceName: '东门考勤机',
+        punchDeviceId: 'ATM-01',
+      })],
+      { chunk: 50 },
+    );
     expect(attendanceService.autoMatchDingRecords).toHaveBeenCalled();
     expect(result.matched).toBe(1);
   });
 
+  it('preserves existing device metadata when a duplicate response omits it', async () => {
+    const existing = {
+      dingId: 'check-keep-device',
+      punchSource: 'ATM',
+      punchDeviceName: '东门考勤机',
+      punchDeviceId: 'ATM-01',
+      rawData: '{}',
+    };
+    dingTalkService.fetchAttendanceResults.mockResolvedValue([{
+      userId: 'ding-1',
+      userName: '张三',
+      workDate: '2026-07-01',
+      timeResult: 'Normal',
+      locationResult: '',
+      planCheckTime: '',
+      actualCheckTime: '2026-07-01T08:00:00.000Z',
+      checkId: 'check-keep-device',
+      checkType: 'OnDuty',
+      sourceType: '',
+    }]);
+    dingRawRepo.find.mockResolvedValue([existing]);
+    attendanceService.autoMatchDingRecords.mockResolvedValue({ matched: 0, total: 1 });
+
+    await service.importFromDingTalk({
+      startDate: '2026-07-01',
+      endDate: '2026-07-01',
+      userIds: ['ding-1'],
+      autoMatch: true,
+    });
+
+    expect(existing).toEqual(expect.objectContaining({
+      punchSource: 'ATM',
+      punchDeviceName: '东门考勤机',
+      punchDeviceId: 'ATM-01',
+    }));
+    expect(dingRawRepo.save).not.toHaveBeenCalled();
+  });
+
   it('scopes SSE progress events to the importing user', async () => {
     dingTalkService.fetchAttendanceResults.mockResolvedValue([
       {

apps/server/src/attendance/attendance-import.service.ts

@@ -104,8 +104,10 @@ export class AttendanceImportService {
 
       // Stage 2: Parse & deduplicate
       this.emit('parsing', 0, total, `Parsing ${total} records...`);
-      const existingDingIds = await this.getExistingDingIds(rawResults);
-      const newRecords = rawResults.filter((r) => !existingDingIds.has(r.checkId));
+      const existingByDingId = await this.getExistingRecordsByDingId(rawResults);
+      const newRecords = rawResults.filter((r) => !existingByDingId.has(r.checkId));
+      const duplicateRecords = rawResults.filter((r) => existingByDingId.has(r.checkId));
+      await this.refreshDuplicatePunchMetadata(duplicateRecords, existingByDingId);
       skipped = rawResults.length - newRecords.length;
       this.emit('parsing', newRecords.length, total, `${newRecords.length} new records, ${skipped} duplicates skipped`);
 
@@ -246,17 +248,45 @@ export class AttendanceImportService {
   /**
    * Query which dingIds already exist to skip duplicates.
    */
-  private async getExistingDingIds(
+  private async getExistingRecordsByDingId(
     results: DingTalkAttendanceResult[],
-  ): Promise<Set<string>> {
+  ): Promise<Map<string, DingAttendanceRaw>> {
     const dingIds = results.map((r) => r.checkId).filter(Boolean);
-    if (dingIds.length === 0) return new Set();
+    if (dingIds.length === 0) return new Map();
 
     const existing = await this.dingRawRepo.find({
       where: { dingId: In(dingIds) },
-      select: ['dingId'],
     });
-    return new Set(existing.map((e) => e.dingId));
+    return new Map(existing.map((entity) => [entity.dingId, entity]));
+  }
+
+  private async refreshDuplicatePunchMetadata(
+    results: DingTalkAttendanceResult[],
+    existingByDingId: Map<string, DingAttendanceRaw>,
+  ): Promise<void> {
+    const changed: DingAttendanceRaw[] = [];
+    for (const result of results) {
+      const entity = existingByDingId.get(result.checkId);
+      if (!entity) continue;
+      const punchSource = result.sourceType || entity.punchSource || null;
+      const punchDeviceName = result.deviceName || entity.punchDeviceName || null;
+      const punchDeviceId = result.deviceId || entity.punchDeviceId || null;
+      if (
+        entity.punchSource === punchSource &&
+        entity.punchDeviceName === punchDeviceName &&
+        entity.punchDeviceId === punchDeviceId
+      ) {
+        continue;
+      }
+      entity.punchSource = punchSource;
+      entity.punchDeviceName = punchDeviceName;
+      entity.punchDeviceId = punchDeviceId;
+      entity.rawData = JSON.stringify(result);
+      changed.push(entity);
+    }
+    if (changed.length > 0) {
+      await this.dingRawRepo.save(changed, { chunk: 50 });
+    }
   }
 
   /**
@@ -271,6 +301,9 @@ export class AttendanceImportService {
     entity.attendanceType = r.checkType || 'OnDuty';
     entity.timeResult = r.timeResult;
     entity.locationResult = r.locationResult || '';
+    entity.punchSource = r.sourceType || null;
+    entity.punchDeviceName = r.deviceName || null;
+    entity.punchDeviceId = r.deviceId || null;
 
     // Parse check-in/out times
     if (r.actualCheckTime) {

apps/server/src/attendance/attendance.lesson-session.spec.ts

@@ -79,6 +79,9 @@ describe('AttendanceService \u2014 DingTalk course attendance', () => {
         attendanceType: 'OnDuty',
         timeResult: 'Normal',
         checkInTime: new Date('2026-07-11T08:55:00+08:00'),
+        punchSource: 'ATM',
+        punchDeviceName: '东门考勤机',
+        punchDeviceId: 'ATM-01',
       },
       {
         matchedStudentId: 2,
@@ -100,7 +103,15 @@ describe('AttendanceService \u2014 DingTalk course attendance', () => {
       }),
     );
     expect(attendanceRepo.save).toHaveBeenCalledWith([
-      expect.objectContaining({ studentId: 1, status: 'present', source: 'dingtalk' }),
+      expect.objectContaining({
+        studentId: 1,
+        status: 'present',
+        source: 'dingtalk',
+        punchSource: 'ATM',
+        punchDeviceName: '东门考勤机',
+        punchDeviceId: 'ATM-01',
+        punchTime: new Date('2026-07-11T08:55:00+08:00'),
+      }),
       expect.objectContaining({ studentId: 2, status: 'present', source: 'dingtalk' }),
       expect.objectContaining({ studentId: 3, status: 'pending', source: 'dingtalk' }),
       expect.objectContaining({ studentId: 4, status: 'pending', source: 'dingtalk' }),

apps/server/src/attendance/attendance.service.ts

@@ -200,6 +200,53 @@ export class AttendanceService {
     if (hasPunch) return 'present';
     return finalize ? 'absent' : 'pending';
   }
+
+  private getLessonPunchMetadata(
+    records: DingAttendanceRaw[],
+    lessonDate: string,
+    startTime: string,
+  ): Pick<AttendanceRecord, 'punchTime' | 'punchSource' | 'punchDeviceName' | 'punchDeviceId'> {
+    const punches = records
+      .map((record) => ({ record, time: record.checkInTime ?? record.checkOutTime }))
+      .filter((item): item is { record: DingAttendanceRaw; time: Date } => !!item.time);
+    if (punches.length === 0) {
+      return {
+        punchTime: null,
+        punchSource: null,
+        punchDeviceName: null,
+        punchDeviceId: null,
+      };
+    }
+
+    const lessonStart = new Date(`${lessonDate}T${startTime}:00+08:00`).getTime();
+    punches.sort(
+      (left, right) =>
+        Math.abs(left.time.getTime() - lessonStart) - Math.abs(right.time.getTime() - lessonStart),
+    );
+    const primary = punches[0];
+    const metadataRecord = [...punches]
+      .filter(({ record }) =>
+        !!(record.punchSource || record.punchDeviceName || record.punchDeviceId) ||
+        !['OnDuty', 'OffDuty'].includes(record.attendanceType),
+      )
+      .sort(
+        (left, right) =>
+          Math.abs(left.time.getTime() - primary.time.getTime()) -
+          Math.abs(right.time.getTime() - primary.time.getTime()),
+      )[0]?.record;
+    const source =
+      metadataRecord?.punchSource ||
+      (metadataRecord && !['OnDuty', 'OffDuty'].includes(metadataRecord.attendanceType)
+        ? metadataRecord.attendanceType
+        : primary.record.punchSource);
+
+    return {
+      punchTime: primary.time,
+      punchSource: source || null,
+      punchDeviceName: metadataRecord?.punchDeviceName || primary.record.punchDeviceName || null,
+      punchDeviceId: metadataRecord?.punchDeviceId || primary.record.punchDeviceId || null,
+    };
+  }
   async createLessonAttendanceFromDingTalk(
     scheduleId: number,
     lessonDate: string,
@@ -270,6 +317,11 @@ export class AttendanceService {
             schedule.endTime,
           );
           record.status = this.mapDingTalkStatus(raw, finalize);
+          Object.assign(record, this.getLessonPunchMetadata(
+              raw,
+              lessonDate,
+              schedule.startTime,
+            ));
           record.remark = raw.some((item) => item.checkInTime || item.checkOutTime)
             ? null
             : finalize
@@ -296,6 +348,11 @@ export class AttendanceService {
               session: this.mapScheduleTimeToSession(schedule.startTime),
               status: this.mapDingTalkStatus(raw, finalize),
               source: 'dingtalk',
+              ...this.getLessonPunchMetadata(
+                raw,
+                lessonDate,
+                schedule.startTime,
+              ),
               remark: raw.some((item) => item.checkInTime || item.checkOutTime)
                 ? undefined
                 : finalize
@@ -378,6 +435,11 @@ export class AttendanceService {
           session: this.mapScheduleTimeToSession(schedule.startTime),
           status: this.mapDingTalkStatus(raw, finalize),
           source: 'dingtalk',
+          ...this.getLessonPunchMetadata(
+            raw,
+            lessonDate,
+            schedule.startTime,
+          ),
           remark: raw.some((item) => item.checkInTime || item.checkOutTime)
             ? undefined
             : finalize
@@ -908,6 +970,10 @@ export class AttendanceService {
       if (dto.status !== undefined) {
         record.status = dto.status;
         record.source = 'manual';
+        record.punchTime = null;
+        record.punchSource = null;
+        record.punchDeviceName = null;
+        record.punchDeviceId = null;
       }
       if (dto.remark !== undefined) {
         record.remark = dto.remark;
@@ -933,6 +999,10 @@ export class AttendanceService {
         if (dto.status !== undefined) {
           freshRecord.status = dto.status;
           freshRecord.source = 'manual';
+          freshRecord.punchTime = null;
+          freshRecord.punchSource = null;
+          freshRecord.punchDeviceName = null;
+          freshRecord.punchDeviceId = null;
         }
         if (dto.remark !== undefined) {
           freshRecord.remark = dto.remark;

apps/server/src/attendance/dingtalk-attendance.service.spec.ts

@@ -12,6 +12,7 @@ describe('DingTalkService — attendance records', () => {
     service = new DingTalkService({} as never, {} as never);
     Object.assign(service, {
       accessToken: 'test-token',
+      accessTokenCredentialKey: 'test-app-key:test-app-secret',
       tokenExpiresAt: Date.now() + 3_600_000,
     });
   });
@@ -67,8 +68,10 @@ describe('DingTalkService — attendance records', () => {
             userId: 'ding-1',
             workDate: Date.parse('2026-07-12T00:00:00+08:00'),
             userCheckTime: Date.parse('2026-07-12T21:05:00+08:00'),
-            sourceType: 'USER',
+            sourceType: 'ATM',
             checkType: 'OnDuty',
+            deviceName: '东门考勤机',
+            deviceId: 'ATM-01',
             timeResult: 'Normal',
           },
         ],
@@ -82,6 +85,13 @@ describe('DingTalkService — attendance records', () => {
     });
 
     expect(record.workDate).toBe('2026-07-12');
+    expect(record).toEqual(
+      expect.objectContaining({
+        checkType: 'OnDuty',
+        sourceType: 'ATM',
+        deviceName: '东门考勤机',
+        deviceId: 'ATM-01',
+      }),
+    );
   });
 });
-

apps/server/src/bills/bills-export.service.ts

@@ -3,9 +3,9 @@ import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
 import { Bill } from '../entities/bill.entity';
 import { BillItem } from '../entities/bill-item.entity';
-import { Deposit } from '../entities/deposit.entity';
+import { UtilityRecharge } from '../entities/utility-recharge.entity';
 import * as ExcelJS from 'exceljs';
-import * as PDFDocument from 'pdfkit';
+import PDFDocument from 'pdfkit';
 import { Response } from 'express';
 
 @Injectable()
@@ -13,7 +13,8 @@ export class BillsExportService {
   constructor(
     @InjectRepository(Bill) private billRepo: Repository<Bill>,
     @InjectRepository(BillItem) private itemRepo: Repository<BillItem>,
-    @InjectRepository(Deposit) private depositRepo: Repository<Deposit>,
+    @InjectRepository(UtilityRecharge)
+    private utilityRechargeRepo: Repository<UtilityRecharge>,
   ) {}
 
   /**
@@ -34,19 +35,8 @@ export class BillsExportService {
     if (query.status) qb.andWhere('b.status = :status', { status: query.status });
     const bills = await qb.getMany();
 
-    // 查询涉及学生的"已缴未退"押金，用于导出押金抵扣字段
     const studentIds = Array.from(new Set(bills.map((b) => b.studentId)));
-    const depMap = new Map<number, number>();
-    if (studentIds.length > 0) {
-      const deposits = await this.depositRepo
-        .createQueryBuilder('d')
-        .where('d.studentId IN (:...ids)', { ids: studentIds })
-        .andWhere('d.status = :status', { status: 'paid' })
-        .getMany();
-      for (const d of deposits) {
-        depMap.set(d.studentId, (depMap.get(d.studentId) || 0) + Number(d.amount || 0));
-      }
-    }
+    const balanceMap = await this.getUtilityBalanceMap(studentIds);
 
     const workbook = new ExcelJS.Workbook();
     workbook.creator = '恭学教育基地管理系统';
@@ -58,11 +48,10 @@ export class BillsExportService {
       { header: '学生姓名', key: 'studentName', width: 14 },
       { header: '计费周期', key: 'period', width: 24 },
       { header: '分摊费用', key: 'shared', width: 12 },
-      { header: '个人费用', key: 'personal', width: 12 },
       { header: '总金额', key: 'total', width: 12 },
-      { header: '可用押金', key: 'deposit', width: 12 },
-      { header: '押金抵扣', key: 'depositApplied', width: 12 },
-      { header: '抵扣后应付', key: 'afterDeposit', width: 14 },
+      { header: '当前水电余额', key: 'utilityBalance', width: 14 },
+      { header: '扣本账单后余额', key: 'utilityBalanceAfterBill', width: 16 },
+      { header: '需补缴', key: 'utilityShortageAmount', width: 12 },
       { header: '状态', key: 'status', width: 10 },
       { header: '生成时间', key: 'generatedAt', width: 20 },
     ];
@@ -77,19 +66,21 @@ export class BillsExportService {
     };
     for (const bill of bills) {
       const total = Number(bill.totalAmount || 0);
-      const dep = Number((depMap.get(bill.studentId) || 0).toFixed(2));
-      const applied = Number(Math.min(dep, total).toFixed(2));
-      const after = Number(Math.max(0, total - applied).toFixed(2));
+      const balance = Number((balanceMap.get(bill.studentId) || 0).toFixed(2));
+      const balanceAfterBill =
+        bill.status === 'confirmed' || bill.status === 'paid'
+          ? balance
+          : Number((balance - total).toFixed(2));
+      const shortage = Math.max(0, -balanceAfterBill);
       ws.addRow({
         id: bill.id,
         studentName: (bill as any).student?.name || '-',
         period: `${bill.periodStart} ~ ${bill.periodEnd}`,
         shared: Number(bill.sharedAmount),
-        personal: Number(bill.personalAmount),
         total,
-        deposit: dep,
-        depositApplied: applied,
-        afterDeposit: after,
+        utilityBalance: balance,
+        utilityBalanceAfterBill: balanceAfterBill,
+        utilityShortageAmount: shortage,
         status: statusMap[bill.status] || bill.status,
         generatedAt: bill.generatedAt ? new Date(bill.generatedAt).toLocaleString('zh-CN') : '',
       });
@@ -147,16 +138,13 @@ export class BillsExportService {
       return;
     }
 
-    // 查询该学生的可用押金（已缴未退）
-    const deposits = await this.depositRepo
-      .createQueryBuilder('d')
-      .where('d.studentId = :sid', { sid: bill.studentId })
-      .andWhere('d.status = :status', { status: 'paid' })
-      .getMany();
-    const availableDeposit = deposits.reduce((s, d) => s + Number(d.amount || 0), 0);
     const totalAmount = Number(bill.totalAmount || 0);
-    const depositApplied = Math.min(availableDeposit, totalAmount);
-    const amountAfterDeposit = Math.max(0, totalAmount - depositApplied);
+    const balanceMap = await this.getUtilityBalanceMap([bill.studentId]);
+    const utilityBalance = Number((balanceMap.get(bill.studentId) || 0).toFixed(2));
+    const utilityBalanceAfterBill =
+      bill.status === 'confirmed' || bill.status === 'paid'
+        ? utilityBalance
+        : Number((utilityBalance - totalAmount).toFixed(2));
 
     const doc = new PDFDocument({ size: 'A4', margin: 50 });
     res.setHeader('Content-Type', 'application/pdf');
@@ -217,26 +205,16 @@ export class BillsExportService {
     doc.moveDown(0.3);
     doc.fontSize(12);
     doc.text(`分摊费用: ¥${Number(bill.sharedAmount).toFixed(2)}`);
-    doc.text(`个人费用: ¥${Number(bill.personalAmount).toFixed(2)}`);
     doc
       .fontSize(14)
       .fillColor('#007AFF')
       .text(`应付总额: ¥${totalAmount.toFixed(2)}`);
     doc.moveDown(0.3);
-    if (availableDeposit > 0) {
-      doc
-        .fontSize(11)
-        .fillColor('#52C41A')
-        .text(`可用押金: ¥${availableDeposit.toFixed(2)}`);
-      doc
-        .fontSize(11)
-        .fillColor('#FA8C16')
-        .text(`押金抵扣: -¥${depositApplied.toFixed(2)}`);
-      doc
-        .fontSize(14)
-        .fillColor('#FF3B30')
-        .text(`抵扣后应付: ¥${amountAfterDeposit.toFixed(2)}`);
-    }
+    doc.fontSize(11).fillColor('#52C41A').text(`当前水电余额: ¥${utilityBalance.toFixed(2)}`);
+    doc
+      .fontSize(11)
+      .fillColor(utilityBalanceAfterBill < 0 ? '#FF3B30' : '#52C41A')
+      .text(`扣本账单后余额: ¥${utilityBalanceAfterBill.toFixed(2)}`);
     doc.moveDown(1);
 
     // 明细表格
@@ -284,4 +262,44 @@ export class BillsExportService {
 
     doc.end();
   }
+
+  private async getUtilityBalanceMap(studentIds: number[]) {
+    const balanceMap = new Map<number, number>();
+    if (studentIds.length === 0) return balanceMap;
+
+    const [rechargeRows, billRows] = await Promise.all([
+      this.utilityRechargeRepo
+        .createQueryBuilder('r')
+        .select('r.studentId', 'studentId')
+        .addSelect('SUM(r.amount)', 'amount')
+        .where('r.studentId IN (:...studentIds)', { studentIds })
+        .groupBy('r.studentId')
+        .getRawMany<{ studentId: number | string; amount: string | number | null }>(),
+      this.billRepo
+        .createQueryBuilder('b')
+        .select('b.studentId', 'studentId')
+        .addSelect('SUM(b.totalAmount)', 'amount')
+        .where('b.studentId IN (:...studentIds)', { studentIds })
+        .andWhere('b.status IN (:...statuses)', { statuses: ['confirmed', 'paid'] })
+        .groupBy('b.studentId')
+        .getRawMany<{ studentId: number | string; amount: string | number | null }>(),
+    ]);
+
+    const rechargeMap = new Map<number, number>();
+    for (const row of rechargeRows) {
+      rechargeMap.set(Number(row.studentId), Number(row.amount || 0));
+    }
+    const paidMap = new Map<number, number>();
+    for (const row of billRows) {
+      paidMap.set(Number(row.studentId), Number(row.amount || 0));
+    }
+
+    for (const studentId of studentIds) {
+      balanceMap.set(
+        studentId,
+        Number(((rechargeMap.get(studentId) || 0) - (paidMap.get(studentId) || 0)).toFixed(2)),
+      );
+    }
+    return balanceMap;
+  }
 }

apps/server/src/bills/bills.controller.ts

@@ -7,6 +7,7 @@ import {
   Param,
   Body,
   Query,
+  ParseIntPipe,
   UseGuards,
   Request,
   Res,
@@ -20,7 +21,11 @@ import { NotificationType } from '../entities/notification.entity';
 import { Student } from '../entities/student.entity';
 import { Bill } from '../entities/bill.entity';
 import { BillsExportService } from './bills-export.service';
-import { GenerateBillsDto, UpdateBillStatusDto } from './dto/bill.dto';
+import {
+  BatchUpdateBillStatusDto,
+  GenerateBillsDto,
+  UpdateBillStatusDto,
+} from './dto/bill.dto';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
 import { OperationLogsService } from '../operation-logs/operation-logs.service';
 import { extractRequestInfo } from '../common/request-utils';
@@ -88,47 +93,15 @@ export class BillsController {
 
   @Get(':id')
   @RequirePermission('bill:view')
-  findOne(@Param('id') id: string) {
-    return this.service.findOne(+id);
-  }
-
-  @Put(':id/status')
-  @RequirePermission('bill:confirm')
-  async updateStatus(
-    @Param('id') id: string,
-    @Body() dto: UpdateBillStatusDto,
-    @Request() req: any,
-  ) {
-    const { ipAddress, userAgent } = extractRequestInfo(req);
-    const result = await this.service.updateStatus(+id, dto);
-    await this.logService.log({
-      userId: req.user?.id,
-      username: req.user?.username,
-      module: '账单管理',
-      action: '确认账单',
-      targetId: +id,
-      targetType: 'bill',
-      ipAddress,
-      userAgent,
-    });
-    // Send bill_paid notification
-    try {
-      const student = await this.studentRepo.findOne({ where: { id: result.studentId } });
-      if (student?.userId) {
-        void this.notificationsService.create({
-          recipientIds: [student.userId],
-          type: NotificationType.BILL_PAID,
-          title: '账单已确认',
-          content: `账单 #${result.id} 已确认收款,金额: ¥${result.totalAmount}`,
-        });
-      }
-    } catch (_) { /* don't block response */ }
-    return result;
+  findOne(@Param('id', ParseIntPipe) id: number) {
+    return this.service.findOne(id);
   }
 
+  // Static routes must be declared before /:id/status, otherwise "batch" is
+  // treated as an id and converted to NaN by the parameterized route.
   @Put('batch/status')
   @RequirePermission('bill:confirm')
-  async batchUpdateStatus(@Body() body: { ids: number[]; status: string }, @Request() req: any) {
+  async batchUpdateStatus(@Body() body: BatchUpdateBillStatusDto, @Request() req: any) {
     const { ipAddress, userAgent } = extractRequestInfo(req);
     const result = await this.service.batchUpdateStatus(body.ids, body.status);
     await this.logService.log({
@@ -158,17 +131,51 @@ export class BillsController {
     return result;
   }
 
+  @Put(':id/status')
+  @RequirePermission('bill:confirm')
+  async updateStatus(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() dto: UpdateBillStatusDto,
+    @Request() req: any,
+  ) {
+    const { ipAddress, userAgent } = extractRequestInfo(req);
+    const result = await this.service.updateStatus(id, dto);
+    await this.logService.log({
+      userId: req.user?.id,
+      username: req.user?.username,
+      module: '账单管理',
+      action: '确认账单',
+      targetId: id,
+      targetType: 'bill',
+      ipAddress,
+      userAgent,
+    });
+    // Send bill_paid notification
+    try {
+      const student = await this.studentRepo.findOne({ where: { id: result.studentId } });
+      if (student?.userId) {
+        void this.notificationsService.create({
+          recipientIds: [student.userId],
+          type: NotificationType.BILL_PAID,
+          title: '账单已确认',
+          content: `账单 #${result.id} 已确认收款,金额: ¥${result.totalAmount}`,
+        });
+      }
+    } catch (_) { /* don't block response */ }
+    return result;
+  }
+
   @Delete(':id')
   @RequirePermission('bill:delete')
-  async remove(@Param('id') id: string, @Request() req: any) {
+  async remove(@Param('id', ParseIntPipe) id: number, @Request() req: any) {
     const { ipAddress, userAgent } = extractRequestInfo(req);
-    const result = await this.service.remove(+id);
+    const result = await this.service.remove(id);
     await this.logService.log({
       userId: req.user?.id,
       username: req.user?.username,
       module: '账单管理',
       action: '删除账单',
-      targetId: +id,
+      targetId: id,
       targetType: 'bill',
       ipAddress,
       userAgent,
@@ -226,18 +233,18 @@ export class BillsController {
 
   @Get('export/pdf/:id')
   @RequirePermission('bill:export-pdf')
-  async exportPdf(@Param('id') id: string, @Res() res: Response, @Req() req: any) {
+  async exportPdf(@Param('id', ParseIntPipe) id: number, @Res() res: Response, @Req() req: any) {
     const { ipAddress, userAgent } = extractRequestInfo(req);
     await this.logService.log({
       userId: req?.user?.id,
       username: req?.user?.username,
       module: '账单管理',
       action: '导出账单',
-      targetId: +id,
+      targetId: id,
       targetType: 'bill',
       ipAddress,
       userAgent,
     });
-    return this.exportService.exportStudentPdf(+id, res);
+    return this.exportService.exportStudentPdf(id, res);
   }
 }

apps/server/src/bills/bills.module.ts

@@ -4,11 +4,10 @@ import { TypeOrmModule } from '@nestjs/typeorm';
 import { Bill } from '../entities/bill.entity';
 import { BillItem } from '../entities/bill-item.entity';
 import { RoomExpense } from '../entities/room-expense.entity';
-import { PersonalExpense } from '../entities/personal-expense.entity';
 import { Occupancy } from '../entities/occupancy.entity';
 import { Room } from '../entities/room.entity';
-import { Deposit } from '../entities/deposit.entity';
 import { Student } from '../entities/student.entity';
+import { UtilityRecharge } from '../entities/utility-recharge.entity';
 import { BillsService } from './bills.service';
 import { BillsExportService } from './bills-export.service';
 import { BillsController } from './bills.controller';
@@ -19,11 +18,10 @@ import { BillsController } from './bills.controller';
       Bill,
       BillItem,
       RoomExpense,
-      PersonalExpense,
       Occupancy,
       Room,
-      Deposit,
       Student,
+      UtilityRecharge,
     ]),
     NotificationsModule,
   ],

apps/server/src/bills/bills.service.spec.ts

@@ -5,10 +5,9 @@ import { BillsService } from './bills.service';
 import { Bill } from '../entities/bill.entity';
 import { BillItem } from '../entities/bill-item.entity';
 import { RoomExpense } from '../entities/room-expense.entity';
-import { PersonalExpense } from '../entities/personal-expense.entity';
 import { Occupancy } from '../entities/occupancy.entity';
 import { Room } from '../entities/room.entity';
-import { Deposit } from '../entities/deposit.entity';
+import { UtilityRecharge } from '../entities/utility-recharge.entity';
 
 type MockRepository<T> = Partial<Record<keyof Repository<T>, jest.Mock>>;
 
@@ -42,20 +41,18 @@ describe('BillsService — generateBills', () => {
   let billRepo: MockRepository<Bill>;
   let itemRepo: MockRepository<BillItem>;
   let roomExpRepo: MockRepository<RoomExpense>;
-  let personalExpRepo: MockRepository<PersonalExpense>;
   let occRepo: MockRepository<Occupancy>;
   let roomRepo: MockRepository<Room>;
-  let depositRepo: MockRepository<Deposit>;
+  let utilityRechargeRepo: MockRepository<UtilityRecharge>;
   let dataSource: { transaction: jest.Mock };
 
   beforeEach(async () => {
     billRepo = mockRepo<Bill>();
     itemRepo = mockRepo<BillItem>();
     roomExpRepo = mockRepo<RoomExpense>();
-    personalExpRepo = mockRepo<PersonalExpense>();
     occRepo = mockRepo<Occupancy>();
     roomRepo = mockRepo<Room>();
-    depositRepo = mockRepo<Deposit>();
+    utilityRechargeRepo = mockRepo<UtilityRecharge>();
     dataSource = { transaction: jest.fn(), query: jest.fn().mockResolvedValue([]) };
 
     const module: TestingModule = await Test.createTestingModule({
@@ -64,10 +61,9 @@ describe('BillsService — generateBills', () => {
         { provide: getRepositoryToken(Bill), useValue: billRepo },
         { provide: getRepositoryToken(BillItem), useValue: itemRepo },
         { provide: getRepositoryToken(RoomExpense), useValue: roomExpRepo },
-        { provide: getRepositoryToken(PersonalExpense), useValue: personalExpRepo },
         { provide: getRepositoryToken(Occupancy), useValue: occRepo },
         { provide: getRepositoryToken(Room), useValue: roomRepo },
-        { provide: getRepositoryToken(Deposit), useValue: depositRepo },
+        { provide: getRepositoryToken(UtilityRecharge), useValue: utilityRechargeRepo },
         { provide: DataSource, useValue: dataSource },
       ],
     }).compile();
@@ -100,11 +96,6 @@ describe('BillsService — generateBills', () => {
       ]),
     );
 
-    // No personal expenses
-    (personalExpRepo.createQueryBuilder as jest.Mock).mockReturnValue(
-      mockQueryBuilder<PersonalExpense>([]),
-    );
-
     const result = await service.generateBills(PERIOD);
 
     expect(result.count).toBe(1);
@@ -145,10 +136,6 @@ describe('BillsService — generateBills', () => {
       ]),
     );
 
-    (personalExpRepo.createQueryBuilder as jest.Mock).mockReturnValue(
-      mockQueryBuilder<PersonalExpense>([]),
-    );
-
     const result = await service.generateBills(PERIOD);
 
     expect(result.count).toBe(2);
@@ -203,10 +190,6 @@ describe('BillsService — generateBills', () => {
       ]),
     );
 
-    (personalExpRepo.createQueryBuilder as jest.Mock).mockReturnValue(
-      mockQueryBuilder<PersonalExpense>([]),
-    );
-
     const result = await service.generateBills(PERIOD);
     const savedCalls = (billRepo.save as jest.Mock).mock.calls as Array<[Record<string, unknown>]>;
 
@@ -253,10 +236,6 @@ describe('BillsService — generateBills', () => {
       ]),
     );
 
-    (personalExpRepo.createQueryBuilder as jest.Mock).mockReturnValue(
-      mockQueryBuilder<PersonalExpense>([]),
-    );
-
     const result = await service.generateBills(THREE_MONTHS);
     expect(result.count).toBe(1);
 
@@ -295,10 +274,6 @@ describe('BillsService — generateBills', () => {
       ]),
     );
 
-    (personalExpRepo.createQueryBuilder as jest.Mock).mockReturnValue(
-      mockQueryBuilder<PersonalExpense>([]),
-    );
-
     const result = await service.generateBills(PERIOD);
     expect(result.count).toBe(1);
 
@@ -361,10 +336,6 @@ describe('BillsService — generateBills', () => {
       ]);
     });
 
-    (personalExpRepo.createQueryBuilder as jest.Mock).mockReturnValue(
-      mockQueryBuilder<PersonalExpense>([]),
-    );
-
     // Mock student department query
     (dataSource.query as jest.Mock).mockResolvedValue([
       { id: 10, department_id: null },
@@ -394,7 +365,7 @@ describe('BillsService — generateBills', () => {
     expect(totalAll).toBeCloseTo(700, 0);
   });
 
-  it('personal expenses → added on top of shared allocation', async () => {
+  it('personal expenses → excluded from generated bill totals', async () => {
     (roomExpRepo.createQueryBuilder as jest.Mock).mockReturnValue(
       mockQueryBuilder<RoomExpense>([
         {
@@ -414,17 +385,6 @@ describe('BillsService — generateBills', () => {
       ]),
     );
 
-    // Personal expense: damage fee of 50
-    (personalExpRepo.createQueryBuilder as jest.Mock).mockReturnValue(
-      mockQueryBuilder<PersonalExpense>([
-        {
-          id: 1, studentId: 10, roomId: 1,
-          expenseType: 'damage', amount: '50' as unknown as number,
-          expenseDate: '2026-06-15', description: 'broken chair',
-        } as PersonalExpense,
-      ]),
-    );
-
     const result = await service.generateBills(PERIOD);
     expect(result.count).toBe(1);
 
@@ -432,8 +392,8 @@ describe('BillsService — generateBills', () => {
     const billData = savedCalls[0][0];
 
     expect(Number(billData.sharedAmount)).toBeCloseTo(300, 0);
-    expect(Number(billData.personalAmount)).toBe(50);
-    expect(Number(billData.totalAmount)).toBeCloseTo(350, 0);
+    expect(Number(billData.personalAmount)).toBe(0);
+    expect(Number(billData.totalAmount)).toBeCloseTo(300, 0);
   });
 
   it('zero overlapping days → no bill generated', async () => {
@@ -457,10 +417,6 @@ describe('BillsService — generateBills', () => {
       ]),
     );
 
-    (personalExpRepo.createQueryBuilder as jest.Mock).mockReturnValue(
-      mockQueryBuilder<PersonalExpense>([]),
-    );
-
     const result = await service.generateBills(PERIOD);
     // Occupancy outside period → no matching student days → no bill
     expect(result.count).toBe(0);
@@ -481,10 +437,6 @@ describe('BillsService — generateBills', () => {
       ]),
     );
 
-    (personalExpRepo.createQueryBuilder as jest.Mock).mockReturnValue(
-      mockQueryBuilder<PersonalExpense>([]),
-    );
-
     const result = await service.generateBills(PERIOD);
     expect(result.count).toBe(0);
   });

apps/server/src/bills/bills.service.ts

@@ -1,38 +1,32 @@
 import { Injectable, NotFoundException } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
-import { Repository, In, DataSource } from 'typeorm';
+import { DataSource, Repository } from 'typeorm';
 import { Bill } from '../entities/bill.entity';
 import { BillItem } from '../entities/bill-item.entity';
-import { RoomExpense } from '../entities/room-expense.entity';
-import { PersonalExpense } from '../entities/personal-expense.entity';
 import { Occupancy } from '../entities/occupancy.entity';
 import { Room } from '../entities/room.entity';
-import { Deposit } from '../entities/deposit.entity';
+import { RoomExpense } from '../entities/room-expense.entity';
+import { UtilityRecharge } from '../entities/utility-recharge.entity';
 import { GenerateBillsDto, UpdateBillStatusDto } from './dto/bill.dto';
 
-
 @Injectable()
 export class BillsService {
   constructor(
     @InjectRepository(Bill) private billRepo: Repository<Bill>,
     @InjectRepository(BillItem) private itemRepo: Repository<BillItem>,
     @InjectRepository(RoomExpense) private roomExpRepo: Repository<RoomExpense>,
-    @InjectRepository(PersonalExpense) private personalExpRepo: Repository<PersonalExpense>,
     @InjectRepository(Occupancy) private occRepo: Repository<Occupancy>,
     @InjectRepository(Room) private roomRepo: Repository<Room>,
-    @InjectRepository(Deposit) private depositRepo: Repository<Deposit>,
+    @InjectRepository(UtilityRecharge) private utilityRechargeRepo: Repository<UtilityRecharge>,
     private dataSource: DataSource,
   ) {}
 
-  /**
-   * 核心计费引擎：按"人天数"加权分摊
-   */
+  /** 核心计费引擎：按"人天数"加权分摊 */
   async generateBills(dto: GenerateBillsDto) {
     const { periodStart, periodEnd } = dto;
     const pStart = new Date(periodStart);
     const pEnd = new Date(periodEnd);
 
-    // 删除该周期已有的草稿账单
     const existingDrafts = await this.billRepo.find({
       where: { periodStart, periodEnd, status: 'draft' },
     });
@@ -50,7 +44,6 @@ export class BillsService {
         .execute();
     }
 
-    // 获取所有有费用的宿舍
     const roomExpenses = await this.roomExpRepo
       .createQueryBuilder('e')
       .where('e.periodStart = :periodStart AND e.periodEnd = :periodEnd', {
@@ -59,18 +52,15 @@ export class BillsService {
       })
       .getMany();
 
-    // 按宿舍分组费用
     const roomExpMap = new Map<number, RoomExpense[]>();
     for (const exp of roomExpenses) {
       if (!roomExpMap.has(exp.roomId)) roomExpMap.set(exp.roomId, []);
       roomExpMap.get(exp.roomId)!.push(exp);
     }
 
-    // 计算每个学生的分摊费用
     const studentBillData = new Map<number, { shared: number; items: any[] }>();
 
     for (const [roomId, expenses] of roomExpMap) {
-      // 获取该宿舍在此周期内的所有入住记录
       const occupancies = await this.occRepo
         .createQueryBuilder('o')
         .leftJoinAndSelect('o.student', 'student')
@@ -80,12 +70,9 @@ export class BillsService {
         .andWhere('(o.billingEndDate IS NULL OR o.billingEndDate >= :periodStart)', { periodStart })
         .getMany();
 
-
-      // 分离长租与短租入住记录
       const shortTermOccs = occupancies.filter((o) => o.stayType !== 'long');
       const longTermOccs = occupancies.filter((o) => o.stayType === 'long');
 
-      // 长租：按月租费独立计费，不参与人天数分摊
       for (const occ of longTermOccs) {
         const monthlyRate = Number(occ.room?.monthlyRate || 0);
         if (!studentBillData.has(occ.studentId)) {
@@ -104,10 +91,8 @@ export class BillsService {
         });
       }
 
-      // 短租：原人天数加权分摊逻辑
       if (shortTermOccs.length === 0) continue;
 
-      // 计算每个学生的计费天数
       const studentDays: { studentId: number; days: number }[] = [];
       let totalDays = 0;
 
@@ -128,7 +113,6 @@ export class BillsService {
 
       if (totalDays === 0) continue;
 
-      // 对每项费用进行分摊
       for (const expense of expenses) {
         for (const sd of studentDays) {
           if (sd.days === 0) continue;
@@ -151,57 +135,23 @@ export class BillsService {
       }
     }
 
-    // 获取个人附加费
-    const personalExps = await this.personalExpRepo
-      .createQueryBuilder('pe')
-      .where('pe.expenseDate >= :periodStart AND pe.expenseDate <= :periodEnd', {
-        periodStart,
-        periodEnd,
-      })
-      .getMany();
-
-    const personalMap = new Map<number, number>();
-    const personalItems = new Map<number, any[]>();
-    for (const pe of personalExps) {
-      personalMap.set(pe.studentId, (personalMap.get(pe.studentId) || 0) + Number(pe.amount));
-      if (!personalItems.has(pe.studentId)) personalItems.set(pe.studentId, []);
-      personalItems.get(pe.studentId)!.push({
-        roomId: pe.roomId,
-        expenseType: pe.expenseType,
-        description: `个人费用: ${pe.description || pe.expenseType}`,
-        days: 0,
-        totalRoomDays: 0,
-        roomTotalAmount: pe.amount,
-        studentAmount: pe.amount,
-      });
-    }
-
-
-    // 合并所有涉及的学生
-    const allStudentIds = new Set([...studentBillData.keys(), ...personalMap.keys()]);
-    // 生成账单
     const bills: Bill[] = [];
-    for (const studentId of allStudentIds) {
+    for (const studentId of studentBillData.keys()) {
       const shared = studentBillData.get(studentId)?.shared || 0;
-      const personal = personalMap.get(studentId) || 0;
-      const total = Number((shared + personal).toFixed(2));
+      const total = Number(shared.toFixed(2));
 
       const bill = this.billRepo.create({
         studentId,
         periodStart,
         periodEnd,
         sharedAmount: Number(shared.toFixed(2)),
-        personalAmount: personal,
+        personalAmount: 0,
         totalAmount: total,
         status: 'draft',
       });
       const savedBill = await this.billRepo.save(bill);
 
-      // 保存明细
-      const items = [
-        ...(studentBillData.get(studentId)?.items || []),
-        ...(personalItems.get(studentId) || []),
-      ];
+      const items = studentBillData.get(studentId)?.items || [];
       for (const item of items) {
         await this.itemRepo.save(this.itemRepo.create({ ...item, billId: savedBill.id }));
       }
@@ -230,44 +180,57 @@ export class BillsService {
       qb.innerJoin('b.items', 'bi', 'bi.expenseType = :et', { et: query.expenseType });
     }
     const bills = await qb.getMany();
-    return this.attachDepositInfo(bills);
+    return this.attachUtilityBalanceInfo(bills);
   }
 
   async findOne(id: number) {
     const bill = await this.billRepo.findOne({ where: { id }, relations: ['student', 'items'] });
     if (!bill) throw new NotFoundException('账单不存在');
-    const [withDeposit] = await this.attachDepositInfo([bill]);
-    return withDeposit;
+    const [withUtilityBalance] = await this.attachUtilityBalanceInfo([bill]);
+    return withUtilityBalance;
   }
 
-  /**
-   * 给账单挂上"押金联动"信息：
-   * - availableDeposit: 当前学生处于已缴未退状态(paid)的押金总额
-   * - depositApplied:   本张账单可从押金抵扣的金额（min(押金, 应付总额)）
-   * - amountAfterDeposit: 抵扣押金后学生需另外支付的金额
-   */
-  private async attachDepositInfo(bills: Bill[]): Promise<any[]> {
+  private async attachUtilityBalanceInfo(bills: Bill[]): Promise<any[]> {
     if (!bills || bills.length === 0) return bills;
     const studentIds = Array.from(new Set(bills.map((b) => b.studentId)));
     if (studentIds.length === 0) return bills;
-    const deposits = await this.depositRepo
-      .createQueryBuilder('d')
-      .where('d.studentId IN (:...ids)', { ids: studentIds })
-      .andWhere('d.status = :status', { status: 'paid' })
-      .getMany();
-    const depMap = new Map<number, number>();
-    for (const d of deposits) {
-      depMap.set(d.studentId, (depMap.get(d.studentId) || 0) + Number(d.amount || 0));
-    }
+
+    const [rechargeRows, billRows] = await Promise.all([
+      this.utilityRechargeRepo
+        .createQueryBuilder('r')
+        .select('r.studentId', 'studentId')
+        .addSelect('SUM(r.amount)', 'amount')
+        .where('r.studentId IN (:...ids)', { ids: studentIds })
+        .groupBy('r.studentId')
+        .getRawMany<{ studentId: number | string; amount: string | number | null }>(),
+      this.billRepo
+        .createQueryBuilder('b')
+        .select('b.studentId', 'studentId')
+        .addSelect('SUM(b.totalAmount)', 'amount')
+        .where('b.studentId IN (:...ids)', { ids: studentIds })
+        .andWhere('b.status IN (:...statuses)', { statuses: ['confirmed', 'paid'] })
+        .groupBy('b.studentId')
+        .getRawMany<{ studentId: number | string; amount: string | number | null }>(),
+    ]);
+
+    const rechargeMap = new Map<number, number>();
+    for (const row of rechargeRows) rechargeMap.set(Number(row.studentId), Number(row.amount || 0));
+    const usedMap = new Map<number, number>();
+    for (const row of billRows) usedMap.set(Number(row.studentId), Number(row.amount || 0));
+
     return bills.map((b) => {
       const total = Number(b.totalAmount || 0);
-      const available = Number((depMap.get(b.studentId) || 0).toFixed(2));
-      const applied = Number(Math.min(available, total).toFixed(2));
-      const afterDeposit = Number(Math.max(0, total - applied).toFixed(2));
+      const currentBalance = Number(
+        ((rechargeMap.get(b.studentId) || 0) - (usedMap.get(b.studentId) || 0)).toFixed(2),
+      );
+      const balanceAfterBill =
+        b.status === 'confirmed' || b.status === 'paid'
+          ? currentBalance
+          : Number((currentBalance - total).toFixed(2));
       return Object.assign({}, b, {
-        availableDeposit: available,
-        depositApplied: applied,
-        amountAfterDeposit: afterDeposit,
+        utilityBalance: currentBalance,
+        utilityBalanceAfterBill: balanceAfterBill,
+        utilityShortageAmount: Math.max(0, -balanceAfterBill),
       });
     });
   }

apps/server/src/bills/dto/bill.dto.ts

@@ -1,4 +1,4 @@
-import { IsString, IsOptional } from 'class-validator';
+import { ArrayNotEmpty, IsArray, IsIn, IsInt, IsString } from 'class-validator';
 
 export class GenerateBillsDto {
   @IsString()
@@ -9,6 +9,13 @@ export class GenerateBillsDto {
 }
 
 export class UpdateBillStatusDto {
-  @IsString()
+  @IsIn(['draft', 'confirmed', 'paid'])
   status: 'draft' | 'confirmed' | 'paid';
 }
+
+export class BatchUpdateBillStatusDto extends UpdateBillStatusDto {
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsInt({ each: true })
+  ids: number[];
+}

apps/server/src/classes/classes.batch-import-membership.spec.ts

@@ -0,0 +1,47 @@
+import { ClassesService } from './classes.service';
+import { ClassStudent } from '../entities';
+
+describe('ClassesService — DingTalk class import membership lifecycle', () => {
+  it('reactivates left memberships and skips active memberships', async () => {
+    const left = {
+      classId: 3,
+      studentId: 8,
+      status: 'left',
+      joinDate: '2026-01-01',
+      leaveDate: '2026-02-01',
+    } as ClassStudent;
+    const active = { classId: 3, studentId: 9, status: 'active' } as ClassStudent;
+    const classStudentRepo = {
+      find: jest.fn().mockResolvedValue([left, active]),
+      create: jest.fn().mockImplementation((value: Partial<ClassStudent>) => value),
+      save: jest.fn().mockImplementation(async (value: ClassStudent[]) => value),
+    };
+    const service = new ClassesService(
+      { findOne: jest.fn().mockResolvedValue({ id: 3 }) } as never,
+      classStudentRepo as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      { create: jest.fn(), save: jest.fn() } as never,
+      {
+        find: jest.fn().mockResolvedValue([
+          { dingUserId: 'd8', studentId: 8 },
+          { dingUserId: 'd9', studentId: 9 },
+        ]),
+        create: jest.fn(),
+        save: jest.fn(),
+      } as never,
+    );
+
+    const result = await service.batchImportStudents(3, [
+      { dingUserId: 'd8', name: '学生8' },
+      { dingUserId: 'd9', name: '学生9' },
+    ]);
+
+    expect(result).toEqual({ imported: 1, skipped: 1 });
+    expect(left).toMatchObject({ status: 'active', leaveDate: null });
+    expect(left.joinDate).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+    expect(classStudentRepo.save).toHaveBeenCalledWith([left]);
+  });
+});

apps/server/src/classes/classes.controller.ts

@@ -29,6 +29,7 @@ import { extractRequestInfo } from '../common/request-utils';
 import { RequirePermission } from '../auth/decorators/permission.decorator';
 import { NotificationsService } from '../notifications/notifications.service';
 import { NotificationType } from '../entities/notification.entity';
+import { TeacherRoleType } from '../entities';
 import * as ExcelJS from 'exceljs';
 import { AuthorizationService, CaslAction, SubjectName, AuthenticatedUser } from '../authorization';
 
@@ -36,6 +37,13 @@ interface AuthenticatedRequest {
   user: AuthenticatedUser;
 }
 
+const teacherRoleLabels: Record<string, string> = {
+  [TeacherRoleType.SUBJECT_TEACHER]: '任课老师',
+  [TeacherRoleType.HEAD_TEACHER]: '班主任',
+  [TeacherRoleType.LIFE_TEACHER]: '生活老师',
+  [TeacherRoleType.ACADEMIC_TEACHER]: '学服老师',
+};
+
 @UseGuards(JwtAuthGuard)
 @Controller('classes')
 export class ClassesController {
@@ -302,7 +310,7 @@ export class ClassesController {
         recipientIds: [dto.userId],
         type: NotificationType.CLASS_CHANGE,
         title: '班级分配',
-        content: `您已被分配到班级担任${dto.roleType}角色`,
+        content: `您已被分配到班级担任${teacherRoleLabels[dto.roleType] ?? dto.roleType}角色`,
       });
     } catch {}
     return result;

apps/server/src/classes/classes.membership.spec.ts

@@ -0,0 +1,95 @@
+import { BadRequestException, NotFoundException } from '@nestjs/common';
+import { ClassesService } from './classes.service';
+import { ClassStudent } from '../entities';
+
+function createService(
+  classStudentRepo: Record<string, jest.Mock>,
+  classRepo: Record<string, jest.Mock> = { findOne: jest.fn().mockResolvedValue({ id: 3 }) },
+  studentRepo: Record<string, jest.Mock> = {
+    find: jest.fn().mockResolvedValue([{ id: 8 }, { id: 9 }, { id: 10 }]),
+  },
+) {
+  return new ClassesService(
+    classRepo as never,
+    classStudentRepo as never,
+    {} as never,
+    {} as never,
+    {} as never,
+    {} as never,
+    studentRepo as never,
+    {} as never,
+  );
+}
+
+describe('ClassesService — student membership lifecycle', () => {
+  it('marks an active membership as left instead of deleting it', async () => {
+    const membership = {
+      classId: 3,
+      studentId: 8,
+      status: 'active',
+      leaveDate: null,
+    } as ClassStudent;
+    const repo = {
+      findOne: jest.fn().mockResolvedValue(membership),
+      save: jest.fn().mockImplementation(async (value: ClassStudent) => value),
+    };
+    const service = createService(repo);
+
+    await service.removeStudent(3, 8);
+
+    expect(membership.status).toBe('left');
+    expect(membership.leaveDate).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+    expect(repo.save).toHaveBeenCalledWith(membership);
+  });
+
+  it('rejects removing an already-left membership', async () => {
+    const repo = {
+      findOne: jest.fn().mockResolvedValue({ status: 'left' }),
+      save: jest.fn(),
+    };
+    const service = createService(repo);
+
+    await expect(service.removeStudent(3, 8)).rejects.toBeInstanceOf(BadRequestException);
+    expect(repo.save).not.toHaveBeenCalled();
+  });
+
+  it('rejects removing a student without a membership', async () => {
+    const repo = {
+      findOne: jest.fn().mockResolvedValue(null),
+      save: jest.fn(),
+    };
+    const service = createService(repo);
+
+    await expect(service.removeStudent(3, 8)).rejects.toBeInstanceOf(NotFoundException);
+  });
+
+  it('reactivates left memberships, creates new ones, and skips active ones', async () => {
+    const left = {
+      id: 1,
+      classId: 3,
+      studentId: 8,
+      status: 'left',
+      joinDate: '2026-01-01',
+      leaveDate: '2026-02-01',
+    } as ClassStudent;
+    const active = { id: 2, classId: 3, studentId: 9, status: 'active' } as ClassStudent;
+    const repo = {
+      find: jest.fn().mockResolvedValue([left, active]),
+      create: jest.fn().mockImplementation((value: Partial<ClassStudent>) => value),
+      save: jest.fn().mockImplementation(async (value: ClassStudent[]) => value),
+    };
+    const service = createService(repo);
+
+    const result = await service.addStudents(3, [8, 9, 10, 10]);
+
+    expect(result).toEqual({ added: 2, skipped: 1 });
+    expect(left).toMatchObject({ status: 'active', leaveDate: null });
+    expect(left.joinDate).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+    expect(repo.create).toHaveBeenCalledWith(
+      expect.objectContaining({ classId: 3, studentId: 10, status: 'active' }),
+    );
+    expect(repo.save).toHaveBeenCalledWith(
+      expect.arrayContaining([left, expect.objectContaining({ studentId: 10 })]),
+    );
+  });
+});

apps/server/src/classes/classes.service.ts

@@ -227,34 +227,45 @@ export class ClassesService {
     }
 
     // 3. Fetch existing class-student links in one query
-    const allStudentIds = Array.from(dingToStudentId.values());
-    const alreadyInClass = new Set<number>();
-    if (allStudentIds.length > 0) {
-      const existingClassStudents = await this.classStudentRepo.find({
-        where: { classId, studentId: In(allStudentIds) },
-      });
-      for (const cs of existingClassStudents) {
-        alreadyInClass.add(cs.studentId);
+    const allStudentIds = Array.from(new Set(dingToStudentId.values()));
+    const existingClassStudents =
+      allStudentIds.length > 0
+        ? await this.classStudentRepo.find({
+            where: { classId, studentId: In(allStudentIds) },
+          })
+        : [];
+    const existingByStudentId = new Map(
+      existingClassStudents.map((classStudent) => [classStudent.studentId, classStudent]),
+    );
+    const today = new Date().toISOString().slice(0, 10);
+    let skipped = 0;
+    const memberships = allStudentIds.flatMap((studentId) => {
+      const existing = existingByStudentId.get(studentId);
+      if (existing?.status === 'active') {
+        skipped++;
+        return [];
       }
-    }
-
-    // 4. Batch insert new class-student records
-    const newClassStudents = allStudentIds
-      .filter((sid) => !alreadyInClass.has(sid))
-      .map((studentId) =>
+      if (existing) {
+        existing.status = 'active';
+        existing.joinDate = today;
+        existing.leaveDate = null;
+        return [existing];
+      }
+      return [
         this.classStudentRepo.create({
           classId,
           studentId,
           status: 'active',
-          joinDate: new Date().toISOString().slice(0, 10),
+          joinDate: today,
         }),
-      );
+      ];
+    });
 
-    if (newClassStudents.length > 0) {
-      await this.classStudentRepo.save(newClassStudents);
+    if (memberships.length > 0) {
+      await this.classStudentRepo.save(memberships);
     }
 
-    return { imported: newClassStudents.length, skipped: alreadyInClass.size };
+    return { imported: memberships.length, skipped };
   }
   async update(id: number, dto: UpdateClassDto) {
     const cls = await this.classRepo.findOne({ where: { id } });
@@ -315,26 +326,61 @@ export class ClassesService {
   }
 
   async addStudents(classId: number, studentIds: number[]) {
+    const uniqueStudentIds = [...new Set(studentIds)];
+    if (uniqueStudentIds.length === 0) return { added: 0, skipped: 0 };
+
+    const cls = await this.classRepo.findOne({ where: { id: classId } });
+    if (!cls) throw new NotFoundException('班级不存在');
+
+    const students = await this.studentRepo.find({ where: { id: In(uniqueStudentIds) } });
+    if (students.length !== uniqueStudentIds.length) {
+      throw new NotFoundException('部分学生不存在');
+    }
+
     const existing = await this.classStudentRepo.find({
-      where: { classId, studentId: In(studentIds) },
+      where: { classId, studentId: In(uniqueStudentIds) },
     });
-    const existingIds = new Set(existing.map((e) => e.studentId));
-    const newIds = studentIds.filter((id) => !existingIds.has(id));
-
-    const entries = newIds.map((sid) =>
-      this.classStudentRepo.create({
-        classId,
-        studentId: sid,
-        joinDate: new Date().toISOString().split('T')[0],
-      }),
+    const existingByStudentId = new Map(
+      existing.map((classStudent) => [classStudent.studentId, classStudent]),
     );
-    if (entries.length) await this.classStudentRepo.save(entries);
+    const today = new Date().toISOString().split('T')[0];
+    let skipped = 0;
+    const memberships = uniqueStudentIds.flatMap((studentId) => {
+      const current = existingByStudentId.get(studentId);
+      if (current?.status === 'active') {
+        skipped++;
+        return [];
+      }
+      if (current) {
+        current.status = 'active';
+        current.joinDate = today;
+        current.leaveDate = null;
+        return [current];
+      }
+      return [
+        this.classStudentRepo.create({
+          classId,
+          studentId,
+          status: 'active',
+          joinDate: today,
+        }),
+      ];
+    });
+    if (memberships.length) await this.classStudentRepo.save(memberships);
 
-    return { added: entries.length, skipped: studentIds.length - entries.length };
+    return { added: memberships.length, skipped };
   }
 
   async removeStudent(classId: number, studentId: number) {
-    await this.classStudentRepo.delete({ classId, studentId });
+    const membership = await this.classStudentRepo.findOne({
+      where: { classId, studentId },
+    });
+    if (!membership) throw new NotFoundException('学生不在该班级');
+    if (membership.status !== 'active') throw new BadRequestException('学生已离班');
+
+    membership.status = 'left';
+    membership.leaveDate = new Date().toISOString().split('T')[0];
+    await this.classStudentRepo.save(membership);
     return { success: true };
   }
 

apps/server/src/classroom-rentals/classroom-rentals.controller.ts

@@ -137,6 +137,42 @@ export class ClassroomRentalsController {
     return result;
   }
 
+  @Put(':id/cancel')
+  @RequirePermission('rental:edit')
+  async cancel(@Param('id') id: string, @Request() req: any) {
+    const { ipAddress, userAgent } = extractRequestInfo(req);
+    const result = await this.service.cancel(+id);
+    await this.logService.log({
+      userId: req.user?.id,
+      username: req.user?.username,
+      module: '教室租赁',
+      action: '取消租赁',
+      targetId: +id,
+      targetType: 'classroom-rental',
+      ipAddress,
+      userAgent,
+    });
+    return result;
+  }
+
+  @Put(':id/end')
+  @RequirePermission('rental:edit')
+  async end(@Param('id') id: string, @Request() req: any) {
+    const { ipAddress, userAgent } = extractRequestInfo(req);
+    const result = await this.service.end(+id);
+    await this.logService.log({
+      userId: req.user?.id,
+      username: req.user?.username,
+      module: '教室租赁',
+      action: '结束租赁',
+      targetId: +id,
+      targetType: 'classroom-rental',
+      ipAddress,
+      userAgent,
+    });
+    return result;
+  }
+
   @Delete(':id')
   @RequirePermission('rental:delete')
   async remove(@Param('id') id: string, @Request() req: any) {

apps/server/src/classroom-rentals/classroom-rentals.service.spec.ts

@@ -243,7 +243,7 @@ describe('ClassroomRentalsService — rental schedule sync', () => {
         startDate: '2026-03-01',
         endDate: '2026-03-31',
       };
-      const classroom = { id: 1, departmentId: 10 } as Classroom;
+      const classroom = { id: 1, status: 'available' } as Classroom;
       const hostOrganization = {
         id: 1,
         name: 'Host',
@@ -315,8 +315,8 @@ describe('ClassroomRentalsService — rental schedule sync', () => {
         id: 1,
         classroomId: 1,
         lesseeOrganizationId: 2,
-        startDate: '2026-03-01',
-        endDate: '2026-03-31',
+        startDate: '2026-07-01',
+        endDate: '2099-03-31',
         status: 'active',
         notes: '',
         lesseeOrganization: { id: 2, name: 'Organization A' } as Organization,
@@ -324,8 +324,8 @@ describe('ClassroomRentalsService — rental schedule sync', () => {
       } as ClassroomRental;
       const updatedRental = {
         ...existingRental,
-        startDate: '2026-04-01',
-        endDate: '2026-04-30',
+        startDate: '2026-08-01',
+        endDate: '2099-04-30',
       };
       const existingSchedule = {
         id: 50,
@@ -339,12 +339,12 @@ describe('ClassroomRentalsService — rental schedule sync', () => {
       scheduleRepo.createQueryBuilder.mockReturnValue(mockQueryBuilder<ClassSchedule>([]));
       scheduleRepo.findOne.mockResolvedValue(existingSchedule);
 
-      const dto: UpdateRentalDto = { startDate: '2026-04-01', endDate: '2026-04-30' };
+      const dto: UpdateRentalDto = { startDate: '2026-08-01', endDate: '2099-04-30' };
       await service.update(1, dto);
 
       expect(rentalRepo.update).toHaveBeenCalledWith(
         1,
-        expect.objectContaining({ startDate: '2026-04-01', endDate: '2026-04-30' }),
+        expect.objectContaining({ startDate: '2026-08-01', endDate: '2099-04-30' }),
       );
       expect(scheduleRepo.update).toHaveBeenCalledWith(
         50,
@@ -352,8 +352,8 @@ describe('ClassroomRentalsService — rental schedule sync', () => {
           scheduleType: 'RENTAL',
           rentalId: 1,
           classroomId: 1,
-          startDate: '2026-04-01',
-          endDate: '2026-04-30',
+          startDate: '2026-08-01',
+          endDate: '2099-04-30',
           status: 'active',
           subject: 'Organization A 租赁',
         }),
@@ -362,27 +362,59 @@ describe('ClassroomRentalsService — rental schedule sync', () => {
       expect(scheduleRepo.delete).not.toHaveBeenCalled();
     });
 
-    it('deletes the RENTAL schedule row when status changes to cancelled', async () => {
+    it('deletes the RENTAL schedule row when the rental is cancelled', async () => {
       const rental = {
         id: 1,
         classroomId: 1,
         lesseeOrganizationId: 2,
-        startDate: '2026-03-01',
-        endDate: '2026-03-31',
+        startDate: '2026-07-01',
+        endDate: '2099-03-31',
         status: 'active',
         lesseeOrganization: { id: 2, name: 'Organization A' } as Organization,
       } as ClassroomRental;
-      const cancelledRental = { ...rental, status: 'cancelled' };
+      const cancelledRental = { ...rental, status: 'cancelled' } as ClassroomRental;
 
       rentalRepo.findOne.mockResolvedValueOnce(rental).mockResolvedValueOnce(cancelledRental);
 
-      await service.update(1, { status: 'cancelled' });
+      await service.cancel(1);
 
       expect(rentalRepo.update).toHaveBeenCalledWith(1, { status: 'cancelled' });
       expect(scheduleRepo.delete).toHaveBeenCalledWith({ rentalId: 1, scheduleType: 'RENTAL' });
-      expect(scheduleRepo.findOne).not.toHaveBeenCalled();
-      expect(scheduleRepo.update).not.toHaveBeenCalled();
-      expect(scheduleRepo.create).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('lifecycle actions', () => {
+    it('ends an active rental and shortens a future end date', async () => {
+      const rental = {
+        id: 1,
+        classroomId: 1,
+        startDate: '2026-07-01',
+        endDate: '2099-12-31',
+        status: 'active',
+        lesseeOrganization: { name: 'Organization A' },
+      } as ClassroomRental;
+      const ended = { ...rental, status: 'ended', endDate: '2026-07-13' } as ClassroomRental;
+      rentalRepo.findOne.mockResolvedValueOnce(rental).mockResolvedValueOnce(ended);
+      scheduleRepo.findOne.mockResolvedValue({ id: 50 } as ClassSchedule);
+
+      await service.end(1);
+
+      expect(rentalRepo.update).toHaveBeenCalledWith(
+        1,
+        expect.objectContaining({ status: 'ended' }),
+      );
+      expect(scheduleRepo.update).toHaveBeenCalled();
+    });
+
+    it('rejects ending a future rental', async () => {
+      rentalRepo.findOne.mockResolvedValue({
+        id: 1,
+        startDate: '2099-01-01',
+        endDate: '2099-12-31',
+        status: 'active',
+      } as ClassroomRental);
+
+      await expect(service.end(1)).rejects.toThrow('租赁尚未开始');
     });
   });
 
@@ -394,7 +426,7 @@ describe('ClassroomRentalsService — rental schedule sync', () => {
         lesseeOrganizationId: 2,
         startDate: '2026-03-01',
         endDate: '2026-03-31',
-        status: 'active',
+        status: 'cancelled',
         lesseeOrganization: { id: 2, name: 'Organization A' } as Organization,
       } as ClassroomRental;
 
@@ -419,7 +451,7 @@ describe('ClassroomRentalsService — organization roles', () => {
       createQueryBuilder: jest.fn().mockReturnValue(mockQueryBuilder<ClassroomRental>([])),
     } as any;
     const classroomRepo = {
-      findOne: jest.fn().mockResolvedValue({ id: 1, departmentId: 10 }),
+      findOne: jest.fn().mockResolvedValue({ id: 1, status: 'available' }),
     } as any;
     const organizationRepo = {
       findOne: jest

apps/server/src/classroom-rentals/classroom-rentals.service.ts

@@ -6,8 +6,8 @@ import {
 } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository, Not, LessThanOrEqual, MoreThanOrEqual } from 'typeorm';
-import { ClassroomRental } from '../entities/classroom-rental.entity';
-import { Classroom } from '../entities/classroom.entity';
+import { ClassroomRental, ClassroomRentalStatus } from '../entities/classroom-rental.entity';
+import { Classroom, ClassroomStatus } from '../entities/classroom.entity';
 import { Organization } from '../entities/organization.entity';
 import { ClassSchedule } from '../entities/class-schedule.entity';
 import { CreateRentalDto, UpdateRentalDto } from './dto/rental.dto';
@@ -70,8 +70,11 @@ export class ClassroomRentalsService {
       const last = `${y}-${String(m).padStart(2, '0')}-${String(lastDay).padStart(2, '0')}`;
       qb.andWhere('r.startDate <= :last AND r.endDate >= :first', { first, last });
     }
-    if (!query?.includeEnded) qb.andWhere('r.status != :cancelled', { cancelled: 'cancelled' });
-    return qb.getMany();
+    if (!query?.includeEnded) {
+      qb.andWhere('r.status = :active', { active: ClassroomRentalStatus.ACTIVE });
+    }
+    const rentals = await qb.getMany();
+    return rentals.map((rental) => this.withEffectiveStatus(rental));
   }
 
   async findOne(id: number) {
@@ -80,7 +83,7 @@ export class ClassroomRentalsService {
       relations: ['classroom', 'lessorOrganization', 'lesseeOrganization'],
     });
     if (!rental) throw new NotFoundException('租赁订单不存在');
-    return rental;
+    return this.withEffectiveStatus(rental);
   }
 
   async getUnavailableDates(classroomId: number, year: number, month: number, excludeId?: number) {
@@ -93,7 +96,7 @@ export class ClassroomRentalsService {
         where: {
           ...(excludeId ? { id: Not(excludeId) } : {}),
           classroomId,
-          status: Not('cancelled'),
+          status: ClassroomRentalStatus.ACTIVE,
           startDate: LessThanOrEqual(monthEnd),
           endDate: MoreThanOrEqual(monthStart),
         },
@@ -101,7 +104,7 @@ export class ClassroomRentalsService {
       this.scheduleRepo.find({
         where: {
           classroomId,
-          status: 'active',
+          status: ClassroomRentalStatus.ACTIVE,
           scheduleType: 'INTERNAL',
           startDate: LessThanOrEqual(monthEnd),
           endDate: MoreThanOrEqual(monthStart),
@@ -133,7 +136,7 @@ export class ClassroomRentalsService {
       .createQueryBuilder('r')
       .leftJoinAndSelect('r.lesseeOrganization', 'lesseeOrganization')
       .where('r.classroomId = :cid', { cid: classroomId })
-      .andWhere('r.status != :cancelled', { cancelled: 'cancelled' })
+      .andWhere('r.status = :active', { active: ClassroomRentalStatus.ACTIVE })
       .andWhere('r.startDate <= :end', { end: endDate })
       .andWhere('r.endDate >= :start', { start: startDate });
     if (excludeId) qb.andWhere('r.id != :excludeId', { excludeId });
@@ -222,6 +225,9 @@ export class ClassroomRentalsService {
     if (dto.startDate > dto.endDate) throw new BadRequestException('起始日期不能晚于结束日期');
     const classroom = await this.classroomRepo.findOne({ where: { id: dto.classroomId } });
     if (!classroom) throw new NotFoundException('教室不存在');
+    if (classroom.status !== ClassroomStatus.AVAILABLE) {
+      throw new BadRequestException('仅可用教室可以创建租赁');
+    }
     const lessorOrganization = dto.lessorOrganizationId
       ? await this.organizationRepo.findOne({
           where: { id: dto.lessorOrganizationId, status: 'active' },
@@ -253,7 +259,7 @@ export class ClassroomRentalsService {
       lessorOrganizationId: lessorOrganization.id,
       lesseeOrganizationId: lesseeOrganization.id,
       createdBy: userId,
-      status: 'active',
+      status: ClassroomRentalStatus.ACTIVE,
     });
     const saved = await this.repo.save(rental);
     await this.syncScheduleFromRental(saved, lesseeOrganization.name);
@@ -262,11 +268,21 @@ export class ClassroomRentalsService {
 
   async update(id: number, dto: UpdateRentalDto) {
     const rental = await this.findOne(id);
+    if (rental.effectiveStatus !== ClassroomRentalStatus.ACTIVE) {
+      throw new BadRequestException('已结束或已取消的租赁不能编辑');
+    }
     // 若修改了教室/日期，重新冲突检查
     const newClassroomId = dto.classroomId ?? rental.classroomId;
     const newStart = dto.startDate ?? rental.startDate;
     const newEnd = dto.endDate ?? rental.endDate;
     if (newStart > newEnd) throw new BadRequestException('起始日期不能晚于结束日期');
+    if (dto.classroomId && dto.classroomId !== rental.classroomId) {
+      const classroom = await this.classroomRepo.findOne({ where: { id: dto.classroomId } });
+      if (!classroom) throw new NotFoundException('教室不存在');
+      if (classroom.status !== ClassroomStatus.AVAILABLE) {
+        throw new BadRequestException('仅可用教室可以承接租赁');
+      }
+    }
     if (dto.classroomId || dto.startDate || dto.endDate) {
       const conflicts = await this.findConflicts(newClassroomId, newStart, newEnd, id);
       if (conflicts.length > 0) {
@@ -300,16 +316,46 @@ export class ClassroomRentalsService {
     }
     await this.repo.update(id, dto);
     const updated = await this.findOne(id);
-    if (dto.status === 'cancelled') {
-      await this.scheduleRepo.delete({ rentalId: id, scheduleType: 'RENTAL' });
-    } else {
-      await this.syncScheduleFromRental(updated);
-    }
+    await this.syncScheduleFromRental(updated);
     return updated;
   }
 
+  async cancel(id: number) {
+    const rental = await this.findOne(id);
+    if (rental.effectiveStatus !== ClassroomRentalStatus.ACTIVE) {
+      throw new BadRequestException('仅有效租赁可以取消');
+    }
+    await this.repo.update(id, { status: ClassroomRentalStatus.CANCELLED });
+    await this.scheduleRepo.delete({ rentalId: id, scheduleType: 'RENTAL' });
+    return this.findOne(id);
+  }
+
+  async end(id: number) {
+    const rental = await this.findOne(id);
+    if (rental.effectiveStatus !== ClassroomRentalStatus.ACTIVE) {
+      throw new BadRequestException('仅有效租赁可以结束');
+    }
+    const today = new Intl.DateTimeFormat('en-CA', {
+      timeZone: 'Asia/Shanghai',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+    }).format(new Date());
+    if (rental.startDate > today) throw new BadRequestException('租赁尚未开始，不能结束');
+    await this.repo.update(id, {
+      status: ClassroomRentalStatus.ENDED,
+      endDate: rental.endDate > today ? today : rental.endDate,
+    });
+    const ended = await this.findOne(id);
+    await this.syncScheduleFromRental(ended);
+    return ended;
+  }
+
   async remove(id: number) {
     const rental = await this.findOne(id);
+    if (rental.effectiveStatus === ClassroomRentalStatus.ACTIVE) {
+      throw new BadRequestException('进行中的租赁请先取消或结束');
+    }
     // 同步删除对应排课记录
     await this.scheduleRepo.delete({ rentalId: id, scheduleType: 'RENTAL' });
     // 同时删除合同文件
@@ -327,6 +373,20 @@ export class ClassroomRentalsService {
     return { message: '删除成功' };
   }
 
+  private withEffectiveStatus(rental: ClassroomRental) {
+    const today = new Intl.DateTimeFormat('en-CA', {
+      timeZone: 'Asia/Shanghai',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+    }).format(new Date());
+    const effectiveStatus =
+      rental.status === ClassroomRentalStatus.ACTIVE && rental.endDate < today
+        ? ClassroomRentalStatus.ENDED
+        : rental.status;
+    return Object.assign(rental, { effectiveStatus });
+  }
+
   /**
    * 同步租赁订单到 class_schedules（schedule_type = 'RENTAL'）
    */
@@ -348,7 +408,7 @@ export class ClassroomRentalsService {
       teacherId: null,
       scheduleType: 'RENTAL',
       rentalId: rental.id,
-      status: 'active',
+      status: rental.status === ClassroomRentalStatus.CANCELLED ? 'cancelled' : 'active',
       notes: rental.notes,
     };
     if (schedule) {
@@ -437,14 +497,16 @@ export class ClassroomRentalsService {
     const last = `${year}-${String(month).padStart(2, '0')}-${String(lastDay).padStart(2, '0')}`;
 
     const classrooms = await this.classroomRepo.find({
-      where: { status: Not('archived') },
+      where: { status: Not(ClassroomStatus.ARCHIVED) },
       order: { building: 'ASC', name: 'ASC' },
     });
     const rentals = await this.repo
       .createQueryBuilder('r')
       .leftJoinAndSelect('r.lesseeOrganization', 'lesseeOrganization')
       .leftJoinAndSelect('r.classroom', 'classroom')
-      .where('r.status != :cancelled', { cancelled: 'cancelled' })
+      .where('r.status IN (:...statuses)', {
+        statuses: [ClassroomRentalStatus.ACTIVE, ClassroomRentalStatus.ENDED],
+      })
       .andWhere('r.startDate <= :last AND r.endDate >= :first', { first, last })
       .getMany();
 

apps/server/src/classroom-rentals/dto/rental.dto.ts

@@ -1,4 +1,4 @@
-import { IsOptional, IsString, IsInt, IsNumber, IsEnum, IsDateString } from 'class-validator';
+import { IsOptional, IsString, IsInt, IsNumber, IsDateString } from 'class-validator';
 
 export class CreateRentalDto {
   @IsInt()
@@ -62,8 +62,4 @@ export class UpdateRentalDto {
   @IsOptional()
   @IsString()
   notes?: string;
-
-  @IsOptional()
-  @IsEnum(['active', 'ended', 'cancelled'])
-  status?: string;
 }

apps/server/src/classrooms/classrooms.service.ts

@@ -1,14 +1,13 @@
 import { Injectable, NotFoundException, BadRequestException } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
-import { Repository, Not } from 'typeorm';
-import { Classroom } from '../entities/classroom.entity';
-import { ClassroomRental } from '../entities/classroom-rental.entity';
+import { Repository, Not, MoreThanOrEqual } from 'typeorm';
+import { Classroom, ClassroomStatus } from '../entities/classroom.entity';
+import { ClassroomRental, ClassroomRentalStatus } from '../entities/classroom-rental.entity';
 import { ClassSchedule } from '../entities/class-schedule.entity';
 import { CreateClassroomDto, UpdateClassroomDto } from './dto/classroom.dto';
 
 @Injectable()
 export class ClassroomsService {
-
   constructor(
     @InjectRepository(Classroom) private repo: Repository<Classroom>,
     @InjectRepository(ClassroomRental) private rentalRepo: Repository<ClassroomRental>,
@@ -21,49 +20,148 @@ export class ClassroomsService {
     if (query?.roomType) where.roomType = query.roomType;
     if (!query?.includeArchived) where.status = Not('archived');
     const list = await this.repo.find({ where, order: { building: 'ASC', name: 'ASC' } });
-    const usageMap = await this.getCurrentUsageForClassrooms(list.map((c) => c.id));
-    return list.map((c) => ({ ...c, currentUsage: usageMap.get(c.id) ?? null }));
+    const usageMap = await this.getUsageForClassrooms(list.map((c) => c.id));
+    return list.map((classroom) => this.withEffectiveStatus(classroom, usageMap.get(classroom.id)));
   }
 
   async findOne(id: number) {
     const cls = await this.repo.findOne({ where: { id } });
     if (!cls) throw new NotFoundException('教室不存在');
-    const usageMap = await this.getCurrentUsageForClassrooms([id]);
-    return { ...cls, currentUsage: usageMap.get(id) ?? null };
+    const usageMap = await this.getUsageForClassrooms([id]);
+    return this.withEffectiveStatus(cls, usageMap.get(id));
   }
 
   async create(dto: CreateClassroomDto) {
     const exists = await this.repo.findOne({ where: { name: dto.name } });
     if (exists) throw new BadRequestException(`教室 ${dto.name} 已存在`);
-    return this.repo.save(this.repo.create(dto));
+    return this.repo.save(this.repo.create({ ...dto, status: ClassroomStatus.AVAILABLE }));
   }
 
   async update(id: number, dto: UpdateClassroomDto) {
-    await this.findOne(id);
+    const classroom = await this.repo.findOne({ where: { id } });
+    if (!classroom) throw new NotFoundException('教室不存在');
+    if (dto.status === ClassroomStatus.MAINTENANCE && classroom.status !== dto.status) {
+      await this.assertNoActiveAllocations(id);
+    }
     await this.repo.update(id, dto);
     return this.repo.findOne({ where: { id } });
   }
 
   async remove(id: number) {
-    await this.findOne(id);
-    await this.repo.update(id, { status: 'archived' });
+    const classroom = await this.repo.findOne({ where: { id } });
+    if (!classroom) throw new NotFoundException('教室不存在');
+    await this.assertNoActiveAllocations(id);
+    await this.repo.update(id, { status: ClassroomStatus.ARCHIVED });
     return { message: '已归档' };
   }
 
   async restore(id: number) {
-    await this.findOne(id);
-    await this.repo.update(id, { status: 'reserved' });
+    const classroom = await this.repo.findOne({ where: { id } });
+    if (!classroom) throw new NotFoundException('教室不存在');
+    await this.repo.update(id, { status: ClassroomStatus.AVAILABLE });
     return this.repo.findOne({ where: { id } });
   }
 
-  private async getCurrentUsageForClassrooms(classroomIds: number[]): Promise<Map<number, { type: 'schedule' | 'rental'; title: string; startTime: string; endTime: string }>> {
-    const result = new Map<number, { type: 'schedule' | 'rental'; title: string; startTime: string; endTime: string }>();
+  private withEffectiveStatus(
+    classroom: Classroom,
+    usage?: {
+      state: 'in_use' | 'reserved';
+      currentUsage: {
+        type: 'schedule' | 'rental';
+        title: string;
+        startTime: string;
+        endTime: string;
+      } | null;
+    },
+  ) {
+    const effectiveStatus =
+      classroom.status === ClassroomStatus.ARCHIVED ||
+      classroom.status === ClassroomStatus.MAINTENANCE
+        ? classroom.status
+        : (usage?.state ?? ClassroomStatus.AVAILABLE);
+    return { ...classroom, currentUsage: usage?.currentUsage ?? null, effectiveStatus };
+  }
+
+  private async assertNoActiveAllocations(classroomId: number) {
+    const today = new Intl.DateTimeFormat('en-CA', {
+      timeZone: 'Asia/Shanghai',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+    }).format(new Date());
+    const scheduleCount = await this.scheduleRepo
+      .createQueryBuilder('schedule')
+      .where('schedule.classroomId = :classroomId', { classroomId })
+      .andWhere('schedule.status = :active', { active: 'active' })
+      .andWhere('schedule.endDate >= :today', { today })
+      .getCount();
+    const rentalCount = await this.rentalRepo.count({
+      where: {
+        classroomId,
+        status: ClassroomRentalStatus.ACTIVE,
+        endDate: MoreThanOrEqual(today),
+      },
+    });
+    if (rentalCount > 0 || scheduleCount > 0) {
+      throw new BadRequestException('该教室存在有效排课或租赁，无法维护或归档');
+    }
+  }
+
+  private async getUsageForClassrooms(classroomIds: number[]): Promise<
+    Map<
+      number,
+      {
+        state: 'in_use' | 'reserved';
+        currentUsage: {
+          type: 'schedule' | 'rental';
+          title: string;
+          startTime: string;
+          endTime: string;
+        } | null;
+      }
+    >
+  > {
+    const result = new Map<
+      number,
+      {
+        state: 'in_use' | 'reserved';
+        currentUsage: {
+          type: 'schedule' | 'rental';
+          title: string;
+          startTime: string;
+          endTime: string;
+        } | null;
+      }
+    >();
     if (classroomIds.length === 0) return result;
 
     const now = new Date();
-    const todayStr = now.toISOString().slice(0, 10);
-    const currentTime = now.toTimeString().slice(0, 5);
-    const weekDay = now.getDay() || 7;
+    const todayStr = new Intl.DateTimeFormat('en-CA', {
+      timeZone: 'Asia/Shanghai',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+    }).format(now);
+    const currentTime = new Intl.DateTimeFormat('en-GB', {
+      timeZone: 'Asia/Shanghai',
+      hour: '2-digit',
+      minute: '2-digit',
+      hour12: false,
+    }).format(now);
+    const shanghaiParts = new Intl.DateTimeFormat('en-US', {
+      timeZone: 'Asia/Shanghai',
+      weekday: 'short',
+    }).format(now);
+    const weekDayMap: Record<string, number> = {
+      Mon: 1,
+      Tue: 2,
+      Wed: 3,
+      Thu: 4,
+      Fri: 5,
+      Sat: 6,
+      Sun: 7,
+    };
+    const weekDay = weekDayMap[shanghaiParts];
 
     const schedules = await this.scheduleRepo
       .createQueryBuilder('s')
@@ -71,26 +169,37 @@ export class ClassroomsService {
       .select('s.classroomId', 'classroomId')
       .addSelect('s.startTime', 'startTime')
       .addSelect('s.endTime', 'endTime')
+      .addSelect('s.startDate', 'startDate')
+      .addSelect('s.endDate', 'endDate')
+      .addSelect('s.weekDay', 'weekDay')
       .addSelect('s.subject', 'subject')
       .addSelect('c.name', 'className')
       .where('s.classroomId IN (:...ids)', { ids: classroomIds })
       .andWhere('s.status = :active', { active: 'active' })
       .andWhere('s.scheduleType = :type', { type: 'INTERNAL' })
-      .andWhere('s.startDate <= :today', { today: todayStr })
       .andWhere('s.endDate >= :today', { today: todayStr })
-      .andWhere('s.weekDay = :weekDay', { weekDay })
-      .andWhere('s.startTime <= :currentTime', { currentTime })
-      .andWhere('s.endTime >= :currentTime', { currentTime })
       .getRawMany();
 
-    for (const s of schedules) {
-      const classroomId = Number(s.classroomId);
-      if (!result.has(classroomId)) {
+    for (const schedule of schedules) {
+      const classroomId = Number(schedule.classroomId);
+      const isCurrent =
+        String(schedule.startDate) <= todayStr &&
+        String(schedule.endDate) >= todayStr &&
+        Number(schedule.weekDay) === weekDay &&
+        String(schedule.startTime) <= currentTime &&
+        String(schedule.endTime) >= currentTime;
+      const existing = result.get(classroomId);
+      if (!existing || isCurrent) {
         result.set(classroomId, {
-          type: 'schedule',
-          title: `${s.className || ''} ${s.subject || ''}`.trim() || '内部课程',
-          startTime: String(s.startTime),
-          endTime: String(s.endTime),
+          state: isCurrent ? 'in_use' : 'reserved',
+          currentUsage: isCurrent
+            ? {
+                type: 'schedule',
+                title: `${schedule.className || ''} ${schedule.subject || ''}`.trim() || '内部课程',
+                startTime: String(schedule.startTime),
+                endTime: String(schedule.endTime),
+              }
+            : null,
         });
       }
     }
@@ -103,19 +212,25 @@ export class ClassroomsService {
       .addSelect('r.endDate', 'endDate')
       .addSelect('t.name', 'tenantName')
       .where('r.classroomId IN (:...ids)', { ids: classroomIds })
-      .andWhere('r.status != :cancelled', { cancelled: 'cancelled' })
-      .andWhere('r.startDate <= :today', { today: todayStr })
+      .andWhere('r.status = :active', { active: ClassroomRentalStatus.ACTIVE })
       .andWhere('r.endDate >= :today', { today: todayStr })
       .getRawMany();
 
-    for (const r of rentals) {
-      const classroomId = Number(r.classroomId);
-      if (!result.has(classroomId)) {
+    for (const rental of rentals) {
+      const classroomId = Number(rental.classroomId);
+      const isCurrent = String(rental.startDate) <= todayStr && String(rental.endDate) >= todayStr;
+      const existing = result.get(classroomId);
+      if (!existing || isCurrent) {
         result.set(classroomId, {
-          type: 'rental',
-          title: r.tenantName ? `${r.tenantName} 租赁` : '外部租赁',
-          startTime: '00:00',
-          endTime: '23:59',
+          state: isCurrent ? 'in_use' : 'reserved',
+          currentUsage: isCurrent
+            ? {
+                type: 'rental',
+                title: rental.tenantName ? `${rental.tenantName} 租赁` : '外部租赁',
+                startTime: '00:00',
+                endTime: '23:59',
+              }
+            : null,
         });
       }
     }
@@ -136,24 +251,38 @@ export class ClassroomsService {
     let skipped = 0;
     const errors: string[] = [];
     for (const row of rows) {
-      if (!row.name?.trim()) { skipped++; continue; }
+      if (!row.name?.trim()) {
+        skipped++;
+        continue;
+      }
       const exists = await this.repo.findOne({ where: { name: row.name.trim() } });
-      if (exists) { errors.push(`教室 ${row.name} 已存在`); skipped++; continue; }
+      if (exists) {
+        errors.push(`教室 ${row.name} 已存在`);
+        skipped++;
+        continue;
+      }
       await this.repo.save(this.repo.create({ ...row, capacity: row.capacity || 30 }));
       imported++;
     }
-    return { message: `成功导入 ${imported} 间教室，跳过 ${skipped} 间`, imported, skipped, errors: errors.length > 0 ? errors : undefined };
+    return {
+      message: `成功导入 ${imported} 间教室，跳过 ${skipped} 间`,
+      imported,
+      skipped,
+      errors: errors.length > 0 ? errors : undefined,
+    };
   }
 
   async getUsageReport(dateFrom: string, dateTo: string) {
     const classrooms = await this.repo.find({
-      where: { status: Not('archived') },
+      where: { status: Not(ClassroomStatus.ARCHIVED) },
       order: { building: 'ASC', name: 'ASC' },
     });
 
     const rentals = await this.rentalRepo
       .createQueryBuilder('r')
-      .where('r.status != :cancelled', { cancelled: 'cancelled' })
+      .where('r.status IN (:...statuses)', {
+        statuses: [ClassroomRentalStatus.ACTIVE, ClassroomRentalStatus.ENDED],
+      })
       .andWhere('r.startDate <= :dateTo AND r.endDate >= :dateFrom', { dateFrom, dateTo })
       .getMany();
 

apps/server/src/classrooms/classrooms.status.spec.ts

@@ -0,0 +1,39 @@
+import { BadRequestException } from '@nestjs/common';
+import { ClassroomStatus } from '../entities/classroom.entity';
+import { ClassroomsService } from './classrooms.service';
+
+function createService(options?: { rentals?: number; schedules?: number }) {
+  const repo = {
+    findOne: jest.fn().mockResolvedValue({ id: 1, name: 'A101', status: ClassroomStatus.ARCHIVED }),
+    update: jest.fn(),
+  };
+  const rentalRepo = { count: jest.fn().mockResolvedValue(options?.rentals ?? 0) };
+  const scheduleRepo = {
+    createQueryBuilder: jest.fn().mockReturnValue({
+      where: jest.fn().mockReturnThis(),
+      andWhere: jest.fn().mockReturnThis(),
+      getCount: jest.fn().mockResolvedValue(options?.schedules ?? 0),
+    }),
+  };
+  return {
+    service: new ClassroomsService(repo as never, rentalRepo as never, scheduleRepo as never),
+    repo,
+  };
+}
+
+describe('ClassroomsService — persisted classroom status', () => {
+  it('restores an archived classroom to available', async () => {
+    const { service, repo } = createService();
+
+    await service.restore(1);
+
+    expect(repo.update).toHaveBeenCalledWith(1, { status: ClassroomStatus.AVAILABLE });
+  });
+
+  it('rejects archiving a classroom with active allocations', async () => {
+    const { service, repo } = createService({ rentals: 1 });
+
+    await expect(service.remove(1)).rejects.toBeInstanceOf(BadRequestException);
+    expect(repo.update).not.toHaveBeenCalled();
+  });
+});

apps/server/src/classrooms/dto/classroom.dto.ts

@@ -1,4 +1,5 @@
 import { IsOptional, IsString, IsNotEmpty, IsInt, IsEnum } from 'class-validator';
+import { ClassroomStatus } from '../../entities/classroom.entity';
 
 export class CreateClassroomDto {
   @IsString()
@@ -21,11 +22,9 @@ export class CreateClassroomDto {
   @IsString()
   roomType?: string; // 大 / 次大 / 小
 
-
   @IsOptional()
   @IsString()
   notes?: string;
-
 }
 
 export class UpdateClassroomDto {
@@ -49,12 +48,11 @@ export class UpdateClassroomDto {
   @IsString()
   roomType?: string;
 
-
   @IsOptional()
   @IsString()
   notes?: string;
 
   @IsOptional()
-  @IsEnum(['available', 'archived'])
-  status?: string;
+  @IsEnum([ClassroomStatus.AVAILABLE, ClassroomStatus.MAINTENANCE])
+  status?: ClassroomStatus;
 }

apps/server/src/dashboard/dashboard.service.ts

@@ -119,13 +119,12 @@ export class DashboardService {
     const pendingQb = this.depositRepo
       .createQueryBuilder('d')
       .select('SUM(d.amount)', 'total')
-      .where('d.status = :paid', { paid: 'paid' })
-      .andWhere('d.refundStatus IS NULL');
+      .where('d.status = :paid', { paid: 'paid' });
     const pendingResult = await pendingQb.getRawOne();
     const pendingDeposits = parseFloat(pendingResult?.total || '0');
 
     const activeRentals = await this.rentalRepo.count({
-      where: { endDate: MoreThanOrEqual(todayStr) },
+      where: { status: 'active' as const, endDate: MoreThanOrEqual(todayStr) },
     });
 
     const occByBldQb = this.occRepo
@@ -366,7 +365,7 @@ export class DashboardService {
 
   async getClassroomOccupancy() {
     const classrooms = await this.classroomRepo.find({
-      where: { status: Not('archived') },
+      where: { status: 'available' as const },
       order: { building: 'ASC', name: 'ASC' },
     });
     const today = new Date().toISOString().slice(0, 10);
@@ -383,7 +382,7 @@ export class DashboardService {
       .createQueryBuilder('r')
       .select('r.classroomId', 'classroomId')
       .addSelect('COUNT(*)', 'rentalCount')
-      .where('r.status != :cancelled', { cancelled: 'cancelled' })
+      .where('r.status = :active', { active: 'active' })
       .andWhere('r.startDate <= :today AND r.endDate >= :today', { today })
       .groupBy('r.classroomId');
     const rentals = await rentalQb.getRawMany();
@@ -403,7 +402,7 @@ export class DashboardService {
 
   async getClassroomUtilizationStats() {
     const totalClassrooms = await this.classroomRepo.count({
-      where: { status: Not('archived') },
+      where: { status: 'available' as const },
     });
 
     const today = new Date().toISOString().slice(0, 10);
@@ -421,7 +420,7 @@ export class DashboardService {
     const rentalQb = this.rentalRepo
       .createQueryBuilder('r')
       .select('COUNT(DISTINCT r.classroomId)', 'cnt')
-      .where('r.status != :cancelled', { cancelled: 'cancelled' })
+      .where('r.status = :active', { active: 'active' })
       .andWhere('r.startDate <= :today AND r.endDate >= :today', { today });
     const rentalResult = await rentalQb.getRawOne();
 
@@ -438,7 +437,7 @@ export class DashboardService {
     const combinedRentalQb = this.rentalRepo
       .createQueryBuilder('r')
       .select('r.classroomId')
-      .where('r.status != :cancelled', { cancelled: 'cancelled' })
+      .where('r.status = :active', { active: 'active' })
       .andWhere('r.startDate <= :today AND r.endDate >= :today', { today })
       .groupBy('r.classroomId');
     const rentalIds = await combinedRentalQb.getRawMany();

apps/server/src/database/database-migrations.class-student.spec.ts

@@ -0,0 +1,56 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { getDataSourceToken } from '@nestjs/typeorm';
+import { DatabaseMigrationsService } from './database-migrations.service';
+
+function createRunner(tableExists: boolean, columns: string[] = []) {
+  return {
+    connect: jest.fn(),
+    release: jest.fn(),
+    getTables: jest.fn().mockResolvedValue(tableExists ? [{ name: 'class_student' }] : []),
+    getTable: jest.fn().mockResolvedValue({
+      name: 'class_student',
+      columns: columns.map((name) => ({ name })),
+    }),
+    dropColumn: jest.fn().mockResolvedValue(undefined),
+  };
+}
+
+async function createService(runner: ReturnType<typeof createRunner>) {
+  const module: TestingModule = await Test.createTestingModule({
+    providers: [
+      DatabaseMigrationsService,
+      {
+        provide: getDataSourceToken(),
+        useValue: {
+          options: { type: 'better-sqlite3' },
+          createQueryRunner: jest.fn().mockReturnValue(runner),
+        },
+      },
+    ],
+  }).compile();
+  return module.get(DatabaseMigrationsService) as DatabaseMigrationsService & {
+    removeUnusedClassStudentColumns(): Promise<void>;
+  };
+}
+
+describe('DatabaseMigrationsService — class student cleanup', () => {
+  it('drops the unused enrollment_id column', async () => {
+    const runner = createRunner(true, ['id', 'enrollment_id']);
+    const service = await createService(runner);
+
+    await service.removeUnusedClassStudentColumns();
+
+    expect(runner.dropColumn).toHaveBeenCalledWith('class_student', 'enrollment_id');
+    expect(runner.release).toHaveBeenCalled();
+  });
+
+  it('does nothing when the table is absent', async () => {
+    const runner = createRunner(false);
+    const service = await createService(runner);
+
+    await service.removeUnusedClassStudentColumns();
+
+    expect(runner.dropColumn).not.toHaveBeenCalled();
+    expect(runner.release).toHaveBeenCalled();
+  });
+});

apps/server/src/database/database-migrations.classroom-status.spec.ts

@@ -0,0 +1,36 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { getDataSourceToken } from '@nestjs/typeorm';
+import { DatabaseMigrationsService } from './database-migrations.service';
+
+describe('DatabaseMigrationsService — classroom status normalization', () => {
+  it('normalizes legacy persisted statuses to available', async () => {
+    const runner = {
+      connect: jest.fn(),
+      release: jest.fn(),
+      getTables: jest.fn().mockResolvedValue([{ name: 'classrooms' }]),
+      query: jest.fn().mockResolvedValue(undefined),
+    };
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        DatabaseMigrationsService,
+        {
+          provide: getDataSourceToken(),
+          useValue: {
+            options: { type: 'better-sqlite3' },
+            createQueryRunner: jest.fn().mockReturnValue(runner),
+          },
+        },
+      ],
+    }).compile();
+    const service = module.get(DatabaseMigrationsService) as DatabaseMigrationsService & {
+      normalizeClassroomStatuses(): Promise<void>;
+    };
+
+    await service.normalizeClassroomStatuses();
+
+    expect(runner.query).toHaveBeenCalledWith(
+      expect.stringContaining("status NOT IN ('available', 'maintenance', 'archived')"),
+    );
+    expect(runner.release).toHaveBeenCalled();
+  });
+});

apps/server/src/database/database-migrations.deposit-refund.spec.ts

@@ -0,0 +1,101 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { getDataSourceToken } from '@nestjs/typeorm';
+import { DatabaseMigrationsService } from './database-migrations.service';
+
+function createRunner(columns: string[]) {
+  return {
+    connect: jest.fn(),
+    release: jest.fn(),
+    query: jest.fn().mockResolvedValue([]),
+    getTables: jest.fn().mockResolvedValue(columns.length ? [{ name: 'deposits' }] : []),
+    getTable: jest.fn().mockResolvedValue({
+      name: 'deposits',
+      columns: columns.map((name) => ({ name })),
+    }),
+    renameColumn: jest.fn().mockResolvedValue(undefined),
+    dropColumn: jest.fn().mockResolvedValue(undefined),
+  };
+}
+
+async function createService(runner: ReturnType<typeof createRunner>) {
+  const module: TestingModule = await Test.createTestingModule({
+    providers: [
+      DatabaseMigrationsService,
+      {
+        provide: getDataSourceToken(),
+        useValue: {
+          options: { type: 'better-sqlite3' },
+          createQueryRunner: jest.fn().mockReturnValue(runner),
+        },
+      },
+    ],
+  }).compile();
+  return module.get(DatabaseMigrationsService) as DatabaseMigrationsService & {
+    cleanupDepositRefundColumns(): Promise<void>;
+  };
+}
+
+describe('DatabaseMigrationsService — deposit refund cleanup', () => {
+  it('renames refund audit fields and drops approval-flow remnants', async () => {
+    const runner = createRunner([
+      'id',
+      'refund_status',
+      'refund_requested_at',
+      'refund_approved_by',
+      'refund_approved_at',
+      'refund_rejected_reason',
+    ]);
+    const service = await createService(runner);
+
+    await service.cleanupDepositRefundColumns();
+
+    expect(runner.renameColumn).toHaveBeenCalledWith(
+      'deposits',
+      'refund_approved_by',
+      'refunded_by',
+    );
+    expect(runner.renameColumn).toHaveBeenCalledWith(
+      'deposits',
+      'refund_approved_at',
+      'refunded_at',
+    );
+    expect(runner.dropColumn).toHaveBeenCalledWith('deposits', 'refund_status');
+    expect(runner.dropColumn).toHaveBeenCalledWith('deposits', 'refund_requested_at');
+    expect(runner.dropColumn).toHaveBeenCalledWith('deposits', 'refund_rejected_reason');
+    expect(runner.release).toHaveBeenCalled();
+  });
+
+  it('merges legacy audit values before dropping duplicate legacy columns', async () => {
+    const runner = createRunner([
+      'id',
+      'refund_approved_by',
+      'refund_approved_at',
+      'refunded_by',
+      'refunded_at',
+    ]);
+    const service = await createService(runner);
+
+    await service.cleanupDepositRefundColumns();
+
+    expect(runner.query).toHaveBeenCalledWith(
+      'UPDATE deposits SET refunded_by = COALESCE(refunded_by, refund_approved_by)',
+    );
+    expect(runner.query).toHaveBeenCalledWith(
+      'UPDATE deposits SET refunded_at = COALESCE(refunded_at, refund_approved_at)',
+    );
+    expect(runner.dropColumn).toHaveBeenCalledWith('deposits', 'refund_approved_by');
+    expect(runner.dropColumn).toHaveBeenCalledWith('deposits', 'refund_approved_at');
+    expect(runner.renameColumn).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when the deposits table is absent', async () => {
+    const runner = createRunner([]);
+    const service = await createService(runner);
+
+    await service.cleanupDepositRefundColumns();
+
+    expect(runner.renameColumn).not.toHaveBeenCalled();
+    expect(runner.dropColumn).not.toHaveBeenCalled();
+    expect(runner.release).toHaveBeenCalled();
+  });
+});

apps/server/src/database/database-migrations.room-gender.spec.ts

@@ -0,0 +1,38 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { getDataSourceToken } from '@nestjs/typeorm';
+import { DatabaseMigrationsService } from './database-migrations.service';
+
+describe('DatabaseMigrationsService — room gender cleanup', () => {
+  it('drops the retired rooms.gender column', async () => {
+    const runner = {
+      connect: jest.fn(),
+      release: jest.fn(),
+      getTables: jest.fn().mockResolvedValue([{ name: 'rooms' }]),
+      getTable: jest.fn().mockResolvedValue({
+        name: 'rooms',
+        columns: [{ name: 'id' }, { name: 'gender' }],
+      }),
+      dropColumn: jest.fn().mockResolvedValue(undefined),
+    };
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        DatabaseMigrationsService,
+        {
+          provide: getDataSourceToken(),
+          useValue: {
+            options: { type: 'better-sqlite3' },
+            createQueryRunner: jest.fn().mockReturnValue(runner),
+          },
+        },
+      ],
+    }).compile();
+    const service = module.get(DatabaseMigrationsService) as DatabaseMigrationsService & {
+      removeUnusedRoomColumns(): Promise<void>;
+    };
+
+    await service.removeUnusedRoomColumns();
+
+    expect(runner.dropColumn).toHaveBeenCalledWith('rooms', 'gender');
+    expect(runner.release).toHaveBeenCalled();
+  });
+});

apps/server/src/database/database-migrations.service.ts

@@ -15,6 +15,10 @@ export class DatabaseMigrationsService implements OnApplicationBootstrap {
     await this.normalizeClassDates();
     await this.protectAttendanceHistory();
     await this.removeUnusedClassroomColumns();
+    await this.removeUnusedRoomColumns();
+    await this.cleanupDepositRefundColumns();
+    await this.removeUnusedClassStudentColumns();
+    await this.normalizeClassroomStatuses();
   }
 
   private async removeUnusedClassroomColumns(): Promise<void> {
@@ -36,6 +40,92 @@ export class DatabaseMigrationsService implements OnApplicationBootstrap {
     }
   }
 
+  private async removeUnusedRoomColumns(): Promise<void> {
+    const runner = this.dataSource.createQueryRunner();
+    await runner.connect();
+    try {
+      const tables = await runner.getTables(['rooms']);
+      if (tables.length === 0) return;
+
+      const table = await runner.getTable('rooms');
+      if (table?.columns.some((column) => column.name === 'gender')) {
+        await runner.dropColumn('rooms', 'gender');
+      }
+    } finally {
+      await runner.release();
+    }
+  }
+
+  private async cleanupDepositRefundColumns(): Promise<void> {
+    const runner = this.dataSource.createQueryRunner();
+    await runner.connect();
+    try {
+      const tables = await runner.getTables(['deposits']);
+      if (tables.length === 0) return;
+
+      const table = await runner.getTable('deposits');
+      const columnNames = new Set(table?.columns.map((column) => column.name) ?? []);
+      for (const [legacyName, currentName] of [
+        ['refund_approved_by', 'refunded_by'],
+        ['refund_approved_at', 'refunded_at'],
+      ] as const) {
+        if (!columnNames.has(legacyName)) continue;
+
+        if (columnNames.has(currentName)) {
+          await runner.query(
+            `UPDATE deposits SET ${currentName} = COALESCE(${currentName}, ${legacyName})`,
+          );
+          await runner.dropColumn('deposits', legacyName);
+        } else {
+          await runner.renameColumn('deposits', legacyName, currentName);
+          columnNames.add(currentName);
+        }
+        columnNames.delete(legacyName);
+      }
+
+      for (const columnName of ['refund_status', 'refund_requested_at', 'refund_rejected_reason']) {
+        if (columnNames.has(columnName)) {
+          await runner.dropColumn('deposits', columnName);
+          columnNames.delete(columnName);
+        }
+      }
+    } finally {
+      await runner.release();
+    }
+  }
+
+  private async removeUnusedClassStudentColumns(): Promise<void> {
+    const runner = this.dataSource.createQueryRunner();
+    await runner.connect();
+    try {
+      const tables = await runner.getTables(['class_student']);
+      if (tables.length === 0) return;
+
+      const table = await runner.getTable('class_student');
+      if (table?.columns.some((column) => column.name === 'enrollment_id')) {
+        await runner.dropColumn('class_student', 'enrollment_id');
+      }
+    } finally {
+      await runner.release();
+    }
+  }
+
+  private async normalizeClassroomStatuses(): Promise<void> {
+    const runner = this.dataSource.createQueryRunner();
+    await runner.connect();
+    try {
+      const tables = await runner.getTables(['classrooms']);
+      if (tables.length === 0) return;
+      await runner.query(`
+        UPDATE classrooms
+        SET status = 'available'
+        WHERE status IS NULL OR status NOT IN ('available', 'maintenance', 'archived')
+      `);
+    } finally {
+      await runner.release();
+    }
+  }
+
   private async ensureAiConfigTable(): Promise<void> {
     const runner = this.dataSource.createQueryRunner();
     await runner.connect();
@@ -354,14 +444,17 @@ export class DatabaseMigrationsService implements OnApplicationBootstrap {
     // Drop any existing FK constraint on schedule_id or class_id
     const fkColumns = ['schedule_id', 'class_id'];
     for (const col of fkColumns) {
-      const fkRows: { CONSTRAINT_NAME: string }[] = await runner.query(`
+      const fkRows: { CONSTRAINT_NAME: string }[] = await runner.query(
+        `
         SELECT CONSTRAINT_NAME
         FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
         WHERE TABLE_SCHEMA = DATABASE()
           AND TABLE_NAME = 'attendance_sessions'
           AND COLUMN_NAME = ?
           AND REFERENCED_TABLE_NAME IS NOT NULL
-      `, [col]);
+      `,
+        [col],
+      );
 
       for (const row of fkRows) {
         try {
@@ -381,13 +474,16 @@ export class DatabaseMigrationsService implements OnApplicationBootstrap {
     ];
     for (const c of constraints) {
       // Only skip if RESTRICT constraint is already confirmed via information_schema
-      const existing: Array<{ DELETE_RULE: string }> = await runner.query(`
+      const existing: Array<{ DELETE_RULE: string }> = await runner.query(
+        `
         SELECT DELETE_RULE
         FROM INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS
         WHERE CONSTRAINT_SCHEMA = DATABASE()
           AND TABLE_NAME = 'attendance_sessions'
           AND CONSTRAINT_NAME = ?
-      `, [c.name]);
+      `,
+        [c.name],
+      );
 
       if (existing.length > 0 && existing[0].DELETE_RULE === 'RESTRICT') {
         this.logger.log(`考勤场次删除保护约束已存在: ${c.name}`);
@@ -449,17 +545,13 @@ export class DatabaseMigrationsService implements OnApplicationBootstrap {
           FROM attendance_sessions
         `);
         await runner.query('DROP TABLE attendance_sessions');
-        await runner.query(
-          'ALTER TABLE attendance_sessions_new RENAME TO attendance_sessions',
-        );
+        await runner.query('ALTER TABLE attendance_sessions_new RENAME TO attendance_sessions');
         await runner.query(
           'CREATE UNIQUE INDEX IF NOT EXISTS uq_attendance_session_schedule_date ON attendance_sessions(schedule_id, lesson_date)',
         );
 
         // Rebuild attendance_records to add/protect FK on attendance_session_id
-        const recordsFk = await runner.query(
-          "PRAGMA foreign_key_list('attendance_records')",
-        );
+        const recordsFk = await runner.query("PRAGMA foreign_key_list('attendance_records')");
         const hasSessionFk = recordsFk.some(
           (r: { from: string }) => r.from === 'attendance_session_id',
         );
@@ -492,9 +584,7 @@ export class DatabaseMigrationsService implements OnApplicationBootstrap {
             FROM attendance_records
           `);
           await runner.query('DROP TABLE attendance_records');
-          await runner.query(
-            'ALTER TABLE attendance_records_new RENAME TO attendance_records',
-          );
+          await runner.query('ALTER TABLE attendance_records_new RENAME TO attendance_records');
           await runner.query(
             'CREATE UNIQUE INDEX IF NOT EXISTS uq_attendance_session_student ON attendance_records(attendance_session_id, student_id)',
           );
@@ -504,9 +594,7 @@ export class DatabaseMigrationsService implements OnApplicationBootstrap {
         // If violations exist, the transaction rolls back and old tables are preserved.
         const checkRows = await runner.query('PRAGMA foreign_key_check');
         if (checkRows.length > 0) {
-          throw new Error(
-            `外键一致性检查失败: ${checkRows.length} 行违反外键约束`,
-          );
+          throw new Error(`外键一致性检查失败: ${checkRows.length} 行违反外键约束`);
         }
 
         await runner.query('COMMIT');

apps/server/src/deposits/deposits.controller.ts

@@ -16,7 +16,7 @@ import { Student } from '../entities/student.entity';
 import { DepositsService } from './deposits.service';
 import { NotificationsService } from '../notifications/notifications.service';
 import { NotificationType } from '../entities/notification.entity';
-import { CreateDepositDto, RefundDepositDto, CreateDepositWithInstallmentsDto } from './dto/deposit.dto';
+import { CreateDepositDto, RefundDepositDto } from './dto/deposit.dto';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
 import { OperationLogsService } from '../operation-logs/operation-logs.service';
 import { extractRequestInfo } from '../common/request-utils';
@@ -61,7 +61,7 @@ export class DepositsController {
 
   @Post()
   @RequirePermission('deposit:create')
-  async create(@Body() dto: CreateDepositDto | CreateDepositWithInstallmentsDto, @Request() req: any) {
+  async create(@Body() dto: CreateDepositDto, @Request() req: any) {
     const { ipAddress, userAgent } = extractRequestInfo(req);
     const result = await this.service.create(dto, req.user?.id);
     await this.logService.log({

apps/server/src/deposits/deposits.lookups.spec.ts

@@ -5,7 +5,7 @@ describe('DepositsService permission-scoped lookups', () => {
     const studentRepo = {
       find: jest.fn().mockResolvedValue([{ id: 2, name: '张三', studentNo: 'S2' }]),
     };
-    const service = new DepositsService({} as never, {} as never, studentRepo as never);
+    const service = new DepositsService({} as never, {} as never, studentRepo as never, {} as never);
 
     await expect(service.getStudentLookups()).resolves.toEqual([
       { id: 2, name: '张三', studentNo: 'S2' },

apps/server/src/deposits/deposits.module.ts

@@ -3,13 +3,18 @@ import { TypeOrmModule } from '@nestjs/typeorm';
 import { Student } from '../entities/student.entity';
 import { Deposit } from '../entities/deposit.entity';
 import { DepositInstallment } from '../entities/deposit-installment.entity';
+import { PersonalExpense } from '../entities/personal-expense.entity';
 import { DepositsService } from './deposits.service';
 import { DepositsController } from './deposits.controller';
 import { OperationLogsModule } from '../operation-logs/operation-logs.module';
 import { NotificationsModule } from '../notifications/notifications.module';
 
 @Module({
-  imports: [TypeOrmModule.forFeature([Deposit, DepositInstallment, Student]), OperationLogsModule, NotificationsModule],
+  imports: [
+    TypeOrmModule.forFeature([Deposit, DepositInstallment, Student, PersonalExpense]),
+    OperationLogsModule,
+    NotificationsModule,
+  ],
   controllers: [DepositsController],
   providers: [DepositsService],
   exports: [DepositsService],

apps/server/src/deposits/deposits.refund.spec.ts

@@ -0,0 +1,38 @@
+import { DepositsService } from './deposits.service';
+import { Deposit } from '../entities/deposit.entity';
+
+describe('DepositsService — direct refund', () => {
+  it('stores the refund result on the main status and renamed audit fields', async () => {
+    const deposit = {
+      id: 1,
+      amount: 500,
+      status: 'paid',
+    } as Deposit;
+    const repo = {
+      findOne: jest.fn().mockResolvedValue(deposit),
+      save: jest.fn().mockImplementation(async (value: Deposit) => value),
+    };
+    const service = new DepositsService(repo as never, {} as never, {} as never, {} as never);
+
+    const result = await service.refund(
+      1,
+      {
+        refundDate: '2026-07-13',
+        deductionAmount: 100,
+        deductionReason: '物品损坏',
+      },
+      42,
+    );
+
+    expect(result).toMatchObject({
+      refundDate: '2026-07-13',
+      refundAmount: 400,
+      deductionAmount: 100,
+      deductionReason: '物品损坏',
+      status: 'partial_refund',
+      refundedBy: 42,
+    });
+    expect(result.refundedAt).toBeInstanceOf(Date);
+    expect(repo.save).toHaveBeenCalledWith(deposit);
+  });
+});

apps/server/src/deposits/deposits.service.ts

@@ -4,8 +4,9 @@ import { Repository } from 'typeorm';
 import { Deposit } from '../entities/deposit.entity';
 import { Student } from '../entities/student.entity';
 import { DepositInstallment } from '../entities/deposit-installment.entity';
+import { PersonalExpense } from '../entities/personal-expense.entity';
 
-import { CreateDepositDto, RefundDepositDto, CreateDepositWithInstallmentsDto } from './dto/deposit.dto';
+import { CreateDepositDto, RefundDepositDto } from './dto/deposit.dto';
 
 @Injectable()
 export class DepositsService {
@@ -16,6 +17,8 @@ export class DepositsService {
     private installmentRepo: Repository<DepositInstallment>,
     @InjectRepository(Student)
     private studentRepo: Repository<Student>,
+    @InjectRepository(PersonalExpense)
+    private personalExpenseRepo: Repository<PersonalExpense>,
   ) {}
 
   async getStudentLookups() {
@@ -34,13 +37,15 @@ export class DepositsService {
       .orderBy('d.createdAt', 'DESC');
     if (query?.studentId) qb.andWhere('d.studentId = :studentId', { studentId: query.studentId });
     if (query?.status) qb.andWhere('d.status = :status', { status: query.status });
-    return qb.getMany();
+    const deposits = await qb.getMany();
+    return this.attachPersonalExpenseAmount(deposits);
   }
 
   async findOne(id: number) {
     const deposit = await this.repo.findOne({ where: { id }, relations: ['student', 'installments'] });
     if (!deposit) throw new NotFoundException('押金记录不存在');
-    return deposit;
+    const [withPersonalExpense] = await this.attachPersonalExpenseAmount([deposit]);
+    return withPersonalExpense;
   }
 
   async create(dto: CreateDepositDto, userId?: number) {
@@ -55,17 +60,6 @@ export class DepositsService {
       recordedBy: userId,
     });
 
-    if (dto instanceof CreateDepositWithInstallmentsDto && dto.installments?.length) {
-      deposit.installments = dto.installments.map((i) => {
-        const inst = this.installmentRepo.create({
-          amount: i.amount,
-          dueDate: i.dueDate,
-          status: 'pending',
-        });
-        return inst;
-      });
-    }
-
     return this.repo.save(deposit);
   }
 
@@ -114,9 +108,8 @@ export class DepositsService {
     deposit.status =
       deduction > 0 ? (refundAmount > 0 ? 'partial_refund' : 'deducted') : 'refunded';
     if (dto.notes) deposit.notes = dto.notes;
-    deposit.refundStatus = 'refunded';
-    deposit.refundApprovedBy = userId ?? null as unknown as number;
-    deposit.refundApprovedAt = new Date();
+    deposit.refundedBy = userId ?? null;
+    deposit.refundedAt = new Date();
 
     return this.repo.save(deposit);
   }
@@ -137,4 +130,29 @@ export class DepositsService {
     qb.groupBy('d.status');
     return qb.getRawMany();
   }
+
+  private async attachPersonalExpenseAmount(deposits: Deposit[]) {
+    if (!deposits.length) return deposits;
+    const studentIds = Array.from(new Set(deposits.map((d) => d.studentId).filter(Boolean)));
+    if (!studentIds.length) return deposits;
+
+    const rows = await this.personalExpenseRepo
+      .createQueryBuilder('pe')
+      .select('pe.studentId', 'studentId')
+      .addSelect('SUM(pe.amount)', 'amount')
+      .where('pe.studentId IN (:...studentIds)', { studentIds })
+      .groupBy('pe.studentId')
+      .getRawMany<{ studentId: number | string; amount: string | number | null }>();
+
+    const amountMap = new Map<number, number>();
+    for (const row of rows) {
+      amountMap.set(Number(row.studentId), Number(Number(row.amount || 0).toFixed(2)));
+    }
+
+    return deposits.map((deposit) =>
+      Object.assign({}, deposit, {
+        personalExpenseAmount: amountMap.get(deposit.studentId) || 0,
+      }),
+    );
+  }
 }

apps/server/src/deposits/dto/deposit.dto.spec.ts

@@ -0,0 +1,19 @@
+import 'reflect-metadata';
+import { validate } from 'class-validator';
+import { CreateDepositDto } from './deposit.dto';
+
+describe('CreateDepositDto boundaries', () => {
+  it('removes inline installments because they are managed after deposit creation', async () => {
+    const dto = Object.assign(new CreateDepositDto(), {
+      studentId: 1,
+      amount: 500,
+      paidDate: '2026-07-13',
+      installments: [{ amount: 250, dueDate: '2026-08-01' }],
+    });
+
+    await validate(dto, { whitelist: true });
+
+    expect(dto).toMatchObject({ studentId: 1, amount: 500, paidDate: '2026-07-13' });
+    expect(dto).not.toHaveProperty('installments');
+  });
+});

apps/server/src/deposits/dto/deposit.dto.ts

@@ -1,5 +1,4 @@
-import { IsInt, IsNumber, IsString, IsOptional, ValidateNested } from 'class-validator';
-import { Type } from 'class-transformer';
+import { IsInt, IsNumber, IsString, IsOptional } from 'class-validator';
 
 export class CreateDepositDto {
   @IsInt()
@@ -16,16 +15,6 @@ export class CreateDepositDto {
   notes?: string;
 }
 
-export class CreateInstallmentDto {
-  @IsNumber()
-  amount: number;
-
-  @IsString()
-  dueDate: string;
-}
-
-
-
 export class RefundDepositDto {
   @IsString()
   refundDate: string;
@@ -42,9 +31,3 @@ export class RefundDepositDto {
   @IsString()
   notes?: string;
 }
-export class CreateDepositWithInstallmentsDto extends CreateDepositDto {
-  @IsOptional()
-  @ValidateNested({ each: true })
-  @Type(() => CreateInstallmentDto)
-  installments?: CreateInstallmentDto[];
-}

apps/server/src/entities/attendance-record.entity.ts

@@ -67,6 +67,18 @@ export class AttendanceRecord {
   @Column({ name: 'source', length: 20, default: 'manual' })
   source: string;
 
+  @Column({ name: 'punch_time', type: 'datetime', nullable: true })
+  punchTime: Date | null;
+
+  @Column({ name: 'punch_source', type: 'varchar', length: 40, nullable: true })
+  punchSource: string | null;
+
+  @Column({ name: 'punch_device_name', type: 'varchar', length: 100, nullable: true })
+  punchDeviceName: string | null;
+
+  @Column({ name: 'punch_device_id', type: 'varchar', length: 100, nullable: true })
+  punchDeviceId: string | null;
+
   @CreateDateColumn({ name: 'created_at' })
   createdAt: Date;
 

apps/server/src/entities/class-student.entity.ts

@@ -30,14 +30,11 @@ export class ClassStudent {
   @JoinColumn({ name: 'student_id' })
   student: Student;
 
-  @Column({ name: 'enrollment_id', type: 'integer', nullable: true })
-  enrollmentId: number;
-
   @Column({ name: 'join_date', type: 'date', nullable: true })
-  joinDate: string;
+  joinDate: string | null;
 
   @Column({ name: 'leave_date', type: 'date', nullable: true })
-  leaveDate: string;
+  leaveDate: string | null;
 
   @Column({ name: 'status', length: 10, default: 'active' })
   status: string;

apps/server/src/entities/classroom-rental.entity.ts

@@ -11,6 +11,12 @@ import {
 import { Classroom } from './classroom.entity';
 import { Organization } from './organization.entity';
 
+export enum ClassroomRentalStatus {
+  ACTIVE = 'active',
+  ENDED = 'ended',
+  CANCELLED = 'cancelled',
+}
+
 @Entity('classroom_rentals')
 @Index(['classroomId', 'startDate', 'endDate'])
 export class ClassroomRental {
@@ -57,8 +63,8 @@ export class ClassroomRental {
   @Column({ name: 'total_amount', type: 'decimal', precision: 10, scale: 2, nullable: true })
   totalAmount: number;
 
-  @Column({ type: 'varchar', length: 20, default: 'active' })
-  status: string; // active / ended / cancelled
+  @Column({ type: 'varchar', length: 20, default: ClassroomRentalStatus.ACTIVE })
+  status: ClassroomRentalStatus | 'active' | 'ended' | 'cancelled';
 
   @Column({ type: 'text', nullable: true })
   notes: string;

apps/server/src/entities/classroom.entity.ts

@@ -1,4 +1,10 @@
-import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, ManyToOne, JoinColumn } from 'typeorm';
+import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn } from 'typeorm';
+
+export enum ClassroomStatus {
+  AVAILABLE = 'available',
+  MAINTENANCE = 'maintenance',
+  ARCHIVED = 'archived',
+}
 
 @Entity('classrooms')
 export class Classroom {
@@ -20,14 +26,12 @@ export class Classroom {
   @Column({ name: 'room_type', type: 'varchar', length: 20, default: '大' })
   roomType: string; // 大 / 次大 / 小
 
-
-  @Column({ type: 'varchar', length: 20, default: 'reserved' })
-  status: string;
+  @Column({ type: 'varchar', length: 20, default: ClassroomStatus.AVAILABLE })
+  status: ClassroomStatus | 'available' | 'maintenance' | 'archived';
 
   @Column({ type: 'text', nullable: true })
   notes: string;
 
   @CreateDateColumn({ name: 'created_at' })
   createdAt: Date;
-
 }

apps/server/src/entities/deposit.entity.ts

@@ -46,20 +46,11 @@ export class Deposit {
   @Column({ name: 'recorded_by', nullable: true })
   recordedBy: number;
 
-  @Column({ name: 'refund_status', length: 30, nullable: true })
-  refundStatus: string; // pending | head_teacher_approved | finance_approved | refunded
+  @Column({ name: 'refunded_by', type: 'integer', nullable: true })
+  refundedBy: number | null;
 
-  @Column({ name: 'refund_requested_at', type: 'datetime', nullable: true })
-  refundRequestedAt: Date;
-
-  @Column({ name: 'refund_approved_by', type: 'integer', nullable: true })
-  refundApprovedBy: number;
-
-  @Column({ name: 'refund_approved_at', type: 'datetime', nullable: true })
-  refundApprovedAt: Date;
-
-  @Column({ name: 'refund_rejected_reason', length: 500, nullable: true })
-  refundRejectedReason: string;
+  @Column({ name: 'refunded_at', type: 'datetime', nullable: true })
+  refundedAt: Date | null;
 
   @OneToMany(() => DepositInstallment, (i) => i.deposit, { cascade: true, eager: true })
   installments: DepositInstallment[];

apps/server/src/entities/ding-attendance-raw.entity.ts

@@ -44,6 +44,15 @@ export class DingAttendanceRaw {
   @Column({ name: 'location_result', length: 20, nullable: true })
   locationResult: string;
 
+  @Column({ name: 'punch_source', type: 'varchar', length: 40, nullable: true })
+  punchSource: string | null;
+
+  @Column({ name: 'punch_device_name', type: 'varchar', length: 100, nullable: true })
+  punchDeviceName: string | null;
+
+  @Column({ name: 'punch_device_id', type: 'varchar', length: 100, nullable: true })
+  punchDeviceId: string | null;
+
   @Column({ name: 'match_status', length: 20, default: 'unmatched' })
   matchStatus: string;
 

apps/server/src/entities/index.ts

@@ -11,9 +11,10 @@ export { User } from './user.entity';
 export { OperationLog } from './operation-log.entity';
 export { Deposit } from './deposit.entity';
 export { DepositInstallment } from './deposit-installment.entity';
-export { Classroom } from './classroom.entity';
+export { UtilityRecharge } from './utility-recharge.entity';
+export { Classroom, ClassroomStatus } from './classroom.entity';
 export { Organization } from './organization.entity';
-export { ClassroomRental } from './classroom-rental.entity';
+export { ClassroomRental, ClassroomRentalStatus } from './classroom-rental.entity';
 export { Permission } from './permission.entity';
 export { Role } from './role.entity';
 export { Class, ClassType, ClassStatus } from './class.entity';

apps/server/src/entities/room.entity.ts

@@ -1,4 +1,12 @@
-import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, OneToMany, ManyToOne, JoinColumn } from 'typeorm';
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  OneToMany,
+  ManyToOne,
+  JoinColumn,
+} from 'typeorm';
 import { Occupancy } from './occupancy.entity';
 import { RoomExpense } from './room-expense.entity';
 
@@ -25,9 +33,6 @@ export class Room {
   @Column({ name: 'room_type', length: 20, nullable: true })
   roomType: string;
 
-  @Column({ length: 10, nullable: true })
-  gender: string;
-
   @Column({ name: 'rental_category', length: 10, default: 'short' })
   rentalCategory: string;
 
@@ -42,5 +47,4 @@ export class Room {
 
   @OneToMany(() => RoomExpense, (e) => e.room)
   roomExpenses: RoomExpense[];
-
 }

apps/server/src/entities/student-profile.entity.ts

@@ -33,9 +33,6 @@ export class StudentProfile {
   @Column({ length: 20, nullable: true })
   grade: string;
 
-  @Column({ name: 'campus_location', length: 100, nullable: true })
-  campusLocation: string;
-
   @Column({ name: 'profile_date', type: 'date', nullable: true })
   profileDate: string;
 

apps/server/src/entities/utility-recharge.entity.ts

@@ -0,0 +1,37 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  ManyToOne,
+  JoinColumn,
+} from 'typeorm';
+import { Student } from './student.entity';
+
+@Entity('utility_recharges')
+export class UtilityRecharge {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @Column({ name: 'student_id' })
+  studentId: number;
+
+  @Column({ type: 'decimal', precision: 10, scale: 2 })
+  amount: number;
+
+  @Column({ name: 'recharge_date', type: 'date' })
+  rechargeDate: string;
+
+  @Column({ type: 'text', nullable: true })
+  notes: string;
+
+  @Column({ name: 'recorded_by', nullable: true })
+  recordedBy: number;
+
+  @CreateDateColumn({ name: 'created_at' })
+  createdAt: Date;
+
+  @ManyToOne(() => Student, { eager: true })
+  @JoinColumn({ name: 'student_id' })
+  student: Student;
+}

apps/server/src/expense-types/expense-types.service.ts

@@ -5,8 +5,7 @@ import { ExpenseType } from '../entities/expense-type.entity';
 import { CreateExpenseTypeDto, UpdateExpenseTypeDto } from './dto/expense-type.dto';
 
 const DEFAULT_TYPES = [
-  { code: 'water', name: '水费', category: 'room', sortOrder: 1 },
-  { code: 'electricity', name: '电费', category: 'room', sortOrder: 2 },
+  { code: 'utility', name: '水电费', category: 'room', sortOrder: 1 },
   { code: 'cleaning', name: '保洁费', category: 'room', sortOrder: 3 },
   { code: 'damage', name: '损坏赔偿', category: 'both', sortOrder: 4 },
   { code: 'penalty', name: '罚款', category: 'personal', sortOrder: 5 },

apps/server/src/expenses/expenses.service.ts

@@ -208,9 +208,11 @@ export class ExpensesService {
           continue;
         }
 
+        const utilityFee = Number(((row.electricityFee || 0) + (row.waterFee || 0)).toFixed(2));
+
         // 关键校验：电费 + 水费 都为 0 时，多半是 Excel 公式未正确计算或字段缺失，
         // 必须给出明确错误，避免出现"提示成功但无数据"的迷之现象。
-        if ((row.electricityFee || 0) <= 0 && (row.waterFee || 0) <= 0) {
+        if (utilityFee <= 0) {
           errors.push(
             `第${rowNum}行: ${row.roomNumber} 电费和水费均为 0，可能 Excel 中是未生效的公式（请打开文件让公式重算后再保存导入），已跳过`,
           );
@@ -218,53 +220,28 @@ export class ExpensesService {
           continue;
         }
 
-        // 幂等：先删除该房间在同一周期已有的水/电费用记录，避免重复导入产生脏数据
+        // 幂等：先删除该房间在同一周期已有的水电费用记录，避免重复导入产生脏数据。
+        // 同时兼容清理旧版本拆开的 water/electricity 记录。
         await this.roomExpRepo
           .createQueryBuilder()
           .delete()
           .where('roomId = :roomId', { roomId: room.id })
           .andWhere('periodStart = :ps AND periodEnd = :pe', { ps: periodStart, pe: periodEnd })
-          .andWhere('expenseType IN (:...types)', { types: ['water', 'electricity'] })
+          .andWhere('expenseType IN (:...types)', { types: ['utility', 'water', 'electricity'] })
           .execute();
 
-        let savedAny = false;
-        // 导入电费
-        if (row.electricityFee > 0) {
-          await this.roomExpRepo.save(
-            this.roomExpRepo.create({
-              roomId: room.id,
-              expenseType: 'electricity',
-              amount: row.electricityFee,
-              periodStart,
-              periodEnd,
-              description: `电量${row.electricityAmount}kWh`,
-              recordedBy: userId,
-            }),
-          );
-          savedAny = true;
-        }
-
-        // 导入水费
-        if (row.waterFee > 0) {
-          await this.roomExpRepo.save(
-            this.roomExpRepo.create({
-              roomId: room.id,
-              expenseType: 'water',
-              amount: row.waterFee,
-              periodStart,
-              periodEnd,
-              description: `用水${row.waterAmount}吨`,
-              recordedBy: userId,
-            }),
-          );
-          savedAny = true;
-        }
-
-        if (savedAny) imported++;
-        else {
-          skipped++;
-          errors.push(`第${rowNum}行: ${row.roomNumber} 无有效金额`);
-        }
+        await this.roomExpRepo.save(
+          this.roomExpRepo.create({
+            roomId: room.id,
+            expenseType: 'utility',
+            amount: utilityFee,
+            periodStart,
+            periodEnd,
+            description: `电量${row.electricityAmount || 0}kWh，电费¥${Number(row.electricityFee || 0).toFixed(2)}；用水${row.waterAmount || 0}吨，水费¥${Number(row.waterFee || 0).toFixed(2)}`,
+            recordedBy: userId,
+          }),
+        );
+        imported++;
       } catch (e: any) {
         errors.push(`第${rowNum}行: ${row.roomNumber} 导入失败 - ${e.message}`);
         skipped++;

apps/server/src/integration/config/dto/config.dto.spec.ts

@@ -0,0 +1,48 @@
+import { ValidationPipe } from '@nestjs/common';
+import {
+  DingTalkThirdConfigDto,
+  IntegrationType,
+  SaveIntegrationConfigDto,
+  WeComThirdConfigDto,
+} from './config.dto';
+
+const pipe = new ValidationPipe({ transform: true, whitelist: true });
+
+const transform = (value: unknown) =>
+  pipe.transform(value, { type: 'body', metatype: SaveIntegrationConfigDto });
+
+describe('integration config request DTO', () => {
+  it('validates and transforms DingTalk configuration', async () => {
+    const result = await transform({
+      type: 'DINGTALK',
+      config: {
+        agentId: 'app-key',
+        corpId: 'corp-id',
+        appSecret: '',
+        appId: 'app-id',
+        ignored: 'value',
+      },
+    });
+
+    expect(result.type).toBe(IntegrationType.DINGTALK);
+    expect(result.config).toBeInstanceOf(DingTalkThirdConfigDto);
+    expect(result.config).toMatchObject({ agentId: 'app-key', corpId: 'corp-id', appSecret: '' });
+    expect(result.config).not.toHaveProperty('ignored');
+  });
+
+  it('uses the WeCom nested DTO and removes DingTalk-only fields', async () => {
+    const result = await transform({
+      type: 'WECOM',
+      config: { agentId: 'agent', corpId: 'corp', appId: 'not-supported' },
+    });
+
+    expect(result.config).toBeInstanceOf(WeComThirdConfigDto);
+    expect(result.config).not.toHaveProperty('appId');
+  });
+
+  it('rejects invalid platform types and incomplete nested config', async () => {
+    await expect(transform({ type: 'UNKNOWN', config: {} })).rejects.toThrow();
+    await expect(transform({ type: 'DINGTALK', config: { corpId: 'corp' } })).rejects.toThrow();
+    await expect(transform({ type: 'DINGTALK' })).rejects.toThrow();
+  });
+});

apps/server/src/integration/config/dto/config.dto.ts

@@ -1,29 +1,71 @@
-/** 钉钉配置 */
-export interface DingTalkThirdConfig {
-  agentId: string; // AppKey
-  appSecret: string; // AppSecret
-  corpId: string; // CorpId
-  startEnable: boolean; // 是否启用同步
-  appId?: string; // 内部应用ID，用于消息推送（可选）
+import { Type } from 'class-transformer';
+import {
+  IsDefined,
+  IsEnum,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  ValidateNested,
+} from 'class-validator';
+
+export enum IntegrationType {
+  WECOM = 'WECOM',
+  DINGTALK = 'DINGTALK',
 }
 
-/** 企微配置 */
-export interface WeComThirdConfig {
+export class DingTalkThirdConfigDto {
+  @IsString()
+  @IsNotEmpty()
   agentId: string;
-  appSecret: string;
+
+  @IsOptional()
+  @IsString()
+  appSecret?: string;
+
+  @IsString()
+  @IsNotEmpty()
   corpId: string;
-  startEnable: boolean;
+
+  @IsOptional()
+  @IsString()
+  appId?: string;
 }
 
+export class WeComThirdConfigDto {
+  @IsString()
+  @IsNotEmpty()
+  agentId: string;
+
+  @IsOptional()
+  @IsString()
+  appSecret?: string;
+
+  @IsString()
+  @IsNotEmpty()
+  corpId: string;
+}
+
+export class IntegrationConfigRequestDto {
+  @IsEnum(IntegrationType)
+  type: IntegrationType;
+
+  @IsDefined()
+  @ValidateNested()
+  @Type((options) =>
+    options?.object?.type === IntegrationType.DINGTALK
+      ? DingTalkThirdConfigDto
+      : WeComThirdConfigDto,
+  )
+  config: DingTalkThirdConfigDto | WeComThirdConfigDto;
+}
+
+export class SaveIntegrationConfigDto extends IntegrationConfigRequestDto {}
+
+export class TestIntegrationConfigDto extends IntegrationConfigRequestDto {}
+
 /** 对外返回的配置（脱敏后，不含 appSecret） */
 export interface ThirdConfigBaseDTO<T = unknown> {
   type: string;
   verify?: boolean;
   config: T;
 }
-
-/** 保存配置的请求体 */
-export interface SaveConfigRequest {
-  type: 'WECOM' | 'DINGTALK';
-  config: DingTalkThirdConfig | WeComThirdConfig;
-}

apps/server/src/integration/config/integration-config.controller.ts

@@ -2,7 +2,7 @@ import { Controller, Get, Post, Body, Param, UseGuards } from '@nestjs/common';
 import { JwtAuthGuard } from '../../auth/guards/jwt-auth.guard';
 import { RequirePermission } from '../../auth/decorators/permission.decorator';
 import { IntegrationConfigService } from './integration-config.service';
-import type { SaveConfigRequest } from './dto/config.dto';
+import { SaveIntegrationConfigDto, TestIntegrationConfigDto } from './dto/config.dto';
 
 @Controller('integration/config')
 @UseGuards(JwtAuthGuard)
@@ -31,7 +31,7 @@ export class IntegrationConfigController {
   /** 保存配置 */
   @Post()
   @RequirePermission('integration:trigger')
-  async saveConfig(@Body() body: SaveConfigRequest) {
+  async saveConfig(@Body() body: SaveIntegrationConfigDto) {
     await this.service.saveConfig(body);
     return { success: true, message: '配置已保存' };
   }
@@ -39,7 +39,7 @@ export class IntegrationConfigController {
   /** 测试连接 */
   @Post('test')
   @RequirePermission('integration:read')
-  async testConnection(@Body() body: SaveConfigRequest) {
+  async testConnection(@Body() body: TestIntegrationConfigDto) {
     const success = await this.service.testConnection(body.type, body.config);
     return { success, message: success ? '连接成功' : '连接失败，请检查配置信息' };
   }

apps/server/src/integration/config/integration-config.service.spec.ts

@@ -0,0 +1,49 @@
+import { IntegrationConfigService } from './integration-config.service';
+
+describe('IntegrationConfigService.testConnection', () => {
+  const originalFetch = global.fetch;
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('uses the saved AppSecret when testing an existing configuration with a blank secret', async () => {
+    const configRepo = {
+      findOne: jest.fn().mockResolvedValue({ id: 1, type: 'THIRD' }),
+    };
+    const detailRepo = {
+      findOne: jest.fn().mockResolvedValue({
+        configId: 1,
+        type: 'DINGTALK_SYNC',
+        content: JSON.stringify({
+          config: {
+            corpId: 'ding-corp',
+            agentId: 'saved-key',
+            appSecret: 'saved-secret',
+          },
+        }),
+      }),
+    };
+    global.fetch = jest.fn().mockResolvedValue({
+      json: jest.fn().mockResolvedValue({ accessToken: 'token' }),
+    }) as never;
+
+    const service = new IntegrationConfigService(configRepo as never, detailRepo as never);
+
+    await expect(
+      service.testConnection('DINGTALK', {
+        corpId: 'ding-corp',
+        agentId: 'saved-key',
+        appSecret: '',
+      }),
+    ).resolves.toBe(true);
+
+    expect(global.fetch).toHaveBeenCalledWith(
+      'https://api.dingtalk.com/v1.0/oauth2/accessToken',
+      expect.objectContaining({
+        body: JSON.stringify({ appKey: 'saved-key', appSecret: 'saved-secret' }),
+      }),
+    );
+  });
+});