# 实际问题与完整使用场景

> 以下用户角色、业务输入和流程均为**设计场景 / 待验证**，数值取自仓库已有固定回归样例，不是访谈、客户账单、真实贷款或市场数据。程序运行只能验证计算行为，不能证明用户需求、采用情况或业务收益。

固定结果的月份归属和验证方式见[功能范围与维护记录](maintenance-history.md)。串联示例对 NPV、拒绝输入、贷款本金与结清、固定利息差作失败检查；不满足时退出非零，但程序通过仍不能证明真实业务需求。

## 项目要解决的具体问题

Aurum 面向在 MoonBit 中接入基础财务计算的开发者。当前可以从源码和回归测试确认的工程问题有：

- **文本金额和分摊需要明确的精度规则**：外部十进制文本如何转成整数分、无法整除的尾差给谁、各份相加是否等于原金额。`money` 提供严格解析、最大余数分配和同币种求和，调用方无需在每个示例里重新实现这些规则。
- **现金流估算需要明确时间点和失败语义**：首项是否位于 `t=0`、各期贡献是什么、多次变号是否能报告唯一 IRR；量级悬殊的正负项还可能导致普通浮点累加丢失小额项。`capital` 提供逐期明细、保守的 IRR 返回规则和补偿 NPV 合计。
- **浮点月供不能直接当作逐期分位账目**：利息舍入、末期调整与额外还本会影响本金和余额。`amortize` 提供最小单位计划与摘要校验，可核对每期还款、本金、利息和最终余额。

这些是本仓库实现所针对的问题，不等于已经证明某类人群频繁遇到这些问题。目标用户优先级、现有工作方式和实际影响仍须维护者提供真实证据。

## 运行入口与证据层级

在仓库根目录、安装 MoonBit 工具链后执行：

```sh
moon run examples/use-cases
moon test lib/money lib/capital lib/amortize lib/integration
```

[完整演示源码](../examples/use-cases/main.mbt) 串联以下三个流程并打印结果及拒绝输入示例，输入写在源码中；修改输入后可以复跑。它是固定输入的开发者示例，不提供表单、文件导入、数据持久化或用户产品界面。示例中的 `abort` 只用于提示预设的合法输入意外失败，应用接入时须自行处理 `None`。

以下场景使用固定输入演示功能；它们能复现代码行为，但不代表真实用户案例或已验证的业务效果。当前实现提供金额分摊、现金流明细与分位贷款计划；`d621e51` 为 NPV 合计加入补偿求和。场景材料和串联演示用于说明已有 API 的组合方式，不更改公式范围。

## 场景一：将一笔金额按约定权重分摊并对账

**用户（设计角色）**：为费用工具接入金额计算的 MoonBit 开发者；实际需求方及权重来源待验证。

**输入**：同一币种 `CNY`，十进制金额文本 `100.00`，三份权重 `[1, 2, 3]`。假设权重已由业务方确认，份额顺序即余数并列时的优先顺序。

**步骤**：

1. 调用 `Money::parse("100.00", "CNY")`，处理 `None`；严格解析不静默舍入超精度输入。
2. 调用 `allocate_by_weights([1, 2, 3])`，按最大余数法分配整数分；处理无效权重的 `None`。
3. 用 `Money::sum` 将三份加回原金额，核对币种及整数最小单位。
4. 用 `to_decimal_string()` 输出无千分位的固定精度文本，供上层保存或展示；示例只打印，不执行保存。

**输出（固定回归值）**：三份分别为 `16.67`、`33.33`、`50.00 CNY`，合计为 `100.00 CNY`。`100.001 CNY` 严格解析为 `None`，全零权重分摊为 `None`，拒绝结果也由示例打印。

**价值（待验证）**：提供可复用的分位守恒和确定性尾差规则，便于解释份额结果。尚无证据证明它缩短了开发时间或减少了真实账单错误。

**功能证据与边界**：[money 实现](../lib/money/money.mbt)、[金额解析/权重/守恒测试](../lib/money/money_test.mbt)、[跨模块回归](../lib/integration/integration.mbt)。金额受 32 位最小单位范围限制；不跨币种分摊，不决定权重公平性，不生成真实付款。

## 场景二：审阅等间隔现金流的净现值和逐期贡献

**用户（设计角色）**：制作现金流教学或方案测算原型的 MoonBit 开发者；没有已确认的真实投资使用者。

**输入**：等间隔现金流 `[-1000, 300, 400, 500]`，每期折现率 `0.10`，统一金额口径。负号表示流出，正号表示流入；首项为第 0 期，后续为第 1～3 期，单位由调用方约定。

**步骤**：

1. 业务方先确认期长、符号和折现率口径；示例用固定数组调用 `discounted_cash_flow_schedule`。
2. 展示每行期号、现金流和现值，核对第 0 期不折现。
3. 调用 `net_present_value` 得到合计，调用 `internal_rate_of_return` 得到该单次变号样例的估算 IRR；均处理 `None`。
4. 单独运行 `[1e16, 1, -1e16]`、折现率 `0` 的**数值压力样例**，检查 NPV 为 `1`；这不是实际业务金额。
5. 运行多次变号 `[-100, 230, -132]`，展示唯一 IRR 返回 `None`，避免把无法报告的结果填成零。

**输出（固定回归值）**：逐期现值约为 `-1000`、`272.727273`、`330.578512`、`375.657400`；NPV 约为 `-21.03681442524436`，IRR 约为 `0.088963395`。在设定口径下净现值为负，程序提供估算结果供解释，不自动做投资决策。抵消压力样例 NPV 为 `1`，多次变号样例唯一 IRR 为 `None`。

**价值（待验证）**：让使用者检查各期折现贡献和失败条件，补偿求和可减少特定抵消输入中的小额项丢失。没有真实项目收益、决策改善或性能优势的验证。

**功能证据与边界**：[capital 实现](../lib/capital/capital.mbt)、[NPV 抵消/明细/IRR 测试](../lib/capital/capital_test.mbt)。使用 `Double` 估算，补偿求和不使每项折现变成精确十进制；普通累加明细在压力输入下可能与补偿合计不同。仅等间隔现金流，无日期日历、市场折现率来源或风险模型；`None` 也可能来自非法输入、无根或数值失败。

## 场景三：生成按分舍入的还款计划并比较额外还本

**用户（设计角色）**：为贷款教学或还款测算原型接入计划计算的 MoonBit 开发者；实际借款人及合同适用性待验证。

**输入**：本金文本 `10000.00 CNY`，每期利率 `0.01`，`12` 期，`round_half_up()`。对照计划为首期额外还本 `100.00 CNY`，后续额外还本为零。月度场景假设每期为一个月，`0.01` 表示月利率 1%，不是年利率或合同 APR。

**步骤**：

1. 严格解析本金，调用 `equal_installment_money_schedule` 生成基准计划，处理 `None`。
2. 展示每期还款、本金、利息和余额；利息逐期按分舍入，最后一个非零还款调整为结清余额。
3. 用 `summarize_money_schedule` 对账，核对期号、币种、每期还款等于本金加利息及余额衔接。
4. 调用 `equal_installment_money_schedule_with_extra_principal`，传入 `[100.00 CNY]`；再次汇总，比较总利息与期末余额。
5. 传入零期数展示 `None`，提醒调用方先确定输入口径再解释失败。

**输出（固定回归值）**：基准首期还款 `888.49`、本金 `788.49`、利息 `100.00 CNY`；共 12 行，末期还款 `888.47 CNY`，汇总本金 `10000.00 CNY`、总利息 `661.86 CNY`、期末余额 `0.00 CNY`。额外还本计划首期还款 `988.49`、本金 `888.49`、利息仍为 `100.00 CNY`；该固定输入总利息为 `650.29 CNY`，比基准低 `11.57 CNY`，汇总本金仍为 `10000.00 CNY`、余额仍为零。最后一期可能调整，不能将首期还款直接乘 12 代替对账。

**价值（待验证）**：提供可核对的分位计划，帮助上层解释舍入和额外还本影响。此处“总利息较低”是固定模型输入的计算关系，不是真实贷款节省收益。

**功能证据与边界**：[amortize 实现](../lib/amortize/amortize.mbt)、[逐期守恒/提前还本测试](../lib/amortize/amortize_test.mbt)、[跨模块回归](../lib/integration/integration.mbt)。不包含费用、罚息、提前还款限制、日期或合同条款；正本金、非负每期利率、正期数及金额范围必须满足实现契约。提前结清后的剩余请求期次保留零行，12 行不一定表示 12 次非零付款。

## 证据边界

本文场景使用合成输入，说明当前函数可以如何组合；没有真实用户访谈、客户数据或试用结果，因此不声称已经落地，也不声称带来效率或收益提升。若将场景用于具体业务，调用方需先确认数据、利率周期、舍入规则和合同条件。

示例执行结果由仓库 CI 按当前提交验证；本地复现命令见 README。测试和示例仅验证程序行为，不代表真实用户价值。