sam-docs/projects/api-integration/MASTER_PLAN.md

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: 사전 분석 ✅ 완료

• API 프로젝트 구조 분석
• React 프로젝트 구조 분석
• 테이블 통합 현황 확인 (items 완료)
• 문서 구조 생성

Phase 1: 테이블 통합 검증 (🟢 확인됨 - 스킵 가능)

상태: items 테이블 통합 이미 완료 (2025-12-13)

• products/materials → items 마이그레이션 완료
• ItemsController, ItemService 통합 완료
• 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 (프론트엔드)

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 (백엔드)

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 호출 패턴

// 프록시 패턴: /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
• CLAUDE.md
• API_RULES.md

---

변경 이력

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