Metadata-Version: 2.4
Name: loankit
Version: 0.1.0
Summary: 贷款还款计划计算器，支持等额本金、等额本息及浮动利率还款方式
Project-URL: Homepage, https://github.com/gdufsh/loankit
Project-URL: Repository, https://github.com/gdufsh/loankit
Project-URL: Issues, https://github.com/gdufsh/loankit/issues
Project-URL: Changelog, https://github.com/gdufsh/loankit/blob/main/CHANGELOG.md
Author-email: gdufsh <gdufsh@gmail.com>
License: MIT License
        
        Copyright (c) 2026 gdufsh
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: calculator,loan,mortgage,repayment,按揭,贷款
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# loankit

[![CI](https://github.com/gdufsh/loankit/actions/workflows/ci.yml/badge.svg)](https://github.com/gdufsh/loankit/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/loankit)](https://pypi.org/project/loankit/)
[![Python](https://img.shields.io/pypi/pyversions/loankit)](https://pypi.org/project/loankit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

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

## 功能

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

## 安装

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

```bash
pipx install loankit
```

### pip（全局或虚拟环境）

```bash
pip install loankit
```

### 从源码安装

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

## 快速上手

```bash
# 等额本息，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`）。

## 开发

```bash
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
