# 订单结算管理方案（客户结算 + 商家结算）

## 1. 目标与范围

本方案用于落地 Web 端两个新页面：

- 客户结算管理
- 商家（供应商）结算管理

两页面保持统一风格，统一操作模式，重点保证：

- 金额展示清晰（总金额、待结算金额、已结算金额、当前勾选金额）
- 支持客户/供应商检索 + 日期区间检索
- 支持检索结果跨分页快速全选并批量结算
- 结算凭证、备注、审计信息可追溯

---

## 2. 业务规则

### 2.1 客户结算规则

- 线上支付订单：默认视为已与客户结算完成，不允许再次进入客户结算批次。
- 线下支付订单：可参与客户结算批量操作。
- 批量结算时上传结算凭证（建议一批次可多文件），并填写结算备注（可选）。
- 结算提交后，关联订单更新为客户已结算。

### 2.2 商家结算规则

- 商家结算独立于客户结算。
- 可按供应商、日期区间等检索待结算订单。
- 批量结算时上传结算凭证并填写备注，提交后更新为商家已结算。

### 2.3 结算颗粒度

- 当前按“整单结算”设计，不做部分金额结算。
- 一笔订单可同时具有两个维度状态：客户结算状态、商家结算状态（互不影响）。

---

## 3. 数据模型设计

> 建议采用“结算主表 + 结算明细表 + 订单状态字段”组合，既便于业务操作，也便于后续审计与追溯。

## 3.1 订单表扩展（`biz_order`）

建议新增字段：

- `client_settlement_status`：客户结算状态（`pending`/`settled`），默认 `pending`
- `supplier_settlement_status`：商家结算状态（`pending`/`settled`），默认 `pending`
- `client_settlement_at`：客户结算时间（最后一次）
- `supplier_settlement_at`：商家结算时间（最后一次）

说明：

- 线上支付订单在写入或补数时直接置 `client_settlement_status = settled`。
- 查询待结算列表时按对应状态过滤。

## 3.2 客户结算主表（`ord_client_settlement`）

核心业务字段建议：

- `settlement_no`：结算单号（唯一）
- `client_id`：客户 ID
- `client_name`：客户名称
- `order_count`：订单数量
- `total_amount`：结算总金额（DECIMAL(12,2)）
- `voucher_urls`：结算凭证（JSON 字符串或逗号分隔 URL）
- `remark`：结算备注
- `settlement_at`：结算时间
- `status`：结算单状态（建议先保留 `done`，后续可扩展）

按项目规范必备字段：

- `id`, `is_del`, `create_at`, `create_by`, `create_name`, `update_at`, `update_by`

## 3.3 客户结算明细表（`ord_client_settlement_item`）

核心字段建议：

- `settlement_id`：结算主表 ID
- `order_id`：订单 ID
- `order_no`：订单号（冗余便于查询）
- `order_amount`：该订单结算金额（DECIMAL(12,2)）
- `client_id`：客户 ID（冗余）

按项目规范必备字段：

- `id`, `is_del`, `create_at`, `create_by`, `create_name`, `update_at`, `update_by`

## 3.4 商家结算主表（`ord_supplier_settlement`）

核心业务字段建议：

- `settlement_no`：结算单号（唯一）
- `supplier_id`：供应商 ID
- `supplier_name`：供应商名称
- `order_count`：订单数量
- `total_amount`：结算总金额（DECIMAL(12,2)）
- `voucher_urls`：结算凭证
- `remark`：结算备注
- `settlement_at`：结算时间
- `status`：结算单状态

按项目规范必备字段：

- `id`, `is_del`, `create_at`, `create_by`, `create_name`, `update_at`, `update_by`

## 3.5 商家结算明细表（`ord_supplier_settlement_item`）

核心字段建议：

- `settlement_id`：结算主表 ID
- `order_id`：订单 ID
- `order_no`：订单号
- `order_amount`：该订单结算金额（DECIMAL(12,2)）
- `supplier_id`：供应商 ID（冗余）

按项目规范必备字段：

- `id`, `is_del`, `create_at`, `create_by`, `create_name`, `update_at`, `update_by`

## 3.6 历史表（按规范必须）

每个业务表建立历史表并在 UPDATE 前写入旧值：

- `ord_client_settlement_his`
- `ord_client_settlement_item_his`
- `ord_supplier_settlement_his`
- `ord_supplier_settlement_item_his`

历史表规则：

- 与主表结构一致
- 不建索引
- `id` 不要求唯一
- 不需要 `is_del`

---

## 4. 索引与查询建议

## 4.1 订单列表检索索引（`biz_order`）

建议索引：

- `(is_del, client_settlement_status, payment_method, create_at)`
- `(is_del, supplier_settlement_status, supplier_id, create_at)`
- `(is_del, client_id, create_at)`
- `(is_del, supplier_id, create_at)`

## 4.2 明细表索引

- `ord_client_settlement_item`: `(settlement_id)`, `(order_id)`, `(client_id)`
- `ord_supplier_settlement_item`: `(settlement_id)`, `(order_id)`, `(supplier_id)`

---

## 5. 页面交互设计（统一风格）

## 5.1 页面结构

两页面统一采用：

1. 检索区
2. 金额统计卡片区
3. 订单表格区（可勾选）
4. 底部批量操作栏（显示已选条数与已选金额）

## 5.2 检索项

客户结算管理建议检索项：

- 客户（支持模糊）
- 日期区间（下单时间或完成时间，需统一）
- 订单号
- 结算状态（默认“待结算”）

商家结算管理建议检索项：

- 供应商（支持模糊）
- 日期区间
- 订单号
- 结算状态（默认“待结算”）

## 5.3 金额展示（重点）

统计区建议至少包含：

- 检索结果订单总金额
- 待结算金额
- 已结算金额
- 当前勾选结算金额

金额统一规则：

- 后端存分，前端显示元（保留 2 位）
- 对负值、空值、异常值统一兜底显示 `0.00`
- 千分位格式化，强化可读性

## 5.4 跨分页全选方案（重点）

推荐交互：

1. 用户先检索得到结果集（例如 2,356 条）
2. 点击“全选当前页”后，提示“是否全选本次检索结果 2,356 条？”
3. 用户确认后进入“全结果集选中”模式，并可手动排除个别不需要结算的订单
4. 底部栏实时显示：
   - 已选总条数（跨页）
   - 已选总金额
   - 已排除条数
5. 提交时传“筛选条件快照 + 排除 ID 列表”或“明确选中 ID 列表（数量较小时）”

推荐技术实现：

- 维护 `selectMode`：
  - `page`：仅当前页勾选
  - `allFiltered`：全检索结果选中 + exclusion
- 维护 `excludedOrderIds` 集合
- 金额统计接口支持按“筛选条件 + exclusion”返回实时合计

---

## 6. API 设计建议

> 路由前缀按现有规范：Web 端 `/api/web/`

## 6.1 客户结算管理

- `GET /api/web/client-settlements/orders`
  - 查询客户结算候选订单（支持分页、检索、统计）
- `POST /api/web/client-settlements/preview`
  - 预计算本次结算金额（支持 allFiltered + exclusion）
- `POST /api/web/client-settlements`
  - 创建客户结算单并落明细，批量更新订单客户结算状态
- `GET /api/web/client-settlements`
  - 结算单列表
- `GET /api/web/client-settlements/{id}`
  - 结算单详情（含明细）

## 6.2 商家结算管理

- `GET /api/web/supplier-settlements/orders`
- `POST /api/web/supplier-settlements/preview`
- `POST /api/web/supplier-settlements`
- `GET /api/web/supplier-settlements`
- `GET /api/web/supplier-settlements/{id}`

## 6.3 创建结算请求体建议

通用字段：

- `selectionMode`: `ids` | `allFiltered`
- `orderIds`: string[]（`ids` 模式下必填）
- `filters`: object（`allFiltered` 模式下必填）
- `excludedOrderIds`: string[]
- `voucherUrls`: string[]
- `remark`: string

服务端处理要点：

- 使用事务：写结算主表 -> 写明细 -> 更新订单状态
- 并发幂等：同一订单不可被重复结算（状态校验 + 行锁）
- 返回结算单号和结算结果汇总

---

## 7. 状态流转建议

## 7.1 客户结算状态（订单维度）

- `pending`：待客户结算
- `settled`：已客户结算

特殊规则：

- `payment_method = online` 的订单，初始化为 `settled`

## 7.2 商家结算状态（订单维度）

- `pending`：待商家结算
- `settled`：已商家结算

---

## 8. 风险与控制

- 重复结算风险：提交前后二次校验订单状态，事务内最终校验
- 金额一致性风险：结算金额以服务端重新聚合为准，前端金额仅展示
- 跨分页误操作风险：全选结果集时必须二次确认并展示影响条数/金额
- 凭证缺失风险：可配置“上传凭证必填”校验

---

## 9. 分阶段落地建议

第一阶段（必做）：

- 订单表新增双结算状态字段
- 新增客户/商家结算主表与明细表
- 新增两结算管理页面（检索、勾选、上传凭证、批量结算）
- 支持跨分页全选（allFiltered + exclusion）

第二阶段（增强）：

- 结算单详情页与导出
- 结算操作日志与权限细化
- 结算凭证文件归档策略（对象存储生命周期）

---

## 10. 结论

本需求建议采用“两个结算业务域 + 订单双状态字段”的方案：

- 客户结算域：`ord_client_settlement` + `ord_client_settlement_item`
- 商家结算域：`ord_supplier_settlement` + `ord_supplier_settlement_item`
- 订单保留 `client_settlement_status` / `supplier_settlement_status` 快速筛选能力

该方案可同时满足：

- 批量结算效率
- 凭证与备注留痕
- 金额统计准确
- 跨分页全选可用性
- 后续审计与追溯能力