@allbluecn/web-app 0.23.3 → 0.23.5

package/src/server/__tests__/exchange-remote-token.test.ts

@@ -11,13 +11,32 @@
 // /rate-limit 全 mock（不真写盘、不真限流）。
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-const H = vi.hoisted(() => ({
-  writeRemoteAuth: vi.fn(),
-  writeRemoteSession: vi.fn(),
-  generateEntitlementsToken: vi.fn(),
-  checkAuthRateLimit: vi.fn(),
-  fetch: vi.fn(),
-}))
+const H = vi.hoisted(() => {
+  type UserWhere = { where?: Record<string, string>; create?: Record<string, unknown> }
+  const tx = {
+    user: {
+      findUnique: vi.fn(async (_args?: UserWhere) => null as Record<string, unknown> | null),
+      upsert: vi.fn(async (args?: UserWhere) => args?.create),
+    },
+  }
+  return {
+    writeRemoteAuth: vi.fn(),
+    writeRemoteSession: vi.fn(),
+    generateEntitlementsToken: vi.fn(),
+    checkAuthRateLimit: vi.fn(),
+    fetch: vi.fn(),
+    tx,
+    prisma: {
+      $transaction: vi.fn(async (fn: (t: typeof tx) => Promise<unknown>) => fn(tx)),
+    },
+  }
+})
+
+/** 取第 n 次 user.upsert 的 create 载荷（测试断言入口） */
+function upsertCreate(n = 0): Record<string, unknown> {
+  const call = H.tx.user.upsert.mock.calls[n]?.[0] as { create?: Record<string, unknown> } | undefined
+  return call?.create ?? {}
+}
 
 vi.mock('@tanstack/react-start', () => {
   // 每个 serverFn 实例独立 capture（session.ts 有三个 serverFn，防串号）
@@ -62,6 +81,8 @@ vi.mock('@/server/entitlements-token', () => ({
 
 vi.mock('@/server/middlewares/rate-limit', () => ({ checkAuthRateLimit: H.checkAuthRateLimit }))
 
+vi.mock('@allbluecn/database/get-prisma', () => ({ getPrisma: async () => H.prisma }))
+
 import { exchangeRemoteTokenFn } from '../serverFns/auth/session'
 
 describe('exchangeRemoteTokenFn 双路径落盘（A10 修复）', () => {
@@ -69,6 +90,10 @@ describe('exchangeRemoteTokenFn 双路径落盘（A10 修复）', () => {
 
   beforeEach(() => {
     vi.resetAllMocks()
+    // resetAllMocks 清掉 hoisted 里的默认实现——逐用例回填（空库：无同 id 行）
+    H.tx.user.findUnique.mockResolvedValue(null)
+    H.tx.user.upsert.mockImplementation(async (args) => args?.create)
+    H.prisma.$transaction.mockImplementation(async (fn) => fn(H.tx))
     vi.stubGlobal('fetch', H.fetch)
   })
 
@@ -79,7 +104,7 @@ describe('exchangeRemoteTokenFn 双路径落盘（A10 修复）', () => {
     else process.env.DEPLOY_TARGET = saved
   })
 
-  it('signedToken 路径（生产 SaaS 恒发）：session 块 + token 双写', async () => {
+  it('signedToken 路径（生产 SaaS 恒发）：session 块 + token 双写 + 云身份行落库', async () => {
     process.env.DEPLOY_TARGET = 'desktop'
     H.fetch.mockResolvedValue({
       ok: true,
@@ -93,9 +118,27 @@ describe('exchangeRemoteTokenFn 双路径落盘（A10 修复）', () => {
     const res = await exchangeRemoteTokenFn({ data: { token: 'tok-123' } })
     expect(res).toEqual({ success: true, userId: 'cloud-1', planName: 'pro' })
     // 修复断言：session 块必须落盘（缺它 readRemoteAuth 恒 null → 云身份不激活）
-    expect(H.writeRemoteSession).toHaveBeenCalledWith('cloud-1', 'pro', 'tok-123')
+    // C2：profile 一并落盘（桌面回落会话组装真实昵称/邮箱）
+    expect(H.writeRemoteSession).toHaveBeenCalledWith('cloud-1', 'pro', 'tok-123', {
+      name: 'Cloud 用户',
+      email: 'cloud@example.com',
+      avatarConfig: undefined,
+      bgShape: undefined,
+      bgColor: undefined,
+    })
     expect(H.writeRemoteAuth).toHaveBeenCalledWith('signed-abc', 'tok-123')
     expect(H.generateEntitlementsToken).not.toHaveBeenCalled()
+    // C2 云身份自洽：users 行必须建出来（否则按 cloudUserId 的列表全空 / P2003）
+    expect(H.prisma.$transaction).toHaveBeenCalledTimes(1)
+    expect(H.tx.user.upsert).toHaveBeenCalledTimes(1)
+    const create = upsertCreate()
+    expect(create).toMatchObject({
+      id: 'cloud-1',
+      email: 'cloud@example.com',
+      username: 'Cloud 用户',
+      status: 'ACTIVE',
+    })
+    expect(typeof create.password).toBe('string')
   })
 
   it('degraded 路径（本地无签名 secret）：仅写 session 块，不写 writeRemoteAuth', async () => {
@@ -107,7 +150,46 @@ describe('exchangeRemoteTokenFn 双路径落盘（A10 修复）', () => {
     H.generateEntitlementsToken.mockResolvedValue(null)
     const res = await exchangeRemoteTokenFn({ data: { token: 'tok-456' } })
     expect(res).toEqual({ success: true, userId: 'cloud-2', planName: 'free', degraded: true })
-    expect(H.writeRemoteSession).toHaveBeenCalledWith('cloud-2', 'free', 'tok-456')
+    expect(H.writeRemoteSession).toHaveBeenCalledWith('cloud-2', 'free', 'tok-456', {
+      name: undefined,
+      email: undefined,
+      avatarConfig: undefined,
+      bgShape: undefined,
+      bgColor: undefined,
+    })
     expect(H.writeRemoteAuth).not.toHaveBeenCalled()
+    // 降级路径同样要有身份行（权益降级不等于身份缺失）
+    expect(H.tx.user.upsert).toHaveBeenCalledTimes(1)
+  })
+
+  it('同 email 已被本地凭据用户占用 → 降级占位邮箱，不 P2002 崩登录', async () => {
+    process.env.DEPLOY_TARGET = 'desktop'
+    H.fetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        user: { id: 'cloud-3', name: 'Cloud 三', email: 'taken@example.com' },
+        planName: 'free',
+        signedToken: 'signed-x',
+      }),
+    })
+    H.tx.user.findUnique.mockImplementation(
+      async (args?: { where?: Record<string, string> }) =>
+        args?.where?.email === 'taken@example.com' ? { id: 'local-user-1' } : null,
+    )
+    await exchangeRemoteTokenFn({ data: { token: 'tok-789' } })
+    expect(upsertCreate().email).toBe('cloud-3@cloud.local')
+  })
+
+  it('身份行已存在（重复 exchange）→ 幂等：不 upsert、不覆盖既有资料', async () => {
+    process.env.DEPLOY_TARGET = 'desktop'
+    H.fetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ user: { id: 'cloud-4' }, planName: 'free', signedToken: 'signed-y' }),
+    })
+    H.tx.user.findUnique.mockResolvedValue({ id: 'cloud-4' })
+    await exchangeRemoteTokenFn({ data: { token: 'tok-999' } })
+    expect(H.tx.user.upsert).not.toHaveBeenCalled()
+    // 会话仍照常落盘（激活与建行解耦：行在不在都要写 session）
+    expect(H.writeRemoteSession).toHaveBeenCalledTimes(1)
   })
 })

package/src/server/__tests__/remote-auth.test.ts

@@ -58,6 +58,45 @@ describe("remote-auth（Electron fs 持久层）", () => {
     expect(await readRemoteAuth()).toBeNull()
   })
 
+  it("C2 云资料落盘：writeRemoteSession 第 4 参 profile 读回为真实昵称/邮箱/头像", async () => {
+    await writeRemoteSession("user-1", "pro", "st-1", {
+      name: "云上名字",
+      email: "cloud@example.com",
+      avatarConfig: { hat: 1, face: 2 },
+      bgShape: "circle",
+      bgColor: "#3b82f6",
+    })
+    expect(await readRemoteAuth()).toMatchObject({
+      userId: "user-1",
+      username: "云上名字",
+      email: "cloud@example.com",
+      avatarConfig: { hat: 1, face: 2 },
+      bgShape: "circle",
+      bgColor: "#3b82f6",
+    })
+    // 后续 writeRemoteSession 省略 profile（旧调用形态）→ 已落盘资料不被抹掉
+    await writeRemoteSession("user-1", "pro", "st-2")
+    expect(await readRemoteAuth()).toMatchObject({
+      sessionToken: "st-2",
+      username: "云上名字",
+    })
+    // writeRemoteAuth 走 merge 语义，profile 与 session 互不覆盖
+    await writeRemoteAuth("signed-token", "st-2")
+    expect(await readRemoteAuth()).toMatchObject({ username: "云上名字", sessionToken: "st-2" })
+  })
+
+  it("C2 旧文件无 profile：读回资料字段全省略（回落 UUID/首字母，行为与旧版一致）", async () => {
+    await fs.writeFile(
+      path.join(dir, "remote-auth.json"),
+      JSON.stringify({ session: { userId: "user-1", planName: "pro" } }),
+      "utf8",
+    )
+    const data = await readRemoteAuth()
+    expect(data).toMatchObject({ userId: "user-1", planName: "pro" })
+    expect(data?.username).toBeUndefined()
+    expect(data?.avatarConfig).toBeUndefined()
+  })
+
   it("非 desktop 部署恒 no-op：写入不落盘、读取恒 null", async () => {
     process.env.DEPLOY_TARGET = "vercel"
     await writeRemoteSession("user-1", "pro")

package/src/server/desktop-bootstrap.ts

@@ -70,11 +70,17 @@ export async function ensureLocalShadowUser(): Promise<string> {
  * 只含 users 行 upsert：内置独立项目走 ensureBuiltinIndependentProject（模块级
  * prisma），由登出后的 getSessionFn guest 分支懒补（项目行经反向转移已回 guest
  * 属主，通常已存在）。
+ *
+ * @param preferences C3：反向转移把云身份行的用户级配置列（AI key/模型/语言/
+ *   时区等）带给重建的 guest 行。只在 create 分支生效——影子行已存在时保留
+ *   本机既有值（update 留空的幂等语义不变）。
  */
-export async function ensureLocalShadowUserWith(tx: Prisma.TransactionClient): Promise<string> {
-  await tx.user.upsert({
-    where: { id: GUEST_USER_ID },
-    create: {
+export async function ensureLocalShadowUserWith(
+  tx: Prisma.TransactionClient,
+  preferences?: Record<string, unknown>,
+): Promise<string> {
+  const create = Object.assign(
+    {
       id: GUEST_USER_ID,
       email: GUEST_EMAIL,
       username: GUEST_USERNAME,
@@ -82,8 +88,13 @@ export async function ensureLocalShadowUserWith(tx: Prisma.TransactionClient): P
       avatarConfig: defaultAvatarConfig as object,
       bgShape: 'square',
       bgColor: shadowBgColor(GUEST_USERNAME),
-      status: 'ACTIVE',
+      status: 'ACTIVE' as const,
     },
+    preferences ?? {},
+  ) as Prisma.UserUncheckedCreateInput
+  await tx.user.upsert({
+    where: { id: GUEST_USER_ID },
+    create,
     update: {},
   })
   return GUEST_USER_ID

package/src/server/desktop-cloud-identity.ts

@@ -0,0 +1,247 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 云身份行幂等落库（桌面本地优先 P3 收尾 C2 / 裁定 R3）。
+//
+// 背景：exchangeRemoteTokenFn 原先只写 remote-auth.json，不建本地 users 行 →
+// 云会话激活后按 cloudUserId 的列表全空、写入撞 P2003（外键目标不存在）、
+// 同步 scope 解析不到任何行——「云身份自洽」缺口。非空账号 / 探测不可达 /
+// 旧壳路径直接把用户带进这个坏态。
+//
+// 本模块是**唯一**的云身份建行入口（exchange、正向转移共用；反向转移复用
+// ensureLocalShadowUserWith 重建 guest 行）：
+// - 幂等：已存在同 id 行 → 不覆盖用户后续改名/改头像（update 分支留空）；唯一
+//   例外是**带 copyPreferencesFrom 的调用**（正向转移）——此时对目标行里仍为空
+//   /默认值的用户级配置列做「仅填空」更新（见 ensureCloudIdentity）；
+// - 唯一冲突不崩：email / username 可能已被本地凭据注册的用户占用（users 两列
+//   都是 @unique），逐个探测后降级——email 降级为 `<cloudUserId>@cloud.local`
+//   （保留云端邮箱会撞 P2002 直接崩登录；清空 email 会让行彻底失联，占位符
+//   至少保留「这是云账号 X」的可追溯性），username 依次降级 name → id → `<id>@cloud`；
+// - password 随机占位（同 desktop-guest / desktop-bootstrap 惯例）：云身份不走
+//   本地凭据登录，凭据比对必失败。
+import { randomUUID } from 'node:crypto'
+import type { Prisma } from '@allbluecn/database'
+
+/** 云端资料（SaaS desktop-callback 下发的身份字段子集） */
+export interface CloudIdentityProfile {
+  id: string
+  name?: string | null
+  email?: string | null
+  avatarConfig?: Record<string, unknown> | null
+  bgShape?: string | null
+  bgColor?: string | null
+}
+
+export interface CloudIdentityResult {
+  /** true = 本次新建了 users 行；false = 行已存在（幂等 no-op） */
+  created: boolean
+  email: string | null
+  username: string | null
+  /** email 因与本地既有用户冲突而降级为占位地址 */
+  emailFallback: boolean
+}
+
+/** 云身份占位邮箱后缀（冲突降级用；不参与邮件投递） */
+const CLOUD_EMAIL_DOMAIN = 'cloud.local'
+
+function placeholderEmail(id: string): string {
+  return `${id}@${CLOUD_EMAIL_DOMAIN}`
+}
+
+async function isEmailTaken(
+  tx: Prisma.TransactionClient,
+  email: string,
+  selfId: string,
+): Promise<boolean> {
+  const row = await tx.user.findUnique({ where: { email }, select: { id: true } })
+  return !!row && row.id !== selfId
+}
+
+async function isUsernameTaken(
+  tx: Prisma.TransactionClient,
+  username: string,
+  selfId: string,
+): Promise<boolean> {
+  const row = await tx.user.findUnique({ where: { username }, select: { id: true } })
+  return !!row && row.id !== selfId
+}
+
+/**
+ * 幂等确保云身份行存在（id = cloudUserId）。
+ *
+ * @param tx 事务客户端（exchange 用独立事务、转移用转移事务——不可传模块单例）
+ * @param profile 云端资料（name/email/avatar 缺省时按 id 兜底）
+ * @param options.copyPreferencesFrom 正向转移传 guest 行 id、反向转移传云行 id：
+ *        新建行时复制该用户的用户级配置列（C3：AI 配置/语言/时区等随身份带走，
+ *        否则 guest 行删除后配置随级联消失）；**已存在行时改为「仅填空」更新**
+ *        （R1：真实绑定链是 exchange 先幂等建行 → 转移这里命中 existing，若直接
+ *        no-op 则 guest 行随后被删、locale/timezone/AI key 等全部丢失）
+ */
+export async function ensureCloudIdentity(
+  tx: Prisma.TransactionClient,
+  profile: CloudIdentityProfile,
+  options: { copyPreferencesFrom?: string } = {},
+): Promise<CloudIdentityResult> {
+  const id = profile.id?.trim()
+  if (!id) throw new Error('[desktop-cloud-identity] 云身份 id 不能为空')
+
+  const existing = await tx.user.findUnique({ where: { id }, select: { id: true } })
+  if (existing) {
+    // update 分支留空语义：已存在即 no-op（幂等，不覆盖用户后续资料）。
+    // 例外：带 copyPreferencesFrom 时对「仍为空/默认值」的配置列做仅填空更新
+    // （真实顺序 = exchange 先建行 → 转移命中 existing；不填则配置随 guest 行删除丢失）。
+    // 不传源（exchange 自建行）时保持纯 no-op——交换阶段没有可复制的源。
+    if (options.copyPreferencesFrom) {
+      await fillMissingPreferences(tx, id, options.copyPreferencesFrom)
+    }
+    return { created: false, email: null, username: null, emailFallback: false }
+  }
+
+  const preferredEmail = profile.email?.trim() || null
+  let email = preferredEmail ?? placeholderEmail(id)
+  let emailFallback = false
+  if (preferredEmail && (await isEmailTaken(tx, preferredEmail, id))) {
+    email = placeholderEmail(id)
+    emailFallback = true
+  }
+
+  const preferredName = profile.name?.trim() || id
+  let username = preferredName
+  if (await isUsernameTaken(tx, username, id)) {
+    username = id
+    if (await isUsernameTaken(tx, username, id)) {
+      username = `${id}@cloud`
+    }
+  }
+
+  const preferences = options.copyPreferencesFrom
+    ? await readUserPreferences(tx, options.copyPreferencesFrom)
+    : {}
+
+  // 用户级配置列按 schema 实际类型（String/Json）展开——统一经 Object.assign
+  // 收口，避免逐列手写可选字段（新增配置列只改 USER_PREFERENCE_COLUMNS）
+  const create = Object.assign(
+    {
+      id,
+      email,
+      username,
+      // 随机占位（非 bcrypt 哈希）：云身份不走本地凭据登录
+      password: randomUUID(),
+      status: 'ACTIVE' as const,
+      avatarConfig: (profile.avatarConfig ?? undefined) as object | undefined,
+      bgShape: profile.bgShape ?? undefined,
+      bgColor: profile.bgColor ?? undefined,
+    },
+    preferences,
+  ) as Prisma.UserUncheckedCreateInput
+
+  await tx.user.upsert({ where: { id }, create, update: {} })
+
+  return { created: true, email, username, emailFallback }
+}
+
+/**
+ * 用户级配置列清单（C3 裁定「AI 配置/偏好随身份翻转」）：
+ * 属「用户偏好 / 个人配置」而非业务数据的 User 标量列——身份翻转（正向
+ * guest→cloud、反向 cloud→guest）时必须随行带走，否则：
+ * ① 正向：guest 行删除后这些配置随行消失（AI key 直接丢）；
+ * ② 反向：云态填的 key 随云行删除消失。
+ *
+ * 口径：schema User 模型中「用户自己填/选的个人配置」列——
+ * aiProvider / aiApiKey / aiModel / aiSourceMode（AI 配置）、locale（语言）、
+ * timezone（时区）、storyDisplayOptions（需求展示偏好）、preferredCurrency
+ * （计费币种）、defaultWorkspaceId（默认工作空间，属主翻转后同一 id 仍有效）。
+ * 不含 role/status/tokenVersion/emailVerified/password（账号安全态，不是偏好）；
+ * 不含 avatarConfig/bgShape/bgColor（身份行创建时由云端资料显式写入）。
+ */
+export const USER_PREFERENCE_COLUMNS = [
+  'aiApiKey',
+  'aiModel',
+  'aiProvider',
+  'aiSourceMode',
+  'defaultWorkspaceId',
+  'locale',
+  'preferredCurrency',
+  'storyDisplayOptions',
+  'timezone',
+] as const
+
+export type UserPreferences = Partial<Record<(typeof USER_PREFERENCE_COLUMNS)[number], unknown>>
+
+/**
+ * 非空配置列的 DB 默认值——与「未设置」等价，可被源值填充（R1「仅填空值」口径）。
+ * 目前仅 preferredCurrency（schema: `String @default("usd")`，列 NOT NULL，读出来
+ * 恒非 null，不特殊处理会永远被视为「已有值」而拒绝填充）。新增非空默认列时同步登记。
+ */
+const PREFERENCE_DEFAULT_VALUES: Partial<Record<(typeof USER_PREFERENCE_COLUMNS)[number], unknown>> = {
+  preferredCurrency: 'usd',
+}
+
+/** 列值是否「空」：null/undefined，或等于该列的 DB 默认值（见 PREFERENCE_DEFAULT_VALUES） */
+function isUnsetPreference(
+  column: (typeof USER_PREFERENCE_COLUMNS)[number],
+  value: unknown,
+): boolean {
+  if (value === undefined || value === null) return true
+  return column in PREFERENCE_DEFAULT_VALUES && value === PREFERENCE_DEFAULT_VALUES[column]
+}
+
+/** 原样读取用户级配置列（含 null——「仅填空」判定需要区分 null 与有值） */
+async function readUserPreferencesRaw(
+  tx: Prisma.TransactionClient,
+  userId: string,
+): Promise<Record<string, unknown> | null> {
+  const select = Object.fromEntries(USER_PREFERENCE_COLUMNS.map((c) => [c, true]))
+  const row = await tx.user.findUnique({
+    where: { id: userId },
+    select: select as Record<(typeof USER_PREFERENCE_COLUMNS)[number], true>,
+  })
+  return (row as Record<string, unknown> | null) ?? null
+}
+
+/** 读取用户级配置列（只取非 null——复制时 null 不覆盖目标行已有值） */
+export async function readUserPreferences(
+  tx: Prisma.TransactionClient,
+  userId: string,
+): Promise<UserPreferences> {
+  const row = await readUserPreferencesRaw(tx, userId)
+  if (!row) return {}
+  const out: UserPreferences = {}
+  for (const col of USER_PREFERENCE_COLUMNS) {
+    const value = row[col]
+    if (value !== undefined && value !== null) out[col] = value
+  }
+  return out
+}
+
+/**
+ * 「仅填空值」把源用户的配置列补到目标用户（R1）。
+ *
+ * 口径：源值非空 且 目标值仍为空/默认值 才写（**绝不覆盖目标已有配置**——
+ * 用户已在云态填过的值优先）。只写真正需要补的列，patch 为空时不发 UPDATE
+ * （保持「已存在即零写入」的幂等可观测性）。返回实际写入的 patch（测试断言用）。
+ */
+async function fillMissingPreferences(
+  tx: Prisma.TransactionClient,
+  targetUserId: string,
+  sourceUserId: string,
+): Promise<UserPreferences> {
+  const source = await readUserPreferences(tx, sourceUserId)
+  if (Object.keys(source).length === 0) return {}
+  const target = await readUserPreferencesRaw(tx, targetUserId)
+  if (!target) return {}
+
+  const patch: Record<string, unknown> = {}
+  for (const col of USER_PREFERENCE_COLUMNS) {
+    const value = source[col]
+    if (value === undefined || value === null) continue
+    if (!isUnsetPreference(col, target[col])) continue
+    if (target[col] === value) continue
+    patch[col] = value
+  }
+  if (Object.keys(patch).length === 0) return {}
+
+  await tx.user.update({ where: { id: targetUserId }, data: patch })
+  return patch as UserPreferences
+}

package/src/server/remote-auth.ts

@@ -30,6 +30,19 @@ export interface RemoteAuthData {
   bgColor?: string
 }
 
+/**
+ * 云账号资料快照（C2：exchange 时从 SaaS profile 落盘，session merge 组装真实
+ * 昵称/邮箱/头像——此前 remote-auth 只存 userId，桌面回落会话恒渲染 UUID）。
+ * add-only：旧文件无此块 → 全部省略，行为与旧版一致（UI 回落首字母/ID）。
+ */
+export interface RemoteAuthProfile {
+  name?: string | null
+  email?: string | null
+  avatarConfig?: Record<string, number> | null
+  bgShape?: string | null
+  bgColor?: string | null
+}
+
 /** 磁盘形态：auth（登录 token）与 session（exchange 后的会话态）分次写入、合并读取 */
 interface RemoteAuthFile {
   token?: string
@@ -38,6 +51,8 @@ interface RemoteAuthFile {
     userId: string
     planName: string
     sessionToken?: string
+    /** C2 云资料（add-only；缺省 = 旧版文件） */
+    profile?: RemoteAuthProfile
   }
 }
 
@@ -121,11 +136,18 @@ export async function readRemoteAuth(): Promise<RemoteAuthData | null> {
   if (process.env.DEPLOY_TARGET !== 'desktop') return null
   const data = await readFile()
   if (!data?.session?.userId) return null
+  const profile = data.session.profile
   return {
     userId: data.session.userId,
     planName: data.session.planName,
     features: {},
     sessionToken: data.session.sessionToken ?? data.sessionToken,
+    // C2：云资料透传（旧文件无 profile → 全 undefined，回落旧行为）
+    username: profile?.name ?? undefined,
+    email: profile?.email ?? undefined,
+    avatarConfig: profile?.avatarConfig ?? undefined,
+    bgShape: profile?.bgShape ?? undefined,
+    bgColor: profile?.bgColor ?? undefined,
   }
 }
 
@@ -144,11 +166,21 @@ export async function writeRemoteSession(
   userId: string,
   planName: string,
   sessionToken?: string,
+  profile?: RemoteAuthProfile,
 ): Promise<void> {
   if (process.env.DEPLOY_TARGET !== 'desktop') return
   try {
     const prev = (await readFile()) ?? {}
-    await writeFile({ ...prev, session: { userId, planName, sessionToken } })
+    await writeFile({
+      ...prev,
+      // profile 省略时保留既有块（writeRemoteAuth 等后续写入不回退资料）
+      session: {
+        userId,
+        planName,
+        sessionToken,
+        ...(profile ? { profile } : prev.session?.profile ? { profile: prev.session.profile } : {}),
+      },
+    })
   } catch (e) {
     console.warn('[remote-auth] write_remote_session 失败（本地会话态未更新）:', e instanceof Error ? e.message : String(e))
   }

package/src/server/serverFns/auth/session.ts

@@ -19,10 +19,12 @@ import { createServerFn } from '@tanstack/react-start'
 import { z } from 'zod'
 import { getRequest } from '@tanstack/react-start/server'
 import type { FeatureKey } from '@allbluecn/kernel'
+import { getPrisma } from '@allbluecn/database/get-prisma'
 import { getCurrentSession } from '@/lib/session'
 import { resetProfileCache } from '@/lib/auth/auth.config'
 import { buildGuestSession, isDesktopServer } from '@/server/desktop-guest'
 import { ensureLocalShadowUser } from '@/server/desktop-bootstrap'
+import { ensureCloudIdentity } from '@/server/desktop-cloud-identity'
 import { readRemoteAuth, writeRemoteAuth, writeRemoteSession, clearRemoteAuth } from '@/server/remote-auth'
 import { generateEntitlementsToken } from '@/server/entitlements-token'
 import { buildRemoteSession } from '@/server/desktop-session-merge'
@@ -125,12 +127,35 @@ export const exchangeRemoteTokenFn = createServerFn({ method: 'POST' })
       })
     }
 
+    // 云身份自洽（C2 / 裁定 R3）：先幂等落本地 users 行（id = 云 userId）——
+    // 否则云会话激活后按 cloudUserId 的列表全空、写入撞 P2003、同步 scope 解析
+    // 不到任何行。放在 remote-auth 落盘之前：建行失败则整个 exchange 失败，
+    // renderer 走回滚路径，绝不留下「已激活但无身份行」的坏态。
+    const prisma = await getPrisma()
+    await prisma.$transaction((tx) =>
+      ensureCloudIdentity(tx, {
+        id: profile.user.id,
+        name: profile.user.name,
+        email: profile.user.email,
+        avatarConfig: profile.user.avatarConfig,
+        bgShape: profile.user.bgShape,
+        bgColor: profile.user.bgColor,
+      }),
+    )
+
     // session 块双路径无条件落盘（A10 修复，控制者核实的激活缺口）：readRemoteAuth
     // 以 data.session.userId 为登录态唯一依据，原先仅降级路径写 session——生产
     // SaaS 恒发 signedToken，signedToken 路径云身份 100% 不激活、云态写入属主错
     // 为 guest。writeRemoteSession / writeRemoteAuth 均 merge 语义（{...prev,
-    // ...}），先 session 后 token 不互踩。
-    await writeRemoteSession(profile.user.id, planName, token)
+    // ...}），先 session 后 token 不互踩。profile 一并落盘（C2）：桌面回落会话
+    // 由此组装真实昵称/邮箱/头像，不再回落 UUID。
+    await writeRemoteSession(profile.user.id, planName, token, {
+      name: profile.user.name,
+      email: profile.user.email,
+      avatarConfig: profile.user.avatarConfig,
+      bgShape: profile.user.bgShape,
+      bgColor: profile.user.bgColor,
+    })
     if (!signedToken) {
       console.warn('[exchangeRemoteTokenFn] 无法签发权益 token（缺少 ENTITLEMENTS_SIGNING_SECRET），降级 OSS')
       return { success: true, userId: profile.user.id, planName, degraded: true }