@allbluecn/web-app 0.23.6 → 0.23.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allbluecn/web-app",
-  "version": "0.23.6",
+  "version": "0.23.7",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [

package/src/components/layout/sidebar-03/__tests__/user-menu-cloud-logout.test.tsx

@@ -0,0 +1,185 @@
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import type React from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// 桌面登出分支回归哨兵（A9 反向转移编排 + 会话来源判别）：
+// /api/auth/session 改为会回落桌面身份并带 desktopSession 标记后，clientSession
+// 不再为空——旧判据 `bridge && !clientSession` 会把云态登出错走成 authjs signOut
+// （数据留在云属主，桌面再也回不到 guest）。本文件钉死三条分支与编排顺序：
+// ① desktopSession=guest → 本地 guest 登出（不反向转移）
+// ② 无标记（本地 authjs 凭据登录）→ signOut（不反向转移）
+// ③ desktopSession=cloud → 反向转移编排（lock begin → reverse → clear → lock end）
+const H = vi.hoisted(() => ({
+  reload: vi.fn(),
+  queryClient: { clear: vi.fn(), resetQueries: vi.fn() },
+  reverseTransferOwnershipFn: vi.fn(async () => ({ tables: 1, rows: 1 })),
+  logoutRemoteFn: vi.fn(async () => ({ success: true })),
+  signOut: vi.fn(async () => ({ success: true })),
+  transferLock: vi.fn(async (_action?: 'begin' | 'end') => ({ ok: true })),
+  clearCloudSession: vi.fn(async () => ({ ok: true })),
+  // 由各用例覆盖：useSession() 的返回值
+  session: null as unknown,
+}))
+
+const CLOUD_SESSION = {
+  user: { id: 'cloud-1', name: '云用户', email: 'cloud@example.com', role: 'USER', isGuest: false },
+  expires: 'never',
+  desktopSession: 'cloud' as const,
+}
+const GUEST_SESSION = {
+  user: { id: 'local-guest', name: '本地用户', email: 'guest@localhost', role: 'USER', isGuest: true },
+  expires: 'never',
+  desktopSession: 'guest' as const,
+}
+const LOCAL_CREDENTIAL_SESSION = {
+  user: { id: 'authjs-user-1', name: '本地账号', email: 'local@example.com', role: 'USER', isGuest: false },
+  expires: '2026-12-31T00:00:00.000Z',
+}
+
+vi.mock('@/lib/auth/auth-client', () => ({
+  useSession: () => ({ data: H.session }),
+  signOut: H.signOut,
+}))
+vi.mock('@/lib/query-client-seam', () => ({
+  getQueryClient: () => H.queryClient,
+}))
+vi.mock('@/components/ui/sidebar', () => ({
+  SidebarMenu: ({ children }: { children?: React.ReactNode }) => <ul>{children}</ul>,
+  SidebarMenuItem: ({ children }: { children?: React.ReactNode }) => <li>{children}</li>,
+  SidebarMenuButton: ({ children, onClick }: { children?: React.ReactNode; onClick?: () => void }) => (
+    <button onClick={onClick}>{children}</button>
+  ),
+  useSidebar: () => ({ isMobile: false }),
+}))
+vi.mock('@/components/ui/toast', () => ({ toast: { success: vi.fn(), error: vi.fn(), info: vi.fn() } }))
+vi.mock('@/server/serverFns/auth/session', () => ({ logoutRemoteFn: H.logoutRemoteFn }))
+vi.mock('@/server/serverFns/sync/transfer', () => ({
+  reverseTransferOwnershipFn: H.reverseTransferOwnershipFn,
+}))
+vi.mock('@/lib/desktop-bridge-types', () => ({
+  getDesktopBridge: () => ({
+    transferLock: H.transferLock,
+    clearCloudSession: H.clearCloudSession,
+  }),
+}))
+vi.mock('@/components/shared-kit', () => ({
+  UserAvatar: ({ name }: { name?: string }) => <div data-testid="avatar">{name}</div>,
+}))
+vi.mock('@/components/magicui/sparkles-text', () => ({
+  SparklesText: ({ children }: { children?: React.ReactNode }) => <span>{children}</span>,
+}))
+vi.mock('@/components/ui/dropdown-menu', () => ({
+  DropdownMenu: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  DropdownMenuTrigger: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  DropdownMenuContent: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  DropdownMenuGroup: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  DropdownMenuItem: ({ children, onClick }: { children?: React.ReactNode; onClick?: () => void }) => (
+    <button type="button" onClick={onClick}>
+      {children}
+    </button>
+  ),
+  DropdownMenuLabel: ({ children }: { children?: React.ReactNode }) => <div>{children}</div>,
+  DropdownMenuSeparator: () => null,
+}))
+vi.mock('@tanstack/react-router', () => ({
+  useRouter: () => ({
+    navigate: vi.fn(),
+    state: { location: { pathname: '/dashboard', searchStr: '' } },
+  }),
+  useMatches: () => [],
+}))
+
+async function clickLogout() {
+  const { UserMenu } = await import('../user-menu')
+  render(<UserMenu />)
+  fireEvent.click(screen.getByText('退出登录'))
+}
+
+/** transferLock 某次调用的 invocationCallOrder（未调用 → -1） */
+function lockOrder(action: 'begin' | 'end'): number {
+  const idx = H.transferLock.mock.calls.findIndex((call) => call[0] === action)
+  return H.transferLock.mock.invocationCallOrder[idx] ?? -1
+}
+
+describe('UserMenu 桌面登出分支', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    try {
+      Object.defineProperty(window, 'location', {
+        configurable: true,
+        value: { ...window.location, reload: H.reload },
+      })
+    } catch {
+      /* jsdom 限制：后续断言只看转移链路 */
+    }
+  })
+
+  afterEach(() => {
+    cleanup()
+  })
+
+  it('③ desktopSession=cloud：走反向转移编排，不走 authjs signOut，最后整页 reload', async () => {
+    H.session = CLOUD_SESSION
+    await clickLogout()
+
+    await waitFor(() => {
+      expect(H.reverseTransferOwnershipFn).toHaveBeenCalledWith({ data: { cloudUserId: 'cloud-1' } })
+    })
+    expect(H.clearCloudSession).toHaveBeenCalledTimes(1)
+    expect(H.logoutRemoteFn).toHaveBeenCalledWith({ data: {} })
+    expect(H.queryClient.clear).toHaveBeenCalledTimes(1)
+    expect(H.signOut).not.toHaveBeenCalled()
+    // ④ 整页 reload（reload 后 getSessionFn 回落 guest 会话）
+    expect(H.reload).toHaveBeenCalledTimes(1)
+  }, 20000)
+
+  it('③ 编排顺序：lock begin → reverse → clearCloudSession → lock end → reload', async () => {
+    H.session = CLOUD_SESSION
+    await clickLogout()
+
+    await waitFor(() => {
+      expect(H.reload).toHaveBeenCalledTimes(1)
+    })
+
+    const begin = lockOrder('begin')
+    const end = lockOrder('end')
+    const reverse = H.reverseTransferOwnershipFn.mock.invocationCallOrder[0]!
+    const clear = H.clearCloudSession.mock.invocationCallOrder[0]!
+    const reload = H.reload.mock.invocationCallOrder[0]!
+
+    expect(begin).toBeGreaterThan(0)
+    expect(begin).toBeLessThan(reverse)
+    expect(reverse).toBeLessThan(clear)
+    // 先清云会话再解锁：引擎恢复 tick 前云会话必须已不可用
+    expect(clear).toBeLessThan(end)
+    expect(end).toBeLessThan(reload)
+  }, 20000)
+
+  it('① desktopSession=guest（local-guest）：本地 guest 登出，不触发反向转移', async () => {
+    H.session = GUEST_SESSION
+    await clickLogout()
+
+    await waitFor(() => {
+      expect(H.logoutRemoteFn).toHaveBeenCalledWith({ data: {} })
+    })
+    expect(H.reverseTransferOwnershipFn).not.toHaveBeenCalled()
+    expect(H.transferLock).not.toHaveBeenCalled()
+    expect(H.clearCloudSession).not.toHaveBeenCalled()
+    expect(H.queryClient.resetQueries).toHaveBeenCalled()
+    expect(H.reload).toHaveBeenCalledTimes(1)
+    expect(H.signOut).not.toHaveBeenCalled()
+  }, 20000)
+
+  it('② 本地 authjs 凭据登录（无 desktopSession 标记）：走 signOut，不触发反向转移', async () => {
+    H.session = LOCAL_CREDENTIAL_SESSION
+    await clickLogout()
+
+    await waitFor(() => {
+      expect(H.signOut).toHaveBeenCalledTimes(1)
+    })
+    expect(H.reverseTransferOwnershipFn).not.toHaveBeenCalled()
+    expect(H.transferLock).not.toHaveBeenCalled()
+    expect(H.clearCloudSession).not.toHaveBeenCalled()
+    expect(H.reload).not.toHaveBeenCalled()
+  }, 20000)
+})

package/src/components/layout/sidebar-03/user-menu.tsx

@@ -23,11 +23,10 @@ import {
   Settings,
   Users,
 } from "lucide-react";
-import type { QueryClient } from "@tanstack/react-query";
 import { logoutRemoteFn } from '@/server/serverFns/auth/session'
 import { reverseTransferOwnershipFn } from '@/server/serverFns/sync/transfer'
 import { getDesktopBridge } from '@/lib/desktop-bridge-types'
-import type { DesktopBridgeApi } from '@/lib/desktop-bridge-types'
+import { runDesktopLogout } from '@/lib/desktop-logout'
 import { toast } from '@/components/ui/toast'
 
 import {
@@ -54,53 +53,29 @@ import { SparklesText } from "@/components/magicui/sparkles-text";
 import { m } from "@/paraglide/messages.js";
 
 /**
- * 桌面云态登出（桌面本地优先 P2-A9 反向转移编排，裁定顺序）：登出 = 把云身份名下
- * 数据翻回 guest（数据保留本机），双会话清理后回到 guest 态。
- * ① 置转移锁（transferLock，复用 bind 锁文件——引擎每 tick 判定同源，「转移进行中
- *   引擎勿 tick」；旧壳无此 IPC 优雅降级：反向转移单事务自身原子，锁为双保险）；
- * ② reverseTransferOwnershipFn（serverFn：校验 remoteAuth/会话本人 → 单事务
- *   cloud→guest + outbox/row_state 同事务清空防反向 op 上云 + 重建 guest 行；
- *   事务提交后 server 侧已清 remote-auth——崩窗口收敛，A8b 发现 2 的镜像）；
- * ③ 双会话清理：logoutRemoteFn（幂等 re-clear remote-auth）+ clearCloudSession
- *   （清 cloud-session.json，引擎 guest 守卫回 idle）→ 清锁（先清云会话再解锁，
- *   引擎恢复 tick 前云会话已不可用）；
- * ④ queryClient.clear() + 整页 reload——reload 后 getSessionFn 回落 guest 会话。
- * 失败路径（锁失败 / 转移失败）：解锁 + toast sync_logout_failed + 不 reload（留在
- * 云态可重试；转移失败单事务已回滚，数据仍是云属主，重试幂等）。模块内局部函数
- * （非导出）：本文件唯一导出是 UserMenu 组件，勿破坏 Fast Refresh 纯组件边界。
+ * 桌面云态登出（P2-A9 反向转移）：编排本体在 `@/lib/desktop-logout`（可测纯函数，
+ * 失败路径/调用顺序由单测钉死），此处只做**依赖装配**——bridge IPC、serverFn、
+ * queryClient 清空与整页 reload。顺序与失败语义见该模块文件头注释。
  */
 async function desktopCloudLogout(
-  bridge: DesktopBridgeApi,
+  bridge: NonNullable<ReturnType<typeof getDesktopBridge>>,
   cloudUserId: string,
-  queryClient: QueryClient,
+  queryClient: { clear: () => void },
 ): Promise<void> {
-  toast.info(m.sync_logout_in_progress());
-  // ① 转移锁
-  let lock: { ok: boolean; error?: string } = { ok: true };
-  try {
-    lock = bridge.transferLock ? await bridge.transferLock("begin") : { ok: true };
-  } catch {
-    lock = { ok: false };
-  }
-  if (!lock.ok) {
-    toast.error(m.sync_logout_failed());
-    return;
-  }
-  // ② 反向转移（失败：单事务回滚留在云态，解锁可重试）
-  try {
-    await reverseTransferOwnershipFn({ data: { cloudUserId } });
-  } catch {
-    try { await bridge.transferLock?.("end"); } catch { /* 尽力而为 */ }
-    toast.error(m.sync_logout_failed());
-    return;
-  }
-  // ③ 双会话清理（均幂等 best-effort：serverFn 已清 remote-auth，此处兜底）
-  try { await logoutRemoteFn({ data: {} }); } catch { /* 尽力而为 */ }
-  try { await bridge.clearCloudSession?.(); } catch { /* 尽力而为 */ }
-  try { await bridge.transferLock?.("end"); } catch { /* 尽力而为 */ }
-  // ④ 缓存清空 + 整页刷新（reload 后 desktop-state 回 guest）
-  queryClient.clear();
-  window.location.reload();
+  await runDesktopLogout(cloudUserId, {
+    // 旧壳无 transferLock IPC：省略 = 置锁成功 / 解锁 no-op（反向转移单事务自身原子）
+    lock: bridge.transferLock ? () => bridge.transferLock!("begin") : undefined,
+    unlock: bridge.transferLock ? () => bridge.transferLock!("end") : undefined,
+    transfer: (id) => reverseTransferOwnershipFn({ data: { cloudUserId: id } }),
+    logoutRemote: () => logoutRemoteFn({ data: {} }),
+    clearCloudSession: bridge.clearCloudSession ? () => bridge.clearCloudSession!() : undefined,
+    clearQueries: () => queryClient.clear(),
+    reload: () => window.location.reload(),
+    notify: (notice) => {
+      if (notice === "in-progress") toast.info(m.sync_logout_in_progress());
+      else toast.error(m.sync_logout_failed());
+    },
+  });
 }
 
 export function UserMenu() {
@@ -137,12 +112,14 @@ export function UserMenu() {
       window.location.reload();
       return;
     }
-    // 桌面云态（A9）：桌面壳存在且无本地 authjs 会话（clientSession 为空）＝当前
-    // 会话是 remote-auth 回落的轻量云身份，登出走反向转移编排（数据翻回 guest）。
-    // 本地凭据登录（clientSession 非空）与 web 照旧走 signOut 链——云身份回落仅在
-    // authjs 会话无效时生效，clientSession 为空是云态判别式。
+    // 桌面云态（A9）：桌面壳存在且会话来自云端回落＝当前身份是 remote-auth
+    // 的轻量云身份，登出走反向转移编排（数据翻回 guest）。
+    // 判据演进（桌面 guest 会话修复）：/api/auth/session 现会回落桌面身份并在
+    // 响应里带 desktopSession 标记，clientSession 不再为空——以标记为准；旧后端
+    // （无标记）保留「clientSession 为空」兜底。本地 authjs 凭据登录（无标记、
+    // clientSession 非空）与 web 照旧走 signOut 链。
     const bridge = getDesktopBridge();
-    if (bridge && !clientSession && user?.id) {
+    if (bridge && (!clientSession || clientSession.desktopSession === 'cloud') && user?.id) {
       await desktopCloudLogout(bridge, user.id, queryClient);
       return;
     }

package/src/components/shared-kit/auth/auth-client.ts

@@ -36,6 +36,10 @@ export interface Session {
     timezone?: string | null
   }
   expires: string
+  /** 桌面端会话来源标记（仅 /api/auth/session 的桌面回落响应携带）：
+   *  guest = 本地影子用户，cloud = remote-auth 云身份。web 部署与本地
+   *  authjs 凭据登录无此字段——云态登出编排（user-menu）据此区分二者。 */
+  desktopSession?: 'guest' | 'cloud'
 }
 
 export function useSession() {

package/src/lib/__tests__/desktop-logout.test.ts

@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 桌面云态登出编排单测（A9 反向转移）：钉死调用顺序与失败路径语义。
+// 编排是纯依赖注入函数（无 React / i18n / DOM），此处全部替身驱动，测的是
+// 「顺序、短路、best-effort 不阻塞」三件事，而不是各依赖自身实现。
+import { describe, expect, it, vi } from 'vitest'
+import { runDesktopLogout, type DesktopLogoutDeps } from '../desktop-logout'
+
+type Log = string[]
+
+/** 记录调用顺序的替身工厂（同一 Log 数组串起全部依赖） */
+function makeDeps(
+  log: Log,
+  overrides: Partial<DesktopLogoutDeps> = {},
+): DesktopLogoutDeps {
+  return {
+    lock: async () => {
+      log.push('lock')
+      return { ok: true }
+    },
+    transfer: async (userId) => {
+      log.push(`transfer:${userId}`)
+    },
+    logoutRemote: async () => {
+      log.push('logoutRemote')
+    },
+    clearCloudSession: async () => {
+      log.push('clearCloudSession')
+    },
+    unlock: async () => {
+      log.push('unlock')
+    },
+    clearQueries: () => {
+      log.push('clearQueries')
+    },
+    reload: () => {
+      log.push('reload')
+    },
+    ...overrides,
+  }
+}
+
+describe('runDesktopLogout —— 成功路径', () => {
+  it('调用顺序严格：lock → transfer → logoutRemote → clearCloudSession → unlock → clearQueries → reload', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout('cloud-user-1', makeDeps(log))
+
+    expect(status).toBe('done')
+    expect(log).toEqual([
+      'lock',
+      'transfer:cloud-user-1',
+      'logoutRemote',
+      'clearCloudSession',
+      'unlock',
+      'clearQueries',
+      'reload',
+    ])
+  })
+
+  it('notify 先发 in-progress，成功路径不发 failed', async () => {
+    const notices: string[] = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps([], { notify: (n) => notices.push(n) }),
+    )
+
+    expect(status).toBe('done')
+    expect(notices).toEqual(['in-progress'])
+  })
+
+  it('旧壳（无 transferLock / clearCloudSession IPC）：缺省即视为成功，仍走完并 reload', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        lock: undefined,
+        unlock: undefined,
+        clearCloudSession: undefined,
+      }),
+    )
+
+    expect(status).toBe('done')
+    expect(log).toEqual(['transfer:u', 'logoutRemote', 'clearQueries', 'reload'])
+  })
+})
+
+describe('runDesktopLogout —— 失败路径（留在云态可重试）', () => {
+  it('置锁返回 ok=false → 不转移、不 reload，通知 failed', async () => {
+    const log: Log = []
+    const notices: string[] = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        lock: async () => ({ ok: false, error: 'locked' }),
+        notify: (n) => notices.push(n),
+      }),
+    )
+
+    expect(status).toBe('lock-failed')
+    expect(log).toEqual([])
+    expect(notices).toEqual(['in-progress', 'failed'])
+  })
+
+  it('置锁抛错 → 与 ok=false 同判（不转移、不 reload）', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        lock: async () => {
+          throw new Error('ipc down')
+        },
+      }),
+    )
+
+    expect(status).toBe('lock-failed')
+    expect(log).toEqual([])
+  })
+
+  it('转移失败 → 尽力解锁 + 通知 failed + 不 reload、不清缓存、不清双会话（保留云态可重试）', async () => {
+    const log: Log = []
+    const notices: string[] = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        transfer: async () => {
+          log.push('transfer')
+          throw new Error('transfer failed')
+        },
+        notify: (n) => notices.push(n),
+      }),
+    )
+
+    expect(status).toBe('transfer-failed')
+    expect(log).toEqual(['lock', 'transfer', 'unlock'])
+    expect(notices).toEqual(['in-progress', 'failed'])
+  })
+
+  it('转移失败且解锁也抛错 → 不误报状态、不 reload', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        transfer: async () => {
+          throw new Error('transfer failed')
+        },
+        unlock: async () => {
+          log.push('unlock')
+          throw new Error('unlock failed')
+        },
+      }),
+    )
+
+    expect(status).toBe('transfer-failed')
+    expect(log).toEqual(['lock', 'unlock'])
+  })
+})
+
+describe('runDesktopLogout —— best-effort 不阻塞（既有实现语义）', () => {
+  it('解锁抛错 → 仍有 clearQueries + reload（reload 后引擎按 guest 守卫重判）', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        unlock: async () => {
+          log.push('unlock')
+          throw new Error('unlock failed')
+        },
+      }),
+    )
+
+    expect(status).toBe('done')
+    expect(log).toEqual([
+      'lock',
+      'transfer:u',
+      'logoutRemote',
+      'clearCloudSession',
+      'unlock',
+      'clearQueries',
+      'reload',
+    ])
+  })
+
+  it('清云会话失败 → 不阻塞解锁 / 清缓存 / reload', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        clearCloudSession: async () => {
+          log.push('clearCloudSession')
+          throw new Error('clear failed')
+        },
+      }),
+    )
+
+    expect(status).toBe('done')
+    expect(log.slice(-4)).toEqual(['clearCloudSession', 'unlock', 'clearQueries', 'reload'])
+    expect(log).toContain('clearQueries')
+  })
+
+  it('清 remote-auth 失败 → 不阻塞后续（云会话清理由 serverFn 侧完成）', async () => {
+    const log: Log = []
+    const status = await runDesktopLogout(
+      'u',
+      makeDeps(log, {
+        logoutRemote: async () => {
+          log.push('logoutRemote')
+          throw new Error('logout remote failed')
+        },
+      }),
+    )
+
+    expect(status).toBe('done')
+    expect(log.slice(-3)).toEqual(['unlock', 'clearQueries', 'reload'])
+  })
+})
+
+describe('runDesktopLogout —— 依赖调用次数', () => {
+  it('成功路径每个依赖恰好一次；notify 只在最前发一次 in-progress', async () => {
+    const spy = {
+      lock: vi.fn(async () => ({ ok: true })),
+      transfer: vi.fn(async () => undefined),
+      logoutRemote: vi.fn(async () => undefined),
+      clearCloudSession: vi.fn(async () => ({ ok: true })),
+      unlock: vi.fn(async () => undefined),
+      clearQueries: vi.fn(),
+      reload: vi.fn(),
+      notify: vi.fn(),
+    }
+    await runDesktopLogout('cloud', spy)
+
+    for (const fn of [spy.lock, spy.transfer, spy.logoutRemote, spy.clearCloudSession, spy.unlock, spy.clearQueries, spy.reload]) {
+      expect(fn).toHaveBeenCalledTimes(1)
+    }
+    expect(spy.notify).toHaveBeenCalledTimes(1)
+    expect(spy.notify).toHaveBeenCalledWith('in-progress')
+  })
+})

package/src/lib/__tests__/session.test.ts

@@ -8,7 +8,7 @@
 // 不触真实 JWT 解密、不真读写 DESKTOP_USER_DATA_DIR 下的 remote-auth.json
 // （#578 fs 实现勿真写盘）。desktop 判定走 DEPLOY_TARGET env stub
 // （isDesktopServer 调用时读 env，见 desktop-guest.ts:40）。
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { getCurrentSession } from '../session'
 import type { Session } from '../session'
 
@@ -45,6 +45,11 @@ const REMOTE_AUTH = {
 const REQ = () => new Request('http://localhost/api/auth/session')
 
 describe('getCurrentSession 桌面回落（A10 优先级链）', () => {
+  beforeEach(() => {
+    // 真实桌面后端由 Electron 主进程注入该 env（fail-open 自检的正常路径）
+    vi.stubEnv('DESKTOP_USER_DATA_DIR', '/tmp/allblue-desktop-test')
+  })
+
   afterEach(() => {
     vi.unstubAllEnvs()
     vi.clearAllMocks()
@@ -72,10 +77,45 @@ describe('getCurrentSession 桌面回落（A10 优先级链）', () => {
     expect(session?.expires).toBe('never')
   })
 
-  it('①c authjs 无效 + desktop + remoteAuth 无 → null', async () => {
+  it('①c authjs 无效 + desktop + remoteAuth 无 → guest 本地影子身份（桌面免登录）', async () => {
     vi.stubEnv('DEPLOY_TARGET', 'desktop')
     getSessionMock.mockResolvedValue(null)
     readRemoteAuthMock.mockResolvedValue(null)
+    const session = await getCurrentSession(REQ())
+    // 桌面端不存在「未登录」态：guest 是本地合法身份，必须在本鉴权单点补齐
+    // （否则 account-team / design-detail 等软鉴权端点把 guest 判成未登录 →
+    // 路由 beforeLoad 收 unauthorized → 自动跳 /login，实测 P0）
+    expect(session?.user?.id).toBe('local-guest')
+    expect(session?.user?.isGuest).toBe(true)
+    expect(session?.expires).toBe('never')
+  })
+
+  it('①d authjs 读取出错 + desktop + remoteAuth 有 → 先回落云身份（不静默降级 guest）', async () => {
+    vi.stubEnv('DEPLOY_TARGET', 'desktop')
+    getSessionMock.mockRejectedValue(new Error('JWTSessionError'))
+    readRemoteAuthMock.mockResolvedValue(REMOTE_AUTH)
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const session = await getCurrentSession(REQ())
+    // cloud 态遇坏 cookie / AUTH_SECRET 轮换：必须保住云身份归属——若直接回 guest，
+    // 界面看起来「数据全空」，期间写入还会落到 local-guest 属主（错主不可逆）
+    expect(session?.user?.id).toBe('cloud-user-abc')
+    expect(session?.user?.isGuest).toBe(false)
+    expect(readRemoteAuthMock).toHaveBeenCalled()
+  })
+
+  it('①e authjs 读取出错 + desktop + remoteAuth 无 → 回落 guest，本地不掉线', async () => {
+    vi.stubEnv('DEPLOY_TARGET', 'desktop')
+    getSessionMock.mockRejectedValue(new Error('JWTSessionError'))
+    readRemoteAuthMock.mockResolvedValue(null)
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const session = await getCurrentSession(REQ())
+    expect(session?.user?.id).toBe('local-guest')
+  })
+
+  it('①f authjs 读取出错 + 非 desktop → null（web 未登录语义不变）', async () => {
+    vi.stubEnv('DEPLOY_TARGET', '')
+    getSessionMock.mockRejectedValue(new Error('JWTSessionError'))
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
     expect(await getCurrentSession(REQ())).toBeNull()
   })
 
@@ -93,3 +133,46 @@ describe('getCurrentSession 桌面回落（A10 优先级链）', () => {
     expect(readRemoteAuthMock).not.toHaveBeenCalled()
   })
 })
+
+describe('桌面 guest 回落的安全自检（fail-open 告警，进程级一次）', () => {
+  // 模块级 warn-once 标记随实例存在：每个用例用 resetModules + 动态 import
+  // 拿全新实例，否则第二条会被前一条的标记吞掉
+  async function importFreshSession(env: { desktopUserDataDir?: string }) {
+    vi.resetModules()
+    vi.stubEnv('DEPLOY_TARGET', 'desktop')
+    vi.stubEnv('DESKTOP_USER_DATA_DIR', env.desktopUserDataDir ?? '')
+    vi.doMock('start-authjs', () => ({ getSession: async () => null }))
+    vi.doMock('@/lib/auth/auth.config', () => ({ getAuthConfig: async () => ({}) }))
+    vi.doMock('@/server/remote-auth', () => ({ readRemoteAuth: async () => null }))
+    return import('../session')
+  }
+
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.restoreAllMocks()
+  })
+
+  it('DEPLOY_TARGET=desktop 且无 DESKTOP_USER_DATA_DIR → console.error 一次（cloud 部署误设信号）', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const { getCurrentSession: fresh } = await importFreshSession({})
+    expect((await fresh(REQ()))?.user?.id).toBe('local-guest')
+    expect((await fresh(REQ()))?.user?.id).toBe('local-guest')
+
+    const securityAlerts = errorSpy.mock.calls.filter((args) => String(args[0]).includes('DESKTOP_USER_DATA_DIR'))
+    expect(securityAlerts).toHaveLength(1)
+    expect(String(securityAlerts[0]?.[0])).toContain('安全边界')
+  })
+
+  it('已注入 DESKTOP_USER_DATA_DIR（正常桌面壳）→ 不告警', async () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const { getCurrentSession: fresh } = await importFreshSession({ desktopUserDataDir: '/tmp/allblue-desktop' })
+    expect((await fresh(REQ()))?.user?.id).toBe('local-guest')
+
+    const securityAlerts = errorSpy.mock.calls.filter((args) => String(args[0]).includes('DESKTOP_USER_DATA_DIR'))
+    expect(securityAlerts).toHaveLength(0)
+  })
+})