# 급여관리 프론트엔드 개발 가이드

> **작성일**: 2026-03-11
> **상태**: API 개발 완료 (개발서버 배포됨)
> **대상**: 프론트엔드 개발자
> **API 명세**: [payroll-api.md](../api-specs/payroll-api.md)

---

## 1. 개요

급여관리 API가 개발 완료되어 개발 서버(`api.dev.codebridge-x.com`)에 배포되었다.
이 문서는 프론트엔드 개발 시 필요한 핵심 정보를 요약한다.

상세 Request/Response 예시는 [API 명세 문서](../api-specs/payroll-api.md)를 참고한다.

---

## 2. 주요 기능

| # | 기능 | 설명 |
|---|------|------|
| 1 | 급여 CRUD | 사원별 월급여 등록/조회/수정/삭제 |
| 2 | 자동 계산 엔진 | 4대보험 + 근로소득세 + 지방소득세 자동 계산 |
| 3 | 상태 관리 | draft → confirmed → paid 3단계 흐름 |
| 4 | 일괄 처리 | 재직사원 일괄 생성, 전월 복사, 일괄 계산, 일괄 확정 |
| 5 | 계산 미리보기 | 저장 없이 실시간 계산 결과 확인 (폼 입력 시 활용) |
| 6 | 급여명세서 | 인쇄용 명세서 데이터 조회 |
| 7 | 설정 관리 | 보험 요율, 수당/공제 유형 테넌트별 설정 |

---

## 3. 엔드포인트 요약 (18개)

| # | Method | Path | 설명 |
|---|--------|------|------|
| 1 | GET | `/api/v1/payrolls` | 급여 목록 (페이지네이션) |
| 2 | POST | `/api/v1/payrolls` | 급여 등록 |
| 3 | GET | `/api/v1/payrolls/summary` | 월간 요약 통계 |
| 4 | POST | `/api/v1/payrolls/calculate` | 급여 일괄 계산 (draft 재계산) |
| 5 | POST | `/api/v1/payrolls/calculate-preview` | 계산 미리보기 (저장 안 함) |
| 6 | POST | `/api/v1/payrolls/bulk-confirm` | 일괄 확정 |
| 7 | POST | `/api/v1/payrolls/bulk-generate` | 재직사원 일괄 생성 |
| 8 | POST | `/api/v1/payrolls/copy-from-previous` | 전월 급여 복사 |
| 9 | GET | `/api/v1/payrolls/{id}` | 급여 상세 |
| 10 | PUT | `/api/v1/payrolls/{id}` | 급여 수정 |
| 11 | DELETE | `/api/v1/payrolls/{id}` | 급여 삭제 |
| 12 | POST | `/api/v1/payrolls/{id}/confirm` | 확정 |
| 13 | POST | `/api/v1/payrolls/{id}/unconfirm` | 확정 취소 |
| 14 | POST | `/api/v1/payrolls/{id}/pay` | 지급 처리 |
| 15 | POST | `/api/v1/payrolls/{id}/unpay` | 지급 취소 (슈퍼관리자) |
| 16 | GET | `/api/v1/payrolls/{id}/payslip` | 급여명세서 조회 |
| 17 | GET | `/api/v1/payrolls/settings` | 급여 설정 조회 |
| 18 | PUT | `/api/v1/payrolls/settings` | 급여 설정 수정 |

---

## 4. 상태 흐름

```
draft(작성중) ──[확정]──→ confirmed(확정) ──[지급]──→ paid(지급완료)
      ▲                       │                          │
      └───[확정취소]───────────┘                          │
      └───[지급취소*]────────────────────────────────────┘

* 지급취소는 슈퍼관리자 전용 (paid → draft로 초기화)
```

### 4.1 상태별 배지 색상

| 상태 | 값 | 배지 색상 | 의미 |
|------|---|----------|------|
| 작성중 | `draft` | gray | 수정/삭제/확정 가능 |
| 확정 | `confirmed` | blue | 확정취소/지급 가능 |
| 지급완료 | `paid` | green | 상세보기만 가능 |

### 4.2 상태별 가능한 작업

| 상태 | 일반 사용자 | 슈퍼관리자 |
|------|-----------|-----------|
| `draft` | 수정, 삭제, 확정, 일괄계산 | 동일 |
| `confirmed` | 확정취소, 지급처리 | + **수정** |
| `paid` | 상세보기만 | + **수정**, **지급취소** |

> 슈퍼관리자 수정 시 `_is_super_admin: true`를 Request Body에 전달한다.

---

## 5. 화면 구성 안내

### 5.1 급여 목록 화면

```
┌─────────────────────────────────────────────────────┐
│ 급여관리                            [2026년 03월 ▼] │
├─────────────────────────────────────────────────────┤
│                                                     │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐│
│ │ 총 인원   │ │ 총 지급액 │ │ 총 공제액 │ │ 실수령액 ││
│ │    15명   │ │ 62,500천원│ │ 15,800천원│ │46,700천원││
│ └──────────┘ └──────────┘ └──────────┘ └─────────┘│
│                                                     │
│ [일괄생성] [전월복사] [일괄계산] [일괄확정] [+ 등록] │
│                                                     │
│ ┌───┬──────┬──────┬──────┬──────┬──────┬────┬────┐│
│ │ # │ 사원  │ 기본급│총지급액│총공제액│실수령액│상태 │ 작업││
│ ├───┼──────┼──────┼──────┼──────┼──────┼────┼────┤│
│ │ 1 │홍길동│ 350만│ 410만│ 98만 │ 312만│작성│ ⋮  ││
│ │ 2 │김철수│ 300만│ 350만│ 85만 │ 265만│확정│ ⋮  ││
│ └───┴──────┴──────┴──────┴──────┴──────┴────┴────┘│
└─────────────────────────────────────────────────────┘
```

- 연월 선택 → `year` + `month` 필터로 목록 조회
- 요약 카드 → `GET /payrolls/summary` API 활용
- 상태별 필터링 → `status` 파라미터
- 부서별 필터링 → `department_id` 파라미터
- 사원 검색 → `search` 파라미터

### 5.2 급여 등록/수정 폼

```
┌─────────────────────────────────────────────────────┐
│ 급여 등록                                           │
├─────────────────────────────────────────────────────┤
│ 사원: [홍길동 ▼]  연도: [2026]  월: [3 ▼]          │
│                                                     │
│ ── 지급 항목 ──────────────────────────────────── │
│ 기본급:         [  3,500,000 ]                      │
│ 연장근로수당:    [          0 ]                      │
│ 식대(비과세):   [    200,000 ]                      │
│ 수당:                                               │
│   직책수당      [    300,000 ] [삭제]               │
│   교통비        [    100,000 ] [삭제]               │
│   [+ 수당 추가]                                     │
│ ────────────────────────── 총 지급액: 4,100,000    │
│                                                     │
│ ── 공제 항목 (자동 계산) ────────────────────────  │
│ 근로소득세:     [    117,750 ] ← 자동 (수정 가능)   │
│ 지방소득세:     [     11,770 ] ← 자동 (수정 가능)   │
│ 건강보험:       [    138,220 ] ← 자동 (수정 가능)   │
│ 장기요양보험:   [      1,250 ] ← 자동 (수정 가능)   │
│ 국민연금:       [    175,500 ] ← 자동 (수정 가능)   │
│ 고용보험:       [     35,100 ] ← 자동 (수정 가능)   │
│ 기타 공제:                                          │
│   대출상환      [    500,000 ] [삭제]               │
│   [+ 기타 공제 추가]                                │
│ ────────────────────────── 총 공제액:   979,590    │
│                                                     │
│ ═════════════════════════ 실수령액:  3,120,410    │
│                                                     │
│ 메모: [                    ]                        │
│                                                     │
│                            [취소]  [미리보기]  [저장]│
└─────────────────────────────────────────────────────┘
```

### 5.3 급여명세서 (인쇄용)

```
┌─────────────────────────────────────────────┐
│              급 여 명 세 서                  │
│                                             │
│ 사원명: 홍길동     귀속기간: 2026년 03월    │
│                                             │
│ ┌──── 지급 내역 ────┬── 공제 내역 ────┐    │
│ │ 기본급    3,500,000│ 소득세    117,750│    │
│ │ 식대       200,000│ 지방소득세 11,770│    │
│ │ 직책수당    300,000│ 건강보험  138,220│    │
│ │ 교통비     100,000│ 장기요양    1,250│    │
│ │                   │ 국민연금  175,500│    │
│ │                   │ 고용보험   35,100│    │
│ │                   │ 대출상환  500,000│    │
│ ├───────────────────┼─────────────────┤    │
│ │ 지급합계 4,100,000│ 공제합계 979,590│    │
│ └───────────────────┴─────────────────┘    │
│                                             │
│         실수령액: 3,120,410원               │
└─────────────────────────────────────────────┘
```

- `GET /payrolls/{id}/payslip` 응답의 `earnings`/`deductions` 구조 활용
- 인쇄 레이아웃은 A4 세로 기준 권장

---

## 6. 구현 시 유의사항

### 6.1 계산 미리보기 (핵심)

급여 등록/수정 폼에서 지급 항목 변경 시 `POST /calculate-preview` API를 호출하여 공제 항목을 실시간 갱신한다.

```
사용자가 기본급 변경 → debounce 300ms → calculate-preview 호출 → 공제 항목 자동 갱신
```

- `user_id`를 전달하면 해당 사원의 가족수를 자동 반영
- `user_id` 미전달 시 가족수 1로 계산

### 6.2 법정 공제 수동 입력

- 법정 공제 필드(소득세, 4대보험)는 기본 readonly
- "수정" 토글로 수동 입력 허용
- 수동 변경한 항목만 `deduction_overrides` 객체에 담아 전달
- 지정하지 않은 항목은 자동 계산값 유지

```json
{
  "deduction_overrides": {
    "pension": 175000
  }
}
```

### 6.3 수당/공제 드롭다운

`GET /payrolls/settings` 응답의 `allowance_types`와 `deduction_types`를 사용하여 드롭다운 목록을 구성한다.

```json
{
  "allowance_types": [
    {"code": "meal", "name": "식대", "is_taxable": false},
    {"code": "position", "name": "직책수당", "is_taxable": true}
  ],
  "deduction_types": [
    {"code": "loan", "name": "대출상환"},
    {"code": "union", "name": "조합비"}
  ]
}
```

### 6.4 금액 표시 규칙

- 모든 금액은 **원(KRW)** 단위 정수
- 천 단위 콤마 필수: `3,500,000`
- 음수 금액(환급): 빨간색 + `-` 부호

---

## 7. 월간 워크플로우

프론트엔드 UI에서 안내할 급여 처리 순서:

```
1. 월초 → [일괄생성] 또는 [전월복사] 실행
2. 개별 급여 데이터 확인/수정
3. [일괄계산] 실행 (공제 항목 최신 요율로 재계산)
4. 데이터 확인 완료 → [일괄확정]
5. 급여 지급일 → 개별 [지급처리] (출금과 연결)
6. 급여명세서 조회/인쇄
```

---

## 8. 에러 처리

주요 에러 메시지와 프론트엔드 대응:

| 에러 상황 | HTTP 코드 | 메시지 | 프론트엔드 대응 |
|----------|----------|--------|----------------|
| 동일 연월+사원 중복 | 400 | 해당 연월에 이미 급여가 등록되어 있습니다. | 토스트 경고 |
| draft 외 수정 시도 | 400 | 작성중 상태의 급여만 수정할 수 있습니다. | 버튼 비활성화로 사전 방지 |
| draft 외 삭제 시도 | 400 | 작성중 상태의 급여만 삭제할 수 있습니다. | 버튼 숨김으로 사전 방지 |
| 전월 데이터 없음 | 400 | 전월 급여 데이터가 없습니다. | 토스트 안내 + 일괄생성 유도 |
| 검증 실패 | 422 | 필드별 에러 메시지 | 폼 필드 하단에 에러 표시 |

---

## 관련 문서

- [급여관리 API 전체 명세](../api-specs/payroll-api.md) — 18개 엔드포인트 상세 Request/Response
- [급여관리 기능 상세](../../features/finance/payroll.md) — 전표 변환, 권한, 멀티테넌트
- [결재관리 API 명세](../api-specs/approval-api.md) — 참고용 (유사 구조)

---

**최종 업데이트**: 2026-03-11