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 구조 완벽 파악

체크리스트:

• 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 시스템

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

3.2 SAM 시스템

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