node-resource-utils 0.0.0-stage → 1.1.8

package/resources/src/components/Providers.tsx

@@ -0,0 +1,99 @@
+'use client';
+
+import { ConfigProvider, App as AntdApp } from 'antd';
+import zhCN from 'antd/locale/zh_CN';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { useEffect, useMemo, useState, type ReactNode } from 'react';
+import dayjs from 'dayjs';
+import 'dayjs/locale/zh-cn';
+import { installRequestTracking } from '@/lib/http';
+import { buildSkinTheme } from '@/lib/skin-theme';
+import RouteProgress from '@/components/feedback/RouteProgress';
+import TaskHint from '@/components/feedback/TaskHint';
+import VisitTracker from '@/components/VisitTracker';
+import { AppearanceProvider, useAppearance } from '@/components/appearance/AppearanceProvider';
+import AppearanceDrawer from '@/components/appearance/AppearanceDrawer';
+
+dayjs.locale('zh-cn');
+
+/**
+ * 全局 Provider。
+ *
+ * - AppearanceProvider: 皮肤 + 字号（整站，含登录页）。少了它，
+ *   页面里的 `var(--wb-*)` 还在，但 antd 组件不会跟着换配色。
+ * - ConfigProvider: 中文语言包 + **按当前皮肤实时编译**的主题 token。
+ *   换皮肤不是换一份写死的配置，而是 `buildSkinTheme()` 现场算一遍，
+ *   所以加一套皮肤只需要在 lib/appearance.ts 里加一条。
+ * - AntdApp: 提供 message / modal / notification 的上下文，
+ *   这样在任意组件里用 App.useApp() 拿到的弹窗是「跟随主题」的，
+ *   比直接 import { message } from 'antd' 更规范（后者不受 ConfigProvider 影响）
+ * - QueryClientProvider: 服务端数据缓存，列表页翻页不重复请求
+ *
+ * ★ 等待反馈的**全局兜底**也挂在这里（所以登录页同样生效）：
+ *   - installRequestTracking(): 给 axios 装拦截器，任何请求超过 3 秒
+ *     都会自动出现在右下角浮层里 —— 页面忘了写 loading 也不会没反应
+ *   - RouteProgress: 跳页面时的顶部细进度条
+ *   - TaskHint: 右下角「正在处理…已等待 N 秒」小卡片
+ *
+ * ★ 外观面板也挂在这里（AppearanceDrawer）：顶栏、用户菜单、任何页面
+ *   只要调 `useAppearance().openPanel()` 就能打开，不用各自渲染一份。
+ */
+export default function Providers({ children }: { children: ReactNode }) {
+  return (
+    <AppearanceProvider>
+      <ThemedApp>{children}</ThemedApp>
+    </AppearanceProvider>
+  );
+}
+
+function ThemedApp({ children }: { children: ReactNode }) {
+  const { settings } = useAppearance();
+
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            staleTime: 30_000,
+            retry: 1,
+            refetchOnWindowFocus: false,
+          },
+        },
+      })
+  );
+
+  /** 皮肤或字号一变，整套 antd token 重算（只是对象计算，不是重载页面） */
+  const theme = useMemo(
+    () => buildSkinTheme(settings.skin, settings.font),
+    [settings.skin, settings.font]
+  );
+
+  // 只在客户端装：模块顶层执行的话 SSR 也会跑一遍，拦截器会重复注册
+  useEffect(() => {
+    installRequestTracking();
+  }, []);
+
+  return (
+    <ConfigProvider
+      locale={zhCN}
+      theme={theme}
+      // 关掉 antd 的「两字中文按钮自动插空格」：默认会把"登录"渲染成"登 录"，
+      // 中文界面里这个空格很突兀，也会让自动化测试按按钮文案定位时对不上。
+      // ⚠️ 这是 ConfigProvider 的 button 配置，不是 theme.components.Button 的 token ——
+      //    写在 components 里是不生效的（踩过）。
+      button={{ autoInsertSpace: false }}
+    >
+      <AntdApp>
+        <QueryClientProvider client={queryClient}>
+          {children}
+          {/* 全站访问埋点：挂在这里，新页面不用再写任何统计代码 */}
+          <VisitTracker />
+          <RouteProgress />
+          <TaskHint />
+          {/* 外观面板：全局唯一实例，任何地方 openPanel() 即可 */}
+          <AppearanceDrawer />
+        </QueryClientProvider>
+      </AntdApp>
+    </ConfigProvider>
+  );
+}

package/resources/src/components/VisitTracker.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { usePathname } from 'next/navigation';
+import {
+  VISIT_DEDUPE_MS,
+  VISIT_HEARTBEAT_MS,
+  VISIT_STATS_EVENT,
+  getOrCreateVisitorId,
+  normalizeVisitPath,
+} from '@/lib/visits';
+
+/**
+ * 全站访问埋点（不渲染任何 DOM）。
+ *
+ * 挂在根 Providers 上，于是登录页、帮助文档、后台各模块自动被统计 ——
+ * 新加页面不需要再写一行埋点代码。
+ *
+ * 两种上报：
+ *   页面浏览（带 path）—— 路由变化时发一次，写入 Visit，计入今日 / 总访问量
+ *   心跳（不带 path）—— 每 60 秒 + 回到前台时发一次，只刷新在线状态
+ *
+ * 为什么用原生 fetch 而不是 trackedFetch：
+ *   埋点是旁路，绝不能触发「正在处理…」的全局等待浮层，也不会因为失败弹错。
+ *   任何异常都吞掉：统计没了可以补，业务被统计拖慢就是本末倒置。
+ */
+
+async function postVisit(visitorId: string, path?: string): Promise<boolean> {
+  try {
+    const res = await fetch('/api/visits', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(path ? { visitorId, path } : { visitorId }),
+      cache: 'no-store',
+    });
+    if (!res.ok) return false;
+    const json = (await res.json()) as { code?: number };
+    return json?.code === 0;
+  } catch {
+    return false;
+  }
+}
+
+export default function VisitTracker() {
+  const pathname = usePathname();
+  const visitorIdRef = useRef<string | null>(null);
+  const lastViewRef = useRef<{ path: string; at: number } | null>(null);
+
+  // 心跳：只要页面还开着、标签页可见，就保持"在线"
+  useEffect(() => {
+    visitorIdRef.current ??= getOrCreateVisitorId();
+
+    const beat = () => {
+      if (document.visibilityState !== 'visible') return;
+      const id = visitorIdRef.current;
+      if (id) void postVisit(id);
+    };
+
+    const timer = window.setInterval(beat, VISIT_HEARTBEAT_MS);
+    document.addEventListener('visibilitychange', beat);
+    window.addEventListener('focus', beat);
+    return () => {
+      window.clearInterval(timer);
+      document.removeEventListener('visibilitychange', beat);
+      window.removeEventListener('focus', beat);
+    };
+  }, []);
+
+  // 页面浏览：路由变化时记一条；同一页面短时间内重复触发只记一次
+  useEffect(() => {
+    const path = normalizeVisitPath(pathname);
+    if (!path) return;
+
+    visitorIdRef.current ??= getOrCreateVisitorId();
+    const id = visitorIdRef.current;
+    if (!id) return;
+
+    const last = lastViewRef.current;
+    if (last && last.path === path && Date.now() - last.at < VISIT_DEDUPE_MS) return;
+    lastViewRef.current = { path, at: Date.now() };
+
+    void postVisit(id, path).then((written) => {
+      // 让顶栏统计立刻更新：自己的这次访问应该马上出现在"今日 / 在线"里
+      if (written) window.dispatchEvent(new Event(VISIT_STATS_EVENT));
+    });
+  }, [pathname]);
+
+  return null;
+}