node-resource-utils 0.0.0-stage → 1.1.8

package/resources/src/components/admin/AdminShell.tsx

@@ -0,0 +1,749 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { APP_NAME, APP_SHORT, APP_SUBTITLE } from '@/lib/appInfo';
+import { brandMark } from '@/lib/brand-mark';
+import Link from 'next/link';
+import { usePathname, useRouter } from 'next/navigation';
+import { signOut } from 'next-auth/react';
+import { App, Avatar, Breadcrumb, Button, Dropdown, Layout, Menu, Space, Tooltip, type MenuProps } from 'antd';
+import {
+  BgColorsOutlined,
+  CloseOutlined,
+  HomeOutlined,
+  LogoutOutlined,
+  MenuFoldOutlined,
+  MenuUnfoldOutlined,
+  QuestionCircleOutlined,
+  StarFilled,
+  StarOutlined,
+  UserOutlined,
+} from '@ant-design/icons';
+import type { SessionUser } from '@/auth';
+import type { MenuTreeNode } from '@/lib/menu-service';
+import { buildSearchEntries } from '@/lib/menu-service';
+import { MAX_FAVORITES, buildFavoriteIndex, resolveFavorites } from '@/lib/favorite-path';
+import { sumBadges } from '@/lib/badges';
+import { iconOf } from './menu-icons';
+import CountBadge from './CountBadge';
+import GlobalSearch from './GlobalSearch';
+import InboxBell from './InboxBell';
+import VisitStats from './VisitStats';
+import { MILITARY, fs } from '@/lib/theme';
+import { useAppearance } from '@/components/appearance/AppearanceProvider';
+import { startRouteProgress } from '@/components/feedback/RouteProgress';
+import { clearTasks } from '@/lib/pending';
+
+/**
+ * 后台外壳：侧边菜单 + 顶栏 + 内容区。
+ *
+ * 菜单数据由服务端传入（layout.tsx），而不是前端登录后再请求一次：
+ * 这样首屏 HTML 里就带着完整侧边栏，不会出现「先进去再闪出菜单」的观感。
+ * 收藏路径同理，服务端一起直出 —— 收藏区固定在侧边栏顶部，闪一下整块菜单都会跳。
+ *
+ * 徽标（未读数 / 待办数）也走同一条路：服务端算好随首屏直出，
+ * 之后由前端轮询增量刷新。挂在菜单上而不是页面里，
+ * 于是"哪个模块亮红点"是一条数据配置，新模块不用改这个文件。
+ *
+ * 图标用「字符串 → 组件」的显式映射表（menu-icons.tsx），
+ * 侧边栏、收藏区与全局搜索共用一份。
+ */
+
+/** 菜单 path → 待处理/未读条数 */
+type BadgeMap = Record<string, number>;
+
+/**
+ * 侧边栏深/浅底上的文字色阶 —— 全部取 CSS 变量。
+ * 三套皮肤的侧栏材质完全不同（深军绿面料 / 纸白 / 舱壁网格），
+ * 所以这里不能写死任何 rgba，否则换皮肤会出现"浅底白字"。
+ */
+const SIDER = {
+  text: 'var(--wb-sider-text)',
+  textStrong: 'var(--wb-sider-text-strong)',
+  textMuted: 'var(--wb-sider-text-muted)',
+  hoverBg: 'var(--wb-sider-hover)',
+  activeBg: 'var(--wb-sider-active)',
+  line: 'var(--wb-sider-line)',
+} as const;
+
+/**
+ * 一个菜单节点要显示的徽标数。
+ *
+ * 目录取「自身 + 所有可见子项」之和：分组收起、或整栏折叠时，
+ * 子项的徽标根本看不见，父级不兜一个总数就等于这条提示消失了。
+ * 隐藏项不计入 —— 用户点不进去，算了只会让他对不上账。
+ */
+function badgeCountOf(node: MenuTreeNode, badges: BadgeMap): number {
+  if (node.type === 'button' || node.hidden === 1) return 0;
+  const own = node.path ? badges[node.path] ?? 0 : 0;
+  if (node.type !== 'dir') return own;
+  return sumBadges([own, ...node.children.map((c) => badgeCountOf(c, badges))]);
+}
+
+/**
+ * 菜单文字 + 行尾徽标；文字自己吃省略号，徽标永远完整显示。
+ *
+ * `flex: 1 1 auto` 不是随手加的（2026-10-23 修）：分组标题（dir）里
+ * antd 把展开箭头绝对定位在右侧，并给标题留了 `padding-inline-end: 34px`
+ * 当它的地盘。若这一行只写 `width: 100%`，百分比是按**内容盒**算的、
+ * 且作为 flex 子项默认不收缩，于是整行会顶进那 34px 内边距，
+ * 行尾徽标正好压在箭头上（实测右边缘 203 vs 箭头 187~197，重叠 16px）。
+ * 允许收缩后整行缩回内容盒内，徽标与箭头之间就能留出 8px 间距。
+ */
+function menuLabel(name: string, count: number): ReactNode {
+  return (
+    <span
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 8,
+        width: '100%',
+        flex: '1 1 auto',
+        minWidth: 0,
+      }}
+    >
+      <span
+        style={{ flex: '1 1 auto', minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}
+      >
+        {name}
+      </span>
+      <CountBadge value={count} label={name} />
+    </span>
+  );
+}
+
+/**
+ * 图标（+ 折叠态叠加的徽标）。
+ *
+ * 折叠后 antd 只渲染 icon，label 里的徽标随之消失。这时把数字压到图标右上角，
+ * 否则"折叠一下就再也看不到有没有待办"——很多人习惯一直折叠着用侧边栏。
+ */
+function menuIcon(icon: string | null, count: number, name: string, collapsed: boolean): ReactNode {
+  const node = iconOf(icon);
+  if (!collapsed || count <= 0) return node;
+  return (
+    <span style={{ position: 'relative', display: 'inline-flex', alignItems: 'center' }}>
+      {node}
+      <CountBadge value={count} floating label={name} />
+    </span>
+  );
+}
+
+/** 菜单树 → antd Menu items；按钮与隐藏项在这里被过滤掉 */
+function toMenuItems(
+  nodes: MenuTreeNode[],
+  badges: BadgeMap,
+  collapsed: boolean
+): NonNullable<MenuProps['items']> {
+  const out: NonNullable<MenuProps['items']> = [];
+  for (const n of nodes) {
+    if (n.type === 'button' || n.hidden === 1) continue;
+    const children = toMenuItems(n.children, badges, collapsed);
+    const key = n.path || n.id;
+    const count = badgeCountOf(n, badges);
+    if (n.type === 'dir') {
+      if (!children.length) continue; // 目录下的菜单全被过滤掉时，目录自身也不该显示
+      out.push({
+        key,
+        icon: menuIcon(n.icon, count, n.name, collapsed),
+        label: menuLabel(n.name, count),
+        children,
+      });
+    } else {
+      out.push({
+        key,
+        icon: menuIcon(n.icon, count, n.name, collapsed),
+        label: menuLabel(n.name, count),
+      });
+    }
+  }
+  return out;
+}
+
+/** 在菜单树里找出 pathname 对应的链路，用于面包屑与默认展开 */
+function findTrail(nodes: MenuTreeNode[], pathname: string, trail: MenuTreeNode[] = []): MenuTreeNode[] {
+  for (const n of nodes) {
+    const next = [...trail, n];
+    if (n.path && (pathname === n.path || pathname.startsWith(`${n.path}/`))) return next;
+    const deep = findTrail(n.children, pathname, next);
+    if (deep.length && deep[deep.length - 1].path) return deep;
+  }
+  return [];
+}
+
+/**
+ * 调收藏接口，统一处理 { code, data, message } 约定。
+ * 失败抛错由调用方回滚乐观更新。
+ */
+async function callFavorites(method: 'POST' | 'DELETE', path: string): Promise<string[]> {
+  const url =
+    method === 'DELETE' ? `/api/favorites?path=${encodeURIComponent(path)}` : '/api/favorites';
+  const res = await fetch(url, {
+    method,
+    headers: method === 'POST' ? { 'Content-Type': 'application/json' } : undefined,
+    body: method === 'POST' ? JSON.stringify({ path }) : undefined,
+  });
+  const json = await res.json();
+  if (json?.code !== 0) throw new Error(json?.message || '收藏操作失败');
+  return (json.data ?? []) as string[];
+}
+
+export default function AdminShell({
+  user,
+  menus,
+  favorites,
+  badges: initialBadges,
+  inboxCount,
+  children,
+}: {
+  user: SessionUser;
+  menus: MenuTreeNode[];
+  /** 当前用户收藏的路由（服务端直出，只需 path，文案与图标在下面反查） */
+  favorites: string[];
+  /** 首屏徽标（服务端直出）：`{ '/feedback': 3 }` */
+  badges: BadgeMap;
+  /** 顶栏铃铛首屏数字：待办 + 未读消息 */
+  inboxCount: number;
+  children: ReactNode;
+}) {
+  const router = useRouter();
+  const pathname = usePathname();
+  const { modal, message } = App.useApp();
+  /** 当前皮肤：决定侧栏深/浅、菜单 theme、以及顶栏那道签名光 */
+  const { skin, openPanel } = useAppearance();
+  const [collapsed, setCollapsed] = useState(false);
+
+  /* ------------------------------ 侧边栏徽标 ------------------------------ */
+
+  const [badges, setBadges] = useState<BadgeMap>(initialBadges);
+
+  /**
+   * 拉一次最新计数；传 ackPath 时顺带把该页的"未读"清零。
+   *
+   * 刻意用原生 fetch 而不是 trackedFetch：徽标是后台静默刷新，
+   * 绝不能因为一次轮询进了全局等待浮层，那会把"后台在数数"说成"你在等"。
+   * 失败也一律吞掉 —— 徽标拉不到就不显示，不该弹任何错误。
+   */
+  const syncBadges = useCallback(async (ackPath?: string) => {
+    try {
+      const res = await fetch(
+        '/api/badges',
+        ackPath
+          ? {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ path: ackPath }),
+            }
+          : { cache: 'no-store' }
+      );
+      const json = (await res.json()) as { code: number; data?: BadgeMap };
+      if (json?.code === 0 && json.data) setBadges(json.data);
+    } catch {
+      /* 静默：徽标是提示，不是业务数据 */
+    }
+  }, []);
+
+  /**
+   * 站内跳转统一走这里。
+   *
+   * 不直接 router.push 的原因：客户端跳转要等下一屏的 JS chunk，
+   * 重页面（图谱、工作台）会有明显的"点了没反应"窗口。
+   * 先点亮顶部进度条，用户至少在第一时间看到"它动了"；
+   * pathname 一变，RouteProgress 自己收尾，不需要在这里善后。
+   */
+  const goto = useCallback(
+    (path: string) => {
+      startRouteProgress();
+      router.push(path);
+    },
+    [router]
+  );
+
+  const menuItems = useMemo(
+    () => toMenuItems(menus, badges, collapsed),
+    [menus, badges, collapsed]
+  );
+
+  // 全局搜索索引：和侧边栏同一份菜单树，权限可见范围完全一致
+  const searchEntries = useMemo(() => buildSearchEntries(menus), [menus]);
+
+  const trail = useMemo(() => findTrail(menus, pathname), [menus, pathname]);
+  const selectedKey = trail.length ? trail[trail.length - 1].path || pathname : pathname;
+  /** 当前页对应的真实菜单路由；不在菜单里（详情页等）时为 null，星标不出现 */
+  const currentPath = trail.length ? trail[trail.length - 1].path : null;
+  /** 当前页挂的计数源；null = 这页没有徽标，进页面也不用 ack */
+  const currentBadgeKey = trail.length ? trail[trail.length - 1].badgeKey : null;
+
+  /**
+   * 进入某个模块 → 让它的"未读"计数归零。
+   *
+   * 三个细节：
+   *   - 只认**挂在菜单上**的计数源：没配 badgeKey 的页面不产生任何请求
+   *   - 用 ref 记住上一次处理过的 path：轮询、折叠侧边栏都会让 trail 重算，
+   *     没有这层去重就会一直重复 ack（清零本身幂等，但白打请求）
+   *   - ack 的返回就是最新全量计数，一次往返同时完成"清零"和"刷新"
+   */
+  const ackedPathRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!currentPath || ackedPathRef.current === currentPath) return;
+    ackedPathRef.current = currentPath;
+    void syncBadges(currentBadgeKey ? currentPath : undefined);
+  }, [currentPath, currentBadgeKey, syncBadges]);
+
+  /**
+   * 后台轮询：待办数字是按分钟变的，60 秒一次足够；
+   * 再补"切回这个标签页/窗口重新获得焦点"两个时机 —— 用户从别的系统处理完回来，
+   * 不该再盯着一个已经过期的红点等下一轮。
+   */
+  useEffect(() => {
+    const refresh = () => {
+      if (document.visibilityState === 'visible') void syncBadges();
+    };
+    const timer = window.setInterval(refresh, 60_000);
+    document.addEventListener('visibilitychange', refresh);
+    window.addEventListener('focus', refresh);
+    return () => {
+      window.clearInterval(timer);
+      document.removeEventListener('visibilitychange', refresh);
+      window.removeEventListener('focus', refresh);
+    };
+  }, [syncBadges]);
+
+  /* ------------------------------ 收藏（书签） ------------------------------ */
+
+  const [favPaths, setFavPaths] = useState<string[]>(favorites);
+  const [saving, setSaving] = useState(false);
+  const [hoverPath, setHoverPath] = useState<string | null>(null);
+
+  // path → 菜单条目。用同一份 searchEntries 反查，于是菜单改名、
+  // 权限收回、功能开关关闭这三种情况都不用额外写代码就自动跟随。
+  const favoriteIndex = useMemo(() => buildFavoriteIndex(searchEntries), [searchEntries]);
+  const favItems = useMemo(() => resolveFavorites(favPaths, favoriteIndex), [favPaths, favoriteIndex]);
+  const starred = currentPath ? favPaths.includes(currentPath) : false;
+
+  /**
+   * 收藏 / 取消收藏。
+   * 先改本地再发请求（点了立刻有反馈），失败回滚并用后端给的文案提示 ——
+   * 超上限这类错误的原因只有后端说得准，前端不要自己编。
+   */
+  const toggleFavorite = async (path: string) => {
+    if (saving) return;
+    const has = favPaths.includes(path);
+    if (!has && favItems.length >= MAX_FAVORITES) {
+      message.warning(`最多收藏 ${MAX_FAVORITES} 个，先移除一个再添加`);
+      return;
+    }
+
+    const prev = favPaths;
+    setFavPaths(has ? prev.filter((p) => p !== path) : [...prev, path]);
+    setSaving(true);
+    try {
+      setFavPaths(await callFavorites(has ? 'DELETE' : 'POST', path));
+    } catch (e) {
+      setFavPaths(prev);
+      message.error((e as Error).message);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const [openKeys, setOpenKeys] = useState<string[]>([]);
+  useEffect(() => {
+    // 路由变化时自动展开当前所在的分组
+    setOpenKeys(trail.map((n) => n.path || n.id));
+  }, [trail]);
+
+  const breadcrumbItems = useMemo(() => {
+    const items: { title: ReactNode }[] = [
+      { title: <Link href="/dashboard"><HomeOutlined /></Link> },
+    ];
+    for (const n of trail) {
+      items.push({ title: n.name });
+    }
+    if (trail.length === 0) items.push({ title: '工作台' });
+    return items;
+  }, [trail]);
+
+  const userMenuItems: MenuProps['items'] = [
+    { key: 'profile', icon: <UserOutlined />, label: '个人信息' },
+    { key: 'appearance', icon: <BgColorsOutlined />, label: '外观设置' },
+    { type: 'divider' },
+    { key: 'logout', icon: <LogoutOutlined />, label: '退出登录' },
+  ];
+
+  const onUserMenuClick: MenuProps['onClick'] = ({ key }) => {
+    if (key === 'profile') {
+      modal.info({
+        title: '个人信息',
+        content: (
+          <div style={{ lineHeight: 2 }}>
+            <div>用户名：{user.username}</div>
+            <div>姓名：{user.name}</div>
+            <div>角色：{user.roleCodes?.length ? user.roleCodes.join('、') : '—'}</div>
+            <div>账号类型：{user.isSuper ? '超级管理员' : '普通用户'}</div>
+          </div>
+        ),
+      });
+    } else if (key === 'appearance') {
+      openPanel();
+    } else if (key === 'logout') {
+      modal.confirm({
+        title: '确认退出登录？',
+        okText: '退出',
+        cancelText: '取消',
+        onOk: async () => {
+          // 登出前清掉全局等待任务：否则上一个会话没结束的请求
+          // 会让浮层在新页面上继续报"已等待"，看起来像卡住了
+          clearTasks();
+          await signOut({ redirectTo: '/login' });
+        },
+      });
+    }
+  };
+
+  return (
+    <Layout style={{ minHeight: '100vh' }}>
+      <Layout.Sider
+        // 侧栏深浅由皮肤决定：原版/炫酷是深色，简洁是纸白
+        theme={skin.sider.dark ? 'dark' : 'light'}
+        width={222}
+        collapsible
+        collapsed={collapsed}
+        trigger={null}
+        style={{
+          position: 'sticky',
+          top: 0,
+          height: '100vh',
+          overflow: 'auto',
+          // 材质（斜纹面料 / 纸面 / 舱壁网格）由皮肤给，页面不写死
+          backgroundImage: 'var(--wb-sider-bg)',
+          borderRight: '1px solid var(--wb-sider-border)',
+        }}
+      >
+        {/*
+          品牌行：min-height 而不是固定高度。
+          系统名超过 9 个字时标题会折成 2 行（见 globals.css 的 .wb-brand-title），
+          固定 56px 会把 3 行内容压成一团；这里让它按内容长高，
+          竖向内边距固定 9px，于是 1 行标题时正好 56px、与原来的观感一致。
+        */}
+        <div
+          style={{
+            minHeight: 56,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: collapsed ? 'center' : 'flex-start',
+            gap: 10,
+            padding: collapsed ? 0 : '9px 16px',
+            color: SIDER.textStrong,
+          }}
+        >
+          {/*
+            品牌方块：展开态 26px（只显示全名首字），收起态 30px（显示短名）。
+            收起态放大 4px 的原因：80px 的收起侧栏里它是唯一的品牌锚点，
+            而两个 13px 的中文要 26px，26px 的方块只剩 24px 内容区，装不下。
+            尺寸也吃 fs()：用户把字号调到特大时方块一起放大，字不会被裁。
+          */}
+          <span
+            title={collapsed ? APP_NAME : undefined}
+            aria-label={collapsed ? APP_NAME : undefined}
+            style={{
+              width: fs(collapsed ? 30 : 26),
+              height: fs(collapsed ? 30 : 26),
+              flex: `0 0 ${fs(collapsed ? 30 : 26)}`,
+              borderRadius: 7,
+              display: 'grid',
+              placeItems: 'center',
+              // 品牌小标记：底色=侧栏选中态，描边=点缀色
+              background: SIDER.activeBg,
+              border: '1px solid var(--wb-sider-mark)',
+              color: SIDER.textStrong,
+              fontSize: fs(13),
+              fontWeight: 700,
+              letterSpacing: 0,
+              // 兜底：短名再离谱也不许漏出方块（旧代码 overflow 默认 visible，'YJXT' 实测漏 6.3px）
+              whiteSpace: 'nowrap',
+              overflow: 'hidden',
+            }}
+          >
+            {/* 收起时侧栏只剩这个方块：显示 APP_SHORT（不是全名首字 ——
+                首字常常是「业」「车」这种没有信息的字），能放几个字由 brandMark 按宽度算 */}
+            {brandMark(collapsed ? APP_SHORT || APP_NAME : APP_NAME, collapsed) || APP_NAME.slice(0, 1)}
+          </span>
+          {!collapsed && (
+            <div style={{ display: 'flex', flexDirection: 'column', minWidth: 0, flex: '1 1 auto' }}>
+              {/*
+                系统名的宽度约束交给 .wb-brand-title（最多 2 行 + 省略号）。
+                flex 必须允许收缩：否则中文长名会把标识块挤扁 —— 但收缩的下限是
+                minWidth:0 的那个容器，字号本身不动，视线重心才稳。
+                短名（≤9 字）仍是单行，和以前完全一样。
+              */}
+              <span className="wb-brand-title" title={APP_NAME} style={{ fontSize: fs(15) }}>
+                {APP_NAME}
+              </span>
+              {/* 副标题是 appInfo 里的可配置项，不渲染就等于"改了没反应" */}
+              {APP_SUBTITLE ? (
+                <span className="wb-brand-sub" title={APP_SUBTITLE} style={{ fontSize: fs(10.5), color: SIDER.textMuted }}>
+                  {APP_SUBTITLE}
+                </span>
+              ) : null}
+            </div>
+          )}
+        </div>
+
+        {/* ---------------------------- 我的常用 ---------------------------- */}
+        {/*
+          刻意不塞进下面的 antd Menu：Menu 的 key 用的是 path，
+          同一条路由出现两次会 key 冲突、双高亮，展开/选中状态也会被带乱。
+          独立区块还带来一个好处 —— 视觉上明显"轻"于正式菜单（字小半号、
+          行高更矮），一眼能看出它是快捷方式而不是新的分类。
+        */}
+        <div style={{ borderTop: `1px solid ${SIDER.line}`, paddingTop: collapsed ? 6 : 8 }}>
+          {!collapsed && (
+            <div
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'space-between',
+                padding: '0 18px 4px',
+                fontSize: fs(11),
+                letterSpacing: 0.8,
+                color: SIDER.textMuted,
+              }}
+            >
+              <span>我的常用</span>
+              <span style={{ fontVariantNumeric: 'tabular-nums' }}>
+                {favItems.length}/{MAX_FAVORITES}
+              </span>
+            </div>
+          )}
+
+          {favItems.length === 0
+            ? !collapsed && (
+                <div
+                  style={{
+                    padding: '2px 18px 10px',
+                    fontSize: fs(12),
+                    lineHeight: 1.7,
+                    color: SIDER.textMuted,
+                  }}
+                >
+                  点页面右上角的 ☆ 收藏常用功能
+                </div>
+              )
+            : favItems.map((item) => {
+                const active = item.path === currentPath;
+                const row = (
+                  <div
+                    key={item.path}
+                    role="button"
+                    tabIndex={0}
+                    onClick={() => goto(item.path)}
+                    onKeyDown={(e) => {
+                      if (e.key === 'Enter' || e.key === ' ') goto(item.path);
+                    }}
+                    onMouseEnter={() => setHoverPath(item.path)}
+                    onMouseLeave={() => setHoverPath((p) => (p === item.path ? null : p))}
+                    style={{
+                      display: 'flex',
+                      alignItems: 'center',
+                      gap: 8,
+                      height: 34,
+                      margin: '0 8px 2px',
+                      padding: collapsed ? 0 : '0 10px',
+                      justifyContent: collapsed ? 'center' : 'flex-start',
+                      borderRadius: 8,
+                      cursor: 'pointer',
+                      fontSize: fs(13),
+                      color: active ? SIDER.textStrong : SIDER.text,
+                      background: active ? SIDER.activeBg : hoverPath === item.path ? SIDER.hoverBg : 'transparent',
+                      transition: 'background .15s, color .15s',
+                    }}
+                  >
+                    <span
+                      style={{
+                        fontSize: fs(13),
+                        flex: '0 0 auto',
+                        opacity: 0.9,
+                        position: 'relative',
+                        display: 'inline-flex',
+                        alignItems: 'center',
+                      }}
+                    >
+                      {iconOf(item.icon)}
+                      {/* 折叠态只剩图标，徽标压到图标上；展开态的徽标在文字右侧 */}
+                      {collapsed && (
+                        <CountBadge value={badges[item.path] ?? 0} floating label={item.name} />
+                      )}
+                    </span>
+                    {!collapsed && (
+                      <span
+                        style={{
+                          flex: 1,
+                          overflow: 'hidden',
+                          textOverflow: 'ellipsis',
+                          whiteSpace: 'nowrap',
+                        }}
+                      >
+                        {item.name}
+                      </span>
+                    )}
+                    {/* 收藏区也是模块入口，有待办就得同样亮红点，否则从快捷方式进去看不到提示 */}
+                    {!collapsed && <CountBadge value={badges[item.path] ?? 0} label={item.name} />}
+                    {!collapsed && (
+                      <CloseOutlined
+                        aria-label={`取消收藏 ${item.name}`}
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          void toggleFavorite(item.path);
+                        }}
+                        style={{
+                          fontSize: fs(10),
+                          flex: '0 0 auto',
+                          opacity: hoverPath === item.path ? 0.55 : 0,
+                          transition: 'opacity .15s',
+                        }}
+                      />
+                    )}
+                  </div>
+                );
+                // 折叠态只剩图标，靠 title 补语义，否则不知道点的是哪个
+                return collapsed ? (
+                  <Tooltip key={item.path} title={item.name} placement="right">
+                    {row}
+                  </Tooltip>
+                ) : (
+                  row
+                );
+              })}
+        </div>
+
+        <div style={{ height: 1, margin: '6px 8px 4px', background: SIDER.line }} />
+
+        <Menu
+          theme={skin.sider.dark ? 'dark' : 'light'}
+          mode="inline"
+          items={menuItems}
+          selectedKeys={[selectedKey]}
+          // 折叠状态下不能受控 openKeys，否则 antd 会告警且弹出层错位
+          {...(collapsed ? {} : { openKeys, onOpenChange: setOpenKeys })}
+          onClick={({ key }) => {
+            const k = String(key);
+            if (k.startsWith('/')) goto(k);
+          }}
+        />
+      </Layout.Sider>
+
+      <Layout>
+        <Layout.Header
+          // .wb-header 是皮肤签名元素的挂点：炫酷底下一道冷光，简洁版去掉投影
+          className="wb-header"
+          style={{
+            background: MILITARY.card,
+            padding: '0 16px',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            borderBottom: `1px solid ${MILITARY.border}`,
+            position: 'sticky',
+            top: 0,
+            zIndex: 10,
+          }}
+        >
+          <Space size={12} style={{ whiteSpace: 'nowrap' }}>
+            <Button
+              type="text"
+              aria-label={collapsed ? '展开菜单' : '收起菜单'}
+              icon={collapsed ? <MenuUnfoldOutlined /> : <MenuFoldOutlined />}
+              onClick={() => setCollapsed((v) => !v)}
+            />
+            <Breadcrumb items={breadcrumbItems} />
+            {/*
+              星标放在面包屑右侧而不是每个页面各写一遍：
+              外壳已经用 findTrail 知道"当前在哪一页"，一处实现就覆盖了所有页面。
+              新加的业务页面只要登记了菜单，自动就有收藏入口，不用改页面代码。
+            */}
+            {currentPath && (
+              <Tooltip title={starred ? '已收藏，点击取消' : '收藏到「我的常用」'}>
+                <Button
+                  type="text"
+                  size="small"
+                  aria-label={starred ? '取消收藏当前页' : '收藏当前页'}
+                  icon={
+                    starred ? (
+                      <StarFilled style={{ color: MILITARY.warning, fontSize: fs(16) }} />
+                    ) : (
+                      <StarOutlined style={{ color: MILITARY.textMuted, fontSize: fs(16) }} />
+                    )
+                  }
+                  onClick={() => void toggleFavorite(currentPath)}
+                />
+              </Tooltip>
+            )}
+          </Space>
+
+          <Space size={12}>
+            <GlobalSearch entries={searchEntries} />
+            <InboxBell initialCount={inboxCount} />
+            {/*
+              外观入口（皮肤 / 字号）：
+              放在顶栏而不是塞进某个设置页 —— 它是"随时想换"的偏好，
+              不该让用户先记住藏在哪个二级菜单里。
+              权限上不分角色：换配色不影响任何数据可见性。
+            */}
+            <Tooltip title="外观设置（皮肤 / 字号）">
+              <Button
+                type="text"
+                aria-label="外观设置"
+                data-testid="appearance-entry"
+                icon={<BgColorsOutlined style={{ fontSize: fs(16) }} />}
+                onClick={openPanel}
+              />
+            </Tooltip>
+            {/*
+              帮助入口固定在顶栏，而不是只依赖「帮助文档」菜单：
+              文档属于全站基础设施，不应因为角色没勾选菜单就看不到入口。
+              新标签页打开，阅读文档时不会把当前业务页面顶掉。
+            */}
+            <Tooltip title="帮助文档（新标签页打开）">
+              <Button
+                type="text"
+                aria-label="打开帮助文档"
+                data-testid="help-docs-entry"
+                icon={<QuestionCircleOutlined style={{ fontSize: fs(16) }} />}
+                href="/docs"
+                target="_blank"
+                rel="noreferrer"
+              />
+            </Tooltip>
+            {/*
+              在线 / 今日 / 总访问：放在头像左侧，属于"全站态势"而不是业务数据，
+              所以不做权限过滤；组件内部自带轮询与失败静默。
+            */}
+            <VisitStats />
+            <Dropdown menu={{ items: userMenuItems, onClick: onUserMenuClick }} trigger={['click']}>
+              <Space style={{ cursor: 'pointer' }}>
+                <Avatar icon={<UserOutlined />} size="small" />
+                <span className="header-user-name">{user.name}</span>
+              </Space>
+            </Dropdown>
+          </Space>
+        </Layout.Header>
+
+        <Layout.Content style={{ padding: 16 }}>
+          <div
+            className="wb-content"
+            style={{
+              background: MILITARY.paper,
+              borderRadius: 12,
+              padding: 16,
+              minHeight: '100%',
+              border: `1px solid ${MILITARY.borderSoft}`,
+            }}
+          >
+            {children}
+          </div>
+        </Layout.Content>
+      </Layout>
+    </Layout>
+  );
+}