sam-docs/projects/mes/00_baseline/STEP_0_1_ANALYSIS_STRATEGY.md

Step 0.1: 기존 시스템 분석 전략

목표: 기존 API 및 mes_react 프로젝트의 MD 문서를 먼저 검토하고, 컨텍스트 누락 방지를 위해 쪼개서 문서화

작업 방식: 문서 우선 검토 → 코드 분석 → 쪼개서 저장 → 후속 단계에서 활용

---

📚 발견된 기존 문서 목록

API 프로젝트 문서 (api/)

핵심 분석 문서:

1. claudedocs/SAM_Item_DB_API_Analysis_v3_FINAL.md ⭐ 최신 품목 분석
2. claudedocs/SAM_Item_Management_DB_Modeling_Analysis.md ⭐ DB 모델링 분석
3. claudedocs/SAM_Item_DB_API_Analysis_v2.md (v2 버전)
4. LOGICAL_RELATIONSHIPS_SIMPLE.md (관계 다이어그램)

Swagger 문서: 5. claudedocs/SWAGGER_PHASE3_1_PRODUCT.md (제품 API) 6. claudedocs/SWAGGER_PHASE3_2_MATERIAL.md (자재 API) 7. claudedocs/SWAGGER_PHASE3_3_CLIENT.md (고객 API) 8. claudedocs/SWAGGER_AUDIT.md (Swagger 감사)

기타: 9. REMOTE_WORK_SETUP.md 10. resources/markdown/terms.md 11. resources/markdown/policy.md

---

MES React 프로젝트 문서 (mes_react/src/)

시스템 아키텍처 (우선순위 높음):

1. ATOMIC_DESIGN_SYSTEM.md ⭐ (40KB - Atomic Design 전체 구조)
2. DEVELOPMENT_GUIDELINES.md ⭐ (26KB - 개발 가이드라인)
3. TECH_STACK.md ⭐ (기술 스택)
4. DEVELOPMENT_ENVIRONMENT.md (개발 환경)
5. QUICK_START.md (빠른 시작 가이드)

화면 설계 (품목 관련): 6. SCREEN_DESIGN_SPECIFICATION.md ⭐ (41KB - 화면 설계 명세) 7. ERP_QUOTATION_GUIDE.md ⭐ (견적 시스템 가이드) 8. USER_STORY_GUIDE.md (사용자 스토리)

디자인 시스템: 9. DESIGN_SYSTEM_README.md 10. DESIGN_SYSTEM_QUICK_REFERENCE.md 11. DESIGN_SYSTEM_STANDARDIZATION_GUIDE.md 12. DESIGN_SYSTEM_COMPLETION_SUMMARY.md 13. DESIGN_STANDARDIZATION_PROGRESS.md

페이지 포맷: 14. STANDARD_PAGE_FORMAT.md 15. UNIFIED_PAGE_FORMAT_SUMMARY.md 16. PAGE_FORMAT_IMPLEMENTATION_GUIDE.md

테이블 시스템: 17. TABLE_DESIGN_SYSTEM.md 18. TABLE_SYSTEM_IMPLEMENTATION.md

컴포넌트: 19. COMMON_COMPONENTS_GUIDE.md 20. COMPONENT_HIERARCHY_REFERENCE.md 21. COMPONENT_CONSOLIDATION_PLAN.md

기타: 22. FORM_VALIDATION_GUIDE.md 23. DATA_INTEGRATION_GUIDE.md 24. MENU_ACCESS_GUIDE.md 25. ICON_STANDARDIZATION_CHECKLIST.md 26. ALL_PAGES_REFACTORING_PROGRESS.md 27. ATOMIC_DESIGN_MIGRATION_SUMMARY.md 28. CONSOLIDATION_PROGRESS.md 29. DESIGN_AUDIT_REPORT.md 30. FINAL_COMPLETION_SUMMARY.md 31. IMPLEMENTATION_SUMMARY.md 32. PHASE3_FINAL_SUMMARY.md 33. TITLE_STRUCTURE_STANDARDIZATION.md

---

🎯 분석 전략: 3단계 접근법

Phase A: 문서 우선 검토 및 매핑

목표: 기존 문서를 통해 전체 시스템 구조 파악

Step A.1: 핵심 문서 검토 (우선순위)

1. API 분석 문서 (3개)

   • SAM_Item_DB_API_Analysis_v3_FINAL.md (최신 버전 우선)
   • SAM_Item_Management_DB_Modeling_Analysis.md
   • LOGICAL_RELATIONSHIPS_SIMPLE.md

2. React 아키텍처 문서 (3개)

   • ATOMIC_DESIGN_SYSTEM.md
   • DEVELOPMENT_GUIDELINES.md
   • SCREEN_DESIGN_SPECIFICATION.md

3. 비즈니스 로직 문서 (2개)

   • ERP_QUOTATION_GUIDE.md
   • USER_STORY_GUIDE.md

Step A.2: 문서 내용 쪼개기

• 각 대형 문서(>10KB)를 주제별로 분리
• 쪼갠 문서를 00_baseline/docs_breakdown/ 폴더에 저장
• 메타데이터 추가 (출처, 작성일, 관련 모듈)

산출물:

00_baseline/docs_breakdown/
├─ api_item_analysis_summary.md         # API 분석 요약
├─ api_db_modeling.md                   # DB 모델링
├─ api_swagger_status.md                # Swagger 현황
├─ react_architecture.md                # React 아키텍처
├─ react_design_system.md               # 디자인 시스템
├─ react_screen_specs.md                # 화면 명세
├─ business_quotation.md                # 견적 비즈니스 로직
└─ document_cross_reference.md          # 문서 간 연관관계

---

Phase B: 코드 레벨 분석

목표: 실제 구현 코드 분석 및 문서와의 일치성 검증

Step B.1: API 프로젝트 구조 분석

• Routes 분석 (routes/api.php)
• Controllers 분석 (app/Http/Controllers/Api/V1/)
• Services 분석 (app/Services/)
• Models 분석 (app/Models/)
• Migrations 분석 (database/migrations/)

Step B.2: mes_react 프로젝트 구조 분석

• 라우팅 구조 (src/routes/)
• 페이지 컴포넌트 (src/pages/)
• 공통 컴포넌트 (src/components/)
• API 연동 (src/api/, src/hooks/)
• 상태 관리 (src/store/, src/contexts/)

산출물:

00_baseline/
├─ api_code_structure.md               # API 코드 구조
├─ api_routes_inventory.md             # API 엔드포인트 목록
├─ api_models_inventory.md             # 모델 목록
├─ react_code_structure.md             # React 코드 구조
├─ react_pages_inventory.md            # 페이지 목록
└─ react_components_inventory.md       # 컴포넌트 목록

---

Phase C: 통합 및 갭 분석

목표: 문서와 코드의 차이점 파악, 개발 범위 명확화

Step C.1: 문서 vs 코드 매칭

• 문서에 있지만 코드에 없는 기능 (TODO 목록)
• 코드에 있지만 문서에 없는 기능 (문서화 필요)
• 문서와 코드가 일치하는 기능 (재사용 가능)

Step C.2: 품목 기준관리 요구사항 도출

• mes_react 화면 명세 기반 요구사항
• 현재 API 상태
• 신규 개발 필요 범위

산출물:

00_baseline/
├─ gap_analysis.md                     # 문서-코드 갭 분석
├─ existing_features.md                # 재사용 가능한 기존 기능
├─ new_features_required.md            # 신규 개발 필요 기능
└─ item_management_requirements.md     # 품목 기준관리 요구사항

---

📋 컨텍스트 누락 방지 전략

1. 문서 쪼개기 원칙

큰 문서 (>20KB) 처리 방법:

ATOMIC_DESIGN_SYSTEM.md (40KB)
→ atomic_design_overview.md        (5KB - 개요)
→ atomic_design_atoms.md            (8KB - Atoms)
→ atomic_design_molecules.md        (10KB - Molecules)
→ atomic_design_organisms.md        (10KB - Organisms)
→ atomic_design_templates.md        (7KB - Templates/Pages)

쪼개기 기준:

• 주제별 분리 (섹션 단위)
• 각 파일 5-10KB 권장
• 파일 간 연관관계 명시
• 원본 문서 링크 포함

2. 메타데이터 추가

각 쪼갠 문서 상단에 메타데이터 포함:

---
source: ATOMIC_DESIGN_SYSTEM.md
section: Molecules
created: 2025-11-10
related:
  - atomic_design_atoms.md
  - COMMON_COMPONENTS_GUIDE.md
tags: [react, design-system, molecules, components]
---

# Atomic Design - Molecules

(내용...)

3. 교차 참조 맵 생성

문서 간 연관관계 시각화:

document_cross_reference.md
├─ API 문서 그룹
│   ├─ SAM_Item_DB_API_Analysis_v3_FINAL.md
│   │   → 참조: SAM_Item_Management_DB_Modeling_Analysis.md
│   │   → 참조: LOGICAL_RELATIONSHIPS_SIMPLE.md
│   └─ SWAGGER_PHASE3_1_PRODUCT.md
│       → 참조: SAM_Item_DB_API_Analysis_v3_FINAL.md
│
├─ React 문서 그룹
│   ├─ ATOMIC_DESIGN_SYSTEM.md
│   │   → 참조: DESIGN_SYSTEM_README.md
│   │   → 참조: COMMON_COMPONENTS_GUIDE.md
│   └─ SCREEN_DESIGN_SPECIFICATION.md
│       → 참조: STANDARD_PAGE_FORMAT.md
│       → 참조: ERP_QUOTATION_GUIDE.md
│
└─ 교차 참조
    └─ SCREEN_DESIGN_SPECIFICATION.md (React)
        → 연동: SAM_Item_DB_API_Analysis_v3_FINAL.md (API)

4. 분석 세션별 체크포인트

각 분석 세션 종료 시:

{
  "session": "Phase A - Step A.1 완료",
  "completed_docs": [
    "SAM_Item_DB_API_Analysis_v3_FINAL.md",
    "SAM_Item_Management_DB_Modeling_Analysis.md"
  ],
  "breakdown_created": [
    "api_item_analysis_summary.md",
    "api_db_modeling.md"
  ],
  "next_session": "Phase A - Step A.2",
  "context_preserved": true
}

---

🔄 후속 단계에서 활용 방법

Phase 1 (품목 기준관리) 에서 활용

Step 1.1 (화면 분석) 참조 문서:

• react_screen_specs.md (쪼갠 문서)
• business_quotation.md (쪼갠 문서)
• SCREEN_DESIGN_SPECIFICATION.md (원본, 필요시)

Step 1.3 (데이터 모델 설계) 참조 문서:

• api_db_modeling.md (쪼갠 문서)
• api_models_inventory.md (코드 분석 결과)
• existing_features.md (재사용 가능 기능)

Step 1.4 (API 설계) 참조 문서:

• api_item_analysis_summary.md (쪼갠 문서)
• api_routes_inventory.md (코드 분석 결과)
• api_swagger_status.md (Swagger 현황)

Phase 2 (견적 시스템) 에서 활용

Step 2.1 (화면 분석) 참조 문서:

• business_quotation.md (쪼갠 문서)
• ERP_QUOTATION_GUIDE.md (원본)

---

✅ 실행 체크리스트

Phase A: 문서 우선 검토

• A.1 핵심 문서 8개 검토
• A.2 대형 문서 쪼개기
• A.3 메타데이터 추가
• A.4 교차 참조 맵 생성

Phase B: 코드 분석

• B.1 API 코드 구조 분석
• B.2 React 코드 구조 분석
• B.3 코드 인벤토리 생성

Phase C: 통합 및 갭 분석

• C.1 문서-코드 매칭
• C.2 품목 기준관리 요구사항 도출
• C.3 개발 범위 명확화

---

📊 예상 산출물 구조

claudedocs/mes/00_baseline/
├─ STEP_0_1_ANALYSIS_STRATEGY.md        # 이 문서
├─ docs_breakdown/                      # 쪼갠 문서
│   ├─ api_item_analysis_summary.md
│   ├─ api_db_modeling.md
│   ├─ api_swagger_status.md
│   ├─ react_architecture.md
│   ├─ react_design_system.md
│   ├─ react_screen_specs.md
│   ├─ business_quotation.md
│   └─ document_cross_reference.md
├─ code_analysis/                       # 코드 분석 결과
│   ├─ api_code_structure.md
│   ├─ api_routes_inventory.md
│   ├─ api_models_inventory.md
│   ├─ react_code_structure.md
│   ├─ react_pages_inventory.md
│   └─ react_components_inventory.md
├─ integration/                         # 통합 분석
│   ├─ gap_analysis.md
│   ├─ existing_features.md
│   ├─ new_features_required.md
│   └─ item_management_requirements.md
└─ existing_api_analysis.md             # 최종 통합 문서

---

🚀 다음 단계 실행 방법

Step A.1 시작:

"Phase A - Step A.1 시작해줘"
또는
"/sc:analyze를 사용해서 핵심 문서 8개 분석해줘"

예상 소요 시간:

• Phase A: 2-3시간
• Phase B: 3-4시간
• Phase C: 2-3시간
• 총 7-10시간 (여러 세션으로 나누어 진행)

---

📌 중요 원칙

1. 문서 우선: 코드보다 문서 먼저 검토
2. 쪼개서 저장: 큰 문서는 반드시 주제별로 분리
3. 메타데이터: 모든 쪼갠 문서에 출처와 연관관계 명시
4. 교차 참조: 문서 간 연결고리 명확히 기록
5. 점진적 분석: 한 번에 모두 하지 말고 Phase 단위로 진행
6. 컨텍스트 보존: 각 세션 종료 시 체크포인트 저장

---

작성일: 2025-11-12 다음 작업: Phase A - Step A.1 (핵심 문서 검토)