financial-calculator

高级金融计算器，具有未来价值表、现值、折扣计算、加价定价和复利。在计算投资增长、定价策略、贷款价值、折扣或比较不同利率和时间段的财务情景时使用。包括 CLI 和交互式 Web UI。

# Financial Calculator

Comprehensive financial calculations including future value, present value, discount/markup pricing, compound interest, and comparative tables.

## Quick Start

### CLI Usage

```bash
# Future Value
python3 scripts/calculate.py fv 10000 0.05 10 12
# PV=$10,000, Rate=5%, Years=10, Monthly compounding

# Present Value
python3 scripts/calculate.py pv 20000 0.05 10 12
# FV=$20,000, Rate=5%, Years=10, Monthly compounding

# Discount
python3 scripts/calculate.py discount 100 20
# Price=$100, Discount=20%

# Markup
python3 scripts/calculate.py markup 100 30
# Cost=$100, Markup=30%

# Future Value Table
python3 scripts/calculate.py fv_table 10000 0.03 0.05 0.07 --periods 1 5 10 20
# Principal=$10,000, Rates=3%,5%,7%, Periods=1,5,10,20 years

# Discount Table
python3 scripts/calculate.py discount_table 100 10 15 20 25 30
# Price=$100, Discounts=10%,15%,20%,25%,30%
```

### Web UI

Launch the interactive calculator:

```bash
./scripts/launch_ui.sh [port]
# Default port: 5050
# Opens at: http://localhost:5050
# Auto-creates venv and installs Flask if needed
```

Or manually:
```bash
cd skills/financial-calculator
python3 -m venv venv  # First time only
venv/bin/pip install flask  # First time only
venv/bin/python scripts/web_ui.py [port]
```

**Features:**
- 7 calculator types with intuitive tabs
- Real-time calculations
- Interactive tables
- Beautiful gradient UI
- Mobile-responsive design

## Calculators

### 1. Future Value (FV)
Calculate what an investment will be worth in the future with compound interest.

**Use cases:**
- Investment growth projections
- Savings account growth
- Retirement planning

**Inputs:**
- Principal amount
- Annual interest rate (%)
- Time period (years)
- Compounding frequency (annual/quarterly/monthly/daily)

### 2. Present Value (PV)
Calculate the current value of a future amount (discounted value).

**Use cases:**
- Loan valuation
- Bond pricing
- Investment analysis

**Inputs:**
- Future value
- Annual discount rate (%)
- Time period (years)
- Compounding frequency

### 3. Discount Calculator
Calculate final price after applying percentage discount.

**Use cases:**
- Retail pricing
- Sale calculations
- Cost savings analysis

**Inputs:**
- Original price
- Discount percentage

**Outputs:**
- Discount amount
- Final price
- Savings percentage

### 4. Markup Calculator
Calculate selling price from cost and markup percentage.

**Use cases:**
- Product pricing
- Profit margin calculation
- Business pricing strategy

**Inputs:**
- Cost price
- Markup percentage

**Outputs:**
- Markup amount
- Selling price
- Profit margin (as % of selling price)

### 5. Compound Interest
Detailed breakdown of compound interest calculations.

**Use cases:**
- Interest analysis
- Effective rate comparison
- Loan interest calculation

**Outputs:**
- Final amount
- Total interest earned
- Effective annual rate

### 6. Future Value Table
Generate comparison table across multiple rates and time periods.

**Use cases:**
- Investment scenario comparison
- Rate shopping
- Long-term planning

**Features:**
- Add multiple interest rates
- Add multiple time periods
- View all combinations in sortable table
- See total gain and gain percentage

### 7. Discount Table
Compare multiple discount percentages for the same price.

**Use cases:**
- Bulk pricing strategies
- Promotional planning
- Price comparison

**Features:**
- Add multiple discount percentages
- See all discount scenarios
- Compare final prices and savings

## Installation

Requires Python 3.7+ and Flask:

```bash
pip install flask
```

Or with venv:

```bash
python3 -m venv venv
source venv/bin/activate
pip install flask
```

## Python API

Import the calculation module:

```python
from calculate import (
    future_value,
    present_value,
    discount_amount,
    markup_price,
    compound_interest,
    generate_fv_table,
    generate_discount_table
)

# Calculate FV
fv = future_value(
    present_value=10000,
    rate=0.05,  # 5% as decimal
    periods=10,
    compound_frequency=12  # Monthly
)

# Generate table
table = generate_fv_table(
    principal=10000,
    rates=[0.03, 0.05, 0.07],  # As decimals
    periods=[1, 5, 10, 20]
)
```

## Formulas

See `references/formulas.md` for detailed mathematical formulas, examples, and use cases for all calculations.

## Tips

**Rate Format:**
- CLI: Use decimals (0.05 for 5%)
- Web UI: Use percentages (5 for 5%)
- Python API: Use decimals (0.05 for 5%)

**Compounding Frequencies:**
- 1 = Annual
- 4 = Quarterly
- 12 = Monthly
- 365 = Daily

**Table Generation:**
Best practices for meaningful comparisons:
- FV tables: Use 3-5 rates, 4-6 time periods
- Discount tables: Use 5-10 discount percentages
- Keep tables focused for easier analysis

**Performance:**
- Web UI calculations are instant
- Tables with >100 combinations may take a few seconds
- CLI is fastest for single calculations

## Common Workflows

### Investment Planning
1. Use **FV Calculator** to project single investment
2. Generate **FV Table** to compare different rates
3. Check **Compound Interest** for detailed breakdown

### Pricing Strategy
1. Use **Markup Calculator** to set selling price
2. Generate **Discount Table** to plan promotions
3. Compare margins and final prices

### Loan Analysis
1. Use **PV Calculator** to value loan
2. Check **Compound Interest** for total interest cost
3. Generate **FV Table** to compare loan terms

---

## 中文说明

# 金融计算器

全面的金融计算，包括未来价值、现值、折扣/加价定价、复利以及对比表格。

## 快速开始

### CLI 用法

```bash
# Future Value
python3 scripts/calculate.py fv 10000 0.05 10 12
# PV=$10,000, Rate=5%, Years=10, Monthly compounding

# Present Value
python3 scripts/calculate.py pv 20000 0.05 10 12
# FV=$20,000, Rate=5%, Years=10, Monthly compounding

# Discount
python3 scripts/calculate.py discount 100 20
# Price=$100, Discount=20%

# Markup
python3 scripts/calculate.py markup 100 30
# Cost=$100, Markup=30%

# Future Value Table
python3 scripts/calculate.py fv_table 10000 0.03 0.05 0.07 --periods 1 5 10 20
# Principal=$10,000, Rates=3%,5%,7%, Periods=1,5,10,20 years

# Discount Table
python3 scripts/calculate.py discount_table 100 10 15 20 25 30
# Price=$100, Discounts=10%,15%,20%,25%,30%
```

### Web UI

启动交互式计算器：

```bash
./scripts/launch_ui.sh [port]
# Default port: 5050
# Opens at: http://localhost:5050
# Auto-creates venv and installs Flask if needed
```

或手动启动：
```bash
cd skills/financial-calculator
python3 -m venv venv  # First time only
venv/bin/pip install flask  # First time only
venv/bin/python scripts/web_ui.py [port]
```

**特性：**
- 7 种计算器类型，配有直观的标签页
- 实时计算
- 交互式表格
- 精美的渐变 UI
- 移动端自适应设计

## 计算器

### 1. 未来价值（FV）
计算一项投资在复利作用下未来的价值。

**使用场景：**
- 投资增长预测
- 储蓄账户增长
- 退休规划

**输入：**
- 本金金额
- 年利率（%）
- 时间周期（年）
- 复利频率（年度/季度/月度/每日）

### 2. 现值（PV）
计算一笔未来金额的当前价值（折现价值）。

**使用场景：**
- 贷款估值
- 债券定价
- 投资分析

**输入：**
- 未来价值
- 年折现率（%）
- 时间周期（年）
- 复利频率

### 3. 折扣计算器
计算应用百分比折扣后的最终价格。

**使用场景：**
- 零售定价
- 促销计算
- 成本节省分析

**输入：**
- 原始价格
- 折扣百分比

**输出：**
- 折扣金额
- 最终价格
- 节省百分比

### 4. 加价计算器
根据成本和加价百分比计算销售价格。

**使用场景：**
- 产品定价
- 利润率计算
- 企业定价策略

**输入：**
- 成本价
- 加价百分比

**输出：**
- 加价金额
- 销售价格
- 利润率（占销售价格的百分比）

### 5. 复利
复利计算的详细分解。

**使用场景：**
- 利息分析
- 实际利率比较
- 贷款利息计算

**输出：**
- 最终金额
- 累计利息收益
- 实际年利率

### 6. 未来价值表
生成跨多个利率和时间周期的对比表。

**使用场景：**
- 投资情景对比
- 利率比选
- 长期规划

**特性：**
- 添加多个利率
- 添加多个时间周期
- 在可排序表格中查看所有组合
- 查看总收益和收益百分比

### 7. 折扣表
对比同一价格的多个折扣百分比。

**使用场景：**
- 批量定价策略
- 促销规划
- 价格对比

**特性：**
- 添加多个折扣百分比
- 查看所有折扣情景
- 对比最终价格和节省金额

## 安装

需要 Python 3.7+ 和 Flask：

```bash
pip install flask
```

或使用 venv：

```bash
python3 -m venv venv
source venv/bin/activate
pip install flask
```

## Python API

导入计算模块：

```python
from calculate import (
    future_value,
    present_value,
    discount_amount,
    markup_price,
    compound_interest,
    generate_fv_table,
    generate_discount_table
)

# Calculate FV
fv = future_value(
    present_value=10000,
    rate=0.05,  # 5% as decimal
    periods=10,
    compound_frequency=12  # Monthly
)

# Generate table
table = generate_fv_table(
    principal=