create-ssnode-cli 0.2.5 → 0.2.7

package/templates/web/src/layouts/components/PageTabs/index.tsx

@@ -0,0 +1,110 @@
+import React, { useEffect, useRef } from 'react';
+import {
+  DndContext,
+  PointerSensor,
+  KeyboardSensor,
+  useSensor,
+  useSensors,
+  closestCenter,
+  type DragEndEvent,
+  type Modifier
+} from '@dnd-kit/core';
+import {
+  SortableContext,
+  horizontalListSortingStrategy,
+  sortableKeyboardCoordinates
+} from '@dnd-kit/sortable';
+import type { PageTabItem } from './usePageTabs';
+import SortableTab from './SortableTab';
+import styles from './index.module.less';
+
+/**
+ * 多页签条(《后台多页签KeepAlive方案》§3.3/§3.5):取代面包屑的 TagsView。
+ * 纯展示组件:数据与操作全由 usePageTabs 持有,本组件只渲染与转发事件。
+ * 右键页签呼出批量菜单(关闭其他/全部/刷新当前);页签常显关闭按钮
+ * (含工作台,唯一禁关规则「最后一个页签」由 usePageTabs.closeTab 兜底)。
+ *
+ * 2026-10-29 拖拽调序(@dnd-kit):
+ * - PointerSensor distance 4px —— 点击/Enter 跳转与拖拽按位移阈值区分,不误触
+ * - KeyboardSensor + sortableKeyboardCoordinates —— Space 拾起/方向键移动/Esc 取消
+ * - closestCenter 横向胶囊签条落点判定;DndContext 内建 autoScroll 溢出时边缘自动滚
+ * - 激活签变化时滚入视口(新签 append 最右后,溢出场景取代原「置顶天然可见」)
+ */
+interface PageTabsProps {
+  tabs: PageTabItem[];
+  activeKey: string;
+  onTabClick: (tab: PageTabItem) => void;
+  onTabClose: (tab: PageTabItem) => void;
+  onCloseOthers: () => void;
+  onCloseAll: () => void;
+  onRefresh: () => void;
+  /** 拖拽调序:把 fromKey 挪到 overKey 当前所在位(使用方 = usePageTabs.moveTab) */
+  onTabReorder: (fromKey: string, overKey: string) => void;
+}
+
+/**
+ * 横向拖拽限制:把跟随位移的 y 钉死为 0(官方 restrictToHorizontalAxis 的就地复刻 ——
+ * core 6.3.1 的 npm 包未内置该 modifier,只有 Modifier 类型与 applyModifiers)。
+ * 只影响拖起后的跟手渲染,不影响落点判定(closestCenter 本就只看水平中心距)。
+ */
+const restrictToHorizontalAxis: Modifier = ({ transform }) => ({ ...transform, y: 0 });
+
+export default function PageTabs({
+  tabs,
+  activeKey,
+  onTabClick,
+  onTabClose,
+  onCloseOthers,
+  onCloseAll,
+  onRefresh,
+  onTabReorder
+}: PageTabsProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // 激活签(新开/切回)滚入视口:inline nearest 只在溢出方向补滚,已可见则不动
+  useEffect(() => {
+    containerRef.current
+      ?.querySelector<HTMLElement>(`[data-tab-key="${CSS.escape(activeKey)}"]`)
+      ?.scrollIntoView({ inline: 'nearest', behavior: 'smooth' });
+  }, [activeKey, tabs.length]);
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 4 } }),
+    // 键盘拾起/落键只用 Space:默认配置含 Enter,会与页签 Enter 跳转打架
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortableKeyboardCoordinates,
+      keyboardCodes: { start: ['Space'], end: ['Space'], cancel: ['Escape'] }
+    })
+  );
+
+  const handleDragEnd = ({ active, over }: DragEndEvent) => {
+    if (over && active.id !== over.id) onTabReorder(String(active.id), String(over.id));
+  };
+
+  return (
+    <div className={styles.pageTabs} ref={containerRef}>
+      <DndContext
+        sensors={sensors}
+        collisionDetection={closestCenter}
+        modifiers={[restrictToHorizontalAxis]}
+        onDragEnd={handleDragEnd}
+      >
+        <SortableContext items={tabs.map((t) => t.key)} strategy={horizontalListSortingStrategy}>
+          {tabs.map((tab) => (
+            <SortableTab
+              key={tab.key}
+              dataTabKey={tab.key}
+              tab={tab}
+              isActive={tab.key === activeKey}
+              onTabClick={onTabClick}
+              onTabClose={onTabClose}
+              onRefresh={onRefresh}
+              onCloseOthers={onCloseOthers}
+              onCloseAll={onCloseAll}
+            />
+          ))}
+        </SortableContext>
+      </DndContext>
+    </div>
+  );
+}

package/templates/web/src/layouts/components/PageTabs/usePageTabs.ts

@@ -0,0 +1,224 @@
+/*
+ * Author  Murphy.xie
+ * Date  2026-10-29 18:24:37
+ * LastEditors  Murphy.xie
+ * LastEditTime  2026-11-04 09:55:15
+ * Description
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+import type { RefObject } from 'react';
+import type { KeepAliveRef } from 'keepalive-for-react';
+import RouterConfig, { getRouteByPathName } from '../../../../config/router.config';
+
+/**
+ * 多页签数据模型(《后台多页签KeepAlive方案》§3.4)
+ */
+export interface PageTabItem {
+  /** 页签唯一键 = pathname,与 KeepAlive 缓存键同源 */
+  key: string;
+  /** 页签标题(路由配置 name) */
+  title: string;
+  /** 切回该页签时要还原的完整地址(search 系页面状态真源,必须带回) */
+  location: { pathname: string; search: string };
+  /**
+   * 最近一次激活时间戳。2026-10-29 排序权下放用户(拖拽调序 + 新签不再置顶)后,
+   * 视觉顺序不再表达访问新旧,超限淘汰改为按本字段取 LRU 最旧,与视觉顺序解耦
+   */
+  lastActiveAt: number;
+}
+
+/** 页签/缓存上限:超出按 lastActiveAt 淘汰 LRU 最旧(KeepAlive max 同值) */
+export const MAX_TABS = 20;
+/**
+ * 不建页签的路径:与 Background 布局 KeepAlive exclude 同源。`/background` 是布局基座路径,
+ * 经其进入会先以 pathname='/background' 渲染一帧 <Navigate to='/background/page-data'>
+ * (菜单树首项 { path:'/', redirect:'/page-data' } 的 fullPath 落点即 /background)。该帧非真实页面,
+ * 不应建页签(否则多出一个「后台管理系统」幽灵签),与旧 TabBar 按菜单树过滤(redirect 子项无 name)
+ * 不建签的口径等价。改 KeepAlive exclude 时此处同步。
+ */
+const NO_TAB_PATHS = ['/background'];
+
+/**
+ * 取路由名做页签标题:路由链末节点 name,兜底「未命名」。
+ * hideInMenu 页(智能助手/消息中心)也有 name,天然覆盖。
+ * getRouteByPathName 只做字面量全等,参数路由(./:id 等)须按段通配回退匹配,
+ * 否则详情类深链(/background/assessment/3)全落「未命名」。
+ */
+const resolveTabTitle = (pathname: string): string => {
+  const { routes } = getRouteByPathName(pathname);
+  if (routes.length > 0) return routes[routes.length - 1]?.name || '未命名';
+  // 段数一致 + :param 段当通配符,命中末节点即取其 name
+  const segments = pathname.split('/').filter(Boolean);
+  const matchParamRoute = (routeList: typeof RouterConfig): string | null =>
+    routeList.reduce((found, route) => {
+      if (found) return found;
+      const routeSegments = (route.fullPath || '').split('/').filter(Boolean);
+      const hit =
+        routeSegments.length === segments.length &&
+        routeSegments.every(
+          (seg, i) => (seg.startsWith(':') && segments[i]) || seg === segments[i]
+        );
+      if (hit && route.name) return route.name;
+      return route.children ? matchParamRoute(route.children) : null;
+    }, null);
+  return matchParamRoute(RouterConfig) || '未命名';
+};
+
+const makeTab = (pathname: string, search: string): PageTabItem => ({
+  key: pathname,
+  title: resolveTabTitle(pathname),
+  location: { pathname, search },
+  lastActiveAt: Date.now()
+});
+
+/**
+ * LRU 淘汰:剔除 lastActiveAt 最小且非当前激活的页签(当前签恒为最新,不会被误伤)。
+ * 只动页签数组(UI 数据),缓存仍交 KeepAlive max 自管 —— 与原「删最右」等价,
+ * 但不再要求「最右 = 最久未访问」这一已退役的前置假设。
+ */
+const evictLeastRecent = (list: PageTabItem[], activeKey: string): PageTabItem[] => {
+  let victimIdx = -1;
+  let minAt = Infinity;
+  list.forEach((t, i) => {
+    if (t.key !== activeKey && t.lastActiveAt < minAt) {
+      minAt = t.lastActiveAt;
+      victimIdx = i;
+    }
+  });
+  if (victimIdx === -1) return list;
+  const copy = [...list];
+  copy.splice(victimIdx, 1);
+  return copy;
+};
+
+/**
+ * 多页签状态与操作(《后台多页签KeepAlive方案》)
+ *
+ * 关键口径:
+ * 1. **activeKey 不落 state,恒由 location.pathname 派生** —— 页签关闭(destroy 缓存)与
+ *    navigate(激活邻页)若分两个 commit,KeepAlive 会对已销毁的 pathname 新建幽灵缓存节点
+ *    (挂一份邻页组件实例泄内存);闭包内同步 navigate + destroy 由 URL 派生键原子兜死。
+ * 2. **页签数组只是 UI 数据**,允许滞后一个 commit,不参与缓存键计算。
+ *    2026-10-29 起**顺序由用户掌控**:新签 append 最右、激活不挪位(原 activeToFront 置顶退役),
+ *    顺序只在拖拽调序(moveTab)与超限淘汰时变化;溢出视口的新签可见性由 PageTabs 滚入兜底。
+ * 3. **关闭/刷新等缓存操作全部走 aliveRef**(destroy / refresh),不自研缓存管理。
+ *
+ * @param aliveRef KeepAlive 的命令通道(useKeepAliveRef() 产物,由调用方持有)
+ * @param homePath 关闭最后一个页签 / 全部关闭时的回落主页,默认 /background/page-data
+ *   (本模板后台首个菜单叶「页面管理」,即 Background 索引路由 redirect:'/page-data' 的落点)。
+ *   回落式兜底,不预置常驻首页签;首个签 = 落地页,全关完回 homePath 由上方 effect 重建其签。
+ */
+export default function usePageTabs(
+  aliveRef: RefObject<KeepAliveRef>,
+  homePath = '/background/page-data'
+) {
+  const location = useLocation();
+  const navigate = useNavigate();
+
+  // 页签条初始:仅当前页(不预置常驻首页签);/background 基座帧不建签(NO_TAB_PATHS)
+  const [tabs, setTabs] = useState<PageTabItem[]>(() =>
+    NO_TAB_PATHS.includes(location.pathname) ? [] : [makeTab(location.pathname, location.search)]
+  );
+
+  // 激活键:URL 唯一真源派生,不用独立 state(见头部口径 1)
+  const activeKey = location.pathname;
+
+  // 路由变化 → 开新签(append 最右)/ 激活已开签并同步最新 search(search 变化不另开签);
+  // 激活只刷新 lastActiveAt(超限 LRU 淘汰依据),不挪位 —— 点页签/菜单/深链三入口口径一致
+  useEffect(() => {
+    const { pathname, search } = location;
+    if (NO_TAB_PATHS.includes(pathname)) return;
+    setTabs((prev) => {
+      const idx = prev.findIndex((t) => t.key === pathname);
+      if (idx === -1) {
+        const next = [...prev, makeTab(pathname, search)];
+        // 超上限淘汰:lastActiveAt 最旧者(新签即当前签,恒不被淘汰)
+        return next.length > MAX_TABS ? evictLeastRecent(next, pathname) : next;
+      }
+      const hit = prev[idx];
+      const copy = [...prev];
+      copy[idx] = { ...hit, location: { pathname, search }, lastActiveAt: Date.now() };
+      return copy;
+    });
+  }, [location.pathname, location.search]);
+
+  /** 点击页签:还原完整地址(pathname+search) */
+  const activeTab = useCallback(
+    (tab: PageTabItem) => {
+      if (tab.key === activeKey && tab.location.search === location.search) return;
+      navigate({ pathname: tab.location.pathname, search: tab.location.search });
+    },
+    [navigate, activeKey, location.search]
+  );
+
+  /**
+   * 关闭页签:删签 + 销毁缓存;关的是当前页签则跳相邻(顺序由用户掌控后,
+   * 数组相邻位即视觉相邻,不再按「次新访问」挑选);无相邻(关最后一个)回落 homePath。
+   * 页签条允许瞬时空(回落导航触发上方 effect 重建 homePath 签),与旧 TabBar 行为一致。
+   */
+  const closeTab = useCallback(
+    (tab: PageTabItem) => {
+      const idx = tabs.findIndex((t) => t.key === tab.key);
+      if (idx === -1) return;
+      const neighbor = tabs[idx - 1] || tabs[idx + 1];
+      setTabs((prev) => prev.filter((t) => t.key !== tab.key));
+      aliveRef.current?.destroy(tab.key);
+      if (tab.key === activeKey) {
+        navigate(
+          neighbor
+            ? { pathname: neighbor.location.pathname, search: neighbor.location.search }
+            : homePath
+        );
+      }
+    },
+    [tabs, activeKey, navigate, aliveRef, homePath]
+  );
+
+  /** 关闭其他:只留当前签,其余连缓存一起销毁 */
+  const closeOthers = useCallback(() => {
+    const victims = tabs.filter((t) => t.key !== activeKey).map((t) => t.key);
+    aliveRef.current?.destroy(victims);
+    setTabs((prev) => prev.filter((t) => t.key === activeKey));
+  }, [tabs, activeKey, aliveRef]);
+
+  /** 全部关闭:清光其他签连缓存,回 homePath 兜底主页(homePath 签/缓存保留,未开则由 effect 重建) */
+  const closeAll = useCallback(() => {
+    const victims = tabs.filter((t) => t.key !== homePath).map((t) => t.key);
+    aliveRef.current?.destroy(victims);
+    setTabs([makeTab(homePath, '')]);
+    if (activeKey !== homePath) navigate(homePath);
+  }, [tabs, activeKey, navigate, aliveRef, homePath]);
+
+  /** 刷新当前页签:renderCount+1 强制重建组件(仅当前签可刷) */
+  const refreshTab = useCallback(() => {
+    aliveRef.current?.refresh(activeKey);
+  }, [activeKey, aliveRef]);
+
+  /**
+   * 拖拽调序(PageTabs onTabReorder 载荷):把 fromKey 页签挪到 overKey 页签当前所在位。
+   * 顺序是纯 UI 数据(口径 2),不触发任何缓存操作;lastActiveAt 不动,淘汰依据不受拖拽影响
+   */
+  const moveTab = useCallback((fromKey: string, overKey: string) => {
+    setTabs((prev) => {
+      const fromIdx = prev.findIndex((t) => t.key === fromKey);
+      const overIdx = prev.findIndex((t) => t.key === overKey);
+      if (fromIdx === -1 || overIdx === -1 || fromIdx === overIdx) return prev;
+      const copy = [...prev];
+      const [moved] = copy.splice(fromIdx, 1);
+      copy.splice(overIdx, 0, moved);
+      return copy;
+    });
+  }, []);
+
+  return {
+    tabs,
+    activeKey,
+    activeTab,
+    closeTab,
+    closeOthers,
+    closeAll,
+    refreshTab,
+    moveTab
+  };
+}

package/templates/web/src/pages/Backend/Image/index.tsx

@@ -111,13 +111,13 @@ export default function ImageManage() {
   };
 
   /** 列表行预览:与大屏同款 ImagePreview(点击缩略图全屏预览,可翻页) */
-  const RowPreview = ({ item }: { item: ImageItem }) => (
-    <ImagePreview
+  function RowPreview({ item }: { item: ImageItem }) {
+    return <ImagePreview
       images={[{ imageUrl: item.url, description: item.name }]}
       thumbnailSrc={item.url}
       thumbnailSize={{ width: 56, height: 40 }}
-    />
-  );
+    />;
+  }
 
   const columns = [
     {

package/templates/web/src/pages/Maintenance/index.module.less

@@ -0,0 +1,177 @@
+// 维护页:白底黑字简约风,与 404 页同一设计语言
+.wrapper {
+  width: 100%;
+  height: 100vh;
+  box-sizing: border-box;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  background: #fff;
+  color: #1a1a1a;
+  overflow: hidden;
+  position: relative;
+
+  // ============ 插画区:齿轮转动 + 扳手轻微摆动 ============
+  .illustration {
+    position: relative;
+    width: 320px;
+    height: 240px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+
+    // 大齿轮(左):断续描边模拟轮齿,旋转动画
+    .gearBig {
+      transform-origin: 128px 128px;
+      animation: gearRotate 12s linear infinite;
+    }
+
+    // 小齿轮(右上):反向旋转
+    .gearSmall {
+      transform-origin: 214px 62px;
+      animation: gearRotate 8s linear infinite reverse;
+    }
+
+    // 扳手:绕卡口一端轻微摆动,像在"拧"
+    .wrench {
+      transform-origin: 245px 120px;
+      animation: wrenchSwing 2.4s ease-in-out infinite;
+    }
+
+    // 底部阴影椭圆:轻微呼吸
+    .shadow {
+      animation: shadowBreath 2.4s ease-in-out infinite;
+    }
+  }
+
+  // ============ 文案区 ============
+  .title {
+    margin-top: 8px;
+    font-size: 30px;
+    font-weight: 700;
+    letter-spacing: 2px;
+    color: #1a1a1a;
+  }
+
+  .subtitle {
+    margin-top: 12px;
+    font-size: 15px;
+    color: rgba(0, 0, 0, 0.45);
+    letter-spacing: 1px;
+  }
+
+  // 服务状态行(检测中 / 仍在维护)
+  .status {
+    margin-top: 20px;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 13px;
+    color: rgba(0, 0, 0, 0.55);
+
+    // 探测指示灯
+    .dot {
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      background: #faad14;
+      animation: dotBlink 1.2s ease-in-out infinite;
+    }
+  }
+
+  // ============ 操作区 ============
+  .actions {
+    margin-top: 32px;
+    display: flex;
+    gap: 16px;
+    justify-content: center;
+
+    .retry {
+      padding: 11px 32px;
+      font-size: 15px;
+      font-weight: 500;
+      border-radius: 24px;
+      cursor: pointer;
+      color: #fff;
+      background: #000;
+      border: 1px solid #000;
+      box-sizing: border-box;
+      transition: all 0.2s ease;
+
+      &:hover {
+        opacity: 0.8;
+      }
+
+      &:disabled {
+        cursor: not-allowed;
+        opacity: 0.4;
+      }
+    }
+
+    .home {
+      padding: 11px 32px;
+      font-size: 15px;
+      font-weight: 500;
+      border-radius: 24px;
+      cursor: pointer;
+      color: #000;
+      border: 1px solid #000;
+      background: transparent;
+      box-sizing: border-box;
+      transition: all 0.2s ease;
+
+      &:hover {
+        background: #000;
+        color: #fff;
+      }
+    }
+  }
+}
+
+// ============ 动画 ============
+@keyframes gearRotate {
+  from {
+    transform: rotate(0deg);
+  }
+
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@keyframes wrenchSwing {
+  0%,
+  100% {
+    transform: rotate(-6deg);
+  }
+
+  50% {
+    transform: rotate(8deg);
+  }
+}
+
+@keyframes shadowBreath {
+  0%,
+  100% {
+    transform: scaleX(1);
+    opacity: 0.7;
+  }
+
+  50% {
+    transform: scaleX(0.85);
+    opacity: 0.5;
+  }
+}
+
+@keyframes dotBlink {
+  0%,
+  100% {
+    opacity: 1;
+  }
+
+  50% {
+    opacity: 0.25;
+  }
+}

package/templates/web/src/pages/Maintenance/index.tsx

@@ -0,0 +1,142 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { consumeReturnPath } from '../../services/maintenance';
+import styles from './index.module.less';
+
+/**
+ * 维护页:后端接口返回 502(服务不可用/发版重启)时由请求层自动整页跳入。
+ *
+ * 页面每 10 秒(以及点击「立即重试」时)用原生 fetch 探活无鉴权的
+ * GET /api/version —— 刻意不走 axios 实例:一来避免探活失败又被
+ * 502 拦截器拉回本页(死循环),二来探活不应受签名/鉴权头影响。
+ * 探测通过即自动跳回进入维护前的原页面。
+ */
+
+/** 自动探活间隔 */
+const PROBE_INTERVAL = 10 * 1000;
+
+export default function Maintenance() {
+  const navigate = useNavigate();
+  const [probing, setProbing] = useState(false);
+  // 探活互斥(手动重试撞上定时探测时只跑一个)
+  const probingRef = useRef(false);
+  // 进入维护前的来源路径,恢复后跳回(只取一次)
+  const returnPathRef = useRef(consumeReturnPath());
+
+  const probe = useCallback(async () => {
+    if (probingRef.current) return;
+    probingRef.current = true;
+    setProbing(true);
+    try {
+      const res = await fetch(`${window.ENV?.requestBaseUrl || ''}/api/version`, {
+        cache: 'no-store'
+      });
+      if (res.ok) {
+        // 服务恢复,跳回来源页
+        navigate(returnPathRef.current);
+        return;
+      }
+    } catch (e) {
+      // 网络仍不通:继续等待下一轮探测
+    }
+    probingRef.current = false;
+    setProbing(false);
+  }, [navigate]);
+
+  useEffect(() => {
+    // 进入页面先探一次,再起定时器
+    probe();
+    const timer = setInterval(probe, PROBE_INTERVAL);
+    return () => clearInterval(timer);
+  }, [probe]);
+
+  return (
+    <div className={styles.wrapper}>
+      {/* 插画:大齿轮 + 小齿轮反向转 + 扳手摆动(纯 SVG + CSS 动画,无外部资源) */}
+      <div className={styles.illustration}>
+        <svg width="320" height="240" viewBox="0 0 320 240" fill="none" aria-hidden="true">
+          {/* 底部阴影 */}
+          <ellipse
+            className={styles.shadow}
+            cx="160"
+            cy="230"
+            rx="92"
+            ry="9"
+            fill="#000"
+            opacity="0.06"
+          />
+          {/* 大齿轮:断续描边模拟轮齿(pathLength 归一化保证齿距均匀) */}
+          <g className={styles.gearBig}>
+            <circle
+              cx="128"
+              cy="128"
+              r="64"
+              stroke="#1a1a1a"
+              strokeWidth="18"
+              pathLength="100"
+              strokeDasharray="3.3 1.7"
+            />
+            <circle cx="128" cy="128" r="52" stroke="#1a1a1a" strokeWidth="10" />
+            <circle cx="128" cy="128" r="14" fill="#1a1a1a" />
+          </g>
+          {/* 小齿轮(灰)反向转 */}
+          <g className={styles.gearSmall}>
+            <circle
+              cx="214"
+              cy="62"
+              r="36"
+              stroke="rgba(0,0,0,0.32)"
+              strokeWidth="12"
+              pathLength="100"
+              strokeDasharray="4 2.5"
+            />
+            <circle cx="214" cy="62" r="27" stroke="rgba(0,0,0,0.32)" strokeWidth="6" />
+            <circle cx="214" cy="62" r="6" fill="rgba(0,0,0,0.32)" />
+          </g>
+          {/* 扳手:粗杆 + 开口卡爪(不闭合圆 + 缺口),正卡在小齿轮下方 */}
+          <g className={styles.wrench}>
+            <line
+              x1="140"
+              y1="214"
+              x2="245"
+              y2="120"
+              stroke="#1a1a1a"
+              strokeWidth="10"
+              strokeLinecap="round"
+            />
+            <circle
+              cx="245"
+              cy="120"
+              r="17"
+              stroke="#1a1a1a"
+              strokeWidth="10"
+              pathLength="100"
+              strokeDasharray="66 34"
+              transform="rotate(60 245 120)"
+            />
+            <circle cx="245" cy="120" r="4" fill="#1a1a1a" />
+          </g>
+        </svg>
+      </div>
+
+      <div className={styles.title}>系统正在维护中</div>
+      <div className={styles.subtitle}>请耐心等待，我们正在加紧处理，很快就会恢复</div>
+
+      <div className={styles.status}>
+        <span className={styles.dot} />
+        <span>{probing ? '正在检测服务状态…' : '服务尚未恢复，每 10 秒自动重试'}</span>
+      </div>
+
+      <div className={styles.actions}>
+        <button
+          type="button"
+          className={styles.retry}
+          disabled={probing}
+          onClick={() => probe()}
+        >
+          {probing ? '检测中…' : '立即重试'}
+        </button>
+      </div>
+    </div>
+  );
+}

package/templates/web/src/services/api.ts

@@ -43,6 +43,10 @@ request.interceptors.response.use(
     if (e?.config?.url?.includes('/api/login')) {
       return Promise.reject(e);
     }
+    // 502(后端不可用)由 request 层拦截器整页跳维护页,不弹全局错误提示
+    if (e?.response?.status === 502) {
+      return Promise.reject(e);
+    }
     // 内部接口 URL(可能含内网 IP/端口)不弹给最终用户,只走 console
     // eslint-disable-next-line no-console
     console.error('request error:', e?.config?.url || e?.request?.responseURL, e?.message);