feat: add Jinshuju student sync

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,

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

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

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

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

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

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

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

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

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

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

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

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(

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,

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

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