給与管理システム新規作成
This commit is contained in:
admin
274
docs/payroll_enhancements.md
Normal file
274
docs/payroll_enhancements.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# 工资系统增强功能说明
|
||||
|
||||
## 已实现的三大改进
|
||||
|
||||
### 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 接口调用。下一步建议创建前端管理画面以便更方便地操作这些功能。
|
||||
Reference in New Issue
Block a user