2026-08-30-settlement-report-export-template-design.md 8.8 KB

陇耘鲜达结算报表模板导出设计

日期:2026-08-30
模板:结算导出的模版/陇耘鲜达结算报表模板.xlsx(6 个 sheet 合订样例)
范围:web-admin 订单/结算/配送相关导出
状态:已实现(Task 1–8);浏览器端到端导出冒烟由运营侧复核

1. 背景与目标

1.1 背景

客户提供结算报表 Excel 模板,含 6 个 sheet:

  1. 01_客户下单清单
  2. 02_供货商供货结算
  3. 03_配送商配送结算
  4. 04_月度客户结算汇总
  5. 05_月度供货商结算汇总
  6. 06_月度配送商结算汇总

合订仅为方便查阅样例;线上每种报表独立导出(一次一个文件、一个 sheet)。

现有系统具备:

  • 【订单列表】
  • 【商家结算管理】(供应商结算 + 既有结算单 Excel)
  • 【客户结算管理】(客户结算 + 既有结算单 Excel)
  • 【配送列表】(配送任务,无配送费结算)

无独立「配送商」主体与配送费率模型;配送侧为配送员 + 配送任务。

1.2 目标

  • 按客户模板版式,提供 6 种独立导出。
  • 客户 / 供应商 / 配送商(配送员)均支持 选月份 → 生成月度汇总 Excel(04 / 05 / 06)。
  • 系统只填充已有业务数据;没有的列一律留空(由客户线下填写)。
  • 不新建【配送商结算管理】菜单。

1.3 非目标(本期不做)

  • 不新建配送商结算管理模块、结算单状态机、配送费率配置。
  • 不实现配送费应付/实付/欠款计算。
  • 不把 6 个 sheet 打进同一个导出文件。
  • 不替换现有「结算单归档 Excel」(食堂定点采购计划表 / 供应商供货清单);两套导出并存。
  • 不写「重量 kg」;配送数量列只写商品数量。

2. 已确认决策

项 选择
总体方案 方案 1:按结算对象挂在现有页面,不新建配送商结算菜单
模板使用方式 6 种独立导出;合订 Excel 仅作样例
月度导出内容 只出月汇总(客户→04、供应商→05、配送→06),各一文件一 sheet
配送费率等金额 留空,客户手填
配送件数/重量列 只填配送商品数量(不计重量)
配送导出入口 【配送列表】
无数据的列 一律留空(不编造实结/已付/欠款等)
配送商主体映射 本期用配送员 ID/姓名填「配送商编号/名称」

3. 入口与职责

导出 页面 交互 输出
01+04 客户结算管理 「导出客户结算报表」→ 选起止月 单文件双 sheet:01 + 04
02+05 商家结算管理 「导出商家结算报表」→ 选起止月 单文件双 sheet:02 + 05
03+06 配送列表 「导出配送结算报表」→ 选起止月 单文件双 sheet:03 + 06

文件命名建议:{角色}_结算报表_{hint}.xlsx(同月 YYYY-MM,跨月 YYYY-MM~YYYY-MM)。

配送入口以 docs/superpowers/specs/2026-08-31-delivery-settlement-export-merge-design.md 为准;客户/商家合并导出以对应 2026-08-31 规格为准。

与现有结算单 Excel:并存;本期不强制统一或下线旧导出。


4. 列填充规则

原则:有系统数据则填;没有则空。

4.1 01 客户下单清单

列 规则
序号、订单编号、下单日期、客户编号、客户名称 客户编号=client_id;客户名称=real_name(无则 username)
商品名称、规格、单位、下单数量 订单商品行
客户结算单价、金额 有售价/金额则填
订单状态、备注 有则填

4.2 02 供货商供货结算

列 规则
序号、关联订单编号、供货日期、供货商编号/名称 有则填
供货单编号 与关联订单编号一致(填订单号 order_no;系统无独立供货单实体)
SKU、商品名称、规格、单位、供货数量 有则填
采购单价、供货金额 有则填
验收状态、结算状态 能映射现有状态则填,否则空
扣款/罚款、实结金额 留空
备注 有则填

4.3 03 配送商配送结算

列 规则
序号、配送单编号(task_no)、关联订单编号、配送日期 有则填
配送商编号/名称 配送员 ID/姓名
客户编号、客户名称/站点、起点、终点 有则填;无则空
配送件数/重量 仅填该任务商品数量合计:优先 delivered_quantity 之和,否则下单 quantity 之和;不写重量单位换算
配送费率、应付配送费、异常扣款、实结配送费 全部留空
结算状态 可填配送任务状态文案;无则空
备注 有则填

4.4 04 / 05 / 06 月度汇总

列 04 客户 05 供应商 06 配送
结算月份、对象编号/名称 填 填 填(配送员)
笔数 订单笔数 供货相关笔数(按订单或可映射口径) 配送单笔数
数量合计 商品数量合计 供货数量合计 配送商品数量合计
应收/应付金额 有订单应收/金额则填 有采购应付则填 留空
优惠/调整、罚款/扣款、实收/实付、已付、欠款 留空 留空 留空
结算状态、对账日期、备注 能映射则填状态;其余空 同左 同左

5. 数据范围与聚合口径

5.1 通用

  • 按当前运营账号区域过滤。
  • is_del = 0。
  • 订单类导出(01/02/04/05):排除 cancelled(已取消);其余状态均计入。
  • 配送类导出(03/06):已取消配送任务不进入导出。
  • 金额单位与现网一致:库内按项目既有口径(分/元)转换后写入「元」,保留 2 位小数。

5.2 明细导出

报表 行粒度 时间字段 范围
01 订单商品行 客户结算入口(按月):订单下单月 create_at(与 04 同口径)。筛选模式(兼容):下单日 create_at 客户结算:选年-月全量;API 无 yearMonth 时仍可筛选/勾选
02 订单商品行(供货视角) 商家结算入口(按月):订单下单月 create_at(与 05 同口径;见 2026-08-31-supplier-supply-export-by-month-design.md)。筛选模式(兼容):优先完结日 completed_time,否则 create_at 商家结算:选年-月全量;API 无 yearMonth 时仍可筛选/勾选
03 配送任务一行 配送完成/配送时间,否则任务创建时间 配送列表当前筛选

5.3 月度汇总

  • 交互:选 年-月 → 下载。
  • 时间归属:
    • 04 / 05:建议按订单 下单月(create_at 落在该月);与明细 01 一致,避免口径分裂。
    • 06:按配送日期(完成/配送时间)落在该月。
  • 04:一行 = 该月有计入订单的一个客户。
  • 05:一行 = 该月有计入供货的一个供应商。
  • 06:一行 = 该月有计入任务的一个配送员。

若实施时发现供应商维度必须挂在订单项/分配供应商上,按现有商家结算数据模型拆行,不新增「供货单」实体(除非已有)。


6. 技术要点(实施约束)

  • 前端:对齐模板表头;可用既有 ExcelJS + file-saver(参考 client-settlement-sheet-excel.ts),新增独立导出工具模块,避免与旧结算单版式耦合。
  • 后端:明细/月度数据可走现有列表数据组装,或新增轻量导出查询接口(按角色投影字段);禁止 N+1。
  • UI:按钮与弹窗遵循 Fresh Mint(docs/web-admin-ui-spec-fresh-mint.md);改动后按约定留痕。
  • 模板文件:以 结算导出的模版/陇耘鲜达结算报表模板.xlsx 为表头与列序权威;页脚签字行可按模板保留空行文案。

7. 验收标准

  1. 六个导出入口分别在约定页面可见,均可独立下载单 sheet 文件。
  2. 列序与模板对应 sheet 一致;无数据列为空,不出现「0 元假数据」冒充已付/欠款(笔数/数量为 0 的汇总行不应输出)。
  3. 03 的件数/重量列仅为数量合计;费率及相关金额列为空。
  4. 04/05/06 选月后按区域聚合正确;取消单/任务不计入。
  5. 不出现新的「配送商结算管理」菜单。
  6. 旧结算单 Excel 导出仍可用。

8. 开放实现细节(计划阶段再钉)

以下不影响产品口径,留给 implementation plan 细化:

  • 01/02 明细按钮落在「待结算」Tab 还是「结算单记录」Tab,或两处都有。
  • 导出超大数据量时的前端生成 vs 后端流式下载。
  • 状态文案与模板「结算状态/验收状态」的精确映射表。
  • 05「供货单笔数」在无独立供货单时是否等同「订单笔数(按供应商)」。