# `naisi_amount_to_scaled_int`

将十进制金额转换为指定精度的缩放整数。
全程按十进制处理并在舍入后检查 64 位有符号整数范围；不会退化为 float。
仅接受原始签名类型，类型不匹配直接返回 false，不进行隐式转换；需要 LICENSE/PROOF 授权及 DATA capability。

## 函数签名

```php
function naisi_amount_to_scaled_int(string $amount, int $decimals = 2, int $rounding_mode = NAISI_DECIMAL_ROUND_HALF_UP): int|false
```

## 调用前提

应用入口先调用 [naisi_is_ext_license_valid](/web/developers/naisilib/naisi-is-ext-license-valid) 并确认返回 `true`。只验证同一请求内已有的有效 FULL/BASIC 证明；没有证明或证明失效时立即返回失败值，不现场补做完整校验。

授权类别：`LICENSE`；执行模式：`PROOF`。许可不代替登录、租户或权限上下文；身份与数据要求见本页参数及用途说明。

## 参数

### `$amount`

- 类型：`string`
- 必填：是
- 默认值：无
- 方向：输入参数。

1～256 字节 ASCII 十进制金额，完整匹配 [+-]?[0-9]+(?:\.[0-9]+)?；允许前导零及超过六位的输入小数，拒绝空白、千分位、科学计数法和 NUL。不得先经 float 转换。

### `$decimals`

- 类型：`int`
- 必填：否
- 默认值：`2`
- 方向：输入参数。

缩放精度，支持 0～6，默认 2；结果为金额乘以 10 的 decimals 次方后按指定模式取整。

### `$rounding_mode`

- 类型：`int`
- 必填：否
- 默认值：`NAISI_DECIMAL_ROUND_HALF_UP`
- 方向：输入参数。

HALF_UP 取最近值且居中时远离零；CEILING 向正无穷；FLOOR 向负无穷。仅接受三个 NAISI_DECIMAL_ROUND_* 常量，默认 HALF_UP。

## 返回值

类型：`int|false`

成功返回 PHP 整数，包含 PHP_INT_MIN 与 PHP_INT_MAX；参数类型不匹配、非法内容、参数值无效、舍入后越界、未授权或处理失败返回 false。整数 0 为成功值。

## 关联常量

- [`NAISI_DECIMAL_ROUND_HALF_UP`](/web/developers/naisilib/const#naisi-decimal-round-half-up) = `1` — 金额四舍五入模式。 取最近值，恰好居中时向远离零的方向舍入；1.235 保留两位为 1.24，-1.235 为 -1.24。
- [`NAISI_DECIMAL_ROUND_CEILING`](/web/developers/naisilib/const#naisi-decimal-round-ceiling) = `2` — 金额向上舍入模式。 向正无穷舍入；1.231 保留两位为 1.24，-1.231 为 -1.23。
- [`NAISI_DECIMAL_ROUND_FLOOR`](/web/developers/naisilib/const#naisi-decimal-round-floor) = `3` — 金额向下舍入模式。 向负无穷舍入；1.231 保留两位为 1.23，-1.231 为 -1.24，不等同于直接截断。

## 调用示例

当前请求须满足上方调用前提；请检查实际返回值和引用输出，随机结果及数据包内容以运行环境为准。

```php
$amount = '-1001.0007919';
$decimals = 1;
$rounding_mode = 2;

$result = naisi_amount_to_scaled_int($amount, $decimals, $rounding_mode);
var_export($result);
```

## 金额精度与失败规则

三个金额接口均只接受声明的原始 PHP 类型，弱类型调用也不隐式转换。金额字符串为 1～256 字节，完整匹配 `[+-]?[0-9]+(?:\.[0-9]+)?`；支持正负号、前导零和超过六位的输入小数，不接受空白、千分位、科学计数法、货币符号、NUL、`.5` 或 `1.`。目标精度支持每个整数值 `0～6`，默认 `2`。

金额从 JSON、数据库读取到业务传递均保留十进制字符串，不经过 float/double。只有显式缩放转换才输出经过范围检查的整数；缩放整数对应 64 位 PHP 和 MySQL `BIGINT SIGNED`，范围为 `-9223372036854775808`～`9223372036854775807`。每个字段的写入和读取精度必须一致。

类型不匹配、无效内容、精度或舍入模式错误、转换越界及授权失败返回 `false`；用 `=== false` 判断失败，整数 `0` 和字符串 `"0"` 都可能是合法结果。参数数量错误仍遵循 PHP 规则。

## 升级与相关接口

金额展示使用 [naisi_format_amount](/web/developers/naisilib/naisi-format-amount)，金额与缩放整数转换分别使用 [naisi_amount_to_scaled_int](/web/developers/naisilib/naisi-amount-to-scaled-int) 和 [naisi_scaled_int_to_amount](/web/developers/naisilib/naisi-scaled-int-to-amount)。

旧 `naisi_normalize_amount()` 已从当前源码移除，没有兼容包装。它与缩放整数还原不是同一操作，迁移时先确认原始数据含义。`naisi_format_amount()` 的旧 `$price`、`$show_decimals`、`$show_zero_decimals` 参数已改为 `$amount`、`$decimals`、`$fixed_decimals`；位置调用和命名参数调用均需同步。格式化结果只用于展示，不回写为计算金额。

## 版本信息

- 自版本：`1.0.6`
- 实现模块：`formatting`
- 授权类别：`LICENSE` / `PROOF`
- 失败回退：`false`
- 文档同步：`2026-10-18`