|
|
@@ -0,0 +1,134 @@
|
|
|
+# 商家结算「导出供货结算」按月导出设计
|
|
|
+
|
|
|
+> 日期：2026-08-31
|
|
|
+> 范围：`web-admin` 商家结算管理 · 模板 02 明细导出
|
|
|
+> 关联：`docs/superpowers/specs/2026-08-30-settlement-report-export-template-design.md`
|
|
|
+> 状态：设计已确认，待实现
|
|
|
+
|
|
|
+## 1. 背景与目标
|
|
|
+
|
|
|
+### 1.1 背景
|
|
|
+
|
|
|
+商家结算管理页现有两个报表导出按钮：
|
|
|
+
|
|
|
+| 按钮 | 模板 | 当前行为 |
|
|
|
+|------|------|----------|
|
|
|
+| 导出供货结算 | 02 供货商供货结算 | 跟页上筛选/勾选导出商品明细；时间优先完结日 |
|
|
|
+| 月度结算导出 | 05 月度供货商结算汇总 | 弹窗选月；按订单下单月 `create_at` 汇总 |
|
|
|
+
|
|
|
+运营期望两者成对使用：**同一月份的汇总表 + 明细表**。
|
|
|
+
|
|
|
+### 1.2 目标
|
|
|
+
|
|
|
+- 「导出供货结算」改为：**选月 → 导出该月全部商品明细**。
|
|
|
+- 与「月度结算导出」使用**同一时间口径**（订单 `create_at` 落在所选年月）。
|
|
|
+- 明细不再依赖页上日期筛选、关键字、勾选订单。
|
|
|
+
|
|
|
+### 1.3 非目标
|
|
|
+
|
|
|
+- 不改客户结算 / 配送列表的明细导出交互。
|
|
|
+- 不改模板 02 / 05 列结构与 Excel 生成工具。
|
|
|
+- 不替换结算单行内「下载」旧版 Excel。
|
|
|
+- 不恢复「按筛选/勾选导出明细」能力（本期明确放弃）。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 2. 已确认决策
|
|
|
+
|
|
|
+1. 交互：**只按月份**（点按钮 → 选月 → 导出该月全量明细）。
|
|
|
+2. 时间字段：与月度汇总一致，用订单 **`create_at`**（不再用完结日优先）。
|
|
|
+3. 范围：当前运营区域 + `is_del = 0` + 排除已取消订单；不叠加供应商/关键字/勾选。
|
|
|
+4. 方案：后端明细接口支持 `yearMonth`；前端固定走月度路径（方案 B）。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 3. 交互与产物
|
|
|
+
|
|
|
+### 3.1 交互
|
|
|
+
|
|
|
+- 「导出供货结算」打开选月弹窗（样式对齐现有「月度供货商结算汇总导出」：`order-module-dialog` + 月份 `el-date-picker`）。
|
|
|
+- 标题建议：`供货结算明细导出`（与汇总弹窗区分）。
|
|
|
+- 未选月份：提示「请选择结算月份」，不请求。
|
|
|
+- 无数据：`暂无数据`；有数据：下载后关闭弹窗。
|
|
|
+
|
|
|
+「月度结算导出」行为不变。
|
|
|
+
|
|
|
+### 3.2 文件命名
|
|
|
+
|
|
|
+| 按钮 | Sheet | 文件名 |
|
|
|
+|------|-------|--------|
|
|
|
+| 导出供货结算 | `02_供货商供货结算` | `供应商_供货结算_YYYY-MM.xlsx` |
|
|
|
+| 月度结算导出 | `05_月度供货商结算汇总` | `供应商_月度结算汇总_YYYY-MM.xlsx`（不变） |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 4. 数据口径
|
|
|
+
|
|
|
+与 `build_supplier_monthly_summary` 对齐：
|
|
|
+
|
|
|
+- `yearMonth`：`YYYY-MM` → `[start, end)`（`parse_year_month`）。
|
|
|
+- 过滤：`BizOrder.create_at >= start AND create_at < end`。
|
|
|
+- `BizOrder.is_del = 0`，`order_status != cancelled`。
|
|
|
+- `region_id`：当前有效区域。
|
|
|
+- 行粒度：仍为一行 = 一条订单商品行（供货价视角）；列填充规则仍按原 02 模板（扣款/实结等无数据则空）。
|
|
|
+
|
|
|
+**配对保证**：同一 `yearMonth` + 同一 `regionId` 下，明细中出现的供应商集合应覆盖汇总表供应商；汇总笔数/数量/应付可由该月明细聚合得到（允许浮点展示差异在既有金额规则内）。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 5. API 变更
|
|
|
+
|
|
|
+### 5.1 `GET /web/admin/settlement-reports/supplier-supply-lines`
|
|
|
+
|
|
|
+新增查询参数：
|
|
|
+
|
|
|
+| 参数 | 必填 | 说明 |
|
|
|
+|------|------|------|
|
|
|
+| `yearMonth` | 与筛选模式互斥 | `YYYY-MM`；有值时进入**按月模式** |
|
|
|
+
|
|
|
+**按月模式（本期商家结算页使用）：**
|
|
|
+
|
|
|
+- 必填：`yearMonth`；可选：`regionId`。
|
|
|
+- 忽略：`supplierId`、`keyword`、`startDate`、`endDate`、`orderIds`。
|
|
|
+- 服务层按 §4 过滤；时间字段改为 `create_at`（仅此模式）。
|
|
|
+
|
|
|
+**筛选模式（保留兼容，本期 web-admin 商家结算页不再调用）：**
|
|
|
+
|
|
|
+- 无 `yearMonth` 时行为可与现网一致（含完结日优先逻辑），供其他潜在调用方或后续回退。
|
|
|
+- 若同时传 `yearMonth` 与筛选参数：以 `yearMonth` 为准，忽略筛选参数（不报错）。
|
|
|
+
|
|
|
+非法 `yearMonth`：返回 400。
|
|
|
+
|
|
|
+### 5.2 前端 API
|
|
|
+
|
|
|
+`fetchSettlementReportSupplierSupplyLines` 增加可选 `yearMonth`；商家结算页只传 `{ yearMonth, regionId }`。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 6. 前端改动要点
|
|
|
+
|
|
|
+文件：`web-admin/src/views/system/supplier-settlement/index.vue`
|
|
|
+
|
|
|
+- 「导出供货结算」改为打开选月弹窗（可复用状态机：一个弹窗 + `exportKind: 'detail' | 'monthly'`，或两个独立弹窗；推荐**一个弹窗 + kind**，避免重复 UI）。
|
|
|
+- `handleExportSupplyLines`：校验月份 → 调接口 → 映射 `HEADERS_02` → 文件名带 `YYYY-MM`。
|
|
|
+- 删除明细导出对 `buildFilters` / `selectedIds` 的依赖。
|
|
|
+
|
|
|
+Excel 工具：`settlement-report-excel.ts` 无需改表头。
|
|
|
+
|
|
|
+UI 规范：弹窗/按钮对齐 Fresh Mint；若有表述变更，在 `docs/web-admin-ui-spec-fresh-mint.md` 简短留痕。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 7. 测试要点
|
|
|
+
|
|
|
+1. 选某月导出明细与同月汇总：供应商集合一致；明细行可按供应商聚合出汇总数量/应付（在金额规则内）。
|
|
|
+2. 无订单月份：提示暂无数据，不下载空文件。
|
|
|
+3. 未选月点导出：校验提示。
|
|
|
+4. 已取消订单不出现在明细与汇总。
|
|
|
+5. 区域隔离：只含当前区域数据。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 8. 与既有 Spec 的关系
|
|
|
+
|
|
|
+本设计**修订** 2026-08-30 设计中「02 跟页上筛选/勾选、时间优先完结日」在**商家结算管理入口**上的约定；模板列与 05 汇总逻辑不变。实现后应回写该文档 §3 / §5.2 对应说明，并注明以本文为准。
|
