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
docs/superpowers/specs/2026-08-30-settlement-report-export-template-design.md结算导出的模版/陇耘鲜达结算报表模板.xlsxis_del=0;取消订单/取消配送任务不导出create_at);06:配送日(delivery_time 否则 create_at)20000;超限返回 400 提示缩小范围btn-ghost / btn-main);改完在 docs/web-admin-ui-spec-fresh-mint.md 留痕web-admin 无单测脚手架:以前端手工验收 + 后端可手测接口为准| 文件 | 职责 |
|---|---|
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 |
变更留痕 |
Files:
web-admin/src/utils/settlement-report-excel.tsInterfaces:
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`
)
}
在任意已登录页的浏览器控制台无法直接 import;改为实现后在页面点一次导出,确认表头列数:01=13,02=18,03=17,04/05/06=14。
文件存在且导出函数可被页面 import;不修改 client-settlement-sheet-excel.ts。
Files:
backend/app/services/settlement_reports.pyInterfaces:
EXPORT_ROW_LIMIT = 20000parse_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
build_client_order_lines逻辑要点(须遵守):
BizOrder:is_del==0,order_status != 'cancelled',region_id 过滤。client_id、order_no like keyword、create_at 落在 [start,end]、id.in_(order_ids)。BizOrderItem、BasProduct、BasProductUnit、SysUser(客户);售价优先复用 admin._price_list_item_map / 结算列表同款单价逻辑(可从 admin 局部 import 已有 helper,避免复制错误公式)。EXPORT_ROW_LIMIT:raise ValueError("导出数据超过 20000 行,请缩小筛选范围")。{
"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,
}
build_client_monthly_summarystart, end = parse_year_month(year_month)create_at >= start AND create_at < end,区域,未删除,非取消。client_id 聚合:orderCount=count distinct order,quantitySum=sum items.quantity,receivableAmount=sum order.total_amount(有则填)。None。settlementMonth = year_month(如 2026-08)。服务函数可被 API import;超限抛 ValueError。
Files:
backend/app/services/settlement_reports.pyInterfaces:
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
supplier_id(与 _build_supplier_pending_settlement_tree_rows 同源)。supplierId / keyword / 日期(日期用 completed_time or create_at)、可选 orderIds。pending→待供应商结算,settled→已与供应商结算)。None。build_supplier_monthly_summaryorder_id;数量 = sum 行数量;应付 = sum 供货金额(有则填)。None。build_delivery_linesBizDeliveryTask:is_del==0,status != 'cancelled',区域;可选 keyword(task_no/order_no)、status、deliverId、日期筛选用 delivery_time or create_at。BizDeliveryTaskItem、供应商(任务上 supplier_id 作起点名称)。delivered_quantity>0 则 sum(delivered_quantity),否则 sum(quantity)。None。build_delivery_monthly_summarydeliver_id 聚合(无配送员的任务可聚到「未分配」一行,编号空、名称为「未分配」)。None。四个 builder 均有超限检查;金额空列不返回 0。
Files:
backend/app/api/settlement_reports.pybackend/app/api/__init__.pybackend/app/main.pyInterfaces:
| 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))。
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 一致(超管可选区域,普通运营强制本区域)。
在 backend/app/api/__init__.py 增加 settlement_reports_router;在 main.py:
app.include_router(settlement_reports_router, prefix=settings.API_V1_PREFIX)
通过 app.openapi() 确认 6 路径已挂载;yearMonth 为必填;非法 yearMonth 由服务层抛 ValueError(API 转 400)。带 Token 的 curl 留给联调/Task 5。
6 个路径可访问;非法 yearMonth 返回 400。
Files:
web-admin/src/api/business.tsweb-admin/src/views/system/client-settlement/index.vueInterfaces:
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 })
}
在「待结算订单」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>
handleExportOrderLines:
orderIds 传勾选 id;否则传当前 clientId/keyword/dateRange + regionId。HEADERS_01 行(序号从 1)→ exportSettlementReportExcel。客户_下单清单_{日期或筛选}.xlsx。分管站长:...(可选)。handleExportMonthly:校验月份 → 调 monthly API → 映射 HEADERS_04(优惠/实收/已付/欠款列传 null)→ 文件名 客户_月度结算汇总_{YYYY-MM}.xlsx。
[x] Step 4: 手工验收
无勾选 + 有筛选:导出行符合筛选
有勾选:只含勾选订单商品行
月度:选月下载;空月提示「暂无数据」不下载(暂无数据则 warning 不下载)
代码侧已实现;浏览器联调由用户复核。
客户页两个按钮可用;旧「结算单导出」仍可用。
Files:
web-admin/src/views/system/supplier-settlement/index.vueInterfaces:
Consumes: 与 Task 5 相同的 API / excel util
[x] Step 1: 工具栏加「导出供货结算」「月度结算导出」(btn-ghost,交互同客户页)
[x] Step 2: 明细映射 HEADERS_02
扣款、实结、供货单编号列显式传 null/''。
HEADERS_05文件名:供应商_月度结算汇总_{YYYY-MM}.xlsx。
切换供应商筛选后导出内容仅含该供应商;月度按供应商多行。浏览器联调由用户复核。
Files:
web-admin/src/views/system/delivery/index.vueInterfaces:
Consumes: delivery report APIs + excel util
[x] Step 1: 在 filter-actions-row 或 panel-top 右侧加按钮
[x] Step 2: 明细映射 HEADERS_03
数量列用接口返回的 quantityTotal;费率与四类金额列空。
HEADERS_06金额列全空;文件名 配送_月度结算汇总_{YYYY-MM}.xlsx。
[x] Step 4: 手工验收
排除已取消任务
件数列为数量不是重量
无新菜单项
浏览器联调由用户复核。
Files:
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,不新增侧栏菜单。
emptyToBlank)quantityTotal;rate/fees = None)exportClientSettlementSheetExcel / exportSupplierSettlementSheetExcel 仍引用)文档已更新;代码侧验收清单通过;浏览器端到端留给用户复核。
| 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 |
无 TBD;开放项已钉死(按钮位置、供货笔数=订单笔数、前端生成 Excel、超限 20000)。