From dbc34e826deaa9a0ce8bea58dd0785ab08f2e0be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Wed, 11 Mar 2026 19:47:34 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[payroll]=20=ED=94=84=EB=A1=A0=ED=8A=B8?= =?UTF-8?q?=EC=97=94=EB=93=9C=20=EA=B0=9C=EB=B0=9C=20=EA=B0=80=EC=9D=B4?= =?UTF-8?q?=EB=93=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 급여관리 화면 구성 와이어프레임 (목록, 등록/수정 폼, 명세서) - 계산 미리보기, 법정공제 수동입력 등 구현 유의사항 - 상태별 UI 제어, 에러 처리 가이드 - 월간 워크플로우 안내 --- INDEX.md | 6 + frontend/integration/payroll-guide.md | 277 ++++++++++++++++++++++++++ 2 files changed, 283 insertions(+) create mode 100644 frontend/integration/payroll-guide.md diff --git a/INDEX.md b/INDEX.md index b56fc5d..87b1258 100644 --- a/INDEX.md +++ b/INDEX.md @@ -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) | 급여관리 프론트엔드 개발 가이드 (화면 구성, 구현 유의사항) | + --- ### 서브프로젝트 문서 diff --git a/frontend/integration/payroll-guide.md b/frontend/integration/payroll-guide.md new file mode 100644 index 0000000..08d502a --- /dev/null +++ b/frontend/integration/payroll-guide.md @@ -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