sam-api/LOGICAL_RELATIONSHIPS.md

논리적 데이터베이스 관계 문서

FK 제약조건 제거 후 개발자 참조용 논리적 관계 명세서

생성일: 2025-09-24 마이그레이션 batch: 17까지 적용됨

🎯 목적

물리적 FK 제약조건을 제거하여 성능과 관리 편의성을 확보하면서도, 개발자들이 비즈니스 로직에서 참조해야 할 논리적 관계를 명시합니다.

📋 FK 제거 현황

✅ 제거된 FK 제약조건 (4개)

테이블	컬럼	참조 테이블	참조 컬럼	제거 단계	효과
classifications	tenant_id	tenants	id	Phase 1	분류 코드 관리 유연성
departments	parent_id	departments	id	Phase 1	부서 구조 변경 유연성
estimates	model_set_id	categories	id	Phase 2	견적 성능 향상
estimate_items	estimate_id	estimates	id	Phase 2	견적 아이템 성능 향상

🔒 유지된 중요 FK 제약조건 (40+개)

멀티테넌트 보안 FK (필수 유지):

• 모든 tenant_id → tenants.id 관계 유지
• 사용자 권한 관련 FK 모두 유지

핵심 비즈니스 FK (필수 유지):

• products.category_id → categories.id
• 권한 관리 시스템 (users, roles, permissions)
• 주문 관리 시스템 (orders, order_items, clients)

🧩 논리적 관계 명세

1. 분류 관리 (Classifications)

classifications (분류 코드)
├── tenant_id → tenants.id (논리적 - 멀티테넌트)
└── [Eloquent Model에서 BelongsToTenant 트레잇으로 관리]

개발 시 주의사항:

• Service 레이어에서 테넌트 격리 검증 필수
• 분류 삭제 시 사용 중인 참조 확인 필요

2. 부서 관리 (Departments)

departments (부서)
├── parent_id → departments.id (논리적 - 계층 구조)
└── [자기 참조 관계, Soft Delete 적용]

개발 시 주의사항:

• 부서 삭제 시 하위 부서 존재 여부 확인
• 순환 참조 방지 로직 필요
• 사용자 배치 여부 확인 후 삭제

3. 견적 시스템 (Estimates)

estimates (견적)
├── model_set_id → categories.id (논리적 - 스냅샷 특성)
├── tenant_id → tenants.id (물리적 FK 유지 - 보안)
└── [견적은 생성 시점 데이터 보존]

estimate_items (견적 아이템)
├── estimate_id → estimates.id (논리적 - 성능 최적화)
├── tenant_id → tenants.id (물리적 FK 유지 - 보안)
└── [대량 데이터 처리 성능 우선]

개발 시 주의사항:

• 견적 데이터는 스냅샷 특성상 참조 무결성보다 성능 우선
• 카테고리 변경이 기존 견적에 영향주지 않도록 주의
• 대량 견적 아이템 처리 시 batch 작업 권장

4. BOM 시스템 (Product Components)

product_components (제품 구성요소)
├── parent_product_id → products.id (물리적 FK 없음 - 이미 유연한 구조)
├── ref_type: 'MATERIAL' | 'PRODUCT' (참조 타입)
├── ref_id → materials.id | products.id (논리적 - ref_type에 따라)
└── [통합 참조 구조로 설계됨]

개발 시 주의사항:

• ref_type 값에 따라 ref_id 해석 필요
• 자재/제품 삭제 시 BOM 영향도 분석 필수
• Service 레이어에서 참조 무결성 검증 구현

📈 성능 최적화 효과

제거된 FK의 성능 영향

1. Classifications: 분류 코드 조회 성능 향상
2. Departments: 부서 구조 변경 시 락킹 감소
3. Estimates: 견적 생성/수정 처리량 증가
4. Estimate Items: 대량 아이템 처리 성능 향상

유지된 인덱스

모든 제거된 FK에 대해 성능 인덱스는 유지하여 조회 성능 보장:

-- 유지된 성능 인덱스들
CREATE INDEX idx_classifications_tenant_id ON classifications (tenant_id);
CREATE INDEX idx_departments_parent_id ON departments (parent_id);
CREATE INDEX idx_estimates_tenant_model_set ON estimates (tenant_id, model_set_id);
CREATE INDEX idx_estimate_items_tenant_estimate ON estimate_items (tenant_id, estimate_id);
CREATE INDEX idx_components_ref_type_id ON product_components (ref_type, ref_id);

🛡️ 개발 가이드라인

Service 레이어 구현 필수사항

1. 데이터 무결성 검증

   // 예시: 부서 삭제 전 검증
   public function deleteDepartment($id) {
       if ($this->hasChildDepartments($id)) {
           throw new ValidationException('하위 부서가 존재합니다.');
       }
       if ($this->hasAssignedUsers($id)) {
           throw new ValidationException('배정된 사용자가 존재합니다.');
       }
       // 삭제 진행
   }
   

2. Eloquent 관계 적극 활용

   // 논리적 관계는 Model에서 정의
   class Department extends Model {
       public function parent() {
           return $this->belongsTo(Department::class, 'parent_id');
       }
   
       public function children() {
           return $this->hasMany(Department::class, 'parent_id');
       }
   }
   

3. 배치 작업 시 주의사항

   • 대량 데이터 변경 시 관련 테이블 영향도 고려
   • Transaction 사용으로 일관성 보장
   • 참조 무결성 검증 로직 포함

🚨 주의사항

절대 하지 말아야 할 것

❌ 직접 SQL로 참조 데이터 삭제 ❌ Service 레이어 무결성 검증 생략 ❌ 대량 작업 시 관련 테이블 확인 누락

권장사항

✅ Eloquent ORM 관계 메서드 사용 ✅ Service 레이어에서 비즈니스 규칙 검증 ✅ Soft Delete 활용으로 데이터 보호 ✅ 단위 테스트로 무결성 검증

🔄 복구 방법

필요시 물리적 FK 제약조건 복구 가능:

# 전체 롤백
php artisan migrate:rollback --step=4

# 특정 단계만 롤백
php artisan migrate:rollback --step=1

참고: FK 복구 시 데이터 무결성 위반으로 실패할 수 있으므로, 복구 전 데이터 정합성 점검 필수.

---

문서 관리: 이 문서는 데이터베이스 스키마 변경 시 함께 업데이트해야 합니다. 최종 업데이트: 2025-09-24 (Phase 1~3 FK 제거 완료)