beta

docs/business_amount_mode_design_2026-07-01.md

@@ -0,0 +1,131 @@
+# Business 金额计算口径设计说明
+
+日期：2026-07-01
+
+## 背景
+
+Business 模块中存在采购、销售、退货、收款、付款等单据。当前项目原本按较高精度计算；为兼容好布业遗留系统，需要支持其整数元金额口径。
+
+本次实现不保存两套金额，不新增字段，不迁移历史数据。系统在任意时刻只启用一种计算口径，口径由配置项控制。
+
+## 目标
+
+- 将金额规则集中在一个入口，后续如果会议调整规则，修改范围尽量收窄。
+- 默认启用好布业整数元口径。
+- 保留回退到原两位小数口径的能力。
+- 采购、销售、采购退货、销售退货、收款、付款保持一致。
+- 覆盖外部财务同步直接创建收款单的路径。
+
+## 配置项
+
+配置项名称：
+
+```env
+BUSINESS_AMOUNT_MODE=haobuye_integer_round_half_up
+```
+
+可选值：
+
+- `haobuye_integer_round_half_up`：好布业整数元口径，默认值。
+- `standard_decimal_2`：原系统两位小数口径。
+
+配置读取位置：
+
+- `flower/settings.py`
+- 示例配置：`env.example`
+
+配置变更后需要重启会执行金额计算的进程，至少包括 Web 容器和 worker 容器。
+
+## 好布业整数元口径
+
+单据明细行：
+
+```text
+行金额 = ROUND_HALF_UP(quantity * price, 0)
+```
+
+单据总额：
+
+```text
+单据总额 = SUM(每一行取整后的行金额)
+```
+
+这里的“多行”对应 DataGrid 形式的一张单据内有多条明细：先逐行计算并取整，再对取整后的行金额求和。
+
+收款单、付款单没有明细行，按同一口径归一化金额：
+
+```text
+amount = ROUND_HALF_UP(amount, 0)
+discount_amount = ROUND_HALF_UP(discount_amount, 0)
+settlement_amount = ROUND_HALF_UP(amount, 0) + ROUND_HALF_UP(discount_amount, 0)
+```
+
+## 原两位小数口径
+
+单据明细行：
+
+```text
+行金额 = ROUND_HALF_UP(real_quantity * price, 2)
+```
+
+单据总额：
+
+```text
+单据总额 = SUM(每一行两位小数行金额)
+```
+
+收款单、付款单：
+
+```text
+amount = ROUND_HALF_UP(amount, 2)
+discount_amount = ROUND_HALF_UP(discount_amount, 2)
+settlement_amount = amount + discount_amount
+```
+
+## 涉及范围
+
+业务单据：
+
+- `PurchaseOrder`
+- `SalesOrder`
+- `PurchaseReturnOrder`
+- `SalesReturnOrder`
+- `PaymentOrder`
+- `ReceiptOrder`
+
+创建入口：
+
+- Business 服务层创建收款单、付款单时会归一化金额。
+- 好布业外部财务同步创建收款单时会归一化金额。
+- 明细类单据通过模型明细行的统一计算入口计算行金额和单据总额。
+
+## 不做的事
+
+- 不新增数据库字段。
+- 不新增 migration。
+- 不回算历史数据。
+- 不自动修复已经生成的资金流水。
+- 不同时保存整数元金额和两位小数金额。
+
+## 运行影响
+
+该变更主要影响未来创建或后续计算的业务金额。已经审批并生成的余额流水不会自动变化。
+
+如果存在未审批单据，审批时会按当前配置计算并写入流水。配置切换前后，需要避免同一批未审批单据跨口径处理。
+
+## 回退方式
+
+如需恢复原计算模式：
+
+```env
+BUSINESS_AMOUNT_MODE=standard_decimal_2
+```
+
+修改配置后重启 Web 和 worker 进程即可。由于本次没有数据库结构变更，也不回算历史数据，回退动作可以较快完成。
+
+## 风险与注意事项
+
+- 口径切换会改变未审批单据后续审批时的金额。
+- 对于没有保存快照、运行时重新计算总额的展示接口，切换配置后展示金额可能按新口径变化。
+- 收款、付款没有明细，已按同一配置归一化金额，以保证和明细单据一致。
+- 如果以后好布业规则再次调整，应优先修改集中计算入口，而不是分散修改各类单据。