feat(settlement): 门店账单确认打款支持上传凭证照片

财务确认打款与提现通过可附带 OSS 凭证图，详情与导出展示。

Co-authored-by: Cursor <cursoragent@cursor.com>

apps/admin-web/src/components/FinancePayProof.tsx

@@ -0,0 +1,97 @@
+import { useEffect, useState } from 'react';
+import { Image, Input, Modal, Space, Typography } from 'antd';
+import { PAYMENT_PROOF_IMAGE_MAX_COUNT } from '@dukang/shared-types';
+import MultiImageUpload from './MultiImageUpload';
+
+export function parsePaymentProofUrls(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.map((u) => String(u ?? '').trim()).filter(Boolean);
+}
+
+export function PaymentProofGallery({ urls }: { urls?: unknown }) {
+  const list = parsePaymentProofUrls(urls);
+  if (!list.length) return <>—</>;
+  return (
+    <Image.PreviewGroup>
+      <Space wrap size={8}>
+        {list.map((url, index) => (
+          <Image
+            key={`${url}-${index}`}
+            src={url}
+            width={72}
+            height={72}
+            style={{ objectFit: 'cover', borderRadius: 6, border: '1px solid #f0f0f0' }}
+          />
+        ))}
+      </Space>
+    </Image.PreviewGroup>
+  );
+}
+
+type FinancePayProofModalProps = {
+  open: boolean;
+  title: string;
+  hint: string;
+  okText: string;
+  confirmLoading?: boolean;
+  onCancel: () => void;
+  onOk: (payload: { paymentRef?: string; paymentProofUrls?: string[] }) => Promise<void>;
+};
+
+export function FinancePayProofModal({
+  open,
+  title,
+  hint,
+  okText,
+  confirmLoading,
+  onCancel,
+  onOk,
+}: FinancePayProofModalProps) {
+  const [paymentRef, setPaymentRef] = useState('');
+  const [proofUrls, setProofUrls] = useState<string[]>([]);
+
+  useEffect(() => {
+    if (open) {
+      setPaymentRef('');
+      setProofUrls([]);
+    }
+  }, [open]);
+
+  return (
+    <Modal
+      title={title}
+      open={open}
+      okText={okText}
+      cancelText="取消"
+      confirmLoading={confirmLoading}
+      destroyOnClose
+      width={480}
+      onCancel={onCancel}
+      onOk={async () => {
+        await onOk({
+          paymentRef: paymentRef.trim() || undefined,
+          paymentProofUrls: proofUrls.length ? proofUrls : undefined,
+        });
+      }}
+    >
+      <Typography.Paragraph style={{ marginBottom: 12 }}>{hint}</Typography.Paragraph>
+      <Input
+        placeholder="打款凭证号（可选）"
+        value={paymentRef}
+        onChange={(e) => setPaymentRef(e.target.value)}
+        style={{ marginBottom: 12 }}
+      />
+      <Typography.Text type="secondary">打款凭证照片（可选，银行转账回单等）</Typography.Text>
+      <div style={{ marginTop: 8 }}>
+        <MultiImageUpload
+          bizType="PAYMENT_PROOF"
+          value={proofUrls}
+          onChange={setProofUrls}
+          maxCount={PAYMENT_PROOF_IMAGE_MAX_COUNT}
+          buttonText="上传凭证照片"
+          tip={`最多 ${PAYMENT_PROOF_IMAGE_MAX_COUNT} 张，支持一次选择多张`}
+        />
+      </div>
+    </Modal>
+  );
+}

apps/admin-web/src/pages/StoreBillsPage.tsx

@@ -18,6 +18,7 @@ import {
   Typography,
   message,
 } from 'antd';
+import { FinancePayProofModal, PaymentProofGallery } from '../components/FinancePayProof';
 import type { ColumnsType } from 'antd/es/table';
 import type { Dayjs } from 'dayjs';
 import {
@@ -113,6 +114,13 @@ export default function StoreBillsPage() {
     pendingCount: number;
     overdueCount: number;
   } | null>(null);
+  const [payModal, setPayModal] = useState<{
+    ids: string[];
+    amountHint?: number;
+  } | null>(null);
+  const [paySubmitting, setPaySubmitting] = useState(false);
+  const [withdrawApproveId, setWithdrawApproveId] = useState<string | null>(null);
+  const [withdrawSubmitting, setWithdrawSubmitting] = useState(false);
 
   useEffect(() => {
     form.setFieldsValue({
@@ -134,77 +142,11 @@ export default function StoreBillsPage() {
   }, []);
 
   function confirmPay(ids: string[], amountHint?: number) {
-    let paymentRef = '';
-    Modal.confirm({
-      title: '确认打款？',
-      content: (
-        <div>
-          <div>
-            将确认 {ids.length} 笔 T+1 门店对账单
-            {amountHint != null ? `，合计约 ¥${amountHint.toFixed(2)}` : ''}。此操作不可撤销。
-          </div>
-          <Input
-            placeholder="打款凭证号（可选）"
-            style={{ marginTop: 8 }}
-            onChange={(e) => {
-              paymentRef = e.target.value;
-            }}
-          />
-        </div>
-      ),
-      okText: '确认打款',
-      cancelText: '取消',
-      onOk: async () => {
-        const body = JSON.stringify({ paymentRef: paymentRef.trim() || undefined });
-        if (ids.length === 1) {
-          await request(`/admin/store-bills/${ids[0]}/confirm`, { method: 'POST', body });
-        } else {
-          setBatchLoading(true);
-          try {
-            await request('/admin/store-bills/batch-confirm', {
-              method: 'POST',
-              body: JSON.stringify({ ids }),
-            });
-          } finally {
-            setBatchLoading(false);
-          }
-        }
-        message.success('已确认打款');
-        setSelectedKeys([]);
-        reload();
-      },
-    });
+    setPayModal({ ids, amountHint });
   }
 
   function approveWithdraw(id: string) {
-    let paymentRef = '';
-    Modal.confirm({
-      title: '审核通过并标记已结算？',
-      content: (
-        <Input
-          placeholder="打款凭证号（可选）"
-          onChange={(e) => {
-            paymentRef = e.target.value;
-          }}
-        />
-      ),
-      okText: '通过并结算',
-      cancelText: '取消',
-      onOk: async () => {
-        await request(`/admin/store-withdrawals/${id}/approve`, {
-          method: 'POST',
-          body: JSON.stringify({ paymentRef: paymentRef.trim() || undefined }),
-        });
-        message.success('已通过并标记已结算');
-        setDrawerOpen(false);
-        reload();
-        void request<{ pendingCount: number; overdueCount: number }>(
-          '/admin/store-withdrawals/overdue-summary',
-        )
-          .then(setOverdueSummary)
-          .catch(() => {});
-      },
-    });
+    setWithdrawApproveId(id);
   }
 
   function rejectWithdraw(id: string) {
@@ -565,6 +507,9 @@ export default function StoreBillsPage() {
               <Descriptions.Item label="打款凭证">
                 {detail.paymentRef ? String(detail.paymentRef) : '—'}
               </Descriptions.Item>
+              <Descriptions.Item label="凭证照片">
+                <PaymentProofGallery urls={detail.paymentProofUrls} />
+              </Descriptions.Item>
             </Descriptions>
             {(detail.storeAccount as {
               bankAccountName?: string;
@@ -649,6 +594,9 @@ export default function StoreBillsPage() {
               <Descriptions.Item label="打款凭证">
                 {detail.paymentRef ? String(detail.paymentRef) : '—'}
               </Descriptions.Item>
+              <Descriptions.Item label="凭证照片">
+                <PaymentProofGallery urls={detail.paymentProofUrls} />
+              </Descriptions.Item>
             </Descriptions>
             {storeAccount ? (
               <>
@@ -719,6 +667,71 @@ export default function StoreBillsPage() {
           </>
         )}
       </Drawer>
+
+      <FinancePayProofModal
+        open={!!payModal}
+        title="确认打款？"
+        hint={`将确认 ${payModal?.ids.length ?? 0} 笔 T+1 门店对账单${
+          payModal?.amountHint != null ? `，合计约 ¥${payModal.amountHint.toFixed(2)}` : ''
+        }。此操作不可撤销。`}
+        okText="确认打款"
+        confirmLoading={paySubmitting}
+        onCancel={() => setPayModal(null)}
+        onOk={async (payload) => {
+          if (!payModal) return;
+          const { ids } = payModal;
+          setPaySubmitting(true);
+          if (ids.length > 1) setBatchLoading(true);
+          try {
+            const body = JSON.stringify({
+              ...payload,
+              ...(ids.length > 1 ? { ids } : {}),
+            });
+            if (ids.length === 1) {
+              await request(`/admin/store-bills/${ids[0]}/confirm`, { method: 'POST', body });
+            } else {
+              await request('/admin/store-bills/batch-confirm', { method: 'POST', body });
+            }
+            message.success('已确认打款');
+            setPayModal(null);
+            setSelectedKeys([]);
+            reload();
+          } finally {
+            setPaySubmitting(false);
+            setBatchLoading(false);
+          }
+        }}
+      />
+
+      <FinancePayProofModal
+        open={!!withdrawApproveId}
+        title="审核通过并标记已结算？"
+        hint="通过后将标记该提现为已结算，此操作不可撤销。"
+        okText="通过并结算"
+        confirmLoading={withdrawSubmitting}
+        onCancel={() => setWithdrawApproveId(null)}
+        onOk={async (payload) => {
+          if (!withdrawApproveId) return;
+          setWithdrawSubmitting(true);
+          try {
+            await request(`/admin/store-withdrawals/${withdrawApproveId}/approve`, {
+              method: 'POST',
+              body: JSON.stringify(payload),
+            });
+            message.success('已通过并标记已结算');
+            setWithdrawApproveId(null);
+            setDrawerOpen(false);
+            reload();
+            void request<{ pendingCount: number; overdueCount: number }>(
+              '/admin/store-withdrawals/overdue-summary',
+            )
+              .then(setOverdueSummary)
+              .catch(() => {});
+          } finally {
+            setWithdrawSubmitting(false);
+          }
+        }}
+      />
     </div>
   );
 }

apps/admin-web/src/pages/StoreWithdrawalsPage.tsx

@@ -23,6 +23,7 @@ import { useAdminList } from '../lib/useAdminList';
 import { useAdminListColumns } from '../lib/useAdminListColumns';
 import { AdminListHeader } from '../components/AdminListHeader';
 import { AdminPrimaryLink } from '../components/AdminPrimaryLink';
+import { FinancePayProofModal, PaymentProofGallery } from '../components/FinancePayProof';
 
 
 type Row = {
@@ -70,6 +71,8 @@ export default function StoreWithdrawalsPage() {
     pendingCount: number;
     overdueCount: number;
   } | null>(null);
+  const [approveId, setApproveId] = useState<string | null>(null);
+  const [approveSubmitting, setApproveSubmitting] = useState(false);
 
   useEffect(() => {
     void request<Paginated<StoreOption>>(`/admin/stores?pageSize=${ADMIN_OPTIONS_PAGE_SIZE}`)
@@ -89,34 +92,7 @@ export default function StoreWithdrawalsPage() {
   }
 
   function approve(id: string) {
-    let paymentRef = '';
-    Modal.confirm({
-      title: '审核通过并标记已结算？',
-      content: (
-        <Input
-          placeholder="打款凭证号（可选）"
-          onChange={(e) => {
-            paymentRef = e.target.value;
-          }}
-        />
-      ),
-      okText: '通过并结算',
-      cancelText: '取消',
-      onOk: async () => {
-        await request(`/admin/store-withdrawals/${id}/approve`, {
-          method: 'POST',
-          body: JSON.stringify({ paymentRef: paymentRef.trim() || undefined }),
-        });
-        message.success('已通过并标记已结算');
-        setDrawerOpen(false);
-        reload();
-        void request<{ pendingCount: number; overdueCount: number }>(
-          '/admin/store-withdrawals/overdue-summary',
-        )
-          .then(setOverdueSummary)
-          .catch(() => {});
-      },
-    });
+    setApproveId(id);
   }
 
   function reject(id: string) {
@@ -356,6 +332,9 @@ export default function StoreWithdrawalsPage() {
               {detail.paymentRef ? (
                 <Descriptions.Item label="打款凭证">{String(detail.paymentRef)}</Descriptions.Item>
               ) : null}
+              <Descriptions.Item label="凭证照片">
+                <PaymentProofGallery urls={detail.paymentProofUrls} />
+              </Descriptions.Item>
               <Descriptions.Item label="收款户名">
                 {storeAccount?.bankAccountName || '—'}
               </Descriptions.Item>
@@ -394,6 +373,36 @@ export default function StoreWithdrawalsPage() {
           </>
         ) : null}
       </Drawer>
+
+      <FinancePayProofModal
+        open={!!approveId}
+        title="审核通过并标记已结算？"
+        hint="通过后将标记该提现为已结算，此操作不可撤销。"
+        okText="通过并结算"
+        confirmLoading={approveSubmitting}
+        onCancel={() => setApproveId(null)}
+        onOk={async (payload) => {
+          if (!approveId) return;
+          setApproveSubmitting(true);
+          try {
+            await request(`/admin/store-withdrawals/${approveId}/approve`, {
+              method: 'POST',
+              body: JSON.stringify(payload),
+            });
+            message.success('已通过并标记已结算');
+            setApproveId(null);
+            setDrawerOpen(false);
+            reload();
+            void request<{ pendingCount: number; overdueCount: number }>(
+              '/admin/store-withdrawals/overdue-summary',
+            )
+              .then(setOverdueSummary)
+              .catch(() => {});
+          } finally {
+            setApproveSubmitting(false);
+          }
+        }}
+      />
     </div>
   );
 }