feat: add Jinshuju student sync

2026-07-22 11:37:20 +08:00
parent 1dc13274de
commit 393ee62168
18 changed files with 1378 additions and 12 deletions
--- 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() : '';
+  }
 }