SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5e1e5b4fcfbb9df3c694a568037207017d51ef5b
sam-docs/projects/api-integration/phase-3-api-mapping/gap-analysis.md
kent 2d9b02f74e docs: API 통합 프로젝트 계획 및 Flow Test 스펙 추가 
- INDEX.md: TODO.md 링크 추가
- TODO.md: 프로젝트 할일 목록 신규 생성
- plans/flow-tests/: Flow Tester 테스트 시나리오 JSON 추가
  - auth-api-flow.json: 인증 API 플로우 테스트
  - pricing-validation-test.json: 가격 검증 테스트
- projects/api-integration/: 마이그레이션 계획 문서
  - MASTER_PLAN.md: 전체 마이그레이션 전략
  - PROGRESS.md: 진행 상황 추적
  - WORKFLOW.md: 작업 워크플로우
  - phase-1 ~ phase-4: 단계별 상세 계획

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-21 01:35:43 +09:00

363 lines
8.8 KiB
Markdown
Raw Blame History

# 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 분석의 일부로 작성되었습니다.*
Reference in New Issue View Git Blame Copy Permalink