Files

hskwon aa696ff3c8 docs: 급여 관리 API 완료 내용 업데이트

- Phase 2 상태: 2/3 완료 (전자결재 + 급여관리)
- 3.2 급여 관리 섹션 완료 체크
- 2025-12-18 작업 일지 추가

2025-12-18 10:56:16 +09:00

19 KiB

Raw Blame History

SAM ERP API 개발 작업 계획

작성일: 2025-12-17 기준 문서: SAM_ERP_Storyboard_D0.8_251216 상태: ✅ Phase 1 완료 | 🟢 Phase 2 진행중 (2/3 완료: 전자결재 + 급여관리)

📚 참고 문서

핵심 참고 문서

문서	경로	용도
ERP API 명세서	`docs/specs/erp-analysis/99-gap-analysis.md`	전체 개발 범위, 테이블 스키마, API 엔드포인트
스토리보드 원본	`docs/plans/SAM_ERP_Storyboard_D0.8_251216/`	UI/UX 참조, 화면 설계

기능별 분석 문서

문서	경로	내용
개요	`docs/specs/erp-analysis/00-overview.md`	메뉴 구조, 슬라이드 매핑
공통 UI	`docs/specs/erp-analysis/01-common.md`	UI 컴포넌트, 알림, 셀렉트박스
인증/영업	`docs/specs/erp-analysis/02-auth.md`	로그인, 회원가입, 테넌트
GPS 출퇴근	`docs/specs/erp-analysis/03-gps-attendance.md`	모바일 출퇴근, 현장 관리
인사관리	`docs/specs/erp-analysis/04-hr-management.md`	부서/사원/근태/휴가
전자결재	`docs/specs/erp-analysis/05-approval.md`	기안/결재/참조함
회계관리	`docs/specs/erp-analysis/06-accounting.md`	거래처/매출/매입/입출금
기준정보	`docs/specs/erp-analysis/07-master-data.md`	직급/직책/설정/카드/계좌
보고서	`docs/specs/erp-analysis/08-reports.md`	일일일보/AI리포트

개발 표준 문서

문서	경로	용도
API 개발 규칙	`docs/standards/api-rules.md`	Service-First, FormRequest, i18n
DB 스키마	`docs/specs/database-schema.md`	테이블 구조, 관계
시스템 아키텍처	`docs/architecture/system-overview.md`	전체 아키텍처
보안 정책	`docs/architecture/security-policy.md`	인증/인가, 보안
Swagger 가이드	`docs/guides/swagger-guide.md`	API 문서 작성법
품질 체크리스트	`docs/standards/quality-checklist.md`	코드 품질 검증

기존 코드 참조

항목	경로	용도
API 라우트	`api/routes/api.php`	기존 엔드포인트 확인
컨트롤러	`api/app/Http/Controllers/Api/V1/`	기존 패턴 참조
서비스	`api/app/Services/`	비즈니스 로직 패턴
모델	`api/app/Models/`	Eloquent 모델 패턴
Swagger	`api/app/Swagger/v1/`	API 문서 패턴

📊 개발 범위 요약

구분	항목수	작업	상태
기존 API 활용	12개	프론트엔드 연동만	⬜ 대기
확장 개발	6개	기존 구조 활용, API 추가	🟢 2/6 완료
신규 개발	8개	테이블 + API 신규 생성	⬜ 대기

🚀 Phase 1: 확장 개발 (예상 1-2주)

2.1 휴가 관리 ✅

참조: 99-gap-analysis.md#21-휴가-관리 완료일: 2025-12-17 | 커밋: e81e5d7

테이블 생성
- leaves 마이그레이션 생성
- leave_balances 마이그레이션 생성
- 마이그레이션 실행 및 검증
모델 생성
- Leave 모델 (BelongsToTenant, SoftDeletes)
- LeaveBalance 모델
서비스 구현
- LeaveService 생성
- 휴가 신청/승인/반려 로직
- 잔여휴가 계산 로직
API 엔드포인트 (11개)
- GET /v1/leaves - 목록
- POST /v1/leaves - 신청
- GET /v1/leaves/{id} - 상세
- PATCH /v1/leaves/{id} - 수정
- DELETE /v1/leaves/{id} - 삭제
- POST /v1/leaves/{id}/approve - 승인
- POST /v1/leaves/{id}/reject - 반려
- POST /v1/leaves/{id}/cancel - 취소
- GET /v1/leaves/balance - 내 잔여휴가
- GET /v1/leaves/balance/{userId} - 특정 사용자 잔여휴가
- PUT /v1/leaves/balance - 잔여휴가 설정
Swagger 문서
- LeaveApi.php 작성
- 스키마 정의 (Leave, LeaveBalance, Request/Response)
테스트
- Feature 테스트 작성
- 수동 API 테스트

2.2 근무/출퇴근 설정 ✅

참조: 99-gap-analysis.md#22-근무출퇴근-설정 완료일: 2025-12-17 | 커밋: ca5618b

테이블 생성
- work_settings 마이그레이션
- attendance_settings 마이그레이션
- sites (현장) 마이그레이션
- 마이그레이션 실행 및 검증
모델 생성
- WorkSetting 모델 (BelongsToTenant)
- AttendanceSetting 모델 (BelongsToTenant, GPS 거리 계산)
- Site 모델 (BelongsToTenant, SoftDeletes)
서비스 구현
- WorkSettingService 생성 (자동 기본값 생성)
- SiteService 생성 (페이지네이션, 검색, 활성 목록)
API 엔드포인트 (10개)
- GET /v1/settings/work - 근무 설정 조회
- PUT /v1/settings/work - 근무 설정 수정
- GET /v1/settings/attendance - 출퇴근 설정 조회
- PUT /v1/settings/attendance - 출퇴근 설정 수정
- GET /v1/sites - 현장 목록
- POST /v1/sites - 현장 등록
- GET /v1/sites/active - 활성 현장 목록 (셀렉트박스용)
- GET /v1/sites/{id} - 현장 상세
- PUT /v1/sites/{id} - 현장 수정
- DELETE /v1/sites/{id} - 현장 삭제
Swagger 문서
- WorkSettingApi.php 작성
- SiteApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

2.3 카드/계좌 관리 ✅

참조: 99-gap-analysis.md#23-카드계좌-관리 완료일: 2025-12-17 | 커밋: e1b0c99

테이블 생성
- cards 마이그레이션 (카드번호 암호화)
- bank_accounts 마이그레이션
모델 생성
- Card 모델 (암호화 처리, Laravel Crypt)
- BankAccount 모델 (대표계좌 자동 설정)
서비스 구현
- CardService 생성
- BankAccountService 생성
- 암호화/복호화 (Crypt::encryptString/decryptString)
API 엔드포인트 (15개)
- GET /v1/cards - 카드 목록
- POST /v1/cards - 카드 등록
- GET /v1/cards/active - 활성 카드 목록 (셀렉트박스용)
- GET /v1/cards/{id} - 카드 상세
- PUT /v1/cards/{id} - 카드 수정
- DELETE /v1/cards/{id} - 카드 삭제
- PATCH /v1/cards/{id}/toggle - 사용/정지
- GET /v1/bank-accounts - 계좌 목록
- POST /v1/bank-accounts - 계좌 등록
- GET /v1/bank-accounts/active - 활성 계좌 목록 (셀렉트박스용)
- GET /v1/bank-accounts/{id} - 계좌 상세
- PUT /v1/bank-accounts/{id} - 계좌 수정
- DELETE /v1/bank-accounts/{id} - 계좌 삭제
- PATCH /v1/bank-accounts/{id}/toggle - 사용/정지
- PATCH /v1/bank-accounts/{id}/set-primary - 대표계좌
Swagger 문서
- CardApi.php 작성
- BankAccountApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

2.4 입금/출금 관리 ✅

참조: 99-gap-analysis.md#24-입금출금-관리 완료일: 2025-12-17 | 커밋: 17799c4

테이블 생성
- deposits 마이그레이션
- withdrawals 마이그레이션
모델 생성
- Deposit 모델 (BelongsToTenant, SoftDeletes)
- Withdrawal 모델 (BelongsToTenant, SoftDeletes)
서비스 구현
- DepositService 생성
- WithdrawalService 생성
- 요약 계산 로직 (payment_method별 집계)
API 엔드포인트 (12개)
- GET /v1/deposits - 입금 목록
- POST /v1/deposits - 입금 등록
- GET /v1/deposits/summary - 입금 요약
- GET /v1/deposits/{id} - 입금 상세
- PUT /v1/deposits/{id} - 입금 수정
- DELETE /v1/deposits/{id} - 입금 삭제
- GET /v1/withdrawals - 출금 목록
- POST /v1/withdrawals - 출금 등록
- GET /v1/withdrawals/summary - 출금 요약
- GET /v1/withdrawals/{id} - 출금 상세
- PUT /v1/withdrawals/{id} - 출금 수정
- DELETE /v1/withdrawals/{id} - 출금 삭제
Swagger 문서
- DepositApi.php 작성
- WithdrawalApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

2.5 매출/매입 관리 ✅

참조: 99-gap-analysis.md#25-매출매입-관리 완료일: 2025-12-17

테이블 생성
- sales 마이그레이션
- purchases 마이그레이션
모델 생성
- Sale 모델 (BelongsToTenant, SoftDeletes)
- Purchase 모델 (BelongsToTenant, SoftDeletes)
서비스 구현
- SaleService 생성 (CRUD, confirm, summary)
- PurchaseService 생성 (CRUD, confirm, summary)
- 세금계산서 발행 연동 (추후 개발)
API 엔드포인트 (14개)
- GET /v1/sales - 매출 목록
- POST /v1/sales - 매출 등록
- GET /v1/sales/{id} - 매출 상세
- PUT /v1/sales/{id} - 매출 수정
- DELETE /v1/sales/{id} - 매출 삭제
- POST /v1/sales/{id}/confirm - 매출 확정
- GET /v1/sales/summary - 매출 요약
- GET /v1/purchases - 매입 목록
- POST /v1/purchases - 매입 등록
- GET /v1/purchases/{id} - 매입 상세
- PUT /v1/purchases/{id} - 매입 수정
- DELETE /v1/purchases/{id} - 매입 삭제
- POST /v1/purchases/{id}/confirm - 매입 확정
- GET /v1/purchases/summary - 매입 요약
Swagger 문서
- SaleApi.php 작성
- PurchaseApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

2.6 보고서 ✅

참조: 99-gap-analysis.md#26-보고서 완료일: 2025-12-17 | 커밋: 77914da

서비스 구현
- ReportService 생성
- 일일 일보 집계 로직 (전일잔액, 당일입출금, 상세내역)
- 지출 예상 내역 계산 로직 (월별 집계, 예상잔액)
- Excel 다운로드 (Laravel Excel - DailyReportExport, ExpenseEstimateExport)
API 엔드포인트
- GET /v1/reports/daily - 일일 일보
- GET /v1/reports/daily/export - 엑셀 다운로드
- GET /v1/reports/expense-estimate - 지출 예상 내역서
- GET /v1/reports/expense-estimate/export - 엑셀 다운로드
Swagger 문서
- ReportApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

🔨 Phase 2: 핵심 신규 개발 (예상 2-4주)

3.1 전자결재 모듈 ✅

참조: 99-gap-analysis.md#31-전자결재-모듈 완료일: 2025-12-17 | 커밋: b43796a

테이블 생성
- approval_forms 마이그레이션
- approval_lines 마이그레이션
- approvals 마이그레이션
- approval_steps 마이그레이션
모델 생성
- ApprovalForm 모델 (BelongsToTenant, SoftDeletes)
- ApprovalLine 모델 (BelongsToTenant, SoftDeletes)
- Approval 모델 (상태: draft→pending→approved/rejected/cancelled)
- ApprovalStep 모델 (유형: approval, agreement, reference)
서비스 구현
- ApprovalService 생성
- 결재선 로직
- 상태 전이 로직 (draft→pending→approved/rejected)
- 알림 연동 (추후 개발)
API 엔드포인트 (26개)
- 결재 양식 API (6개: CRUD + active)
- 결재선 템플릿 API (5개: CRUD)
- 결재 문서 API (15개: drafts, inbox, reference, CRUD, 액션)
Swagger 문서
- ApprovalFormApi.php 작성
- ApprovalLineApi.php 작성
- ApprovalApi.php 작성
테스트
- Feature 테스트 작성
- 수동 API 테스트

3.2 급여 관리 ✅

참조: 99-gap-analysis.md#32-급여-관리 완료일: 2025-12-18

테이블 생성
- payrolls 마이그레이션
- payroll_settings 마이그레이션
모델 생성
- Payroll 모델 (상태: draft→confirmed→paid, BelongsToTenant, SoftDeletes)
- PayrollSetting 모델 (4대보험 요율, 수당/공제 유형)
서비스 구현
- PayrollService 생성
- 급여 계산 로직 (4대보험: 건강보험, 장기요양, 국민연금, 고용보험)
- 소득세/주민세 계산 로직
- 급여명세서 데이터 (payslip)
- 급여명세서 PDF 생성 (추후 개발)
API 엔드포인트 (13개)
- 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 - 급여명세서 조회
- GET /v1/settings/payroll - 급여 설정 조회
- PUT /v1/settings/payroll - 급여 설정 수정
Swagger 문서
- PayrollApi.php 작성 (스키마 10개, 엔드포인트 13개)
테스트
- Feature 테스트 작성
- 수동 API 테스트

3.3 대시보드

참조: 99-gap-analysis.md#33-대시보드

서비스 구현
- DashboardService 생성
- 통계 집계 로직
- 차트 데이터 생성
API 엔드포인트
- GET /v1/dashboard/summary - 요약 데이터
- GET /v1/dashboard/charts - 차트 데이터
- GET /v1/dashboard/notifications - 알림
- GET /v1/dashboard/approvals - 결재 현황
Swagger 문서
- DashboardApi.php 작성

🔧 Phase 3: 추가 기능 (예상 4-6주)

3.4 AI 리포트

테이블 생성 (ai_reports)
서비스 구현 (AI 연동 로직)
API 구현
Swagger 문서

3.5 가지급금 관리

테이블 생성 (loans)
서비스 구현 (인정이자 계산)
API 구현
Swagger 문서

3.8 바로빌 연동

테이블 생성 (tax_invoices)
외부 API 연동 서비스
API 구현
Swagger 문서

💼 Phase 4: SaaS 기능 (별도 일정)

3.6 구독/결제 관리

테이블 생성 (subscriptions, payments)
PG 연동 서비스
API 구현
Swagger 문서

3.7 고객센터

테이블 생성 (support_tickets, faqs)
서비스 구현
API 구현
Swagger 문서

📋 기획 확인 필요 항목

⚠️ API 구현 전 비즈니스 로직 확정 필요

상태 전이 조건

테넌트: 신청→승인→만료→해지 전이 조건
사원: 휴직→복직/퇴사 전이 조건
결재: 반려 후 재기안 프로세스
미수금: 연체 판정 기준일 (기본 30일)
악성채권: 판정 조건 (기본 90일 + 수동)

모듈 간 연동

전자결재→회계: 지출결의서 승인 시 출금 자동 생성?
휴가신청→결재: 휴가가 결재 문서로 생성되는지?
휴가승인→근태: 승인 휴가 근태 자동 반영 (기본 O)
GPS출퇴근→근태: GPS 기록 근태 자동 반영 (기본 O)
급여→출금: 급여 확정 시 출금 자동 생성?

외부 연동

바로빌 API 비용 확인
연동 은행 범위 확인
연동 실패 처리 정책

📝 작업 일지

2025-12-17

ERP 스토리보드 분석 문서 작성 완료 (00~08)
Gap Analysis 문서 작성 완료 (99-gap-analysis.md)
개발 작업 계획 수립 (이 문서)
휴가 관리 API 구현 완료 (커밋: e81e5d7)
- 마이그레이션 2개 (leaves, leave_balances)
- 모델 2개 (Leave, LeaveBalance)
- 서비스 1개 (LeaveService)
- 컨트롤러 1개, FormRequest 5개
- API 엔드포인트 11개
- Swagger 문서 (LeaveApi.php)
- i18n 메시지 키 추가
카드/계좌 관리 API 구현 완료 (커밋: e1b0c99)
- 마이그레이션 2개 (cards, bank_accounts)
- 모델 2개 (Card, BankAccount)
- 서비스 2개 (CardService, BankAccountService)
- 컨트롤러 2개, FormRequest 4개
- API 엔드포인트 15개 (카드 7개, 계좌 8개)
- Swagger 문서 (CardApi.php, BankAccountApi.php)
- 카드번호 암호화 (Laravel Crypt 사용)
- 대표계좌 자동 설정 로직
전자결재 모듈 API 구현 완료 (커밋: b43796a)
- 마이그레이션 4개 (approval_forms, approval_lines, approvals, approval_steps)
- 모델 4개 (ApprovalForm, ApprovalLine, Approval, ApprovalStep)
- 서비스 1개 (ApprovalService)
- 컨트롤러 3개, FormRequest 13개
- API 엔드포인트 26개 (양식 6, 결재선 5, 문서 15)
- Swagger 문서 3개 (ApprovalFormApi.php, ApprovalLineApi.php, ApprovalApi.php)
- i18n 메시지/에러 키 추가

2025-12-18

급여 관리 API 구현 완료
- 마이그레이션 2개 (payrolls, payroll_settings)
- 모델 2개 (Payroll, PayrollSetting)
- 서비스 1개 (PayrollService)
- 컨트롤러 1개, FormRequest 5개
- API 엔드포인트 13개
- Swagger 문서 (PayrollApi.php)
- i18n 메시지/에러 키 추가
- 4대보험 계산 로직 (건강보험, 장기요양, 국민연금, 고용보험)
- 급여 상태 관리 (draft→confirmed→paid)

YYYY-MM-DD

(작업 내용 기록)

✅ 완료 기준

Phase 1 완료 조건

모든 확장 개발 API 구현 완료
Swagger 문서 100% 완성
API 테스트 통과
Pint 코드 포맷팅 완료

Phase 2 완료 조건

전자결재 모듈 완전 동작
급여 관리 완전 동작
대시보드 데이터 정상 조회

전체 완료 조건

모든 API 구현 완료
Swagger 문서 100%
통합 테스트 통과
프론트엔드 연동 준비 완료

🔗 관련 링크

API Swagger UI: http://sam.kr/api-docs/index.html
기존 API 라우트: api/routes/api.php
ERP 스토리보드 원본: docs/plans/SAM_ERP_Storyboard_D0.8_251216/

19 KiB Raw Blame History

SAM ERP API 개발 작업 계획

📚 참고 문서

핵심 참고 문서

기능별 분석 문서

개발 표준 문서

기존 코드 참조

📊 개발 범위 요약

🚀 Phase 1: 확장 개발 (예상 1-2주)

2.1 휴가 관리 ✅

2.2 근무/출퇴근 설정 ✅

2.3 카드/계좌 관리 ✅

2.4 입금/출금 관리 ✅

2.5 매출/매입 관리 ✅

2.6 보고서 ✅

🔨 Phase 2: 핵심 신규 개발 (예상 2-4주)

3.1 전자결재 모듈 ✅

3.2 급여 관리 ✅

3.3 대시보드

🔧 Phase 3: 추가 기능 (예상 4-6주)

3.4 AI 리포트

3.5 가지급금 관리

3.8 바로빌 연동

💼 Phase 4: SaaS 기능 (별도 일정)

3.6 구독/결제 관리

3.7 고객센터

📋 기획 확인 필요 항목

상태 전이 조건

모듈 간 연동

외부 연동

📝 작업 일지

2025-12-17

2025-12-18

YYYY-MM-DD

✅ 완료 기준

Phase 1 완료 조건

Phase 2 완료 조건

전체 완료 조건

🔗 관련 링크

19 KiB

Raw Blame History