sam-docs/projects/5130-migration/MASTER_PLAN.md

# 5130 → SAM 품목 마이그레이션 마스터 플랜

> **프로젝트**: 5130 품목(부품, 자재, BOM) 데이터를 SAM API/MNG DB로 이전
> **시작일**: 2025-12-21
> **목표**: 5130의 item 관련 데이터를 SAM 구조에 맞게 마이그레이션

---

## 1. 프로젝트 개요

### 1.1 배경
- 5130(경동기업 레거시)과 SAM(신규 ERP)의 DB 구조가 상이
- 수작업 데이터 입력은 불가능한 데이터 볼륨
- 구조 분석 → 매핑 → 마이그레이션 전략 필요

### 1.2 핵심 원칙
| 원칙 | 설명 |
|------|------|
| **분석 우선** | 양쪽 구조를 완벽히 파악 후 작업 |
| **문서화 필수** | 모든 매핑/변환 규칙 문서화 |
| **반복 검증** | 테스트 마이그레이션 → 수정 → 재시도 |
| **롤백 가능** | 실패 시 복구 가능한 전략 |

### 1.3 대상 테이블 (5130)
| 테이블 | 설명 | 우선순위 |
|--------|------|----------|
| `items` | 품목 기본 정보 | 🔴 필수 |
| `item_sections` | 품목 섹션 | 🔴 필수 |
| `item_pages` | 품목 페이지 | 🟡 중요 |
| `item_id_mappings` | ID 매핑 관계 | 🟡 중요 |
| `item_fields` | 필드 정의 | 🔴 필수 |
| `item_details` | 품목 상세 데이터 | 🔴 필수 |
| `item_bom_items` | BOM 구성 | 🔴 필수 |
| `entity_relationships` | 엔티티 관계 | 🟡 중요 |

---

## 2. 작업 Phase 정의

### Phase 1: 소스 분석 (5130) 🔵 진행중
**목표**: 5130 DB 구조 완벽 파악

체크리스트:
- [x] 5130/docs 문서 확인
- [ ] Item 관련 테이블 스키마 조회 (DB 직접)
- [ ] 테이블 간 관계도 작성
- [ ] 데이터 샘플 확인
- [ ] 데이터 볼륨 파악

**산출물**: `phase-1-source-analysis/`
- `5130-item-schema.md` - 테이블 스키마
- `5130-item-relations.md` - 테이블 관계도
- `5130-data-samples.md` - 데이터 샘플

### Phase 2: 타겟 분석 (SAM) ⚪ 대기
**목표**: SAM API/MNG DB 구조 파악

체크리스트:
- [ ] api/docs 문서 확인
- [ ] SAM items 테이블 스키마 확인
- [ ] API 엔드포인트 구조 확인
- [ ] Multi-tenant 구조 파악

**산출물**: `phase-2-target-analysis/`
- `sam-item-schema.md`
- `sam-api-endpoints.md`

### Phase 3: 매핑 설계 ⚪ 대기
**목표**: 5130 → SAM 변환 규칙 정의

체크리스트:
- [ ] 필드 매핑 테이블 작성
- [ ] 타입 변환 규칙 정의
- [ ] 관계 매핑 정의
- [ ] 누락/추가 필드 식별
- [ ] 데이터 변환 함수 설계

**산출물**: `phase-3-mapping/`
- `field-mapping.md` - 필드 매핑 테이블
- `transform-rules.md` - 변환 규칙
- `gap-analysis.md` - Gap 분석

### Phase 4: 마이그레이션 개발 ⚪ 대기
**목표**: 마이그레이션 스크립트 개발

체크리스트:
- [ ] 마이그레이션 스크립트 설계
- [ ] 순서 결정 (의존성 기반)
- [ ] 검증 쿼리 작성
- [ ] 롤백 스크립트 작성

**산출물**: `phase-4-migration/`
- `migration-order.md`
- `scripts/` (마이그레이션 스크립트)
- `validation/` (검증 쿼리)

### Phase 5: 실행 및 검증 ⚪ 대기
**목표**: 실제 마이그레이션 및 검증

체크리스트:
- [ ] 테스트 환경 마이그레이션
- [ ] 데이터 정합성 검증
- [ ] 오류 수정 및 재시도
- [ ] 최종 마이그레이션
- [ ] 완료 리포트 작성

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

---

## 3. 참조 정보

### 3.1 5130 시스템
```yaml
DB명: chandj
엔진: MySQL 8.0
PHP: 7.3
도메인: 5130.co.kr, 5130.sam.kr (개발)
회사: 경동기업, 주일철강
```

### 3.2 SAM 시스템
```yaml
Framework: Laravel 12
PHP: 8.4+
Multi-tenant: tenant_id 기반
DB: items 테이블 (products + materials 통합 완료)
```

### 3.3 주요 문서
- 5130: `5130/docs/DATABASE.md`, `MODULES.md`, `README.md`
- SAM: `api/docs/`, `docs/guides/PROJECT_DEVELOPMENT_POLICY.md`
- 워크플로우: `docs/guides/common-workflow-framework.md`

---

## 4. 문서 구조

```
docs/projects/5130-migration/
├── MASTER_PLAN.md              # 이 문서
├── PROGRESS.md                 # 진행 상황 추적
│
├── phase-1-source-analysis/    # 🔵 진행중
│   ├── README.md
│   ├── 5130-item-schema.md
│   ├── 5130-item-relations.md
│   └── 5130-data-samples.md
│
├── phase-2-target-analysis/    # ⚪ 대기
│   ├── README.md
│   ├── sam-item-schema.md
│   └── sam-api-endpoints.md
│
├── phase-3-mapping/            # ⚪ 대기
│   ├── README.md
│   ├── field-mapping.md
│   ├── transform-rules.md
│   └── gap-analysis.md
│
├── phase-4-migration/          # ⚪ 대기
│   ├── README.md
│   ├── migration-order.md
│   ├── scripts/
│   └── validation/
│
└── FINAL_REPORT.md
```

---

## 5. 세션 영속성

### 5.1 Serena 메모리
```
5130-migration-state    → 현재 phase, task, 다음 액션
5130-migration-context  → 분석 결과, 결정사항, 참조
```

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

### 5.3 업데이트 시점
| 시점 | 행동 |
|------|------|
| 세션 시작 | `read_memory(state)` → 이어서 진행 |
| Phase 완료 | `write_memory(state)` + PROGRESS.md |
| 중요 발견 | `write_memory(context)` |
| 세션 종료 | 양쪽 최종 저장 |

---

## 6. 작업 프로세스

### 6.1 기본 원칙 (common-workflow-framework 참조)
- **분석 작업**: 분석 → 문서화 → 확인
- **마이그레이션**: 설계 → 개발 → 테스트 → 수정 (반복)

### 6.2 단계별 프로세스
| Phase | 유형 | 프로세스 |
|-------|------|----------|
| 1-2 | 분석 | 조사 → 문서화 → 검토 |
| 3 | 설계 | 매핑 → 규칙정의 → 검토 |
| 4 | 개발 | 스크립트 → 테스트 → 수정 |
| 5 | 실행 | 마이그레이션 → 검증 → 수정 (반복) |

---

## 7. 현재 상태

### 7.1 Phase 1 진행 현황
- ✅ 5130/docs 문서 확인 완료
- ⚠️ Item 테이블 스키마가 문서에 없음 → DB 직접 조회 필요
- ⏳ 다음 액션: 5130 DB에서 Item 테이블 스키마 조회

### 7.2 발견 사항
- 5130/docs에는 `output`, `estimate`, `instock`, `eworks` 등 업무 테이블만 문서화
- Item 관련 8개 테이블은 문서 미작성 → 실제 DB에서 직접 분석 필요

---

## 변경 이력

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