Files

김보곤 dbc34e826d docs: [payroll] 프론트엔드 개발 가이드 추가

- 급여관리 화면 구성 와이어프레임 (목록, 등록/수정 폼, 명세서)
- 계산 미리보기, 법정공제 수동입력 등 구현 유의사항
- 상태별 UI 제어, 에러 처리 가이드
- 월간 워크플로우 안내

2026-03-11 19:47:34 +09:00

14 KiB

Raw Blame History

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

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

1. 개요

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

상세 Request/Response 예시는 API 명세 문서를 참고한다.

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 객체에 담아 전달
지정하지 않은 항목은 자동 계산값 유지

{
  "deduction_overrides": {
    "pension": 175000
  }
}

6.3 수당/공제 드롭다운

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

{
  "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	필드별 에러 메시지	폼 필드 하단에 에러 표시

14 KiB Raw Blame History