SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: [payroll] 프론트엔드 개발 가이드 추가

Browse Source 
- 급여관리 화면 구성 와이어프레임 (목록, 등록/수정 폼, 명세서)
- 계산 미리보기, 법정공제 수동입력 등 구현 유의사항
- 상태별 UI 제어, 에러 처리 가이드
- 월간 워크플로우 안내
This commit is contained in:
김보곤
2026-03-11 19:47:34 +09:00
parent 764ef9f82a
commit dbc34e826d
2 changed files with 283 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
INDEX.md
View File

@@ -212,6 +212,12 @@ DB 도메인별:
| [document-api-integration.md](frontend/api-specs/document-api-integration.md) | 문서 API 연동 명세 |
| [payroll-api.md](frontend/api-specs/payroll-api.md) | 급여관리 API 전체 명세 (18개 엔드포인트) |
### frontend/integration/ — 프론트엔드 개발 가이드
| 문서 | 설명 |
|------|------|
| [payroll-guide.md](frontend/integration/payroll-guide.md) | 급여관리 프론트엔드 개발 가이드 (화면 구성, 구현 유의사항) |
---
### 서브프로젝트 문서

277
frontend/integration/payroll-guide.md Normal file
View File

@@ -0,0 +1,277 @@
# 급여관리 프론트엔드 개발 가이드
> **작성일**: 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