SamProject/sam-docs
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2d9b02f74e77e42b68fff1f61866bbc456bc8a8b
sam-docs/projects/api-integration/MASTER_PLAN.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

232 lines
7.0 KiB
Markdown
Raw Blame History

# 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 |
Reference in New Issue View Git Blame Copy Permalink