@allbluecn/web-app 0.22.4 → 0.23.1

package/src/lib/__tests__/query-global-error.test.ts

@@ -0,0 +1,256 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { MutationCache, QueryCache, QueryClient } from '@tanstack/react-query'
+import { m } from '@/paraglide/messages.js'
+import { toast } from '@/components/ui/toast'
+import {
+  handleGlobalMutationError,
+  handleGlobalQueryError,
+} from '../query-global-error'
+
+vi.mock('@/components/ui/toast', () => ({
+  toast: { error: vi.fn() },
+}))
+
+function makeRouter() {
+  const navigate = vi.fn()
+  // 结构桩仅含 handler 实际消费的字段，与既有 anonymous-safe.test.ts 同口径 as never
+  const router = {
+    state: { location: { pathname: '/prd', searchStr: '?tab=all' } },
+    navigate,
+  } as never
+  return { router, navigate }
+}
+
+/** 构建一个直接失败的 query 并触发其 fetch（retry: false 免去重试延迟） */
+async function fetchFailingQuery(
+  queryCache: QueryCache,
+  client: QueryClient,
+  options: { error: unknown; meta?: Record<string, unknown> },
+) {
+  const query = queryCache.build(client, {
+    queryKey: ['test-global-error'],
+    queryFn: () => Promise.reject(options.error),
+    retry: false,
+    meta: options.meta,
+  })
+  await query.fetch().catch(() => undefined)
+}
+
+/** 构建并执行一个直接失败的 mutation */
+async function executeFailingMutation(
+  mutationCache: MutationCache,
+  client: QueryClient,
+  options: { error: unknown; meta?: Record<string, unknown> },
+) {
+  const mutation = mutationCache.build(client, {
+    mutationFn: () => Promise.reject(options.error),
+    meta: options.meta,
+  })
+  await mutation.execute(undefined as never).catch(() => undefined)
+}
+
+beforeEach(() => {
+  vi.mocked(toast.error).mockClear()
+})
+
+describe('QueryCache 全局 onError（web）', () => {
+  it('401 查询错误跳登录（带回跳）且不 toast', async () => {
+    const { router, navigate } = makeRouter()
+    const queryCache = new QueryCache({
+      onError: (error, query) => handleGlobalQueryError(error, query, router),
+    })
+    const client = new QueryClient({ queryCache })
+    await fetchFailingQuery(queryCache, client, {
+      error: new Error('UNAUTHORIZED'),
+    })
+    expect(navigate).toHaveBeenCalledWith({
+      to: '/login',
+      search: { redirect: '/prd?tab=all' },
+    })
+    expect(toast.error).not.toHaveBeenCalled()
+  })
+
+  it('4xx（非 401）toast 展示错误详情', async () => {
+    const { router, navigate } = makeRouter()
+    const queryCache = new QueryCache({
+      onError: (error, query) => handleGlobalQueryError(error, query, router),
+    })
+    const client = new QueryClient({ queryCache })
+    await fetchFailingQuery(queryCache, client, {
+      error: Object.assign(new Error('没有权限'), { status: 403 }),
+    })
+    expect(toast.error).toHaveBeenCalledWith('没有权限')
+    expect(navigate).not.toHaveBeenCalled()
+  })
+
+  it('5xx toast 通用文案（不透出服务端错误详情）', async () => {
+    const { router } = makeRouter()
+    const queryCache = new QueryCache({
+      onError: (error, query) => handleGlobalQueryError(error, query, router),
+    })
+    const client = new QueryClient({ queryCache })
+    await fetchFailingQuery(queryCache, client, {
+      error: Object.assign(new Error('Internal Server Error'), {
+        statusCode: 500,
+      }),
+    })
+    expect(toast.error).toHaveBeenCalledWith(m.common_error_generic())
+  })
+
+  it('网络错误（无 status）toast 通用文案', async () => {
+    const { router } = makeRouter()
+    const queryCache = new QueryCache({
+      onError: (error, query) => handleGlobalQueryError(error, query, router),
+    })
+    const client = new QueryClient({ queryCache })
+    await fetchFailingQuery(queryCache, client, {
+      error: new TypeError('Failed to fetch'),
+    })
+    expect(toast.error).toHaveBeenCalledWith(m.common_error_generic())
+  })
+
+  it('query meta.suppressGlobalToast=true 时全局 onError 不出手（防双 toast）', async () => {
+    const { router, navigate } = makeRouter()
+    const queryCache = new QueryCache({
+      onError: (error, query) => handleGlobalQueryError(error, query, router),
+    })
+    const client = new QueryClient({ queryCache })
+    await fetchFailingQuery(queryCache, client, {
+      error: Object.assign(new Error('没有权限'), { status: 403 }),
+      meta: { suppressGlobalToast: true },
+    })
+    expect(toast.error).not.toHaveBeenCalled()
+    expect(navigate).not.toHaveBeenCalled()
+  })
+
+  it('error 对象自带 meta.suppressGlobalToast 同样抑制 toast', async () => {
+    const { router } = makeRouter()
+    const queryCache = new QueryCache({
+      onError: (error, query) => handleGlobalQueryError(error, query, router),
+    })
+    const client = new QueryClient({ queryCache })
+    await fetchFailingQuery(queryCache, client, {
+      error: Object.assign(new Error('没有权限'), {
+        status: 403,
+        meta: { suppressGlobalToast: true },
+      }),
+    })
+    expect(toast.error).not.toHaveBeenCalled()
+  })
+
+  it('查询取消（CancelledError）不 toast 不跳转', async () => {
+    const { router, navigate } = makeRouter()
+    const queryCache = new QueryCache({
+      onError: (error, query) => handleGlobalQueryError(error, query, router),
+    })
+    const client = new QueryClient({ queryCache })
+    await fetchFailingQuery(queryCache, client, {
+      error: new Error('CancelledError'),
+    })
+    expect(toast.error).not.toHaveBeenCalled()
+    expect(navigate).not.toHaveBeenCalled()
+  })
+
+  it('SSR（window 缺失）不跳转不 toast', async () => {
+    vi.stubGlobal('window', undefined)
+    try {
+      const { router, navigate } = makeRouter()
+      const queryCache = new QueryCache({
+        onError: (error, query) => handleGlobalQueryError(error, query, router),
+      })
+      const client = new QueryClient({ queryCache })
+      await fetchFailingQuery(queryCache, client, {
+        error: new Error('UNAUTHORIZED'),
+      })
+      await fetchFailingQuery(queryCache, client, {
+        error: Object.assign(new Error('没有权限'), { status: 403 }),
+      })
+      expect(navigate).not.toHaveBeenCalled()
+      expect(toast.error).not.toHaveBeenCalled()
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+})
+
+describe('MutationCache 全局 onError（web 补齐对称面）', () => {
+  it('401 变更错误跳登录（保留既有逻辑）', async () => {
+    const { router, navigate } = makeRouter()
+    const mutationCache = new MutationCache({
+      onError: (error, _variables, _onMutateResult, mutation) =>
+        handleGlobalMutationError(error, mutation, router),
+    })
+    const client = new QueryClient({ mutationCache })
+    await executeFailingMutation(mutationCache, client, {
+      error: new Error('UNAUTHORIZED'),
+    })
+    expect(navigate).toHaveBeenCalledWith({
+      to: '/login',
+      search: { redirect: '/prd?tab=all' },
+    })
+    expect(toast.error).not.toHaveBeenCalled()
+  })
+
+  it('非 401 变更错误 toast 详情（403）', async () => {
+    const { router, navigate } = makeRouter()
+    const mutationCache = new MutationCache({
+      onError: (error, _variables, _onMutateResult, mutation) =>
+        handleGlobalMutationError(error, mutation, router),
+    })
+    const client = new QueryClient({ mutationCache })
+    await executeFailingMutation(mutationCache, client, {
+      error: Object.assign(new Error('配额不足'), { status: 403 }),
+    })
+    expect(toast.error).toHaveBeenCalledWith('配额不足')
+    expect(navigate).not.toHaveBeenCalled()
+  })
+
+  it('5xx 变更错误 toast 通用文案', async () => {
+    const { router } = makeRouter()
+    const mutationCache = new MutationCache({
+      onError: (error, _variables, _onMutateResult, mutation) =>
+        handleGlobalMutationError(error, mutation, router),
+    })
+    const client = new QueryClient({ mutationCache })
+    await executeFailingMutation(mutationCache, client, {
+      error: Object.assign(new Error('Bad Gateway'), { status: 502 }),
+    })
+    expect(toast.error).toHaveBeenCalledWith(m.common_error_generic())
+  })
+
+  it('mutation options.meta.suppressGlobalToast=true 时全局 onError 不出手', async () => {
+    const { router } = makeRouter()
+    const mutationCache = new MutationCache({
+      onError: (error, _variables, _onMutateResult, mutation) =>
+        handleGlobalMutationError(error, mutation, router),
+    })
+    const client = new QueryClient({ mutationCache })
+    await executeFailingMutation(mutationCache, client, {
+      error: Object.assign(new Error('配额不足'), { status: 403 }),
+      meta: { suppressGlobalToast: true },
+    })
+    expect(toast.error).not.toHaveBeenCalled()
+  })
+
+  it('SSR（window 缺失）不跳转不 toast', async () => {
+    vi.stubGlobal('window', undefined)
+    try {
+      const { router, navigate } = makeRouter()
+      const mutationCache = new MutationCache({
+        onError: (error, _variables, _onMutateResult, mutation) =>
+          handleGlobalMutationError(error, mutation, router),
+      })
+      const client = new QueryClient({ mutationCache })
+      await executeFailingMutation(mutationCache, client, {
+        error: new Error('UNAUTHORIZED'),
+      })
+      await executeFailingMutation(mutationCache, client, {
+        error: Object.assign(new Error('配额不足'), { status: 403 }),
+      })
+      expect(navigate).not.toHaveBeenCalled()
+      expect(toast.error).not.toHaveBeenCalled()
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+})

package/src/lib/anyhub/anyhub-store.ts

@@ -16,7 +16,7 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { Store } from '@tanstack/store'
-import { useStore } from '@tanstack/react-store'
+import { useSelector } from '@tanstack/react-store'
 import type { AnyHubAppData, AnyHubMarketAppData } from './types'
 import { listAnyHubAppsFn, listMarketplaceAppsFn, togglePinFn } from '@/server/serverFns/anyhub/index'
 import { installAnyHubAppFn } from '@/server/serverFns/anyhub/install'
@@ -41,7 +41,7 @@ export const anyHubStore = new Store<AnyHubState>({
 })
 
 export function useAnyHubStore<T>(selector: (state: AnyHubState) => T): T {
-  return useStore(anyHubStore, selector)
+  return useSelector(anyHubStore, selector)
 }
 
 export const anyHubActions = {

package/src/lib/changelog/sdk-versions.ts

@@ -87,14 +87,6 @@ export const SDK_GROUPS: SdkGroup[] = [
         "source": "apps/admin/package.json#dependencies",
         "docsUrl": "https://tanstack.com/virtual/latest"
       },
-      {
-        "name": "@tanstack/db",
-        "displayName": "TanStack DB",
-        "version": "v1.0.0-rc.1",
-        "lastUpdate": "Oct 30, 2026",
-        "source": "apps/web/package.json#dependencies",
-        "docsUrl": "https://tanstack.com/db/latest"
-      },
       {
         "name": "@tanstack/store",
         "displayName": "TanStack Store",
@@ -120,8 +112,8 @@ export const SDK_GROUPS: SdkGroup[] = [
     "items": [
       {
         "name": "@allbluecn/web-app",
-        "version": "v0.22.4",
-        "lastUpdate": "Oct 31, 2026",
+        "version": "v0.23.1",
+        "lastUpdate": "Nov 1, 2026",
         "source": "apps/web/package.json",
         "docsUrl": "https://github.com/allbluecn/allblue"
       },

package/src/lib/collab/presence-store.ts

@@ -33,7 +33,7 @@
 // 重建）。
 
 import { Store } from '@tanstack/store'
-import { useStore } from '@tanstack/react-store'
+import { useSelector } from '@tanstack/react-store'
 
 // ---------------------------------------------------------------------------
 // 类型（§8.1 awareness state schema 逐字）
@@ -250,7 +250,7 @@ export function __resetPresenceStoreForTests(): void {
 // hooks（任务 10 消费面）
 // ---------------------------------------------------------------------------
 
-/** 浅比较数组（元素引用级）：selector 产出新数组时避免 useStore 死循环 */
+/** 浅比较数组（元素引用级）：selector 产出新数组时避免死循环重渲染 */
 function areStateListsEqual(a: readonly PresenceState[], b: readonly PresenceState[]): boolean {
   if (a === b) return true
   if (a.length !== b.length) return false
@@ -317,7 +317,7 @@ export function useTeammates(
   selfId?: string | null,
   equality: (a: PresenceState[], b: PresenceState[]) => boolean = areStateListsEqual,
 ): PresenceState[] {
-  return useStore(
+  return useSelector(
     presenceStore,
     (state) => {
       const list = [...state.teammates.values()].filter(
@@ -325,7 +325,7 @@ export function useTeammates(
       )
       return selector ? selector(list) : list
     },
-    equality,
+    { compare: equality },
   )
 }
 
@@ -346,5 +346,5 @@ export function byModule(module: PresenceModule): (list: PresenceState[]) => Pre
 
 /** 订阅 presence 连接状态（降级 UI 用：offline → 不渲染头像组） */
 export function usePresenceStatus(): PresenceStatus {
-  return useStore(presenceStore, (state) => state.status)
+  return useSelector(presenceStore, (state) => state.status)
 }

package/src/lib/collab/use-presence-list-refresh.ts

@@ -43,7 +43,7 @@
 // isEntityViewer。
 
 import { useEffect, useRef } from 'react'
-import { useStore } from '@tanstack/react-store'
+import { useSelector } from '@tanstack/react-store'
 import { useDebouncedCallback } from '@/lib/pacer'
 import { presenceStore } from './presence-store'
 import { MODULE_ROUTES } from './module-map'
@@ -98,7 +98,7 @@ export function usePresenceListRefresh({
   // Object.is 值相等），心跳式全量重建（id+route 不变的新对象）不再触发
   // 挂载组件（StoryListView 等重型列表体）的空转重渲染。模块过滤收进
   // selector（原 byModule 前置口径不变），跨模块 presence 噪声不进签名。
-  const signature = useStore(
+  const signature = useSelector(
     presenceStore,
     (state) =>
       entityViewersSignature(

package/src/lib/collab/use-share-presence.ts

@@ -44,7 +44,7 @@
 
 import { useEffect, useMemo } from 'react'
 import { Store } from '@tanstack/store'
-import { useStore } from '@tanstack/react-store'
+import { useSelector } from '@tanstack/react-store'
 import { m } from '@/paraglide/messages.js'
 import { createSharePresenceTicketFn } from '@/server/serverFns/collab'
 import { destroyProvider, getOrCreateProvider } from './provider'
@@ -534,7 +534,7 @@ export function useSharePresence(
     }
   }, [shareToken, designId, designver])
 
-  const state = useStore(sharePresenceStore, (s) => s)
+  const state = useSelector(sharePresenceStore, (s) => s)
 
   const { members, guests } = useMemo(() => {
     const members: SharePresencePerson[] = []

package/src/lib/collections/query-keys.ts

@@ -4,12 +4,17 @@
 
 // React Query key 常量（零依赖纯模块）。
 //
-// 为什么单独成文件：collection 模块在**模块作用域**执行
+// 为什么单独成文件（历史）：原 DB collection 模块在**模块作用域**执行
 // `createCollection({ ... queryClient: getQueryClient() })`，而 getQueryClient()
 // 在 SSR 未注入时 fail-fast（防跨请求缓存串染）。路由文件（如 _nav/route.tsx）
 // 只需要 key 常量做 prefetch，却值引入 collection 模块 → SSR 模块初始化阶段
 // 就触发 getQueryClient()，早于 router.tsx 的 setQueryClient，全站 500。
-// 消费方一律从本模块取 key；collection 模块转 re-export 保持兼容。
+// 现状：collection 模块与 @tanstack/db / query-db-collection 已于 2026-10-31
+// 删除/卸载（TanStack 优化计划 T28），本文件为现存消费方（_nav/route.tsx 预取、
+// sidebar nav-workspace / nav-knowledge）保留，仍保持零依赖（路由只为取 key，
+// 不应牵连任何模块作用域副作用）。新查询不再往这里加 key：走 lib/queries/ 的
+// xxxQueryOptions 工厂（AGENTS.md「新查询必须走 queryOptions 工厂单一来源」），
+// 本文件存量随触碰迁移。
 export const WORKSPACES_QUERY_KEY = ['workspaces'] as const
 export const KNOWLEDGE_BASES_QUERY_KEY = ['knowledge-bases'] as const
 export const PROJECTS_QUERY_KEY = ['projects'] as const

package/src/lib/commands/__tests__/command-palette-state.test.ts

@@ -18,8 +18,6 @@
 import { describe, it, expect, vi, beforeEach } from "vitest"
 import {
   commandPaletteStore,
-  getCommandPaletteSnapshot,
-  subscribeCommandPalette,
   setCommandPaletteOpen,
   toggleCommandPalette,
 } from "../command-palette-state"
@@ -30,39 +28,39 @@ describe("command-palette-state", () => {
   })
 
   it("初始状态为关闭", () => {
-    expect(getCommandPaletteSnapshot()).toBe(false)
+    expect(commandPaletteStore.get()).toBe(false)
   })
 
   it("setCommandPaletteOpen 更新快照并通知订阅者", () => {
     const listener = vi.fn()
-    const unsub = subscribeCommandPalette(listener)
+    const sub = commandPaletteStore.subscribe(listener)
     setCommandPaletteOpen(true)
-    expect(getCommandPaletteSnapshot()).toBe(true)
+    expect(commandPaletteStore.get()).toBe(true)
     expect(listener).toHaveBeenCalledTimes(1)
-    unsub()
+    sub.unsubscribe()
   })
 
   it("toggleCommandPalette 翻转状态", () => {
     toggleCommandPalette()
-    expect(getCommandPaletteSnapshot()).toBe(true)
+    expect(commandPaletteStore.get()).toBe(true)
     toggleCommandPalette()
-    expect(getCommandPaletteSnapshot()).toBe(false)
+    expect(commandPaletteStore.get()).toBe(false)
   })
 
   it("订阅后取消订阅不再收到通知", () => {
     const listener = vi.fn()
-    const unsub = subscribeCommandPalette(listener)
-    unsub()
+    const sub = commandPaletteStore.subscribe(listener)
+    sub.unsubscribe()
     setCommandPaletteOpen(true)
     expect(listener).not.toHaveBeenCalled()
   })
 
-  it("getCommandPaletteSnapshot 引用稳定（相同状态返回同一 boolean）", () => {
-    expect(getCommandPaletteSnapshot()).toBe(getCommandPaletteSnapshot())
+  it("get 引用稳定（相同状态返回同一 boolean）", () => {
+    expect(commandPaletteStore.get()).toBe(commandPaletteStore.get())
   })
 
-  it("commandPaletteStore 暴露 useSyncExternalStore 兼容接口", () => {
+  it("commandPaletteStore 暴露官方 Store 接口（useSelector 兼容）", () => {
     expect(commandPaletteStore.subscribe).toBeTypeOf("function")
-    expect(commandPaletteStore.getSnapshot).toBeTypeOf("function")
+    expect(commandPaletteStore.get).toBeTypeOf("function")
   })
 })

package/src/lib/commands/__tests__/registry.test.ts

@@ -17,7 +17,7 @@
 
 import { describe, it, expect } from "vitest"
 import { COMMAND_REGISTRY, getSequencePairs } from "../registry"
-import { HOTKEY_REGISTRY } from "../../hotkeys/registry"
+import { appHotkeys } from "../../hotkeys/registry"
 
 const KNOWN_ROUTES = new Set([
   "/dashboard",
@@ -81,13 +81,16 @@ describe("COMMAND_REGISTRY", () => {
   })
 })
 
-describe("COMMAND_REGISTRY ↔ HOTKEY_REGISTRY 跨表一致性", () => {
+describe("COMMAND_REGISTRY ↔ appHotkeys 跨表一致性", () => {
   it("序列键集合一致", () => {
     const cmdSeq = new Set(
       COMMAND_REGISTRY.filter((c) => c.shortcut).map((c) => c.shortcut!.join(" "))
     )
     const hkSeq = new Set(
-      HOTKEY_REGISTRY.filter((h) => h.keys.includes(" ")).map((h) => h.keys)
+      Object.values(appHotkeys)
+        .filter((entry): entry is typeof entry & { hotkey: ReadonlyArray<string> } =>
+          Array.isArray(entry.hotkey))
+        .map((entry) => entry.hotkey.join(" "))
     )
     expect(cmdSeq).toEqual(hkSeq)
   })

package/src/lib/commands/command-palette-state.ts

@@ -15,42 +15,19 @@
 // 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/>.
 
-export interface CommandPaletteStore {
-  subscribe: (listener: () => void) => () => void
-  getSnapshot: () => boolean
-}
-
-let open = false
-const listeners = new Set<() => void>()
-
-function emit() {
-  for (const listener of listeners) listener()
-}
+import { Store } from '@tanstack/store'
 
-export const commandPaletteStore: CommandPaletteStore = {
-  subscribe(listener: () => void) {
-    listeners.add(listener)
-    return () => {
-      listeners.delete(listener)
-    }
-  },
-  getSnapshot: () => open,
-}
-
-export function subscribeCommandPalette(listener: () => void) {
-  return commandPaletteStore.subscribe(listener)
-}
+// 命令面板开关全局单例（任务 25：手写 useSyncExternalStore store 迁官方
+// Store，与 anyhub-store 同构）。初始值模块级 false 且仅由客户端交互
+// （热键/菜单/侧栏触发器）经 setState 变更，SSR 渲染期间恒为 false——
+// useSelector 以 get() 同时充当 server snapshot，无 hydration 差异。
 
-export function getCommandPaletteSnapshot() {
-  return commandPaletteStore.getSnapshot()
-}
+export const commandPaletteStore = new Store<boolean>(false)
 
 export function setCommandPaletteOpen(next: boolean) {
-  if (open === next) return
-  open = next
-  emit()
+  commandPaletteStore.setState(() => next)
 }
 
 export function toggleCommandPalette() {
-  setCommandPaletteOpen(!open)
+  setCommandPaletteOpen(!commandPaletteStore.get())
 }

package/src/lib/hotkeys/__tests__/registry.test.ts

@@ -16,31 +16,84 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { describe, it, expect } from "vitest"
-import { HOTKEY_REGISTRY, CATEGORY_ORDER, getHotkeysByCategory } from "../registry"
+import { checkHotkey } from "@tanstack/hotkeys"
 
-describe("HOTKEY_REGISTRY", () => {
-  it("快捷键组合（keys 字段整体）不重复", () => {
-    const keys = HOTKEY_REGISTRY.map((h) => h.keys)
-    expect(new Set(keys).size).toBe(keys.length)
+import { appHotkeys, findAppHotkeyConflicts, formatAppHotkeyForBadge, CATEGORY_ORDER, type AppHotkeyId } from "../registry"
+
+const DECLARED_IDS = Object.keys(appHotkeys) as AppHotkeyId[]
+
+describe("appHotkeys（defineAppHotkeys 官方声明）", () => {
+  it("恰好 25 条声明，且 id 与迁移前注册表对齐", () => {
+    expect(DECLARED_IDS).toHaveLength(25)
+    expect(DECLARED_IDS).toEqual(
+      expect.arrayContaining([
+        "shortcuts-panel",
+        "toggle-sidebar",
+        "save",
+        "close-panel",
+        "copy-message",
+        "chat-prev",
+        "chat-next",
+        "command-palette",
+        "toggle-theme",
+        "goto-dashboard",
+        "goto-chat",
+        "goto-agents",
+        "goto-inspiration",
+        "goto-stories",
+        "goto-prd",
+        "goto-design",
+        "goto-test-cases",
+        "goto-bugs",
+        "goto-knowledge",
+        "goto-anyhub",
+        "goto-workspaces",
+        "goto-settings",
+        "create-prd-hk",
+        "create-conversation-hk",
+        "create-story-hk",
+      ]),
+    )
   })
 
-  it("序列键条目 keys 为空格分隔的两键（如 'G D'）", () => {
-    const seqKeys = HOTKEY_REGISTRY.filter((h) => h.keys.includes(" "))
-    expect(seqKeys.length).toBeGreaterThanOrEqual(16)
-    for (const h of seqKeys) {
-      expect(h.keys.split(" ")).toHaveLength(2)
+  it("每条声明都是合法组合键（官方 validateHotkey），且 meta 完整（descriptionKey + category）", () => {
+    for (const id of DECLARED_IDS) {
+      const entry = appHotkeys[id]!
+      const hotkey = entry.hotkey
+      expect(hotkey, `${id} 应有默认组合键`).not.toBeNull()
+      expect(checkHotkey(hotkey!), `${id} 组合键非法`).toBe(true)
+      expect(entry.meta?.descriptionKey, `${id} 缺 descriptionKey`).toMatch(/^common_hotkey_desc_/)
+      expect(CATEGORY_ORDER, `${id} category 非法`).toContain(entry.meta?.category)
     }
   })
 
-  it("所有条目 category 都在 CATEGORY_ORDER 中", () => {
-    for (const h of HOTKEY_REGISTRY) {
-      expect(CATEGORY_ORDER).toContain(h.category)
+  it("组合键（chord 整体）不重复", () => {
+    const chords = DECLARED_IDS.map((id) => formatAppHotkeyForBadge(appHotkeys[id]!.hotkey))
+    expect(new Set(chords).size).toBe(chords.length)
+  })
+
+  it("序列键条目为两步序列（G/N 前缀，共 16 条）", () => {
+    const sequences = DECLARED_IDS.map((id) => appHotkeys[id]!).filter((e) => Array.isArray(e.hotkey))
+    expect(sequences).toHaveLength(16)
+    for (const entry of sequences) {
+      const seq = entry.hotkey
+      expect(seq).toHaveLength(2)
+      expect(["G", "N"]).toContain(seq![0])
     }
   })
 
-  it("getHotkeysByCategory 过滤正确", () => {
-    const nav = getHotkeysByCategory("导航")
-    expect(nav.length).toBeGreaterThan(0)
-    expect(nav.every((h) => h.category === "导航")).toBe(true)
+  it("非序列条目为 9 条 chord（Mod+/ 等）", () => {
+    const chords = DECLARED_IDS.map((id) => appHotkeys[id]!).filter((e) => typeof e.hotkey === "string")
+    expect(chords).toHaveLength(9)
+  })
+
+  it("现网声明零冲突（findAppHotkeyConflicts）", () => {
+    expect(findAppHotkeyConflicts()).toEqual([])
+  })
+
+  it("formatAppHotkeyForBadge：chord 原样、序列空格连接、null 返回空串", () => {
+    expect(formatAppHotkeyForBadge("Mod+/")).toBe("Mod+/")
+    expect(formatAppHotkeyForBadge(["G", "D"])).toBe("G D")
+    expect(formatAppHotkeyForBadge(null)).toBe("")
   })
-})
+})