# 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 进程即可。由于本次没有数据库结构变更，也不回算历史数据，回退动作可以较快完成。

## 风险与注意事项

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