njts-accounting-core/docs/payroll_enhancements.md

工资系统增强功能说明

已实现的三大改进

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 - 审批奖金

奖金计算逻辑

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

# 应用社保上限
健康保险 = 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 格式示例

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 - 社保上限设置表

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

2. bonus_payments - 奖金计算表

- 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 - 扶养判定条件表

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

应用数据库变更

# 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. 设置社保上限

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

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. 计算奖金

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. 查询扶养判定规则

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

---

总结

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

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