diff --git a/plans/erp-api-development-plan.md b/plans/erp-api-development-plan.md new file mode 100644 index 0000000..392799b --- /dev/null +++ b/plans/erp-api-development-plan.md @@ -0,0 +1,422 @@ +# 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/`