v4.0.11HQ后端优化（快链、账单日等）

2026-09-02 15:45:12 +08:00
parent 1000b489a0
commit 6880b5daf4
31 changed files with 1014 additions and 402 deletions
@@ -21,6 +21,7 @@ import {
  previousShanghaiWeek,
  resolveSettlementRate,
  shanghaiBillPeriodYmds,
+  shanghaiCalendarDaysBetween,
  shanghaiMonthLastInstant,
  shanghaiMonthRange,
  shanghaiPeriodYmds,
@@ -40,6 +41,7 @@ import {
 import { PrismaService } from '../../common/prisma/prisma.module';
 import { serializeBigInt } from '../../common/decorators/current-user.decorator';
 import { AlertService } from '../../common/alert/alert.service';
+import { buildCsvFromColumns, parseExportColumnKeys, type ExportColumnDef } from '../../common/export/column-export.util';
 import { WecomMessagePushService } from '../../integrations/wecom/wecom-message-push.service';
 import { AnalyticsService } from '../analytics/analytics.service';
 import { PartnerCityService } from '../city-scope/partner-city.service';
@@ -88,6 +90,34 @@ function withShanghaiPeriod<T extends { periodStart: Date; periodEnd: Date }>(ro
  return { ...row, ...shanghaiBillPeriodYmds(row.periodStart, row.periodEnd) };
 }

+/** 门店 T+1：账期 = 出账日前一日 */
+function mapStoreBillDates(billDate: Date) {
+  const billDateYmd = shanghaiYmd(billDate);
+  const periodDay = shanghaiYmd(addShanghaiDays(parseShanghaiYmd(billDateYmd), -1));
+  return { billDate: billDateYmd, periodStart: periodDay, periodEnd: periodDay };
+}
+
+/**
+ * 合伙人出账日：周账 = 账期周一 + 7 天（下周一）；
+ * 历史月账 = 账期所在月次月 1 日。
+ */
+function partnerBillIssueYmd(periodStart: Date, periodEnd: Date): string {
+  const days = shanghaiCalendarDaysBetween(periodStart, periodEnd);
+  if (days >= 0 && days <= 8) {
+    return shanghaiYmd(addShanghaiDays(startOfShanghaiDay(periodStart), 7));
+  }
+  const [y, m] = shanghaiYmd(periodStart).split('-').map(Number);
+  return shanghaiYmd(shanghaiMonthRange(y, m).endExclusive);
+}
+
+function withPartnerBillDates<T extends { periodStart: Date; periodEnd: Date }>(row: T) {
+  return {
+    ...row,
+    ...shanghaiBillPeriodYmds(row.periodStart, row.periodEnd),
+    billDate: partnerBillIssueYmd(row.periodStart, row.periodEnd),
+  };
+}
+
 function resolvePartnerWeekPeriod(weekStartYmd: string): {
  periodStart: Date;
  periodEnd: Date;
@@ -1429,14 +1459,20 @@ export class SettlementService implements OnModuleInit {
    const payoutAmount = rows.reduce((s, r) => s + r.amount, 0);

    return serializeBigInt({
-      items: slice.map((r) => ({
-        ...r,
-        date: r.kind === 'T1_BILL' ? shanghaiYmd(r.date) : r.date,
-        bankAccount:
-          r.kind === 'T1_BILL'
-            ? bankMap.get(String(r.storeId)) ?? null
-            : null,
-      })),
+      items: slice.map((r) => {
+        const storeDates =
+          r.kind === 'T1_BILL' ? mapStoreBillDates(r.date) : null;
+        return {
+          ...r,
+          date: r.kind === 'T1_BILL' ? storeDates!.billDate : r.date,
+          periodStart: storeDates?.periodStart ?? null,
+          periodEnd: storeDates?.periodEnd ?? null,
+          bankAccount:
+            r.kind === 'T1_BILL'
+              ? bankMap.get(String(r.storeId)) ?? null
+              : null,
+        };
+      }),
      total,
      page,
      pageSize,
@@ -1487,7 +1523,7 @@ export class SettlementService implements OnModuleInit {
    };

    return serializeBigInt({
-      items: items.map((b) => ({ ...b, billDate: shanghaiYmd(b.billDate) })),
+      items: items.map((b) => ({ ...b, ...mapStoreBillDates(b.billDate) })),
      total,
      page,
      pageSize,
@@ -1510,7 +1546,7 @@ export class SettlementService implements OnModuleInit {
    const storeAccount = await loadStorePrimaryBank(this.prisma, bill.storeId);
    return serializeBigInt({
      ...bill,
-      billDate: shanghaiYmd(bill.billDate),
+      ...mapStoreBillDates(bill.billDate),
      storeAccount,
      paymentProofUrls: parsePaymentProofUrls(bill.paymentProofUrls),
    });
@@ -1568,6 +1604,7 @@ export class SettlementService implements OnModuleInit {
    storeId?: string;
    dateFrom?: string;
    dateTo?: string;
+    columns?: string;
  }) {
    const where = this.buildStoreBillWhere(query);
    const bills = await this.prisma.storeBill.findMany({
@@ -1579,44 +1616,70 @@ export class SettlementService implements OnModuleInit {
      this.prisma,
      bills.map((b) => b.storeId),
    );
-    const header = [
-      '账单号',
-      '出账日',
-      '门店',
-      '城市',
-      '核销笔数',
-      '核销金额',
-      '结算比例',
-      '应付金额',
-      '状态',
-      '打款时间',
-      '打款凭证',
-      '打款凭证照片',
-      '收款户名',
-      '收款账号',
-      '开户行',
-    ].join(',');
-    const rows = bills.map((b) => {
-      const bank = bankMap.get(String(b.storeId));
-      return [
-        csvEscape(b.billNo),
-        shanghaiYmd(b.billDate),
-        csvEscape(b.store.name),
-        csvEscape(b.store.cityName ?? ''),
-        b.redeemCount,
-        Number(b.redeemAmount),
-        Number(b.settlementRate),
-        Number(b.payoutAmount),
-        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 ?? ''),
-      ].join(',');
-    });
-    return { csv: `\uFEFF${[header, ...rows].join('\n')}`, count: bills.length };
+    const columnKeys = parseExportColumnKeys(query.columns);
+
+    type Row = (typeof bills)[number] & { bank?: ReturnType<typeof bankMap.get> extends infer T ? T : never };
+    const rows = bills.map((b) => ({ ...b, bank: bankMap.get(String(b.storeId)) }));
+
+    const defs: ExportColumnDef<Row>[] = [
+      { key: '账单号', header: '账单号', value: (r) => r.billNo },
+      { key: '出账日', header: '出账日', value: (r) => shanghaiYmd(r.billDate) },
+      {
+        key: '账期',
+        header: '账期',
+        value: (r) => {
+          const d = mapStoreBillDates(r.billDate);
+          return `${d.periodStart} ~ ${d.periodEnd}`;
+        },
+      },
+      { key: '门店', header: '门店', value: (r) => r.store.name },
+      { key: '登录手机', header: '登录手机', value: (r) => r.store.phone ?? '' },
+      { key: '城市', header: '城市', value: (r) => r.store.cityName ?? '' },
+      { key: '收款户名', header: '收款户名', value: (r) => r.bank?.bankAccountName ?? '' },
+      { key: '收款账号', header: '收款账号', value: (r) => r.bank?.bankAccountNo ?? '' },
+      { key: '笔数', header: '笔数', value: (r) => r.redeemCount },
+      { key: '应付金额', header: '应付金额', value: (r) => Number(r.payoutAmount) },
+      { key: '核销金额', header: '核销金额', value: (r) => Number(r.redeemAmount) },
+      { key: '结算比例', header: '结算比例', value: (r) => Number(r.settlementRate) },
+      { key: '状态', header: '状态', value: (r) => r.status },
+      {
+        key: '打款时间',
+        header: '打款时间',
+        value: (r) => (r.paidAt ? r.paidAt.toISOString().slice(0, 19).replace('T', ' ') : ''),
+      },
+      { key: '打款凭证', header: '打款凭证', value: (r) => r.paymentRef ?? '' },
+      {
+        key: '打款凭证照片',
+        header: '打款凭证照片',
+        value: (r) => parsePaymentProofUrls(r.paymentProofUrls).join(' '),
+      },
+      { key: '开户行', header: '开户行', value: (r) => r.bank?.bankBranch ?? '' },
+    ];
+
+    // 兼容旧英文 key
+    const aliases: Record<string, string> = {
+      billNo: '账单号',
+      date: '出账日',
+      billDate: '出账日',
+      period: '账期',
+      'store.name': '门店',
+      'store.phone': '登录手机',
+      'store.cityName': '城市',
+      bankAccountName: '收款户名',
+      bankAccountNo: '收款账号',
+      redeemCount: '笔数',
+      amount: '应付金额',
+      redeemAmount: '核销金额',
+      settlementRate: '结算比例',
+      status: '状态',
+      paidAt: '打款时间',
+      paymentRef: '打款凭证',
+      paymentProofUrls: '打款凭证照片',
+      bankBranch: '开户行',
+    };
+    const normalized = columnKeys?.map((k) => aliases[k] ?? k);
+
+    return buildCsvFromColumns(defs, rows, normalized);
  }

  private buildStoreBillWhere(query: {
@@ -1665,7 +1728,7 @@ export class SettlementService implements OnModuleInit {
      eventName: 'partner_bill_view',
      extraJson: { count: bills.length },
    });
-    return serializeBigInt(bills.map(withShanghaiPeriod));
+    return serializeBigInt(bills.map(withPartnerBillDates));
  }

  getPartnerSettlementCycle(anchor = new Date()) {
@@ -1737,7 +1800,7 @@ export class SettlementService implements OnModuleInit {
    });
    const { items, ...header } = bill;
    return serializeBigInt({
-      ...withShanghaiPeriod(header),
+      ...withPartnerBillDates(header),
      partnerId: header.partnerAccountId.toString(),
      ...splitPartnerBillItems(items),
    });
@@ -1785,7 +1848,7 @@ export class SettlementService implements OnModuleInit {
    ]);

    const items = rawItems.map((b) => ({
-      ...withShanghaiPeriod(b),
+      ...withPartnerBillDates(b),
      partner: b.partnerAccount,
    }));

@@ -1904,7 +1967,7 @@ export class SettlementService implements OnModuleInit {
    if (!bill) throw new NotFoundException('账单不存在');
    const { items, ...header } = bill;
    return serializeBigInt({
-      ...withShanghaiPeriod(header),
+      ...withPartnerBillDates(header),
      partnerId: header.partnerAccountId.toString(),
      ...splitPartnerBillItems(items),
    });
@@ -2229,6 +2292,7 @@ export class SettlementService implements OnModuleInit {
    year?: number;
    month?: number;
    weekStartYmd?: string;
+    columns?: string;
  }) {
    const where = this.buildPartnerBillWhere(query);
    const bills = await this.prisma.partnerBill.findMany({
@@ -2237,76 +2301,82 @@ export class SettlementService implements OnModuleInit {
        partnerAccount: {
          select: {
            companyName: true,
+            name: true,
            phone: true,
            bankAccountName: true,
            bankAccountNo: true,
            bankBranch: true,
          },
        },
-        items: { orderBy: { occurredAt: 'asc' } },
      },
      orderBy: { periodStart: 'desc' },
    });
+    const columnKeys = parseExportColumnKeys(query.columns);

-    const header = [
-      '账单号',
-      '合伙人',
-      '登录手机',
-      '账期起',
-      '账期止',
-      '酒单佣金',
-      '核销佣金',
-      '合计应付',
-      '状态',
-      '发送时间',
-      '确认时间',
-      '打款时间',
-      '打款凭证',
-      '收款户名',
-      '收款账号',
-      '开户行',
-      '驳回理由',
-    ].join(',');
-    const rows = bills.map((b) =>
-      [
-        csvEscape(b.billNo),
-        csvEscape(b.partnerAccount.companyName ?? ''),
-        csvEscape(b.partnerAccount.phone ?? ''),
-        shanghaiBillPeriodYmds(b.periodStart, b.periodEnd).periodStart,
-        shanghaiBillPeriodYmds(b.periodStart, b.periodEnd).periodEnd,
-        Number(b.orderCommission),
-        Number(b.redeemCommission),
-        Number(b.totalAmount),
-        b.status,
-        b.sentAt ? shanghaiYmd(b.sentAt) : '',
-        b.confirmedAt ? shanghaiYmd(b.confirmedAt) : '',
-        b.paidAt ? shanghaiYmd(b.paidAt) : '',
-        csvEscape(b.paymentRef ?? ''),
-        csvEscape(b.partnerAccount.bankAccountName ?? ''),
-        csvEscape(b.partnerAccount.bankAccountNo ?? ''),
-        csvEscape(b.partnerAccount.bankBranch ?? ''),
-        csvEscape(b.rejectReason ?? ''),
-      ].join(','),
-    );
+    type Row = (typeof bills)[number];
+    const defs: ExportColumnDef<Row>[] = [
+      { key: '账单号', header: '账单号', value: (r) => r.billNo },
+      {
+        key: '合伙人',
+        header: '合伙人',
+        value: (r) => {
+          const c = (r.partnerAccount.companyName || '').trim();
+          const n = (r.partnerAccount.name || '').trim();
+          if (c && n) return `${c}-${n}`;
+          return c || n || r.partnerAccount.phone || '';
+        },
+      },
+      {
+        key: '出账日',
+        header: '出账日',
+        value: (r) => partnerBillIssueYmd(r.periodStart, r.periodEnd),
+      },
+      {
+        key: '账期',
+        header: '账期',
+        value: (r) => {
+          const p = shanghaiBillPeriodYmds(r.periodStart, r.periodEnd);
+          return `${p.periodStart} ~ ${p.periodEnd}`;
+        },
+      },
+      { key: '酒单佣金', header: '酒单佣金', value: (r) => Number(r.orderCommission) },
+      { key: '核销佣金', header: '核销佣金', value: (r) => Number(r.redeemCommission) },
+      { key: '合计应付', header: '合计应付', value: (r) => Number(r.totalAmount) },
+      { key: '收款户名', header: '收款户名', value: (r) => r.partnerAccount.bankAccountName ?? '' },
+      { key: '收款账号', header: '收款账号', value: (r) => r.partnerAccount.bankAccountNo ?? '' },
+      { key: '状态', header: '状态', value: (r) => r.status },
+      { key: '登录手机', header: '登录手机', value: (r) => r.partnerAccount.phone ?? '' },
+      { key: '开户行', header: '开户行', value: (r) => r.partnerAccount.bankBranch ?? '' },
+      {
+        key: '发送时间',
+        header: '发送时间',
+        value: (r) => (r.sentAt ? shanghaiYmd(r.sentAt) : ''),
+      },
+      {
+        key: '确认时间',
+        header: '确认时间',
+        value: (r) => (r.confirmedAt ? shanghaiYmd(r.confirmedAt) : ''),
+      },
+      {
+        key: '打款时间',
+        header: '打款时间',
+        value: (r) => (r.paidAt ? shanghaiYmd(r.paidAt) : ''),
+      },
+      { key: '打款凭证', header: '打款凭证', value: (r) => r.paymentRef ?? '' },
+      { key: '驳回理由', header: '驳回理由', value: (r) => r.rejectReason ?? '' },
+    ];

-    const itemHeader = ['账单号', '类型', '单号', '标题', '备注', '基数', '费率', '佣金', '发生时间'].join(',');
-    const itemRows = bills.flatMap((b) =>
-      b.items.map((it) =>
-        [
-          csvEscape(b.billNo),
-          it.kind === 'ORDER' ? '酒订单' : '核销',
-          csvEscape(it.refNo),
-          csvEscape(it.title ?? ''),
-          csvEscape(it.extra ?? ''),
-          Number(it.baseAmount),
-          Number(it.rate),
-          Number(it.commission),
-          it.occurredAt.toISOString().slice(0, 19).replace('T', ' '),
-        ].join(','),
-      ),
-    );
-    const csv = ['账单汇总', header, ...rows, '', '酒订单/核销明细', itemHeader, ...itemRows].join('\n');
-    return { csv: `\uFEFF${csv}`, count: bills.length };
+    const aliases: Record<string, string> = {
+      billNo: '账单号',
+      billDate: '出账日',
+      period: '账期',
+      orderCommission: '酒单佣金',
+      redeemCommission: '核销佣金',
+      totalAmount: '合计应付',
+      status: '状态',
+    };
+    const normalized = columnKeys?.map((k) => aliases[k] ?? k);
+    return buildCsvFromColumns(defs, bills, normalized);
  }

  // ─── Winery bills ────────────────────────────────────
@@ -2673,7 +2743,7 @@ export class SettlementService implements OnModuleInit {
    };

    return serializeBigInt({
-      items: items.map((b) => ({ ...b, billDate: shanghaiYmd(b.billDate) })),
+      items: items.map((b) => this.mapWineryBillForAdmin(b)),
      total,
      page,
      pageSize,
@@ -2681,6 +2751,33 @@ export class SettlementService implements OnModuleInit {
    });
  }

+  private mapWineryBillForAdmin(b: {
+    id: bigint;
+    billNo: string;
+    billDate: Date;
+    orderCount: number;
+    orderAmount: Prisma.Decimal | number;
+    wineryRate: Prisma.Decimal | number;
+    wineryAmount: Prisma.Decimal | number;
+    status: string;
+    paidAt?: Date | null;
+    paymentRef?: string | null;
+  }) {
+    const billDateYmd = shanghaiYmd(b.billDate);
+    const { start, end } = shanghaiWineryPeriodWindow(
+      parseShanghaiYmd(billDateYmd),
+      WINERY_SETTLEMENT_PERIOD_DAYS,
+    );
+    const periodStart = shanghaiYmd(start);
+    const periodEnd = shanghaiYmd(addShanghaiDays(end, -1));
+    return {
+      ...b,
+      billDate: billDateYmd,
+      periodStart,
+      periodEnd,
+    };
+  }
+
  async getAdminWineryBill(id: bigint) {
    const bill = await this.prisma.wineryBill.findUnique({
      where: { id },
@@ -2688,7 +2785,7 @@ export class SettlementService implements OnModuleInit {
    });
    if (!bill) throw new NotFoundException('酒厂对账单不存在');
    const wineryBank = await loadWineryBankConfig(this.prisma);
-    return serializeBigInt({ ...bill, billDate: shanghaiYmd(bill.billDate), wineryBank });
+    return serializeBigInt({ ...this.mapWineryBillForAdmin(bill), items: bill.items, wineryBank });
  }

  async confirmWineryBill(id: bigint, dto: { paymentRef?: string } = {}) {
@@ -2728,87 +2825,87 @@ export class SettlementService implements OnModuleInit {
    dateTo?: string;
    year?: number;
    month?: number;
+    columns?: string;
  }) {
    const where = this.buildWineryBillWhere(query);
    const bills = await this.prisma.wineryBill.findMany({
      where,
-      include: { items: true },
      orderBy: { billDate: 'desc' },
    });
    const wineryBank = await loadWineryBankConfig(this.prisma);
+    const columnKeys = parseExportColumnKeys(query.columns);

-    const header = [
-      '账单号',
-      '账单日',
-      '订单号',
-      '配送类型',
-      '实付金额',
-      '酒厂比例',
-      '应付',
-      '支付时间',
-      '账单状态',
-      '打款凭证',
-      '收款户名',
-      '开户银行',
-      '开户支行',
-      '收款账号',
-    ].join(',');
-    const rows: string[] = [];
    const statusLabel = (b: { status: string; wineryAmount: Prisma.Decimal | number }) => {
      if (Number(b.wineryAmount) === 0) return '无需打款';
      if (b.status === 'PAID') return '已打款';
      if (b.status === 'UNPAID') return '未打款';
      return b.status;
    };
-    const bankCols = (b: { paymentRef?: string | null }) => [
-      csvEscape(b.paymentRef ?? ''),
-      csvEscape(wineryBank.bankAccountName ?? ''),
-      csvEscape(wineryBank.bankName ?? ''),
-      csvEscape(wineryBank.bankBranch ?? ''),
-      csvEscape(wineryBank.bankAccountNo ?? ''),
+
+    type ExportRow = {
+      billNo: string;
+      billDate: string;
+      periodStart: string;
+      periodEnd: string;
+      orderCount: number;
+      orderAmount: Prisma.Decimal | number;
+      wineryRate: Prisma.Decimal | number;
+      wineryAmount: Prisma.Decimal | number;
+      status: string;
+      paymentRef?: string | null;
+      paidAt?: Date | null;
+    };
+
+    const rows: ExportRow[] = bills.map((b) => ({
+      ...this.mapWineryBillForAdmin(b),
+      paymentRef: b.paymentRef,
+      paidAt: b.paidAt,
+    }));
+
+    const defs: ExportColumnDef<ExportRow>[] = [
+      { key: '账单号', header: '账单号', value: (r) => r.billNo },
+      { key: '出账日', header: '出账日', value: (r) => r.billDate },
+      {
+        key: '账期',
+        header: '账期',
+        value: (r) => `${r.periodStart} ~ ${r.periodEnd}`,
+      },
+      { key: '订单数', header: '订单数', value: (r) => r.orderCount },
+      { key: '订单总额', header: '订单总额', value: (r) => Number(r.orderAmount) },
+      { key: '酒厂比例', header: '酒厂比例', value: (r) => Number(r.wineryRate) },
+      { key: '应付', header: '应付', value: (r) => Number(r.wineryAmount) },
+      { key: '状态', header: '状态', value: (r) => statusLabel(r) },
+      {
+        key: '打款时间',
+        header: '打款时间',
+        value: (r) => (r.paidAt ? r.paidAt.toISOString().slice(0, 19).replace('T', ' ') : ''),
+      },
+      { key: '打款凭证', header: '打款凭证', value: (r) => r.paymentRef ?? '' },
+      { key: '收款户名', header: '收款户名', value: () => wineryBank.bankAccountName ?? '' },
+      { key: '开户银行', header: '开户银行', value: () => wineryBank.bankName ?? '' },
+      { key: '开户支行', header: '开户支行', value: () => wineryBank.bankBranch ?? '' },
+      { key: '收款账号', header: '收款账号', value: () => wineryBank.bankAccountNo ?? '' },
    ];
-    for (const b of bills) {
-      if (b.items.length === 0) {
-        rows.push(
-          [
-            csvEscape(b.billNo),
-            shanghaiYmd(b.billDate),
-            '',
-            '',
-            Number(b.orderAmount),
-            Number(b.wineryRate),
-            Number(b.wineryAmount),
-            '',
-            statusLabel(b),
-            ...bankCols(b),
-          ].join(','),
-        );
-        continue;
-      }
-      for (const item of b.items) {
-        rows.push(
-          [
-            csvEscape(b.billNo),
-            shanghaiYmd(b.billDate),
-            csvEscape(item.orderNo),
-            item.deliveryType === 'LOCAL'
-              ? '同城'
-              : item.deliveryType === 'CROSS_CITY'
-                ? '跨城'
-                : item.deliveryType === 'ON_SITE_PICKUP'
-                  ? '现场提货'
-                  : item.deliveryType,
-            Number(item.payAmount),
-            Number(b.wineryRate),
-            Number(item.wineryAmount),
-            item.paidAt.toISOString().slice(0, 19).replace('T', ' '),
-            statusLabel(b),
-            ...bankCols(b),
-          ].join(','),
-        );
-      }
-    }
-    return { csv: `\uFEFF${[header, ...rows].join('\n')}`, count: rows.length };
+
+    const aliases: Record<string, string> = {
+      billNo: '账单号',
+      billDate: '出账日',
+      period: '账期',
+      orderCount: '订单数',
+      orderAmount: '订单总额',
+      wineryRate: '酒厂比例',
+      wineryAmount: '应付',
+      status: '状态',
+      paidAt: '打款时间',
+      paymentRef: '打款凭证',
+      bankAccountName: '收款户名',
+      bankName: '开户银行',
+      bankBranch: '开户支行',
+      bankAccountNo: '收款账号',
+    };
+    const normalized = columnKeys?.map((k) => aliases[k] ?? k);
+
+    return buildCsvFromColumns(defs, rows, normalized);
  }

  private buildWineryBillWhere(query: {
@@ -3362,6 +3459,7 @@ export class SettlementService implements OnModuleInit {
    providerId?: string;
    year?: number;
    month?: number;
+    columns?: string;
  }) {
    const where = this.buildLogisticsBillWhere(query);
    const bills = await this.prisma.logisticsBill.findMany({
@@ -3377,78 +3475,73 @@ export class SettlementService implements OnModuleInit {
            bankAccountNo: true,
          },
        },
-        items: true,
      },
      orderBy: { periodStart: 'desc' },
    });
+    const columnKeys = parseExportColumnKeys(query.columns);

-    const header = [
-      '账单号',
-      '承运商编码',
-      '承运商名称',
-      '账期起',
-      '账期止',
-      '结算方式',
-      '订单号',
-      '瓶数',
-      '物流费',
-      '发货时间',
-      '账单状态',
-      '打款凭证',
-      '收款户名',
-      '开户银行',
-      '开户支行',
-      '收款账号',
-    ].join(',');
-    const rows: string[] = [];
-    for (const b of bills) {
-      const p = b.fulfillmentProvider;
-      const bankCols = [
-        csvEscape(b.paymentRef ?? ''),
-        csvEscape(p.bankAccountName ?? ''),
-        csvEscape(p.bankName ?? ''),
-        csvEscape(p.bankBranch ?? ''),
-        csvEscape(p.bankAccountNo ?? ''),
-      ];
-      if (b.items.length === 0) {
-        rows.push(
-          [
-            csvEscape(b.billNo),
-            csvEscape(p.code),
-            csvEscape(p.name),
-            shanghaiPeriodYmds(b.periodStart).periodStart,
-            shanghaiPeriodYmds(b.periodStart).periodEnd,
-            b.settlementMethod,
-            '',
-            b.bottleCount,
-            Number(b.logisticsAmount),
-            '',
-            b.status,
-            ...bankCols,
-          ].join(','),
-        );
-        continue;
-      }
-      for (const item of b.items) {
-        rows.push(
-          [
-            csvEscape(b.billNo),
-            csvEscape(p.code),
-            csvEscape(p.name),
-            shanghaiPeriodYmds(b.periodStart).periodStart,
-            shanghaiPeriodYmds(b.periodStart).periodEnd,
-            b.settlementMethod,
-            csvEscape(item.orderNo),
-            item.quantity,
-            Number(item.logisticsAmount),
-            item.shippedAt.toISOString().slice(0, 19).replace('T', ' '),
-            b.status,
-            ...bankCols,
-          ].join(','),
-        );
-      }
-    }
-    return { csv: `\uFEFF${[header, ...rows].join('\n')}`, count: rows.length };
+    type Row = (typeof bills)[number];
+    const defs: ExportColumnDef<Row>[] = [
+      { key: '账单号', header: '账单号', value: (r) => r.billNo },
+      {
+        key: '承运商',
+        header: '承运商',
+        value: (r) => `${r.fulfillmentProvider.name} (${r.fulfillmentProvider.code})`,
+      },
+      {
+        key: '账期',
+        header: '账期',
+        value: (r) => {
+          const p = shanghaiPeriodYmds(r.periodStart);
+          return `${p.periodStart} ~ ${p.periodEnd}`;
+        },
+      },
+      {
+        key: '结算方式',
+        header: '结算方式',
+        value: (r) =>
+          LOGISTICS_SETTLEMENT_METHOD_LABELS[
+            r.settlementMethod as keyof typeof LOGISTICS_SETTLEMENT_METHOD_LABELS
+          ] || r.settlementMethod,
+      },
+      { key: '订单数', header: '订单数', value: (r) => r.orderCount },
+      { key: '瓶数', header: '瓶数', value: (r) => r.bottleCount },
+      { key: '物流费', header: '物流费', value: (r) => Number(r.logisticsAmount) },
+      {
+        key: '收款户名',
+        header: '收款户名',
+        value: (r) => r.fulfillmentProvider.bankAccountName ?? '',
+      },
+      {
+        key: '收款账号',
+        header: '收款账号',
+        value: (r) => r.fulfillmentProvider.bankAccountNo ?? '',
+      },
+      { key: '状态', header: '状态', value: (r) => r.status },
+      {
+        key: '开户银行',
+        header: '开户银行',
+        value: (r) => r.fulfillmentProvider.bankName ?? '',
+      },
+      {
+        key: '开户支行',
+        header: '开户支行',
+        value: (r) => r.fulfillmentProvider.bankBranch ?? '',
+      },
+      { key: '打款凭证', header: '打款凭证', value: (r) => r.paymentRef ?? '' },
+    ];
+
+    const aliases: Record<string, string> = {
+      billNo: '账单号',
+      period: '账期',
+      settlementMethod: '结算方式',
+      orderCount: '订单数',
+      bottleCount: '瓶数',
+      logisticsAmount: '物流费',
+      status: '状态',
+    };
+    const normalized = columnKeys?.map((k) => aliases[k] ?? k);
+    return buildCsvFromColumns(defs, bills, normalized);
  }

  private buildLogisticsBillWhere(query: {