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 = '';
+    setPayModal({ ids, amountHint });
-    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();
-      },
-    });
   }
 
   function approveWithdraw(id: string) {
-    let paymentRef = '';
+    setWithdrawApproveId(id);
-    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(() => {});
-      },
-    });
   }
 
   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 = '';
+    setApproveId(id);
-    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(() => {});
-      },
-    });
   }
 
   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>
   );
 }

docs/杜康好客-v3-PRD.md

@@ -113,7 +113,7 @@
 **HQ 财务打款信息**（`admin-web` 财务四页，v3.5.6）：
 
 - 门店/合伙人/酒厂/物流账单列表、详情、导出展示收款账户（户名、账号、开户行）
-- 确认打款时可填写打款凭证号（`paymentRef`），已打款后在详情与导出中展示
+- 确认打款时可填写打款凭证号（`paymentRef`），并可上传凭证照片（`paymentProofUrls`，最多 9 张）；已打款后在详情与导出中展示
 - 门店账单统一列表：T+1 终态「已打款」、手动提现终态「已结算」（均为 `PAID`，文案区分业务类型）
 - 门店 T+1「出账日」= 出账当天（核销窗口「昨日 00:00–今日 00:00」中的今天）
 - 核销详情展示核销门店主账户收款信息

docs/杜康好客-v3-现状对照.md

@@ -71,6 +71,7 @@
 
 | 日期 | 说明 |
 |------|------|
+| 2026-08-30 | HQ 门店账单确认打款支持上传凭证照片（`payment_proof_urls`） |
 | 2026-08-26 | v3.5.14：`order_submit`/`pay_success` 埋点改用真实 `clientApp`；线上这两类 `USER_H5` 回填为 `USER_MINI` |
 | 2026-08-26 | v3.5.12：订单大屏循环 BGM；HQ 日志/订单状态流转/用户行为时间线英文码改中文；修复删除门店分类后被 `ensureDefaults` 回种；HQ 侧栏按业务前 11 项重排、系统设置置底 |
 | 2026-08-26 | v3.5.11：城市三种履约起购；企微补提交人/订单规格物流收货/核销用户（昵称+明文手机+HQ备注）；`alert.settlement` 改名「结算任务失败通知」归入系统监控；补提现通过与四账单（城市/合伙人、笔数、累计金额、收款人账号开户行） |

docs/杜康好客-v3编码手册.md

@@ -54,6 +54,8 @@ C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAd
 
 **用户日志端（v3.5.14）**：`order_submit` / `pay_success` 的 `clientApp` 取 JWT（小程序 `USER_MINI`）；微信支付回调沿用该订单已有埋点，缺省小程序。禁止再写死 `USER_H5`。
 
+**HQ 门店账单打款凭证**：确认打款 / 提现通过可填 `paymentRef`，并可上传照片（`paymentProofUrls`，OSS `PAYMENT_PROOF`，最多 9 张）。详情与 T+1 导出展示。
+
 **合伙人关联与订单佣金（v4.0.1）**：规则见 v4-PRD。`user_user.assoc_partner_account_id` 首次扫码锁定；`user_order.partner_account_id_at_pay` 仅关联或代下单显式选择写入（禁止区县解析）。`partner_bill_item` 分酒单 / 核销两段。合伙人备注独立表 `partner_user_note`（勿写 `hq_remark`）。`POST /user/partner-assoc/bind` · `GET /partner/assoc` · `GET /partner/assoc/stats`（关联用户 / 当前关联用户已付购酒单，本日/本月）· `GET /partner/assoc/users?keyword&sort`（合伙人侧返回 `partnerRemark`，不返回 `hqRemark`）· `GET /partner/assoc/users/:userId/orders` · `GET /partner/assoc/orders` · `PUT /partner/assoc/users/:userId/remark` · HQ `GET /admin/users` 支持 `keyword`、`assocPartnerAccountId`（`none` / `any` / 主账号 ID）· `GET /admin/orders` 支持 `assocPartnerAccountId`（筛本单快照，`none`=无快照）· `PUT /admin/users/:id/assoc`（权限 `users_partner_assoc`）改绑/解绑 · 开城合伙人关联用户快链 `/users?assocPartnerAccountId=` · `PUT /admin/partners/:id` 改费率用 `Decimal(toFixed(4))`。
 
 ## 5. 验收用例（必过）

packages/shared-types/src/settlement.ts

@@ -66,6 +66,14 @@ export interface StoreWithdrawSummaryDto {
   bankAccount?: StoreWithdrawBankAccountDto | null;
 }
 
+/** 确认打款 / 提现通过时可附带的凭证照片上限 */
+export const PAYMENT_PROOF_IMAGE_MAX_COUNT = 9;
+
+export interface ConfirmFinancePayDto {
+  paymentRef?: string;
+  paymentProofUrls?: string[];
+}
+
 export interface StoreWithdrawRequestDto {
   id: string;
   withdrawNo: string;
@@ -78,6 +86,7 @@ export interface StoreWithdrawRequestDto {
   reviewedAt?: string | null;
   paidAt?: string | null;
   paymentRef?: string | null;
+  paymentProofUrls?: string[];
 }
 
 export interface StorePayoutDto {
@@ -171,6 +180,8 @@ export interface StoreBillDto {
   payoutAmount: number;
   status: FinancePayStatus;
   paidAt?: string | null;
+  paymentRef?: string | null;
+  paymentProofUrls?: string[];
 }
 
 export interface WineryBillDto {

server/dukang-api/prisma/migrate-store-bill-payment-proof.sql

@@ -0,0 +1,5 @@
+-- 门店账单 / 手动提现：确认打款凭证照片
+ALTER TABLE `store_bill`
+  ADD COLUMN `payment_proof_urls` JSON NULL AFTER `payment_ref`;
+ALTER TABLE `store_withdraw_request`
+  ADD COLUMN `payment_proof_urls` JSON NULL AFTER `payment_ref`;

server/dukang-api/prisma/schema.prisma

@@ -1953,10 +1953,11 @@ model StoreBill {
   redeemAmount   Decimal          @map("redeem_amount") @db.Decimal(10, 2)
   settlementRate Decimal          @map("settlement_rate") @db.Decimal(5, 4)
   payoutAmount   Decimal          @map("payout_amount") @db.Decimal(10, 2)
-  status         FinancePayStatus @default(UNPAID)
+  status           FinancePayStatus @default(UNPAID)
-  paymentRef     String?          @map("payment_ref") @db.VarChar(128)
+  paymentRef       String?          @map("payment_ref") @db.VarChar(128)
-  paidAt         DateTime?        @map("paid_at") @db.DateTime(3)
+  paymentProofUrls Json?            @map("payment_proof_urls")
-  createdAt      DateTime         @default(now()) @map("created_at") @db.DateTime(3)
+  paidAt           DateTime?        @map("paid_at") @db.DateTime(3)
+  createdAt        DateTime         @default(now()) @map("created_at") @db.DateTime(3)
 
   store   Store         @relation(fields: [storeId], references: [id], onDelete: Restrict)
   payouts StorePayout[]
@@ -2002,9 +2003,10 @@ model StoreWithdrawRequest {
   appliedAt       DateTime            @default(now()) @map("applied_at") @db.DateTime(3)
   reviewedAt      DateTime?           @map("reviewed_at") @db.DateTime(3)
   reviewedByHqId  BigInt?             @map("reviewed_by_hq_id") @db.UnsignedBigInt
-  paidAt          DateTime?           @map("paid_at") @db.DateTime(3)
+  paidAt           DateTime?           @map("paid_at") @db.DateTime(3)
-  paymentRef      String?             @map("payment_ref") @db.VarChar(128)
+  paymentRef       String?             @map("payment_ref") @db.VarChar(128)
-  createdAt       DateTime            @default(now()) @map("created_at") @db.DateTime(3)
+  paymentProofUrls Json?               @map("payment_proof_urls")
+  createdAt        DateTime            @default(now()) @map("created_at") @db.DateTime(3)
   updatedAt       DateTime            @updatedAt @map("updated_at") @db.DateTime(3)
 
   store        Store                      @relation(fields: [storeId], references: [id], onDelete: Restrict)

server/dukang-api/src/modules/settlement/settlement.controller.ts

@@ -133,7 +133,7 @@ export class AdminStoreWithdrawController {
   approve(
     @CurrentUser() user: AuthUser,
     @Param('id') id: string,
-    @Body() body: { paymentRef?: string },
+    @Body() body: { paymentRef?: string; paymentProofUrls?: string[] },
   ) {
     return this.settlementService.approveStoreWithdraw(BigInt(id), user.actorId, body);
   }
@@ -287,8 +287,10 @@ export class AdminStoreBillController {
     batch: true,
     includeBody: true,
   })
-  batchConfirm(@Body() body: { ids: string[] }) {
+  batchConfirm(
-    return this.settlementService.batchConfirmStoreBills(body.ids ?? []);
+    @Body() body: { ids: string[]; paymentRef?: string; paymentProofUrls?: string[] },
+  ) {
+    return this.settlementService.batchConfirmStoreBills(body.ids ?? [], body);
   }
 
   @Get(':id')
@@ -302,7 +304,10 @@ export class AdminStoreBillController {
     refType: 'STORE_BILL',
     refIdParam: 'id',
   })
-  confirm(@Param('id') id: string, @Body() body: { paymentRef?: string }) {
+  confirm(
+    @Param('id') id: string,
+    @Body() body: { paymentRef?: string; paymentProofUrls?: string[] },
+  ) {
     return this.settlementService.confirmStoreBill(BigInt(id), body);
   }
 }

server/dukang-api/src/modules/settlement/settlement.service.ts

@@ -4,6 +4,7 @@ import {
   DEFAULT_STORE_WITHDRAW_DAILY_LIMIT,
   DEFAULT_XFX_LOGISTICS_PRICING,
   LOGISTICS_SETTLEMENT_METHOD_LABELS,
+  PAYMENT_PROOF_IMAGE_MAX_COUNT,
   WINERY_SETTLEMENT_LAG_DAYS,
   WINERY_SETTLEMENT_RATE,
 } from '@dukang/shared-types';
@@ -50,6 +51,19 @@ function csvEscape(value: string) {
   return value;
 }
 
+function parsePaymentProofUrls(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((u) => String(u ?? '').trim())
+    .filter((u) => /^https?:\/\//i.test(u))
+    .slice(0, PAYMENT_PROOF_IMAGE_MAX_COUNT);
+}
+
+function paymentProofUrlsInput(urls?: string[]): Prisma.InputJsonValue | typeof Prisma.JsonNull {
+  const parsed = parsePaymentProofUrls(urls);
+  return parsed.length ? (parsed as Prisma.InputJsonValue) : Prisma.JsonNull;
+}
+
 /** 上海时区自然日 00:00（用本地 Date 构造；服务器需设 Asia/Shanghai 或等价） */
 function startOfDay(d: Date) {
   return new Date(d.getFullYear(), d.getMonth(), d.getDate(), 0, 0, 0, 0);
@@ -715,6 +729,7 @@ export class SettlementService implements OnModuleInit {
     if (!row) throw new NotFoundException('提现申请不存在');
     return serializeBigInt({
       ...row,
+      paymentProofUrls: parsePaymentProofUrls(row.paymentProofUrls),
       overdue:
         row.status === 'PENDING_REVIEW' ? isWithdrawOverdue(row.appliedAt) : false,
     });
@@ -723,7 +738,7 @@ export class SettlementService implements OnModuleInit {
   async approveStoreWithdraw(
     id: bigint,
     hqAccountId: bigint,
-    dto?: { paymentRef?: string },
+    dto?: { paymentRef?: string; paymentProofUrls?: string[] },
   ) {
     const row = await this.prisma.storeWithdrawRequest.findUnique({
       where: { id },
@@ -744,6 +759,7 @@ export class SettlementService implements OnModuleInit {
           reviewedByHqId: hqAccountId,
           paidAt,
           paymentRef: dto?.paymentRef?.trim() || null,
+          paymentProofUrls: paymentProofUrlsInput(dto?.paymentProofUrls),
         },
       });
       await tx.storePayout.updateMany({
@@ -764,6 +780,7 @@ export class SettlementService implements OnModuleInit {
       extraJson: {
         amount: Number(row.amount),
         paymentRef: dto?.paymentRef,
+        paymentProofCount: parsePaymentProofUrls(dto?.paymentProofUrls).length,
       },
     });
 
@@ -1425,10 +1442,18 @@ export class SettlementService implements OnModuleInit {
     });
     if (!bill) throw new NotFoundException('门店对账单不存在');
     const storeAccount = await loadStorePrimaryBank(this.prisma, bill.storeId);
-    return serializeBigInt({ ...bill, billDate: shanghaiYmd(bill.billDate), storeAccount });
+    return serializeBigInt({
+      ...bill,
+      billDate: shanghaiYmd(bill.billDate),
+      storeAccount,
+      paymentProofUrls: parsePaymentProofUrls(bill.paymentProofUrls),
+    });
   }
 
-  async confirmStoreBill(id: bigint, dto: { paymentRef?: string } = {}) {
+  async confirmStoreBill(
+    id: bigint,
+    dto: { paymentRef?: string; paymentProofUrls?: string[] } = {},
+  ) {
     const bill = await this.prisma.storeBill.findUnique({ where: { id } });
     if (!bill) throw new NotFoundException('门店对账单不存在');
     if (bill.status !== 'UNPAID') throw new BadRequestException('仅未打款账单可确认打款');
@@ -1441,6 +1466,7 @@ export class SettlementService implements OnModuleInit {
           status: 'PAID',
           paidAt,
           paymentRef: dto.paymentRef?.trim() || null,
+          paymentProofUrls: paymentProofUrlsInput(dto.paymentProofUrls),
         },
       });
       await tx.storePayout.updateMany({
@@ -1449,14 +1475,20 @@ export class SettlementService implements OnModuleInit {
       });
       return b;
     });
-    return serializeBigInt(updated);
+    return serializeBigInt({
+      ...updated,
+      paymentProofUrls: parsePaymentProofUrls(updated.paymentProofUrls),
+    });
   }
 
-  async batchConfirmStoreBills(ids: string[]) {
+  async batchConfirmStoreBills(
+    ids: string[],
+    dto: { paymentRef?: string; paymentProofUrls?: string[] } = {},
+  ) {
     const results: Array<{ id: string; ok: boolean; message?: string }> = [];
     for (const id of ids) {
       try {
-        await this.confirmStoreBill(BigInt(id));
+        await this.confirmStoreBill(BigInt(id), dto);
         results.push({ id, ok: true });
       } catch (e) {
         results.push({ id, ok: false, message: e instanceof Error ? e.message : '失败' });
@@ -1493,6 +1525,7 @@ export class SettlementService implements OnModuleInit {
       '状态',
       '打款时间',
       '打款凭证',
+      '打款凭证照片',
       '收款户名',
       '收款账号',
       '开户行',
@@ -1511,6 +1544,7 @@ export class SettlementService implements OnModuleInit {
         b.status,
         b.paidAt ? b.paidAt.toISOString().slice(0, 19).replace('T', ' ') : '',
         csvEscape(b.paymentRef ?? ''),
+        csvEscape(parsePaymentProofUrls(b.paymentProofUrls).join(' ')),
         csvEscape(bank?.bankAccountName ?? ''),
         csvEscape(bank?.bankAccountNo ?? ''),
         csvEscape(bank?.bankBranch ?? ''),