@allbluecn/web-app 0.22.4 → 0.23.1

package/src/hooks/use-notifications.ts

@@ -5,15 +5,15 @@ import { useRouter } from '@tanstack/react-router'
 import { toast } from '@/components/ui/toast'
 import type { NotificationSseValue, NotificationItem } from '@allbluecn/kernel'
 import { isInDndWindow } from '@allbluecn/kernel'
-import { getUnreadCountFn, getNotificationPreferencesFn } from '@/server/serverFns/notifications'
+import {
+  NOTIFICATION_PREFERENCES_KEY,
+  NOTIFICATION_ROOT_KEY,
+  NOTIFICATION_UNREAD_KEY,
+  notificationPreferencesQueryOptions,
+  notificationsUnreadQueryOptions,
+} from '@/lib/queries/notifications'
 import { m } from "@/paraglide/messages.js";
 
-export const NOTIFICATION_ROOT_KEY = ['notifications'] as const
-export const NOTIFICATION_LIST_KEY = ['notifications', 'list'] as const
-export const NOTIFICATION_POPOVER_KEY = ['notifications', 'popover'] as const
-export const NOTIFICATION_UNREAD_KEY = ['notifications', 'unread'] as const
-export const NOTIFICATION_PREFERENCES_KEY = ['notifications', 'preferences'] as const
-
 export function parseNotificationEvent(raw: string): NotificationSseValue | null {
   try {
     const parsed = JSON.parse(raw)
@@ -50,19 +50,12 @@ export function useNotifications(options?: { toastEnabled?: boolean }) {
   const router = useRouter()
   const toastEnabled = options?.toastEnabled !== false
 
-  const { data: unreadData } = useQuery({
-    queryKey: NOTIFICATION_UNREAD_KEY,
-    queryFn: () => getUnreadCountFn({ data: {} }),
-  })
+  const { data: unreadData } = useQuery(notificationsUnreadQueryOptions())
 
   const unreadCount = unreadData?.count ?? 0
 
   // N2 修复：预加载偏好数据到缓存，确保 DND 判断在任何页面均可用
-  useQuery({
-    queryKey: NOTIFICATION_PREFERENCES_KEY,
-    queryFn: () => getNotificationPreferencesFn({ data: {} }),
-    staleTime: 60000,
-  })
+  useQuery({ ...notificationPreferencesQueryOptions(), staleTime: 60000 })
 
   const setUnreadCount = useCallback(
     (updater: number | ((c: number) => number)) => {

package/src/hooks/use-unsaved-guard.tsx

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { useCallback, useRef } from "react";
+import { useBlocker } from "@tanstack/react-router";
+import { m } from "@/paraglide/messages.js";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+
+/**
+ * 未保存拦截统一 hook（TanStack 优化计划任务 2）：TanStack Router useBlocker
+ * 封装 + 受控 AlertDialog（文案走 paraglide i18n，禁 window.confirm）。
+ *
+ * - SPA 导航：仅 isDirty() 为 true 时 block（shouldBlockFn 读 ref，防抖保存
+ *   成功把 dirty 置 false 后，导航不再弹窗——过度拦截防线）；blocked 态由
+ *   调用方渲染返回的 dialog，「离开」先 await onSaveAndLeave（flush 保存）
+ *   再 proceed，「留下」/Esc/reset。
+ * - 刷新/关闭：enableBeforeUnload 必须用函数形态而非 true——@tanstack/history
+ *   的 onBeforeUnload 对 boolean true 在 blocker 注册期间无条件 preventDefault
+ *   （不查询 shouldBlockFn），clean 态刷新也会弹原生警告；函数形态在卸载时
+ *   调用，与「仅 dirty 时拦截」同一防线。
+ * - 浏览器关闭/刷新时的自动落库（beforeunload 尽力保存）不属于本 hook 职责，
+ *   由各编辑器既有的通道三监听保留，与本 hook 的 enableBeforeUnload 原生警告
+ *   并存不冲突。
+ */
+export function useUnsavedGuard({
+  isDirty,
+  onSaveAndLeave,
+}: {
+  /** dirty 信号（每次渲染刷新 ref，回调 identity 不影响 blocker 注册） */
+  isDirty: () => boolean;
+  /** 「离开」时先执行的保存（flush），完成后才 proceed；缺省 = 纯拦截 */
+  onSaveAndLeave?: () => Promise<void> | void;
+}) {
+  const isDirtyRef = useRef(isDirty);
+  isDirtyRef.current = isDirty;
+  const onSaveAndLeaveRef = useRef(onSaveAndLeave);
+  onSaveAndLeaveRef.current = onSaveAndLeave;
+
+  // 稳定引用：useBlocker 以 shouldBlockFn/enableBeforeUnload 为 effect 依赖
+  // 注册 history.block，identity 抖动会导致反复注销/重挂 blocker
+  const shouldBlockFn = useCallback(() => isDirtyRef.current(), []);
+  const beforeUnloadGuard = useCallback(() => isDirtyRef.current(), []);
+
+  // 默认形态返回 void，withResolver: true 才返回 BlockerResolver（.d.ts 出入）
+  const blocker = useBlocker({
+    shouldBlockFn,
+    enableBeforeUnload: beforeUnloadGuard,
+    withResolver: true,
+  });
+
+  const handleLeave = useCallback(async () => {
+    await onSaveAndLeaveRef.current?.();
+    blocker.proceed?.();
+  }, [blocker]);
+
+  const dialog =
+    blocker.status === "blocked" ? (
+      <AlertDialog
+        open
+        onOpenChange={(open) => {
+          // Cancel/Esc 的关闭请求一律视为「留下」
+          if (!open) blocker.reset?.();
+        }}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>{m.common_unsaved_title()}</AlertDialogTitle>
+            <AlertDialogDescription>{m.common_unsaved_body()}</AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>{m.common_unsaved_stay()}</AlertDialogCancel>
+            <AlertDialogAction onClick={handleLeave}>{m.common_unsaved_leave()}</AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    ) : null;
+
+  return { dialog };
+}

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

@@ -15,104 +15,41 @@
 // 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 { describe, expect, it, vi, beforeEach, afterEach } from "vitest"
-import { checkRateLimit, getRateLimiter } from "../pacer"
+import { describe, expect, it } from "vitest"
 
 describe("pacer", () => {
-  let setIntervalSpy: ReturnType<typeof vi.spyOn>
-  let clearIntervalSpy: ReturnType<typeof vi.spyOn>
-
-  beforeEach(() => {
-    setIntervalSpy = vi.spyOn(globalThis, "setInterval").mockImplementation(vi.fn(() => undefined as unknown as ReturnType<typeof setInterval>))
-    clearIntervalSpy = vi.spyOn(globalThis, "clearInterval").mockImplementation(vi.fn())
-    vi.useFakeTimers()
-  })
-
-  afterEach(() => {
-    vi.useRealTimers()
-    setIntervalSpy?.mockRestore()
-    clearIntervalSpy?.mockRestore()
-    vi.restoreAllMocks()
-  })
-
-  describe("checkRateLimit", () => {
-    it("allows requests within limit", () => {
-      const config = { max: 2, windowMs: 1000 }
-
-      const result1 = checkRateLimit("test-key-1", config)
-      expect(result1.allowed).toBe(true)
-      expect(result1.retryAfterMs).toBe(0)
-
-      const result2 = checkRateLimit("test-key-1", config)
-      expect(result2.allowed).toBe(true)
-    })
-
-    it("rejects requests exceeding limit", () => {
-      const config = { max: 2, windowMs: 1000 }
-
-      checkRateLimit("test-key-2", config)
-      checkRateLimit("test-key-2", config)
-      const result3 = checkRateLimit("test-key-2", config)
-
-      expect(result3.allowed).toBe(false)
-      expect(result3.retryAfterMs).toBeGreaterThan(0)
-    })
-
-    it("different keys have independent limits", () => {
-      const config = { max: 1, windowMs: 1000 }
-
-      const resultA = checkRateLimit("key-a", config)
-      expect(resultA.allowed).toBe(true)
-
-      const resultB = checkRateLimit("key-b", config)
-      expect(resultB.allowed).toBe(true)
-    })
-
-    it("resets after window expires", () => {
-      const config = { max: 1, windowMs: 1000 }
-
-      checkRateLimit("test-key-4", config)
-      const blocked = checkRateLimit("test-key-4", config)
-      expect(blocked.allowed).toBe(false)
-
-      vi.advanceTimersByTime(1001)
-
-      const afterWait = checkRateLimit("test-key-4", config)
-      expect(afterWait.allowed).toBe(true)
-    })
-  })
-
-  describe("getRateLimiter", () => {
-    it("returns same limiter for same key", () => {
-      const limiter1 = getRateLimiter("limiter-key-1", { max: 5, windowMs: 10000 })
-      const limiter2 = getRateLimiter("limiter-key-1", { max: 5, windowMs: 10000 })
-
-      expect(limiter1).toBe(limiter2)
-    })
-
-    it("returns different limiters for different keys", () => {
-      const limiter1 = getRateLimiter("limiter-key-a", { max: 5, windowMs: 10000 })
-      const limiter2 = getRateLimiter("limiter-key-b", { max: 5, windowMs: 10000 })
-
-      expect(limiter1).not.toBe(limiter2)
-    })
-
-    it("limiter maybeExecute respects limit", () => {
-      const limiter = getRateLimiter("limiter-key-3", { max: 2, windowMs: 1000 })
-
-      expect(limiter.maybeExecute()).toBe(true)
-      expect(limiter.maybeExecute()).toBe(true)
-      expect(limiter.maybeExecute()).toBe(false)
-    })
-
-    it("reset clears the limiter state", () => {
-      const limiter = getRateLimiter("limiter-key-4", { max: 1, windowMs: 1000 })
-
-      limiter.maybeExecute()
-      expect(limiter.maybeExecute()).toBe(false)
-
-      limiter.reset()
-      expect(limiter.maybeExecute()).toBe(true)
+  describe("导出面回归", () => {
+    it("仅保留客户端防抖/节流面，限流实现收敛 server/lib/rate-limit", async () => {
+      const pacer = await import("../pacer")
+      expect(Object.keys(pacer).sort()).toEqual(
+        [
+          "EDITOR_AUTO_SAVE_MS",
+          "EDITOR_CHANGE_DEBOUNCE_MS",
+          "SEARCH_DEBOUNCE_MS",
+          "SCROLL_THROTTLE_MS",
+          "useDebouncedCallback",
+          "useDebouncedValue",
+          "useDebouncer",
+          "useThrottledCallback",
+        ].sort()
+      )
+    })
+
+    it("常量取值稳定（客户端消费者依赖）", async () => {
+      const pacer = await import("../pacer")
+      expect(pacer.EDITOR_AUTO_SAVE_MS).toBe(2000)
+      expect(pacer.EDITOR_CHANGE_DEBOUNCE_MS).toBe(500)
+      expect(pacer.SEARCH_DEBOUNCE_MS).toBe(300)
+      expect(pacer.SCROLL_THROTTLE_MS).toBe(150)
+    })
+
+    it("hooks 为 @tanstack/react-pacer 原样 re-export", async () => {
+      const pacer = await import("../pacer")
+      const reactPacer = await import("@tanstack/react-pacer")
+      expect(pacer.useDebouncedCallback).toBe(reactPacer.useDebouncedCallback)
+      expect(pacer.useDebouncedValue).toBe(reactPacer.useDebouncedValue)
+      expect(pacer.useDebouncer).toBe(reactPacer.useDebouncer)
+      expect(pacer.useThrottledCallback).toBe(reactPacer.useThrottledCallback)
     })
   })
 })

package/src/lib/__tests__/query-defaults.test.ts

@@ -0,0 +1,169 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  QueryClient,
+  QueryObserver,
+  dehydrate,
+  hydrate,
+} from '@tanstack/react-query'
+import { QUERY_STALE_TIME_MS } from '../query-defaults'
+
+// 协同测试基座：与 router.tsx 的 defaultOptions 共享同一 staleTime 常量（单一来源），
+// 断言全局 staleTime 与 invalidate / loader（fetchQuery / ensureQueryData）/ SSR 水合
+// 的协同语义。
+//
+// ⚠ query-core 5.104 的方法语义（测试按此校准）：
+// - fetchQuery：命中「不 stale」缓存即返回，stale（超窗或被 invalidate）则重拉——
+//   与 loader 的 fetchInfiniteQuery 同语义；
+// - ensureQueryData：只要有缓存一律返回（已 deprecated 的预取语义），不按窗口重拉；
+// - useQuery（QueryObserver）：mount 时 stale 才重拉（refetchOnMount 默认 true）。
+function createClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { staleTime: QUERY_STALE_TIME_MS, refetchOnWindowFocus: false },
+    },
+  })
+}
+
+describe('全局 staleTime 常量', () => {
+  it('为 30 秒（毫秒常量）', () => {
+    expect(QUERY_STALE_TIME_MS).toBe(30_000)
+  })
+})
+
+describe('staleTime 与 mutation invalidate 协同', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('mutation 成功后 invalidate：导航回列表 loader fetchQuery 重拉新数据（staleTime 不阻断失效）', async () => {
+    vi.useFakeTimers()
+    const client = createClient()
+    let version = 'v1'
+    let fetchCount = 0
+    const listKey = ['story', 'list'] as const
+    const listQuery = {
+      queryKey: listKey,
+      queryFn: () => {
+        fetchCount += 1
+        return Promise.resolve(version)
+      },
+    }
+
+    // 首次进入列表：loader 拉取，数据 fresh
+    await client.fetchQuery(listQuery)
+    expect(fetchCount).toBe(1)
+    expect(client.getQueryData(listKey)).toBe('v1')
+
+    // 离开列表（查询无 observer 仍留在缓存）→ 在详情页执行 mutation，
+    // onSuccess 走真实 invalidateQueries 通道：无 active observer 时不立即拉取，
+    // 仅把 fresh 数据标记为 stale
+    version = 'v2'
+    const mutation = client.getMutationCache().build(client, {
+      mutationFn: () => Promise.resolve(),
+      onSuccess: () => client.invalidateQueries({ queryKey: listKey }),
+    })
+    await mutation.execute(undefined as never)
+    expect(fetchCount).toBe(1)
+
+    // 导航回列表：loader fetchQuery（fetchInfiniteQuery 同语义）——被失效的
+    // fresh 数据必须重拉，30s staleTime 窗口不得阻断
+    const data = await client.fetchQuery(listQuery)
+    expect(data).toBe('v2')
+    expect(fetchCount).toBe(2)
+  })
+
+  it('active 查询（页面挂载中）被 invalidate 立即 refetch，不等 staleTime 过期', async () => {
+    const client = createClient()
+    let fetchCount = 0
+    const options = {
+      queryKey: ['agents'] as const,
+      queryFn: () => {
+        fetchCount += 1
+        return Promise.resolve('v1')
+      },
+    }
+
+    await client.fetchQuery(options)
+    // 挂上 observer（= 组件 mounted 的 active 语义）；数据 fresh 不触发拉取
+    const observer = new QueryObserver(client, options)
+    const unsubscribe = observer.subscribe(() => {})
+    expect(fetchCount).toBe(1)
+
+    // invalidateQueries 会把 fresh 标记为 stale 并 refetch active 查询
+    await client.invalidateQueries({ queryKey: options.queryKey })
+    expect(fetchCount).toBe(2)
+
+    unsubscribe()
+  })
+})
+
+describe('staleTime 30s 窗口内的纯导航', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('窗口内 loader（fetchQuery / ensureQueryData）命中缓存不重跑，窗口外恢复重拉', async () => {
+    vi.useFakeTimers()
+    const client = createClient()
+    let fetchCount = 0
+    const listQuery = {
+      queryKey: ['prd', 'list'] as const,
+      queryFn: () => {
+        fetchCount += 1
+        return Promise.resolve('v1')
+      },
+    }
+
+    await client.fetchQuery(listQuery)
+    expect(fetchCount).toBe(1)
+
+    // 29.999s 后纯导航回列表：loader 重跑但命中缓存，不重新请求
+    vi.advanceTimersByTime(QUERY_STALE_TIME_MS - 1)
+    await client.fetchQuery(listQuery)
+    await client.ensureQueryData(listQuery)
+    expect(fetchCount).toBe(1)
+
+    // 越过 30s 窗口后：fetchQuery 恢复重拉
+    vi.advanceTimersByTime(1)
+    await client.fetchQuery(listQuery)
+    expect(fetchCount).toBe(2)
+  })
+})
+
+describe('SSR 脱水/水合与 staleTime 协同', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('水合的 SSR 数据在 30s 窗口内不触发客户端 refetch（期望行为，无双取），窗口外恢复重拉', async () => {
+    vi.useFakeTimers()
+    // 服务端：SSR fetch 后脱水
+    const serverClient = createClient()
+    await serverClient.fetchQuery({
+      queryKey: ['dashboard'] as const,
+      queryFn: () => Promise.resolve('ssr-data'),
+    })
+    const dehydrated = dehydrate(serverClient)
+
+    // 客户端：水合后 30s 内导航到该页不重拉（hydration 无 double-fetch）
+    const client = createClient()
+    hydrate(client, dehydrated)
+    let fetchCount = 0
+    const dashboardQuery = {
+      queryKey: ['dashboard'] as const,
+      queryFn: () => {
+        fetchCount += 1
+        return Promise.resolve('client-data')
+      },
+    }
+    await client.ensureQueryData(dashboardQuery)
+    await client.fetchQuery(dashboardQuery)
+    expect(fetchCount).toBe(0)
+    expect(client.getQueryData(['dashboard'])).toBe('ssr-data')
+
+    // 窗口外恢复客户端重拉
+    vi.advanceTimersByTime(QUERY_STALE_TIME_MS + 1)
+    await client.fetchQuery(dashboardQuery)
+    expect(fetchCount).toBe(1)
+  })
+})