Last Updated: 2025-12-19

SAM Code Development Policy

SAM 시스템의 견적, 수주, 생산, 출하, 품질 등 모든 MES 기능 개발에 적용되는 핵심 가이드라인 및 공통 정책입니다.

📋 개요

이 문서는 SAM 시스템의 모든 기능 개발에 공통으로 적용되는 정책을 정의합니다. 각 기능별 개발 문서(MASTER_PLAN.md)는 반드시 이 공통 정책 문서를 참조하며, 정책 준수 여부가 품질 검증의 최우선 순위입니다.

🚨 필수 준수 규칙

1. 테이블 정책

❌ 절대 금지

  • 새로운 테이블을 임의로 생성 (price_new, order_items_v2 등)
  • 기존 테이블 구조를 사용자 승인 없이 변경
  • mng 프로젝트에서 마이그레이션 실행

✅ 필수 사항

  • 기존 테이블을 최우선으로 분석하여 활용
  • 테이블 추가가 필요한 경우 반드시 사용자 승인 획득
  • DB 마이그레이션은 오직 api 프로젝트에서만 실행

2. 프로젝트 스택

프로젝트 기술 스택 주의사항
mng Laravel 12 + Plain Blade + Tailwind + Filament ❌ Alpine.js 금지
api Laravel 12 REST API + Swagger Multi-tenant 필수
5130 PHP + jQuery + Legacy JS 분석 및 참조용
react Next.js 15 프론트엔드 전담

3. 코드 컨벤션 (추측 금지 원칙)

🔴 핵심: 모든 코드 요소는 실제 확인 후 사용

❌ 절대 금지 - 추측/할루시네이션

  • 컬럼명 추측 (tenant.name → 실제는 tenant.company_name)
  • 관계명 추측 (user.roles → 실제는 user.userRoles)
  • 경로 및 메서드명 추측 (getName() → getCompanyName() 확인 필요)
  • 테이블명 확인 (users → sam_users 여부 확인)

✅ 필수 사항 - 확인 프로세스

  • 모델 파일(app/Models/*.php)에서 컬럼/관계 직접 확인
  • 마이그레이션 파일에서 원본 데이터 구조 대조
  • 기존 컨트롤러/서비스의 실제 구현 패턴 확인
  • 불확실한 경우 주저하지 말고 사용자에게 질문

🗄️ DB 테이블 상세 정책

테이블 설계 정책 (Hybrid EAV)

🔴 필수 컬럼 (일반 컬럼 생성)

  • 조인에 사용되는 필드 (FK: tenant_id, product_id 등)
  • 인덱싱이 필요한 검색/정렬 필드 (status, created_at)
  • 고빈도 쿼리 WHERE 조건 필드
  • 유니크 제약이 필요한 고유 필드 (code, slug)

🟢 가변 컬럼 (options JSON 통합)

  • 순수 비즈니스 로직용 데이터
  • 설정값, 부가 옵션 정보
  • 향후 확장 가능성이 높은 데이터
  • 조인이나 검색 필터로 사용되지 않는 필드

⚠️ Enum 지양 정책

// ❌ 지양: DB Enum (변경 시 마이그레이션 복잡)
$table->enum('status',['pending','approved','rejected']);

// ✅ 권장: string + 코드 테이블 (common_codes)
$table->string('status', 20)->default('pending');

// ✅ 허용: boolean (명확한 2가지 상태)
$table->boolean('is_active')->default(true);

🔄 Phase 진행 및 커밋 정책

Phase 워크플로우

Step 1: 5130 리서치
원본 데이터 구조 분석
↓
Step 2: SAM 매핑
기존 확인 및 신규 설계
↓
Step 3: 필수/가변 분류
JSON 통합 필드 식별
↓
Step 4: 사용자 승인
설계 확정 후 구현 시작

세션 및 커밋 원칙

  • 롤백 포인트: 각 Phase 완료 시 Git 태그 생성 필수
  • 세션 중단 대응: PROGRESS.md를 통해 컨텍스트 실시간 복구
  • 커밋 메시지: 반드시 한글로 작성하며 단계별 커밋
  • 푸시 정책: 커밋 후 푸시 여부는 묻지 않으며 사용자 수동 진행

📝 변경 이력

날짜 변경 내용 작성자
2025-12-19 초기 공통 정책 문서 작성 (MES 통합 가이드) Claude