feat(contracts,api): page-mode pagination + synced profile on admin users list

Co-Authored-By: Claude Code <noreply@anthropic.com>

services/api/test/user-sync.e2e-spec.ts

@@ -257,7 +257,12 @@ describe('用户定期同步 /admin/user-sync (e2e)', () => {
   const U3 = (version: number) => ext('ext-3', 'sync-u3', '赵三', version);
 
   it('① 首轮全量：1 account 关联 + 2 新增（V1.1 直接 active）；counts/水位/映射/红线（不动凭据角色会话）', async () => {
-    scenario([U1(1), U2(1), U3(1)]); // pageSize 2 → 两页（1,2 | 3），全 v1
+    // U2 携带档案快照（G4 profile：随映射行落库，纯展示维度）。
+    scenario([
+      U1(1),
+      { ...U2(1), sourceProfile: { sn: 'S-002', email: 'u2@x.com', companyAbbr: '摄制' } },
+      U3(1),
+    ]); // pageSize 2 → 两页（1,2 | 3），全 v1
     const { run } = await triggerRun();
 
     expect(run.state).toBe('success');
@@ -303,6 +308,13 @@ describe('用户定期同步 /admin/user-sync (e2e)', () => {
     for (const m of mappings) {
       expect(m.sourceVersion).toBe(1);
     }
+    // profile 快照落库（G4）：U2 的映射行携带源档案，字段原样。
+    const m2 = await prisma.external_user_mappings.findUnique({
+      where: {
+        sourceSystem_externalUserId: { sourceSystem: 'mock', externalUserId: 'ext-2' },
+      },
+    });
+    expect(m2?.profile).toEqual({ sn: 'S-002', email: 'u2@x.com', companyAbbr: '摄制' });
 
     // status 端点：首轮即 success + 水位 + 计数。
     const status = await getStatus();
@@ -320,7 +332,11 @@ describe('用户定期同步 /admin/user-sync (e2e)', () => {
   });
 
   it('② 改名幂等：版本更高 → displayName 更新；同版本重跑 → 全跳过', async () => {
-    scenario([U1(1), U2(2, '王二改'), U3(1)]);
+    scenario([
+      U1(1),
+      { ...U2(2, '王二改'), sourceProfile: { sn: 'S-002', email: 'u2@x.com', companyAbbr: '摄制二部' } },
+      U3(1),
+    ]);
     const first = await triggerRun();
     expect(first.run.state).toBe('success');
     expect(first.run.counts).toEqual({ added: 0, updated: 1, disabled: 0, failed: 0 });
@@ -331,6 +347,8 @@ describe('用户定期同步 /admin/user-sync (e2e)', () => {
       },
     });
     expect(mapping?.sourceVersion).toBe(2);
+    // 快照随版本推进刷新（companyAbbr 变化生效）。
+    expect(mapping?.profile).toEqual({ sn: 'S-002', email: 'u2@x.com', companyAbbr: '摄制二部' });
 
     // 同版本重跑：幂等跳过，counts 全 0，displayName 不动。
     const again = await triggerRun();
@@ -725,4 +743,42 @@ describe('用户定期同步 /admin/user-sync (e2e)', () => {
     expect(anonPost.status).toBe(401);
     expect(anonPost.body.code).toBe(ErrorCodes.AUTH_TOKEN_EXPIRED);
   });
+
+  it('⑬ profile 展示补偿写：全量批同版本（版本门跳过）+ 快照缺失 → 回填且 counts 全 0', async () => {
+    // 回填只发生在**行被送到引擎**的批次——增量批过滤 v > 水位（11）会滤掉
+    // 同版本行；生产 http 源每批全量拉取天然送达。此处仿 ⑩ 把下一批顶成第
+    // 10 批全量对账批（cursor=null → 全场景行不过滤）。
+    const stateRow = await prisma.user_sync_state.findUniqueOrThrow({
+      where: { id: USER_SYNC_STATE_SINGLETON_ID },
+    });
+    const fillers = (10 - ((stateRow.runCount + 1) % 10)) % 10;
+    scenario([]);
+    for (let i = 0; i < fillers; i++) {
+      await triggerRun();
+    }
+
+    // 构造 G4 存量形态：ext-2 映射版本已最新（11）但 profile 为 null
+    // （JSON 列置 NULL 经原生 SQL——Prisma DbNull 需 @prisma/client 运行时
+    // 导入，api 包非其直接依赖）。
+    await prisma.$executeRaw`UPDATE external_user_mappings SET profile = NULL
+      WHERE sourceSystem = 'mock' AND externalUserId = 'ext-2'`;
+
+    // 全量批同版本行 + 快照：版本门跳过（不进 updated 桶）→ 仅回填 profile。
+    scenario([
+      { ...U2(11, '王二对账名'), sourceProfile: { sn: 'S-002R', companyAbbr: '摄制' } },
+    ]);
+    const { run } = await triggerRun();
+    expect(run.state).toBe('success');
+    expect(run.counts).toEqual({ added: 0, updated: 0, disabled: 0, failed: 0 });
+
+    const backfilled = await prisma.external_user_mappings.findUnique({
+      where: {
+        sourceSystem_externalUserId: { sourceSystem: 'mock', externalUserId: 'ext-2' },
+      },
+    });
+    expect(backfilled?.profile).toEqual({ sn: 'S-002R', companyAbbr: '摄制' });
+    // users 行未被牵连：版本未动、displayName 维持 ⑩ 对账值。
+    expect(backfilled?.sourceVersion).toBe(11);
+    expect((await userByAccount('sync-u2'))?.displayName).toBe('王二对账名');
+  });
 });