xiongyuxing/gongxue-base
1
0
Fork 0
forked from wangziqi/gongxue-base
Code Pull Requests Activity

feat: add Jinshuju student sync

Browse Source
This commit is contained in:
wangziqi
2026-07-22 11:37:20 +08:00
parent 1dc13274de
commit 393ee62168
18 changed files with 1378 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

565
apps/admin/src/components/JinshujuMatchModal.tsx Normal file
View File

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

16
apps/admin/src/pages/Students/index.tsx
View File

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

6
apps/server/src/app.module.ts
View File

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

1
apps/server/src/entities/index.ts
View File

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

53
apps/server/src/entities/jinshuju-match-rule.entity.ts Normal file
View File

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

2
apps/server/src/entities/sync-log.entity.ts
View File

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

5
apps/server/src/integration/integration.module.ts
View File

@@ -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 {}

118
apps/server/src/integration/jinshuju-student-sync.ts Normal file
View File

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

101
apps/server/src/integration/jinshuju.service.ts Normal file
View File

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

2
apps/server/src/migration-runner.ts
View File

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

33
apps/server/src/migrations/1784700000000-AddJinshujuMatchRules.ts Normal file
View File

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

4
apps/server/src/rbac/rbac.service.ts
View File

@@ -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')

40
apps/server/src/rbac/rbac.teachers.spec.ts Normal file
View File

@@ -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: ['任课老师', '老师'],
},
);
});
});

19
apps/server/src/sync/sync.controller.spec.ts
View File

@@ -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: '姓名' });
});
});

121
apps/server/src/sync/sync.controller.ts
View File

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

2
apps/server/src/sync/sync.module.ts
View File

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

66
apps/server/src/sync/sync.service.spec.ts
View File

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

236
apps/server/src/sync/sync.service.ts
View File

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