sqxp/docs/结算管理方案.md

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

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 快速筛选能力

该方案可同时满足：

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