# moonactuary 项目申报书

## 基本信息

- **项目名称：** moonactuary：基于 MoonBit 的中国寿险精算与生命表计算引擎
- **参赛者：** 待填写
- **联系方式：** 待填写
- **GitHub 仓库链接：** https://github.com/hua1104/Moon-actuary
- **项目方向：** MoonBit 通用科学计算基础库 / 金融保险精算工具
- **项目性质：** 原创项目
- **是否为移植项目：** 否

## 1、项目名称

**moonactuary：基于 MoonBit 的中国寿险精算与生命表计算引擎**

## 2、项目简介

moonactuary 是一个使用 MoonBit 原生实现的寿险精算计算库与命令行工具，面向保险精算教学、寿险产品原型验证、生命表研究以及金融计算应用开发。项目内置中国人身保险业经验生命表 CL 2010—2013 的六张标准业务表，支持生命表函数、利息理论、换算函数、寿险与年金现值、净保费及净保费准备金等核心计算。

为了保证计算结果可靠，项目建立了多层交叉校验机制。准备金同时采用前瞻法、后顾法和 Fackler 递推法计算，并逐保单年度比较结果；同时使用寿险精算第一原则恒等式，对六张生命表、多档利率和多个年龄点进行批量验证。

项目提供可复用的 MoonBit API、命令行工具、快速示例、零依赖 SVG 绘图、六表保费对比、CSV 数据导出和自动化验收命令。相同代码可以构建至 wasm、wasm-gc、JavaScript 和 native 后端，便于接入网页应用、教学工具、服务端程序和其他 MoonBit 项目。

## 3、项目方向及通用性说明

### 项目方向

- MoonBit 科学计算与金融计算基础库；
- 寿险精算及生命表计算工具；
- 可嵌入 Web、CLI 和服务端应用的行业计算组件；
- 精算教学、公式验证和自动化回归工具。

### 通用性说明

虽然项目内置的是中国寿险业 CL 2010—2013 经验生命表，但底层计算模块不局限于这六张表。开发者可以通过 `LifeTable::from_qx(...)` 输入其他死亡率序列，构造自定义生命表，并复用生存函数、换算函数、保险现值、年金现值、保费和准备金计算能力。

因此，该项目可以扩展到其他国家或地区的生命表、养老和年金产品、教学模拟生命表、死亡率与利率敏感性分析，以及基于 WebAssembly 的在线精算计算器。项目采用零第三方运行依赖设计，仅使用 MoonBit 标准库，支持 wasm、wasm-gc、JavaScript 和 native 多后端构建。

## 4、预期使用场景

### 场景一：寿险产品净保费与准备金快速测算

产品设计或精算人员可以选择生命表、投保年龄、保险期间、产品类型和预定利率，计算终身寿险、定期寿险或两全保险的趸缴净保费和年缴均衡净保费，并输出逐保单年度准备金。三种准备金方法会并列展示，便于发现公式、参数或实现错误。

```bash
moon run cmd/main premium --table CL1 --product endowment --age 30 --term 20 --rate 2.5
moon run cmd/main reserve --table CL1 --product endowment --age 30 --term 20 --rate 2.5
```

### 场景二：高校精算教学与教材公式验证

教师和学生可以查询 `qx`、`lx`、`dx`、`Lx`、`Tx`、`ex`，观察保险现值、年金现值、换算函数、净保费和准备金之间的关系。`demo` 命令可以在一次运行中展示公开基准数字、第一原则恒等式和三种准备金计算路径，适合课堂演示和实验教学。

```bash
moon run cmd/main demo
```

### 场景三：精算程序的自动化验收与回归测试

维护者可以运行 `verify`，对六张生命表、三档利率和三类产品执行 126 项恒等式校核和 1,134 项准备金比对。只有全部结果处于容差范围内才会输出 `PASS`。该能力已经接入 GitHub Actions，也提供 Windows 和 Linux/macOS 本地验收脚本。

```bash
moon run cmd/main verify
powershell -ExecutionPolicy Bypass -File scripts/acceptance.ps1
bash scripts/acceptance.sh
```

### 场景四：六张经验生命表的敏感性比较与数据导出

研究人员可以在相同年龄、期限、利率和产品假设下，一次比较 CL1—CL6 的保费结果，观察不同业务类别和性别死亡率基础带来的差异。结果既可以直接显示为表格，也可以导出为 CSV，供 Excel、数据分析程序或网页前端继续使用。

```bash
moon run cmd/main compare --product term --age 40 --term 10 --rate 3.5
moon run cmd/main compare --format csv > premiums.csv
```

### 场景五：构建在线生命表和精算计算器

由于项目支持 wasm、wasm-gc 和 JavaScript，开发者可以把核心计算能力接入浏览器应用，实时展示生命表指标、保险现值、净保费、准备金以及死亡率和生存曲线。MoonBit 负责可验证的计算核心，前端负责交互和展示。

## 5、拟实现的核心功能

### 生命表基础能力

- 内置中国人身保险业经验生命表 CL1—CL6；
- 支持自定义 `qx` 死亡率数组构造生命表；
- 计算 `qx`、`px`、`lx`、`dx`、`Lx`、`Tx` 和 `ex`；
- 计算整数年龄和分数年龄的生存、死亡概率；
- 支持 UDD、CFM 和 Balducci 三种分数年龄假设。

### 利息、保险与年金计算

- 年有效利率、贴现率、名义利率和利息力转换；
- 期初、期末、永续、连续、递增及递减年金；
- 终身寿险、定期寿险、两全保险、纯生存保险和递延寿险；
- 递增及递减定期寿险；
- `D`、`C`、`M`、`N`、`R`、`S` 换算函数。

### 保费和准备金

- 趸缴净保费和年缴均衡净保费；
- 终身缴费与限期缴费；
- 前瞻法、后顾法和 Fackler 递推准备金；
- 逐保单年度准备金表和路径偏差比较。

### 命令行、导出和可视化

- `tables`、`table`、`premium`、`compare`、`reserve`、`plot`、`demo`、`verify` 命令；
- 六张经验表统一口径的横向保费比较；
- 表格和 CSV 两种比较结果输出；
- 零依赖 SVG 死亡率及生存人数曲线；
- 对生命表代码、年龄、期间、利率、产品及输出格式进行输入校验。

### 测试与工程交付

- 62 项 MoonBit 测试；
- 教材公开基准、定义式求和和边界输入验证；
- 126 项第一原则恒等式校核；
- 1,134 项准备金路径比对；
- GitHub Actions 多后端检查、构建、测试和冒烟验收；
- Windows 与 Linux/macOS 一键验收脚本。

## 6、原创项目、移植项目或参考已有开源项目说明

本项目属于**原创项目**，不是对现有开源精算库的逐行移植。项目的代码结构、MoonBit API、生命表数据组织方式、换算函数实现、命令行工具、SVG 绘图模块、CSV 导出、自动验收机制和测试体系均使用 MoonBit独立设计和实现。

项目采用寿险精算学中的公开数学理论和行业标准，包括生命表、生存模型、利息理论、寿险与年金现值、等价原则、换算函数、前瞻准备金、后顾准备金和 Fackler 递推公式。这些属于公开的数学方法和行业基础理论，项目没有复制其他开源软件的程序代码。

六张经验生命表的 `qx` 数据来自中国精算师协会公开发布的《中国人身保险业经验生命表（2010—2013）》。本项目对公开数据进行 MoonBit 数据化封装，并在此基础上实现完整计算引擎。

## 7、移植项目参考信息与许可证

本项目**不是移植项目**，因此没有需要继承的参考软件项目许可证。

- **参考内容：** 中国人身保险业经验生命表 CL 2010—2013及公开寿险精算理论；
- **数据发布机构：** 中国精算师协会；
- **项目源代码许可证：** Apache License 2.0；
- **第三方程序代码：** 无；
- **第三方运行依赖：** 无。

## 8、GitHub 仓库链接和有效提交说明

- **GitHub 仓库：** https://github.com/hua1104/Moon-actuary
- **MoonBit 模块名：** `hua1104/moonactuary`
- **项目许可证：** Apache License 2.0

仓库包含完整 MoonBit 源代码、六张经验生命表、公共 API、CLI、快速示例、SVG 绘图、CSV 导出、自动验收命令、测试、GitHub Actions、使用文档及黑客松演示说明。

截至本申报书生成时，本地 Git 历史已包含不少于 10 个具有独立开发意义的有效提交，提交内容依次覆盖模块初始化、利息理论、生命表、保险产品、准备金、SVG 绘图、CLI、测试、自动验收、六表对比、CSV 导出、验收脚本和申报材料。不存在空提交、重复提交或为了满足数量要求而进行的无意义代码拆分。最终提交数量以推送到上述 GitHub 仓库后的公开历史为准。

## 评审快速复现

```bash
moon run cmd/main verify
moon run cmd/main demo
moon run cmd/main compare --product term --age 40 --term 10 --rate 3.5
moon run examples/quickstart
```

成功运行 `verify` 时，程序会输出：

```text
PASS：全部核心精算路径交叉校核通过
```