@allbluecn/web-app 0.23.3 → 0.23.5

package/src/server/sync/__tests__/sync-first-push.e2e.test.ts

@@ -0,0 +1,349 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 首次上云端到端（真实 schema）：空账号 + 一批本地业务行 → 引擎出箱 → 服务端
+// applyOp 逐 op 应用 → 全部 applied、零冲突、无 500（R3 收尾验收）。
+//
+// 装置：两个 **真实迁移全量** 的 PGlite 实例
+// - client：packages/database/migrations 全量 + 客户端 overlay（出箱触发器）
+//   ——等价桌面端 PGlite 库的真实形态（迁移里的服务端 overlay 也会装，与生产一致）
+// - cloud：同样的全量迁移（含 sync_trg_* 服务端触发器 + change log），空数据
+//   ——等价「刚绑定好的空云账号」
+//
+// 覆盖的真实 schema 外键（R3）：stories.iterationId → iterations、
+// test_cases.folderId → test_case_folders（本轮新注册）、knowledge_documents
+// 自引用 parentId（三轮深度）、stories.projectId → projects、docs.kbId →
+// knowledge_bases 等。数据播种刻意让**父行的最后一次修改晚于子行**（纯 lamport
+// 序会反序），由 PUSH_TABLE_ORDER + 祖先链深度排序纠正。
+// @vitest-environment node
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createPglite, type PgliteHandle } from '@allbluecn/database/pglite-init'
+import {
+  SYNC_TABLES,
+  SYNC_TABLE_MAP,
+  admitScopeForOp,
+  applyOp,
+  createSyncEngine,
+} from '@allbluecn/sync-core'
+import { buildClientOverlayDdl } from '@allbluecn/sync-core/client/overlay'
+import type { ApplyOpOutcome, SyncOp, SyncOpResult, SyncPushResponse } from '@allbluecn/sync-core'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+// apps/web/src/server/sync/__tests__ → 仓根（6 层）
+const MIGRATIONS_DIR = join(HERE, '../../../../../..', 'packages/database/migrations')
+
+const OWNER = 'cloud-owner-e2e'
+const GUEST_SESSION_SCOPES = [`user:${OWNER}`]
+
+const tmpDirs: string[] = []
+function makeDataDir(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix))
+  tmpDirs.push(dir)
+  return dir
+}
+
+async function openRealSchemaDb(prefix: string): Promise<PgliteHandle> {
+  return createPglite({ dataDir: makeDataDir(prefix), migrationsDir: MIGRATIONS_DIR })
+}
+
+function executorOf(handle: PgliteHandle) {
+  return {
+    query: async <T = Record<string, unknown>>(sql: string, params: unknown[] = []) =>
+      (await handle.db.query<T>(sql, params as never[])).rows as T[],
+    execute: async (sql: string, params: unknown[] = []) => {
+      const r = await handle.db.query(sql, params as never[])
+      return (r as unknown as { rows?: unknown[] }).rows?.length ?? 0
+    },
+  }
+}
+
+function mapOutcome(opId: string, outcome: ApplyOpOutcome): SyncOpResult {
+  switch (outcome.kind) {
+    case 'applied':
+      return { opId, status: 'applied', syncVersion: outcome.syncVersion, row: outcome.row }
+    case 'duplicate':
+      return { opId, status: 'applied', syncVersion: outcome.syncVersion }
+    case 'conflict':
+      return {
+        opId,
+        status: 'conflict',
+        conflict: { reason: outcome.reason, local: outcome.local, remote: outcome.remote },
+      }
+    case 'forbidden':
+      return { opId, status: 'conflict', conflict: { reason: 'forbidden' } }
+    case 'unknownTable':
+      return { opId, status: 'conflict', conflict: { reason: 'unknownTable' } }
+    case 'invalidPayload':
+      return { opId, status: 'conflict', conflict: { reason: outcome.reason } }
+  }
+}
+
+/**
+ * 云侧 push 处理器（与 apps/web/src/routes/api/sync/push.ts 同构的最小实现）：
+ * 整批单事务 + 逐 op 动态 scope 准入 + applyOp。任何未降级的异常都会直接抛出
+ * （= 生产里的 push 500），故本用例「全 applied」即等价「无 500」。
+ */
+function createCloudPushHandler(cloud: PgliteHandle) {
+  const ex = executorOf(cloud)
+  return async (ops: SyncOp[]): Promise<SyncPushResponse> => {
+    const admitted = new Set(GUEST_SESSION_SCOPES)
+    await ex.execute('BEGIN', [])
+    try {
+      const results: SyncOpResult[] = []
+      for (const op of ops) {
+        const reg = SYNC_TABLE_MAP.get(op.table)
+        if (!reg) {
+          results.push({ opId: op.opId, status: 'conflict', conflict: { reason: 'unknownTable' } })
+          continue
+        }
+        await admitScopeForOp(ex, reg, { pk: op.pk, op: op.op, payload: op.payload }, OWNER, admitted)
+        const outcome = await applyOp(ex, reg, op, {
+          userId: OWNER,
+          scopes: [...admitted],
+          now: new Date('2026-11-01T00:00:00Z'),
+        })
+        results.push(mapOutcome(op.opId, outcome))
+      }
+      await ex.execute('COMMIT', [])
+      return { results }
+    } catch (e) {
+      await ex.execute('ROLLBACK', [])
+      throw e
+    }
+  }
+}
+
+let client: PgliteHandle
+let cloud: PgliteHandle
+let pushToCloud: (ops: SyncOp[]) => Promise<SyncPushResponse>
+
+beforeAll(async () => {
+  // 两个实例并行初始化：全量迁移在 PGlite 上各需数秒
+  ;[client, cloud] = await Promise.all([openRealSchemaDb('sync-e2e-client-'), openRealSchemaDb('sync-e2e-cloud-')])
+  // 客户端 overlay（真实桌面端由宿主在 bootstrap 时装配）：出箱 + row_state + 游标
+  await client.db.exec(buildClientOverlayDdl(SYNC_TABLES, { clientId: 'client-e2e', schemaVersion: 'sv-e2e' }))
+  // 云端「空账号」= 只有账号本身（users 行由 exchange 的 ensureCloudIdentity 建好），
+  // 无任何业务数据。users 行是 workspaces.ownerId / stories.createdById 等 FK 的目标，
+  // 缺了它首推会（正确地）撞 FK——真实链路里这一行必然存在。
+  await cloud.prisma.user.create({
+    data: { id: OWNER, email: 'owner-e2e@example.com', username: '云上用户', password: 'x' },
+  })
+  pushToCloud = createCloudPushHandler(cloud)
+}, 300_000)
+
+afterAll(async () => {
+  await client?.prisma.$disconnect()
+  await cloud?.prisma.$disconnect()
+  while (tmpDirs.length) {
+    const dir = tmpDirs.pop()
+    if (dir) rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+/** 本地播种：真实 schema 下的「一台设备上的全部数据」 */
+async function seedLocalData(prisma: PgliteHandle['prisma']) {
+  await prisma.user.create({
+    data: { id: OWNER, email: 'owner-e2e@example.com', username: '云上用户', password: 'x' },
+  })
+  await prisma.workspace.create({ data: { id: 'ws1', name: '我的空间', ownerId: OWNER } })
+  await prisma.project.create({
+    data: { id: 'p1', displayId: 'PRJ', name: '我的项目', ownerId: OWNER, workspaceId: 'ws1' },
+  })
+  await prisma.workspaceMember.create({
+    data: { id: 'wm1', workspaceId: 'ws1', userId: OWNER, role: 'owner' },
+  })
+  await prisma.projectMember.create({
+    data: { id: 'pm1', projectId: 'p1', userId: OWNER, role: 'owner' },
+  })
+  // 迭代先建、随后改名（lamport 晚于 story）——旧兜底序会把 story 排在前面撞 FK
+  await prisma.iteration.create({
+    data: {
+      id: 'it1',
+      projectId: 'p1',
+      name: '迭代 1',
+      startDate: new Date('2026-11-01T00:00:00Z'),
+      endDate: new Date('2026-11-30T00:00:00Z'),
+      createdById: OWNER,
+    },
+  })
+  await prisma.story.create({
+    data: {
+      id: 's1',
+      sequenceId: 1,
+      identifier: 'PRJ-1',
+      projectId: 'p1',
+      name: '带迭代的需求',
+      iterationId: 'it1',
+      createdById: OWNER,
+    },
+  })
+  // 知识库 + 三层文档树
+  await prisma.knowledgeBase.create({ data: { id: 'kb1', name: '知识库', userId: OWNER, workspaceId: 'ws1' } })
+  for (const [id, parentId] of [
+    ['doc-root', null],
+    ['doc-child', 'doc-root'],
+    ['doc-grand', 'doc-child'],
+  ] as const) {
+    await prisma.knowledgeDocument.create({
+      data: { id, kbId: 'kb1', parentId, title: id, createdBy: OWNER, syncWorkspaceId: 'ws1' },
+    })
+  }
+  // 用例文件夹 + 带文件夹的用例（folder 随后改名 → lamport 晚于 test_case）
+  await prisma.testCaseFolder.create({ data: { id: 'f1', projectId: 'p1', name: '文件夹' } })
+  await prisma.testCase.create({
+    data: {
+      id: 'tc1',
+      sequenceId: 1,
+      identifier: 'PRJ-TC1',
+      projectId: 'p1',
+      folderId: 'f1',
+      title: '带文件夹的用例',
+      createdById: OWNER,
+    },
+  })
+
+  // 刻意把「父行」的最后修改排到子行之后（纯 lamport 序会反序）
+  await prisma.iteration.update({ where: { id: 'it1' }, data: { name: '迭代 1（改名）' } })
+  await prisma.testCaseFolder.update({ where: { id: 'f1' }, data: { position: 3 } })
+  await prisma.knowledgeDocument.update({ where: { id: 'doc-root' }, data: { title: '根（改名）' } })
+  await prisma.knowledgeDocument.update({ where: { id: 'doc-child' }, data: { title: '子（改名）' } })
+}
+
+describe('R3 首次上云：真实 schema 一批 op 全 applied（无 500）', () => {
+  it('workspace/project/member/iteration/story/kb/三层 doc/folder/test_case → 零冲突', async () => {
+    await seedLocalData(client.prisma)
+    const iface = executorOf(client)
+
+    // 出箱现状（诊断）：12 行 pending
+    const pending = await iface.query<{ table_name: string; pk: string; base_version: number }>(
+      `SELECT table_name, pk, base_version FROM sync_outbox WHERE status = 'pending' ORDER BY lamport`,
+    )
+    expect(pending).toHaveLength(12)
+    // 首推全部 base_version=0（本地新建）
+    expect(pending.every((r) => Number(r.base_version) === 0)).toBe(true)
+
+    // 机制对照：纯 lamport 序下 story 排在 iteration 之前（会被旧兜底序推成 FK 失败）
+    const lamportOrder = pending.map((r) => `${r.table_name}:${r.pk}`)
+    expect(lamportOrder.indexOf('stories:s1')).toBeLessThan(lamportOrder.indexOf('iterations:it1'))
+    expect(lamportOrder.indexOf('test_cases:tc1')).toBeLessThan(lamportOrder.indexOf('test_case_folders:f1'))
+
+    const engine = createSyncEngine({
+      executor: iface,
+      fetchApi: async (path, init) => {
+        if (path === '/api/sync/push') {
+          const body = JSON.parse(init.body!) as { ops: SyncOp[] }
+          return { status: 200, json: await pushToCloud(body.ops) }
+        }
+        return { status: 200, json: { changes: [], nextSeq: 0, hasMore: false } }
+      },
+      registrations: SYNC_TABLES,
+      batchSize: 200,
+    })
+
+    const result = await engine.syncOnce()
+    expect(result).toEqual({ pushed: 12, conflicts: 0, pulled: 0 })
+
+    // 出箱应已清空（无 pending、无 conflict）
+    const left = await iface.query<{ status: string; c: number }>(
+      `SELECT status, COUNT(*)::int AS c FROM sync_outbox GROUP BY status`,
+      [],
+    )
+    expect(left).toEqual([])
+
+    // 云端落库的事实断言（含真实外键列）
+    const cloudEx = executorOf(cloud)
+    expect((await cloudEx.query(`SELECT COUNT(*)::int AS c FROM workspaces`, []))[0]).toEqual({ c: 1 })
+    expect((await cloudEx.query(`SELECT COUNT(*)::int AS c FROM projects`, []))[0]).toEqual({ c: 1 })
+    expect((await cloudEx.query(`SELECT COUNT(*)::int AS c FROM workspace_members`, []))[0]).toEqual({ c: 1 })
+    expect((await cloudEx.query(`SELECT COUNT(*)::int AS c FROM project_members`, []))[0]).toEqual({ c: 1 })
+    expect((await cloudEx.query(`SELECT COUNT(*)::int AS c FROM iterations`, []))[0]).toEqual({ c: 1 })
+    expect((await cloudEx.query(`SELECT COUNT(*)::int AS c FROM test_case_folders`, []))[0]).toEqual({ c: 1 })
+
+    const story = await cloudEx.query<{ iterationId: string | null; identifier: string }>(
+      `SELECT "iterationId", identifier FROM stories WHERE id = 's1'`,
+      [],
+    )
+    expect(story[0]).toEqual({ iterationId: 'it1', identifier: 'PRJ-1' })
+
+    const tc = await cloudEx.query<{ folderId: string | null }>(
+      `SELECT "folderId" FROM test_cases WHERE id = 'tc1'`,
+      [],
+    )
+    expect(tc[0]).toEqual({ folderId: 'f1' })
+
+    const docs = await cloudEx.query<{ id: string; parentId: string | null }>(
+      `SELECT id, "parentId" FROM knowledge_documents ORDER BY id`,
+      [],
+    )
+    expect(docs).toEqual([
+      { id: 'doc-child', parentId: 'doc-root' },
+      { id: 'doc-grand', parentId: 'doc-child' },
+      { id: 'doc-root', parentId: null },
+    ])
+  }, 300_000)
+
+  it('机制对照：子行先于父行推送 → FK 降级为 per-op 冲突（不再 500），父行到达后可重推成功', async () => {
+    const ex = executorOf(cloud)
+    const now = '2026-11-01T00:00:00.000Z'
+    const mk = (over: Partial<SyncOp>): SyncOp => ({
+      opId: `op-ctl-${Math.random().toString(36).slice(2, 10)}`,
+      table: 'stories',
+      pk: 's-ctl',
+      op: 'upsert',
+      payload: {
+        id: 's-ctl',
+        sequenceId: 9,
+        identifier: 'PRJ-9',
+        projectId: 'p1',
+        name: '顺序错误的需求',
+        createdById: OWNER,
+        createdAt: now,
+        updatedAt: now,
+        iterationId: 'it-ctl',
+      },
+      baseVersion: 0,
+      lamport: 1,
+      clientId: 'client-e2e',
+      schemaVersion: 'sv-e2e',
+      ...over,
+    })
+
+    // ① story 先到（iteration 尚不存在）→ 冲突，不抛（旧实现此处整批 500）
+    const first = await pushToCloud([mk({})])
+    expect(first.results[0]).toMatchObject({ status: 'conflict', conflict: { reason: 'fk-violation' } })
+    expect((await ex.query(`SELECT id FROM stories WHERE id = 's-ctl'`, [])).length).toBe(0)
+
+    // ② 父行到达
+    const iter = await pushToCloud([
+      mk({
+        table: 'iterations',
+        pk: 'it-ctl',
+        payload: {
+          id: 'it-ctl',
+          projectId: 'p1',
+          name: '对照迭代',
+          startDate: now,
+          endDate: now,
+          createdById: OWNER,
+          createdAt: now,
+          updatedAt: now,
+        },
+      } as Partial<SyncOp>),
+    ])
+    expect(iter.results[0]).toMatchObject({ status: 'applied' })
+
+    // ③ 子行重推（新 opId = 客户端未标记 applied 的重试形态）→ applied
+    const retry = await pushToCloud([mk({})])
+    expect(retry.results[0]).toMatchObject({ status: 'applied' })
+    const row = await ex.query<{ iterationId: string | null }>(
+      `SELECT "iterationId" FROM stories WHERE id = 's-ctl'`,
+      [],
+    )
+    expect(row[0]).toEqual({ iterationId: 'it-ctl' })
+  }, 120_000)
+})

package/src/server/sync/account-status-cloud.ts

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 云账号空置状态的**云端权威**探测（桌面本地优先 P3 收尾 I2）。
+//
+// 背景：绑定转移的「目标必须空账号」复核原先用本地 PGlite 的 isAccountEmpty
+// 按 cloudUserId 计数——转移前恒 0（真）、**转移后恒 >0（假）**，第二次进入
+// bind 流程会被自己的本地数据判成「目标账号非空」，幂等重试直接失效；本地库
+// 也根本看不到云端数据（非空账号的真实判定只有 SaaS 权威）。
+//
+// 口径（与 probeCloudAccountStatusFn 原实现逐字一致）：以云会话 token 请求
+// SaaS /api/sync/account-status；非 200 / 网络异常 / 形状漂移一律视为
+// unreachable（宁可不转不可错转），调用方按「拒绝转移」处理。
+import { DESKTOP_SAAS_URL } from './saas-profile'
+
+export interface CloudAccountStatus {
+  empty: boolean
+  /** true = 无法确认（非空按 false 返回，调用方必须拒绝转移） */
+  unreachable: boolean
+}
+
+/** 以云会话 token 探测云端账号是否空账号（SaaS 权威） */
+export async function probeCloudAccountStatus(
+  sessionToken: string | undefined,
+): Promise<CloudAccountStatus> {
+  if (!sessionToken) return { empty: false, unreachable: true }
+  try {
+    const res = await fetch(`${DESKTOP_SAAS_URL}/api/sync/account-status`, {
+      headers: { Cookie: `auth.session-token=${sessionToken}` },
+      credentials: 'omit',
+      signal: AbortSignal.timeout(10_000),
+    })
+    if (!res.ok) return { empty: false, unreachable: true }
+    const json = (await res.json().catch(() => null)) as { empty?: unknown } | null
+    if (typeof json?.empty !== 'boolean') return { empty: false, unreachable: true }
+    return json.empty ? { empty: true, unreachable: false } : { empty: false, unreachable: false }
+  } catch {
+    return { empty: false, unreachable: true }
+  }
+}

package/src/server/sync/ownership-transfer.ts

@@ -10,16 +10,20 @@
 //
 // 属主列全集的派生口径（A8 预裁定，A5 实证）：schema **全量 User-relation FK
 // 标量列**（遍历 @relation 到 User 的关系取其 fields 标量列，共 79 处；含
-// ownerId/userId/createdById/createdBy/assignee 类），排除 users 表自身与
-// TRANSFER_EXCLUDED（配置类不转移，规格 Q1①）。为什么必须全量：转移末尾删除
-// guest users 行，任何漏改的 User-FK 列要么触发 onDelete: Cascade **级联删掉
-// 业务数据**，要么留下指向已删用户的孤儿行 / Restrict 直接炸删除——全量翻转是
-// 规格 Q1②「防孤儿行」的唯一安全读法。
+// ownerId/userId/createdById/createdBy/assignee 类，**含 AiProviderConfig.userId**
+// ——C3 裁定：AI 配置随身份翻转，见 TRANSFER_EXCLUDED 注释），排除 users 表自身。
+// 为什么必须全量：转移末尾删除 guest users 行，任何漏改的 User-FK 列要么触发
+// onDelete: Cascade **级联删掉业务数据**，要么留下指向已删用户的孤儿行 /
+// Restrict 直接炸删除——全量翻转是规格 Q1②「防孤儿行」的唯一安全读法。
 //
-// ⚠ 不触碰 sync_outbox/sync_row_state（简报 ④，审查重点 2）：属主 UPDATE 走
-// 常规 Prisma 写入，已装触发的表自然产出 op='upsert' + base_version=0 的整行
-// change log，推送拓扑 A7 已修为 upsert 正向——转移面因此天然含全部注册表，
-// 本函数手碰同步两表反而会污染版本语义。测试 ④ 以「零触达」断言钉死此边界。
+// ⚠ sync_outbox 零触达；sync_row_state 只在正向转移末尾做一次**版本基线重置**
+// （R2 换绑修复：base_version=0 + dirty=true，见函数内 ③）。属主 UPDATE 走常规
+// Prisma 写入，已装触发的表自然产出 op='upsert' + base_version=0 的整行 change
+// log，推送拓扑 A7 已修为 upsert 正向——转移面因此天然含全部注册表；基线重置是
+// 唯一必需的例外（旧 base_version 指向上一个账号的云端版本，换绑后会全量
+// remoteRowMissing 冲突）。
+// ai_provider_configs **不在同步面**（SYNC_TABLES 仅 10 张注册表，无此表）：
+// 翻转只改本地行，不产出 outbox/change log，AI Key 不会随同步上云。
 //
 // 幂等语义：重复调用不抛错——UPDATE where fromUserId 匹配 0 行（已翻转）、
 // 云身份行 upsert update 分支留空（no-op）、guest 行已删（deleteMany 计 0
@@ -27,21 +31,27 @@
 // 清单对齐哨兵：__tests__/ownership-transfer.test.ts 内固定清单与本常量逐项
 // 相等——schema 增删 User-relation FK 时该测试红，须同步重扫本清单。
 
-import { randomUUID } from "node:crypto"
 import type { PrismaClient } from "@allbluecn/database"
+import { ensureCloudIdentity, readUserPreferences } from "@/server/desktop-cloud-identity"
 import { ensureLocalShadowUserWith } from "@/server/desktop-bootstrap"
 
 /**
- * 配置类排除清单（规格 Q1①「配置类不转移」）：
- * - `AiProviderConfig.userId`：用户 AI 配置属配置数据而非业务数据，不随归属
- *   翻转（转移后 guest 的 AI 配置随 guest 行级联删除——删前 guest 已不再使用）。
- * - DesktopSetting 无 user 列（桌面设置按设备存储），不在口径内。
+ * 配置类排除清单（规格 Q1①）——**C3 裁定已清零**：原先把 `AiProviderConfig.userId`
+ * 排除在翻转之外，但转移末尾的 `user.deleteMany` 会经 `ON DELETE CASCADE` 把
+ * guest 名下全部 AI 配置行一起删掉（「不翻转」实际等于「静默丢失」）。现改为
+ * 随身份翻转：配置行在删行前已改属云身份，CASCADE 无从命中；反向转移同理把
+ * 云态配置带回 guest。用户级偏好列（aiApiKey/locale/timezone 等）另由
+ * ensureCloudIdentity / readUserPreferences 复制（见 desktop-cloud-identity）。
+ *
+ * 常量保留为「口径位」：新增真正不该翻转的 User-FK 列时在此登记（并在
+ * OWNERSHIP_COLUMNS 之外），当前为空。
  */
-export const TRANSFER_EXCLUDED: readonly string[] = ["AiProviderConfig.userId"]
+export const TRANSFER_EXCLUDED: readonly string[] = []
 
 /**
- * 属主列全集：schema 全量 User-relation FK 标量列（79 处）减 TRANSFER_EXCLUDED
- * = 78 处「表.列」（table 为 Prisma 模型名，delegate 取 lowerFirst）。
+ * 属主列全集：schema 全量 User-relation FK 标量列（79 处，**含** AiProviderConfig.userId）
+ * 减 TRANSFER_EXCLUDED（当前为空）= 79 处「表.列」（table 为 Prisma 模型名，
+ * delegate 取 lowerFirst）。
  * 派生方法（复核命令）：
  *   grep -nE "^\s*\w+\s+User\??\s+@relation" packages/database/schema.prisma
  * 取各行的 fields: [...] 标量列；与 User 模型反向关系数组（79 项）互为镜像。
@@ -99,6 +109,9 @@ export const OWNERSHIP_COLUMNS: ReadonlyArray<{ table: string; column: string }>
   { table: "StoryFilterView", column: "userId" },
   { table: "Subscription", column: "userId" },
   { table: "AiUsageLog", column: "userId" },
+  // C3：AI 配置随身份翻转（移出 TRANSFER_EXCLUDED——否则末尾删 guest 行会经
+  // ON DELETE CASCADE 把配置行一起删掉）。该表不在同步面（无触发器/无 outbox）。
+  { table: "AiProviderConfig", column: "userId" },
   { table: "LicenseKey", column: "issuedById" },
   { table: "SsoMapping", column: "userId" },
   { table: "RoleAssignment", column: "userId" },
@@ -157,9 +170,10 @@ function delegateKey(model: string): string {
  * OWNERSHIP_COLUMNS 长度）；`rows`：Σ updateMany.count（实际翻转的属主行数，
  * 幂等二跑为 0）。
  *
- * 步序（事务内）：① upsert 云身份行（必须先于属主翻转——后续 FK 写入的合法
- * 目标；update 分支留空保证幂等不覆盖既有资料，password 随机占位与
- * desktop-bootstrap 同惯例：本地行凭据登录必失败）；② 全量属主列 UPDATE；
+ * 步序（事务内）：① ensureCloudIdentity 幂等建云身份行（必须先于属主翻转——
+ * 后续 FK 写入的合法目标；update 分支留空保证幂等不覆盖既有资料，password
+ * 随机占位与 desktop-bootstrap 同惯例：本地行凭据登录必失败；email/username
+ * 与本地既有用户冲突时降级占位，不 P2002 崩掉转移）；② 全量属主列 UPDATE；
  * ③ 删除 guest 行（Restrict 列已全部翻转，删除不被 FK 阻塞）。
  */
 export async function transferOwnership(
@@ -175,23 +189,23 @@ export async function transferOwnership(
   const columns = OWNERSHIP_COLUMNS
 
   return prisma.$transaction(async (tx) => {
-    // ① 云身份行（先于属主翻转：FK 目标必须先存在）
-    await tx.user.upsert({
-      where: { id: toUserId },
-      create: {
+    // ① 云身份行（先于属主翻转：FK 目标必须先存在）。统一走 ensureCloudIdentity
+    //    （C2）：幂等 upsert + email/username 唯一冲突降级——本地凭据用户已占用
+    //    云邮箱时不再 P2002 崩掉整个转移。
+    //    C3：copyPreferencesFrom=guest——用户级配置列（AI key/模型/语言/时区等）
+    //    随身份搬到云行；否则 guest 行删除后这些配置直接丢失（AI Key 需要重填）。
+    await ensureCloudIdentity(
+      tx,
+      {
         id: toUserId,
-        email: toUser.email?.trim() || `${toUserId}@cloud.local`,
-        username: toUser.name?.trim() || toUserId,
-        password: randomUUID(),
-        avatarConfig: (toUser.avatarConfig ?? undefined) as object | undefined,
-        bgShape: toUser.bgShape ?? undefined,
-        bgColor: toUser.bgColor ?? undefined,
-        status: "ACTIVE",
+        name: toUser.name,
+        email: toUser.email,
+        avatarConfig: toUser.avatarConfig,
+        bgShape: toUser.bgShape,
+        bgColor: toUser.bgColor,
       },
-      // update 留空（同 desktop-bootstrap 惯例）：云身份行已存在时 upsert no-op，
-      // 不覆盖用户后续改名/改头像（幂等）
-      update: {},
-    })
+      { copyPreferencesFrom: fromUserId },
+    )
 
     // ② 全量属主列翻转（清单纯 server 侧数据；配置类 TRANSFER_EXCLUDED 不在内）
     let rows = 0
@@ -211,7 +225,23 @@ export async function transferOwnership(
       rows += result.count
     }
 
-    // ③ 删除 guest 行（翻转后无任何 FK 指向它：Cascade 无从级联、Restrict 不阻塞）。
+    // ③ 重置 sync_row_state 版本基线（R2，换绑账号）：反向转移**保留** row_state
+    //    （裁定 R2——维持同账号重登的版本连续性），但正向转移是「本机数据整体搬
+    //    去另一个（必为空的）云账号」：旧 base_version 是**上一个**账号的云端
+    //    版本号，留用会让首推撞 remoteRowMissing（云端 current=null 且
+    //    baseVersion>0）——全量冲突且不可自愈（resolveApplyLocal 不重置
+    //    base_version）。故在同事务内、属主翻转之后、删 guest 行之前清零基线：
+    //    - base_version = 0：新账号云端无行，首推按 INSERT 应用；
+    //    - dirty = true：翻转本身已为重同步面行产出待推 upsert（触发器语义
+    //      「本地有未推送变更」），且在新 op 落地前挡住 pull 覆盖本地行
+    //      （applyRemoteChange 对 dirty 行留存 conflict_copies 并跳过）。
+    //    选择 UPDATE 而非 DELETE 行：删掉 row_state 会让「行存在但无 row_state
+    //    记录」被 pull 视为非 dirty → 直接覆盖本地行（本地数据丢失窗口）；保留行
+    //    并把 dirty 置 true 才有防护。表名静态写死（非用户输入，无注入面），
+    //    $executeRaw 只经 tx（与属主翻转同一事务闭包，无 tick 窗口）。
+    await tx.$executeRaw`UPDATE sync_row_state SET base_version = 0, dirty = true`
+
+    // ④ 删除 guest 行（翻转后无任何 FK 指向它：Cascade 无从级联、Restrict 不阻塞）。
     // 必须用 deleteMany 而非 delete：delete 对已删行抛 P2025 并回滚整个二跑事务
     // （幂等二跑变确定性失败，renderer 超时重试即误入 bind:fail）——deleteMany
     // count=0 即 no-op，幂等三要素才全部为真（审查轮 1 修复）。
@@ -230,18 +260,21 @@ export async function transferOwnership(
  * ① guest 影子行**重建**而非删除：正向末尾删了 guest 行（或首启尚未 seed），
  *    反向翻转的 FK 目标必须先存在——事务内先调 ensureLocalShadowUserWith(tx)
  *    重建（抽自 desktop-bootstrap，原无参包装直用模块级 prisma 单例会绕过 tx）。
- * ② sync_outbox / sync_row_state **同事务清空**（正向零触达——正向的 outbox 语义
- *    由触发器自然产出；反向必须清：属主翻转触发的 upsert ops 若留在 outbox，登出
- *    后引擎一旦带云会话 tick 就会把「cloud→guest 属主翻转」推上云，污染云端数据
- *    ——审查重点「防反向 op 推上云」）。两表是 sync-core 客户端原生 SQL 表（无
- *    Prisma delegate），用 $executeRaw 静态 SQL（表名写死非用户输入，无注入面），
- *    且与属主 UPDATE 同一 $transaction 闭包（原子化，无 tick 窗口）；行状态重建
- *    由下次 pull bootstrap 回填。
+ * ② sync_outbox **同事务清空**，sync_row_state **保留**（正向两表零触达——正向的
+ *    outbox 语义由触发器自然产出）。清 outbox 是必须的：属主翻转触发的 upsert ops
+ *    若留在队列，登出后引擎一旦带云会话 tick 就会把「cloud→guest 属主翻转」推上
+ *    云，污染云端数据（审查重点「防反向 op 推上云」）。row_state 不清（裁定 R2）：
+ *    它存的是 base_version（该行上次同步到的云端 sync_version），清掉会让重登后的
+ *    首推 base_version 全 0 而云端 sync_version ≥ 1 → 全量 versionDiverged；保留即
+ *    维持版本连续性，且 row_state 不承载「待推 op」语义（推什么由 outbox 决定）。
+ *    两表都是 sync-core 客户端原生 SQL 表（无 Prisma delegate），用 $executeRaw 静态
+ *    SQL（表名写死非用户输入，无注入面），且与属主 UPDATE 同一 $transaction 闭包
+ *    （原子化，无 tick 窗口）。
  * ③ 云身份行删除后不做快照/恢复编排：单事务自身原子，失败整体回滚即留在云态，
  *    调用方（reverseTransferOwnershipFn + renderer 登出流程）解锁后可重试。
  *
  * 幂等语义与正向一致：二跑 UPDATE 匹配 0 行、guest 行 upsert update 留空、云身份
- * 行 deleteMany 计 0 no-op、raw 清表照常（DELETE 全表天然幂等）。
+ * 行 deleteMany 计 0 no-op、raw 清 outbox 照常（DELETE 全表天然幂等）。
  */
 export async function reverseTransferOwnership(
   prisma: PrismaClient,
@@ -256,10 +289,13 @@ export async function reverseTransferOwnership(
 
   return prisma.$transaction(async (tx) => {
     // ① guest 影子行重建（先于属主翻转：FK 目标必须先存在；update 留空幂等，
-    //    不覆盖既有影子行资料）
-    await ensureLocalShadowUserWith(tx)
+    //    不覆盖既有影子行资料）。C3：云身份行删除前把用户级配置列（AI key/
+    //    模型/语言/时区等）复制到重建的 guest 行——否则云态填的配置随云行
+    //    消失（只在 create 分支生效：已存在的影子行保留本机值）。
+    const cloudPreferences = await readUserPreferences(tx, fromUserId)
+    await ensureLocalShadowUserWith(tx, cloudPreferences)
 
-    // ② 全量属主列翻转 cloud → guest（与正向同清单反向；TRANSFER_EXCLUDED 同样不在内）
+    // ② 全量属主列翻转 cloud → guest（与正向同清单反向，含 AiProviderConfig：
     let rows = 0
     const delegates = tx as unknown as Record<string, OwnerDelegate | undefined>
     for (const { table, column } of columns) {
@@ -279,12 +315,15 @@ export async function reverseTransferOwnership(
     // ③ 删除云身份行（翻转后无 FK 指向它；deleteMany 幂等——二跑已删计 0）
     await tx.user.deleteMany({ where: { id: fromUserId } })
 
-    // ④ 同事务清空同步两表（防反向 op 推上云污染；表名静态写死无注入面）。
+    // ④ 同事务清空 outbox（防反向 op 推上云污染；表名静态写死无注入面）。
     //    放在翻转之后：清空前的任何窗口内 outbox ops 都随事务回滚/覆盖，清空后
     //    引擎 tick 无 op 可推。$executeRaw 仅经 tx（测试以「外层无此方法」钉死同
     //    闭包语义）。
+    //    ⚠ 不清 sync_row_state（裁定 R2）：属主翻转产生的 upsert op 必须清（否则
+    //    反向流转被推上云），但 row_state 的 base_version 是「行上次同步到的云端
+    //    版本」，清掉会让重登后首推 base_version 全 0 vs 云端 sync_version ≥ 1 →
+    //    全量 versionDiverged。保留它维持版本连续性。
     await tx.$executeRaw`DELETE FROM sync_outbox`
-    await tx.$executeRaw`DELETE FROM sync_row_state`
 
     return { tables: columns.length, rows }
   })