# Gap 분석 보고서

> **작성일**: 2025-12-20
> **분석 범위**: React ↔ Laravel API 연동 현황
> **목적**: Mock 데이터 → 실제 API 전환을 위한 우선순위 도출

---

## Executive Summary

### 현재 상태

| 지표 | 값 |
|------|-----|
| 총 React 페이지 | 109개 |
| API 연동 완료 | 8개 (7.3%) |
| Mock 데이터 사용 | 95개 (87.2%) |
| 부분 연동 | 4개 (3.7%) |
| 미구현 | 2개 (1.8%) |

### 핵심 발견사항

1. **Items + Master Data 모듈만 완전 연동** (100%)
2. **Sales 모듈 절반 연동** (거래처/단가 O, 견적/주문 X)
3. **나머지 8개 모듈은 전체 Mock 데이터** (Accounting, HR, Board, Approval, Settings, Dashboard, Reports, Production, Customer Center)
4. **권한 관리는 localStorage 사용** → API 전환 필요

---

## 1. 모듈별 Gap 분석

### 1.1 ✅ 완료 모듈 (연동률 100%)

#### Items 모듈
- **상태**: 완전 연동
- **Gap**: 없음
- **비고**: 파일 업로드, BOM 관리 포함

#### Master Data 모듈
- **상태**: 완전 연동
- **Gap**: 없음
- **비고**: 50+ 마스터 데이터 API 연동

---

### 1.2 🟡 부분 연동 모듈

#### Sales 모듈 (50% 연동)

| 기능 | 상태 | Gap |
|------|------|-----|
| 거래처 관리 | ✅ | - |
| 단가 관리 | ✅ | - |
| 견적 관리 | 🆕 | `QuoteController` 필요 |
| 주문 관리 | 🆕 | `OrderController` 필요 |
| 영업 실적 | 🆕 | 리포트 API 필요 |

**필요 API 목록**:
```
POST   /api/v1/quotes
GET    /api/v1/quotes
GET    /api/v1/quotes/{id}
PUT    /api/v1/quotes/{id}
DELETE /api/v1/quotes/{id}
POST   /api/v1/quotes/{id}/send
POST   /api/v1/quotes/{id}/convert-to-order

GET    /api/v1/orders
POST   /api/v1/orders
GET    /api/v1/orders/{id}
PUT    /api/v1/orders/{id}

GET    /api/v1/reports/sales-performance
```

---

### 1.3 🔴 Mock 데이터 모듈 (연동률 0%)

#### Accounting 모듈 (17 페이지)

**현재 상태**: 모든 페이지에서 `generateMockData()` 함수 사용

**필요 API 우선순위**:

| 우선순위 | 기능 | 필요 API | 복잡도 |
|---------|------|----------|--------|
| 🔴 높음 | 매출 관리 | `SalesController` CRUD | 중 |
| 🔴 높음 | 매입 관리 | `PurchaseController` CRUD | 중 |
| 🔴 높음 | 수금 관리 | `CollectionController` CRUD | 중 |
| 🔴 높음 | 지급 관리 | `PaymentController` CRUD | 중 |
| 🟡 중간 | 전표 관리 | `SlipController` CRUD | 상 |
| 🟡 중간 | 세금계산서 | `TaxInvoiceController` + 외부연동 | 상 |
| 🟢 낮음 | 장부 조회 | `LedgerController` (조회 전용) | 하 |
| 🟢 낮음 | 결산 | `ClosingController` | 상 |

**예상 개발 규모**: Controller 8개, 모델 10+개

---

#### HR 모듈 (9 페이지)

**현재 상태**: 모든 페이지에서 Mock 데이터 사용

**필요 API 우선순위**:

| 우선순위 | 기능 | 필요 API | 복잡도 |
|---------|------|----------|--------|
| 🔴 높음 | 사원 관리 | `EmployeeController` CRUD | 중 |
| 🔴 높음 | 부서 관리 | `DepartmentController` CRUD | 하 |
| 🔴 높음 | 근태 관리 | `AttendanceController` + 출퇴근 | 중 |
| 🟡 중간 | 휴가 관리 | `LeaveController` + 승인 | 중 |
| 🟡 중간 | 급여 관리 | `SalaryController` + 계산 | 상 |
| 🟢 낮음 | 카드 관리 | `EmployeeCardController` | 하 |
| 🟢 낮음 | HR 설정 | `HrSettingController` | 하 |

**예상 개발 규모**: Controller 7개, 모델 8+개

---

#### Board 모듈 (6 페이지)

**현재 상태**: Mock 데이터 사용

**필요 API**:
```
GET    /api/v1/boards
GET    /api/v1/boards/{boardType}/posts
POST   /api/v1/boards/{boardType}/posts
GET    /api/v1/posts/{id}
PUT    /api/v1/posts/{id}
DELETE /api/v1/posts/{id}
POST   /api/v1/posts/{id}/comments
GET    /api/v1/posts/{id}/files
POST   /api/v1/posts/{id}/files
```

**예상 개발 규모**: Controller 3개, 모델 3개

---

#### Approval 모듈 (4 페이지)

**현재 상태**: Mock 데이터 사용

**필요 API**:
```
GET    /api/v1/approvals
POST   /api/v1/approvals
GET    /api/v1/approvals/{id}
POST   /api/v1/approvals/{id}/approve
POST   /api/v1/approvals/{id}/reject
GET    /api/v1/approval-templates
GET    /api/v1/approval-lines
POST   /api/v1/approval-lines
```

**예상 개발 규모**: Controller 3개, 모델 4개

---

#### Settings 모듈 (10 페이지)

**현재 상태**:
- 권한 관리: localStorage 사용 (⚠️ 보안 이슈)
- 기타: Mock 데이터

**필요 API**:
```
# 권한 관리 (우선순위 높음)
GET    /api/v1/permissions
POST   /api/v1/permissions
GET    /api/v1/roles
POST   /api/v1/roles
PUT    /api/v1/roles/{id}/permissions

# 사용자 관리
GET    /api/v1/users
POST   /api/v1/users
PUT    /api/v1/users/{id}

# 메뉴 관리
GET    /api/v1/menus
PUT    /api/v1/menus

# 시스템 설정
GET    /api/v1/settings
PUT    /api/v1/settings
```

**⚠️ 특별 주의**: 권한 관리 localStorage → API 전환 우선

---

#### Dashboard 모듈 (1 페이지)

**현재 상태**: 빈 페이지 (미구현)

**필요 API**:
```
GET /api/v1/dashboard/summary
GET /api/v1/dashboard/sales-chart
GET /api/v1/dashboard/inventory-status
GET /api/v1/dashboard/recent-activities
GET /api/v1/dashboard/pending-approvals
```

---

#### Reports 모듈 (2 페이지)

**현재 상태**: Mock 데이터

**필요 API**:
```
GET /api/v1/reports/sales
GET /api/v1/reports/purchase
GET /api/v1/reports/inventory
GET /api/v1/reports/financial
GET /api/v1/reports/comprehensive
```

---

#### Customer Center 모듈 (6 페이지)

**현재 상태**: Mock 데이터

**필요 API**:
```
GET    /api/v1/notices
GET    /api/v1/faqs
GET    /api/v1/inquiries
POST   /api/v1/inquiries
GET    /api/v1/inquiries/{id}
```

---

#### Production 모듈 (4 페이지)

**현재 상태**: Mock 데이터 (초기 개발 단계)

**필요 API**:
```
GET    /api/v1/production-orders
POST   /api/v1/production-orders
GET    /api/v1/production-orders/{id}
PUT    /api/v1/production-orders/{id}
POST   /api/v1/production-orders/{id}/start
POST   /api/v1/production-orders/{id}/complete
GET    /api/v1/work-orders
POST   /api/v1/work-performance
```

---

## 2. 우선순위 권장사항

### Phase 1: 핵심 비즈니스 (1-2주)

| 순위 | 모듈 | 작업 | 이유 |
|------|------|------|------|
| 1 | Settings | 권한 API 전환 | 🔴 보안 이슈 |
| 2 | Sales | 견적 관리 API | 핵심 영업 기능 |
| 3 | Accounting | 매출/매입 API | 핵심 회계 기능 |

### Phase 2: 운영 지원 (2-3주)

| 순위 | 모듈 | 작업 | 이유 |
|------|------|------|------|
| 4 | HR | 사원/근태 API | 기본 인사 관리 |
| 5 | Approval | 결재 시스템 API | 업무 프로세스 |
| 6 | Board | 게시판 API | 커뮤니케이션 |

### Phase 3: 부가 기능 (3-4주)

| 순위 | 모듈 | 작업 | 이유 |
|------|------|------|------|
| 7 | Dashboard | 대시보드 API | 경영 현황 |
| 8 | Reports | 리포트 API | 분석 기능 |
| 9 | Customer Center | 고객센터 API | 지원 기능 |
| 10 | Production | 생산 관리 API | 제조 기능 |

---

## 3. 기술적 Gap

### 3.1 API 클라이언트 패턴 불일치

| 패턴 | 사용처 | 문제점 |
|------|--------|--------|
| `/api/proxy/*` | Items, Clients | ✅ 표준 패턴 |
| `/api/v1/*` | Pricing | Server Actions 사용 |
| `generateMockData()` | 대부분 | Mock 데이터 |

**권장사항**: `/api/proxy/*` 패턴으로 통일

### 3.2 인증 토큰 처리

- **현재**: HttpOnly Cookie (access_token)
- **문제**: 일부 페이지에서 토큰 갱신 미처리
- **권장**: 토큰 갱신 미들웨어 적용

### 3.3 에러 처리

- **현재**: 페이지별 개별 처리
- **권장**: 글로벌 에러 핸들러 + Toast 알림 통일

---

## 4. 개발 예상 규모

### API 개발 (Laravel)

| 항목 | 수량 |
|------|------|
| 신규 Controller | 25+ |
| 신규 Model | 30+ |
| 신규 Migration | 20+ |
| FormRequest | 40+ |
| Resource | 30+ |

### React 연동

| 항목 | 수량 |
|------|------|
| API 클라이언트 함수 | 80+ |
| Mock → API 전환 페이지 | 95개 |
| 새 타입 정의 | 50+ |

---

## 5. 리스크 및 대응

| 리스크 | 영향도 | 대응 방안 |
|--------|--------|----------|
| 권한 관리 localStorage | 🔴 높음 | 즉시 API 전환 필요 |
| Mock 데이터 의존도 | 🟡 중간 | 점진적 전환 |
| API 응답 형식 불일치 | 🟡 중간 | Resource 클래스 표준화 |
| 다중 테넌트 미적용 | 🔴 높음 | BelongsToTenant 확인 |

---

## 6. 다음 단계 권장

1. **즉시 조치**
   - [ ] Settings 권한 API 개발 및 localStorage 제거
   - [ ] API 응답 표준 정의 (Resource 클래스)

2. **Phase 4 준비**
   - [ ] 영업 모듈 견적 API 개발
   - [ ] 회계 모듈 매출/매입 API 개발

3. **표준화 작업**
   - [ ] API 클라이언트 패턴 통일
   - [ ] 에러 처리 글로벌화
   - [ ] 토큰 갱신 자동화

---

*이 문서는 Phase 3 API 분석의 일부로 작성되었습니다.*