sam-docs/projects/api-integration/phase-3-api-mapping/gap-analysis.md

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 분석의 일부로 작성되었습니다.