feat(hosts): add one-click Categraf install dialog and templated install docs - #2202

🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Handle rejection of every fallback document request. In both components, the fallback fetch is returned from a catch handler without a final rejection handler.

• src/components/DocumentDrawer/Document.tsx#L47-L53: add a terminal catch or explicit error state after the en_US fallback request.
• src/components/DocumentDrawer/index.tsx#L58-L64: add a terminal catch or explicit error state after the en_US fallback request.

As per coding guidelines, all asynchronous requests must include error handling consistent with existing patterns.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/components/DocumentDrawer/Document.tsx` around lines 47 - 53, Handle
rejection from the en_US fallback fetch by adding terminal error handling after
the fallback promise chain in Document.tsx (lines 47-53) and index.tsx (lines
58-64). Apply the existing request-error pattern or set an explicit error state
in both fallback paths so every asynchronous request is handled.

Source: Coding guidelines

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Concurrent captureBaseline() calls can clobber the baseline with stale data.

captureBaseline has no guard against re-entrancy. While status is 'baselining' (or whenever baselineRef.current is still null), the useInterval tick (Line 59-64) fires every POLL_INTERVAL and calls captureBaseline() again — even if the original call from start() (Line 43) is merely slow, not failed. If the first (now-stale) call resolves after the second, it overwrites baselineRef.current with older data, which can produce a spurious "new host detected" or mask a real one on the next tick. This will reproduce deterministically whenever probeTargets takes ≥5s to resolve.

+  const capturingRef = useRef(false);
+
   const captureBaseline = useCallback(async () => {
-    const [all, ungrouped] = await Promise.all([probeTargets(), probeTargets({ gids: '0', limit: 100 })]);
-    if (!all) return false;
-    baselineRef.current = {
-      total: all.total,
-      ungrouped: new Set(_.map(ungrouped?.list ?? [], 'ident')),
-    };
-    return true;
+    if (capturingRef.current) return false;
+    capturingRef.current = true;
+    try {
+      const [all, ungrouped] = await Promise.all([probeTargets(), probeTargets({ gids: '0', limit: 100 })]);
+      if (!all) return false;
+      baselineRef.current = {
+        total: all.total,
+        ungrouped: new Set(_.map(ungrouped?.list ?? [], 'ident')),
+      };
+      return true;
+    } finally {
+      capturingRef.current = false;
+    }
   }, []);

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/pages/hosts/pages/List/InstallCategraf/useTargetArrival.ts` around lines
24 - 65, Prevent overlapping baseline probes in captureBaseline by adding an
in-flight guard or shared promise, so start and the useInterval recovery path
reuse the same capture attempt rather than launching concurrent calls. Ensure
the guard is cleared when the attempt settles, while baselineRef.current is
updated only from the active capture result and existing success/failure status
behavior is preserved.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Non-2xx responses are cached as "unsupported" forever, defeating the stated retry intent.

The docstring says network-layer failures aren't cached so a "next mount" retry is possible, but that guarantee only covers fetch rejecting. If the response resolves with !res.ok (Line 85) — e.g. a transient 401 because the access token was mid-refresh at initial page load, or a 500 — categrafMetaPromise is never reset, so null is memoized for the rest of the SPA session and the install entry silently disappears until a full page reload, exactly the failure mode the comment says it's trying to avoid.

Consider only treating clearly deterministic "route doesn't exist" signals (e.g. 404) as permanently cacheable, and resetting the cache (like the catch block already does) for other non-2xx statuses so a later mount can retry.

       .then(async (res) => {
-        if (!res.ok) return null;
+        if (!res.ok) {
+          // 404 之外的状态码（如登录态刷新期间的 401、临时的 5xx）不代表「不支持」，
+          // 不能永久缓存，否则一次瞬断会让入口整个会话消失
+          if (res.status !== 404) categrafMetaPromise = undefined;
+          return null;
+        }

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/pages/hosts/services.ts` around lines 72 - 110, Update
getCategrafInstallMeta’s response handling so only a deterministic missing-route
response such as 404 remains cached as null; for other non-2xx responses, clear
categrafMetaPromise before returning null, matching the retry behavior in the
catch block. Preserve the existing successful JSON validation and network-error
handling.