Merge pull request '增加金数据学生同步与匹配规则' (#35) from feature/jinshuju-student-sync into main

2026-07-22 04:30:03 +00:00
parent 1dc13274de e1bc3a6b2c
commit cd1996f281
20 changed files with 1405 additions and 14 deletions
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -4,10 +4,8 @@ env:
  NPM_CONFIG_REGISTRY: https://registry.npmmirror.com
  NPM_CONFIG_AUDIT: "false"
  NPM_CONFIG_FUND: "false"
-  NPM_CONFIG_PREFER_OFFLINE: "true"
  NPM_CONFIG_REPLACE_REGISTRY_HOST: always
  CI: "true"
-  TURBO_UI: stream

 on:
  pull_request:
--- a/apps/admin/src/components/JinshujuMatchModal.tsx
+++ b/apps/admin/src/components/JinshujuMatchModal.tsx
@@ -0,0 +1,565 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { Button, Form, Input, Modal, Popconfirm, Select, Spin, Steps, Tag, Typography } from 'antd';
+import {
+  CloudUploadOutlined,
+  DeleteOutlined,
+  EditOutlined,
+  LinkOutlined,
+  PlusOutlined,
+  SaveOutlined,
+  SearchOutlined,
+} from '@ant-design/icons';
+import api from '../api';
+import { message } from '../ui/app-message';
+
+const { Text } = Typography;
+
+// ── Types ──
+
+interface JinshujuEntryRow {
+  serialNumber: number;
+  name: string;
+  phone: string | null;
+  suggestedStudent: {
+    id: number;
+    name: string;
+    phone: string | null;
+    studentNo: string | null;
+  } | null;
+}
+
+interface StudentOption {
+  id: number;
+  name: string;
+  phone: string | null;
+  studentNo: string | null;
+}
+
+interface PreviewResponse {
+  success: boolean;
+  entries: JinshujuEntryRow[];
+  students: StudentOption[];
+}
+
+interface MatchRule {
+  id: number;
+  name: string;
+  formToken: string;
+  mappings: Record<string, string>;
+  createdAt: string;
+}
+
+interface JinshujuFormField {
+  key: string;
+  label: string;
+  type: string;
+}
+
+type MatchDecision =
+  | { action: 'match'; matchStudentId: number }
+  | { action: 'create'; createName: string; createPhone: string }
+  | { action: 'skip' };
+
+// ── Constants ──
+
+const ROW_HEIGHT = 72;
+const LEFT_WIDTH = 260;
+const GAP = 80;
+
+const STUDENT_FIELDS = [
+  { key: 'name', label: '姓名' },
+  { key: 'phone', label: '手机号' },
+  { key: 'idNumber', label: '身份证号' },
+  { key: 'gender', label: '性别' },
+  { key: 'ethnicity', label: '民族' },
+  { key: 'emergencyContact', label: '紧急联系人' },
+  { key: 'emergencyPhone', label: '紧急联系电话' },
+  { key: 'studentNo', label: '学号' },
+];
+
+// ── MatchSelector sub-component ──
+
+interface MatchSelectorProps {
+  entry: JinshujuEntryRow;
+  decision: MatchDecision | undefined;
+  studentOptions: StudentOption[];
+  onChange: (d: MatchDecision) => void;
+}
+
+const MatchSelector: React.FC<MatchSelectorProps> = ({ entry, decision, studentOptions, onChange }) => {
+  const action = decision?.action ?? 'skip';
+
+  if (action === 'match') {
+    const matchD = decision as { action: 'match'; matchStudentId: number };
+    const matchedStudent = studentOptions.find((s) => s.id === matchD.matchStudentId);
+    return (
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8, width: '100%' }}>
+        <Tag color="blue" icon={<LinkOutlined />}>已匹配</Tag>
+        <Text style={{ flex: 1 }}>
+          {matchedStudent?.name ?? '未知'}
+          {matchedStudent?.studentNo && (
+            <Text type="secondary" style={{ fontSize: 12, marginLeft: 4 }}>
+              ({matchedStudent.studentNo})
+            </Text>
+          )}
+        </Text>
+        <Button size="small" type="link" danger onClick={() => onChange({ action: 'skip' })}>取消</Button>
+      </div>
+    );
+  }
+
+  if (action === 'create') {
+    const createD = decision as { action: 'create'; createName: string; createPhone: string };
+    return (
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8, width: '100%' }}>
+        <Tag color="green" icon={<PlusOutlined />}>将新建</Tag>
+        <Input size="small" value={createD.createName} placeholder="姓名" style={{ width: 100 }}
+          onChange={(e) => onChange({ action: 'create', createName: e.target.value, createPhone: createD.createPhone })} />
+        <Input size="small" value={createD.createPhone} placeholder="手机号" style={{ width: 120 }}
+          onChange={(e) => onChange({ action: 'create', createName: createD.createName, createPhone: e.target.value })} />
+        <Button size="small" type="link" danger onClick={() => onChange({ action: 'skip' })}>取消</Button>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 8, width: '100%' }}>
+      <Select showSearch size="small" placeholder="搜索学生…" style={{ flex: 1 }} value={undefined}
+        filterOption={(input, option) => ((option?.label as string) || '').toLowerCase().includes(input.toLowerCase())}
+        options={studentOptions.map((s) => ({
+          value: s.id,
+          label: `${s.name}${s.phone ? ` (${s.phone})` : ''}${s.studentNo ? ` [${s.studentNo}]` : ''}`,
+        }))}
+        onChange={(studentId: number) => onChange({ action: 'match', matchStudentId: studentId })} />
+      <Button size="small" type="dashed" icon={<PlusOutlined />}
+        onClick={() => onChange({ action: 'create', createName: entry.name || '', createPhone: entry.phone || '' })}>
+        新建
+      </Button>
+      <Button size="small" type="link" onClick={() => onChange({ action: 'skip' })}>跳过</Button>
+    </div>
+  );
+};
+
+// ── Rule Editor sub-component ──
+
+interface RuleEditorProps {
+  rule: MatchRule | null;
+  formToken: string;
+  fields: JinshujuFormField[];
+  onSave: () => void;
+  onDelete: (id: number) => void;
+  onCancel: () => void;
+}
+
+const RuleEditor: React.FC<RuleEditorProps> = ({ rule, formToken, fields, onSave, onDelete, onCancel }) => {
+  const [name, setName] = useState(rule?.name ?? '');
+  const [mappings, setMappings] = useState<Record<string, string>>(rule?.mappings ?? { name: 'field_1', phone: 'field_2' });
+  const [saving, setSaving] = useState(false);
+
+  const handleSave = async () => {
+    if (!name.trim()) { message.warning('请输入规则名称'); return; }
+    setSaving(true);
+    try {
+      if (rule) {
+        await api.put(`/sync/jinshuju/rules/${rule.id}`, { name, mappings });
+      } else {
+        await api.post('/sync/jinshuju/rules', { name, formToken, mappings });
+      }
+      message.success('规则已保存');
+      onSave();
+    } catch (e: unknown) {
+      const err = e as { message?: string };
+      if (err?.message) message.error(err.message);
+    } finally { setSaving(false); }
+  };
+
+  return (
+    <div style={{ padding: '12px 0' }}>
+      <Input placeholder="规则名称" value={name} onChange={(e) => setName(e.target.value)}
+        style={{ marginBottom: 12 }} />
+      <Text type="secondary" style={{ display: 'block', marginBottom: 8 }}>选择金数据字段映射到学生资料</Text>
+      {STUDENT_FIELDS.map((sf) => (
+        <div key={sf.key} style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 6 }}>
+          <Text style={{ width: 100, textAlign: 'right', fontSize: 13 }}>{sf.label}</Text>
+          <Text type="secondary" style={{ fontSize: 12 }}>←</Text>
+          <Select
+            allowClear
+            showSearch
+            optionFilterProp="label"
+            placeholder="选择金数据字段"
+            value={mappings[sf.key]}
+            style={{ flex: 1 }}
+            options={fields.map((field) => ({
+              value: field.key,
+              label: `${field.label}（${field.key}）`,
+            }))}
+            onChange={(value) => setMappings((prev) => {
+              const next = { ...prev };
+              if (value) next[sf.key] = value;
+              else delete next[sf.key];
+              return next;
+            })}
+          />
+        </div>
+      ))}
+      <div style={{ marginTop: 12, display: 'flex', gap: 8 }}>
+        <Button type="primary" icon={<SaveOutlined />} loading={saving} onClick={handleSave}>保存</Button>
+        {rule && (
+          <Popconfirm title="确定删除此规则？" onConfirm={() => onDelete(rule.id)}>
+            <Button danger icon={<DeleteOutlined />}>删除</Button>
+          </Popconfirm>
+        )}
+        <Button onClick={onCancel}>取消</Button>
+      </div>
+    </div>
+  );
+};
+
+// ── Main MatchModal ──
+
+interface MatchModalProps {
+  open: boolean;
+  onClose: () => void;
+  onApplied: () => void;
+}
+
+const JinshujuMatchModal: React.FC<MatchModalProps> = ({ open, onClose, onApplied }) => {
+  const [step, setStep] = useState<'connection' | 'rule' | 'match' | 'applying'>('connection');
+  const [loading, setLoading] = useState(false);
+  const [selectedRuleId, setSelectedRuleId] = useState<number | undefined>();
+  const [rules, setRules] = useState<MatchRule[]>([]);
+  const [editingRule, setEditingRule] = useState<MatchRule | null>(null);
+  const [showRuleEditor, setShowRuleEditor] = useState(false);
+  const [credForm] = Form.useForm();
+  const formToken = Form.useWatch('formToken', credForm) ?? '';
+
+  const [entries, setEntries] = useState<JinshujuEntryRow[]>([]);
+  const [studentOptions, setStudentOptions] = useState<StudentOption[]>([]);
+  const [decisions, setDecisions] = useState<Map<number, MatchDecision>>(new Map());
+  const leftRef = useRef<HTMLDivElement>(null);
+  const rightRef = useRef<HTMLDivElement>(null);
+  const [formFields, setFormFields] = useState<JinshujuFormField[]>([]);
+  const [formName, setFormName] = useState('');
+  const [scrollTop, setScrollTop] = useState(0);
+
+  // Load rules on open
+  useEffect(() => {
+    if (open) loadRules();
+  }, [open]);
+
+  const loadRules = async () => {
+    try {
+      const res = await api.get<{ success: boolean; data: MatchRule[] }>('/sync/jinshuju/rules');
+      if (res.success) setRules(res.data);
+    } catch { /* ignore */ }
+  };
+
+  const handleConnectionNext = async () => {
+    try {
+      const values = await credForm.validateFields();
+      setLoading(true);
+      const response = await api.post<{
+        success: boolean;
+        data: { name: string; fields: JinshujuFormField[] };
+      }>('/sync/jinshuju/fields', values);
+      setFormFields(response.data.fields);
+      setFormName(response.data.name);
+      setStep('rule');
+    } catch (error: unknown) {
+      const apiError = error as { message?: string; errorFields?: unknown[] };
+      if (!apiError.errorFields && apiError.message) message.error(apiError.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handlePreview = async () => {
+    try {
+      const values = await credForm.validateFields();
+      setLoading(true);
+      const body: Record<string, unknown> = { ...values };
+      if (selectedRuleId) body.ruleId = selectedRuleId;
+      const res = await api.post<PreviewResponse>('/sync/jinshuju/preview', body);
+      if (!res.success) throw new Error('预览失败');
+      setEntries(res.entries);
+      setStudentOptions(res.students);
+      const initial = new Map<number, MatchDecision>();
+      for (const entry of res.entries) {
+        if (entry.suggestedStudent) {
+          initial.set(entry.serialNumber, { action: 'match', matchStudentId: entry.suggestedStudent.id });
+        }
+      }
+      setDecisions(initial);
+      setStep('match');
+    } catch (e: unknown) {
+      const err = e as { message?: string };
+      if (err?.message) message.error(err.message);
+    } finally { setLoading(false); }
+  };
+
+  const handleApply = async () => {
+    setLoading(true);
+    setStep('applying');
+    try {
+      const decisionList = [...decisions.entries()].map(([serialNumber, d]) => ({ serialNumber, ...d }));
+      const body: Record<string, unknown> = {
+        ...credForm.getFieldsValue(),
+        decisions: decisionList,
+      };
+      if (selectedRuleId) body.ruleId = selectedRuleId;
+      const res = await api.post<{ success: boolean; log: { recordsCount: number; message?: string } }>(
+        '/sync/jinshuju/apply', body,
+      );
+      if (res.success) {
+        message.success(res.log.message || `处理 ${res.log.recordsCount} 条记录`);
+        onApplied();
+        reset();
+      }
+    } catch (e: unknown) {
+      const err = e as { message?: string };
+      if (err?.message) message.error(err.message);
+      setStep('match');
+    } finally { setLoading(false); }
+  };
+
+  const reset = () => {
+    setStep('connection');
+    setEntries([]);
+    setStudentOptions([]);
+    setDecisions(new Map());
+    setSelectedRuleId(undefined);
+    setFormFields([]);
+    setFormName('');
+    setShowRuleEditor(false);
+    credForm.resetFields();
+  };
+
+  const handleClose = () => { reset(); onClose(); };
+  const handleScroll = (source: 'left' | 'right') => {
+    const el = source === 'left' ? leftRef.current : rightRef.current;
+    if (el) setScrollTop(el.scrollTop);
+  };
+
+  useEffect(() => {
+    if (leftRef.current) leftRef.current.scrollTop = scrollTop;
+    if (rightRef.current) rightRef.current.scrollTop = scrollTop;
+  }, [scrollTop]);
+
+  const getDecision = (serial: number): MatchDecision | undefined => decisions.get(serial);
+  const setDecision = (serial: number, d: MatchDecision) => setDecisions((prev) => new Map(prev).set(serial, d));
+  const total = entries.length;
+  const matched = [...decisions.values()].filter((d) => d.action !== 'skip').length;
+
+  const visibleRules = rules.filter((rule) => rule.formToken === formToken);
+  const selectedRule = visibleRules.find((rule) => rule.id === selectedRuleId) ?? null;
+
+  // ── Render ──
+
+  const renderConnectionStep = () => (
+    <Form form={credForm} layout="vertical" style={{ marginTop: 24 }}>
+      <Form.Item
+        name="apiKey"
+        label="API Key"
+        extra="金数据个人中心 → API 中获取"
+        rules={[{ required: true, message: '请输入 API Key' }]}
+      >
+        <Input placeholder="请输入 API Key" autoComplete="username" />
+      </Form.Item>
+      <Form.Item
+        name="apiSecret"
+        label="API Secret"
+        rules={[{ required: true, message: '请输入 API Secret' }]}
+      >
+        <Input.Password placeholder="请输入 API Secret" autoComplete="current-password" />
+      </Form.Item>
+      <Form.Item
+        name="formToken"
+        label="表单 Token"
+        extra="例如表单地址 /f/AbC123 中的 AbC123"
+        rules={[{ required: true, message: '请输入表单 Token' }]}
+      >
+        <Input placeholder="请输入表单 Token" />
+      </Form.Item>
+    </Form>
+  );
+
+  const renderRuleStep = () => (
+    <div style={{ marginTop: 24 }}>
+      <div style={{ marginBottom: 12 }}>
+        <Text strong>选择匹配规则</Text>
+        <Text type="secondary" style={{ display: 'block', marginTop: 4 }}>
+          已连接表单「{formName}」，共 {formFields.length} 个字段。选择已有规则或新建字段映射。
+        </Text>
+      </div>
+
+      <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+        <Select
+          style={{ flex: 1 }}
+          placeholder="默认规则：field_1 → 姓名，field_2 → 手机号"
+          allowClear
+          value={selectedRuleId}
+          onChange={(value) => setSelectedRuleId(value)}
+          options={visibleRules.map((rule) => ({ value: rule.id, label: rule.name }))}
+        />
+        {selectedRule ? (
+          <Button
+            icon={<EditOutlined />}
+            onClick={() => {
+              setEditingRule(selectedRule);
+              setShowRuleEditor(true);
+            }}
+          >
+            编辑
+          </Button>
+        ) : null}
+        <Button
+          icon={<PlusOutlined />}
+          onClick={() => {
+            setEditingRule(null);
+            setShowRuleEditor(true);
+          }}
+        >
+          新建规则
+        </Button>
+      </div>
+
+      {visibleRules.length === 0 && !showRuleEditor ? (
+        <Text type="secondary" style={{ display: 'block', marginTop: 12 }}>
+          当前表单还没有保存的规则。
+        </Text>
+      ) : null}
+
+      {showRuleEditor ? (
+        <RuleEditor
+          rule={editingRule}
+          formToken={formToken}
+          fields={formFields}
+          onSave={() => {
+            setShowRuleEditor(false);
+            loadRules();
+          }}
+          onDelete={async (id) => {
+            await api.delete(`/sync/jinshuju/rules/${id}`);
+            message.success('规则已删除');
+            if (selectedRuleId === id) setSelectedRuleId(undefined);
+            setShowRuleEditor(false);
+            loadRules();
+          }}
+          onCancel={() => setShowRuleEditor(false)}
+        />
+      ) : null}
+    </div>
+  );
+
+  const renderMatchStep = () => {
+    const svgHeight = entries.length * ROW_HEIGHT;
+    const lines: React.ReactNode[] = [];
+    entries.forEach((entry, i) => {
+      const y = i * ROW_HEIGHT + ROW_HEIGHT / 2;
+      const d = getDecision(entry.serialNumber);
+      const isMatched = d?.action === 'match';
+      const color = isMatched ? '#1677ff' : '#d9d9d9';
+      lines.push(<line key={entry.serialNumber} x1={LEFT_WIDTH} y1={y} x2={LEFT_WIDTH + GAP} y2={y}
+        stroke={color} strokeWidth={isMatched ? 2 : 1}
+        strokeDasharray={isMatched ? undefined : '4 4'} opacity={isMatched ? 0.7 : 0.3} />);
+    });
+
+    return (
+      <div style={{ position: 'relative' }}>
+        <div style={{ marginBottom: 12, display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
+          <Text type="secondary">共 {total} 条，已匹配 {matched} 条</Text>
+          <Button size="small" onClick={() => setDecisions(new Map())}>清除全部匹配</Button>
+        </div>
+        <div style={{ display: 'flex', position: 'relative' }}>
+          <svg style={{ position: 'absolute', top: 0, left: 0, width: LEFT_WIDTH + GAP, height: svgHeight, pointerEvents: 'none', zIndex: 1 }}>
+            {lines}
+          </svg>
+          <div ref={leftRef} onScroll={() => handleScroll('left')}
+            style={{ width: LEFT_WIDTH, maxHeight: 480, overflowY: 'auto', flexShrink: 0 }}>
+            {entries.map((entry, i) => {
+              const d = getDecision(entry.serialNumber);
+              const isMatched = d?.action === 'match';
+              return (
+                <div key={entry.serialNumber} style={{
+                  height: ROW_HEIGHT, padding: '8px 12px', borderBottom: '1px solid #f0f0f0',
+                  display: 'flex', flexDirection: 'column', justifyContent: 'center',
+                  background: isMatched ? '#f6ffed' : i % 2 === 0 ? '#fafafa' : '#fff',
+                  borderLeft: isMatched ? '3px solid #1677ff' : '3px solid transparent',
+                }}>
+                  <Text strong style={{ fontSize: 13 }}>{entry.name || <Text type="secondary">无姓名</Text>}</Text>
+                  {entry.phone && <Text type="secondary" style={{ fontSize: 12 }}>{entry.phone}</Text>}
+                  <Text type="secondary" style={{ fontSize: 11 }}>#{entry.serialNumber}</Text>
+                </div>
+              );
+            })}
+          </div>
+          <div style={{ width: GAP, flexShrink: 0 }} />
+          <div ref={rightRef} onScroll={() => handleScroll('right')}
+            style={{ flex: 1, maxHeight: 480, overflowY: 'auto' }}>
+            {entries.map((entry) => (
+              <div key={entry.serialNumber} style={{
+                height: ROW_HEIGHT, padding: '8px 12px', borderBottom: '1px solid #f0f0f0',
+                display: 'flex', alignItems: 'center', gap: 8,
+              }}>
+                <MatchSelector entry={entry} decision={getDecision(entry.serialNumber)}
+                  studentOptions={studentOptions}
+                  onChange={(newD) => setDecision(entry.serialNumber, newD)} />
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+    );
+  };
+
+  const currentStep = step === 'connection' ? 0 : step === 'rule' ? 1 : 2;
+
+  return (
+    <Modal
+      title="同步金数据"
+      open={open}
+      onCancel={handleClose}
+      width={step === 'match' || step === 'applying' ? 900 : 640}
+      maskClosable={false}
+      footer={
+        step === 'connection'
+          ? [
+              <Button key="cancel" onClick={handleClose}>取消</Button>,
+              <Button key="next" type="primary" onClick={handleConnectionNext}>下一步</Button>,
+            ]
+          : step === 'rule'
+            ? [
+                <Button key="back" onClick={() => setStep('connection')}>上一步</Button>,
+                <Button key="cancel" onClick={handleClose}>取消</Button>,
+                <Button key="next" type="primary" icon={<SearchOutlined />} loading={loading} onClick={handlePreview}>
+                  获取数据并下一步
+                </Button>,
+              ]
+            : step === 'match'
+              ? [
+                  <Button key="back" onClick={() => setStep('rule')}>上一步</Button>,
+                  <Button key="cancel" onClick={handleClose}>取消</Button>,
+                  <Button key="apply" type="primary" icon={<CloudUploadOutlined />} loading={loading} onClick={handleApply}>
+                    应用匹配
+                  </Button>,
+                ]
+              : null
+      }
+    >
+      <Steps
+        current={currentStep}
+        items={[
+          { title: '连接表单' },
+          { title: '匹配规则' },
+          { title: '确认匹配' },
+        ]}
+      />
+      {step === 'connection' ? renderConnectionStep() : null}
+      {step === 'rule' ? renderRuleStep() : null}
+      {step === 'match' ? renderMatchStep() : null}
+      {step === 'applying' ? <Spin tip="正在同步..." style={{ display: 'block', margin: '48px auto' }} /> : null}
+    </Modal>
+  );
+};
+
+export default JinshujuMatchModal;
--- a/apps/admin/src/pages/Students/index.tsx
+++ b/apps/admin/src/pages/Students/index.tsx
@@ -21,6 +21,7 @@ import {
 } from 'antd';
 import type { UploadProps } from 'antd';
 import {
+  CloudUploadOutlined,
  DownloadOutlined,
  ExportOutlined,
  EyeOutlined,
@@ -34,6 +35,7 @@ import api from '../../api';
 import PermissionButton from '../../components/PermissionButton';
 import StudentProfileContent from '../../components/StudentProfileContent';
 import EditableCell from '../../components/EditableCell';
+import JinshujuMatchModal from '../../components/JinshujuMatchModal';
 import { maskIdNumber, maskPhone } from '../../utils/sensitive';
 import { message } from '../../ui/app-message';

@@ -109,6 +111,8 @@ const StudentsPage: React.FC = () => {
    setDrawerOpen(true);
  };

+  const [jinshujuOpen, setJinshujuOpen] = useState(false);
+
  const handleViewSensitive = (studentId: number, field: string, value: string) => {
    modal.confirm({
      title: '查看敏感信息',
@@ -775,6 +779,13 @@ const StudentsPage: React.FC = () => {
          >
            <Button icon={<SwapOutlined />}>更新已有学生资料</Button>
          </Upload>
+          <PermissionButton
+            permission="student:edit"
+            icon={<CloudUploadOutlined />}
+            onClick={() => setJinshujuOpen(true)}
+          >
+            同步金数据
+          </PermissionButton>
          <PermissionButton
            permission="student:view"
            icon={<DownloadOutlined />}
@@ -955,6 +966,11 @@ const StudentsPage: React.FC = () => {
        </Form>
      </Modal>

+      <JinshujuMatchModal
+        open={jinshujuOpen}
+        onClose={() => setJinshujuOpen(false)}
+        onApplied={() => { setJinshujuOpen(false); fetchData(); }}
+      />
      <Drawer
        title={null}
        open={drawerOpen}
--- a/apps/admin/vite.config.ts
+++ b/apps/admin/vite.config.ts
@@ -4,6 +4,33 @@ import react from '@vitejs/plugin-react';
 // https://vite.dev/config/
 export default defineConfig({
  plugins: [react()],
+  build: {
+    rolldownOptions: {
+      output: {
+        codeSplitting: {
+          groups: [
+            {
+              name: 'react',
+              test: /node_modules[\\/](react|react-dom|react-router|react-router-dom)[\\/]/,
+              priority: 30,
+            },
+            {
+              name: 'echarts',
+              test: /node_modules[\\/](echarts|zrender)[\\/]/,
+              priority: 20,
+              maxSize: 300_000,
+            },
+            {
+              name: 'antd',
+              test: /node_modules[\\/](@ant-design|antd|rc-[^\\/]+)[\\/]/,
+              priority: 10,
+              maxSize: 300_000,
+            },
+          ],
+        },
+      },
+    },
+  },
  server: {
    port: 3002,
    proxy: {
--- a/apps/server/src/app.module.ts
+++ b/apps/server/src/app.module.ts
@@ -47,6 +47,7 @@ import {
  ResultArchive,
  ArchiveAttachment,
  StudentDingMapping,
+  JinshujuMatchRule,
  AiConfig,
  StudentWallet,
  WalletTransaction,
@@ -56,10 +57,12 @@ import { AuthModule } from './auth/auth.module';
 import { InitialSchema1784520727860 } from './migrations/1784520727860-InitialSchema';
 import { AddExamManagement1784600000000 } from './migrations/1784600000000-AddExamManagement';
 import { AddRoomInspections1784680000000 } from './migrations/1784680000000-AddRoomInspections';
+import { AddJinshujuMatchRules1784700000000 } from './migrations/1784700000000-AddJinshujuMatchRules';
 const allMigrations = [
  InitialSchema1784520727860,
  AddExamManagement1784600000000,
  AddRoomInspections1784680000000,
+  AddJinshujuMatchRules1784700000000,
 ];
 import { AuthorizationModule } from './authorization';
 import { RbacModule } from './rbac/rbac.module';
@@ -150,7 +153,8 @@ import { IntegrationConfigModule } from './integration/config/config.module';
          StudentEnrollment,
          ExamScore,
          Exam,
-          LearningRecord,
+          StudentDingMapping,
+          JinshujuMatchRule,
          ExpenseType,
          ArchiveAttachment,
          ResultArchive,
--- a/apps/server/src/entities/index.ts
+++ b/apps/server/src/entities/index.ts
@@ -39,6 +39,7 @@ export { LearningRecord } from './learning-record.entity';
 export { ResultArchive } from './result-archive.entity';
 export { ArchiveAttachment } from './archive-attachment.entity';
 export { StudentDingMapping } from './student-ding-mapping.entity';
+export { JinshujuMatchRule } from './jinshuju-match-rule.entity';
 export { AiConfig } from '../ai-config/ai-config.entity';

 export * from './student-wallet.entity';
--- a/apps/server/src/entities/jinshuju-match-rule.entity.ts
+++ b/apps/server/src/entities/jinshuju-match-rule.entity.ts
@@ -0,0 +1,53 @@
+import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn } from 'typeorm';
+
+/**
+ * Field mappings from Jinshuju field keys (field_1, field_2, ...) to Student columns.
+ * Only mapped fields are extracted; unmapped fields are ignored.
+ */
+export interface JinshujuFieldMapping {
+  /** Jinshuju field key → Student column name */
+  name?: string;         // e.g. "field_1"
+  phone?: string;        // e.g. "field_2"
+  idNumber?: string;     // e.g. "field_3"
+  gender?: string;
+  ethnicity?: string;
+  emergencyContact?: string;
+  emergencyPhone?: string;
+  studentNo?: string;
+}
+
+export const DEFAULT_MAPPING: JinshujuFieldMapping = {
+  name: 'field_1',
+  phone: 'field_2',
+};
+
+const mappingTransformer = {
+  to(value: JinshujuFieldMapping): string {
+    return JSON.stringify(value);
+  },
+  from(value: string | null): JinshujuFieldMapping {
+    if (!value) return {};
+    return JSON.parse(value);
+  },
+};
+
+@Entity('jinshuju_match_rules')
+export class JinshujuMatchRule {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @Column({ length: 100 })
+  name: string;
+
+  @Column({ name: 'form_token', length: 64 })
+  formToken: string;
+
+  @Column({ type: 'text', transformer: mappingTransformer })
+  mappings: JinshujuFieldMapping;
+
+  @CreateDateColumn({ name: 'created_at' })
+  createdAt: Date;
+
+  @UpdateDateColumn({ name: 'updated_at' })
+  updatedAt: Date;
+}
--- a/apps/server/src/entities/sync-log.entity.ts
+++ b/apps/server/src/entities/sync-log.entity.ts
@@ -1,6 +1,6 @@
 import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn } from 'typeorm';

-export type SyncPlatform = 'dingtalk_students' | 'dingtalk_attendance' | 'wecom';
+export type SyncPlatform = 'dingtalk_students' | 'dingtalk_attendance' | 'wecom' | 'jinshuju';
 export type SyncType = 'full' | 'incremental';
 export type SyncStatus = 'running' | 'success' | 'partial' | 'failed';

--- a/apps/server/src/integration/integration.module.ts
+++ b/apps/server/src/integration/integration.module.ts
@@ -3,6 +3,7 @@ import { TypeOrmModule } from '@nestjs/typeorm';
 import { User, Student, StudentDingMapping, Class } from '../entities';
 import { DingTalkService } from './dingtalk.service';
 import { WeComService } from './wecom.service';
+import { JinshujuService } from './jinshuju.service';
 import { IntegrationConfigModule } from './config/config.module';

@Module({
@@ -10,7 +11,7 @@ import { IntegrationConfigModule } from './config/config.module';
    TypeOrmModule.forFeature([User, Student, StudentDingMapping, Class]),
    IntegrationConfigModule,
  ],
-  providers: [DingTalkService, WeComService],
-  exports: [DingTalkService, WeComService],
+  providers: [DingTalkService, WeComService, JinshujuService],
+  exports: [DingTalkService, WeComService, JinshujuService],
 })
 export class IntegrationModule {}
--- a/apps/server/src/integration/jinshuju-student-sync.ts
+++ b/apps/server/src/integration/jinshuju-student-sync.ts
@@ -0,0 +1,118 @@
+import { EntityManager, In } from 'typeorm';
+import { Organization, Student } from '../entities';
+import type { JinshujuEntry } from './jinshuju.service';
+
+export interface JinshujuStudentSyncResult {
+  matched: number; // already-existing students matched by phone or name
+  created: number;
+  conflicts: Array<{ serialNumber: number; name: string; reason: string }>;
+  skippedNoName: number;
+}
+
+/**
+ * Match Jinshuju form entries to existing students, create new ones when no match found.
+ *
+ * Matching strategy (first-match):
+ * 1. By phone (field mapped to phone) — most reliable
+ * 2. By name (field mapped to name)
+ *
+ * Field mapping: we assume field_1 = name, field_2 = phone by convention.
+ * ponytail: hardcoded mapping; make configurable when needed.
+ */
+export async function syncJinshujuStudents(
+  manager: EntityManager,
+  entries: JinshujuEntry[],
+): Promise<JinshujuStudentSyncResult> {
+  // Extract name/phone from entries
+  interface ParsedEntry {
+    serialNumber: number;
+    name: string;
+    phone?: string;
+  }
+
+  const parsed: ParsedEntry[] = [];
+  let skippedNoName = 0;
+
+  for (const entry of entries) {
+    const name = typeof entry.field_1 === 'string' ? entry.field_1.trim() : '';
+    if (!name) { skippedNoName++; continue; }
+    const phone = typeof entry.field_2 === 'string' ? entry.field_2.trim() : undefined;
+    parsed.push({ serialNumber: entry.serial_number, name, phone: phone || undefined });
+  }
+
+  if (parsed.length === 0) {
+    return { matched: 0, created: 0, conflicts: [], skippedNoName };
+  }
+
+  // Match by phone first
+  const phones = [...new Set(parsed.filter((p) => p.phone).map((p) => p.phone!))];
+  const phoneStudents = phones.length
+    ? await manager.find(Student, { where: { phone: In(phones) } })
+    : [];
+  const studentByPhone = new Map(phoneStudents.map((s) => [s.phone, s]));
+
+  const matchedIds = new Set<number>();
+  const matchedCount = { value: 0 };
+  const conflicts: JinshujuStudentSyncResult['conflicts'] = [];
+
+  // Match remaining by name
+  const names = [...new Set(parsed.filter((p) => !p.phone || !studentByPhone.has(p.phone)).map((p) => p.name))];
+  const nameStudents = names.length
+    ? await manager.find(Student, { where: { name: In(names) } })
+    : [];
+  const studentByName = new Map<string, Student[]>();
+  for (const s of nameStudents) {
+    const list = studentByName.get(s.name) || [];
+    list.push(s);
+    studentByName.set(s.name, list);
+  }
+
+  const toCreate: Array<{ name: string; phone?: string }> = [];
+
+  for (const p of parsed) {
+    // Try phone match first
+    if (p.phone && studentByPhone.has(p.phone)) {
+      const student = studentByPhone.get(p.phone)!;
+      if (!matchedIds.has(student.id)) {
+        matchedIds.add(student.id);
+        matchedCount.value++;
+      }
+      continue;
+    }
+
+    // Try name match
+    const candidates = studentByName.get(p.name);
+    if (candidates && candidates.length > 0) {
+      // ponytail: take first match; no ambiguity resolution
+      const student = candidates[0];
+      if (!matchedIds.has(student.id)) {
+        matchedIds.add(student.id);
+        matchedCount.value++;
+      }
+      continue;
+    }
+
+    // No match — create
+    toCreate.push({ name: p.name, phone: p.phone });
+  }
+
+  // Create new students
+  let created = 0;
+  if (toCreate.length > 0) {
+    const host = await manager.findOne(Organization, { where: { isHost: true, status: 'active' } });
+    if (!host) throw new Error('尚未配置本机构');
+
+    const newStudents = toCreate.map((s) => {
+      const student = {
+        name: s.name,
+        phone: s.phone || undefined,
+        organizationId: host.id,
+      };
+      return manager.create(Student, student);
+    });
+    const saved = await manager.save(Student, newStudents);
+    created = saved.length;
+  }
+
+  return { matched: matchedCount.value, created, conflicts, skippedNoName };
+}
--- a/apps/server/src/integration/jinshuju.service.ts
+++ b/apps/server/src/integration/jinshuju.service.ts
@@ -0,0 +1,101 @@
+import { Injectable, Logger, ServiceUnavailableException } from '@nestjs/common';
+
+export interface JinshujuEntry {
+  serial_number: number;
+  /** field values — keyed by api_code like field_1, field_2 */
+  [fieldKey: string]: unknown;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface JinshujuEntriesResponse {
+  total: number;
+  count: number;
+  data: JinshujuEntry[];
+  next: number | null;
+}
+
+export interface JinshujuFormField {
+  key: string;
+  label: string;
+  type: string;
+}
+
+interface JinshujuFormResponse {
+  name: string;
+  fields: Array<Record<string, { label?: unknown; type?: unknown }>>;
+}
+
+@Injectable()
+export class JinshujuService {
+  private readonly logger = new Logger(JinshujuService.name);
+  private static readonly BASE = 'https://jinshuju.net/api/v1';
+
+  private getAuthorization(apiKey: string, apiSecret: string): string {
+    return `Basic ${Buffer.from(`${apiKey}:${apiSecret}`).toString('base64')}`;
+  }
+
+  async fetchFormFields(
+    apiKey: string,
+    apiSecret: string,
+    formToken: string,
+  ): Promise<{ name: string; fields: JinshujuFormField[] }> {
+    const response = await fetch(
+      `${JinshujuService.BASE}/forms/${encodeURIComponent(formToken)}`,
+      {
+        headers: {
+          Authorization: this.getAuthorization(apiKey, apiSecret),
+          Accept: 'application/json',
+        },
+      },
+    );
+    if (!response.ok) {
+      const text = await response.text().catch(() => '');
+      throw new ServiceUnavailableException(
+        `获取金数据表单结构失败: HTTP ${response.status} ${text.slice(0, 200)}`,
+      );
+    }
+
+    const body = (await response.json()) as JinshujuFormResponse;
+    const fields = (body.fields ?? []).flatMap((group) =>
+      Object.entries(group).map(([key, field]) => ({
+        key,
+        label: typeof field.label === 'string' && field.label.trim() ? field.label.trim() : key,
+        type: typeof field.type === 'string' ? field.type : 'unknown',
+      })),
+    );
+    return { name: body.name, fields };
+  }
+
+  /** Fetch all entries for a form, following pagination. */
+  async fetchAllEntries(apiKey: string, apiSecret: string, formToken: string): Promise<JinshujuEntry[]> {
+    const auth = this.getAuthorization(apiKey, apiSecret);
+    const entries: JinshujuEntry[] = [];
+    let next: number | null | undefined = undefined;
+
+    do {
+      const url = new URL(`${JinshujuService.BASE}/forms/${encodeURIComponent(formToken)}/entries`);
+      if (next) url.searchParams.set('next', String(next));
+
+      this.logger.log(`Fetching Jinshuju entries: ${url.toString().replace(/api_key=[^&]+/, 'api_key=***')}`);
+      const res = await fetch(url.toString(), {
+        headers: {
+          Authorization: auth,
+          Accept: 'application/json',
+        },
+      });
+
+      if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new ServiceUnavailableException(`金数据 API 请求失败: HTTP ${res.status} ${text.slice(0, 200)}`);
+      }
+
+      const body = (await res.json()) as JinshujuEntriesResponse;
+      entries.push(...body.data);
+      next = body.next ?? undefined;
+    } while (next);
+
+    this.logger.log(`Fetched ${entries.length} entries from Jinshuju form ${formToken}`);
+    return entries;
+  }
+}
--- a/apps/server/src/migration-runner.ts
+++ b/apps/server/src/migration-runner.ts
@@ -2,6 +2,7 @@ import { DataSource } from 'typeorm';
 import { InitialSchema1784520727860 } from './migrations/1784520727860-InitialSchema';
 import { AddExamManagement1784600000000 } from './migrations/1784600000000-AddExamManagement';
 import { AddRoomInspections1784680000000 } from './migrations/1784680000000-AddRoomInspections';
+import { AddJinshujuMatchRules1784700000000 } from './migrations/1784700000000-AddJinshujuMatchRules';
 import { config } from 'dotenv';

 config();
@@ -24,6 +25,7 @@ export async function runMigrationsOnStartup(): Promise<void> {
      InitialSchema1784520727860,
      AddExamManagement1784600000000,
      AddRoomInspections1784680000000,
+      AddJinshujuMatchRules1784700000000,
    ],
  });

--- a/apps/server/src/migrations/1784700000000-AddJinshujuMatchRules.ts
+++ b/apps/server/src/migrations/1784700000000-AddJinshujuMatchRules.ts
@@ -0,0 +1,33 @@
+import { MigrationInterface, QueryRunner, Table } from 'typeorm';
+
+export class AddJinshujuMatchRules1784700000000 implements MigrationInterface {
+  async up(queryRunner: QueryRunner): Promise<void> {
+    if (await queryRunner.hasTable('jinshuju_match_rules')) return;
+
+    await queryRunner.createTable(
+      new Table({
+        name: 'jinshuju_match_rules',
+        columns: [
+          {
+            name: 'id',
+            type: 'integer',
+            isPrimary: true,
+            isGenerated: true,
+            generationStrategy: 'increment',
+          },
+          { name: 'name', type: 'varchar', length: '100' },
+          { name: 'form_token', type: 'varchar', length: '64' },
+          { name: 'mappings', type: 'text' },
+          { name: 'created_at', type: 'datetime', default: 'CURRENT_TIMESTAMP' },
+          { name: 'updated_at', type: 'datetime', default: 'CURRENT_TIMESTAMP' },
+        ],
+      }),
+    );
+  }
+
+  async down(queryRunner: QueryRunner): Promise<void> {
+    if (await queryRunner.hasTable('jinshuju_match_rules')) {
+      await queryRunner.dropTable('jinshuju_match_rules');
+    }
+  }
+}
--- a/apps/server/src/rbac/rbac.service.ts
+++ b/apps/server/src/rbac/rbac.service.ts
@@ -756,8 +756,8 @@ export class RbacService {
  async getTeachers(query?: { search?: string; page?: number; pageSize?: number }) {
    const page = query?.page || 1;
    const pageSize = query?.pageSize || 20;
-    const teacherRoleCodes = ['teacher', 'super_admin'];
-    const teacherRoleNames = ['任课老师', '老师', '超级管理员', '超管'];
+    const teacherRoleCodes = ['teacher'];
+    const teacherRoleNames = ['任课老师', '老师'];

    const qb = this.userRepo
      .createQueryBuilder('u')
--- a/apps/server/src/rbac/rbac.teachers.spec.ts
+++ b/apps/server/src/rbac/rbac.teachers.spec.ts
@@ -0,0 +1,40 @@
+import { RbacService } from './rbac.service';
+
+describe('RbacService teacher listing', () => {
+  it('queries only teacher roles, excluding administrators', async () => {
+    const queryBuilder = {
+      leftJoinAndSelect: jest.fn(),
+      where: jest.fn(),
+      andWhere: jest.fn(),
+      getCount: jest.fn().mockResolvedValue(0),
+      orderBy: jest.fn(),
+      skip: jest.fn(),
+      take: jest.fn(),
+      getMany: jest.fn().mockResolvedValue([]),
+    };
+    for (const method of ['leftJoinAndSelect', 'where', 'andWhere', 'orderBy', 'skip', 'take'] as const) {
+      queryBuilder[method].mockReturnValue(queryBuilder);
+    }
+    const userRepo = { createQueryBuilder: jest.fn().mockReturnValue(queryBuilder) };
+    const service = new RbacService(
+      {} as never,
+      {} as never,
+      userRepo as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+    );
+
+    await service.getTeachers();
+
+    expect(queryBuilder.where).toHaveBeenCalledWith(
+      '(role.code IN (:...roleCodes) OR role.name IN (:...roleNames))',
+      {
+        roleCodes: ['teacher'],
+        roleNames: ['任课老师', '老师'],
+      },
+    );
+  });
+});
--- a/apps/server/src/sync/sync.controller.spec.ts
+++ b/apps/server/src/sync/sync.controller.spec.ts
@@ -43,4 +43,23 @@ describe('SyncController — schedule sync options', () => {

    expect(syncService.triggerSync).toHaveBeenCalledWith('dingtalk_students', 12);
  });
+
+  it('returns Jinshuju form fields for the selector', async () => {
+    const syncService = {
+      getJinshujuFormFields: jest.fn().mockResolvedValue({
+        name: '报名表',
+        fields: [{ key: 'field_1', label: '姓名', type: 'single_line_text' }],
+      }),
+    };
+    const controller = new SyncController(syncService as never);
+
+    const result = await controller.getJinshujuFields({
+      apiKey: 'key',
+      apiSecret: 'secret',
+      formToken: 'form-a',
+    });
+
+    expect(syncService.getJinshujuFormFields).toHaveBeenCalledWith('key', 'secret', 'form-a');
+    expect(result.data.fields[0]).toMatchObject({ key: 'field_1', label: '姓名' });
+  });
 });
--- a/apps/server/src/sync/sync.controller.ts
+++ b/apps/server/src/sync/sync.controller.ts
@@ -1,4 +1,4 @@
-import { BadRequestException, Controller, Get, Logger, Post, Query, UseGuards } from '@nestjs/common';
+import { BadRequestException, Body, Controller, Delete, Get, Logger, Param, ParseIntPipe, Post, Put, Query, UseGuards } from '@nestjs/common';
 import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
 import { RequirePermission } from '../auth/decorators/permission.decorator';
 import { SyncService } from './sync.service';
@@ -68,6 +68,125 @@ export class SyncController {
    };
  }

+  /** 从金数据表单同步学生数据 */
+  @Post('jinshuju')
+  @RequirePermission('sync:trigger')
+  async syncJinshuju(
+    @Body() body: { apiKey: string; apiSecret: string; formToken: string },
+  ) {
+    if (!body.apiKey || !body.apiSecret || !body.formToken) {
+      throw new BadRequestException('apiKey, apiSecret, formToken 均为必填');
+    }
+    const log = await this.syncService.syncJinshuju(body.apiKey, body.apiSecret, body.formToken);
+    return { success: true, log };
+  }
+
+  /** 获取金数据表单字段，供匹配规则选择器使用 */
+  @Post('jinshuju/fields')
+  @RequirePermission('sync:trigger')
+  async getJinshujuFields(
+    @Body() body: { apiKey: string; apiSecret: string; formToken: string },
+  ) {
+    if (!body.apiKey || !body.apiSecret || !body.formToken) {
+      throw new BadRequestException('apiKey, apiSecret, formToken 均为必填');
+    }
+    const data = await this.syncService.getJinshujuFormFields(
+      body.apiKey,
+      body.apiSecret,
+      body.formToken,
+    );
+    return { success: true, data };
+  }
+
+  /** 预览金数据表单条目及建议匹配（不写入） */
+  @Post('jinshuju/preview')
+  @RequirePermission('sync:trigger')
+  async previewJinshuju(
+    @Body() body: { apiKey: string; apiSecret: string; formToken: string; ruleId?: number },
+  ) {
+    if (!body.apiKey || !body.apiSecret || !body.formToken) {
+      throw new BadRequestException('apiKey, apiSecret, formToken 均为必填');
+    }
+    const data = await this.syncService.previewJinshuju(body.apiKey, body.apiSecret, body.formToken, body.ruleId);
+    return { success: true, ...data };
+  }
+
+  /** 应用用户的手动匹配决定 */
+  @Post('jinshuju/apply')
+  @RequirePermission('sync:trigger')
+  async applyJinshuju(
+    @Body() body: {
+      apiKey: string;
+      apiSecret: string;
+      formToken: string;
+      ruleId?: number;
+      decisions: Array<{
+        serialNumber: number;
+        action: 'match' | 'create' | 'skip';
+        matchStudentId?: number;
+        createName?: string;
+        createPhone?: string;
+      }>;
+    },
+  ) {
+    if (!body.apiKey || !body.apiSecret || !body.formToken) {
+      throw new BadRequestException('apiKey, apiSecret, formToken 均为必填');
+    }
+    if (!Array.isArray(body.decisions) || body.decisions.length === 0) {
+      throw new BadRequestException('decisions 不能为空');
+    }
+    const log = await this.syncService.applyJinshuju(
+      body.apiKey,
+      body.apiSecret,
+      body.formToken,
+      body.decisions,
+      body.ruleId,
+    );
+    return { success: true, log };
+  }
+
+  // ── 金数据匹配规则 CRUD ──
+
+  @Get('jinshuju/rules')
+  @RequirePermission('sync:read')
+  async listMatchRules() {
+    const rules = await this.syncService.listMatchRules();
+    return { success: true, data: rules };
+  }
+
+  @Post('jinshuju/rules')
+  @RequirePermission('sync:trigger')
+  async createMatchRule(
+    @Body() body: { name: string; formToken: string; mappings: Record<string, string> },
+  ) {
+    if (!body.name || !body.formToken) {
+      throw new BadRequestException('name, formToken 均为必填');
+    }
+    const rule = await this.syncService.createMatchRule({
+      name: body.name,
+      formToken: body.formToken,
+      mappings: body.mappings ?? {},
+    });
+    return { success: true, data: rule };
+  }
+
+  @Put('jinshuju/rules/:id')
+  @RequirePermission('sync:trigger')
+  async updateMatchRule(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() body: { name?: string; mappings?: Record<string, string> },
+  ) {
+    const rule = await this.syncService.updateMatchRule(id, body);
+    return { success: true, data: rule };
+  }
+
+  @Delete('jinshuju/rules/:id')
+  @RequirePermission('sync:trigger')
+  async deleteMatchRule(@Param('id', ParseIntPipe) id: number) {
+    await this.syncService.deleteMatchRule(id);
+    return { success: true };
+  }
+
  @Get('logs')
  @RequirePermission('sync:read')
  async getLogs(
--- a/apps/server/src/sync/sync.module.ts
+++ b/apps/server/src/sync/sync.module.ts
@@ -12,6 +12,7 @@ import {
  Student,
  Role,
  Class,
+  JinshujuMatchRule,
 } from '../entities';
 import { SyncService } from './sync.service';
 import { SyncController } from './sync.controller';
@@ -29,6 +30,7 @@ import { ScheduleSyncService } from './schedule-sync.service';
      Student,
      Role,
      Class,
+      JinshujuMatchRule,
    ]),
    IntegrationModule,
    AttendanceModule,
--- a/apps/server/src/sync/sync.service.spec.ts
+++ b/apps/server/src/sync/sync.service.spec.ts
@@ -1,5 +1,5 @@
 import { ConflictException, ServiceUnavailableException } from '@nestjs/common';
-import { SyncLog } from '../entities';
+import { Student, SyncLog } from '../entities';
 import { SyncService } from './sync.service';

 function queryBuilder(affected = 1) {
@@ -45,16 +45,44 @@ function createService(options?: {
      errors: [],
    }),
  };
+  const matchRuleRepo = {
+    find: jest.fn(),
+    findOne: jest.fn(),
+    save: jest.fn(),
+    create: jest.fn(),
+    update: jest.fn(),
+    delete: jest.fn(),
+  };
+  const jinshujuService = { fetchAllEntries: jest.fn().mockResolvedValue([]) };
+  const manager = {
+    query: jest.fn().mockResolvedValue([{ id: 1 }]),
+    update: jest.fn(),
+    save: jest.fn(),
+    create: jest.fn().mockImplementation((_entity, value) => value),
+  };
+  const dataSource = { transaction: jest.fn((callback) => callback(manager)) };
  const service = new SyncService(
    syncLogRepo as never,
    syncStateRepo as never,
    { find: jest.fn().mockResolvedValue([{ dingUserId: 'u1' }]) } as never,
+    matchRuleRepo as never,
    dingTalkService as never,
    { syncAll: jest.fn().mockResolvedValue({ userCount: 0 }) } as never,
+    jinshujuService as never,
    attendanceImportService as never,
    {} as never,
+    dataSource as never,
  );
-  return { service, syncStateRepo, syncLogRepo, dingTalkService, attendanceImportService };
+  return {
+    service,
+    syncStateRepo,
+    syncLogRepo,
+    dingTalkService,
+    attendanceImportService,
+    matchRuleRepo,
+    jinshujuService,
+    manager,
+  };
 }

 describe('SyncService — safe DingTalk orchestration', () => {
@@ -94,4 +122,38 @@ describe('SyncService — safe DingTalk orchestration', () => {
      expect.objectContaining({ status: 'failed', errorMessage: expect.stringContaining('upstream failed') }),
    );
  });
+
+  it('applies the selected field mappings and decisions', async () => {
+    const { service, matchRuleRepo, jinshujuService, manager } = createService();
+    matchRuleRepo.findOne.mockResolvedValue({
+      id: 7,
+      formToken: 'form-a',
+      mappings: { name: 'field_3', phone: 'field_4', idNumber: 'field_5' },
+    });
+    jinshujuService.fetchAllEntries.mockResolvedValue([
+      {
+        serial_number: 1,
+        field_3: '张三',
+        field_4: '13800000000',
+        field_5: '123456',
+        created_at: '',
+        updated_at: '',
+      },
+    ]);
+
+    const log = await service.applyJinshuju(
+      'key',
+      'secret',
+      'form-a',
+      [{ serialNumber: 1, action: 'match', matchStudentId: 99 }],
+      7,
+    );
+
+    expect(manager.update).toHaveBeenCalledWith(Student, 99, {
+      name: '张三',
+      phone: '13800000000',
+      idNumber: '123456',
+    });
+    expect(log.recordsCount).toBe(1);
+  });
 });
--- a/apps/server/src/sync/sync.service.ts
+++ b/apps/server/src/sync/sync.service.ts
@@ -1,12 +1,15 @@
-import { ConflictException, Injectable, Logger, ServiceUnavailableException } from '@nestjs/common';
+import { ConflictException, Injectable, Logger, NotFoundException, ServiceUnavailableException } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { randomUUID } from 'node:crypto';
-import { Repository } from 'typeorm';
-import { SyncLog, SyncState, StudentDingMapping } from '../entities';
+import { DataSource, In, Repository } from 'typeorm';
+import { SyncLog, SyncState, Student, StudentDingMapping } from '../entities';
+import { JinshujuMatchRule, type JinshujuFieldMapping } from '../entities/jinshuju-match-rule.entity';
 import type { SyncPlatform, SyncStatus, SyncType } from '../entities/sync-log.entity';
 import { AttendanceImportService } from '../attendance/attendance-import.service';
 import { DingTalkService } from '../integration/dingtalk.service';
 import { WeComService } from '../integration/wecom.service';
+import { JinshujuService } from '../integration/jinshuju.service';
+import { syncJinshujuStudents } from '../integration/jinshuju-student-sync';
 import { ScheduleSyncService } from './schedule-sync.service';

@Injectable()
@@ -21,10 +24,14 @@ export class SyncService {
    private readonly syncStateRepo: Repository<SyncState>,
    @InjectRepository(StudentDingMapping)
    private readonly studentDingMappingRepo: Repository<StudentDingMapping>,
+    @InjectRepository(JinshujuMatchRule)
+    private readonly matchRuleRepo: Repository<JinshujuMatchRule>,
    private readonly dingTalkService: DingTalkService,
    private readonly weComService: WeComService,
+    private readonly jinshujuService: JinshujuService,
    private readonly attendanceImportService: AttendanceImportService,
    private readonly scheduleSyncService: ScheduleSyncService,
+    private readonly dataSource: DataSource,
  ) {}

  async syncDingTalkStudents(rootDeptId = 1): Promise<SyncLog> {
@@ -69,6 +76,149 @@ export class SyncService {
      return { recordsCount: result.userCount, status: 'success' };
    });
  }
+  async syncJinshuju(apiKey: string, apiSecret: string, formToken: string): Promise<SyncLog> {
+    return this.runSync('jinshuju', async () => {
+      const entries = await this.jinshujuService.fetchAllEntries(apiKey, apiSecret, formToken);
+      const result = await this.dataSource.transaction((manager) =>
+        syncJinshujuStudents(manager, entries),
+      );
+      return {
+        recordsCount: result.matched + result.created,
+        status: result.conflicts.length ? 'partial' : 'success',
+        message: result.conflicts.length
+          ? JSON.stringify(result.conflicts.slice(0, 20))
+          : `匹配 ${result.matched} 人，新增 ${result.created} 人，跳过无姓名 ${result.skippedNoName} 条`,
+      };
+    });
+  }
+
+  /** Fetch Jinshuju entries and return with auto-suggested student matches (no writes). */
+  getJinshujuFormFields(apiKey: string, apiSecret: string, formToken: string) {
+    return this.jinshujuService.fetchFormFields(apiKey, apiSecret, formToken);
+  }
+
+  async previewJinshuju(apiKey: string, apiSecret: string, formToken: string, ruleId?: number) {
+    const entries = await this.jinshujuService.fetchAllEntries(apiKey, apiSecret, formToken);
+    const rule = ruleId ? await this.getMatchRule(ruleId, formToken) : null;
+    const map = rule?.mappings ?? { name: 'field_1', phone: 'field_2' };
+
+    const parsed = entries
+      .map((e) => ({
+        serialNumber: e.serial_number,
+        name: this.extractField(e, map.name),
+        phone: this.extractField(e, map.phone),
+      }))
+      .filter((p) => p.name);
+
+    const phones = [...new Set(parsed.filter((p) => p.phone).map((p) => p.phone))];
+    const names = [...new Set(parsed.map((p) => p.name))];
+
+    const [phoneStudents, nameStudents] = await Promise.all([
+      phones.length
+        ? this.dataSource.getRepository(Student).find({ where: { phone: In(phones) } })
+        : ([] as Student[]),
+      names.length
+        ? this.dataSource.getRepository(Student).find({ where: { name: In(names) } })
+        : ([] as Student[]),
+    ]);
+
+    const studentByPhone = new Map(phoneStudents.map((s) => [s.phone, s]));
+    const studentByName = new Map<string, Student[]>();
+    for (const s of nameStudents) {
+      const list = studentByName.get(s.name) || [];
+      list.push(s);
+      studentByName.set(s.name, list);
+    }
+
+    const allStudents = await this.dataSource.getRepository(Student).find({
+      where: { status: 'active' },
+      order: { name: 'ASC' },
+      select: ['id', 'name', 'phone', 'studentNo'],
+    });
+
+    const rows = parsed.map((p) => {
+      const phoneMatch = p.phone ? studentByPhone.get(p.phone) : undefined;
+      const nameMatches = studentByName.get(p.name) || [];
+      const suggested = phoneMatch ?? nameMatches[0] ?? null;
+      return {
+        serialNumber: p.serialNumber,
+        name: p.name,
+        phone: p.phone || null,
+        suggestedStudent: suggested
+          ? { id: suggested.id, name: suggested.name, phone: suggested.phone, studentNo: suggested.studentNo }
+          : null,
+      };
+    });
+
+    return { entries: rows, students: allStudents };
+  }
+
+  /** Apply user's matching decisions. */
+  async applyJinshuju(
+    apiKey: string,
+    apiSecret: string,
+    formToken: string,
+    decisions: Array<{
+      serialNumber: number;
+      action: 'match' | 'create' | 'skip';
+      matchStudentId?: number;
+      createName?: string;
+      createPhone?: string;
+    }>,
+    ruleId?: number,
+  ): Promise<SyncLog> {
+    return this.runSync('jinshuju', async () => {
+      const rule = ruleId ? await this.getMatchRule(ruleId, formToken) : null;
+      const map = rule?.mappings ?? { name: 'field_1', phone: 'field_2' };
+      const entries = await this.jinshujuService.fetchAllEntries(apiKey, apiSecret, formToken);
+      const entryMap = new Map(entries.map((entry) => [entry.serial_number, entry]));
+      const decisionMap = new Map(decisions.map((decision) => [decision.serialNumber, decision]));
+
+      let matched = 0;
+      let created = 0;
+      await this.dataSource.transaction(async (manager) => {
+        const orgs = await manager.query(
+          'SELECT id FROM organizations WHERE is_host = 1 AND status = ? LIMIT 1',
+          ['active'],
+        );
+        const orgId: number | undefined = orgs[0]?.id;
+
+        for (const [serial, entry] of entryMap) {
+          const decision = decisionMap.get(serial);
+          if (!decision || decision.action === 'skip') continue;
+
+          const mappedValues = Object.fromEntries(
+            Object.entries(map)
+              .map(([studentField, fieldKey]) => [studentField, this.extractField(entry, fieldKey)])
+              .filter(([, value]) => value),
+          );
+
+          if (decision.action === 'match' && decision.matchStudentId) {
+            await manager.update(Student, decision.matchStudentId, mappedValues);
+            matched++;
+          } else if (decision.action === 'create') {
+            const name = decision.createName || mappedValues.name;
+            if (!name) continue;
+            await manager.save(
+              manager.create(Student, {
+                ...mappedValues,
+                name,
+                phone: decision.createPhone || mappedValues.phone || undefined,
+                organizationId: orgId,
+              }),
+            );
+            created++;
+          }
+        }
+      });
+
+      return {
+        recordsCount: matched + created,
+        status: 'success',
+        message: `匹配 ${matched} 人，新增 ${created} 人`,
+      };
+    });
+  }

  async triggerSync(platform?: SyncPlatform, rootDeptId = 1): Promise<SyncLog[]> {
    if (platform === 'dingtalk_students') return [await this.syncDingTalkStudents(rootDeptId)];
@@ -231,4 +381,84 @@ export class SyncService {
    log.errorMessage = errorMessage ?? null;
    await this.syncLogRepo.save(log);
  }
+
+  // ── Match Rules CRUD ──
+
+  async listMatchRules(): Promise<JinshujuMatchRule[]> {
+    return this.matchRuleRepo.find({ order: { updatedAt: 'DESC' } });
+  }
+
+  async createMatchRule(dto: {
+    name: string;
+    formToken: string;
+    mappings: JinshujuFieldMapping;
+  }): Promise<JinshujuMatchRule> {
+    this.validateMatchRule(dto.formToken, dto.mappings);
+    return this.matchRuleRepo.save(
+      this.matchRuleRepo.create({
+        ...dto,
+        name: dto.name.trim(),
+        formToken: dto.formToken.trim(),
+      }),
+    );
+  }
+
+  async updateMatchRule(
+    id: number,
+    dto: { name?: string; mappings?: JinshujuFieldMapping },
+  ): Promise<JinshujuMatchRule> {
+    const rule = await this.matchRuleRepo.findOne({ where: { id } });
+    if (!rule) throw new NotFoundException('规则不存在');
+    const mappings = dto.mappings ?? rule.mappings;
+    this.validateMatchRule(rule.formToken, mappings);
+    await this.matchRuleRepo.update(id, {
+      name: dto.name?.trim(),
+      mappings,
+    });
+    return this.matchRuleRepo.findOneOrFail({ where: { id } });
+  }
+
+  async deleteMatchRule(id: number): Promise<void> {
+    const result = await this.matchRuleRepo.delete(id);
+    if (!result.affected) throw new NotFoundException('规则不存在');
+  }
+
+  private async getMatchRule(id: number, formToken: string): Promise<JinshujuMatchRule> {
+    const rule = await this.matchRuleRepo.findOne({ where: { id } });
+    if (!rule) throw new NotFoundException('规则不存在');
+    if (rule.formToken !== formToken) {
+      throw new ConflictException('匹配规则不属于当前表单');
+    }
+    return rule;
+  }
+
+  private validateMatchRule(formToken: string, mappings: JinshujuFieldMapping): void {
+    if (!formToken.trim()) throw new ConflictException('表单 Token 不能为空');
+    if (!mappings.name) throw new ConflictException('匹配规则必须映射姓名字段');
+    const allowedStudentFields = new Set([
+      'name',
+      'studentNo',
+      'phone',
+      'idNumber',
+      'gender',
+      'ethnicity',
+      'emergencyContact',
+      'emergencyPhone',
+    ]);
+    for (const [studentField, fieldKey] of Object.entries(mappings)) {
+      if (!allowedStudentFields.has(studentField)) {
+        throw new ConflictException(`不允许映射学生字段：${studentField}`);
+      }
+      if (fieldKey && !/^field_\d+$/.test(fieldKey)) {
+        throw new ConflictException(`无效的金数据字段：${fieldKey}`);
+      }
+    }
+  }
+
+  /** Extract value from a Jinshuju entry by field mapping. */
+  private extractField(entry: Record<string, unknown>, fieldKey: string | undefined): string {
+    if (!fieldKey) return '';
+    const val = entry[fieldKey];
+    return typeof val === 'string' ? val.trim() : '';
+  }
 }