node-resource-utils 0.0.0-stage → 1.1.8

package/resources/src/app/(admin)/demo/loading/page.tsx

@@ -0,0 +1,513 @@
+'use client';
+
+import { useState } from 'react';
+import { Alert, App, Button, Card, Space, Tag, Typography } from 'antd';
+import {
+  ClockCircleOutlined,
+  CloseCircleOutlined,
+  LoadingOutlined,
+  ThunderboltOutlined,
+} from '@ant-design/icons';
+import AsyncButton from '@/components/feedback/AsyncButton';
+import LoadingOverlay from '@/components/feedback/LoadingOverlay';
+import {
+  SkeletonCards,
+  SkeletonDetail,
+  SkeletonTable,
+  SkeletonText,
+} from '@/components/feedback/Skeleton';
+import { formatElapsed, useAsyncTask } from '@/components/feedback/usePending';
+import { beginTask, endTask } from '@/lib/pending';
+import { fs, MILITARY } from '@/lib/theme';
+
+const { Paragraph, Text, Title } = Typography;
+
+/**
+ * 「等待与反馈」样板间。
+ *
+ * 这个页面不解决业务问题，它解决的是**比赛现场的一个固定问题**：
+ * 出的题不确定，但"点了一下要等几秒"这件事一定会出现。
+ * 所以把各种等待形态集中在这里，新题来了照抄对应的一块就行。
+ *
+ * 五类形态，覆盖从 0.2 秒到 1 分钟：
+ *   1. 按钮级   —— 提交、保存、导出：换成一个 AsyncButton 即可
+ *   2. 区域级   —— 一块卡片整体在等：套一层 LoadingOverlay
+ *   3. 骨架屏   —— 首次加载还不知道等多久：用 Skeleton* 占住版式
+ *   4. 长任务   —— 超过 8 秒的导入/生成：给秒数 + 给取消
+ *   5. 全局兜底 —— 页面忘了写 loading 也有右下角提示（Providers 已装好）
+ */
+
+/** 可被 AbortSignal 打断的 sleep —— 演示"取消"用 */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        reject(new DOMException('aborted', 'AbortError'));
+      },
+      { once: true }
+    );
+  });
+}
+
+function Section({
+  index,
+  title,
+  desc,
+  children,
+}: {
+  index: string;
+  title: string;
+  desc: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <Card
+      variant="borderless"
+      style={{ boxShadow: MILITARY.shadowSm, border: `1px solid ${MILITARY.borderSoft}` }}
+      title={
+        <Space size={10}>
+          <span
+            style={{
+              width: 22,
+              height: 22,
+              borderRadius: 6,
+              background: MILITARY.soft,
+              border: `1px solid ${MILITARY.softStrong}`,
+              color: MILITARY.primary,
+              fontSize: fs(12),
+              display: 'inline-grid',
+              placeItems: 'center',
+            }}
+          >
+            {index}
+          </span>
+          <span>{title}</span>
+        </Space>
+      }
+    >
+      <Paragraph style={{ fontSize: fs(12.5), color: MILITARY.textMuted, marginBottom: 14 }}>
+        {desc}
+      </Paragraph>
+      {children}
+    </Card>
+  );
+}
+
+export default function LoadingDemoPage() {
+  const { message } = App.useApp();
+
+  // 区域遮罩演示
+  const [regionLoading, setRegionLoading] = useState(false);
+  const [regionVersion, setRegionVersion] = useState(1);
+
+  // 骨架屏演示：切换"骨架 / 真实内容"
+  const [showSkeleton, setShowSkeleton] = useState(true);
+
+  /**
+   * 长任务演示：useAsyncTask 提供 pending / elapsed / stageText / cancel。
+   * 自己画等待 UI 时就靠这四个值，不用再手写 setInterval。
+   */
+  const longJob = useAsyncTask(
+    (signal) => sleep(20000, signal),
+    {
+      label: '正在导入 1 万行数据…',
+      /**
+       * silent: true —— 页面里已经有阶段文案 + 已耗时 + 取消按钮，
+       * 再让右下角浮出一张同样内容的卡片就是噪音了。
+       * 兜底层的定位是「没写提示的页面不至于没反应」，不是给写好的页面加压。
+       * 第 5 节会单独演示浮层长什么样。
+       */
+      silent: true,
+      stages: [
+        { after: 0, text: '正在校验文件格式…' },
+        { after: 2500, text: '正在写入数据库（分批 200 行）…' },
+        { after: 8000, text: '数据量较大，仍在写入，可以继续等待或取消…' },
+      ],
+      onSuccess: () => message.success('导入完成'),
+      onCancel: () => message.info('已取消导入'),
+    }
+  );
+
+  const reloadRegion = () => {
+    setRegionLoading(true);
+    setTimeout(() => {
+      setRegionLoading(false);
+      setRegionVersion((v) => v + 1);
+    }, 4000);
+  };
+
+  /**
+   * 全局浮层演示：手工登记一条任务，3 秒后右下角自己浮出来。
+   * 真实场景里这一步由 axios 拦截器/AsyncButton 自动完成，
+   * 这里手写是为了让你看到"浮层长什么样、什么时候出现"。
+   */
+  const simulateGlobal = () => {
+    const id = beginTask('正在生成月度统计报表（8 张表汇总）…', 'task');
+    setTimeout(() => {
+      endTask(id);
+      message.success('报表已生成');
+    }, 6000);
+    message.info('已发起，3 秒后右下角会出现提示');
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      {/* 页头：和全站其他页面同一套节奏（kicker + 标题 + 一行说明） */}
+      <div>
+        <div
+          style={{
+            fontSize: fs(10.5),
+            letterSpacing: 3,
+            color: MILITARY.textMuted,
+            textTransform: 'uppercase',
+            marginBottom: 6,
+          }}
+        >
+          Loading & Feedback
+        </div>
+        <Title level={4} style={{ margin: 0, color: MILITARY.text }}>
+          等待与反馈样板间
+        </Title>
+        <Paragraph style={{ margin: '4px 0 0', fontSize: fs(12.5), color: MILITARY.textSecondary }}>
+          新题里任何&ldquo;点一下要等几秒&rdquo;的地方，从下面五种形态里挑一种套上去即可。
+          全部不引新依赖、只走军绿主题，复制走就能用。
+        </Paragraph>
+      </div>
+
+      <Alert
+        type="info"
+        showIcon
+        title="三个阈值决定手感"
+        description={
+          <span>
+            <b>200ms</b> 以内完成的操作不出现 spinner（避免闪一下）；
+            <b> 3 秒</b>后右下角浮出全局提示；
+            <b> 8 秒</b>后文案升级为「仍在继续，请勿重复提交」。
+            改 <Text code>lib/pending.ts</Text> 的 <Text code>WAIT</Text> 即可全站生效。
+          </span>
+        }
+      />
+
+      {/* ---------- 1. 按钮级 ---------- */}
+      <Section
+        index="1"
+        title="按钮级：提交、保存、导出"
+        desc="把 <Button onClick={async …}> 换成 <AsyncButton task={…}>，自动得到：防重复点击、延迟转圈、失败弹提示、超过 3 秒在按钮上显示秒数。"
+      >
+        <Space wrap size={10}>
+          <AsyncButton
+            type="primary"
+            task={() => sleep(600)}
+            successText="已完成（0.6 秒）"
+          >
+            短任务 0.6s
+          </AsyncButton>
+
+          <AsyncButton task={() => sleep(2500)} successText="已完成（2.5 秒）">
+            标准任务 2.5s
+          </AsyncButton>
+
+          <AsyncButton
+            type="primary"
+            task={(signal) => sleep(9000, signal)}
+            label="正在生成季度报表…"
+            successText="报表已生成"
+          >
+            长任务 9s（看右下角）
+          </AsyncButton>
+
+          <AsyncButton
+            danger
+            task={async () => {
+              await sleep(1200);
+              throw new Error('服务端返回：当前数据已被他人修改，请刷新后重试');
+            }}
+          >
+            失败会怎样
+          </AsyncButton>
+        </Space>
+      </Section>
+
+      {/* ---------- 2. 区域遮罩 ---------- */}
+      <Section
+        index="2"
+        title="区域级：一块卡片整体在等"
+        desc="保留旧内容 + 半透明蒙层，用户知道「还在原地」；200ms 后才出现，快请求不会闪。超过 3 秒开始显示已等待秒数。"
+      >
+        <Space style={{ marginBottom: 12 }}>
+          <Button type="primary" onClick={reloadRegion} loading={regionLoading}>
+            重新加载这块区域（4 秒）
+          </Button>
+          <Tag icon={<ClockCircleOutlined />} color="default">
+            第 {regionVersion} 次加载
+          </Tag>
+        </Space>
+
+        <LoadingOverlay
+          loading={regionLoading}
+          text="正在重新统计这批数据…"
+          minHeight={180}
+          tone="card"
+        >
+          <div
+            style={{
+              border: `1px solid ${MILITARY.borderSoft}`,
+              borderRadius: 10,
+              overflow: 'hidden',
+            }}
+          >
+            {[
+              ['设备编号', '所属单位', '状态', '更新时间'],
+            ].map((row) => (
+              <div
+                key={row[0]}
+                style={{
+                  display: 'grid',
+                  gridTemplateColumns: '1.2fr 1.6fr .8fr 1fr',
+                  gap: 8,
+                  padding: '10px 14px',
+                  background: MILITARY.soft,
+                  fontSize: fs(12.5),
+                  color: MILITARY.textSecondary,
+                  fontWeight: 600,
+                }}
+              >
+                {row.map((c) => (
+                  <span key={c}>{c}</span>
+                ))}
+              </div>
+            ))}
+            {Array.from({ length: 5 }).map((_, i) => (
+              <div
+                key={i}
+                style={{
+                  display: 'grid',
+                  gridTemplateColumns: '1.2fr 1.6fr .8fr 1fr',
+                  gap: 8,
+                  padding: '10px 14px',
+                  fontSize: fs(12.5),
+                  color: MILITARY.text,
+                  borderTop: `1px solid ${MILITARY.borderSoft}`,
+                }}
+              >
+                <span>EQ-2026-{String(i + 1).padStart(3, '0')}</span>
+                <span>保障分队 · 第 {i + 1} 组</span>
+                <span style={{ color: i % 2 ? MILITARY.warning : MILITARY.success }}>
+                  {i % 2 ? '检修中' : '正常'}
+                </span>
+                <span style={{ color: MILITARY.textMuted }}>
+                  10-{20 + i} {9 + i}:0{i}
+                </span>
+              </div>
+            ))}
+          </div>
+        </LoadingOverlay>
+      </Section>
+
+      {/* ---------- 3. 骨架屏 ---------- */}
+      <Section
+        index="3"
+        title="骨架屏：首次加载还不知道等多久"
+        desc="比转圈多给了一层信息：等来的是表格还是表单、大概几行。内容是空的但版式先立住，数据填进来时不会整页跳一下。"
+      >
+        <Space style={{ marginBottom: 14 }}>
+          <Button size="small" onClick={() => setShowSkeleton((v) => !v)}>
+            {showSkeleton ? '换成真实内容' : '换回骨架'}
+          </Button>
+          <span style={{ fontSize: fs(12), color: MILITARY.textMuted }}>
+            三种骨架对应三种版式：列表 / 统计卡 / 表单详情
+          </span>
+        </Space>
+
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 14 }}>
+          <div>
+            <div style={{ fontSize: fs(12), color: MILITARY.textMuted, marginBottom: 6 }}>
+              列表（SkeletonTable）
+            </div>
+            {showSkeleton ? (
+              <SkeletonTable rows={4} cols={4} />
+            ) : (
+              <div
+                style={{
+                  border: `1px solid ${MILITARY.borderSoft}`,
+                  borderRadius: 8,
+                  padding: 14,
+                  fontSize: fs(12.5),
+                  color: MILITARY.textSecondary,
+                }}
+              >
+                真实表格到了 —— 高度和上面的骨架基本一致，所以没有跳动。
+              </div>
+            )}
+          </div>
+
+          <div>
+            <div style={{ fontSize: fs(12), color: MILITARY.textMuted, marginBottom: 6 }}>
+              统计卡（SkeletonCards）
+            </div>
+            {showSkeleton ? (
+              <SkeletonCards count={4} height={76} />
+            ) : (
+              <div style={{ display: 'grid', gridTemplateColumns: 'repeat(4, 1fr)', gap: 16 }}>
+                {[
+                  ['在编人数', '128'],
+                  ['本月新增', '12'],
+                  ['待处理', '7'],
+                  ['完成率', '86%'],
+                ].map(([k, v]) => (
+                  <div
+                    key={k}
+                    style={{
+                      border: `1px solid ${MILITARY.borderSoft}`,
+                      borderRadius: 10,
+                      padding: 14,
+                    }}
+                  >
+                    <div style={{ fontSize: fs(11.5), color: MILITARY.textMuted }}>{k}</div>
+                    <div style={{ fontSize: fs(20), fontWeight: 600, color: MILITARY.primary }}>{v}</div>
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+
+          <div>
+            <div style={{ fontSize: fs(12), color: MILITARY.textMuted, marginBottom: 6 }}>
+              表单详情（SkeletonDetail / SkeletonText）
+            </div>
+            {showSkeleton ? (
+              <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 18 }}>
+                <SkeletonDetail rows={3} />
+                <SkeletonText lines={5} />
+              </div>
+            ) : (
+              <div style={{ fontSize: fs(12.5), color: MILITARY.textSecondary }}>
+                真实字段渲染出来了，位置与上面的占位一一对应。
+              </div>
+            )}
+          </div>
+        </div>
+      </Section>
+
+      {/* ---------- 4. 长任务 ---------- */}
+      <Section
+        index="4"
+        title="长任务：超过 8 秒要有秒数，也要能取消"
+        desc="导入、批量生成、大模型长回答都属于这一类。关键不是「转得快」，而是「我知道它进展到哪一步、我可以停」。"
+      >
+        <Space wrap style={{ marginBottom: 12 }}>
+          <Button
+            type="primary"
+            icon={<ThunderboltOutlined />}
+            onClick={() => void longJob.run()}
+            disabled={longJob.pending}
+          >
+            开始导入（20 秒）
+          </Button>
+          <Button danger disabled={!longJob.pending} onClick={longJob.cancel}>
+            取消
+          </Button>
+          {longJob.pending ? (
+            <Tag icon={<LoadingOutlined spin />} color="processing">
+              已等待 {formatElapsed(longJob.elapsed)}
+            </Tag>
+          ) : (
+            <Tag color="default">空闲</Tag>
+          )}
+        </Space>
+
+        {longJob.pending ? (
+          <div
+            style={{
+              border: `1px solid ${MILITARY.borderSoft}`,
+              borderRadius: 10,
+              padding: '12px 14px',
+              background: MILITARY.paper,
+            }}
+          >
+            <div style={{ fontSize: fs(13), color: MILITARY.text, marginBottom: 8 }}>
+              {longJob.stageText}
+            </div>
+            <div
+              style={{
+                height: 4,
+                borderRadius: 999,
+                background: MILITARY.soft,
+                overflow: 'hidden',
+              }}
+            >
+              <div
+                className="wb-indeterminate-bar"
+                style={{
+                  width: '38%',
+                  height: '100%',
+                  background: `linear-gradient(90deg, ${MILITARY.primaryHover}, ${MILITARY.accent})`,
+                }}
+              />
+            </div>
+          </div>
+        ) : (
+          <div style={{ fontSize: fs(12.5), color: MILITARY.textMuted }}>
+            点&ldquo;开始导入&rdquo;看阶段文案怎么随耗时升级（0s → 2.5s → 8s）。
+          </div>
+        )}
+      </Section>
+
+      {/* ---------- 5. 全局兜底 ---------- */}
+      <Section
+        index="5"
+        title="全局兜底：页面忘了写 loading 也不会没反应"
+        desc="Providers 里已经装好 axios 拦截器 + 右下角浮层。任何请求超过 3 秒，右下角自动浮出「正在处理…已等待 N 秒」，与新题里写没写 loading 无关。"
+      >
+        <Space wrap style={{ marginBottom: 12 }}>
+          <Button onClick={simulateGlobal} icon={<ClockCircleOutlined />}>
+            模拟一个 6 秒的耗时任务
+          </Button>
+          <Button
+            onClick={() => {
+              // 真接口演示：/api/stats 很快，但链路和专业版一致
+              void fetch('/api/health');
+              message.info('这条不会触发浮层：接口太快，3 秒内就结束了（这正是想要的效果）');
+            }}
+          >
+            快请求不该打扰
+          </Button>
+        </Space>
+
+        <div
+          style={{
+            border: `1px dashed ${MILITARY.border}`,
+            borderRadius: 10,
+            padding: 12,
+            fontSize: fs(12.5),
+            color: MILITARY.textSecondary,
+            background: MILITARY.paper,
+            lineHeight: 1.9,
+          }}
+        >
+          <div>
+            <CloseCircleOutlined style={{ color: MILITARY.success, marginRight: 6 }} />
+            3 秒内结束 → 什么都不显示（不打扰）
+          </div>
+          <div>
+            <ClockCircleOutlined style={{ color: MILITARY.primary, marginRight: 6 }} />
+            超过 3 秒 → 右下角淡入，带已等待秒数和不确定进度条
+          </div>
+          <div>
+            <LoadingOutlined style={{ color: MILITARY.warning, marginRight: 6 }} />
+            超过 8 秒 → 文案变黄并提示「请勿重复提交」，同时顶部路由条也换色
+          </div>
+        </div>
+      </Section>
+
+      <div style={{ fontSize: fs(11.5), color: MILITARY.textMuted, padding: '0 2px 8px' }}>
+        代码位置：<Text code>src/components/feedback/</Text> ｜ 阈值：
+        <Text code>src/lib/pending.ts</Text> ｜ 请求文案映射：
+        <Text code>src/lib/http.ts</Text>
+      </div>
+    </div>
+  );
+}

package/resources/src/app/(admin)/error.tsx

@@ -0,0 +1,96 @@
+'use client';
+
+import { useEffect } from 'react';
+import { Button } from 'antd';
+import { useRouter } from 'next/navigation';
+import { fs, MILITARY } from '@/lib/theme';
+
+/**
+ * 路由级错误兜底。
+ *
+ * 「耗时的另一面是会不会失败」。只有 loading 没有 error，等于告诉用户
+ * "等下去总会有结果"——真挂了的时候反而更慌。所以这一层必须补：
+ * 明确说清"没打开"、给出可能的两个原因、并且**保留重试按钮**。
+ *
+ * 注意：错误信息做脱敏 —— 生产环境只给摘要（digest），
+ * 开发环境才显示原始 message，避免把堆栈/路径泄漏给评委看到。
+ */
+export default function AdminError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  const router = useRouter();
+  const dev = process.env.NODE_ENV !== 'production';
+
+  useEffect(() => {
+    console.error('[页面异常]', error);
+  }, [error]);
+
+  return (
+    <div
+      style={{
+        minHeight: 420,
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 14,
+        padding: 40,
+        textAlign: 'center',
+      }}
+    >
+      <div
+        aria-hidden
+        style={{
+          width: 46,
+          height: 46,
+          borderRadius: 12,
+          background: MILITARY.accentSoft,
+          border: `1px solid ${MILITARY.border}`,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          fontSize: fs(22),
+          color: MILITARY.warning,
+        }}
+      >
+        !
+      </div>
+
+      <div style={{ fontSize: fs(17), fontWeight: 600, color: MILITARY.text }}>
+        这个页面没能打开
+      </div>
+
+      <div style={{ fontSize: fs(13), color: MILITARY.textSecondary, lineHeight: 1.7, maxWidth: 460 }}>
+        可能是后端服务正在重启，或者这一步处理超时了。可以先重试一次；
+        如果一直这样，回到工作台确认其他页面是否正常。
+      </div>
+
+      <div
+        style={{
+          fontSize: fs(11.5),
+          color: MILITARY.textMuted,
+          fontFamily: 'ui-monospace, Consolas, monospace',
+          maxWidth: 520,
+          wordBreak: 'break-all',
+          background: MILITARY.paper,
+          border: `1px solid ${MILITARY.borderSoft}`,
+          borderRadius: 8,
+          padding: '6px 10px',
+        }}
+      >
+        {dev ? error.message || '未知错误' : `错误编号 ${error.digest ?? 'unknown'}`}
+      </div>
+
+      <div style={{ display: 'flex', gap: 10, marginTop: 4 }}>
+        <Button type="primary" onClick={reset}>
+          重试
+        </Button>
+        <Button onClick={() => router.push('/dashboard')}>回到工作台</Button>
+      </div>
+    </div>
+  );
+}