@allbluecn/web-app 0.22.4 → 0.23.1

package/src/lib/queries/__tests__/compliance-queries.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { QueryClient, keepPreviousData } from '@tanstack/react-query'
+
+vi.mock('@/server/serverFns/knowledge/public/compliance/list', () => ({
+  listComplianceFn: vi.fn().mockResolvedValue({ items: [], hasMore: false }),
+}))
+vi.mock('@/server/serverFns/knowledge/public/compliance/detail', () => ({
+  getComplianceDetailFn: vi.fn().mockResolvedValue({}),
+}))
+vi.mock('@/server/serverFns/knowledge/public/entity-tags', () => ({
+  getEntityTagsFn: vi.fn().mockResolvedValue([]),
+}))
+vi.mock('@/server/serverFns/knowledge/public/favorite', () => ({
+  getFavoriteIdsFn: vi.fn().mockResolvedValue([]),
+}))
+
+import { listComplianceFn } from '@/server/serverFns/knowledge/public/compliance/list'
+import { getComplianceDetailFn } from '@/server/serverFns/knowledge/public/compliance/detail'
+import { getEntityTagsFn } from '@/server/serverFns/knowledge/public/entity-tags'
+import { getFavoriteIdsFn } from '@/server/serverFns/knowledge/public/favorite'
+import {
+  COMPLIANCE_LIST_KEY,
+  ENTITY_TAGS_KEY,
+  FAVORITE_IDS_KEY,
+  complianceDetailQueryOptions,
+  complianceListQueryOptions,
+  entityTagsQueryOptions,
+  favoriteIdsQueryOptions,
+} from '../compliance'
+
+const mockedList = vi.mocked(listComplianceFn)
+const mockedDetail = vi.mocked(getComplianceDetailFn)
+const mockedTags = vi.mocked(getEntityTagsFn)
+const mockedFavoriteIds = vi.mocked(getFavoriteIdsFn)
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+/** queryFn 运行时恒存在（工厂必传），类型上可选故窄化；context 形状对齐 react-query v5 调用面 */
+function invokeQueryFn(
+  options: { queryFn?: (...args: never[]) => unknown },
+  queryKey: readonly unknown[],
+): Promise<unknown> {
+  return (options.queryFn as (c: unknown) => Promise<unknown>)({
+    client: new QueryClient(),
+    queryKey,
+    signal: new AbortController().signal,
+    meta: undefined,
+  })
+}
+
+/**
+ * compliance key 结构零漂移：与迁移前两个路由文件的内联字面量逐字一致。
+ * 迁移前 $id.lazy.tsx 的 detail / favorite-ids key 在 useQuery 与
+ * LegalDetailActions props 各持一份靠人工对齐（审计点名的双份维护税），
+ * 现在两处消费 factory().queryKey，编译期防漂移。
+ */
+describe('compliance queryOptions key 结构', () => {
+  it('列表 key 前缀为 [\'compliance\']（invalidateQueries 前缀匹配同形）', () => {
+    expect(COMPLIANCE_LIST_KEY).toEqual(['compliance'])
+    expect(ENTITY_TAGS_KEY).toEqual(['entity-tags'])
+    expect(FAVORITE_IDS_KEY).toEqual(['favorite-ids'])
+  })
+
+  it('列表 key 五段结构与迁移前 [compliance, scope, search, industry, tag] 同形', () => {
+    // 迁移前：['compliance', scope, debouncedSearch, industry, tag]
+    expect(
+      complianceListQueryOptions({ scope: 'all', search: '', industry: undefined, tag: undefined })
+        .queryKey,
+    ).toEqual(['compliance', 'all', '', undefined, undefined])
+    expect(
+      complianceListQueryOptions({ scope: 'private', search: 'gdpr', industry: '金融', tag: '安全' })
+        .queryKey,
+    ).toEqual(['compliance', 'private', 'gdpr', '金融', '安全'])
+  })
+
+  it('详情 key 与迁移前 [compliance-detail, id] 逐字一致', () => {
+    expect(complianceDetailQueryOptions('abc').queryKey).toEqual(['compliance-detail', 'abc'])
+  })
+
+  it('entity-tags key 与迁移前 [entity-tags, entityType] 逐字一致', () => {
+    expect(entityTagsQueryOptions('compliance').queryKey).toEqual(['entity-tags', 'compliance'])
+    expect(entityTagsQueryOptions('legal').queryKey).toEqual(['entity-tags', 'legal'])
+  })
+
+  it('favorite-ids key 与迁移前 [favorite-ids, entityType] 逐字一致', () => {
+    expect(favoriteIdsQueryOptions('compliance').queryKey).toEqual(['favorite-ids', 'compliance'])
+  })
+
+  it('列表工厂保留 placeholderData: keepPreviousData（迁移前 index 页行为）', () => {
+    expect(complianceListQueryOptions({ scope: 'all' }).placeholderData).toBe(keepPreviousData)
+  })
+})
+
+/** queryFn 接线：必须调用既有 serverFn 且 data 形状与迁移前内联写法逐字一致 */
+describe('compliance queryOptions queryFn 接线', () => {
+  it('列表：空 search 归一化为 undefined（迁移前 search || undefined 同形）', async () => {
+    const options = complianceListQueryOptions({ scope: 'all', search: '' })
+    await invokeQueryFn(options, options.queryKey)
+    expect(mockedList).toHaveBeenCalledWith({
+      data: { scope: 'all', search: undefined, industry: undefined, tag: undefined },
+    })
+  })
+
+  it('列表：全量过滤直传（迁移前同形）', async () => {
+    const options = complianceListQueryOptions({
+      scope: 'share',
+      search: 'gdpr',
+      industry: '金融',
+      tag: '安全',
+    })
+    await invokeQueryFn(options, options.queryKey)
+    expect(mockedList).toHaveBeenCalledWith({
+      data: { scope: 'share', search: 'gdpr', industry: '金融', tag: '安全' },
+    })
+  })
+
+  it('详情 → getComplianceDetailFn({ data: { id } })', async () => {
+    const options = complianceDetailQueryOptions('abc')
+    await invokeQueryFn(options, options.queryKey)
+    expect(mockedDetail).toHaveBeenCalledWith({ data: { id: 'abc' } })
+  })
+
+  it('entity-tags → getEntityTagsFn({ data: { entityType } })', async () => {
+    const options = entityTagsQueryOptions('compliance')
+    await invokeQueryFn(options, options.queryKey)
+    expect(mockedTags).toHaveBeenCalledWith({ data: { entityType: 'compliance' } })
+  })
+
+  it('favorite-ids → getFavoriteIdsFn({ data: { entityType } })', async () => {
+    const options = favoriteIdsQueryOptions('compliance')
+    await invokeQueryFn(options, options.queryKey)
+    expect(mockedFavoriteIds).toHaveBeenCalledWith({ data: { entityType: 'compliance' } })
+  })
+})

package/src/lib/queries/__tests__/notifications-queries.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { QueryClient } from '@tanstack/react-query'
+
+vi.mock('@/server/serverFns/notifications', () => ({
+  getUnreadCountFn: vi.fn().mockResolvedValue({ count: 0 }),
+  getNotificationPreferencesFn: vi.fn().mockResolvedValue({}),
+  listNotificationsFn: vi.fn().mockResolvedValue({ items: [], hasMore: false }),
+  markNotificationReadFn: vi.fn(),
+  markAllNotificationsReadFn: vi.fn(),
+  deleteNotificationFn: vi.fn(),
+  clearNotificationsFn: vi.fn(),
+  updateNotificationPreferencesFn: vi.fn(),
+}))
+
+import type { NotificationItem } from '@allbluecn/kernel'
+import { getNotificationPreferencesFn, getUnreadCountFn, listNotificationsFn } from '@/server/serverFns/notifications'
+import {
+  NOTIFICATION_LIST_KEY,
+  NOTIFICATION_POPOVER_KEY,
+  NOTIFICATION_PREFERENCES_KEY,
+  NOTIFICATION_ROOT_KEY,
+  NOTIFICATION_UNREAD_KEY,
+  notificationPreferencesQueryOptions,
+  notificationsListInfiniteQueryOptions,
+  notificationsPopoverUnreadQueryOptions,
+  notificationsUnreadQueryOptions,
+} from '../notifications'
+
+const mockedUnread = vi.mocked(getUnreadCountFn)
+const mockedPreferences = vi.mocked(getNotificationPreferencesFn)
+const mockedList = vi.mocked(listNotificationsFn)
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+/** queryFn 运行时恒存在（工厂必传），类型上可选故窄化；context 形状对齐 react-query v5 调用面 */
+function invokeQueryFn(
+  options: { queryFn?: (...args: never[]) => unknown },
+  ctx: unknown,
+): Promise<unknown> {
+  return (options.queryFn as (c: unknown) => Promise<unknown>)(ctx)
+}
+
+const queryCtx = (queryKey: readonly unknown[]) => ({
+  client: new QueryClient(),
+  queryKey,
+  signal: new AbortController().signal,
+  meta: undefined,
+})
+
+/** notifications key 结构零漂移：与迁移前 hooks/use-notifications.ts 常量逐字一致 */
+describe('notifications queryOptions key 结构', () => {
+  it('五个 key 常量与历史字面量逐字一致', () => {
+    expect(NOTIFICATION_ROOT_KEY).toEqual(['notifications'])
+    expect(NOTIFICATION_LIST_KEY).toEqual(['notifications', 'list'])
+    expect(NOTIFICATION_POPOVER_KEY).toEqual(['notifications', 'popover'])
+    expect(NOTIFICATION_UNREAD_KEY).toEqual(['notifications', 'unread'])
+    expect(NOTIFICATION_PREFERENCES_KEY).toEqual(['notifications', 'preferences'])
+  })
+
+  it('unread 工厂产出 NOTIFICATION_UNREAD_KEY 同一引用', () => {
+    expect(notificationsUnreadQueryOptions().queryKey).toBe(NOTIFICATION_UNREAD_KEY)
+  })
+
+  it('preferences 工厂产出 NOTIFICATION_PREFERENCES_KEY 同一引用', () => {
+    expect(notificationPreferencesQueryOptions().queryKey).toBe(NOTIFICATION_PREFERENCES_KEY)
+  })
+
+  it('popover 工厂 key 为 [...POPOVER, status, unread]（迁移前 nav-notifications 内联同形）', () => {
+    expect(notificationsPopoverUnreadQueryOptions().queryKey).toEqual([
+      'notifications',
+      'popover',
+      'status',
+      'unread',
+    ])
+  })
+
+  it('列表工厂 category 省略时 key 为 [...LIST, undefined]（迁移前 loader 预取同形）', () => {
+    expect(notificationsListInfiniteQueryOptions().queryKey).toEqual([
+      'notifications',
+      'list',
+      undefined,
+    ])
+  })
+
+  it('列表工厂 category 传入时追加到 key 尾位（迁移前 [...LIST, categoryFilter] 同形）', () => {
+    expect(notificationsListInfiniteQueryOptions('team').queryKey).toEqual([
+      'notifications',
+      'list',
+      'team',
+    ])
+  })
+})
+
+/** queryFn 接线：必须调用既有 serverFn 且 data 形状与迁移前内联写法逐字一致 */
+describe('notifications queryOptions queryFn 接线', () => {
+  it('unread → getUnreadCountFn({ data: {} })', async () => {
+    const options = notificationsUnreadQueryOptions()
+    await invokeQueryFn(options, queryCtx(options.queryKey))
+    expect(mockedUnread).toHaveBeenCalledWith({ data: {} })
+  })
+
+  it('preferences → getNotificationPreferencesFn({ data: {} })', async () => {
+    const options = notificationPreferencesQueryOptions()
+    await invokeQueryFn(options, queryCtx(options.queryKey))
+    expect(mockedPreferences).toHaveBeenCalledWith({ data: {} })
+  })
+
+  it('popover → listNotificationsFn({ data: { status: "unread" } })', async () => {
+    const options = notificationsPopoverUnreadQueryOptions()
+    await invokeQueryFn(options, queryCtx(options.queryKey))
+    expect(mockedList).toHaveBeenCalledWith({ data: { status: 'unread' } })
+  })
+
+  it('列表首页（无 category 无 cursor）→ listNotificationsFn({ data: {} })（迁移前 loader 同形）', async () => {
+    const options = notificationsListInfiniteQueryOptions()
+    await invokeQueryFn(options, {
+      ...queryCtx(options.queryKey),
+      pageParam: options.initialPageParam,
+      direction: 'forward',
+    })
+    expect(mockedList).toHaveBeenCalledWith({ data: {} })
+  })
+
+  it('列表带 category + cursor → listNotificationsFn({ data: { category, cursor } })（迁移前面板同形）', async () => {
+    const options = notificationsListInfiniteQueryOptions('team')
+    await invokeQueryFn(options, {
+      ...queryCtx(options.queryKey),
+      pageParam: 'c1',
+      direction: 'forward',
+    })
+    expect(mockedList).toHaveBeenCalledWith({ data: { category: 'team', cursor: 'c1' } })
+  })
+
+  it('initialPageParam 为 undefined（字符串游标）', () => {
+    expect(notificationsListInfiniteQueryOptions().initialPageParam).toBeUndefined()
+  })
+})
+
+/** getNextPageParam 防御边界（迁移自 loader 注释：hasMore=true 而 items 为空不抛 TypeError） */
+describe('notifications 列表 getNextPageParam', () => {
+  const options = notificationsListInfiniteQueryOptions()
+
+  const makeItem = (id: string): NotificationItem => ({
+    id,
+    category: 'system',
+    type: 'test',
+    title: 't',
+    body: null,
+    link: null,
+    readAt: null,
+    createdAt: '2026-01-01T00:00:00Z',
+  })
+  const makePage = (items: ReturnType<typeof makeItem>[]) => ({
+    items,
+    total: items.length,
+    hasMore: true,
+  })
+
+  it('hasMore=true 取最后一个 item 的 id', () => {
+    const page = makePage([makeItem('a'), makeItem('b')])
+    expect(options.getNextPageParam(page, [page], undefined, [undefined])).toBe('b')
+  })
+
+  it('hasMore=false 返回 undefined', () => {
+    const page = { ...makePage([makeItem('a')]), hasMore: false }
+    expect(options.getNextPageParam(page, [page], undefined, [undefined])).toBeUndefined()
+  })
+
+  it('hasMore=true 而 items 为空 → undefined（.at(-1) 防御，不抛 TypeError）', () => {
+    const page = makePage([])
+    expect(options.getNextPageParam(page, [page], undefined, [undefined])).toBeUndefined()
+  })
+})

package/src/lib/queries/__tests__/team-queries.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { QueryClient } from '@tanstack/react-query'
+
+vi.mock('@/server/serverFns/team', () => ({
+  listTeamMembersFn: vi.fn().mockResolvedValue([]),
+  listTeamInvitationsFn: vi.fn().mockResolvedValue({ invitations: [] }),
+  listTeamUsersFn: vi.fn().mockResolvedValue([]),
+  createTeamInvitationFn: vi.fn(),
+  refreshTeamInvitationLinkFn: vi.fn(),
+  revokeTeamInvitationFn: vi.fn(),
+  resendTeamInvitationFn: vi.fn(),
+  approveTeamInvitationFn: vi.fn(),
+  approveTeamJoinRequestFn: vi.fn(),
+  rejectTeamJoinRequestFn: vi.fn(),
+  deleteTeamInvitationFn: vi.fn(),
+  deleteTeamJoinRequestFn: vi.fn(),
+  removeTeamMemberFn: vi.fn(),
+  leaveTeamFn: vi.fn(),
+  clearExpiredInvitationsFn: vi.fn(),
+}))
+
+import { listTeamInvitationsFn, listTeamMembersFn, listTeamUsersFn } from '@/server/serverFns/team'
+import {
+  TEAM_INVITATIONS_QUERY_KEY,
+  TEAM_MEMBERS_QUERY_KEY,
+  TEAM_USERS_QUERY_KEY,
+  teamInvitationsQueryOptions,
+  teamMembersQueryOptions,
+  teamUsersQueryOptions,
+} from '../team'
+
+const mockedMembers = vi.mocked(listTeamMembersFn)
+const mockedInvitations = vi.mocked(listTeamInvitationsFn)
+const mockedUsers = vi.mocked(listTeamUsersFn)
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+/** queryFn 运行时恒存在（工厂必传），类型上可选故窄化；context 形状对齐 react-query v5 调用面 */
+function invokeQueryFn(
+  options: { queryFn?: (...args: never[]) => unknown },
+  queryKey: readonly unknown[],
+): Promise<unknown> {
+  return (options.queryFn as (c: unknown) => Promise<unknown>)({
+    client: new QueryClient(),
+    queryKey,
+    signal: new AbortController().signal,
+    meta: undefined,
+  })
+}
+
+/** team key 结构零漂移：与迁移前 team-client.tsx 内联字面量逐字一致（此前无常量，自此收敛单一来源） */
+describe('team queryOptions key 结构', () => {
+  it('三个 key 常量与历史内联字面量逐字一致', () => {
+    expect(TEAM_MEMBERS_QUERY_KEY).toEqual(['teamMembers'])
+    expect(TEAM_INVITATIONS_QUERY_KEY).toEqual(['teamInvitations'])
+    expect(TEAM_USERS_QUERY_KEY).toEqual(['teamUsers'])
+  })
+
+  it('各工厂产出对应常量同一引用（invalidate 与 useQuery 同源）', () => {
+    expect(teamMembersQueryOptions().queryKey).toBe(TEAM_MEMBERS_QUERY_KEY)
+    expect(teamInvitationsQueryOptions().queryKey).toBe(TEAM_INVITATIONS_QUERY_KEY)
+    expect(teamUsersQueryOptions().queryKey).toBe(TEAM_USERS_QUERY_KEY)
+  })
+})
+
+/** queryFn 接线：必须调用既有 serverFn 且无参形态与迁移前内联写法一致 */
+describe('team queryOptions queryFn 接线', () => {
+  it('members → listTeamMembersFn()（无参）', async () => {
+    const options = teamMembersQueryOptions()
+    await invokeQueryFn(options, options.queryKey)
+    expect(mockedMembers).toHaveBeenCalledWith()
+  })
+
+  it('invitations → listTeamInvitationsFn()（无参）', async () => {
+    const options = teamInvitationsQueryOptions()
+    await invokeQueryFn(options, options.queryKey)
+    expect(mockedInvitations).toHaveBeenCalledWith()
+  })
+
+  it('users → listTeamUsersFn()（无参）', async () => {
+    const options = teamUsersQueryOptions()
+    await invokeQueryFn(options, options.queryKey)
+    expect(mockedUsers).toHaveBeenCalledWith()
+  })
+})

package/src/lib/queries/agents.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// agents 模块 queryOptions 工厂（key + queryFn 单一来源）。
+// 消费方（组件 useQuery / invalidate / setQueryData）一律从本模块取，
+// 禁止再写 ['agents'] 等内联字面量。模式说明见 ./README.md。
+import { queryOptions } from '@tanstack/react-query'
+import { listAgentsFn } from '@/server/serverFns/agents/agent-crud'
+import { listSkillsFn } from '@/server/serverFns/agents/skill-crud'
+import { listBindingsFn, getPersonaHintFn } from '@/server/serverFns/agents/bindings'
+
+export const AGENTS_QUERY_KEY = ['agents'] as const
+export const SKILLS_QUERY_KEY = ['skills'] as const
+export const AGENT_BINDINGS_QUERY_KEY = ['agent-bindings'] as const
+export const PERSONA_HINT_QUERY_KEY = ['persona-hint'] as const
+
+export const agentsQueryOptions = () =>
+  queryOptions({
+    queryKey: AGENTS_QUERY_KEY,
+    queryFn: () => listAgentsFn(),
+  })
+
+export const skillsQueryOptions = () =>
+  queryOptions({
+    queryKey: SKILLS_QUERY_KEY,
+    queryFn: () => listSkillsFn(),
+  })
+
+export const agentBindingsQueryOptions = () =>
+  queryOptions({
+    queryKey: AGENT_BINDINGS_QUERY_KEY,
+    queryFn: () => listBindingsFn(),
+  })
+
+export const personaHintQueryOptions = () =>
+  queryOptions({
+    queryKey: PERSONA_HINT_QUERY_KEY,
+    queryFn: () => getPersonaHintFn(),
+  })

package/src/lib/queries/compliance.ts

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// compliance 模块 queryOptions 工厂（key + queryFn 单一来源）。
+// 审计点名的双份维护税：detail / favorite-ids 的 key 字面量曾在
+// $id.lazy.tsx 的 useQuery 与 LegalDetailActions props 各持一份靠人工对齐；
+// 现在两处都从本模块取 factory().queryKey，编译期防漂移。
+// entity-tags / favorite-ids 的 entityType 参数化了 legal / compliance /
+// dictionary 共用族（laws / dictionary 渐进迁移见 ./README.md）。
+import { keepPreviousData, queryOptions } from '@tanstack/react-query'
+import { listComplianceFn } from '@/server/serverFns/knowledge/public/compliance/list'
+import { getComplianceDetailFn } from '@/server/serverFns/knowledge/public/compliance/detail'
+import { getEntityTagsFn } from '@/server/serverFns/knowledge/public/entity-tags'
+import { getFavoriteIdsFn } from '@/server/serverFns/knowledge/public/favorite'
+
+export type ComplianceScope = 'all' | 'private' | 'share' | 'favorite'
+
+export const COMPLIANCE_LIST_KEY = ['compliance'] as const
+export const ENTITY_TAGS_KEY = ['entity-tags'] as const
+export const FAVORITE_IDS_KEY = ['favorite-ids'] as const
+
+export interface ComplianceListFilters {
+  scope: ComplianceScope
+  search?: string
+  industry?: string
+  tag?: string
+}
+
+export const complianceListQueryOptions = (filters: ComplianceListFilters) =>
+  queryOptions({
+    queryKey: [
+      ...COMPLIANCE_LIST_KEY,
+      filters.scope,
+      filters.search,
+      filters.industry,
+      filters.tag,
+    ],
+    queryFn: () =>
+      listComplianceFn({
+        data: {
+          scope: filters.scope,
+          search: filters.search || undefined,
+          industry: filters.industry,
+          tag: filters.tag || undefined,
+        },
+      }),
+    placeholderData: keepPreviousData,
+  })
+
+export const complianceDetailQueryOptions = (id: string) =>
+  queryOptions({
+    queryKey: ['compliance-detail', id] as const,
+    queryFn: () => getComplianceDetailFn({ data: { id } }),
+  })
+
+export const entityTagsQueryOptions = (entityType: 'legal' | 'compliance' | 'dictionary') =>
+  queryOptions({
+    queryKey: [...ENTITY_TAGS_KEY, entityType] as const,
+    queryFn: () => getEntityTagsFn({ data: { entityType } }),
+  })
+
+export const favoriteIdsQueryOptions = (
+  entityType: 'legal' | 'compliance' | 'dictionary' | 'bookmark',
+) =>
+  queryOptions({
+    queryKey: [...FAVORITE_IDS_KEY, entityType] as const,
+    queryFn: () => getFavoriteIdsFn({ data: { entityType } }),
+  })

package/src/lib/queries/notifications.ts

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// notifications 模块 queryOptions 工厂（key + queryFn 单一来源）。
+//
+// key 常量原本散在 hooks/use-notifications.ts（NOTIFICATION_*）与
+// settings-notifications.tsx（preferences 内联字面量），消费方（loader prefetch
+// / 组件 useQuery / invalidate / setQueryData）一律从本模块取，禁止再写内联
+// 字面量。模式说明见 ./README.md。
+import { infiniteQueryOptions, queryOptions } from '@tanstack/react-query'
+import type { NotificationCategory, NotificationListResult } from '@allbluecn/kernel'
+import {
+  getNotificationPreferencesFn,
+  getUnreadCountFn,
+  listNotificationsFn,
+} from '@/server/serverFns/notifications'
+
+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
+
+/** 未读数（SSE setQueryData 写入目标；loader SSR 预取 + 铃铛消费） */
+export const notificationsUnreadQueryOptions = () =>
+  queryOptions({
+    queryKey: NOTIFICATION_UNREAD_KEY,
+    queryFn: () => getUnreadCountFn({ data: {} }),
+  })
+
+/** 通知偏好（settings 面板读写 + useNotifications 预热供 DND 判断） */
+export const notificationPreferencesQueryOptions = () =>
+  queryOptions({
+    queryKey: NOTIFICATION_PREFERENCES_KEY,
+    queryFn: () => getNotificationPreferencesFn({ data: {} }),
+  })
+
+/** 铃铛 popover 未读列表（非分页形态，与列表查询必须独立 key） */
+export const notificationsPopoverUnreadQueryOptions = () =>
+  queryOptions({
+    queryKey: [...NOTIFICATION_POPOVER_KEY, 'status', 'unread'] as const,
+    queryFn: () => listNotificationsFn({ data: { status: 'unread' } }),
+  })
+
+/**
+ * 通知列表（分页 + 分类过滤）。
+ * category 传 undefined 表示「全部」（与旧 [...NOTIFICATION_LIST_KEY, undefined] 同形）。
+ */
+export const notificationsListInfiniteQueryOptions = (category?: NotificationCategory) =>
+  infiniteQueryOptions({
+    queryKey: [...NOTIFICATION_LIST_KEY, category],
+    queryFn: ({ pageParam }) => {
+      const base = category ? { category } : {}
+      return listNotificationsFn({
+        data: pageParam ? { ...base, cursor: pageParam } : base,
+      })
+    },
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (lastPage: NotificationListResult) =>
+      // .at(-1) 防御 hasMore=true 而 items 为空的服务端边界 bug（[-1].id 会抛 TypeError）
+      lastPage.hasMore ? lastPage.items.at(-1)?.id : undefined,
+  })

package/src/lib/queries/team.ts

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// team 模块 queryOptions 工厂（key + queryFn 单一来源）。
+// 消费方（组件 useQuery / invalidate）一律从本模块取，禁止再写
+// ['teamMembers'] 等内联字面量。模式说明见 ./README.md。
+//
+// ⚠ tiptap mention-dropdown-menu 的 ['teamUsers'] 是另一数据源
+// （编辑器 mentionUserSource），与本工厂同 key 不同 queryFn，属既有
+// 缓存共键碰撞，迁移时禁止单方面改其一（缓存行为会漂移）。
+import { queryOptions } from '@tanstack/react-query'
+import {
+  listTeamMembersFn,
+  listTeamInvitationsFn,
+  listTeamUsersFn,
+} from '@/server/serverFns/team'
+
+export const TEAM_MEMBERS_QUERY_KEY = ['teamMembers'] as const
+export const TEAM_INVITATIONS_QUERY_KEY = ['teamInvitations'] as const
+export const TEAM_USERS_QUERY_KEY = ['teamUsers'] as const
+
+export const teamMembersQueryOptions = () =>
+  queryOptions({
+    queryKey: TEAM_MEMBERS_QUERY_KEY,
+    queryFn: () => listTeamMembersFn(),
+  })
+
+export const teamInvitationsQueryOptions = () =>
+  queryOptions({
+    queryKey: TEAM_INVITATIONS_QUERY_KEY,
+    queryFn: () => listTeamInvitationsFn(),
+  })
+
+export const teamUsersQueryOptions = () =>
+  queryOptions({
+    queryKey: TEAM_USERS_QUERY_KEY,
+    queryFn: () => listTeamUsersFn(),
+  })

package/src/lib/query-defaults.ts

@@ -0,0 +1,8 @@
+// 全局查询默认 staleTime：30 秒（毫秒常量）。
+// - 30s 内纯导航：loader 的 ensureQueryData / useQuery 命中缓存不重跑
+// - mutation 后 invalidateQueries 不受 staleTime 阻断：显式失效把 fresh 数据
+//   标记为 stale，active 查询立即 refetch、非 active 查询在下次访问时重拉
+// - SSR：水合数据携带服务端 dataUpdatedAt，30s 窗口内客户端不重复请求（期望行为）
+// 单一来源：router.tsx 的 defaultOptions 与协同测试
+// （lib/__tests__/query-defaults.test.ts）共同引用本常量。
+export const QUERY_STALE_TIME_MS = 30_000