# 工资系统增强功能说明

## 已实现的三大改进

### 1. 扶养人数输入和判定 ✓

#### 功能说明

- **扶养家族管理**: 已有的 `dependents` 表允许录入扶养家族信息
- **自动计算扶养人数**: 系统自动统计有效期内的扶养人数
- **扶养判定规则表**: 新增 `dependent_rules` 表，可配置扶养条件

#### API 端点

- `POST /payroll/employees/{employee_id}/dependents` - 添加扶养家族
- `GET /payroll/employees/{employee_id}/dependents` - 查看扶养家族列表
- `GET /payroll/settings/dependent-rules` - 查看扶养判定规则
- `POST /payroll/settings/dependent-rules` - 设置扶养判定规则

#### 扶养判定条件（可配置）

```
- 所得限度額_一般: 480,000円/年
- 所得限度額_配偶者: 480,000円/年
- 所得限度額_配偶者特別: 1,330,000円/年
- 年齢_特定扶養親族: 19-23歳
- 年齢_老人扶養親族: 70歳以上
```

---

### 2. 奖金计算 + 社保上限设置 ✓

#### 社会保险料上限表 (`insurance_limit_settings`)

可通过画面手动修改的上限值：

| 设定类型                 | 2026 年初始值 | 说明                             |
| ------------------------ | ------------- | -------------------------------- |
| 健康保険標準報酬月額上限 | 1,390,000 円  | 健康保险计算基数上限（第 50 级） |
| 厚生年金標準報酬月額上限 | 650,000 円    | 厚生年金计算基数上限（第 32 级） |
| 通勤手当非課税限度額     | 150,000 円    | 通勤补贴免税上限                 |

#### API 端点

**社保上限管理**:

- `GET /payroll/settings/insurance-limits` - 获取当前社保上限
- `POST /payroll/settings/insurance-limits` - 创建新的上限设置
- `PUT /payroll/settings/insurance-limits/{limit_id}` - 修改上限值

**奖金计算**:

- `POST /payroll/bonus/calculate` - 计算奖金
- `GET /payroll/bonus/` - 获取奖金列表
- `GET /payroll/bonus/{bonus_id}` - 获取奖金详情
- `POST /payroll/bonus/{bonus_id}/approve` - 审批奖金

#### 奖金计算逻辑

```python
总支给额 = 基本奖金 + 业绩奖金 + 其他奖金

# 应用社保上限
健康保险 = min(总支给额, 健康保险上限) × 健康保险率
厚生年金 = min(总支给额, 厚生年金上限) × 厚生年金率
介护保险 = min(总支给额, 健康保险上限) × 介护保险率 (40-64岁)
雇用保险 = 总支给额 × 雇用保险率

# 奖金所得税（特殊算法）
所得税 = (总支给额 - 社保) × 根据前3月平均工资和扶养人数确定的税率

差引支给额 = 总支给额 - 总控除额
```

#### 奖金类型

- 夏季賞与（夏季奖金）
- 冬季賞与（冬季奖金）
- 決算賞与（结算奖金）
- その他（其他）

---

### 3. 源泉徴収税額表上传功能 ✓

#### 功能说明

- **CSV 上传**: 可通过 API 上传源泉徴收税额表的 CSV 文件
- **年份区分**: 每条税率记录有 `valid_from` 和 `valid_to` 字段区分年份
- **自动应用**: 计算工资时自动使用对应年份的税额表

#### API 端点

- `POST /payroll/settings/income-tax/import-csv` - 上传税额表 CSV
- `GET /payroll/settings/income-tax` - 查看当前税额表
- `GET /payroll/settings/income-tax/calculate` - 测试税额计算

#### CSV 格式示例

```csv
monthly_income_from,monthly_income_to,dependents_count,tax_amount,valid_from
0,88000,0,0,2026-01-01
88000,89000,0,130,2026-01-01
89000,90000,0,200,2026-01-01
```

**字段说明**:

- `monthly_income_from`: 月收入下限
- `monthly_income_to`: 月收入上限
- `dependents_count`: 扶养人数 (0, 1, 2, 3...)
- `tax_amount`: 源泉徴収税额
- `valid_from`: 适用开始日期

#### 使用流程

1. 准备 CSV 文件（按国税厅公布的源泉徴収税額表格式）
2. 调用上传 API: `POST /payroll/settings/income-tax/import-csv`
3. 系统自动应用新税额表进行计算

---

## 数据库变更

### 新增表

1. **insurance_limit_settings** - 社保上限设置表

```sql
- limit_id (主键)
- setting_type (设定类型)
- limit_amount (上限金额)
- valid_from/valid_to (有效期)
```

2. **bonus_payments** - 奖金计算表

```sql
- bonus_id (主键)
- employee_id (员工ID)
- bonus_year/bonus_month (年月)
- bonus_type (奖金类型)
- base_bonus/performance_bonus/other_bonus (支给项目)
- health_insurance/care_insurance/pension_insurance... (控除项目)
- total_bonus/total_deduction/net_bonus (合计金额)
```

3. **dependent_rules** - 扶养判定条件表

```sql
- rule_id (主键)
- rule_type (规则类型)
- rule_value (规则值)
- valid_from/valid_to (有效期)
- description (说明)
```

### 应用数据库变更

```bash
# 1. 应用增强功能schema
psql -U your_user -d your_database -f backend/sql/payroll_enhancements.sql

# 2. 验证表是否创建成功
psql -U your_user -d your_database -c "\dt *bonus* *insurance_limit* *dependent_rule*"
```

---

## 计算逻辑改进总结

### 月度工资计算

1. ✅ 应用健康保险上限 (1,390,000 円)
2. ✅ 应用厚生年金上限 (650,000 円)
3. ✅ 应用通勤补贴免税限度 (可配置)
4. ✅ 40-64 岁自动计算介护保险
5. ✅ 自动统计扶养人数用于所得税计算

### 奖金计算

1. ✅ 应用社保上限（与工资计算一致）
2. ✅ 特殊的奖金所得税算法
3. ✅ 支持多种奖金类型
4. ✅ 基于前 3 月平均工资计算税率

---

## 前端 TODO（建议）

需要创建以下管理画面：

1. **社保上限设置画面**

   - 显示当前上限值
   - 允许修改上限金额
   - 查看历史变更记录

2. **扶养判定规则画面**

   - 显示当前判定条件
   - 允许修改所得限度额
   - 配置年龄条件

3. **税额表上传画面**

   - CSV 文件上传组件
   - 预览上传内容
   - 查看当前税额表

4. **奖金计算画面**
   - 选择员工
   - 输入奖金金额
   - 显示计算结果
   - 审批流程

---

## API 测试示例

### 1. 设置社保上限

```bash
curl -X POST http://localhost:18080/payroll/settings/insurance-limits \
  -H "Content-Type: application/json" \
  -d '{
    "setting_type": "健康保険標準報酬月額上限",
    "limit_amount": 1390000,
    "valid_from": "2026-01-01",
    "notes": "2026年度上限"
  }'
```

### 2. 上传税额表 CSV

```bash
curl -X POST http://localhost:18080/payroll/settings/income-tax/import-csv \
  -F "file=@tax_table_2026.csv" \
  -F "valid_from=2026-01-01"
```

### 3. 计算奖金

```bash
curl -X POST http://localhost:18080/payroll/bonus/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": 1,
    "bonus_year": 2026,
    "bonus_month": 6,
    "bonus_type": "夏季賞与",
    "payment_date": "2026-06-30",
    "base_bonus": 500000,
    "performance_bonus": 100000,
    "calculated_by": "admin"
  }'
```

### 4. 查询扶养判定规则

```bash
curl http://localhost:18080/payroll/settings/dependent-rules
```

---

## 总结

✅ **问题 1**: 扶养人数输入和判定 - 已实现，可配置判定条件  
✅ **问题 2**: 奖金计算 + 社保上限 - 已实现，上限可手动修改  
✅ **问题 3**: 税额表上传 - 已实现，支持 CSV 上传和年份区分

所有功能都已实现 API 层，可以通过 RESTful 接口调用。下一步建议创建前端管理画面以便更方便地操作这些功能。