@allbluecn/web-app 0.22.4 → 0.23.1

package/src/components/layout/sidebar-03/nav-knowledge.tsx

@@ -65,9 +65,8 @@ import {
   LibraryBig,
   PinOff,
 } from "lucide-react";
-import { Link, useLocation } from "@tanstack/react-router";
+import { Link } from "@tanstack/react-router";
 import { cn } from "@/lib/utils";
-import { isParentActive } from "@/lib/sidebar-utils";
 import { useEffect, useState } from "react";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { KNOWLEDGE_BASES_QUERY_KEY } from "@/lib/collections/query-keys";
@@ -184,7 +183,7 @@ function UnpinButton({ kb }: { kb: KnowledgeItem }) {
   );
 }
 
-function KnowledgeBaseLinks({ pathname }: { pathname: string }) {
+function KnowledgeBaseLinks() {
   // useQuery 直读 per-request queryClient（_nav loader 已 SSR 预取），
   // 列表随 SSR HTML 直出，刷新无需等待；避免 module-level collection 的跨请求泄漏
   const { data: items } = useQuery({
@@ -202,12 +201,13 @@ function KnowledgeBaseLinks({ pathname }: { pathname: string }) {
     <SidebarMenu className="space-y-1">
       {pinnedItems.map((item) => {
         const Icon = ICON_MAP[item.icon] || NotebookPen;
-        const itemActive = pathname.startsWith(`/knowledge/${item.id}`);
         return (
           <SidebarMenuItem key={item.id} className="group/kb relative">
+            {/* 默认模糊匹配（段边界前缀）等价原 pathname.startsWith(`/knowledge/${item.id}`)，
+                且不误伤 id 互为字符串前缀的知识库；activeProps data-active 走 Link 自身激活判定 */}
             <SidebarMenuButton render={<Link to={"/knowledge/$kbId" as any}
                 params={{ kbId: item.id } as any}
-                className="flex w-full items-center" />} tooltip={item.name} isActive={itemActive} className="flex w-full items-center rounded-lg px-2">
+                className="flex w-full items-center" activeProps={{ 'data-active': '' }} activeOptions={{ includeSearch: false }} />} tooltip={item.name} className="flex w-full items-center rounded-lg px-2">
                 <Icon className="size-4 mr-2 shrink-0" />
                 <span className="text-sm font-medium truncate">{item.name}</span>
               </SidebarMenuButton>
@@ -221,12 +221,10 @@ function KnowledgeBaseLinks({ pathname }: { pathname: string }) {
 
 export function NavKnowledge() {
   const { state } = useSidebar();
-  const { pathname } = useLocation();
   const isCollapsed = state === "collapsed";
   const [open, setOpen] = useState(false);
   const [createOpen, setCreateOpen] = useState(false);
   const queryClient = useQueryClient();
-  const active = isParentActive(pathname, "/knowledge");
 
   useEffect(() => {
     const refresh = () => {
@@ -268,8 +266,10 @@ export function NavKnowledge() {
         <SidebarMenu>
           <SidebarMenuItem>
             <div className="relative">
+              {/* 精确匹配（activeOptions.exact）保持原 isParentActive（pathname === "/knowledge"）口径；
+                  activeProps data-active 走 Link 自身激活判定，includeSearch:false 保持纯 pathname 口径 */}
               <SidebarMenuButton render={<Link to={("/knowledge" as any)}
-                  className="flex w-full items-center" />} tooltip={m.common_sidebar_knowledge_title()} isActive={active} className={cn(
+                  className="flex w-full items-center" activeProps={{ 'data-active': '' }} activeOptions={{ exact: true, includeSearch: false }} />} tooltip={m.common_sidebar_knowledge_title()} className={cn(
                   "flex w-full items-center rounded-lg px-2 pr-9",
                   isCollapsed && "justify-center"
                 )}>
@@ -302,11 +302,11 @@ export function NavKnowledge() {
             <SidebarMenuSub className="my-1 ml-3.5">
               {systemRoutes.map((route) => {
                 const Icon = route.icon;
-                const subActive = pathname === route.link;
                 return (
                   <SidebarMenuSubItem key={route.id} className="h-auto">
+                    {/* 精确匹配（activeOptions.exact）保持原 pathname === route.link 口径 */}
                     <SidebarMenuSubButton render={<Link to={route.link}
-                        className="flex items-center rounded-md w-50 py-1.5 text-sm font-medium" />} isActive={subActive}>
+                        className="flex items-center rounded-md w-50 py-1.5 text-sm font-medium" activeProps={{ 'data-active': '' }} activeOptions={{ exact: true, includeSearch: false }} />}>
  <Icon className="size-4 mr-2" />
                           {route.title()}
                           {route.badge && (
@@ -324,7 +324,7 @@ export function NavKnowledge() {
       </Collapsible>
 
       {!isCollapsed && (
-        <KnowledgeBaseLinks pathname={pathname} />
+        <KnowledgeBaseLinks />
       )}
 
       <KnowledgeFormDialog

package/src/components/layout/sidebar-03/nav-main.tsx

@@ -46,9 +46,7 @@ import {
 } from "lucide-react";
 import { Link } from "@tanstack/react-router";
 import { useState } from "react";
-import { useLocation } from "@tanstack/react-router";
 import type { Route } from "@/config/sidebar-routes";
-import { isParentActive } from "@/lib/sidebar-utils";
 import { MODULE_ROUTES } from "@/lib/collab/module-map";
 
 import { AnimatedGradientText } from "@/components/magicui/animated-gradient-text";
@@ -95,19 +93,21 @@ function getIconComponent(iconName: string | undefined) {
 import { CreateDesignDialog } from "@/components/design/editor/dashboard/create-design-dialog";
 import { m } from "@/paraglide/messages.js";
 
+// 激活态交由 Link 自身判定（activeProps data-active 替代 SidebarMenuButton isActive，
+// Base UI state.active=true 同样落 data-active=""，CSS data-active: 变体不受影响）。
+// 口径保持：/dashboard 与有子级的父行 = 精确匹配（原 isParentActive / pathname=== 特例），
+// 其余 = 默认模糊匹配（段边界前缀，等价原 startsWith 且不误伤 /bugs-x 同前缀路由）；
+// includeSearch:false 保持纯 pathname 口径（否则带查询串的 URL 不命中激活态）。
+const EXACT_ACTIVE_OPTIONS = { exact: true, includeSearch: false } as const;
+const FUZZY_ACTIVE_OPTIONS = { includeSearch: false } as const;
+const LINK_ACTIVE_PROPS = { "data-active": "" } as const;
+
 export default function DashboardNavigation({ routes }: { routes: Route[] }) {
   const { state } = useSidebar();
-  const { pathname } = useLocation();
   const isCollapsed = state === "collapsed";
   const [openCollapsible, setOpenCollapsible] = useState<string | null>(null);
   const [createDesignOpen, setCreateDesignOpen] = useState(false);
 
-  const isActive = (link: string) => {
-    if (link === "/dashboard") return pathname === "/dashboard";
-    if (link === "#") return false;
-    return pathname.startsWith(link);
-  };
-
   return (
     <>
       <SidebarMenu className="space-y-1">
@@ -115,9 +115,6 @@ export default function DashboardNavigation({ routes }: { routes: Route[] }) {
           const hasSubRoutes = !!route.subs?.length;
           const isDesignRoute = route.id === "prd";
           const isOpen = hasSubRoutes && !isCollapsed && openCollapsible === route.id;
-          const active = hasSubRoutes
-            ? isParentActive(pathname, route.link)
-            : isActive(route.link);
           // route.id ≠ presence module key（home→dashboard 等），MODULE_ROUTES 查表（§8.2 交接锚点 F）
           const presenceModule = MODULE_ROUTES.find(
             (mr) => mr.id === route.id,
@@ -135,7 +132,7 @@ export default function DashboardNavigation({ routes }: { routes: Route[] }) {
                 >
                   <div className="relative">
                     <SidebarMenuButton render={<Link to={route.link}
-                        className="flex w-full items-center" />} isActive={active} className={cn(
+                        className="flex w-full items-center" activeProps={LINK_ACTIVE_PROPS} activeOptions={hasSubRoutes ? EXACT_ACTIVE_OPTIONS : FUZZY_ACTIVE_OPTIONS} />} className={cn(
                         "flex w-full items-center rounded-lg px-2",
                         !isCollapsed && (isDesignRoute || hasSubRoutes) && "pr-16",
                         isCollapsed && "justify-center"
@@ -202,7 +199,7 @@ export default function DashboardNavigation({ routes }: { routes: Route[] }) {
                             className="h-auto"
                           >
                             <SidebarMenuSubButton render={<Link to={subRoute.link}
-                                className="flex items-center rounded-md px-2.5 py-1.5 text-sm font-medium" />} isActive={isActive(subRoute.link)}>
+                                className="flex items-center rounded-md px-2.5 py-1.5 text-sm font-medium" activeProps={LINK_ACTIVE_PROPS} activeOptions={subRoute.link === "/dashboard" ? EXACT_ACTIVE_OPTIONS : FUZZY_ACTIVE_OPTIONS} />}>
                                 {getIconComponent(subRoute.icon as string)}
                                 <span className="truncate min-w-0">{subRoute.title()}</span>
                                 {/* {subRoute.badge?.trim() && (
@@ -224,7 +221,7 @@ export default function DashboardNavigation({ routes }: { routes: Route[] }) {
                         "flex items-center rounded-lg px-2",
                         !isCollapsed && presenceModule && route.presence && "pr-12",
                         isCollapsed && "justify-center"
-                      )} />} tooltip={route.title()} isActive={active}>
+                      )} activeProps={LINK_ACTIVE_PROPS} activeOptions={route.link === "/dashboard" ? EXACT_ACTIVE_OPTIONS : FUZZY_ACTIVE_OPTIONS} />} tooltip={route.title()}>
                       {route.icon}
                       {!isCollapsed && (
 <span className="ml-2 text-sm font-medium">

package/src/components/layout/sidebar-03/nav-notifications.tsx

@@ -32,12 +32,12 @@ import {
   PopoverTrigger,
 } from '@/components/ui/popover'
 import { CATEGORY_ICONS, formatRelativeTime } from '@/components/notifications/team-notifications'
+import { useNotifications } from '@/hooks/use-notifications'
 import {
-  useNotifications,
-  NOTIFICATION_POPOVER_KEY,
   NOTIFICATION_ROOT_KEY,
-} from '@/hooks/use-notifications'
-import { listNotificationsFn, markAllNotificationsReadFn, markNotificationReadFn } from '@/server/serverFns/notifications'
+  notificationsPopoverUnreadQueryOptions,
+} from '@/lib/queries/notifications'
+import { markAllNotificationsReadFn, markNotificationReadFn } from '@/server/serverFns/notifications'
 import type { NotificationItem } from '@allbluecn/kernel'
 import { m } from "@/paraglide/messages.js";
 
@@ -50,10 +50,7 @@ export function NotificationsBell() {
   const [open, setOpen] = useState(false)
 
   // ⚠ 与详情页 useInfiniteQuery 的分页缓存形态不同，必须使用独立 queryKey
-  const { data } = useQuery({
-    queryKey: [...NOTIFICATION_POPOVER_KEY, 'status', 'unread'],
-    queryFn: () => listNotificationsFn({ data: { status: 'unread' } }),
-  })
+  const { data } = useQuery(notificationsPopoverUnreadQueryOptions())
   const items = (data?.items ?? []).slice(0, POPOVER_ITEM_LIMIT)
 
   const invalidateNotificationData = () => {

package/src/components/layout/sidebar-03/nav-workspace.tsx

@@ -15,7 +15,7 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
-import { Link, useLocation } from "@tanstack/react-router";
+import { Link } from "@tanstack/react-router";
 import { useEffect, useState } from "react";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { Layers, Plus, PinOff } from "lucide-react";
@@ -28,7 +28,6 @@ import {
 } from "@/components/ui/sidebar";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import { cn } from "@/lib/utils";
-import { isParentActive } from "@/lib/sidebar-utils";
 import { LucideIconByName } from "@/components/shared-kit/icons/lucide-icon-picker/lucide-icon-by-name";
 import { CreateWorkspaceDialog } from "@/components/workspace/dialogs/create-workspace-dialog";
 import { WORKSPACES_QUERY_KEY } from "@/lib/collections/query-keys";
@@ -39,7 +38,7 @@ import {
 import { m } from "@/paraglide/messages.js";
 import { onEvent, emitEvent, AppEvents } from "@/lib/events";
 
-function WorkspaceLinks({ pathname }: { pathname: string }) {
+function WorkspaceLinks() {
   // useQuery 直读 per-request queryClient（_nav loader 已 SSR 预取），
   // 列表随 SSR HTML 直出，刷新无需等待；避免 module-level collection 的跨请求泄漏
   const { data } = useQuery({
@@ -52,18 +51,22 @@ function WorkspaceLinks({ pathname }: { pathname: string }) {
   return (
     <SidebarMenu className="space-y-1">
       <SidebarMenuItem>
-        <SidebarMenuButton render={<Link to="/workspaces" className="flex w-full items-center" />} tooltip={m.common_sidebar_workspace_home()} isActive={pathname === "/workspaces"} className="flex w-full items-center rounded-lg px-2 font-medium data-active:text-sidebar-foreground">
+        {/* 精确匹配（activeOptions.exact）保持原 pathname === "/workspaces" 口径；
+            includeSearch:false 保持纯 pathname 口径（activeProps data-active 走 Link 自身
+            激活判定，替代 SidebarMenuButton isActive，data-active 值同为空串） */}
+        <SidebarMenuButton render={<Link to="/workspaces" className="flex w-full items-center" activeProps={{ 'data-active': '' }} activeOptions={{ exact: true, includeSearch: false }} />} tooltip={m.common_sidebar_workspace_home()} className="flex w-full items-center rounded-lg px-2 font-medium data-active:text-sidebar-foreground">
             <Layers className="size-4" />
             <span className="ml-2 text-sm font-medium">{m.common_sidebar_workspace_home()}</span>
           </SidebarMenuButton>
       </SidebarMenuItem>
       {workspacesList.map((ws) => {
-        const active = pathname.startsWith(`/workspaces/${ws.id}`);
         return (
           <SidebarMenuItem key={ws.id} className="group/ws relative">
+            {/* 默认模糊匹配（段边界前缀）等价原 pathname.startsWith(`/workspaces/${ws.id}`)，
+                且不误伤 id 互为字符串前缀的工作区 */}
             <SidebarMenuButton render={<Link to="/workspaces/$workspaceId"
                 params={{ workspaceId: ws.id }}
-                className="flex w-full items-center" />} tooltip={ws.name} isActive={active} className="flex w-full items-center rounded-lg px-2 font-medium pr-8 data-active:text-sidebar-foreground">
+                className="flex w-full items-center" activeProps={{ 'data-active': '' }} activeOptions={{ includeSearch: false }} />} tooltip={ws.name} className="flex w-full items-center rounded-lg px-2 font-medium pr-8 data-active:text-sidebar-foreground">
                 <LucideIconByName
                   name={ws.icon}
                   size={16}
@@ -95,7 +98,6 @@ function WorkspaceLinks({ pathname }: { pathname: string }) {
 
 export function NavWorkspace() {
   const { state } = useSidebar();
-  const { pathname } = useLocation();
   const isCollapsed = state === "collapsed";
   const [createOpen, setCreateOpen] = useState(false);
   const queryClient = useQueryClient();
@@ -118,7 +120,7 @@ export function NavWorkspace() {
       <SidebarGroup className="p-0">
         <SidebarMenu>
           <SidebarMenuItem>
-            <SidebarMenuButton render={<Link to="/workspaces" className="flex items-center" />} tooltip={m.common_sidebar_workspace_home()} isActive={isParentActive(pathname, "/workspaces")}>
+            <SidebarMenuButton render={<Link to="/workspaces" className="flex items-center" activeProps={{ 'data-active': '' }} activeOptions={{ exact: true, includeSearch: false }} />} tooltip={m.common_sidebar_workspace_home()}>
                 <Layers className="size-4" />
               </SidebarMenuButton>
           </SidebarMenuItem>
@@ -145,7 +147,7 @@ export function NavWorkspace() {
           <Plus className="size-3.5" />
         </button>
       </div>
-      <WorkspaceLinks pathname={pathname} />
+      <WorkspaceLinks />
       <CreateWorkspaceDialog open={createOpen} onOpenChange={setCreateOpen} />
     </SidebarGroup>
   );

package/src/components/notifications/__tests__/settings-notifications.test.tsx

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// settings-notifications 偏好保存竞态回归（TanStack 优化任务 12）。
+//
+// 旧实现在保存 serverFn 成功后才 setQueryData 写缓存，且成功路径无 invalidate、
+// 无 cancelQueries：mutation 前已在途的 refetch 若在成功写缓存之后才 resolve
+// （其响应内容是保存提交前的服务端旧偏好），会把缓存写回旧值——组件 useEffect
+// 同步本地状态后，用户的开关被永久弹回（直到下一次无关 refetch 才纠偏）。
+// 迁移为官方三段式后：onMutate cancelQueries + 快照 + 乐观写（取消在途 fetch，
+// 旧值永不落缓存）、onError 回滚 + toast、onSettled invalidate 对齐服务端真相。
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react'
+
+vi.mock('@/server/serverFns/notifications', () => ({
+  getNotificationPreferencesFn: vi.fn(),
+  getUnreadCountFn: vi.fn(),
+  listNotificationsFn: vi.fn(),
+  updateNotificationPreferencesFn: vi.fn(),
+}))
+vi.mock('@/server/serverFns/auth/email-verification', () => ({
+  getEmailVerifiedStatusFn: vi.fn(),
+  resendVerificationEmailFn: vi.fn(),
+}))
+vi.mock('@/components/shared-kit/auth/auth-client', () => ({
+  useSession: vi.fn(() => ({ data: null })),
+}))
+
+import { SettingsNotifications } from '../settings-notifications'
+import { NOTIFICATION_PREFERENCES_KEY } from '@/lib/queries/notifications'
+import {
+  getNotificationPreferencesFn,
+  updateNotificationPreferencesFn,
+} from '@/server/serverFns/notifications'
+import type { NotificationPreferences } from '@allbluecn/kernel'
+
+const prefsDndOff: NotificationPreferences = {
+  categories: { team: 'realtime', collaboration: 'realtime', system: 'realtime', billing: 'realtime', security: 'realtime' },
+  emailCategories: { team: true, collaboration: true, system: true, billing: true, security: true },
+  dndEnabled: false,
+  dndStart: '22:00',
+  dndEnd: '07:00',
+}
+const prefsDndOn: NotificationPreferences = { ...prefsDndOff, dndEnabled: true }
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  let reject!: (reason?: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+const clients: QueryClient[] = []
+
+function renderPanel() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  })
+  clients.push(client)
+  render(
+    <QueryClientProvider client={client}>
+      <SettingsNotifications />
+    </QueryClientProvider>,
+  )
+  return client
+}
+
+const readDnd = (client: QueryClient) =>
+  client.getQueryData<NotificationPreferences>(NOTIFICATION_PREFERENCES_KEY)?.dndEnabled
+
+const dndSwitch = () => document.getElementById('dnd-enabled') as HTMLButtonElement
+
+beforeEach(() => {
+  // shouldAdvanceTime：让 RTL waitFor 的轮询 timer 走真实节奏；调度确定性仍由显式 advance 控制
+  vi.useFakeTimers({ shouldAdvanceTime: true })
+  vi.mocked(getNotificationPreferencesFn).mockResolvedValue(prefsDndOff)
+  vi.mocked(updateNotificationPreferencesFn).mockResolvedValue(undefined as never)
+})
+
+afterEach(() => {
+  cleanup()
+  vi.useRealTimers()
+  // reset 而非 clear：mockClear 不清 mockImplementationOnce 队列，会泄漏到下一用例
+  vi.resetAllMocks()
+  clients.length = 0
+})
+
+describe('SettingsNotifications 偏好保存乐观更新（官方 onMutate 通道）', () => {
+  it('保存成功后在途 refetch 迟到返回旧偏好不覆盖缓存（cancelQueries 防线），终态为新值', async () => {
+    const inFlight = deferred<NotificationPreferences>()
+    const mutation = deferred<{ success: true }>()
+    const afterInvalidate = deferred<NotificationPreferences>()
+
+    vi.mocked(getNotificationPreferencesFn)
+      .mockImplementationOnce(() => Promise.resolve(prefsDndOff)) // 首屏
+      .mockImplementationOnce(() => inFlight.promise) // mutation 前触发的在途 refetch
+      .mockImplementationOnce(() => afterInvalidate.promise) // onSettled invalidate
+    vi.mocked(updateNotificationPreferencesFn).mockImplementation(() => mutation.promise)
+
+    const client = renderPanel()
+    await waitFor(() => expect(dndSwitch()).toBeTruthy())
+
+    // mutation（防抖保存）前触发一次 refetch，延迟返回旧偏好
+    void client.invalidateQueries({ queryKey: NOTIFICATION_PREFERENCES_KEY })
+    await waitFor(() => expect(getNotificationPreferencesFn).toHaveBeenCalledTimes(2))
+
+    // 开启 DND → 本地 state 立即切换，500ms 防抖后发起保存
+    fireEvent.click(dndSwitch())
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500)
+    })
+    await waitFor(() => expect(updateNotificationPreferencesFn).toHaveBeenCalledTimes(1))
+    // 乐观写先落地（缓存已含新值，不等服务端返回）
+    await waitFor(() => expect(readDnd(client)).toBe(true))
+
+    // 服务端确认 → onSettled invalidate → 拉取服务端真相
+    await act(async () => {
+      mutation.resolve({ success: true })
+      await vi.advanceTimersByTimeAsync(50)
+    })
+    await waitFor(() => expect(getNotificationPreferencesFn).toHaveBeenCalledTimes(3))
+
+    // 竞态核心断言：在途 refetch 此刻才 resolve 保存前的旧偏好（canceled，不得覆盖）
+    await act(async () => {
+      inFlight.resolve(prefsDndOff)
+      await vi.advanceTimersByTimeAsync(50)
+    })
+    expect(readDnd(client)).toBe(true)
+
+    afterInvalidate.resolve(prefsDndOn)
+    await waitFor(() => {
+      expect(client.getQueryData<NotificationPreferences>(NOTIFICATION_PREFERENCES_KEY)).toEqual(prefsDndOn)
+    })
+  })
+
+  it('保存失败回滚快照并 invalidate 纠偏（开关不被乐观值残留误导）', async () => {
+    const truth = deferred<NotificationPreferences>()
+    vi.mocked(getNotificationPreferencesFn)
+      .mockImplementationOnce(() => Promise.resolve(prefsDndOff)) // 首屏
+      .mockImplementationOnce(() => truth.promise) // onSettled invalidate
+    vi.mocked(updateNotificationPreferencesFn).mockRejectedValue(new Error('boom'))
+
+    const client = renderPanel()
+    await waitFor(() => expect(dndSwitch()).toBeTruthy())
+
+    fireEvent.click(dndSwitch())
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500)
+    })
+    // 失败 → onError 回滚快照 + onSettled invalidate 拉取服务端真相
+    truth.resolve(prefsDndOff)
+    await waitFor(() => expect(readDnd(client)).toBe(false))
+    expect(readDnd(client)).toBe(false)
+  })
+})

package/src/components/notifications/settings-notifications.tsx

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // Adapted from @hextaui/settings-notifications (https://www.hextaui.com)
 import { useEffect, useState } from 'react'
-import { useQuery, useQueryClient } from '@tanstack/react-query'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
 import { toast } from '@/components/ui/toast'
 import { Bell, Mail } from 'lucide-react'
 import { Field, FieldContent, FieldDescription, FieldLabel } from '@/components/ui/field'
@@ -16,7 +16,11 @@ import {
 import { Separator } from '@/components/ui/separator'
 import { Switch } from '@/components/ui/switch'
 import { useDebouncedCallback } from '@/lib/pacer'
-import { getNotificationPreferencesFn, updateNotificationPreferencesFn } from '@/server/serverFns/notifications'
+import { updateNotificationPreferencesFn } from '@/server/serverFns/notifications'
+import {
+  NOTIFICATION_PREFERENCES_KEY,
+  notificationPreferencesQueryOptions,
+} from '@/lib/queries/notifications'
 import { getEmailVerifiedStatusFn } from '@/server/serverFns/auth/email-verification'
 import { useSession } from '@/components/shared-kit/auth/auth-client'
 import type {
@@ -52,10 +56,7 @@ export function SettingsNotifications() {
   const { data: session } = useSession()
   const userId = session?.user?.id ?? null
 
-  const { data: prefsData, isLoading } = useQuery({
-    queryKey: ['notifications', 'preferences'],
-    queryFn: () => getNotificationPreferencesFn({ data: {} }),
-  })
+  const { data: prefsData, isLoading } = useQuery(notificationPreferencesQueryOptions())
 
   const { data: emailVerified = null } = useQuery({
     queryKey: ['email-verified-status', userId ?? 'anonymous'],
@@ -73,14 +74,37 @@ export function SettingsNotifications() {
     if (prefsData) setPrefs(prefsData)
   }, [prefsData])
 
-  const debouncedSave = useDebouncedCallback(async (next: NotificationPreferences) => {
-    try {
-      await updateNotificationPreferencesFn({ data: next })
-      queryClient.setQueryData(['notifications', 'preferences'], next)
-    } catch {
+  // 官方乐观更新三段式（TanStack Query Optimistic Updates 指南）：
+  // onMutate —— cancelQueries 取消在途 refetch（防其迟到返回保存前的旧偏好覆盖
+  //             刚写入的值——旧实现成功写缓存后无 invalidate，被覆盖即成永久回退）+
+  //             快照 + 乐观写；onError —— 回滚快照 + toast；onSettled —— invalidate
+  //             对齐服务端真相（失败路径同样兜底纠偏）。
+  const savePrefsMutation = useMutation({
+    mutationFn: (next: NotificationPreferences) =>
+      updateNotificationPreferencesFn({ data: next }),
+    onMutate: async (next) => {
+      await queryClient.cancelQueries({ queryKey: NOTIFICATION_PREFERENCES_KEY })
+      const previous = queryClient.getQueryData<NotificationPreferences>(
+        NOTIFICATION_PREFERENCES_KEY,
+      )
+      queryClient.setQueryData(NOTIFICATION_PREFERENCES_KEY, next)
+      return { previous }
+    },
+    onError: (_err, _next, ctx) => {
+      if (ctx?.previous !== undefined) {
+        queryClient.setQueryData(NOTIFICATION_PREFERENCES_KEY, ctx.previous)
+      }
       toast.error(m.notifications_preferences_saveFailed())
-      queryClient.invalidateQueries({ queryKey: ['notifications', 'preferences'] })
-    }
+    },
+    onSettled: () => {
+      void queryClient.invalidateQueries({ queryKey: NOTIFICATION_PREFERENCES_KEY })
+    },
+  })
+
+  const debouncedSave = useDebouncedCallback((next: NotificationPreferences) => {
+    void savePrefsMutation.mutateAsync(next).catch(() => {
+      // onError 已 toast + 回滚，rejection 到此终结
+    })
   }, { wait: PREFERENCES_SAVE_DEBOUNCE_MS })
 
   const patch = (partial: Partial<NotificationPreferences>) => {

package/src/components/notifications/team-notifications.tsx

@@ -47,12 +47,15 @@ import {
 } from '@/components/ui/select'
 import { Separator } from '@/components/ui/separator'
 import { cn } from '@/lib/utils'
-import { useNotifications, NOTIFICATION_LIST_KEY, NOTIFICATION_ROOT_KEY } from '@/hooks/use-notifications'
+import { useNotifications } from '@/hooks/use-notifications'
+import {
+  NOTIFICATION_ROOT_KEY,
+  notificationsListInfiniteQueryOptions,
+} from '@/lib/queries/notifications'
 import type { NotificationCategory, NotificationItem } from '@allbluecn/kernel'
 import {
   clearNotificationsFn,
   deleteNotificationFn,
-  listNotificationsFn,
   markAllNotificationsReadFn,
   markNotificationReadFn,
 } from '@/server/serverFns/notifications'
@@ -106,18 +109,11 @@ export function TeamNotificationsPanel() {
   const [categoryFilter, setCategoryFilter] = useState<'all' | NotificationCategory>('all')
   const [statusFilter, setStatusFilter] = useState<StatusFilter>('all')
 
-  const { data, isLoading, fetchNextPage, isFetchingNextPage, hasNextPage } = useInfiniteQuery({
-    queryKey: [...NOTIFICATION_LIST_KEY, categoryFilter === 'all' ? undefined : categoryFilter],
-    queryFn: async ({ pageParam }) => {
-      const base = categoryFilter === 'all' ? {} : { category: categoryFilter }
-      return listNotificationsFn({
-        data: pageParam ? { ...base, cursor: pageParam } : base,
-      })
-    },
-    initialPageParam: undefined as string | undefined,
-    getNextPageParam: (lastPage) =>
-      lastPage.hasMore ? lastPage.items[lastPage.items.length - 1].id : undefined,
-  })
+  const { data, isLoading, fetchNextPage, isFetchingNextPage, hasNextPage } = useInfiniteQuery(
+    notificationsListInfiniteQueryOptions(
+      categoryFilter === 'all' ? undefined : categoryFilter,
+    ),
+  )
 
   const items = useMemo(() => data?.pages.flatMap((page) => page.items) ?? [], [data])