feat(frontend): TanStack Query + React Router migration & in-panel API docs (#4541)

* feat(frontend): introduce TanStack Query with status polling

Wires @tanstack/react-query into every entry and migrates useStatus to
useStatusQuery as the foundation for the multi-page MPA → SPA migration.

- QueryProvider wraps each entry inside ThemeProvider, with devtools gated
  on import.meta.env.DEV
- Shared queryClient: 30s staleTime, refetchOnWindowFocus, 1 retry
- useStatusQuery preserves the { status, fetched, refresh } shape so
  IndexPage swaps in without further changes
- refetchIntervalInBackground:false stops the 2s status poll when the
  panel tab is hidden, cutting idle traffic against the server

* feat(frontend): collapse panel pages into a single React Router SPA

Replaces the 7-entry MPA shell (index/clients/inbounds/nodes/settings/
xray/api-docs HTML files) with one main.tsx + createBrowserRouter. The
Go backend now serves the same index.html for every authenticated
panel route; React Router reads the URL and mounts the page from cache
on subsequent navigation — no more full reloads between tabs.

Frontend
- main.tsx: single bootstrap (setupAxios, i18n, ThemeProvider,
  QueryProvider, RouterProvider) replacing 7 near-duplicate entries
- routes.tsx: declarative router with lazy()-loaded pages, basename
  derived from window.X_UI_BASE_PATH so panels at /secret/panel work
- layouts/PanelLayout.tsx: shell mount-point for the WS → queryClient
  bridge so connection survives navigation
- api/websocketBridge.ts: subscribes the singleton WebSocketClient to
  queryClient and dispatches invalidate/outbounds events to cached
  queries (page-level useWebSocket handlers stay until Phase 3 hooks
  migrate)
- AppSidebar: navigates via useNavigate + useLocation instead of
  window.location.href; drops basePath/requestUri props
- Pages: drop the unused basePath/requestUri locals exposed only for
  the old sidebar

Build
- vite.config: 9 rollup inputs → 3 (index, login, subpage). Dev proxy
  bypass collapses /panel/* to index.html and skips API prefixes
- vendor-tanstack + vendor-router chunks added to manualChunks

Backend
- xui.go: 7 per-page HTML handlers → one panelSPA handler serving
  index.html for /, /inbounds, /clients, /nodes, /settings, /xray,
  /api-docs. The /panel/api, /panel/setting, /panel/xray sub-routers
  are untouched

* feat(frontend): migrate useNodes to TanStack Query

Splits the hand-rolled useNodes hook into useNodesQuery (server data +
NodeRecord type + derived totals) and useNodeMutations (add/update/del/
setEnable/probe/test). Mutations invalidate ['nodes'] on success, so
the list refreshes without each call awaiting a manual refresh().

NodesPage drops useWebSocket({ nodes: applyNodesEvent }) — the
WebSocket → query bridge now forwards the 'nodes' push to
setQueryData(['nodes', 'list']) once at the SPA root.

InboundsPage and the inbound form/list components import NodeRecord
from its new home next to the query hook.

* feat(frontend): migrate useAllSetting to TanStack Query

Replaces the hand-rolled fetch + dirty-tracking hook with useAllSettings
backed by useQuery + useMutation. The draft (current edits) is kept in
local state and reset whenever query.data lands. saveAll posts the
draft via a mutation; on success, invalidating ['settings'] refetches
and the useEffect resets the draft so saveDisabled flips back to true.

staleTime: Infinity prevents refetchOnWindowFocus from clobbering
in-flight edits — settings only change in response to this user's own
save.

setSpinning stays as a pass-through to a local flag so the existing
restartPanel flow in SettingsPage keeps showing its spinner.

* feat(frontend): route useInbounds fetches through TanStack Query

Rewrites useInbounds so its four server fetches (slim list, default
settings, online clients, last-online map) live in useQuery with
staleTime: Infinity. The in-place WS merge logic for traffic and
client_stats is preserved — applyTrafficEvent / applyClientStatsEvent
still mutate the locally-mirrored dbInbounds so the panel doesn't
refetch every 1-2 seconds when stats stream in.

refresh() becomes a thin invalidateQueries on the three list keys,
which mutations in the page already call after add/edit/del.

The bridge now forwards the WebSocket 'inbounds' push to
setQueryData(['inbounds', 'slim']), and InboundsPage drops its
useEffect(fetchDefaultSettings → refresh) plus the invalidate /
inbounds wiring on useWebSocket — both are owned by the bridge now.

* feat(frontend): migrate useClients to TanStack Query

Replaces 12 hand-rolled mutation callbacks and a tangle of useState +
useRef + useEffect with one useQuery (paged list) + nine useMutation
wrappers. The list query uses keepPreviousData so paging/filter
changes don't blank the table mid-fetch.

The setQuery shallow-compare logic is preserved for backward
compatibility with ClientsPage's effect that rebuilds the params on
every render. Internally setQuery only updates state when the params
actually differ — Query's queryKey equality handles the rest.

WS-driven applyTrafficEvent / applyClientStatsEvent now mutate the
query cache via setQueryData(['clients', 'list', currentParams]) so
per-second stats updates skip a full refetch. applyInvalidate is gone
from the hook — the bridge owns coarse 'clients' invalidation.

ClientsPage drops the invalidate handler from its useWebSocket
subscription; auxiliary queries (inboundOptions, defaults, onlines)
load via TanStack Query and are shared with useInbounds via the same
query keys.

* feat(frontend): route useXraySetting fetches through TanStack Query

Keeps the bidirectional xraySetting ↔ templateSettings editor sync and
the 1s dirty-tracking interval intact (those are local editor state,
not server data). All seven server calls move:

- config + traffic → useQuery on ['xray', 'config'] and
  ['xray', 'outboundsTraffic']
- saveAll → useMutation that invalidates the config query
- resetOutboundsTraffic → useMutation that invalidates the traffic
  query
- restartXray → useMutation (fires the restart, then reads the
  result string)
- resetToDefault → useMutation (fetch default config, push it into
  the editor via setTemplateSettings)

The WebSocket 'outbounds' event already lands in
keys.xray.outboundsTraffic() via the bridge, so XrayPage drops its
useWebSocket({ outbounds: applyOutboundsEvent }) wiring entirely and
the hook no longer exposes applyOutboundsEvent.

A useEffect seeds xraySetting / templateSettings / tags / test URL
from query data on first fetch and on every refetch, mirroring what
the original fetchAll() did.

* fix(frontend): restore per-route document titles in the SPA

When the multi-entry MPA collapsed into a single index.html, every
route inherited the static <title>3X-UI</title> from the shared shell,
so every panel page showed "hostname - 3X-UI" instead of the original
"hostname - Overview / Clients / Inbounds / ...".

usePageTitle reads the current pathname and rewrites document.title
on every navigation, matching the titles the deleted *.html files
used to carry. Mounted in PanelLayout so it covers all panel routes
without each page having to opt in.

The startup applyDocumentTitle() call in main.tsx is gone — the hook
sets the full "hostname - PageTitle" string itself.

* feat(api-docs): expose OpenAPI spec + render Swagger UI in panel

Replaces the hand-rolled API docs UI with industry-standard tooling so
external integrations (Postman, Insomnia, openapi-generator) can
consume the panel API without parsing endpoints.js by hand.

Generator
- frontend/scripts/build-openapi.mjs: walks the existing endpoints.js
  (still the single source of truth) and emits an OpenAPI 3.0.3 spec
  at frontend/public/openapi.json. Handles Gin :param → {param} path
  translation, body / query / path parameter splits, 200 + error
  response examples, and Bearer + cookie security schemes
- npm run build now runs gen:api before vite build, so the spec is
  always in sync with what's documented

Backend
- web/controller/dist.go exposes ServeOpenAPISpec which streams the
  embedded dist/openapi.json with a short Cache-Control. Public
  endpoint (no auth) so Postman can fetch it without first logging in
- web/web.go wires GET /panel/api/openapi.json before the auth-gated
  /panel/api router

Panel
- ApiDocsPage now renders swagger-ui-react fed by the basePath-aware
  openapi.json URL. Dark mode is overridden via CSS targeting the
  Swagger UI internals
- CodeBlock / EndpointRow / EndpointSection are gone; the swagger-ui
  vendor chunk (134 KB gzipped) only loads on this lazy route, not on
  every panel page
- vite.config: vendor-swagger manualChunk keeps the new dep out of
  the main vendor bundle

For Postman: import http://<panel>/panel/api/openapi.json. Everything
from /login + /panel/api/* shows up with auth, params, and examples.

* style(api-docs): dark/ultra theme for Swagger UI

Override every visual surface Swagger does not theme on its own:
opblocks, tables, model boxes, form inputs, code blocks, modals,
Servers dropdown, per-endpoint padlocks and expand chevrons. Replaces
Swagger's default light-arrow chevron on selects with a light-fill SVG
positioned at the corner so the dark background-color is visible.

Also disables deepLinking to silence the noisy v4 underscore warning;
not used in our panel.

frontend/src/hooks/useAllSetting.ts

@@ -1,69 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { HttpUtil } from '@/utils';
-import { AllSetting } from '@/models/setting';
-
-interface ApiMsg<T = unknown> {
-  success?: boolean;
-  obj?: T;
-}
-
-export function useAllSetting() {
-  const [allSetting, setAllSetting] = useState<AllSetting>(() => new AllSetting());
-  const [oldAllSetting, setOldAllSetting] = useState<AllSetting>(() => new AllSetting());
-  const [fetched, setFetched] = useState(false);
-  const [spinning, setSpinning] = useState(false);
-  const fetchedRef = useRef(false);
-
-  const applyServerState = useCallback((obj: unknown) => {
-    setAllSetting(new AllSetting(obj));
-    setOldAllSetting(new AllSetting(obj));
-  }, []);
-
-  const fetchAll = useCallback(async () => {
-    const msg = await HttpUtil.post('/panel/setting/all') as ApiMsg;
-    if (msg?.success) {
-      applyServerState(msg.obj);
-      fetchedRef.current = true;
-      setFetched(true);
-    }
-  }, [applyServerState]);
-
-  const saveAll = useCallback(async () => {
-    setSpinning(true);
-    try {
-      const msg = await HttpUtil.post('/panel/setting/update', allSetting) as ApiMsg;
-      if (msg?.success) await fetchAll();
-    } finally {
-      setSpinning(false);
-    }
-  }, [allSetting, fetchAll]);
-
-  const updateSetting = useCallback((patch: Partial<AllSetting>) => {
-    setAllSetting((prev) => {
-      const next = new AllSetting(prev);
-      Object.assign(next, patch);
-      return next;
-    });
-  }, []);
-
-  const saveDisabled = useMemo(
-    () => allSetting.equals(oldAllSetting),
-    [allSetting, oldAllSetting],
-  );
-
-  useEffect(() => {
-     
-    fetchAll();
-  }, [fetchAll]);
-
-  return {
-    allSetting,
-    updateSetting,
-    fetched,
-    spinning,
-    setSpinning,
-    saveDisabled,
-    fetchAll,
-    saveAll,
-  };
-}

frontend/src/hooks/useClients.ts

@@ -1,5 +1,8 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { keepPreviousData, useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+
 import { HttpUtil } from '@/utils';
+import { keys } from '@/api/queryKeys';
 
 const JSON_HEADERS = { headers: { 'Content-Type': 'application/json' } } as const;
 
@@ -84,22 +87,49 @@ interface ClientPageResponse {
 }
 
 const DEFAULT_QUERY: ClientQueryParams = { page: 1, pageSize: 25 };
+const DEFAULT_SUMMARY: ClientsSummary = {
+  total: 0, active: 0, online: [], depleted: [], expiring: [], deactive: [],
+};
+
+function buildQS(p: ClientQueryParams): string {
+  const sp = new URLSearchParams();
+  sp.set('page', String(p.page || 1));
+  sp.set('pageSize', String(p.pageSize || DEFAULT_QUERY.pageSize));
+  if (p.search) sp.set('search', p.search);
+  if (p.filter) sp.set('filter', p.filter);
+  if (p.protocol) sp.set('protocol', p.protocol);
+  if (p.inbound && p.inbound > 0) sp.set('inbound', String(p.inbound));
+  if (p.sort) sp.set('sort', p.sort);
+  if (p.order) sp.set('order', p.order);
+  return sp.toString();
+}
+
+async function fetchClientPage(params: ClientQueryParams): Promise<ClientPageResponse> {
+  const qs = buildQS(params);
+  const msg = await HttpUtil.get(`/panel/api/clients/list/paged?${qs}`, undefined, { silent: true }) as ApiMsg<ClientPageResponse>;
+  if (!msg?.success || !msg.obj) throw new Error(msg?.msg || 'Failed to fetch clients');
+  return msg.obj;
+}
+
+async function fetchInboundOptions(): Promise<InboundOption[]> {
+  const msg = await HttpUtil.get('/panel/api/inbounds/options', undefined, { silent: true }) as ApiMsg<InboundOption[]>;
+  if (!msg?.success) throw new Error(msg?.msg || 'Failed to fetch inbound options');
+  return Array.isArray(msg.obj) ? msg.obj : [];
+}
+
+async function fetchDefaults(): Promise<Record<string, unknown>> {
+  const msg = await HttpUtil.post('/panel/setting/defaultSettings', undefined, { silent: true }) as ApiMsg<Record<string, unknown>>;
+  if (!msg?.success) throw new Error(msg?.msg || 'Failed to fetch defaults');
+  return msg.obj || {};
+}
 
 export function useClients() {
-  const [clients, setClients] = useState<ClientRecord[]>([]);
-  const [total, setTotal] = useState(0);
-  const [filtered, setFiltered] = useState(0);
-  const [summary, setSummary] = useState<ClientsSummary>({
-    total: 0, active: 0, online: [], depleted: [], expiring: [], deactive: [],
-  });
-  const [inbounds, setInbounds] = useState<InboundOption[]>([]);
-  const [onlines, setOnlines] = useState<string[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [fetched, setFetched] = useState(false);
+  const queryClient = useQueryClient();
+
   const [query, setQueryState] = useState<ClientQueryParams>(DEFAULT_QUERY);
-  // Shallow-compare against the previous query so callers can pass a fresh
-  // object on every render (the common React pattern) without triggering a
-  // re-fetch when nothing actually changed.
+  // setQuery shallow-compares so callers can pass a fresh object every render
+  // (the common React pattern) without triggering a re-fetch when nothing
+  // actually changed.
   const setQuery = useCallback((next: ClientQueryParams) => {
     setQueryState((prev) => {
       if (
@@ -115,86 +145,69 @@ export function useClients() {
       return next;
     });
   }, []);
-  const [subSettings, setSubSettings] = useState<SubSettings>({
-    enable: false, subURI: '', subJsonURI: '', subJsonEnable: false,
+
+  const listQuery = useQuery({
+    queryKey: keys.clients.list(query),
+    queryFn: () => fetchClientPage(query),
+    staleTime: Infinity,
+    placeholderData: keepPreviousData,
   });
-  const [ipLimitEnable, setIpLimitEnable] = useState(false);
-  const [tgBotEnable, setTgBotEnable] = useState(false);
-  const [expireDiff, setExpireDiff] = useState(0);
-  const [trafficDiff, setTrafficDiff] = useState(0);
-  const [pageSize, setPageSize] = useState(0);
 
-  const clientsRef = useRef<ClientRecord[]>([]);
-  const queryRef = useRef<ClientQueryParams>(query);
-  const invalidateTimerRef = useRef<number | null>(null);
+  const inboundOptionsQuery = useQuery({
+    queryKey: keys.inbounds.options(),
+    queryFn: fetchInboundOptions,
+    staleTime: Infinity,
+  });
 
-  useEffect(() => { clientsRef.current = clients; }, [clients]);
-  useEffect(() => { queryRef.current = query; }, [query]);
+  const defaultsQuery = useQuery({
+    queryKey: keys.settings.defaults(),
+    queryFn: fetchDefaults,
+    staleTime: Infinity,
+  });
 
-  const buildQS = (p: ClientQueryParams) => {
-    const sp = new URLSearchParams();
-    sp.set('page', String(p.page || 1));
-    sp.set('pageSize', String(p.pageSize || DEFAULT_QUERY.pageSize));
-    if (p.search) sp.set('search', p.search);
-    if (p.filter) sp.set('filter', p.filter);
-    if (p.protocol) sp.set('protocol', p.protocol);
-    if (p.inbound && p.inbound > 0) sp.set('inbound', String(p.inbound));
-    if (p.sort) sp.set('sort', p.sort);
-    if (p.order) sp.set('order', p.order);
-    return sp.toString();
-  };
+  const onlinesQuery = useQuery({
+    queryKey: keys.clients.onlines(),
+    queryFn: async () => {
+      const msg = await HttpUtil.post('/panel/api/clients/onlines', undefined, { silent: true }) as ApiMsg<string[]>;
+      if (!msg?.success) throw new Error(msg?.msg || 'Failed to fetch onlines');
+      return Array.isArray(msg.obj) ? msg.obj : [];
+    },
+    staleTime: Infinity,
+  });
 
-  const refresh = useCallback(async (override?: ClientQueryParams) => {
-    setLoading(true);
-    try {
-      const params = override ?? queryRef.current;
-      const qs = buildQS(params);
-      const msg = await HttpUtil.get(`/panel/api/clients/list/paged?${qs}`) as ApiMsg<ClientPageResponse>;
-      if (msg?.success && msg.obj) {
-        setClients(Array.isArray(msg.obj.items) ? msg.obj.items : []);
-        setTotal(msg.obj.total ?? 0);
-        setFiltered(msg.obj.filtered ?? 0);
-        if (msg.obj.summary) setSummary(msg.obj.summary);
-      }
-      setFetched(true);
-    } finally {
-      setLoading(false);
-    }
-  }, []);
+  const clients = listQuery.data?.items ?? [];
+  const total = listQuery.data?.total ?? 0;
+  const filtered = listQuery.data?.filtered ?? 0;
+  const summary = listQuery.data?.summary ?? DEFAULT_SUMMARY;
+  const fetched = listQuery.data !== undefined;
+  const loading = listQuery.isFetching;
 
-  // Inbound options are picker-shaped and don't depend on the clients query —
-  // fetch them once on mount instead of every refresh.
-  useEffect(() => {
-    let cancelled = false;
-    (async () => {
-      const msg = await HttpUtil.get('/panel/api/inbounds/options') as ApiMsg<InboundOption[]>;
-      if (cancelled) return;
-      if (msg?.success) setInbounds(Array.isArray(msg.obj) ? msg.obj : []);
-    })();
-    return () => { cancelled = true; };
-  }, []);
+  const inbounds = inboundOptionsQuery.data ?? [];
+  const onlines = onlinesQuery.data ?? [];
 
-  const fetchSubSettings = useCallback(async () => {
-    const msg = await HttpUtil.post('/panel/setting/defaultSettings') as ApiMsg<Record<string, unknown>>;
-    if (!msg?.success) return;
-    const s = msg.obj || {};
-    setSubSettings({
-      enable: !!s.subEnable,
-      subURI: (s.subURI as string) || '',
-      subJsonURI: (s.subJsonURI as string) || '',
-      subJsonEnable: !!s.subJsonEnable,
-    });
-    setIpLimitEnable(!!s.ipLimitEnable);
-    setTgBotEnable(!!s.tgBotEnable);
-    setExpireDiff(((s.expireDiff as number) ?? 0) * 86400000);
-    setTrafficDiff(((s.trafficDiff as number) ?? 0) * 1073741824);
-    setPageSize((s.pageSize as number) ?? 0);
-  }, []);
+  const defaults = defaultsQuery.data ?? {};
+  const subSettings: SubSettings = useMemo(() => ({
+    enable: !!defaults.subEnable,
+    subURI: (defaults.subURI as string) || '',
+    subJsonURI: (defaults.subJsonURI as string) || '',
+    subJsonEnable: !!defaults.subJsonEnable,
+  }), [defaults.subEnable, defaults.subURI, defaults.subJsonURI, defaults.subJsonEnable]);
+
+  const ipLimitEnable = !!defaults.ipLimitEnable;
+  const tgBotEnable = !!defaults.tgBotEnable;
+  const expireDiff = ((defaults.expireDiff as number) ?? 0) * 86400000;
+  const trafficDiff = ((defaults.trafficDiff as number) ?? 0) * 1073741824;
+  const pageSize = (defaults.pageSize as number) ?? 0;
+
+  const invalidateAll = useCallback(
+    () => queryClient.invalidateQueries({ queryKey: keys.clients.root() }),
+    [queryClient],
+  );
+
+  const refresh = useCallback(async () => {
+    await invalidateAll();
+  }, [invalidateAll]);
 
-  // hydrate fetches the full client record (uuid, password, flow, ...) for a
-  // single email. The paged list endpoint omits these to keep the row payload
-  // tiny; edit / info / qr / link modals call this to get a complete record
-  // before opening.
   const hydrate = useCallback(async (email: string): Promise<{ client: ClientRecord; inboundIds: number[] } | null> => {
     if (!email) return null;
     const msg = await HttpUtil.get(`/panel/api/clients/get/${encodeURIComponent(email)}`) as ApiMsg<{ client: ClientRecord; inboundIds: number[] }>;
@@ -202,88 +215,109 @@ export function useClients() {
     return msg.obj;
   }, []);
 
-  const create = useCallback(async (payload: unknown) => {
-    const msg = await HttpUtil.post('/panel/api/clients/add', payload, JSON_HEADERS) as ApiMsg;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
+  const createMut = useMutation({
+    mutationFn: (payload: unknown) =>
+      HttpUtil.post('/panel/api/clients/add', payload, JSON_HEADERS) as Promise<ApiMsg>,
+    onSuccess: (msg) => { if (msg?.success) invalidateAll(); },
+  });
 
-  const update = useCallback(async (email: string, client: unknown) => {
-    if (!email) return null;
-    const encoded = encodeURIComponent(email);
-    const msg = await HttpUtil.post(`/panel/api/clients/update/${encoded}`, client, JSON_HEADERS) as ApiMsg;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
+  const updateMut = useMutation({
+    mutationFn: ({ email, client }: { email: string; client: unknown }) =>
+      HttpUtil.post(`/panel/api/clients/update/${encodeURIComponent(email)}`, client, JSON_HEADERS) as Promise<ApiMsg>,
+    onSuccess: (msg) => { if (msg?.success) invalidateAll(); },
+  });
 
-  const remove = useCallback(async (email: string, keepTraffic = false) => {
-    if (!email) return null;
-    const encoded = encodeURIComponent(email);
-    const url = keepTraffic
-      ? `/panel/api/clients/del/${encoded}?keepTraffic=1`
-      : `/panel/api/clients/del/${encoded}`;
-    const msg = await HttpUtil.post(url) as ApiMsg;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
+  const removeMut = useMutation({
+    mutationFn: ({ email, keepTraffic }: { email: string; keepTraffic?: boolean }) => {
+      const url = keepTraffic
+        ? `/panel/api/clients/del/${encodeURIComponent(email)}?keepTraffic=1`
+        : `/panel/api/clients/del/${encodeURIComponent(email)}`;
+      return HttpUtil.post(url) as Promise<ApiMsg>;
+    },
+    onSuccess: (msg) => { if (msg?.success) invalidateAll(); },
+  });
 
-  const removeMany = useCallback(async (emails: string[], keepTraffic = false) => {
-    if (!Array.isArray(emails) || emails.length === 0) return [];
-    const suffix = keepTraffic ? '?keepTraffic=1' : '';
-    const results = await Promise.all(emails.map((email) => {
-      const url = `/panel/api/clients/del/${encodeURIComponent(email)}${suffix}`;
-      return HttpUtil.post(url, undefined, { silent: true }) as Promise<ApiMsg>;
-    }));
-    await refresh();
-    return results;
-  }, [refresh]);
+  const removeManyMut = useMutation({
+    mutationFn: async ({ emails, keepTraffic }: { emails: string[]; keepTraffic?: boolean }) => {
+      const suffix = keepTraffic ? '?keepTraffic=1' : '';
+      const results = await Promise.all(emails.map((email) => {
+        const url = `/panel/api/clients/del/${encodeURIComponent(email)}${suffix}`;
+        return HttpUtil.post(url, undefined, { silent: true }) as Promise<ApiMsg>;
+      }));
+      return results;
+    },
+    onSuccess: () => invalidateAll(),
+  });
 
-  const bulkAdjust = useCallback(async (emails: string[], addDays: number, addBytes: number) => {
-    if (!Array.isArray(emails) || emails.length === 0) return null;
-    const msg = await HttpUtil.post(
-      '/panel/api/clients/bulkAdjust',
-      { emails, addDays, addBytes },
-      JSON_HEADERS,
-    ) as ApiMsg<{ adjusted: number; skipped?: { email: string; reason: string }[] }>;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
+  const bulkAdjustMut = useMutation({
+    mutationFn: (payload: { emails: string[]; addDays: number; addBytes: number }) =>
+      HttpUtil.post(
+        '/panel/api/clients/bulkAdjust',
+        payload,
+        JSON_HEADERS,
+      ) as Promise<ApiMsg<{ adjusted: number; skipped?: { email: string; reason: string }[] }>>,
+    onSuccess: (msg) => { if (msg?.success) invalidateAll(); },
+  });
 
-  const attach = useCallback(async (email: string, inboundIds: number[]) => {
-    if (!email) return null;
-    const encoded = encodeURIComponent(email);
-    const msg = await HttpUtil.post(`/panel/api/clients/${encoded}/attach`, { inboundIds }, JSON_HEADERS) as ApiMsg;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
+  const attachMut = useMutation({
+    mutationFn: ({ email, inboundIds }: { email: string; inboundIds: number[] }) =>
+      HttpUtil.post(`/panel/api/clients/${encodeURIComponent(email)}/attach`, { inboundIds }, JSON_HEADERS) as Promise<ApiMsg>,
+    onSuccess: (msg) => { if (msg?.success) invalidateAll(); },
+  });
 
-  const detach = useCallback(async (email: string, inboundIds: number[]) => {
-    if (!email) return null;
-    const encoded = encodeURIComponent(email);
-    const msg = await HttpUtil.post(`/panel/api/clients/${encoded}/detach`, { inboundIds }, JSON_HEADERS) as ApiMsg;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
+  const detachMut = useMutation({
+    mutationFn: ({ email, inboundIds }: { email: string; inboundIds: number[] }) =>
+      HttpUtil.post(`/panel/api/clients/${encodeURIComponent(email)}/detach`, { inboundIds }, JSON_HEADERS) as Promise<ApiMsg>,
+    onSuccess: (msg) => { if (msg?.success) invalidateAll(); },
+  });
 
-  const resetTraffic = useCallback(async (client: ClientRecord) => {
-    if (!client?.email) return null;
-    const url = `/panel/api/clients/resetTraffic/${encodeURIComponent(client.email)}`;
-    const msg = await HttpUtil.post(url) as ApiMsg;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
+  const resetTrafficMut = useMutation({
+    mutationFn: (email: string) =>
+      HttpUtil.post(`/panel/api/clients/resetTraffic/${encodeURIComponent(email)}`) as Promise<ApiMsg>,
+    onSuccess: (msg) => { if (msg?.success) invalidateAll(); },
+  });
 
-  const resetAllTraffics = useCallback(async () => {
-    const msg = await HttpUtil.post('/panel/api/clients/resetAllTraffics') as ApiMsg;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
+  const resetAllTrafficsMut = useMutation({
+    mutationFn: () => HttpUtil.post('/panel/api/clients/resetAllTraffics') as Promise<ApiMsg>,
+    onSuccess: (msg) => { if (msg?.success) invalidateAll(); },
+  });
 
-  const delDepleted = useCallback(async () => {
-    const msg = await HttpUtil.post('/panel/api/clients/delDepleted') as ApiMsg<{ deleted?: number }>;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
+  const delDepletedMut = useMutation({
+    mutationFn: () => HttpUtil.post('/panel/api/clients/delDepleted') as Promise<ApiMsg<{ deleted?: number }>>,
+    onSuccess: (msg) => { if (msg?.success) invalidateAll(); },
+  });
+
+  const create = useCallback((payload: unknown) => createMut.mutateAsync(payload), [createMut]);
+  const update = useCallback((email: string, client: unknown) => {
+    if (!email) return Promise.resolve(null as unknown as ApiMsg);
+    return updateMut.mutateAsync({ email, client });
+  }, [updateMut]);
+  const remove = useCallback((email: string, keepTraffic = false) => {
+    if (!email) return Promise.resolve(null as unknown as ApiMsg);
+    return removeMut.mutateAsync({ email, keepTraffic });
+  }, [removeMut]);
+  const removeMany = useCallback((emails: string[], keepTraffic = false) => {
+    if (!Array.isArray(emails) || emails.length === 0) return Promise.resolve([] as ApiMsg[]);
+    return removeManyMut.mutateAsync({ emails, keepTraffic });
+  }, [removeManyMut]);
+  const bulkAdjust = useCallback((emails: string[], addDays: number, addBytes: number) => {
+    if (!Array.isArray(emails) || emails.length === 0) return Promise.resolve(null);
+    return bulkAdjustMut.mutateAsync({ emails, addDays, addBytes });
+  }, [bulkAdjustMut]);
+  const attach = useCallback((email: string, inboundIds: number[]) => {
+    if (!email) return Promise.resolve(null as unknown as ApiMsg);
+    return attachMut.mutateAsync({ email, inboundIds });
+  }, [attachMut]);
+  const detach = useCallback((email: string, inboundIds: number[]) => {
+    if (!email) return Promise.resolve(null as unknown as ApiMsg);
+    return detachMut.mutateAsync({ email, inboundIds });
+  }, [detachMut]);
+  const resetTraffic = useCallback((client: ClientRecord) => {
+    if (!client?.email) return Promise.resolve(null as unknown as ApiMsg);
+    return resetTrafficMut.mutateAsync(client.email);
+  }, [resetTrafficMut]);
+  const resetAllTraffics = useCallback(() => resetAllTrafficsMut.mutateAsync(), [resetAllTrafficsMut]);
+  const delDepleted = useCallback(() => delDepletedMut.mutateAsync(), [delDepletedMut]);
 
   const setEnable = useCallback(async (client: ClientRecord, enable: boolean) => {
     if (!client?.email) return null;
@@ -302,57 +336,53 @@ export function useClients() {
     return update(client.email, payload);
   }, [update]);
 
+  // WS-driven in-place merges. Page wires these via useWebSocket; the bridge
+  // covers coarse 'invalidate' and 'inbounds' events centrally.
+  const queryRef = useRef(query);
+  queryRef.current = query;
+
   const applyTrafficEvent = useCallback((payload: unknown) => {
     if (!payload || typeof payload !== 'object') return;
     const p = payload as { onlineClients?: string[] };
     if (Array.isArray(p.onlineClients)) {
-      setOnlines(p.onlineClients);
+      queryClient.setQueryData(keys.clients.onlines(), p.onlineClients);
     }
-  }, []);
+  }, [queryClient]);
 
   const applyClientStatsEvent = useCallback((payload: unknown) => {
     if (!payload || typeof payload !== 'object') return;
-    const p = payload as { clients?: ClientTraffic[] & { email?: string }[] };
+    const p = payload as { clients?: (ClientTraffic & { email?: string })[] };
     if (!Array.isArray(p.clients) || p.clients.length === 0) return;
     const byEmail = new Map<string, ClientTraffic>();
-    for (const row of p.clients as (ClientTraffic & { email?: string })[]) {
+    for (const row of p.clients) {
       if (row && row.email) byEmail.set(row.email, row);
     }
-    const cur = clientsRef.current || [];
-    let touched = false;
-    const next = cur.slice();
-    for (let i = 0; i < next.length; i++) {
-      const row = next[i];
-      const upd = byEmail.get(row?.email);
-      if (!upd) continue;
-      const merged: ClientTraffic = { ...(row.traffic || {}) };
-      if (typeof upd.up === 'number') merged.up = upd.up;
-      if (typeof upd.down === 'number') merged.down = upd.down;
-      if (typeof upd.total === 'number') merged.total = upd.total;
-      if (typeof upd.expiryTime === 'number') merged.expiryTime = upd.expiryTime;
-      if (typeof upd.enable === 'boolean') merged.enable = upd.enable;
-      if (typeof upd.lastOnline === 'number') merged.lastOnline = upd.lastOnline;
-      next[i] = { ...row, traffic: merged };
-      touched = true;
-    }
-    if (touched) setClients(next);
-  }, []);
-
-  const applyInvalidate = useCallback((payload: unknown) => {
-    if (!payload || typeof payload !== 'object') return;
-    const p = payload as { type?: string };
-    if (p.type !== 'inbounds' && p.type !== 'clients') return;
-    if (invalidateTimerRef.current != null) clearTimeout(invalidateTimerRef.current);
-    invalidateTimerRef.current = window.setTimeout(() => {
-      invalidateTimerRef.current = null;
-      refresh();
-    }, 200);
-  }, [refresh]);
+    queryClient.setQueryData<ClientPageResponse>(keys.clients.list(queryRef.current), (prev) => {
+      if (!prev) return prev;
+      let touched = false;
+      const next = prev.items.slice();
+      for (let i = 0; i < next.length; i++) {
+        const row = next[i];
+        const upd = byEmail.get(row?.email);
+        if (!upd) continue;
+        const merged: ClientTraffic = { ...(row.traffic || {}) };
+        if (typeof upd.up === 'number') merged.up = upd.up;
+        if (typeof upd.down === 'number') merged.down = upd.down;
+        if (typeof upd.total === 'number') merged.total = upd.total;
+        if (typeof upd.expiryTime === 'number') merged.expiryTime = upd.expiryTime;
+        if (typeof upd.enable === 'boolean') merged.enable = upd.enable;
+        if (typeof upd.lastOnline === 'number') merged.lastOnline = upd.lastOnline;
+        next[i] = { ...row, traffic: merged };
+        touched = true;
+      }
+      if (!touched) return prev;
+      return { ...prev, items: next };
+    });
+  }, [queryClient]);
 
   useEffect(() => {
-    Promise.all([refresh(query), fetchSubSettings()]);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [query, fetchSubSettings]);
+    queryRef.current = query;
+  }, [query]);
 
   return {
     clients,
@@ -386,6 +416,5 @@ export function useClients() {
     setEnable,
     applyTrafficEvent,
     applyClientStatsEvent,
-    applyInvalidate,
   };
 }

frontend/src/hooks/useNodes.ts

@@ -1,177 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { HttpUtil } from '@/utils';
-
-export interface NodeRecord {
-  id: number;
-  name?: string;
-  remark?: string;
-  scheme?: string;
-  address?: string;
-  port?: number;
-  basePath?: string;
-  apiToken?: string;
-  enable?: boolean;
-  status?: 'online' | 'offline' | string;
-  latencyMs?: number;
-  cpuPct?: number;
-  memPct?: number;
-  xrayVersion?: string;
-  panelVersion?: string;
-  uptimeSecs?: number;
-  inboundCount?: number;
-  clientCount?: number;
-  onlineCount?: number;
-  depletedCount?: number;
-  lastHeartbeat?: number;
-  lastError?: string;
-  allowPrivateAddress?: boolean;
-  [key: string]: unknown;
-}
-
-interface ApiMsg<T = unknown> {
-  success?: boolean;
-  msg?: string;
-  obj?: T;
-}
-
-interface NodeTotals {
-  total: number;
-  online: number;
-  offline: number;
-  avgLatency: number;
-  inbounds: number;
-  clients: number;
-  onlineClients: number;
-  depleted: number;
-}
-
-export function useNodes() {
-  const [nodes, setNodes] = useState<NodeRecord[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [fetched, setFetched] = useState(false);
-  const fetchedRef = useRef(false);
-
-  const refresh = useCallback(async () => {
-    setLoading(true);
-    try {
-      const msg = await HttpUtil.get('/panel/api/nodes/list') as ApiMsg<NodeRecord[]>;
-      if (msg?.success) {
-        setNodes(Array.isArray(msg.obj) ? msg.obj : []);
-      }
-      fetchedRef.current = true;
-      setFetched(true);
-    } finally {
-      setLoading(false);
-    }
-  }, []);
-
-  const applyNodesEvent = useCallback((payload: unknown) => {
-    if (Array.isArray(payload)) {
-      setNodes(payload as NodeRecord[]);
-      if (!fetchedRef.current) {
-        fetchedRef.current = true;
-        setFetched(true);
-      }
-    }
-  }, []);
-
-  const create = useCallback(async (payload: Partial<NodeRecord>) => {
-    const msg = await HttpUtil.post('/panel/api/nodes/add', payload) as ApiMsg;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
-
-  const update = useCallback(async (id: number, payload: Partial<NodeRecord>) => {
-    const msg = await HttpUtil.post(`/panel/api/nodes/update/${id}`, payload) as ApiMsg;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
-
-  const remove = useCallback(async (id: number) => {
-    const msg = await HttpUtil.post(`/panel/api/nodes/del/${id}`) as ApiMsg;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
-
-  const setEnable = useCallback(async (id: number, enable: boolean) => {
-    const msg = await HttpUtil.post(`/panel/api/nodes/setEnable/${id}`, { enable }) as ApiMsg;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
-
-  const testConnection = useCallback(async (payload: Partial<NodeRecord>) => {
-    return await HttpUtil.post('/panel/api/nodes/test', payload) as ApiMsg<{
-      status: string;
-      latencyMs?: number;
-      xrayVersion?: string;
-      error?: string;
-    }>;
-  }, []);
-
-  const probe = useCallback(async (id: number) => {
-    const msg = await HttpUtil.post(`/panel/api/nodes/probe/${id}`) as ApiMsg<{
-      status: string;
-      latencyMs?: number;
-      error?: string;
-    }>;
-    if (msg?.success) await refresh();
-    return msg;
-  }, [refresh]);
-
-  const totals = useMemo<NodeTotals>(() => {
-    let online = 0;
-    let offline = 0;
-    let latencySum = 0;
-    let latencyCount = 0;
-    let inbounds = 0;
-    let clients = 0;
-    let onlineClients = 0;
-    let depleted = 0;
-    for (const n of nodes) {
-      inbounds += n.inboundCount || 0;
-      clients += n.clientCount || 0;
-      onlineClients += n.onlineCount || 0;
-      depleted += n.depletedCount || 0;
-      if (!n.enable) continue;
-      if (n.status === 'online') {
-        online += 1;
-        if (n.latencyMs && n.latencyMs > 0) {
-          latencySum += n.latencyMs;
-          latencyCount += 1;
-        }
-      } else if (n.status === 'offline') {
-        offline += 1;
-      }
-    }
-    return {
-      total: nodes.length,
-      online,
-      offline,
-      avgLatency: latencyCount > 0 ? Math.round(latencySum / latencyCount) : 0,
-      inbounds,
-      clients,
-      onlineClients,
-      depleted,
-    };
-  }, [nodes]);
-
-  useEffect(() => {
-     
-    refresh();
-  }, [refresh]);
-
-  return {
-    nodes,
-    loading,
-    fetched,
-    totals,
-    refresh,
-    applyNodesEvent,
-    create,
-    update,
-    remove,
-    setEnable,
-    testConnection,
-    probe,
-  };
-}

frontend/src/hooks/usePageTitle.ts

@@ -0,0 +1,22 @@
+import { useEffect } from 'react';
+import { useLocation } from 'react-router-dom';
+
+const TITLES: Record<string, string> = {
+  '/': 'Overview',
+  '/inbounds': 'Inbounds',
+  '/clients': 'Clients',
+  '/nodes': 'Nodes',
+  '/settings': 'Settings',
+  '/xray': 'Xray Config',
+  '/api-docs': 'API Docs',
+};
+
+export function usePageTitle() {
+  const { pathname } = useLocation();
+
+  useEffect(() => {
+    const title = TITLES[pathname] || '3X-UI';
+    const host = window.location.hostname;
+    document.title = host ? `${host} - ${title}` : title;
+  }, [pathname]);
+}

frontend/src/hooks/useStatus.ts

@@ -1,35 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-
-import { HttpUtil } from '@/utils';
-import { Status } from '@/models/status';
-
-const POLL_INTERVAL_MS = 2000;
-
-export function useStatus() {
-  const [status, setStatus] = useState<Status>(() => new Status());
-  const [fetched, setFetched] = useState(false);
-  const fetchedRef = useRef(false);
-
-  const refresh = useCallback(async () => {
-    try {
-      const msg = await HttpUtil.get('/panel/api/server/status');
-      if (msg?.success) {
-        setStatus(new Status(msg.obj));
-        if (!fetchedRef.current) {
-          fetchedRef.current = true;
-          setFetched(true);
-        }
-      }
-    } catch (e) {
-      console.error('Failed to get status:', e);
-    }
-  }, []);
-
-  useEffect(() => {
-    refresh();
-    const timer = window.setInterval(refresh, POLL_INTERVAL_MS);
-    return () => window.clearInterval(timer);
-  }, [refresh]);
-
-  return { status, fetched, refresh };
-}

frontend/src/hooks/useXraySetting.ts

@@ -1,8 +1,11 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 
 import { HttpUtil, PromiseUtil } from '@/utils';
+import { keys } from '@/api/queryKeys';
 
 const DIRTY_POLL_MS = 1000;
+const DEFAULT_TEST_URL = 'https://www.google.com/generate_204';
 
 export interface OutboundTrafficRow {
   tag: string;
@@ -70,7 +73,6 @@ export interface UseXraySettingResult {
   fetchAll: () => Promise<void>;
   fetchOutboundsTraffic: () => Promise<void>;
   resetOutboundsTraffic: (tag: string) => Promise<void>;
-  applyOutboundsEvent: (payload: unknown) => void;
   testOutbound: (
     index: number,
     outbound: unknown,
@@ -82,18 +84,59 @@ export interface UseXraySettingResult {
   restartXray: () => Promise<void>;
 }
 
+interface ApiMsg<T = unknown> {
+  success?: boolean;
+  obj?: T;
+  msg?: string;
+}
+
+interface XrayConfigPayload {
+  xraySetting: XraySettingsValue;
+  inboundTags?: string[];
+  clientReverseTags?: string[];
+  outboundTestUrl?: string;
+}
+
+async function fetchXrayConfig(): Promise<XrayConfigPayload> {
+  const msg = await HttpUtil.post('/panel/xray/', undefined, { silent: true }) as ApiMsg<string>;
+  if (!msg?.success) throw new Error(msg?.msg || 'Failed to load xray config');
+  if (typeof msg.obj !== 'string') throw new Error('Malformed xray config response: expected string');
+  try {
+    return JSON.parse(msg.obj) as XrayConfigPayload;
+  } catch (e) {
+    const err = e as Error;
+    throw new Error(`Malformed xray config response: ${err.message}`, { cause: e });
+  }
+}
+
+async function fetchOutboundsTraffic(): Promise<OutboundTrafficRow[]> {
+  const msg = await HttpUtil.get('/panel/xray/getOutboundsTraffic', undefined, { silent: true }) as ApiMsg<OutboundTrafficRow[]>;
+  if (!msg?.success) throw new Error(msg?.msg || 'Failed to fetch outbounds traffic');
+  return Array.isArray(msg.obj) ? msg.obj : [];
+}
+
 export function useXraySetting(): UseXraySettingResult {
-  const [fetched, setFetched] = useState(false);
-  const [spinning, setSpinning] = useState(false);
+  const queryClient = useQueryClient();
+
+  const configQuery = useQuery({
+    queryKey: keys.xray.config(),
+    queryFn: fetchXrayConfig,
+    staleTime: Infinity,
+  });
+
+  const trafficQuery = useQuery({
+    queryKey: keys.xray.outboundsTraffic(),
+    queryFn: fetchOutboundsTraffic,
+    staleTime: Infinity,
+  });
+
   const [saveDisabled, setSaveDisabled] = useState(true);
-  const [fetchError, setFetchError] = useState('');
   const [xraySetting, setXraySettingState] = useState('');
   const [templateSettings, setTemplateSettingsState] = useState<XraySettingsValue | null>(null);
-  const [outboundTestUrl, setOutboundTestUrlState] = useState('https://www.google.com/generate_204');
+  const [outboundTestUrl, setOutboundTestUrlState] = useState(DEFAULT_TEST_URL);
   const [inboundTags, setInboundTags] = useState<string[]>([]);
   const [clientReverseTags, setClientReverseTags] = useState<string[]>([]);
   const [restartResult, setRestartResult] = useState('');
-  const [outboundsTraffic, setOutboundsTraffic] = useState<OutboundTrafficRow[]>([]);
   const [outboundTestStates, setOutboundTestStates] = useState<Record<number, OutboundTestState>>({});
   const [testingAll, setTestingAll] = useState(false);
 
@@ -108,6 +151,28 @@ export function useXraySetting(): UseXraySettingResult {
   outboundTestUrlRef.current = outboundTestUrl;
   templateSettingsRef.current = templateSettings;
 
+  // Seed local editor state from the config query. Runs on first fetch and
+  // every time the query refetches (e.g. after a successful save).
+  useEffect(() => {
+    if (!configQuery.data) return;
+    const obj = configQuery.data;
+    const pretty = JSON.stringify(obj.xraySetting, null, 2);
+    syncingRef.current = true;
+    setXraySettingState(pretty);
+    setTemplateSettingsState(obj.xraySetting);
+    oldXraySettingRef.current = pretty;
+    syncingRef.current = false;
+    setInboundTags(obj.inboundTags || []);
+    setClientReverseTags(obj.clientReverseTags || []);
+    const nextUrl = obj.outboundTestUrl || DEFAULT_TEST_URL;
+    setOutboundTestUrlState(nextUrl);
+    oldOutboundTestUrlRef.current = nextUrl;
+    setSaveDisabled(true);
+  }, [configQuery.data]);
+
+  const fetched = configQuery.data !== undefined || configQuery.isError;
+  const fetchError = configQuery.error ? (configQuery.error as Error).message : '';
+
   const setXraySetting = useCallback((next: string) => {
     setXraySettingState(next);
     if (syncingRef.current) return;
@@ -142,63 +207,59 @@ export function useXraySetting(): UseXraySettingResult {
   }, []);
 
   const fetchAll = useCallback(async () => {
-    setFetchError('');
-    const msg = await HttpUtil.post('/panel/xray/');
-    if (!msg?.success) {
-      setFetchError(msg?.msg || 'Failed to load xray config');
-      setFetched(true);
-      return;
-    }
-    let obj;
-    try {
-      obj = JSON.parse(msg.obj);
-    } catch (e) {
-      const err = e as Error;
-      setFetchError(`Malformed xray config response: ${err?.message || String(err)}`);
-      setFetched(true);
-      return;
-    }
-    const pretty = JSON.stringify(obj.xraySetting, null, 2);
-    syncingRef.current = true;
-    setXraySettingState(pretty);
-    setTemplateSettingsState(obj.xraySetting);
-    oldXraySettingRef.current = pretty;
-    syncingRef.current = false;
-    setInboundTags(obj.inboundTags || []);
-    setClientReverseTags(obj.clientReverseTags || []);
-    const nextUrl = obj.outboundTestUrl || 'https://www.google.com/generate_204';
-    setOutboundTestUrlState(nextUrl);
-    oldOutboundTestUrlRef.current = nextUrl;
-    setFetched(true);
-    setSaveDisabled(true);
-  }, []);
+    await queryClient.invalidateQueries({ queryKey: keys.xray.config() });
+  }, [queryClient]);
 
-  const saveAll = useCallback(async () => {
-    setSpinning(true);
-    try {
-      const msg = await HttpUtil.post('/panel/xray/update', {
+  const fetchOutboundsTrafficCb = useCallback(async () => {
+    await queryClient.invalidateQueries({ queryKey: keys.xray.outboundsTraffic() });
+  }, [queryClient]);
+
+  const saveMut = useMutation({
+    mutationFn: async () =>
+      HttpUtil.post('/panel/xray/update', {
         xraySetting: xraySettingRef.current,
-        outboundTestUrl: outboundTestUrlRef.current || 'https://www.google.com/generate_204',
-      });
-      if (msg?.success) await fetchAll();
-    } finally {
-      setSpinning(false);
-    }
-  }, [fetchAll]);
+        outboundTestUrl: outboundTestUrlRef.current || DEFAULT_TEST_URL,
+      }) as Promise<ApiMsg>,
+    onSuccess: (msg) => {
+      if (msg?.success) queryClient.invalidateQueries({ queryKey: keys.xray.config() });
+    },
+  });
 
-  const fetchOutboundsTraffic = useCallback(async () => {
-    const msg = await HttpUtil.get('/panel/xray/getOutboundsTraffic');
-    if (msg?.success) setOutboundsTraffic(msg.obj || []);
-  }, []);
+  const resetTrafficMut = useMutation({
+    mutationFn: (tag: string) =>
+      HttpUtil.post('/panel/xray/resetOutboundsTraffic', { tag }) as Promise<ApiMsg>,
+    onSuccess: (msg) => {
+      if (msg?.success) queryClient.invalidateQueries({ queryKey: keys.xray.outboundsTraffic() });
+    },
+  });
 
-  const resetOutboundsTraffic = useCallback(async (tag: string) => {
-    const msg = await HttpUtil.post('/panel/xray/resetOutboundsTraffic', { tag });
-    if (msg?.success) await fetchOutboundsTraffic();
-  }, [fetchOutboundsTraffic]);
+  const restartMut = useMutation({
+    mutationFn: async () => {
+      const msg = await HttpUtil.post('/panel/api/server/restartXrayService') as ApiMsg;
+      if (!msg?.success) return msg;
+      await PromiseUtil.sleep(500);
+      const r = await HttpUtil.get('/panel/xray/getXrayResult') as ApiMsg<string>;
+      if (r?.success) setRestartResult(r.obj || '');
+      return msg;
+    },
+  });
 
-  const applyOutboundsEvent = useCallback((payload: unknown) => {
-    if (Array.isArray(payload)) setOutboundsTraffic(payload as OutboundTrafficRow[]);
-  }, []);
+  const resetDefaultMut = useMutation({
+    mutationFn: async () => HttpUtil.get('/panel/setting/getDefaultJsonConfig') as Promise<ApiMsg<XraySettingsValue>>,
+    onSuccess: (msg) => {
+      if (msg?.success && msg.obj) {
+        const cloned = JSON.parse(JSON.stringify(msg.obj));
+        setTemplateSettings(cloned);
+      }
+    },
+  });
+
+  const saveAll = useCallback(async () => { await saveMut.mutateAsync(); }, [saveMut]);
+  const resetOutboundsTraffic = useCallback(async (tag: string) => { await resetTrafficMut.mutateAsync(tag); }, [resetTrafficMut]);
+  const restartXray = useCallback(async () => { await restartMut.mutateAsync(); }, [restartMut]);
+  const resetToDefault = useCallback(async () => { await resetDefaultMut.mutateAsync(); }, [resetDefaultMut]);
+
+  const spinning = saveMut.isPending || restartMut.isPending || resetDefaultMut.isPending;
 
   const testOutbound = useCallback(
     async (index: number, outbound: unknown, mode = 'tcp'): Promise<OutboundTestResult | null> => {
@@ -212,11 +273,11 @@ export function useXraySetting(): UseXraySettingResult {
           outbound: JSON.stringify(outbound),
           allOutbounds: JSON.stringify(templateSettingsRef.current?.outbounds || []),
           mode,
-        });
-        if (msg?.success) {
+        }) as ApiMsg<OutboundTestResult>;
+        if (msg?.success && msg.obj) {
           setOutboundTestStates((prev) => ({
             ...prev,
-            [index]: { testing: false, result: msg.obj },
+            [index]: { testing: false, result: msg.obj as OutboundTestResult },
           }));
           return msg.obj;
         }
@@ -273,43 +334,16 @@ export function useXraySetting(): UseXraySettingResult {
     }
   }, [testingAll, testOutbound]);
 
-  const resetToDefault = useCallback(async () => {
-    setSpinning(true);
-    try {
-      const msg = await HttpUtil.get('/panel/setting/getDefaultJsonConfig');
-      if (msg?.success) {
-        const cloned = JSON.parse(JSON.stringify(msg.obj));
-        setTemplateSettings(cloned);
-      }
-    } finally {
-      setSpinning(false);
-    }
-  }, [setTemplateSettings]);
-
-  const restartXray = useCallback(async () => {
-    setSpinning(true);
-    try {
-      const msg = await HttpUtil.post('/panel/api/server/restartXrayService');
-      if (msg?.success) {
-        await PromiseUtil.sleep(500);
-        const r = await HttpUtil.get('/panel/xray/getXrayResult');
-        if (r?.success) setRestartResult(r.obj || '');
-      }
-    } finally {
-      setSpinning(false);
-    }
-  }, []);
-
   useEffect(() => {
-    fetchAll();
-    fetchOutboundsTraffic();
     const timer = window.setInterval(() => {
       const dirtyXray = oldXraySettingRef.current !== xraySettingRef.current;
       const dirtyUrl = oldOutboundTestUrlRef.current !== outboundTestUrlRef.current;
       setSaveDisabled(!(dirtyXray || dirtyUrl));
     }, DIRTY_POLL_MS);
     return () => window.clearInterval(timer);
-  }, [fetchAll, fetchOutboundsTraffic]);
+  }, []);
+
+  const outboundsTraffic = useMemo(() => trafficQuery.data ?? [], [trafficQuery.data]);
 
   return useMemo(
     () => ({
@@ -330,9 +364,8 @@ export function useXraySetting(): UseXraySettingResult {
       outboundTestStates,
       testingAll,
       fetchAll,
-      fetchOutboundsTraffic,
+      fetchOutboundsTraffic: fetchOutboundsTrafficCb,
       resetOutboundsTraffic,
-      applyOutboundsEvent,
       testOutbound,
       testAllOutbounds,
       saveAll,
@@ -357,9 +390,8 @@ export function useXraySetting(): UseXraySettingResult {
       outboundTestStates,
       testingAll,
       fetchAll,
-      fetchOutboundsTraffic,
+      fetchOutboundsTrafficCb,
       resetOutboundsTraffic,
-      applyOutboundsEvent,
       testOutbound,
       testAllOutbounds,
       saveAll,