优化：明确提现审核状态与超时订单处理 (#71)

## 改动说明

- 将支付配置阻断问题改为明确、可操作的提示，技术详情默认折叠。
- 为支付配置检测和现金账本校验增加加载状态、精确时间与完成反馈。
- 账本正常时使用紧凑状态展示，异常时才显示醒目提示。
- 将“批量对账”改为“处理超时订单”，在确认弹窗中说明查单、更新状态、撤销和退款行为。
- 移除自动查单关闭提示，避免把非阻断运维状态展示成业务问题。
- 审计记录中的操作名称同步调整为“处理超时订单”。

## 验证

- `npx tsc --noEmit`
- Next.js 本地页面编译通过。
- 实际验证重新检测、重新校验和超时订单确认弹窗，浏览器控制台无错误。

## 后端配套

- WonderableAI/shaguabijia-app-server#170

---------

Co-authored-by: guke <guke@wonderable.ai>
Co-authored-by: linkeyu <798648091@qq.com>
Reviewed-on: #71
Co-authored-by: linkeyu <linkeyu@wonderable.ai>
Co-committed-by: linkeyu <linkeyu@wonderable.ai>

deploy/nginx/admin.shaguabijia.com.conf

@@ -32,6 +32,20 @@ server {
         proxy_read_timeout 60s;
     }
 
+    # 新手引导视频上传:视频比图片大一个量级,单独放宽到 100MB(对齐后端
+    # settings.GUIDE_VIDEO_MAX_BYTES)。不放宽全站上限,避免其它接口被大 body 打。
+    # 上传大文件耗时长,读超时同步放宽到 300s。
+    location = /admin/api/guide-video/video {
+        client_max_body_size 100m;
+        proxy_pass http://127.0.0.1:8771;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 300s;
+        proxy_send_timeout 300s;
+        proxy_request_buffering off;
+    }
+
     # 用户上传媒体(上报截图 / 反馈截图 / 反馈二维码)由 App 后端(:8770)的 /media 托管。
     # admin 页面要展示这些图,经此同域反代过去(免跨域 + 免 https 页面引 http 图被拦)。
     # 前提:App 后端与本 admin 同机;若分机,把 127.0.0.1:8770 换成 App 后端可达地址。

src/app/(main)/config/GuideVideoConfig.tsx

@@ -0,0 +1,222 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { Button, Card, Space, Spin, Switch, Tag, Typography, Upload, message } from 'antd';
+import { DeleteOutlined, UploadOutlined } from '@ant-design/icons';
+import { api, errMsg } from '@/lib/api';
+import { canDo } from '@/lib/auth';
+import { mediaUrl } from '@/lib/media';
+import type { GuideVideoConfig as GuideCfg } from '@/lib/types';
+
+const { Text } = Typography;
+
+/** 后端 media.save_guide_video 只认 MP4 魔数;这里先在浏览器挡一道,省得白传 100MB。 */
+const MAX_BYTES = 100 * 1024 * 1024;
+
+/**
+ * 领券等候浮层的「新手引导视频」配置。
+ *
+ * 用户点首页「一键自动领取」→ 出等候浮层,浮层下方那块位置**前 3 次**放这支引导视频
+ * (而不是广告),每次固定发 120 金币;播完若浮层还开着,自动接着放广告(原逻辑)。
+ * 「系统配置 → 领券引导视频」tab 的一个区块。
+ *
+ * 后台只管两件事:**开关** 和 **换片**。次数(3)/ 金币(120)走服务端默认值,产品已拍板不再
+ * 开放配置,所以这里不渲染输入框、PATCH 也不带这两个字段(后端仍保留字段与默认值)。
+ */
+export default function GuideVideoConfig() {
+  const [cfg, setCfg] = useState<GuideCfg | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [uploading, setUploading] = useState(false);
+
+  // 本地编辑态,保存时一次性 PATCH
+  const [enabled, setEnabled] = useState(true);
+
+  const canEdit = canDo(['operator']);
+
+  const sync = (c: GuideCfg) => {
+    setCfg(c);
+    setEnabled(c.enabled);
+  };
+
+  const load = async () => {
+    setLoading(true);
+    try {
+      const { data } = await api.get<GuideCfg>('/admin/api/guide-video');
+      sync(data);
+    } finally {
+      setLoading(false);
+    }
+  };
+  useEffect(() => {
+    load();
+  }, []);
+
+  const save = async () => {
+    setSaving(true);
+    try {
+      const { data } = await api.patch<GuideCfg>('/admin/api/guide-video', { enabled });
+      sync(data);
+      message.success('已保存，用户下一次进入领券浮层即生效');
+    } catch (e) {
+      message.error(errMsg(e));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  // antd Upload:beforeUpload 里自行 POST(multipart),返回 false 阻止其默认上传。
+  const beforeUpload = (file: File) => {
+    // 有些系统给 .mp4 的 type 是空串,不能只看 type,再兜一层扩展名。
+    const looksMp4 = file.type === 'video/mp4' || /\.mp4$/i.test(file.name);
+    if (!looksMp4) {
+      message.error('仅支持 MP4 视频（H.264 编码）');
+      return Upload.LIST_IGNORE;
+    }
+    if (file.size > MAX_BYTES) {
+      message.error('视频不能超过 100MB');
+      return Upload.LIST_IGNORE;
+    }
+    void uploadVideo(file);
+    return false;
+  };
+
+  const uploadVideo = async (file: File) => {
+    const form = new FormData();
+    form.append('file', file);
+    setUploading(true);
+    try {
+      const { data } = await api.post<GuideCfg>('/admin/api/guide-video/video', form);
+      sync(data);
+      message.success('引导视频已更新，用户下一次进入领券浮层即生效');
+    } catch (e) {
+      message.error(errMsg(e));
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  const removeVideo = async () => {
+    setUploading(true);
+    try {
+      const { data } = await api.delete<GuideCfg>('/admin/api/guide-video/video');
+      sync(data);
+      message.success('已移除引导视频，领券浮层恢复为只放广告');
+    } catch (e) {
+      message.error(errMsg(e));
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  return (
+    <Card
+      size="small"
+      title="领券引导视频（App 领券等候浮层，前 3 次替代广告）"
+      style={{ marginBottom: 16 }}
+      extra={
+        cfg?.updated_at ? (
+          <Text type="secondary" style={{ fontSize: 12 }}>
+            更新于 {new Date(cfg.updated_at).toLocaleString('zh-CN')}
+          </Text>
+        ) : null
+      }
+    >
+      <p style={{ color: '#999', marginTop: 0 }}>
+        用户点「一键自动领取」后出现的等候浮层，下方那块广告位<b>前 3 次</b>改放这支引导视频。
+        视频<b>不可快进</b>；播完或中途关闭都算看完，各发一次 <b>120 金币</b>；播完若浮层还开着，会自动接着放广告。
+        次数<b>按账号</b>计（换设备不重置），<b>视频一开播就算用掉一次</b>。
+        次数与金币走固定值、后台不开放调整；这里只管<b>开关</b>和<b>换片</b>，每次改动进审计日志。
+      </p>
+      {loading || !cfg ? (
+        <Spin style={{ display: 'block', margin: '24px 0' }} />
+      ) : (
+        <Space align="start" size={32} wrap>
+          {/* 左:视频预览 */}
+          <div>
+            <Text type="secondary" style={{ fontSize: 12 }}>
+              当前引导视频
+            </Text>
+            <div style={{ marginTop: 8, width: 240 }}>
+              {cfg.video_url ? (
+                // eslint-disable-next-line jsx-a11y/media-has-caption
+                <video
+                  src={mediaUrl(cfg.video_url)}
+                  controls
+                  style={{
+                    width: 240,
+                    maxHeight: 420,
+                    borderRadius: 12,
+                    background: '#000',
+                    border: '1px solid #f0f0f0',
+                  }}
+                />
+              ) : (
+                <div
+                  style={{
+                    width: 240,
+                    height: 320,
+                    borderRadius: 12,
+                    border: '1px dashed #d9d9d9',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    color: '#bbb',
+                    fontSize: 13,
+                    textAlign: 'center',
+                    padding: 16,
+                  }}
+                >
+                  未上传视频
+                  <br />
+                  （领券浮层照旧只放广告）
+                </div>
+              )}
+            </div>
+            {!enabled && cfg.video_url && (
+              <div style={{ color: '#fa8c16', fontSize: 12, marginTop: 6 }}>
+                当前为「关闭」：浮层不放引导视频，直接放广告
+              </div>
+            )}
+          </div>
+
+          {/* 右:编辑控件 */}
+          <Space direction="vertical" size="middle" style={{ minWidth: 360 }}>
+            <Space>
+              <span>启用引导视频：</span>
+              <Switch checked={enabled} disabled={!canEdit} onChange={setEnabled} />
+              {!enabled && <Tag color="orange">已关闭</Tag>}
+            </Space>
+
+            <Space wrap>
+              <Upload accept="video/mp4,.mp4" showUploadList={false} beforeUpload={beforeUpload} disabled={!canEdit}>
+                <Button icon={<UploadOutlined />} loading={uploading} disabled={!canEdit}>
+                  {cfg.video_url ? '更换视频' : '上传视频'}
+                </Button>
+              </Upload>
+              {cfg.video_url && (
+                <Button
+                  icon={<DeleteOutlined />}
+                  danger
+                  loading={uploading}
+                  disabled={!canEdit}
+                  onClick={removeVideo}
+                >
+                  移除视频
+                </Button>
+              )}
+              <Text type="secondary" style={{ fontSize: 12 }}>
+                MP4（H.264），≤100MB
+              </Text>
+            </Space>
+
+            <Button type="primary" loading={saving} disabled={!canEdit} onClick={save}>
+              保存开关
+            </Button>
+            {!canEdit && <Text type="secondary">仅 operator / super_admin 可修改</Text>}
+          </Space>
+        </Space>
+      )}
+    </Card>
+  );
+}

src/app/(main)/config/page.tsx

@@ -6,6 +6,7 @@ import { api, errMsg } from '@/lib/api';
 import HomeMarqueeSeeds from './HomeMarqueeSeeds';
 import HomeStatsConfig from './HomeStatsConfig';
 import FeedbackQrConfig from './FeedbackQrConfig';
+import GuideVideoConfig from './GuideVideoConfig';
 
 interface ConfigItem {
   key: string;
@@ -164,6 +165,7 @@ export default function ConfigPage() {
           },
           { key: 'welfare', label: '福利页', children: welfareConfig },
           { key: 'feedback-qr', label: '反馈二维码', children: <FeedbackQrConfig /> },
+          { key: 'guide-video', label: '领券引导视频', children: <GuideVideoConfig /> },
         ]}
       />
     </div>

src/app/(main)/withdraws/page.tsx

@@ -142,7 +142,7 @@ function actionLabel(action: string) {
     'withdraw.approve': '审核通过',
     'withdraw.reject': '审核拒绝',
     'withdraw.refresh': '查单刷新',
-    'withdraw.reconcile': '批量对账',
+    'withdraw.reconcile': '处理超时订单',
   };
   return labels[action] || action;
 }
@@ -182,8 +182,11 @@ export default function WithdrawsPage() {
   const [activeStatus, setActiveStatus] = useState('reviewing');
   const [summary, setSummary] = useState<WithdrawSummary | null>(null);
   const [health, setHealth] = useState<WxpayHealthCheck | null>(null);
+  const [healthLoading, setHealthLoading] = useState(false);
+  const [healthCheckedAt, setHealthCheckedAt] = useState<number | null>(null);
   const [ledger, setLedger] = useState<WithdrawLedgerCheck | null>(null);
   const [ledgerLoading, setLedgerLoading] = useState(false);
+  const [ledgerCheckedAt, setLedgerCheckedAt] = useState<number | null>(null);
   const [drawerOpen, setDrawerOpen] = useState(false);
   const [detail, setDetail] = useState<WithdrawDetail | null>(null);
   const [detailLoading, setDetailLoading] = useState(false);
@@ -255,21 +258,36 @@ export default function WithdrawsPage() {
     }
   }, []);
 
-  const loadHealth = useCallback(async () => {
+  const loadHealth = useCallback(async (showFeedback = false) => {
+    setHealthLoading(true);
     try {
       const { data } = await api.get<WxpayHealthCheck>('/admin/api/withdraws/health-check');
       setHealth(data);
+      setHealthCheckedAt(Date.now());
+      if (showFeedback) {
+        message.success(data.ok ? '检测完成，微信提现配置正常' : '检测完成，仍有配置项需要处理');
+      }
     } catch (e) {
       message.error(errMsg(e));
+    } finally {
+      setHealthLoading(false);
     }
   }, []);
 
   // 账本校验是全表对账、相对重,故只在进页时拉一次 + 提供手动按钮,不随每次写操作重算。
-  const loadLedger = useCallback(async () => {
+  const loadLedger = useCallback(async (showFeedback = false) => {
     setLedgerLoading(true);
     try {
       const { data } = await api.get<WithdrawLedgerCheck>('/admin/api/withdraws/ledger-check');
       setLedger(data);
+      setLedgerCheckedAt(Date.now());
+      if (showFeedback) {
+        if (data.ok) {
+          message.success('校验完成，现金账本正常');
+        } else {
+          message.warning('校验完成，发现现金账本异常');
+        }
+      }
     } catch (e) {
       message.error(errMsg(e));
     } finally {
@@ -465,15 +483,16 @@ export default function WithdrawsPage() {
 
   const reconcile = () => {
     modal.confirm({
-      title: '批量对账?',
+      title: '处理超时打款订单？',
-      content: '扫描超过 15 分钟仍处于打款中的提现单，逐单向微信查实并归一化。',
+      content:
-      okText: '开始对账',
+        '将检查超过 15 分钟仍处于“打款中”的订单：微信已成功则更新为“已到账”；失败则退款；仍待用户确认的老单将撤销并退款；仍在处理中则保持不变。',
+      okText: '开始处理',
       onOk: async () => {
         try {
           const { data } = await api.post<{ checked: number; resolved: number }>(
             '/admin/api/withdraws/reconcile',
           );
-          message.success(`对账完成: 检查 ${data.checked} 单，解决 ${data.resolved} 单`);
+          message.success(`处理完成：检查 ${data.checked} 单，更新 ${data.resolved} 单`);
           await refreshAfterChange();
         } catch (e) {
           message.error(errMsg(e));
@@ -652,6 +671,10 @@ export default function WithdrawsPage() {
           : '',
       ].filter(Boolean)
     : [];
+  const payoutReady = Boolean(
+    health?.wxpay_configured && health.private_key_loadable && health.public_key_loadable,
+  );
+  const hasBlockingPayoutIssue = Boolean(health && !payoutReady);
 
   return (
     <div>
@@ -662,41 +685,62 @@ export default function WithdrawsPage() {
         </div>
         {canManage && (
           <Button danger icon={<ReloadOutlined />} onClick={reconcile}>
-            批量对账
+            处理超时订单
           </Button>
         )}
       </Space>
 
-      {(health || ledger) && (
+      {(hasBlockingPayoutIssue || (ledger && !ledger.ok)) && (
         <Space direction="vertical" style={{ width: '100%', marginBottom: 16 }}>
-          {health && (
+          {health && hasBlockingPayoutIssue && (
             <Alert
               showIcon
-              type={health.ok ? 'success' : 'warning'}
+              type="warning"
-              message={health.ok ? '微信提现配置正常' : '微信提现配置需检查'}
+              message="当前环境无法执行微信打款"
               description={
-                health.ok
+                <Space direction="vertical" size={6}>
-                  ? `自动对账已${health.auto_reconcile_enabled ? '开启' : '关闭'}，每 ${health.auto_reconcile_interval_sec}s 扫描 ${health.auto_reconcile_older_than_minutes} 分钟前的打款中订单`
+                  <Text>微信支付配置不完整，点击“通过并打款”将失败。请联系部署管理员处理。</Text>
-                  : health.issues.join('；')
+                  {healthCheckedAt && (
-              }
+                    <Text type="secondary">
-            />
+                      最近检测：{dayjs(healthCheckedAt).format('HH:mm:ss')}
-          )}
+                    </Text>
-          {ledger && (
+                  )}
-            <Alert
+                  <details>
-              showIcon
+                    <summary style={{ color: '#1677ff', cursor: 'pointer' }}>查看技术详情</summary>
-              type={ledger.ok ? 'success' : 'error'}
+                    <ul style={{ margin: '8px 0 0', paddingInlineStart: 20 }}>
-              message={ledger.ok ? '现金账本校验正常' : '现金账本存在异常'}
+                      {health.issues.map((issue) => (
-              description={
+                        <li key={issue} style={{ marginBottom: 4, overflowWrap: 'anywhere' }}>
-                ledger.ok
+                          {issue}
-                  ? `现金 余额 ${yuan(ledger.cash_balance_total_cents)} / 流水 ${yuan(ledger.cash_transaction_total_cents)}；邀请金 余额 ${yuan(ledger.invite_cash_balance_total_cents)} / 流水 ${yuan(ledger.invite_cash_transaction_total_cents)}`
+                        </li>
-                  : ledgerIssues.join('；')
+                      ))}
+                    </ul>
+                  </details>
+                </Space>
               }
+              action={
+                <Button
+                  size="small"
+                  icon={<ReloadOutlined />}
+                  loading={healthLoading}
+                  onClick={() => void loadHealth(true)}
+                >
+                  重新检测
+                </Button>
+              }
+            />
+          )}
+          {ledger && !ledger.ok && (
+            <Alert
+              showIcon
+              type="error"
+              message="现金账本存在异常"
+              description={ledgerIssues.join('；')}
               action={
                 <Button
                   size="small"
                   icon={<ReloadOutlined />}
                   loading={ledgerLoading}
-                  onClick={() => void loadLedger()}
+                  onClick={() => void loadLedger(true)}
                 >
                   重新校验
                 </Button>
@@ -706,6 +750,36 @@ export default function WithdrawsPage() {
         </Space>
       )}
 
+      {(health || ledger) && (
+        <Space
+          size={12}
+          wrap
+          style={{ width: '100%', justifyContent: 'flex-end', marginBottom: 12 }}
+        >
+          {health && payoutReady && <Tag color="success">微信打款可用</Tag>}
+          {ledger?.ok && (
+            <Space size={6}>
+              <CheckCircleOutlined style={{ color: '#52c41a' }} />
+              <Text strong>账本正常</Text>
+              {ledgerCheckedAt && (
+                <Text type="secondary">
+                  · {dayjs(ledgerCheckedAt).format('HH:mm:ss')} 校验
+                </Text>
+              )}
+              <Button
+                type="link"
+                size="small"
+                icon={<ReloadOutlined />}
+                loading={ledgerLoading}
+                onClick={() => void loadLedger(true)}
+              >
+                重新校验
+              </Button>
+            </Space>
+          )}
+        </Space>
+      )}
+
       <Row gutter={12} style={{ marginBottom: 16 }}>
         <Col xs={24} sm={12}>
           <Card size="small">

src/lib/types.ts

@@ -317,6 +317,18 @@ export interface FeedbackQrConfig {
   updated_at: string | null;
 }
 
+/** 领券等候浮层的「新手引导视频」配置(前 3 次用它替代广告,每次固定 120 金币)。
+ *  后台只开放 enabled + 换片;下面几个字段接口仍返回,但页面不展示、也不回传。 */
+export interface GuideVideoConfig {
+  enabled: boolean;
+  video_url: string | null; // /media/guide_video/xxx.mp4;null = 未配片(浮层照旧只放广告)
+  max_plays: number; // 每个账号前 N 次浮层放引导视频(服务端默认 3,后台不开放调整)
+  reward_coin: number; // 每次固定金币(服务端默认 120,播完 / 中途关闭都发)
+  updated_at: string | null;
+  total_plays: number; // 只读统计:全站已播次数(后台不再展示)
+  granted_plays: number; // 只读统计:其中已发币次数(后台不再展示)
+}
+
 export interface AuditLog {
   id: number;
   admin_id: number;