docs: 结算报表模板六种独立导出设计规格

明确客户/供应商/配送导出入口、列填充与月度汇总口径，不新建配送商结算模块。

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/superpowers/specs/2026-08-30-settlement-report-export-template-design.md

@@ -0,0 +1,190 @@
+# 陇耘鲜达结算报表模板导出设计
+
+> 日期：2026-08-30  
+> 模板：`结算导出的模版/陇耘鲜达结算报表模板.xlsx`（6 个 sheet 合订样例）  
+> 范围：`web-admin` 订单/结算/配送相关导出  
+> 状态：设计已确认，待写实施计划
+
+## 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 客户下单清单 | 客户结算管理 | 「导出下单清单」（筛选/勾选范围） | 单 sheet：01 |
+| 02 供货商供货结算 | 商家结算管理 | 「导出供货结算」 | 单 sheet：02 |
+| 03 配送商配送结算 | 配送列表 | 「导出配送结算」 | 单 sheet：03 |
+| 04 月度客户结算汇总 | 客户结算管理 | 「月度结算导出」→ 选年-月 | 单 sheet：04 |
+| 05 月度供货商结算汇总 | 商家结算管理 | 「月度结算导出」→ 选年-月 | 单 sheet：05 |
+| 06 月度配送商结算汇总 | 配送列表 | 「月度结算导出」→ 选年-月 | 单 sheet：06 |
+
+文件命名建议：`{角色}_{报表简称}_{范围}.xlsx`  
+示例：`客户_月度结算汇总_2026-08.xlsx`、`配送_配送结算_2026-08-01~08-30.xlsx`。
+
+与现有结算单 Excel：并存；本期不强制统一或下线旧导出。
+
+---
+
+## 4. 列填充规则
+
+原则：**有系统数据则填；没有则空。**
+
+### 4.1 01 客户下单清单
+
+| 列 | 规则 |
+|----|------|
+| 序号、订单编号、下单日期、客户编号、客户名称 | 有则填 |
+| 商品名称、规格、单位、下单数量 | 订单商品行 |
+| 客户结算单价、金额 | 有售价/金额则填 |
+| 订单状态、备注 | 有则填 |
+
+### 4.2 02 供货商供货结算
+
+| 列 | 规则 |
+|----|------|
+| 序号、关联订单编号、供货日期、供货商编号/名称 | 有则填 |
+| 供货单编号 | 有独立单号则填；否则留空（不伪造） |
+| SKU、商品名称、规格、单位、供货数量 | 有则填 |
+| 采购单价、供货金额 | 有则填 |
+| 验收状态、结算状态 | 能映射现有状态则填，否则空 |
+| 扣款/罚款、实结金额 | **留空** |
+| 备注 | 有则填 |
+
+### 4.3 03 配送商配送结算
+
+| 列 | 规则 |
+|----|------|
+| 序号、配送单编号（`task_no`）、关联订单编号、配送日期 | 有则填 |
+| 配送商编号/名称 | 配送员 ID/姓名 |
+| 客户编号、客户名称/站点、起点、终点 | 有则填；无则空 |
+| 配送件数/重量 | **仅填该任务商品数量合计**：优先 `delivered_quantity` 之和，否则下单 `quantity` 之和；不写重量单位换算 |
+| 配送费率、应付配送费、异常扣款、实结配送费 | **全部留空** |
+| 结算状态 | 可填配送任务状态文案；无则空 |
+| 备注 | 有则填 |
+
+### 4.4 04 / 05 / 06 月度汇总
+
+| 列 | 04 客户 | 05 供应商 | 06 配送 |
+|----|---------|-----------|---------|
+| 结算月份、对象编号/名称 | 填 | 填 | 填（配送员） |
+| 笔数 | 订单笔数 | 供货相关笔数（按订单或可映射口径） | 配送单笔数 |
+| 数量合计 | 商品数量合计 | 供货数量合计 | 配送商品数量合计 |
+| 应收/应付金额 | 有订单应收/金额则填 | 有采购应付则填 | **留空** |
+| 优惠/调整、罚款/扣款、实收/实付、已付、欠款 | **留空** | **留空** | **留空** |
+| 结算状态、对账日期、备注 | 能映射则填状态；其余空 | 同左 | 同左 |
+
+---
+
+## 5. 数据范围与聚合口径
+
+### 5.1 通用
+
+- 按当前运营账号**区域**过滤。
+- `is_del = 0`。
+- **已取消**订单 / **已取消**配送任务不进入导出。
+- 金额单位与现网一致：库内按项目既有口径（分/元）转换后写入「元」，保留 2 位小数。
+
+### 5.2 明细导出
+
+| 报表 | 行粒度 | 时间字段 | 范围 |
+|------|--------|----------|------|
+| 01 | 订单商品行 | 下单日 = 订单 `create_at` | 页面筛选；若支持勾选则优先勾选订单 |
+| 02 | 订单商品行（供货视角） | 优先完结日 `completed_time`，否则 `create_at` | 同上，按供应商 |
+| 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「供货单笔数」在无独立供货单时是否等同「订单笔数（按供应商）」。