# React ↔ API 연동 마스터 플랜

> **프로젝트**: SAM ERP 프론트엔드-백엔드 연동
> **시작일**: 2025-12-20
> **목표**: React(dev.sam.kr) 화면이 API(api.sam.kr)와 완벽하게 연동되어 정상 작동

---

## 1. 프로젝트 개요

### 1.1 배경
- React와 API가 동일 기획서 기반으로 개발되었으나, 문서 없이 독립 개발
- 프론트엔드와 백엔드의 관점 차이로 API 불일치 발생
- 연동 및 오류 수정 작업 필요

### 1.2 핵심 원칙
| 원칙 | 설명 |
|------|------|
| **React 기준** | 화면 요구사항에 맞게 API 수정/신규 개발 |
| **시스템 구조 예외** | items 통합 등 구조 변경은 정책 기반 처리 |
| **문서화 우선** | 모든 작업은 문서화하여 세션 간 연속성 보장 |

### 1.3 현황 분석 결과 (2025-12-20)

#### API 프로젝트
- **테이블 통합 완료**: `products` + `materials` → `items` (2025-12-13)
- **총 엔드포인트**: 약 325개 (8개 주요 도메인)
- **인증 방식**: API Key + Bearer Token (Sanctum)
- **Swagger 문서**: 69개 파일

#### React 프로젝트
- **프레임워크**: Next.js 15.5.7 + React 19
- **라우팅**: App Router ([locale]/(protected)/*)
- **API 클라이언트**: Native Fetch (axios 미사용)
- **인증**: HttpOnly Cookie + Bearer Token
- **목업 데이터**: 없음 (모든 데이터 실시간 API 호출)

---

## 2. 작업 Phase 정의

### Phase 0: 사전 분석 ✅ 완료
- [x] API 프로젝트 구조 분석
- [x] React 프로젝트 구조 분석
- [x] 테이블 통합 현황 확인 (items 완료)
- [x] 문서 구조 생성

### Phase 1: 테이블 통합 검증 (🟢 확인됨 - 스킵 가능)
**상태**: items 테이블 통합 이미 완료 (2025-12-13)

- [x] products/materials → items 마이그레이션 완료
- [x] ItemsController, ItemService 통합 완료
- [x] BOM 관리 items/{id}/bom으로 통합
- [ ] 레거시 참조 정리 확인 (옵션)

### Phase 2: React 라우터 → 메뉴 추출 (병행 작업)
**목표**: React 라우트 기반 메뉴 등록

체크리스트:
- [ ] React 전체 라우트 목록 추출
- [ ] 메뉴 구조 정리 (계층, 이름, URL)
- [ ] mng 메뉴 등록 포맷 생성
- [ ] 권한 매핑 정의

**산출물**: `phase-2-menu-extraction/menu-list.md`

### Phase 3: React ↔ API 매핑 분석
**목표**: 화면별 필요 API 식별 및 Gap 분석

체크리스트:
- [ ] React 페이지별 API 호출 분석
- [ ] 기존 API 엔드포인트 매핑
- [ ] 신규 개발 필요 API 식별
- [ ] 수정 필요 API 식별
- [ ] 중복/유사 API 정리

**산출물**: `phase-3-api-mapping/mapping-matrix.md`

### Phase 4: 연동 작업 + 오류 수정
**목표**: 실제 연동 및 오류 해결

작업 그룹:
1. **인증/메뉴**: 로그인, 메뉴 로드, 권한 체크
2. **품목 관리**: Items CRUD, BOM, 파일
3. **거래처/판매**: 거래처, 견적, 주문
4. **인사/재무**: 사원, 근태, 급여
5. **기타 기능**: 게시판, 설정, 대시보드

**산출물**: `phase-4-integration/integration-log.md`

### Phase 5: 최종 검증 및 리포트
**목표**: 전체 기능 검증 및 문서화

체크리스트:
- [ ] 전체 기능 테스트
- [ ] 오류 리스트 정리
- [ ] 변경 내역 정리
- [ ] 최종 리포트 작성

**산출물**: `FINAL_REPORT.md`

---

## 3. 주요 연동 대상 (React 페이지 기준)

### 3.1 핵심 기능 (우선순위 높음)
| 카테고리 | 페이지 | API 엔드포인트 | 상태 |
|----------|--------|----------------|------|
| 인증 | /login | POST /login | ✅ 연동됨 |
| 대시보드 | /dashboard | GET /dashboard/* | 🔍 확인 필요 |
| 품목 | /items | GET/POST/PUT/DELETE /items | 🔍 확인 필요 |
| 품목 BOM | /items/[id] | GET/POST /items/{id}/bom | 🔍 확인 필요 |

### 3.2 업무 기능
| 카테고리 | 페이지 | API 그룹 | 상태 |
|----------|--------|----------|------|
| 회계-매출 | /accounting/sales | /sales/* | 🔍 확인 필요 |
| 회계-매입 | /accounting/purchase | /purchases/* | 🔍 확인 필요 |
| 거래처 | /accounting/vendors | /clients/* | 🔍 확인 필요 |
| 영업-견적 | /sales/quote-management | /quotes/* | 🔍 확인 필요 |
| 영업-단가 | /sales/pricing-management | /pricing/* | 🔍 확인 필요 |

### 3.3 관리 기능
| 카테고리 | 페이지 | API 그룹 | 상태 |
|----------|--------|----------|------|
| HR-사원 | /hr/employee-management | /employees/* | 🔍 확인 필요 |
| HR-근태 | /hr/attendance | /attendances/* | 🔍 확인 필요 |
| 설정-권한 | /settings/permissions | /roles/* | 🔍 확인 필요 |
| 게시판 | /board | /boards/*, /posts/* | 🔍 확인 필요 |

---

## 4. 기술 스택 참조

### 4.1 React (프론트엔드)
```yaml
Framework: Next.js 15.5.7
React: 19.2.1
UI: shadcn/ui (Radix UI + Tailwind CSS)
Form: React Hook Form 7.66 + Zod 4.1
State: Zustand 5.0.8
i18n: next-intl 4.4.0
HTTP: Native Fetch API
```

### 4.2 API (백엔드)
```yaml
Framework: Laravel 12
PHP: 8.4+
Auth: Sanctum (Bearer Token)
Multi-tenant: BelongsToTenant scope
API Version: v1 (/api/v1/*)
Swagger: L5-Swagger
```

### 4.3 React API 호출 패턴
```typescript
// 프록시 패턴: /api/proxy/* → PHP /api/v1/*
// HttpOnly 쿠키에서 토큰 자동 추출
fetch('/api/proxy/items', {
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' }
});
```

---

## 5. 문서 구조

```
docs/projects/api-integration/
├── MASTER_PLAN.md              # 이 문서
├── PROGRESS.md                 # 진행 상황 추적
├── WORKFLOW.md                 # 작업 프로세스
├── react-api-guide.md          # React API 연동 가이드
│
├── phase-1-table-migration/    # 🟢 완료 (스킵)
│   └── README.md
│
├── phase-2-menu-extraction/    # 🟡 병행
│   ├── README.md
│   ├── react-routes-analysis.md
│   └── menu-list.md
│
├── phase-3-api-mapping/        # 🔵 순차
│   ├── README.md
│   ├── api-endpoints-list.md
│   ├── mapping-matrix.md
│   └── gap-analysis.md
│
├── phase-4-integration/        # 🔵 순차
│   ├── README.md
│   ├── integration-log.md
│   ├── api-changes.md
│   └── issues/
│
├── FINAL_REPORT.md
└── appendix/
    ├── api-analysis.json       # API 분석 원본
    └── react-analysis.json     # React 분석 원본
```

---

## 6. 세션 영속성

### 6.1 Serena 메모리
```
api-integration-state.md     # 현재 phase, task, 다음 액션
api-integration-context.md   # 결정사항, 임시 메모
```

### 6.2 세션 복구
1. `serena.list_memories()` → 상태 확인
2. `PROGRESS.md` → 상세 진행상황
3. "다음 액션"부터 재개

---

## 7. 참조 문서

- [PROJECT_DEVELOPMENT_POLICY.md](../../../docs/guides/PROJECT_DEVELOPMENT_POLICY.md)
- [CLAUDE.md](../../../CLAUDE.md)
- [API_RULES.md](../../../API_RULES.md)

---

## 변경 이력

| 날짜 | 변경 내용 | 작성자 |
|------|----------|--------|
| 2025-12-20 | 초기 마스터 플랜 작성 | Claude |