2026-08-30-settlement-report-export-template.md 21 KB

结算报表模板六种独立导出 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 在客户结算、商家结算、配送列表三处提供与客户模板对齐的 6 种独立 Excel 导出(01–06),月度支持选月生成;无系统数据的列留空;不新建配送商结算菜单。

Architecture: 后端新增 /web/admin/settlement-reports/* 查询接口(批量投影、禁止 N+1),返回行数据 JSON;前端用独立 settlement-report-excel.ts(ExcelJS)按模板表头生成单 sheet 单文件。旧结算单导出(client-settlement-sheet-excel.ts)不动。

Tech Stack: FastAPI + SQLAlchemy;Vue3 + TS + Element Plus;ExcelJS + file-saver

Global Constraints

  • Spec: docs/superpowers/specs/2026-08-30-settlement-report-export-template-design.md
  • 模板权威:结算导出的模版/陇耘鲜达结算报表模板.xlsx
  • 每次导出 = 一个文件、一个 sheet;不打合订包
  • 无数据列一律留空(不写假 0 冒充已付/欠款/费率)
  • 03「配送件数/重量」= 商品数量合计(优先已配送数量);费率与金额列空
  • 配送商 = 配送员 ID/姓名;不新建配送商结算菜单
  • 区域隔离 + is_del=0;取消订单/取消配送任务不导出
  • 04/05 时间口径:订单 下单月(create_at);06:配送日(delivery_time 否则 create_at)
  • 05「供货单笔数」= 该供应商在该月计入的 订单笔数(无独立供货单实体)
  • 01/02 按钮放在各自页「待结算订单」工具栏;04/05/06 用「月度结算导出」弹窗选月
  • 单次导出行数上限:20000;超限返回 400 提示缩小范围
  • UI:Fresh Mint(btn-ghost / btn-main);改完在 docs/web-admin-ui-spec-fresh-mint.md 留痕
  • 不主动 git commit(除非用户要求)
  • web-admin 无单测脚手架:以前端手工验收 + 后端可手测接口为准

File map

文件 职责
backend/app/services/settlement_reports.py 行数据组装(01–06),纯查询聚合
backend/app/api/settlement_reports.py 6 个导出数据 API
backend/app/api/__init__.py 导出 router
backend/app/main.py include_router
web-admin/src/utils/settlement-report-excel.ts 按模板写单 sheet Excel
web-admin/src/api/business.ts 前端 API 封装
web-admin/src/views/system/client-settlement/index.vue 01 + 04 入口
web-admin/src/views/system/supplier-settlement/index.vue 02 + 05 入口
web-admin/src/views/system/delivery/index.vue 03 + 06 入口
docs/web-admin-ui-spec-fresh-mint.md 变更留痕

Task 1: 前端 Excel 工具(表头与空列行为)

Files:

  • Create: web-admin/src/utils/settlement-report-excel.ts

Interfaces:

  • Produces:

    • exportSettlementReportExcel(opts: { sheetName: string; headers: string[]; rows: Array<Array<string \| number \| null \| undefined>>; filename: string; footerSign?: string }): Promise<void>
    • 常量表头:HEADERS_01 … HEADERS_06(与模板列序完全一致)
    • emptyToBlank(v):null/undefined/'' → 单元格空;不把金额空列写成 0
  • [x] Step 1: 创建工具文件

import ExcelJS from 'exceljs'
import { saveAs } from 'file-saver'

export const HEADERS_01 = [
  '序号', '订单编号', '下单日期', '客户编号', '客户名称', '商品名称', '规格', '单位',
  '下单数量', '客户结算单价(元)', '金额(元)', '订单状态', '备注'
] as const

export const HEADERS_02 = [
  '序号', '供货单编号', '关联订单编号', '供货日期', '供货商编号', '供货商名称', 'SKU编码',
  '商品名称', '规格', '单位', '供货数量', '采购单价(元)', '供货金额(元)', '验收状态',
  '扣款/罚款(元)', '实结金额(元)', '结算状态', '备注'
] as const

export const HEADERS_03 = [
  '序号', '配送单编号', '关联订单编号', '配送日期', '配送商编号', '配送商名称', '客户编号',
  '客户名称/站点', '起点(供货商/仓)', '终点(客户站点)', '配送件数/重量(kg)',
  '配送费率(元/kg或件)', '应付配送费(元)', '异常扣款(元)', '实结配送费(元)',
  '结算状态', '备注'
] as const

export const HEADERS_04 = [
  '序号', '结算月份', '客户编号', '客户名称/站点', '订单笔数', '商品总数量', '应收金额(元)',
  '优惠/调整(元)', '实收金额(元)', '已付金额(元)', '欠款(元)', '结算状态', '对账日期', '备注'
] as const

export const HEADERS_05 = [
  '序号', '结算月份', '供货商编号', '供货商名称', '供货单笔数', '供货总数量', '应付金额(元)',
  '罚款/扣款(元)', '实付金额(元)', '已付金额(元)', '欠款(元)', '结算状态', '对账日期', '备注'
] as const

export const HEADERS_06 = [
  '序号', '结算月份', '配送商编号', '配送商名称', '配送单笔数', '配送总件数/重量',
  '应付配送费(元)', '异常扣款(元)', '实付配送费(元)', '已付金额(元)', '欠款(元)',
  '结算状态', '对账日期', '备注'
] as const

function cellValue(v: string | number | null | undefined): string | number {
  if (v === null || v === undefined || v === '') return ''
  return v
}

export async function exportSettlementReportExcel(opts: {
  sheetName: string
  headers: readonly string[]
  rows: Array<Array<string | number | null | undefined>>
  filename: string
  footerSign?: string
}): Promise<void> {
  const wb = new ExcelJS.Workbook()
  const ws = wb.addWorksheet(opts.sheetName)
  ws.addRow([...opts.headers])
  for (const row of opts.rows) {
    ws.addRow(row.map(cellValue))
  }
  if (opts.footerSign) {
    ws.addRow([])
    ws.addRow([opts.footerSign])
  }
  const buffer = await wb.xlsx.writeBuffer()
  saveAs(
    new Blob([buffer], {
      type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
    }),
    opts.filename.endsWith('.xlsx') ? opts.filename : `${opts.filename}.xlsx`
  )
}
  • Step 2: 本地冒烟(可选)

在任意已登录页的浏览器控制台无法直接 import;改为实现后在页面点一次导出,确认表头列数:01=13,02=18,03=17,04/05/06=14。

  • Step 3: 完成标准

文件存在且导出函数可被页面 import;不修改 client-settlement-sheet-excel.ts。


Task 2: 后端服务层 — 通用与客户报表(01 / 04)

Files:

  • Create: backend/app/services/settlement_reports.py

Interfaces:

  • Produces:
    • EXPORT_ROW_LIMIT = 20000
    • parse_year_month(year_month: str) -> tuple[datetime, datetime] # [start, next_month)
    • build_client_order_lines(db, *, region_id, client_id=None, keyword=None, start=None, end=None, order_ids=None) -> list[dict]
    • build_client_monthly_summary(db, *, region_id, year_month: str) -> list[dict]
  • 行 dict 键用驼峰,与前端直接映射;金额已是「元」float(与现网 total_amount 一致),无值用 None

  • [x] Step 1: 实现 parse_year_month 与常量

from datetime import datetime
from calendar import monthrange

EXPORT_ROW_LIMIT = 20000

def parse_year_month(year_month: str) -> tuple[datetime, datetime]:
    """year_month: 'YYYY-MM' -> [month_start, next_month_start)"""
    parts = (year_month or "").strip().split("-")
    if len(parts) != 2:
        raise ValueError("yearMonth 格式应为 YYYY-MM")
    y, m = int(parts[0]), int(parts[1])
    if m < 1 or m > 12:
        raise ValueError("yearMonth 月份无效")
    start = datetime(y, m, 1, 0, 0, 0)
    if m == 12:
        end = datetime(y + 1, 1, 1, 0, 0, 0)
    else:
        end = datetime(y, m + 1, 1, 0, 0, 0)
    return start, end
  • Step 2: 实现 build_client_order_lines

逻辑要点(须遵守):

  1. 查 BizOrder:is_del==0,order_status != 'cancelled',region_id 过滤。
  2. 可选:client_id、order_no like keyword、create_at 落在 [start,end]、id.in_(order_ids)。
  3. 批量拉 BizOrderItem、BasProduct、BasProductUnit、SysUser(客户);售价优先复用 admin._price_list_item_map / 结算列表同款单价逻辑(可从 admin 局部 import 已有 helper,避免复制错误公式)。
  4. 一行 = 一个订单商品行。
  5. 若行数 > EXPORT_ROW_LIMIT:raise ValueError("导出数据超过 20000 行,请缩小筛选范围")。
  6. 返回字段示例:
{
  "orderNo": o.order_no,
  "orderDate": o.create_at.strftime("%Y-%m-%d %H:%M:%S") if o.create_at else None,
  "clientId": o.client_id,
  "clientName": client_name,
  "productName": ...,
  "spec": ...,
  "unitName": ...,
  "quantity": float(qty) if qty is not None else None,
  "unitPrice": sell_u,       # 无则 None
  "amount": sell_amt,        # 无则 None
  "orderStatusText": ORDER_STATUS_MAP.get(o.order_status),
  "remark": o.remark,
}
  • Step 3: 实现 build_client_monthly_summary
  1. start, end = parse_year_month(year_month)
  2. 订单:create_at >= start AND create_at < end,区域,未删除,非取消。
  3. 按 client_id 聚合:orderCount=count distinct order,quantitySum=sum items.quantity,receivableAmount=sum order.total_amount(有则填)。
  4. 优惠/实收/已付/欠款/对账日期:不输出数字 0 冒充,这些键直接不设或为 None。
  5. settlementMonth = year_month(如 2026-08)。
  • Step 4: 完成标准

服务函数可被 API import;超限抛 ValueError。


Task 3: 后端服务层 — 供应商(02 / 05)与配送(03 / 06)

Files:

  • Modify: backend/app/services/settlement_reports.py

Interfaces:

  • Produces:

    • build_supplier_supply_lines(...) → 02 行
    • build_supplier_monthly_summary(...) → 05 行
    • build_delivery_lines(...) → 03 行
    • build_delivery_monthly_summary(...) → 06 行
  • [x] Step 1: build_supplier_supply_lines

  1. 数据源对齐商家结算:订单 + 价格清单上的 supplier_id(与 _build_supplier_pending_settlement_tree_rows 同源)。
  2. 过滤:区域、非取消、可选 supplierId / keyword / 日期(日期用 completed_time or create_at)、可选 orderIds。
  3. 一行 = 订单商品行;填:关联订单号、供货日期、供货商编号/名称、SKU、品名、规格、单位、数量、采购单价、供货金额、供应商结算状态文案(pending→待供应商结算,settled→已与供应商结算)。
  4. 供货单编号、扣款、实结:恒为 None。
  • Step 2: build_supplier_monthly_summary
  1. 下单月口径同 04。
  2. 按供应商聚合:笔数 = distinct order_id;数量 = sum 行数量;应付 = sum 供货金额(有则填)。
  3. 罚款/实付/已付/欠款 = None。
  • Step 3: build_delivery_lines
  1. BizDeliveryTask:is_del==0,status != 'cancelled',区域;可选 keyword(task_no/order_no)、status、deliverId、日期筛选用 delivery_time or create_at。
  2. 批量:订单、客户、配送员、BizDeliveryTaskItem、供应商(任务上 supplier_id 作起点名称)。
  3. 数量:对任务明细,若任一 delivered_quantity>0 则 sum(delivered_quantity),否则 sum(quantity)。
  4. 费率/应付/扣款/实结 = None。
  5. 状态文案:与配送列表一致(可复用 delivery 模块标签或本地 map)。
  • Step 4: build_delivery_monthly_summary
  1. 配送日落在月内;按 deliver_id 聚合(无配送员的任务可聚到「未分配」一行,编号空、名称为「未分配」)。
  2. 填:笔数、数量合计;所有金额列 None。
  • Step 5: 完成标准

四个 builder 均有超限检查;金额空列不返回 0。


Task 4: 后端 API 路由注册

Files:

  • Create: backend/app/api/settlement_reports.py
  • Modify: backend/app/api/__init__.py
  • Modify: backend/app/main.py

Interfaces:

  • Produces HTTP(均需运营登录 + 区域权限,与其它 admin 接口相同依赖):
Method Path 说明
GET /web/admin/settlement-reports/client-order-lines 01
GET /web/admin/settlement-reports/client-monthly 04 yearMonth 必填
GET /web/admin/settlement-reports/supplier-supply-lines 02
GET /web/admin/settlement-reports/supplier-monthly 05
GET /web/admin/settlement-reports/delivery-lines 03
GET /web/admin/settlement-reports/delivery-monthly 06

统一响应:success_response({ "list": [...], "total": n });ValueError → error_response(400, str(e))。

  • Step 1: 写 router
from fastapi import APIRouter, Depends, Query
from typing import Optional
from sqlalchemy.orm import Session
from app.core.database import get_db
# 使用与 admin 结算接口相同的 get_current_admin / 区域解析方式
from app.services import settlement_reports as svc
from app.core.response import success_response, error_response

router = APIRouter(prefix="/web/admin/settlement-reports", tags=["结算报表导出"])

@router.get("/client-order-lines")
def export_client_order_lines(
    regionId: Optional[str] = Query(None),
    clientId: Optional[str] = Query(None),
    keyword: Optional[str] = Query(None),
    startDate: Optional[str] = Query(None),
    endDate: Optional[str] = Query(None),
    orderIds: Optional[str] = Query(None, description="逗号分隔,优先于日期筛选"),
    db: Session = Depends(get_db),
    # current_admin = Depends(...),
):
    try:
        ids = [x for x in (orderIds or "").split(",") if x.strip()] or None
        rows = svc.build_client_order_lines(
            db, region_id=..., client_id=clientId, keyword=keyword,
            start=..., end=..., order_ids=ids,
        )
        return success_response({"list": rows, "total": len(rows)})
    except ValueError as e:
        return error_response(400, str(e))

其余 5 个端点同模式。regionId 解析必须与 list_client_settlement_orders 一致(超管可选区域,普通运营强制本区域)。

  • Step 2: 注册

在 backend/app/api/__init__.py 增加 settlement_reports_router;在 main.py:

app.include_router(settlement_reports_router, prefix=settings.API_V1_PREFIX)
  • Step 3: 手测

通过 app.openapi() 确认 6 路径已挂载;yearMonth 为必填;非法 yearMonth 由服务层抛 ValueError(API 转 400)。带 Token 的 curl 留给联调/Task 5。

  • Step 4: 完成标准

6 个路径可访问;非法 yearMonth 返回 400。


Task 5: 前端 API + 客户结算页(01 / 04)

Files:

  • Modify: web-admin/src/api/business.ts
  • Modify: web-admin/src/views/system/client-settlement/index.vue

Interfaces:

  • Consumes: Task 1 excel util;Task 4 APIs
  • Produces: fetchSettlementReportClientOrderLines、fetchSettlementReportClientMonthly 等 6 个函数(本 Task 先做客户 2 个,其余可同文件一次加齐)

  • [x] Step 1: API 封装(6 个一次加完)

export function fetchSettlementReportClientOrderLines(params: Record<string, any>) {
  return request.get({ url: '/web/admin/settlement-reports/client-order-lines', params })
}
export function fetchSettlementReportClientMonthly(params: { yearMonth: string; regionId?: string }) {
  return request.get({ url: '/web/admin/settlement-reports/client-monthly', params })
}
export function fetchSettlementReportSupplierSupplyLines(params: Record<string, any>) {
  return request.get({ url: '/web/admin/settlement-reports/supplier-supply-lines', params })
}
export function fetchSettlementReportSupplierMonthly(params: { yearMonth: string; regionId?: string }) {
  return request.get({ url: '/web/admin/settlement-reports/supplier-monthly', params })
}
export function fetchSettlementReportDeliveryLines(params: Record<string, any>) {
  return request.get({ url: '/web/admin/settlement-reports/delivery-lines', params })
}
export function fetchSettlementReportDeliveryMonthly(params: { yearMonth: string; regionId?: string }) {
  return request.get({ url: '/web/admin/settlement-reports/delivery-monthly', params })
}
  • Step 2: 客户页 UI

在「待结算订单」toolbar 内「结算」按钮旁增加:

<el-button class="btn-ghost" :loading="exportingDetail" @click="handleExportOrderLines"
  >导出下单清单</el-button
>
<el-button class="btn-ghost" @click="openMonthlyExportDialog">月度结算导出</el-button>

月度弹窗:

<el-dialog v-model="monthlyExportVisible" title="月度客户结算汇总导出" width="420px" class="order-module-dialog">
  <el-form label-position="top">
    <el-form-item label="结算月份" required>
      <el-date-picker v-model="monthlyExportMonth" type="month" value-format="YYYY-MM" placeholder="选择月份" />
    </el-form-item>
  </el-form>
  <template #footer>
    <el-button class="btn-ghost" @click="monthlyExportVisible = false">取消</el-button>
    <el-button class="btn-main" type="primary" :loading="exportingMonthly" @click="handleExportMonthly"
      >导出</el-button
    >
  </template>
</el-dialog>
  • Step 3: 导出逻辑

handleExportOrderLines:

  1. 若有勾选订单 → orderIds 传勾选 id;否则传当前 clientId/keyword/dateRange + regionId。
  2. 调 API → 映射为 HEADERS_01 行(序号从 1)→ exportSettlementReportExcel。
  3. 文件名:客户_下单清单_{日期或筛选}.xlsx。
  4. footerSign 可用模板文案:分管站长:...(可选)。

handleExportMonthly:校验月份 → 调 monthly API → 映射 HEADERS_04(优惠/实收/已付/欠款列传 null)→ 文件名 客户_月度结算汇总_{YYYY-MM}.xlsx。

  • [x] Step 4: 手工验收

  • 无勾选 + 有筛选:导出行符合筛选

  • 有勾选:只含勾选订单商品行

  • 月度:选月下载;空月提示「暂无数据」不下载(暂无数据则 warning 不下载)

代码侧已实现;浏览器联调由用户复核。

  • Step 5: 完成标准

客户页两个按钮可用;旧「结算单导出」仍可用。


Task 6: 商家结算页(02 / 05)

Files:

  • Modify: web-admin/src/views/system/supplier-settlement/index.vue

Interfaces:

  • Consumes: 与 Task 5 相同的 API / excel util

  • [x] Step 1: 工具栏加「导出供货结算」「月度结算导出」(btn-ghost,交互同客户页)

  • [x] Step 2: 明细映射 HEADERS_02

扣款、实结、供货单编号列显式传 null/''。

  • Step 3: 月度映射 HEADERS_05

文件名:供应商_月度结算汇总_{YYYY-MM}.xlsx。

  • Step 4: 手工验收

切换供应商筛选后导出内容仅含该供应商;月度按供应商多行。浏览器联调由用户复核。


Task 7: 配送列表(03 / 06)

Files:

  • Modify: web-admin/src/views/system/delivery/index.vue

Interfaces:

  • Consumes: delivery report APIs + excel util

  • [x] Step 1: 在 filter-actions-row 或 panel-top 右侧加按钮

  • [x] Step 2: 明细映射 HEADERS_03

数量列用接口返回的 quantityTotal;费率与四类金额列空。

  • Step 3: 月度 HEADERS_06

金额列全空;文件名 配送_月度结算汇总_{YYYY-MM}.xlsx。

  • [x] Step 4: 手工验收

  • 排除已取消任务

  • 件数列为数量不是重量

  • 无新菜单项

浏览器联调由用户复核。


Task 8: UI 规范留痕与总验收

Files:

  • Modify: docs/web-admin-ui-spec-fresh-mint.md(追加一小段变更记录)
  • Modify: docs/superpowers/specs/2026-08-30-settlement-report-export-template-design.md(状态改为「实施计划已就绪 / 开发中」)

  • [x] Step 1: 在 Fresh Mint 文档追加

说明三页新增「导出… / 月度结算导出」为 btn-ghost,月度弹窗用 order-module-dialog,不新增侧栏菜单。

  • Step 2: 对照 spec §7 验收清单逐项勾选
  1. 六个入口可独立下载 — 代码已就位(三页各两按钮;浏览器冒烟待用户)
  2. 列序与模板一致;空列为空 — PASS(HEADERS_01–06 与模板 6/6 一致;emptyToBlank)
  3. 03 仅数量;费率金额空 — PASS(quantityTotal;rate/fees = None)
  4. 月度区域聚合正确;取消不计入 — 代码已就位(服务层过滤 cancelled;联调待用户)
  5. 无配送商结算菜单 — PASS(无新页面/菜单文件)
  6. 旧结算单 Excel 仍可用 — PASS(exportClientSettlementSheetExcel / exportSupplierSettlementSheetExcel 仍引用)
  • Step 3: 完成标准

文档已更新;代码侧验收清单通过;浏览器端到端留给用户复核。


Spec coverage self-check

Spec 要求 Task
01 客户下单清单 T2 + T4 + T5
02 供货商供货结算 T3 + T4 + T6
03 配送结算 + 数量口径 T3 + T4 + T7
04/05/06 月度独立文件 T2–T7
不新建配送商菜单 T7/T8(仅配送列表按钮)
无数据留空 T1 cellValue + 各 builder 返回 None
旧导出并存 T5 不改旧 excel 工具
Fresh Mint 留痕 T8
行数上限 T2/T3 ValueError + API 400

Placeholder scan

无 TBD;开放项已钉死(按钮位置、供货笔数=订单笔数、前端生成 Excel、超限 20000)。