SamProject/sam-docs

Fork 0

Files

hskwon e5b3e6c939 docs: 휴가 관리 API 구현 완료 상태 업데이트

2025-12-17 20:18:29 +09:00

14 KiB

Raw Blame History

SAM ERP API 개발 작업 계획

작성일: 2025-12-17 기준 문서: SAM_ERP_Storyboard_D0.8_251216 상태: 🟢 Phase 1 진행 중 (휴가 관리 완료)

📚 참고 문서

핵심 참고 문서

문서	경로	용도
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 추가	🟢 1/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-근무출퇴근-설정

테이블 생성
- work_settings 마이그레이션
- attendance_settings 마이그레이션
- sites (현장) 마이그레이션
모델 생성
- WorkSetting 모델
- AttendanceSetting 모델
- Site 모델
서비스 구현
- WorkSettingService 생성
- SiteService 생성
API 엔드포인트
- GET/PUT /v1/settings/work - 근무 설정
- GET/PUT /v1/settings/attendance - 출퇴근 설정
- GET/POST/PUT/DELETE /v1/sites - 현장 CRUD
Swagger 문서
- WorkSettingApi.php 작성
- SiteApi.php 작성

2.3 카드/계좌 관리

참조: 99-gap-analysis.md#23-카드계좌-관리

테이블 생성
- cards 마이그레이션 (카드번호 암호화)
- bank_accounts 마이그레이션
모델 생성
- Card 모델 (암호화 처리)
- BankAccount 모델
서비스 구현
- CardService 생성
- BankAccountService 생성
- 암호화/복호화 유틸리티
API 엔드포인트
- GET/POST/PUT/DELETE /v1/cards - 카드 CRUD
- PATCH /v1/cards/{id}/toggle - 사용/정지
- GET/POST/PUT/DELETE /v1/bank-accounts - 계좌 CRUD
- PATCH /v1/bank-accounts/{id}/toggle - 사용/정지
- PATCH /v1/bank-accounts/{id}/set-primary - 대표계좌
Swagger 문서
- CardApi.php 작성
- BankAccountApi.php 작성

2.4 입금/출금 관리

참조: 99-gap-analysis.md#24-입금출금-관리

테이블 생성
- deposits 마이그레이션
- withdrawals 마이그레이션
모델 생성
- Deposit 모델
- Withdrawal 모델
서비스 구현
- DepositService 생성
- WithdrawalService 생성
- 요약 계산 로직
API 엔드포인트
- GET/POST/PUT/DELETE /v1/deposits - 입금 CRUD
- GET /v1/deposits/summary - 입금 요약
- GET/POST/PUT/DELETE /v1/withdrawals - 출금 CRUD
- GET /v1/withdrawals/summary - 출금 요약
Swagger 문서
- DepositApi.php 작성
- WithdrawalApi.php 작성

2.5 매출/매입 관리

참조: 99-gap-analysis.md#25-매출매입-관리

테이블 생성
- sales 마이그레이션
- purchases 마이그레이션
모델 생성
- Sale 모델
- Purchase 모델
서비스 구현
- SaleService 생성
- PurchaseService 생성
- 세금계산서 발행 연동 준비
API 엔드포인트
- GET/POST/PUT/DELETE /v1/sales - 매출 CRUD
- POST /v1/sales/{id}/confirm - 매출 확정
- POST /v1/sales/{id}/tax-invoice - 세금계산서 발행
- GET/POST/PUT/DELETE /v1/purchases - 매입 CRUD
- POST /v1/purchases/{id}/confirm - 매입 확정
Swagger 문서
- SaleApi.php 작성
- PurchaseApi.php 작성

2.6 보고서

참조: 99-gap-analysis.md#26-보고서

서비스 구현
- ReportService 생성
- 일일 일보 집계 로직
- 지출 예상 내역 계산 로직
- Excel 다운로드 (Laravel Excel)
API 엔드포인트
- GET /v1/reports/daily - 일일 일보
- GET /v1/reports/daily/export - 엑셀 다운로드
- GET /v1/reports/expense-estimate - 지출 예상 내역서
- GET /v1/reports/expense-estimate/export - 엑셀 다운로드
Swagger 문서
- ReportApi.php 작성

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

3.1 전자결재 모듈 ⭐

참조: 99-gap-analysis.md#31-전자결재-모듈

테이블 생성
- approval_forms 마이그레이션
- approval_lines 마이그레이션
- approvals 마이그레이션
- approval_steps 마이그레이션
모델 생성
- ApprovalForm 모델
- ApprovalLine 모델
- Approval 모델
- ApprovalStep 모델
서비스 구현
- ApprovalService 생성
- 결재선 로직
- 상태 전이 로직 (draft→pending→approved/rejected)
- 알림 연동
API 엔드포인트
- 결재 문서 API (drafts, inbox, completed, reference)
- 결재선 템플릿 API
- 결재 양식 API
Swagger 문서
- ApprovalApi.php 작성

3.2 급여 관리

참조: 99-gap-analysis.md#32-급여-관리

테이블 생성
- payrolls 마이그레이션
모델 생성
- Payroll 모델
서비스 구현
- PayrollService 생성
- 급여 계산 로직 (4대보험, 세금)
- 급여명세서 PDF 생성
API 엔드포인트
- 급여 CRUD API
- POST /v1/payrolls/calculate - 급여 일괄 계산
- GET /v1/payrolls/{id}/payslip/pdf - 급여명세서 PDF
Swagger 문서
- PayrollApi.php 작성

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 메시지 키 추가

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/

14 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

YYYY-MM-DD

✅ 완료 기준

Phase 1 완료 조건

Phase 2 완료 조건

전체 완료 조건

🔗 관련 링크

14 KiB

Raw Blame History