erpnew/docs/business_amount_mode_design_2026-07-01.md

Business 金额计算口径设计说明

日期：2026-07-01

背景

Business 模块中存在采购、销售、退货、收款、付款等单据。当前项目原本按较高精度计算；为兼容好布业遗留系统，需要支持其整数元金额口径。

本次实现不保存两套金额，不新增字段，不迁移历史数据。系统在任意时刻只启用一种计算口径，口径由配置项控制。

目标

• 将金额规则集中在一个入口，后续如果会议调整规则，修改范围尽量收窄。
• 默认启用好布业整数元口径。
• 保留回退到原两位小数口径的能力。
• 采购、销售、采购退货、销售退货、收款、付款保持一致。
• 覆盖外部财务同步直接创建收款单的路径。

配置项

配置项名称：

BUSINESS_AMOUNT_MODE=haobuye_integer_round_half_up

可选值：

• haobuye_integer_round_half_up：好布业整数元口径，默认值。
• standard_decimal_2：原系统两位小数口径。

配置读取位置：

• flower/settings.py
• 示例配置：env.example

配置变更后需要重启会执行金额计算的进程，至少包括 Web 容器和 worker 容器。

好布业整数元口径

单据明细行：

行金额 = ROUND_HALF_UP(quantity * price, 0)

单据总额：

单据总额 = SUM(每一行取整后的行金额)

这里的“多行”对应 DataGrid 形式的一张单据内有多条明细：先逐行计算并取整，再对取整后的行金额求和。

收款单、付款单没有明细行，按同一口径归一化金额：

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)

原两位小数口径

单据明细行：

行金额 = ROUND_HALF_UP(real_quantity * price, 2)

单据总额：

单据总额 = SUM(每一行两位小数行金额)

收款单、付款单：

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。
• 不回算历史数据。
• 不自动修复已经生成的资金流水。
• 不同时保存整数元金额和两位小数金额。

运行影响

该变更主要影响未来创建或后续计算的业务金额。已经审批并生成的余额流水不会自动变化。

如果存在未审批单据，审批时会按当前配置计算并写入流水。配置切换前后，需要避免同一批未审批单据跨口径处理。

回退方式

如需恢复原计算模式：

BUSINESS_AMOUNT_MODE=standard_decimal_2

修改配置后重启 Web 和 worker 进程即可。由于本次没有数据库结构变更，也不回算历史数据，回退动作可以较快完成。

风险与注意事项

• 口径切换会改变未审批单据后续审批时的金额。
• 对于没有保存快照、运行时重新计算总额的展示接口，切换配置后展示金额可能按新口径变化。
• 收款、付款没有明细，已按同一配置归一化金额，以保证和明细单据一致。
• 如果以后好布业规则再次调整，应优先修改集中计算入口，而不是分散修改各类单据。