# SAM ERP API 개발 작업 계획

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

---

## 📚 참고 문서

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

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

### 개발 표준 문서
| 문서 | 경로 | 용도 |
|------|------|------|
| API 개발 규칙 | [`docs/standards/api-rules.md`](../standards/api-rules.md) | Service-First, FormRequest, i18n |
| DB 스키마 | [`docs/specs/database-schema.md`](../specs/database-schema.md) | 테이블 구조, 관계 |
| 시스템 아키텍처 | [`docs/architecture/system-overview.md`](../architecture/system-overview.md) | 전체 아키텍처 |
| 보안 정책 | [`docs/architecture/security-policy.md`](../architecture/security-policy.md) | 인증/인가, 보안 |
| Swagger 가이드 | [`docs/guides/swagger-guide.md`](../guides/swagger-guide.md) | API 문서 작성법 |
| 품질 체크리스트 | [`docs/standards/quality-checklist.md`](../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-휴가-관리](../specs/erp-analysis/99-gap-analysis.md)
> **완료일**: 2025-12-17 | **커밋**: `e81e5d7`

- [x] **테이블 생성**
  - [x] `leaves` 마이그레이션 생성
  - [x] `leave_balances` 마이그레이션 생성
  - [ ] 마이그레이션 실행 및 검증

- [x] **모델 생성**
  - [x] `Leave` 모델 (BelongsToTenant, SoftDeletes)
  - [x] `LeaveBalance` 모델

- [x] **서비스 구현**
  - [x] `LeaveService` 생성
  - [x] 휴가 신청/승인/반려 로직
  - [x] 잔여휴가 계산 로직

- [x] **API 엔드포인트** (11개)
  - [x] `GET /v1/leaves` - 목록
  - [x] `POST /v1/leaves` - 신청
  - [x] `GET /v1/leaves/{id}` - 상세
  - [x] `PATCH /v1/leaves/{id}` - 수정
  - [x] `DELETE /v1/leaves/{id}` - 삭제
  - [x] `POST /v1/leaves/{id}/approve` - 승인
  - [x] `POST /v1/leaves/{id}/reject` - 반려
  - [x] `POST /v1/leaves/{id}/cancel` - 취소
  - [x] `GET /v1/leaves/balance` - 내 잔여휴가
  - [x] `GET /v1/leaves/balance/{userId}` - 특정 사용자 잔여휴가
  - [x] `PUT /v1/leaves/balance` - 잔여휴가 설정

- [x] **Swagger 문서**
  - [x] `LeaveApi.php` 작성
  - [x] 스키마 정의 (Leave, LeaveBalance, Request/Response)

- [ ] **테스트**
  - [ ] Feature 테스트 작성
  - [ ] 수동 API 테스트

---

### 2.2 근무/출퇴근 설정
> 참조: [99-gap-analysis.md#22-근무출퇴근-설정](../specs/erp-analysis/99-gap-analysis.md)

- [ ] **테이블 생성**
  - [ ] `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-카드계좌-관리](../specs/erp-analysis/99-gap-analysis.md)

- [ ] **테이블 생성**
  - [ ] `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-입금출금-관리](../specs/erp-analysis/99-gap-analysis.md)

- [ ] **테이블 생성**
  - [ ] `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-매출매입-관리](../specs/erp-analysis/99-gap-analysis.md)

- [ ] **테이블 생성**
  - [ ] `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-보고서](../specs/erp-analysis/99-gap-analysis.md)

- [ ] **서비스 구현**
  - [ ] `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-전자결재-모듈](../specs/erp-analysis/99-gap-analysis.md)

- [ ] **테이블 생성**
  - [ ] `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-급여-관리](../specs/erp-analysis/99-gap-analysis.md)

- [ ] **테이블 생성**
  - [ ] `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-대시보드](../specs/erp-analysis/99-gap-analysis.md)

- [ ] **서비스 구현**
  - [ ] `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
- [x] ERP 스토리보드 분석 문서 작성 완료 (00~08)
- [x] Gap Analysis 문서 작성 완료 (99-gap-analysis.md)
- [x] 개발 작업 계획 수립 (이 문서)
- [x] **휴가 관리 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/`