# 급여관리 (Payroll & Salary)

> **최종 갱신**: 2026-02-27

---

## 1. 개요

두 가지 급여 모델이 병존한다:
- **Payroll**: 급여대장 (기본급, 수당, 공제 상세, 확정/지급 워크플로우)
- **Salary**: 급여관리 React 연동용 (통계, 내보내기, 상태 일괄 변경)

---

## 2. 모델

### Payroll (급여대장)

**주요 필드:** user_id, pay_year, pay_month, base_salary, overtime_pay, bonus, allowances(JSON), gross_salary, income_tax, resident_tax, health_insurance, pension, employment_insurance, deductions(JSON), total_deductions, net_salary, status, confirmed_at, paid_at, withdrawal_id

**상태:** draft → confirmed → paid

### Salary (급여관리)

**주요 필드:** employee_id, year, month, base_salary, total_allowance, total_overtime, total_bonus, total_deduction, net_payment, allowance_details(JSON), deduction_details(JSON), payment_date, status

---

## 3. API 엔드포인트

### 급여대장 (Payrolls)

| HTTP | URI | 설명 |
|------|-----|------|
| GET | `/v1/payrolls` | 급여 목록 |
| POST | `/v1/payrolls` | 급여 생성 |
| GET | `/v1/payrolls/summary` | 급여 요약 |
| POST | `/v1/payrolls/calculate` | 급여 계산 |
| POST | `/v1/payrolls/bulk-confirm` | 일괄 확정 |
| GET | `/v1/payrolls/{id}` | 급여 상세 |
| PUT | `/v1/payrolls/{id}` | 급여 수정 |
| DELETE | `/v1/payrolls/{id}` | 급여 삭제 |
| POST | `/v1/payrolls/{id}/confirm` | 확정 |
| POST | `/v1/payrolls/{id}/pay` | 지급 처리 |
| GET | `/v1/payrolls/{id}/payslip` | 급여명세서 조회 |

### 급여관리 (Salaries)

| HTTP | URI | 설명 |
|------|-----|------|
| GET | `/v1/salaries` | 급여 목록 |
| POST | `/v1/salaries` | 급여 생성 |
| GET | `/v1/salaries/statistics` | 급여 통계 |
| GET | `/v1/salaries/export` | 급여 내보내기 |
| POST | `/v1/salaries/bulk-update-status` | 상태 일괄 변경 |
| GET | `/v1/salaries/{id}` | 급여 상세 |
| PUT | `/v1/salaries/{id}` | 급여 수정 |
| DELETE | `/v1/salaries/{id}` | 급여 삭제 |
| PATCH | `/v1/salaries/{id}/status` | 상태 변경 |

---

## 관련 문서

- [재무관리 개요](README.md)
- Swagger: `/api-docs` → Payrolls / Salaries 섹션