loankit 0.1.0

贷款还款计划计算器，支持等额本金、等额本息及浮动利率还款方式

loankit

贷款还款计划计算器，支持等额本金、等额本息，以及香港 H/P 利率联动场景下的浮动利率等额本息。

功能

• 等额本金 / 等额本息还款计划生成
• 两种方式并排对比，含逐期明细与利息节省比例
• 浮动利率等额本息：--rate-changes 按区间指定利率，区间外自动回退至封顶利率
• 浮动利率对比：--compare --rate-changes 同时输出封顶利率基准方案与实际方案的利息差
• 逐期明细含剩余本金列，方便核对银行账单
• Rich 彩色终端输出；--no-color 适合重定向到文件或管道

安装

推荐：pipx（隔离安装，全局可用）

pipx install loankit

pip（全局或虚拟环境）

pip install loankit

从源码安装

git clone https://github.com/gdufsh/loankit.git
cd loan
pip install .

快速上手

# 等额本息，100 万，年利率 3.25%，30 年
loan -p 1000000 -r 3.25 -m 360

# 等额本金
loan -p 1000000 -r 3.25 -m 360 -M equal-principal

# 两种方式对比（含逐期明细）
loan -p 1000000 -r 3.25 -m 360 --compare --compare-detail

# 浮动利率：前 24 期优惠利率 2.5%，之后回落至封顶利率 3.25%
loan -p 1000000 -r 3.25 -m 360 --rate-changes 1:24:2.5

# 浮动利率对比：封顶基准 vs 实际浮动方案
loan -p 1000000 -r 3.25 -m 360 --rate-changes 1:24:2.5 --compare

参数说明

参数	简写	说明
--principal	-p	贷款本金（元），如 1000000
--annual-rate	-r	年利率（百分比），如 3.25；浮动模式下为封顶利率
--months	-m	还款期数（月），如 360
--method	-M	还款方式：equal-installment（默认）、equal-principal；--compare 时忽略
--compare	-c	对比模式；与 --rate-changes 合用时输出浮动利率对比
--compare-detail	-d	对比模式下附加逐期明细（需配合 --compare）
--rate-changes		浮动利率区间，格式 x:y:rc[,x:y:rc,...]，rc 不可超过 -r，区间不可重叠
--no-color	-n	禁用彩色输出（纯文本）
--version	-v	显示版本号

示例输出

等额本息（12 期）

还款计划 — 等额本息 | 本金 ¥1,000,000.00 | 年利率 3.25% | 期限 12 期
--------------------------------------------------------------------------------
  期数            月供           还本金           还利息            剩余本金
--------------------------------------------------------------------------------
     1     84,807.62     82,099.29      2,708.33      917,900.71
     2     84,807.62     82,321.64      2,485.98      835,579.07
   ...
    12     84,807.63     84,578.56        229.07            0.00
--------------------------------------------------------------------------------
  总还款额:   ¥  1,017,691.45
  总利息:     ¥     17,691.45
  首期月供:   ¥     84,807.62
  末期月供:   ¥     84,807.63

浮动利率（前 6 期 2.5%，后 6 期 3.25%）

还款计划 — 浮动利率等额本息 | 本金 ¥1,000,000.00 | 封顶利率 3.25% | 期限 12 期
--------------------------------------------------------------------------------------------
  期数            月供           还本金           还利息            剩余本金     年利率
--------------------------------------------------------------------------------------------
     1     84,466.11     82,382.78      2,083.33      917,617.22     2.5%
   ...
     7     84,650.27     83,287.65      1,362.62      419,834.06    3.25%  <- 利率变更
   ...
    12     84,650.28     84,421.64        228.64            0.00
--------------------------------------------------------------------------------------------
  总还款额:   ¥  1,014,698.29
  总利息:     ¥     14,698.29

两种方式对比

还款方式对比 | 本金 ¥1,000,000.00 | 年利率 3.25% | 期限 12 期
================================================================================
指标                        等额本金          等额本息     差异(EI-EP)
--------------------------------------------------------------------------------
首月月供(元)              86,041.66     84,807.62     -1,234.04
末月月供(元)              83,559.06     84,807.63      1,248.57
月均月供(元)              84,800.35     84,807.62          7.27
总还款额(元)           1,017,604.16  1,017,691.45         87.29
总利息(元)               17,604.16     17,691.45         87.29
利息节省比例                   0.49%            基准             —
================================================================================

算法说明

• 等额本金：每月还款本金固定，利息随剩余本金递减。
• 等额本息：按 PMT 公式一次性计算固定月供，末期本金取剩余余额以消除舍入误差。
• 浮动利率等额本息：每期按当期利率与剩余期数重新计算 PMT，期数固定不延长，末期同样取剩余余额归零。
• 所有金额使用 decimal.Decimal 精确计算，舍入至分（ROUND_HALF_UP）。

开发

git clone https://github.com/gdufsh/loankit.git
cd loan
pip install -e ".[dev]"

# 运行测试
pytest

# 代码检查
ruff check src/ tests/
ruff format src/ tests/

License

MIT