sam-docs/dev/dev_plans/erp-api-development-plan.md

# SAM ERP API 개발 작업 계획

> **작성일**: 2025-12-17
> **기준 문서**: SAM_ERP_Storyboard_D0.8_251216
> **상태**: ✅ Phase 1 완료 | ✅ Phase 2 완료 | ✅ Phase 3 완료 | ✅ Phase L 완료 (직급/직책) | 🟡 L-2 권한관리 React 연동 대기

---

## 📚 참고 문서

### 핵심 참고 문서
| 문서 | 경로 | 용도 |
|------|------|------|
| **ERP API 명세서** | [`docs/specs/erp-analysis/99-gap-analysis.md`](../specs/erp-analysis/99-gap-analysis.md) | 전체 개발 범위, 테이블 스키마, API 엔드포인트 |
| **스토리보드 원본** | [`docs/dev_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 추가 | 🟢 2/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] **모델 생성**
  - [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)
> **완료일**: 2025-12-17 | **커밋**: `ca5618b`

- [x] **테이블 생성**
  - [x] `work_settings` 마이그레이션
  - [x] `attendance_settings` 마이그레이션
  - [x] `sites` (현장) 마이그레이션
  - [x] 마이그레이션 실행 및 검증

- [x] **모델 생성**
  - [x] `WorkSetting` 모델 (BelongsToTenant)
  - [x] `AttendanceSetting` 모델 (BelongsToTenant, GPS 거리 계산)
  - [x] `Site` 모델 (BelongsToTenant, SoftDeletes)

- [x] **서비스 구현**
  - [x] `WorkSettingService` 생성 (자동 기본값 생성)
  - [x] `SiteService` 생성 (페이지네이션, 검색, 활성 목록)

- [x] **API 엔드포인트** (10개)
  - [x] `GET /v1/settings/work` - 근무 설정 조회
  - [x] `PUT /v1/settings/work` - 근무 설정 수정
  - [x] `GET /v1/settings/attendance` - 출퇴근 설정 조회
  - [x] `PUT /v1/settings/attendance` - 출퇴근 설정 수정
  - [x] `GET /v1/sites` - 현장 목록
  - [x] `POST /v1/sites` - 현장 등록
  - [x] `GET /v1/sites/active` - 활성 현장 목록 (셀렉트박스용)
  - [x] `GET /v1/sites/{id}` - 현장 상세
  - [x] `PUT /v1/sites/{id}` - 현장 수정
  - [x] `DELETE /v1/sites/{id}` - 현장 삭제

- [x] **Swagger 문서**
  - [x] `WorkSettingApi.php` 작성
  - [x] `SiteApi.php` 작성

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

---

### 2.3 카드/계좌 관리 ✅
> 참조: [99-gap-analysis.md#23-카드계좌-관리](../specs/erp-analysis/99-gap-analysis.md)
> **완료일**: 2025-12-17 | **커밋**: `e1b0c99`

- [x] **테이블 생성**
  - [x] `cards` 마이그레이션 (카드번호 암호화)
  - [x] `bank_accounts` 마이그레이션

- [x] **모델 생성**
  - [x] `Card` 모델 (암호화 처리, Laravel Crypt)
  - [x] `BankAccount` 모델 (대표계좌 자동 설정)

- [x] **서비스 구현**
  - [x] `CardService` 생성
  - [x] `BankAccountService` 생성
  - [x] 암호화/복호화 (Crypt::encryptString/decryptString)

- [x] **API 엔드포인트** (15개)
  - [x] `GET /v1/cards` - 카드 목록
  - [x] `POST /v1/cards` - 카드 등록
  - [x] `GET /v1/cards/active` - 활성 카드 목록 (셀렉트박스용)
  - [x] `GET /v1/cards/{id}` - 카드 상세
  - [x] `PUT /v1/cards/{id}` - 카드 수정
  - [x] `DELETE /v1/cards/{id}` - 카드 삭제
  - [x] `PATCH /v1/cards/{id}/toggle` - 사용/정지
  - [x] `GET /v1/bank-accounts` - 계좌 목록
  - [x] `POST /v1/bank-accounts` - 계좌 등록
  - [x] `GET /v1/bank-accounts/active` - 활성 계좌 목록 (셀렉트박스용)
  - [x] `GET /v1/bank-accounts/{id}` - 계좌 상세
  - [x] `PUT /v1/bank-accounts/{id}` - 계좌 수정
  - [x] `DELETE /v1/bank-accounts/{id}` - 계좌 삭제
  - [x] `PATCH /v1/bank-accounts/{id}/toggle` - 사용/정지
  - [x] `PATCH /v1/bank-accounts/{id}/set-primary` - 대표계좌

- [x] **Swagger 문서**
  - [x] `CardApi.php` 작성
  - [x] `BankAccountApi.php` 작성

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

---

### 2.4 입금/출금 관리 ✅
> 참조: [99-gap-analysis.md#24-입금출금-관리](../specs/erp-analysis/99-gap-analysis.md)
> **완료일**: 2025-12-17 | **커밋**: `17799c4`

- [x] **테이블 생성**
  - [x] `deposits` 마이그레이션
  - [x] `withdrawals` 마이그레이션

- [x] **모델 생성**
  - [x] `Deposit` 모델 (BelongsToTenant, SoftDeletes)
  - [x] `Withdrawal` 모델 (BelongsToTenant, SoftDeletes)

- [x] **서비스 구현**
  - [x] `DepositService` 생성
  - [x] `WithdrawalService` 생성
  - [x] 요약 계산 로직 (payment_method별 집계)

- [x] **API 엔드포인트** (12개)
  - [x] `GET /v1/deposits` - 입금 목록
  - [x] `POST /v1/deposits` - 입금 등록
  - [x] `GET /v1/deposits/summary` - 입금 요약
  - [x] `GET /v1/deposits/{id}` - 입금 상세
  - [x] `PUT /v1/deposits/{id}` - 입금 수정
  - [x] `DELETE /v1/deposits/{id}` - 입금 삭제
  - [x] `GET /v1/withdrawals` - 출금 목록
  - [x] `POST /v1/withdrawals` - 출금 등록
  - [x] `GET /v1/withdrawals/summary` - 출금 요약
  - [x] `GET /v1/withdrawals/{id}` - 출금 상세
  - [x] `PUT /v1/withdrawals/{id}` - 출금 수정
  - [x] `DELETE /v1/withdrawals/{id}` - 출금 삭제

- [x] **Swagger 문서**
  - [x] `DepositApi.php` 작성
  - [x] `WithdrawalApi.php` 작성

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

---

### 2.5 매출/매입 관리 ✅
> 참조: [99-gap-analysis.md#25-매출매입-관리](../specs/erp-analysis/99-gap-analysis.md)
> **완료일**: 2025-12-17

- [x] **테이블 생성**
  - [x] `sales` 마이그레이션
  - [x] `purchases` 마이그레이션

- [x] **모델 생성**
  - [x] `Sale` 모델 (BelongsToTenant, SoftDeletes)
  - [x] `Purchase` 모델 (BelongsToTenant, SoftDeletes)

- [x] **서비스 구현**
  - [x] `SaleService` 생성 (CRUD, confirm, summary)
  - [x] `PurchaseService` 생성 (CRUD, confirm, summary)
  - [ ] 세금계산서 발행 연동 (추후 개발)

- [x] **API 엔드포인트** (14개)
  - [x] `GET /v1/sales` - 매출 목록
  - [x] `POST /v1/sales` - 매출 등록
  - [x] `GET /v1/sales/{id}` - 매출 상세
  - [x] `PUT /v1/sales/{id}` - 매출 수정
  - [x] `DELETE /v1/sales/{id}` - 매출 삭제
  - [x] `POST /v1/sales/{id}/confirm` - 매출 확정
  - [x] `GET /v1/sales/summary` - 매출 요약
  - [x] `GET /v1/purchases` - 매입 목록
  - [x] `POST /v1/purchases` - 매입 등록
  - [x] `GET /v1/purchases/{id}` - 매입 상세
  - [x] `PUT /v1/purchases/{id}` - 매입 수정
  - [x] `DELETE /v1/purchases/{id}` - 매입 삭제
  - [x] `POST /v1/purchases/{id}/confirm` - 매입 확정
  - [x] `GET /v1/purchases/summary` - 매입 요약

- [x] **Swagger 문서**
  - [x] `SaleApi.php` 작성
  - [x] `PurchaseApi.php` 작성

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

---

### 2.6 보고서 ✅
> 참조: [99-gap-analysis.md#26-보고서](../specs/erp-analysis/99-gap-analysis.md)
> **완료일**: 2025-12-17 | **커밋**: `77914da`

- [x] **서비스 구현**
  - [x] `ReportService` 생성
  - [x] 일일 일보 집계 로직 (전일잔액, 당일입출금, 상세내역)
  - [x] 지출 예상 내역 계산 로직 (월별 집계, 예상잔액)
  - [x] Excel 다운로드 (Laravel Excel - `DailyReportExport`, `ExpenseEstimateExport`)

- [x] **API 엔드포인트**
  - [x] `GET /v1/reports/daily` - 일일 일보
  - [x] `GET /v1/reports/daily/export` - 엑셀 다운로드
  - [x] `GET /v1/reports/expense-estimate` - 지출 예상 내역서
  - [x] `GET /v1/reports/expense-estimate/export` - 엑셀 다운로드

- [x] **Swagger 문서**
  - [x] `ReportApi.php` 작성

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

---

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

### 3.1 전자결재 모듈 ✅
> 참조: [99-gap-analysis.md#31-전자결재-모듈](../specs/erp-analysis/99-gap-analysis.md)
> **완료일**: 2025-12-17 | **커밋**: `b43796a`

- [x] **테이블 생성**
  - [x] `approval_forms` 마이그레이션
  - [x] `approval_lines` 마이그레이션
  - [x] `approvals` 마이그레이션
  - [x] `approval_steps` 마이그레이션

- [x] **모델 생성**
  - [x] `ApprovalForm` 모델 (BelongsToTenant, SoftDeletes)
  - [x] `ApprovalLine` 모델 (BelongsToTenant, SoftDeletes)
  - [x] `Approval` 모델 (상태: draft→pending→approved/rejected/cancelled)
  - [x] `ApprovalStep` 모델 (유형: approval, agreement, reference)

- [x] **서비스 구현**
  - [x] `ApprovalService` 생성
  - [x] 결재선 로직
  - [x] 상태 전이 로직 (draft→pending→approved/rejected)
  - [ ] 알림 연동 (추후 개발)

- [x] **API 엔드포인트** (26개)
  - [x] 결재 양식 API (6개: CRUD + active)
  - [x] 결재선 템플릿 API (5개: CRUD)
  - [x] 결재 문서 API (15개: drafts, inbox, reference, CRUD, 액션)

- [x] **Swagger 문서**
  - [x] `ApprovalFormApi.php` 작성
  - [x] `ApprovalLineApi.php` 작성
  - [x] `ApprovalApi.php` 작성

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

---

### 3.2 급여 관리 ✅
> 참조: [99-gap-analysis.md#32-급여-관리](../specs/erp-analysis/99-gap-analysis.md)
> **완료일**: 2025-12-18

- [x] **테이블 생성**
  - [x] `payrolls` 마이그레이션
  - [x] `payroll_settings` 마이그레이션

- [x] **모델 생성**
  - [x] `Payroll` 모델 (상태: draft→confirmed→paid, BelongsToTenant, SoftDeletes)
  - [x] `PayrollSetting` 모델 (4대보험 요율, 수당/공제 유형)

- [x] **서비스 구현**
  - [x] `PayrollService` 생성
  - [x] 급여 계산 로직 (4대보험: 건강보험, 장기요양, 국민연금, 고용보험)
  - [x] 소득세/주민세 계산 로직
  - [x] 급여명세서 데이터 (payslip)
  - [ ] 급여명세서 PDF 생성 (추후 개발)

- [x] **API 엔드포인트** (13개)
  - [x] `GET /v1/payrolls` - 급여 목록
  - [x] `POST /v1/payrolls` - 급여 등록
  - [x] `GET /v1/payrolls/summary` - 급여 현황 요약
  - [x] `POST /v1/payrolls/calculate` - 급여 일괄 계산
  - [x] `POST /v1/payrolls/bulk-confirm` - 급여 일괄 확정
  - [x] `GET /v1/payrolls/{id}` - 급여 상세
  - [x] `PUT /v1/payrolls/{id}` - 급여 수정
  - [x] `DELETE /v1/payrolls/{id}` - 급여 삭제
  - [x] `POST /v1/payrolls/{id}/confirm` - 급여 확정
  - [x] `POST /v1/payrolls/{id}/pay` - 급여 지급 처리
  - [x] `GET /v1/payrolls/{id}/payslip` - 급여명세서 조회
  - [x] `GET /v1/settings/payroll` - 급여 설정 조회
  - [x] `PUT /v1/settings/payroll` - 급여 설정 수정

- [x] **Swagger 문서**
  - [x] `PayrollApi.php` 작성 (스키마 10개, 엔드포인트 13개)

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

---

### 3.3 대시보드 ✅
> 참조: [99-gap-analysis.md#33-대시보드](../specs/erp-analysis/99-gap-analysis.md)
> **완료일**: 2025-12-18

- [x] **서비스 구현**
  - [x] `DashboardService` 생성
  - [x] 통계 집계 로직 (오늘 현황, 재무, 매출/매입, 할 일)
  - [x] 차트 데이터 생성 (입금/출금 추이, 거래처별 매출)

- [x] **API 엔드포인트** (3개)
  - [x] `GET /v1/dashboard/summary` - 요약 데이터
  - [x] `GET /v1/dashboard/charts` - 차트 데이터
  - [x] `GET /v1/dashboard/approvals` - 결재 현황
  - [ ] `GET /v1/dashboard/notifications` - 알림 (Push 기능과 함께 개발 예정)

- [x] **Swagger 문서**
  - [x] `DashboardApi.php` 작성

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

---

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

### 3.4 AI 리포트 ✅
> **완료일**: 2025-12-18 | **커밋**: `9864531`

- [x] **테이블 생성**
  - [x] `ai_reports` 마이그레이션

- [x] **모델 생성**
  - [x] `AiReport` 모델 (BelongsToTenant, SoftDeletes)
  - [x] 상수 정의 (REPORT_TYPES, STATUSES, ANALYSIS_AREAS, STATUS_CODES)

- [x] **서비스 구현**
  - [x] `AiReportService` 생성
  - [x] Google Gemini API 연동
  - [x] 비즈니스 데이터 수집 로직 (매출, 매입, 입출금, 미수금, 카드/계좌)
  - [x] AI 프롬프트 생성 (재무 분석 전문가 역할)

- [x] **API 엔드포인트** (4개)
  - [x] `GET /v1/reports/ai` - 목록 조회
  - [x] `POST /v1/reports/ai/generate` - 리포트 생성
  - [x] `GET /v1/reports/ai/{id}` - 상세 조회
  - [x] `DELETE /v1/reports/ai/{id}` - 삭제

- [x] **Swagger 문서**
  - [x] `AiReportApi.php` 작성

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

### 3.5 가지급금 관리 ✅
- [x] 테이블 생성 (`loans`) - 2025-12-18
- [x] 서비스 구현 (인정이자 계산) - LoanService
- [x] API 구현 - LoanController, FormRequest 5개, 9개 라우트
- [x] Swagger 문서 - `LoanApi.php` (스키마 7개, 엔드포인트 9개)

### 3.8 바로빌 연동 ✅
> **완료일**: 2025-12-18 | **커밋**: `8ad4d7c`

- [x] **테이블 생성**
  - [x] `barobill_settings` 마이그레이션 (테넌트별 바로빌 설정, 인증서 암호화)
  - [x] `tax_invoices` 마이그레이션 (세금계산서 발행 내역)

- [x] **모델 생성**
  - [x] `BarobillSetting` 모델 (cert_key 암호화 - Laravel Crypt)
  - [x] `TaxInvoice` 모델 (5개 상태, 3개 유형, 공급자/공급받는자 정보)

- [x] **서비스 구현**
  - [x] `BarobillService` 생성 (바로빌 API 연동, 테스트/운영 환경 구분)
  - [x] `TaxInvoiceService` 생성 (CRUD, 발행, 취소, 상태조회, 통계)

- [x] **API 엔드포인트** (12개)
  - [x] `GET /v1/barobill-settings` - 바로빌 설정 조회
  - [x] `PUT /v1/barobill-settings` - 바로빌 설정 저장
  - [x] `POST /v1/barobill-settings/test-connection` - 연동 테스트
  - [x] `GET /v1/tax-invoices` - 목록 조회
  - [x] `POST /v1/tax-invoices` - 세금계산서 생성
  - [x] `GET /v1/tax-invoices/summary` - 요약 통계
  - [x] `GET /v1/tax-invoices/{id}` - 상세 조회
  - [x] `PUT /v1/tax-invoices/{id}` - 수정
  - [x] `DELETE /v1/tax-invoices/{id}` - 삭제
  - [x] `POST /v1/tax-invoices/{id}/issue` - 발행
  - [x] `POST /v1/tax-invoices/{id}/cancel` - 취소
  - [x] `GET /v1/tax-invoices/{id}/check-status` - 국세청 전송 상태

- [x] **Swagger 문서**
  - [x] `BarobillSettingApi.php` 작성
  - [x] `TaxInvoiceApi.php` 작성

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

---

## ⚙️ Phase L: 설정 및 기준정보 (2025-12-30)

> 참조: [`docs/dev_plans/react-mock-remaining-tasks.md`](./react-mock-remaining-tasks.md) - Phase L 섹션

### L-2 권한관리 🟡
> 참조: [`docs/dev_plans/l2-permission-management-plan.md`](./l2-permission-management-plan.md)
> **상태**: API 개발 완료, React 연동 대기

- [x] **테이블 수정**
  - [x] `roles` 테이블에 `is_hidden` 컬럼 추가 마이그레이션

- [x] **API 엔드포인트** (9개)
  - [x] `GET /v1/roles` - 역할 목록
  - [x] `POST /v1/roles` - 역할 생성
  - [x] `GET /v1/roles/{id}` - 역할 상세
  - [x] `PATCH /v1/roles/{id}` - 역할 수정
  - [x] `DELETE /v1/roles/{id}` - 역할 삭제
  - [x] `GET /v1/roles/{id}/permissions` - 역할 권한 조회
  - [x] `POST /v1/roles/{id}/permissions` - 권한 추가
  - [x] `DELETE /v1/roles/{id}/permissions` - 권한 제거
  - [x] `PUT /v1/roles/{id}/permissions/sync` - 권한 동기화

- [x] **Swagger 문서**
  - [x] `RoleApi.php` 작성
  - [x] `RolePermissionApi.php` 작성

- [ ] **React 연동**
  - [ ] actions.ts 생성
  - [ ] 컴포넌트 API 연동
  - [ ] Mock 데이터 제거

---

### L-3 직급관리 ✅ + L-4 직책관리 ✅
> **완료일**: 2025-12-30
> **설계**: 직급(rank)과 직책(title)을 통합 `positions` 테이블로 구현

- [x] **테이블 생성**
  - [x] `positions` 마이그레이션 (type 컬럼으로 rank/title 구분)
  - [x] `common_codes`에 position_type 그룹 추가

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

- [x] **서비스 구현**
  - [x] `PositionService` 생성 (CRUD, reorder)

- [x] **API 엔드포인트** (6개)
  - [x] `GET /v1/positions?type=rank` - 직급 목록
  - [x] `GET /v1/positions?type=title` - 직책 목록
  - [x] `POST /v1/positions` - 생성 (type 필수)
  - [x] `PUT /v1/positions/{id}` - 수정
  - [x] `DELETE /v1/positions/{id}` - 삭제
  - [x] `POST /v1/positions/reorder` - 순서 변경 (bulk)

- [x] **Swagger 문서**
  - [x] `PositionApi.php` 작성

- [x] **React 연동**
  - [x] `lib/api/positions.ts` API 클라이언트
  - [x] `RankManagement/` 컴포넌트 API 연동
  - [x] `TitleManagement/` 컴포넌트 API 연동
  - [x] 드래그 앤 드롭 순서 저장

---

### L-5 출퇴근설정 🟡
> **상태**: 부분 완료 - 부서 목록 API 연동 필요

- [x] 출퇴근 설정 API 연동 완료
- [ ] `MOCK_DEPARTMENTS` → `getDepartments()` API 연동 필요

---

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

> ⚠️ **기존 코드베이스 분석 결과 반영** (2025-12-18)
> - 구독/결제: 이미 모델 존재 → 신규 테이블 불필요, API 확장만 필요
> - 고객센터: mng 게시판 기능으로 대체 가능 → 신규 개발 불필요

### 3.6 구독/결제 관리 (기존 모델 확장)

**기존 구성요소 (이미 존재):**
| 항목 | 위치 | 상태 |
|------|------|------|
| `Plan` 모델 | `api/app/Models/Tenants/Plan.php` | ✅ 완성 |
| `Subscription` 모델 | `api/app/Models/Tenants/Subscription.php` | ✅ 완성 |
| `Payment` 모델 | `api/app/Models/Tenants/Payment.php` | ✅ 완성 |
| 테넌트 구독 조회 | `api/admin/tenants/{id}/subscription` | ✅ 라우트 존재 |
| 관리 페이지 | `public/tenant/subscription/` | ✅ 3개 파일 |

**기존 스키마:**
```php
// Plan: name, code, description, price, billing_cycle, features(json), is_active
// Subscription: tenant_id, plan_id, started_at, ended_at, status
// Payment: subscription_id, amount, payment_method, transaction_id, paid_at, status, memo
```

**추가 개발 필요 (API 확장):**
- [ ] **Plan API** (관리자용)
  - [ ] `GET /v1/admin/plans` - 요금제 목록
  - [ ] `POST /v1/admin/plans` - 요금제 등록
  - [ ] `PUT /v1/admin/plans/{id}` - 요금제 수정
  - [ ] `DELETE /v1/admin/plans/{id}` - 요금제 삭제

- [ ] **Subscription API** (테넌트용)
  - [ ] `GET /v1/subscriptions/current` - 현재 구독 조회
  - [ ] `POST /v1/subscriptions` - 구독 신청
  - [ ] `PUT /v1/subscriptions/{id}` - 구독 변경
  - [ ] `POST /v1/subscriptions/{id}/cancel` - 구독 해지

- [ ] **Payment API**
  - [ ] `GET /v1/payments` - 결제 내역
  - [ ] `POST /v1/payments` - 결제 처리 (PG 연동)
  - [ ] `GET /v1/payments/{id}` - 결제 상세

- [ ] **PG 연동** (별도 검토)
  - [ ] 토스페이먼츠 / 아임포트 연동
  - [ ] 자동결제(정기결제) 구현

- [ ] **Swagger 문서**
  - [ ] `PlanApi.php`, `SubscriptionApi.php`, `PaymentApi.php`

### 3.7 고객센터 (mng 게시판 활용)

**기존 구성요소 (이미 존재 - mng):**
| 항목 | 위치 | 상태 |
|------|------|------|
| `Board` 모델 | `mng/app/Models/Boards/Board.php` | ✅ 완성 |
| `Post` 모델 | `mng/app/Models/Boards/Post.php` | ✅ 완성 |
| `BoardSetting` | `mng/app/Models/Boards/BoardSetting.php` | ✅ 동적 필드 지원 |
| `BoardService` | `mng/app/Services/BoardService.php` | ✅ 520줄 |
| API 라우트 | `api/admin/boards/*` | ✅ 20개+ 라우트 |

**게시판 구조:**
- `is_system = true` → 시스템 전체용 (공지사항, FAQ)
- `is_system = false` → 테넌트별 개별 게시판 (문의게시판)
- 템플릿 기반 생성 지원 (`createBoardFromTemplate`)

**추가 개발 필요 (템플릿 추가):**
- [ ] **게시판 템플릿 정의** (`config/board_templates.php`)
  - [ ] `faq` - FAQ 게시판 템플릿
  - [ ] `inquiry` - 1:1 문의 템플릿
  - [ ] `notice` - 공지사항 템플릿

- [ ] **API 라우트 확장** (api 프로젝트)
  - [ ] `GET /v1/boards/{code}/posts` - 게시글 목록 (사용자용)
  - [ ] `POST /v1/boards/{code}/posts` - 게시글 작성
  - [ ] `GET /v1/boards/{code}/posts/{id}` - 게시글 상세

- [ ] **Swagger 문서**
  - [ ] `BoardApi.php` (사용자용 API)

**참고:** mng의 `BoardService`는 시스템/테넌트 게시판 모두 지원하므로 신규 테이블 생성 불필요

---

## 📋 기획 확인 필요 항목

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

- [x] **카드/계좌 관리 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 사용)
  - 대표계좌 자동 설정 로직

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

- [x] **대시보드 API 구현 완료**
  - 서비스 1개 (`DashboardService`)
  - 컨트롤러 1개 (`DashboardController`)
  - FormRequest 2개 (`DashboardChartsRequest`, `DashboardApprovalsRequest`)
  - API 엔드포인트 3개 (summary, charts, approvals)
  - Swagger 문서 (`DashboardApi.php`)
  - i18n 메시지/에러 키 추가
  - 통계 집계 로직 (오늘 현황, 재무, 매출/매입, 할 일)
  - 차트 데이터 (입금/출금 추이, 거래처별 매출 상위 10)
  - ※ notifications는 Push 기능과 함께 개발 예정

- [x] **API 품질 점검 및 수정** (커밋: `c7eee97`)
  - Pint 스타일 이슈 25개 자동 수정 (783 파일 통과)
  - 마이그레이션 4개 실행 (payrolls, payroll_settings, push_device_tokens, push_notification_settings)
  - PHP 문법 검사 통과
  - Swagger 문서 재생성 완료
  - 라우트 로딩 테스트 통과 (471개 엔드포인트)

- [x] **AI 리포트 API 구현 완료** (커밋: `9864531`)
  - 마이그레이션 1개 (`ai_reports`)
  - 모델 1개 (`AiReport`)
  - 서비스 1개 (`AiReportService`)
  - 컨트롤러 1개, FormRequest 2개
  - API 엔드포인트 4개 (목록/생성/상세/삭제)
  - Swagger 문서 (`AiReportApi.php`)
  - i18n 메시지/에러 키 추가
  - Google Gemini API 연동
  - 비즈니스 데이터 수집 (매출/매입/입출금/미수금/카드/계좌)

- [x] **가지급금 관리 API 구현 완료** (커밋: `9b3dd2f`)
  - 마이그레이션 1개 (`loans`)
  - 모델 1개 (`Loan`)
  - 서비스 1개 (`LoanService` - 인정이자 계산 포함)
  - 컨트롤러 1개, FormRequest 5개
  - API 엔드포인트 9개
  - Swagger 문서 (`LoanApi.php`)

- [x] **바로빌 세금계산서 연동 API 구현 완료** (커밋: `8ad4d7c`)
  - 마이그레이션 2개 (`barobill_settings`, `tax_invoices`)
  - 모델 2개 (`BarobillSetting`, `TaxInvoice`)
  - 서비스 2개 (`BarobillService`, `TaxInvoiceService`)
  - 컨트롤러 2개, FormRequest 6개
  - API 엔드포인트 12개
  - Swagger 문서 2개 (`BarobillSettingApi.php`, `TaxInvoiceApi.php`)
  - 바로빌 API 연동 (테스트/운영 환경 구분)
  - 인증서 키 암호화 (Laravel Crypt)
  - 세금계산서 발행/취소/상태조회/통계

- [x] **Phase 4 계획 수정** (기존 코드베이스 분석 반영)
  - 구독/결제: `Plan`, `Subscription`, `Payment` 모델 이미 존재 → 신규 테이블 불필요
  - 고객센터: mng 게시판 기능(`Board`, `Post`, `BoardService`)으로 대체 가능
  - 계획 문서 수정: 신규 개발 → 기존 모델 확장으로 변경

### 2025-12-30
- [x] **Phase L 설정 및 기준정보 개발**
  - L-2 권한관리 API 개발 완료 (React 연동 대기)
  - L-3 직급관리 + L-4 직책관리 완료 (통합 positions 테이블)
  - 마이그레이션 2개, 모델 1개, 서비스 2개, 컨트롤러 2개
  - API 엔드포인트 15개 (Role 9개 + Position 6개)
  - Swagger 문서 3개 (RoleApi, RolePermissionApi, PositionApi)
  - React API 클라이언트 및 컴포넌트 연동 (직급/직책)

### 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/dev_plans/SAM_ERP_Storyboard_D0.8_251216/`