# 功能对照与数值回归

当前实现范围、版本差异及验证方式见[功能范围与维护记录](maintenance-history.md)。以下样例用于界定功能边界并复现计算结果。

## 项目范围

Aurum 是 MoonBit 中的基础金融计算库原型。项目核心范围包含三项可检查能力：

1. `money`：用币种最小单位的整数表达金额，并明确范围、舍入和错误契约；
2. `tvm` 与 `capital`：实现常见周期现金流估算，并说明 NPV 时间点、IRR 可报告条件和数值边界；
3. `amortize`：提供两类周期还款公式及还款计划。

`wear`、`bond`、`ratio`、`currency` 是有限输入与公式示例，展示相同的模块化和失败处理方式。它们不表示 Aurum 覆盖了完整固定资产会计、债券市场估值、财报分析或外汇服务。库不接入行情，不处理日期/节假日/日计数约定、票息日程、收益率曲线、税务及会计准则，也不适用于未经业务复核的实际资金结算。

## 成熟工具对照

MoonBit 生态内的相邻包与具体能力交集另见 [MoonBit 生态定位与边界核对](moonbit-ecosystem.md)（2026-10-12）。其中记录已发布包版本、文档/API 来源及核验限制；以下跨语言对照不能用于推导 MoonBit 生态缺少相关实现。

对照依据是各项目公开文档中的功能范围和接口约定。该表用于界定项目位置，不代表本项目已运行其他语言实现进行性能或逐值基准测试。

| 能力 | NumPy Financial（Python） | Python `decimal` | QuantLib | Aurum（MoonBit） |
| --- | --- | --- | --- | --- |
| 常见 TVM / 现金流 | 提供 `fv`、`pv`、`pmt`、`npv`、`irr` 等周期函数；NPV 文档规定首项现金流位于 `t=0` | 十进制数值类型，不提供这些领域函数 | 可用于广泛的定量金融建模 | 提供有限期 TVM、NPV（含逐期现值分解）、IRR、名义/有效年利率换算；现金流等间隔，NPV 首项为 `t=0` |
| 金额表示 | 提供周期金融函数，但不提供与 Aurum 相同的、带币种和币种精度规则的 Money 类型；具体数值类型按各 API 文档描述（部分函数支持 Decimal 等输入） | 支持十进制算术及上下文精度/舍入 | 提供金融建模组件；此项目不对其金额模型作等价性声明 | `Money` 用 32 位 `Int` 保存最小单位；有严格文本解析、整数比例运算和等额/最大余数权重分摊；范围有限，溢出按契约返回 `None` 或中止 |
| 贷款计算 | 提供付款、本金和利息分量等公式函数 | 不提供贷款领域公式 | 可表达更广泛的金融工具和现金流模型 | 提供浮点公式计划及分位舍入计划；末期余额对账，不处理日期、费用或合同条款 |
| 债券估值 | 不作为本项目的债券市场对标 | 不提供债券领域公式 | 定位为覆盖建模、交易与风险管理的定量金融库 | 仅支持规则周期的简化票息/收益率/久期/凸性计算，不含市场日历、日计数和曲线 |
| 本项目定位 | 参考其基础周期公式和接口范围 | 参考其十进制语义边界 | 参考其完整金融平台的功能边界；不宣称功能等价 | 面向 MoonBit 的小型基础计算实现和可检查的错误契约 |

来源： [NumPy Financial 函数索引](https://numpy.org/numpy-financial/latest/genindex.html)、[NumPy Financial `fv`](https://numpy.org/numpy-financial/latest/fv.html)、[NumPy Financial `npv`](https://numpy.org/numpy-financial/latest/_api_stubs/numpy_financial.npv.html)、[Python `decimal`](https://docs.python.org/3/library/decimal.html)、[QuantLib 项目介绍](https://www.quantlib.org/index.shtml)、[QuantLib 官方文档入口](https://www.quantlib.org/docs.shtml)。

## 可复现回归样例

以下固定样例用于检查核心功能的计算行为。浮点结果使用给定绝对误差；这些是实现回归值，不是跨语言性能基准。跨模块断言位于 `lib/integration/integration.mbt`，公式级数值断言和边界契约由各模块单元测试覆盖。

| 场景 | 输入 | 预期结果 | 容差/判定 |
| --- | --- | --- | --- |
| 精确金额 | `Money::of(10, "CNY").add(Money::of(20, "CNY"))` | `minor = 30`，格式为 `0.30` | 整数精确相等 |
| 精确输入与按权重分摊 | 解析 `100.00 CNY`，按 `[1,2,3]` 分摊 | `16.67`、`33.33`、`50.00`；总和 `100.00` | 每份整数最小单位，合计精确 |
| 单笔终值 | `1000`，每期利率 `0.05`，`2` 期 | `1102.5` | 绝对误差 `< 1e-9` |
| 利率口径换算 | 名义年利率 `0.12`，每年复利 `12` 次 | 有效年利率约 `0.12682503013196977` | 绝对误差 `< 1e-12` |
| NPV | `[-1000, 300, 400, 500]`，折现率 `0.10` | 约 `-21.0368145` | 绝对误差 `< 1e-6`；首项为 `t=0` |
| NPV 抵消回归 | `[1e16, 1, -1e16]`，折现率 `0` | `1`；基线提交 `8e9cd48` 的结果为 `0` | 此固定输入精确相等；不承诺任意精度 |
| NPV 逐期审计 | 同一现金流与折现率 | 第 0 期现值为 `-1000`；此固定样例的明细普通合计与 NPV 在给定容差内一致 | 聚合差绝对值 `< 1e-12` |
| IRR | `[-100, 110]` | 约 `0.10` | 绝对误差 `< 1e-9`；仅单次符号变化 |
| 等额本息 | 本金 `10000`，每期利率 `0.01`，`12` 期 | 每期约 `888.4878869` | 绝对误差 `< 1e-6` |
| 分位还款计划 | `Money(10000.00 CNY)`，每期利率 `0.01`，`12` 期，half-up | 首期还款 `888.49 CNY`，汇总本金 `10000.00 CNY`，期末余额为零 | 每期整数分守恒；末期结清 |
| 提前还本 | 同一贷款首期额外还本 `100.00 CNY` | 总利息低于无额外还本计划，余额仍精确归零 | 每期金额守恒、摘要校验通过 |
| 无效浮点输入 | NPV 输入包含 `Infinity` | `None` | 必须返回 `None` |

仓库 CI 使用 MoonBit 官方工具链执行以下步骤：

```sh
moon fmt --check
moon check
moon test
moon run bin
moon run examples/use-cases
moon run examples/readme
```

复现时逐项检查六条命令的退出状态；全量测试还应包含跨模块场景。`Money` 的非法币种、币种不一致、越界舍入或整数溢出属于中止契约，不能与返回 `None` 的浮点 API 混为一谈。使用者应在所用提交上复跑命令并核对本页数值；这些固定结果不证明真实业务适用性。