#Aurum

金额使用整数最小单位，财务指标使用浮点估算。

#维护记录

• 模块基线：以 2026-09-30 的 8e9cd48 为功能比较基线，包含八个公式模块及金额解析/分摊、利率换算、NPV 逐期明细和按最小单位舍入的还款计划。
• 数值稳定性：d621e51 为 NPV 逐期现值求和加入 Neumaier 补偿，附抵消输入回归测试和 CLI 演示。
• 场景与复现：仓库提供金额分摊、现金流估算和还款对账的固定输入场景，以及完整导入示例；输入为设计样例，不代表真实用户反馈或业务效果。

#为什么是 Aurum

#实际问题与使用场景

• 金额分摊：解析 100.00 CNY，按 [1, 2, 3] 分配为 16.67 / 33.33 / 50.00，核对合计。
• 现金流审阅：展示 [-1000, 300, 400, 500] 在每期 10% 折现率下的逐期现值、NPV 和 IRR；另用抵消压力样例说明补偿求和的作用。
• 还款测算：生成 10000.00 CNY、每期 1%、12 期的分位计划，对账并比较首期额外还本 100.00 CNY 的模型结果。

#特性

• 精确金额：按币种最小单位存储；支持严格十进制字符串解析/序列化、显式舍入输入、失败可控运算、整数比例运算和等额/按权重分摊
• 多种舍入策略：半向上（恰好一半时远离零）、银行家舍入、远离零 / 向零截断
• 货币时间价值：现值、终值、年金、永续年金
• 资本预算：补偿求和的 NPV、IRR、回收期、盈利指数
• 贷款摊销：浮点估算计划，以及按币种最小单位逐期舍入、末期结清的等额本息 / 等额本金计划
• 固定资产折旧：直线法、双倍余额递减、年数总和、工作量法
• 债券定价：价格、到期收益率、久期与凸性
• 财务比率：流动性、偿债、盈利、营运与估值指标
• 多币种：12 种币种的代码/小数位元数据与调用方提供汇率的换算

#安装与快速复现

$env:MOONBIT_INSTALL_VERSION = "0.10.16+b1a0e846e"
irm https://cli.moonbitlang.com/install/powershell.ps1 | iex

curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash -s -- '0.10.16+b1a0e846e'

git clone https://github.com/Lyllyl789/aurum.git
cd aurum
git rev-parse HEAD
moon version --all
moon fmt --check
moon check
moon test
moon run bin
moon run examples/use-cases
moon run examples/readme

#测试与兼容说明

moon fmt --check
moon check
moon test
moon test lib/money lib/tvm lib/capital lib/amortize lib/integration
moon test lib/capital

moon check --target js
moon test --target js
moon run --target js bin
moon run --target js examples/use-cases
moon run --target js examples/readme

#目录结构

aurum/
├── lib/                 # 核心库
│   ├── money/           # 精确金额与舍入
│   ├── tvm/             # 货币时间价值
│   ├── capital/         # 资本预算
│   ├── amortize/        # 贷款摊销
│   ├── wear/            # 固定资产折旧
│   ├── bond/            # 债券定价
│   ├── ratio/           # 财务比率
│   └── currency/        # 多币种与汇率
├── bin/                 # 命令行演示
├── examples/
│   ├── readme/          # README 完整导入与运行示例
│   └── use-cases/       # 三个固定输入场景
├── notes/               # 设计笔记
└── moon.mod

#使用与包导入

#仓库内可运行示例

import {
  "Lyllyl789/aurum/lib/money",
  "Lyllyl789/aurum/lib/tvm",
  "Lyllyl789/aurum/lib/capital",
  "Lyllyl789/aurum/lib/amortize",
}

pkgtype(kind: "executable")

///|
fn main {
  let a = @money.Money::of(12345, "CNY")
  let b = @money.Money::of(100, "CNY")
  println("金额合计 CNY = " + a.add(b).to_decimal_string())
  let invoice = match @money.Money::parse("100.00", "CNY") {
    Some(value) => value
    None => abort("invalid invoice")
  }
  let shares = match invoice.allocate_by_weights([1, 2, 3]) {
    Some(value) => value
    None => abort("invalid weights")
  }
  for share in shares {
    println("份额 CNY = " + share.to_decimal_string())
  }
  match @tvm.future_value(10000.0, 0.05, 10) {
    Some(value) => println("终值估算 = " + value.to_string())
    None => abort("invalid TVM input or non-finite result")
  }
  match @capital.net_present_value(0.10, [-1000.0, 300.0, 400.0, 500.0]) {
    Some(value) => println("NPV 估算 = " + value.to_string())
    None => abort("invalid cashflows or non-finite result")
  }
  let rows = match
    @amortize.equal_installment_money_schedule(
      @money.Money::of(1000000, "CNY"),
      0.01,
      12,
      @money.round_half_up(),
    ) {
    Some(value) => value
    None => abort("invalid loan input or overflow")
  }
  let summary = match @amortize.summarize_money_schedule(rows) {
    Some(value) => value
    None => abort("loan reconciliation failed or overflow")
  }
  println("贷款总利息 CNY = " + summary.interest.to_decimal_string())
  println(
    "贷款期末余额 CNY = " + summary.ending_balance.to_decimal_string(),
  )
}

金额合计 CNY = 124.45
份额 CNY = 16.67
份额 CNY = 33.33
份额 CNY = 50.00
终值估算 = 16288.946267774423
NPV 估算 = -21.03681442524436
贷款总利息 CNY = 661.86
贷款期末余额 CNY = 0.00

#从 Mooncakes 使用

moon add Lyllyl789/aurum@0.1.0

import {
  "Lyllyl789/aurum/lib/money",
  "Lyllyl789/aurum/lib/tvm",
  "Lyllyl789/aurum/lib/capital",
  "Lyllyl789/aurum/lib/amortize",
}

pkgtype(kind: "executable")

#货币 API 约定

#TVM API 约定

#资本预算 API 约定

#其余模块的返回边界

#最小单位贷款计划

#进度

• money 精确金额与舍入
• tvm 货币时间价值
• capital 资本预算（NPV / IRR）
• amortize 贷款摊销
• wear 折旧
• bond 债券定价
• ratio 财务比率
• currency 有限币种元数据与外部汇率换算

#设计、验证与贡献记录

• 设计规范：设计笔记 详细记录了各模块实现边界与数值精度策略。
• AI 辅助说明：AI 辅助与人工决策 说明实际 AI 参与范围及项目负责人的决策责任。
• 开发记录：功能变化与验证记录 按阶段概述项目改动、AI 辅助范围和可复现检查。
• 功能对照与数值回归：功能对照与数值回归 记录了项目功能范围、成熟工具功能矩阵对照、差异说明和固定可复现回归值。

#参考来源

• 货币时间价值、债券定价、贷款摊销与固定资产折旧的标准公式，属于通行的财务管理 / 金融数学公式。
• 内部收益率（IRR）与到期收益率（YTM）使用二分法求根；IRR 的单次符号变化检查是本库的保守返回契约，具体搜索区间和失败条件见 API 约定。
• 年金公式以 ln_1p / expm1 替代朴素幂运算，以减少利率接近零时的抵消误差，参考数值计算的通行惯例。

#许可证