forked from erp-dev/erp
132 lines
3.7 KiB
Markdown
132 lines
3.7 KiB
Markdown
# 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 进程即可。由于本次没有数据库结构变更，也不回算历史数据，回退动作可以较快完成。
|
||
|
||
## 风险与注意事项
|
||
|
||
- 口径切换会改变未审批单据后续审批时的金额。
|
||
- 对于没有保存快照、运行时重新计算总额的展示接口，切换配置后展示金额可能按新口径变化。
|
||
- 收款、付款没有明细，已按同一配置归一化金额，以保证和明细单据一致。
|
||
- 如果以后好布业规则再次调整，应优先修改集中计算入口，而不是分散修改各类单据。
|