docs: 配送列表结算报表合并导出设计规格

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

docs/superpowers/specs/2026-08-31-delivery-settlement-export-merge-design.md

@@ -0,0 +1,158 @@
+# 配送列表「导出配送结算报表」合并设计
+
+> 日期：2026-08-31  
+> 范围：`web-admin` 配送列表 · 模板 03 明细 + 06 月度汇总  
+> 关联：  
+> - `docs/superpowers/specs/2026-08-30-settlement-report-export-template-design.md`  
+> - 商家/客户结算已落地的合并导出（红按钮 + 月份区间 + 双 sheet）  
+> 状态：设计已确认，待实现
+
+## 1. 背景与目标
+
+### 1.1 背景
+
+配送列表页现有两个报表导出按钮：
+
+| 按钮 | 模板 | 当前行为 |
+|------|------|----------|
+| 导出配送结算 | 03 配送商配送结算 | 跟页上关键字/状态等筛选导出明细；不按月份 |
+| 月度结算导出 | 06 月度配送商结算汇总 | 选**单月** → 按配送员汇总 |
+
+商家结算、客户结算已改造为：**一个红底高亮按钮 → 选起始/结束月 → 一个 Excel 含明细+汇总两个 sheet**。配送列表需对齐同一交互与产物形态。
+
+### 1.2 目标
+
+- 两按钮合并为 **「导出配送结算报表」**（红底白字）。
+- 选**月份区间**后导出**一个** Excel，含两个 sheet：`03_配送商配送结算`、`06_月度配送商结算汇总`。
+- 明细与汇总均只按月份区间 + 当前区域；**忽略**页上关键字、状态等筛选。
+- 状态口径：排除 `cancelled`，其余状态都计入。
+- 时间口径：沿用 `coalesce(delivery_time, create_at)`。
+
+### 1.3 非目标
+
+- 不新建配送商结算菜单、费率模型、应付/实付计算。
+- 不改客户/商家已上线导出逻辑。
+- 不把 6 个模板 sheet 打成一个总文件。
+- 不恢复「按页上筛选导出配送明细」能力（本期明确放弃）。
+
+---
+
+## 2. 已确认决策
+
+1. 方案：**方案 1** — 复用商家/客户改造路径（双接口并行 + 前端多 sheet 拼装）。
+2. 按钮文案：`导出配送结算报表`。
+3. 样式：红底 `#dc2626`、白字；hover `#b91c1c`（与商家/客户同款高亮）。
+4. 明细范围：与汇总完全一致，只按月份区间 + 区域（选项 A）。
+5. 时间字段：`delivery_time`，无则任务 `create_at`（选项 A）。
+6. 状态：`status != cancelled`。
+
+---
+
+## 3. 交互与产物
+
+### 3.1 交互
+
+- 工具栏仅保留 **「导出配送结算报表」**；点击打开月份区间弹窗。
+- 弹窗：起始月 + 结束月（`YYYY-MM`）；标题与按钮一致。
+- 未选齐月份：提示后不请求。
+- 起始月晚于结束月：提示后不请求（前后端均可校验；后端抛 ValueError → 400）。
+- 并行请求 03 + 06；两边都空 →「暂无数据」、不下载；有任一侧数据则生成文件并关闭弹窗。
+- 导出参数仅：`yearMonthStart`、`yearMonthEnd`、`regionId`。
+
+### 3.2 文件与 Sheet
+
+| 产物 | 约定 |
+|------|------|
+| 文件名 | `配送_结算报表_{hint}.xlsx` |
+| hint | 同月 `YYYY-MM`；跨月 `YYYY-MM~YYYY-MM` |
+| Sheet 1 | `03_配送商配送结算`（`HEADERS_03`） |
+| Sheet 2 | `06_月度配送商结算汇总`（`HEADERS_06`） |
+| 页脚签字 | 沿用现有：「配送商 / 记账 / 制单」 |
+
+Excel 生成：复用 `exportSettlementReportMultiSheetExcel`（`web-admin/src/utils/settlement-report-excel.ts`）。
+
+---
+
+## 4. 数据口径
+
+时间表达式：`eff_dt = coalesce(BizDeliveryTask.delivery_time, BizDeliveryTask.create_at)`。
+
+月份区间：复用 `resolve_year_month_range` → `[range_start, range_end)`；跨月时汇总行「结算月份」标签为 `YYYY-MM~YYYY-MM`。
+
+公共过滤：
+
+- `BizDeliveryTask.is_del = 0`
+- `BizDeliveryTask.status != 'cancelled'`
+- `region_id` = 当前有效区域（解析逻辑与现网一致）
+
+### 4.1 `build_delivery_lines`（03）
+
+- **按月模式**（有 `yearMonth` 或 `yearMonthStart`/`End`）：按 `eff_dt` 落在区间；忽略 keyword / status / deliverId / startDate / endDate。
+- **筛选模式**（无月份参数）：保留现有筛选行为，供兼容；本期配送页不再调用。
+- 行粒度、列填充不变（费率/金额列仍空；数量仍为任务商品数量合计）。
+
+### 4.2 `build_delivery_monthly_summary`（06）
+
+- 支持单月 `yearMonth` 与区间 `yearMonthStart`/`End`。
+- 按配送员聚合任务数、数量合计；金额列仍空。
+- 未分配配送员：编号空、名称「未分配」（与现网一致）。
+
+**配对保证**：同一区间 + 同一区域下，明细中出现的配送员集合应覆盖汇总表。
+
+---
+
+## 5. API 变更
+
+### 5.1 `GET /web/admin/settlement-reports/delivery-lines`
+
+新增可选查询参数：
+
+| 参数 | 说明 |
+|------|------|
+| `yearMonth` | `YYYY-MM`；单月兼容 |
+| `yearMonthStart` | 起始月 |
+| `yearMonthEnd` | 结束月 |
+
+有月份参数时进入按月模式（§4.1）；同时传筛选参数时以月份为准、忽略筛选（不报错）。
+
+### 5.2 `GET /web/admin/settlement-reports/delivery-monthly`
+
+| 参数 | 变更 |
+|------|------|
+| `yearMonth` | 改为可选（单月兼容） |
+| `yearMonthStart` / `yearMonthEnd` | 新增；与客户/商家汇总同构 |
+
+非法月份或起始晚于结束 → `400`。
+
+### 5.3 前端 API
+
+- `fetchSettlementReportDeliveryLines`：继续 `Record` 传参即可。
+- `fetchSettlementReportDeliveryMonthly`：参数类型放宽为含 `yearMonth?` / `yearMonthStart?` / `yearMonthEnd?` / `regionId?`。
+
+---
+
+## 6. 前端改动要点
+
+文件：`web-admin/src/views/system/delivery/index.vue`
+
+- 移除「导出配送结算」「月度结算导出」双按钮与跟筛明细导出逻辑。
+- 新增红底按钮 `btn-export-delivery` + 起止月弹窗（对齐客户/商家）。
+- `handleExportDeliveryReport`：`Promise.all` 拉明细+汇总 → 映射行 → `exportSettlementReportMultiSheetExcel`。
+- UI 规范：`docs/web-admin-ui-spec-fresh-mint.md` 追加配送合并导出留痕（建议第 53 条）。
+
+---
+
+## 7. 测试要点
+
+1. 选单月/跨月：文件名 hint、汇总「结算月份」标签正确。
+2. 已取消任务不出现在明细与汇总。
+3. 无数据月份：暂无数据、不下载空文件。
+4. 未选月 / 起始晚于结束：校验提示或 400。
+5. 区域隔离：只含当前区域。
+6. 同区间明细配送员集合覆盖汇总。
+
+---
+
+## 8. 与既有 Spec 的关系
+
+本设计**修订** 2026-08-30 设计中「03 跟页上筛选、06 单月单文件、6 种独立导出」在**配送列表入口**上的约定；模板列与金额留空规则不变。实现后应回写该文档 §3 对应说明，并注明配送入口以本文为准。