sam-docs/specs/database-schema.md

SAM 데이터베이스 스키마

업데이트: 2025-12-16 데이터베이스: samdb (MySQL 8.0.43) 전체 테이블: 92개

---

Multi-tenant 데이터 아키텍처

데이터 격리 방식

• 방식: tenant_id 컬럼 기반 격리
• 스코프: BelongsToTenant global scope 자동 적용
• 모델: shared/Models/ 디렉토리의 공통 모델 사용
• Soft Deletes: 대부분의 엔티티에 적용
• 감사 컬럼: created_by, updated_by, deleted_by

핵심 테이블 구조

인증 및 권한

users (24 컬럼) - Phase 4 완료

용도: 시스템 사용자 정보 (관리자, 일반 사용자)

주요 컬럼:

• id (PK), user_id (UK), name, email (UK), password
• phone, role (deprecated), is_active, is_super_admin
• email_verified_at, last_login_at
• 2FA: two_factor_secret, two_factor_recovery_codes, two_factor_confirmed_at
• remember_token, current_team_id, profile_photo_path
• options (JSON)
• Audit: created_by, updated_by, deleted_by
• Timestamps: created_at, updated_at, deleted_at (Soft Delete)

특징:

• Laravel Sanctum 인증
• Multi-tenant via user_tenants pivot
• 2FA 지원
• Soft Delete 지원

roles (11 컬럼) - Phase 4 완료, Spatie Permission

용도: 사용자 역할 정의

주요 컬럼:

• id (PK), tenant_id, name, guard_name, description
• Audit: created_by, updated_by, deleted_by
• Timestamps: created_at, updated_at, deleted_at

인덱스:

• UNIQUE (tenant_id, name, guard_name)
• INDEX (tenant_id)

특징:

• Spatie Laravel Permission 패키지
• Multi-tenant 지원
• Soft Delete 지원

permissions (8 컬럼) - Phase 4 완료, Spatie Permission

용도: 시스템 권한 정의

주요 컬럼:

• id (PK), tenant_id (nullable), name, guard_name
• Audit: created_by, updated_by
• Timestamps: created_at, updated_at

인덱스:

• UNIQUE (name, guard_name, tenant_id)
• INDEX (tenant_id)

특징:

• tenant_id nullable (마스터 권한 지원)
• Spatie Laravel Permission 패키지

model_has_roles (4 컬럼) - Spatie Permission

용도: 사용자-역할 연결 (Many-to-Many)

주요 컬럼:

• role_id (PK, FK), model_type (PK), model_id (PK), tenant_id (PK)

외래키:

• role_id → roles.id (ON DELETE CASCADE)

특징:

• Polymorphic 관계
• Multi-tenant 지원

role_has_permissions (2 컬럼) - Spatie Permission

용도: 역할-권한 연결 (Many-to-Many)

주요 컬럼:

• permission_id (PK, FK), role_id (PK, FK)

외래키:

• permission_id → permissions.id (ON DELETE CASCADE)
• role_id → roles.id (ON DELETE CASCADE)

user_tenants

• 사용자-테넌트 다대다 관계
• active, default 플래그

personal_access_tokens

• Sanctum 토큰 저장

api_keys

• API 키 관리
• is_active 상태 관리

permission_overrides

• 수동 권한 허용/거부
• 시간 기반 유효성

멀티테넌트 조직

tenants (32 컬럼) - Phase 4 완료

용도: 다중 회사/조직 관리 (Multi-tenant 핵심)

주요 컬럼:

• id (PK), company_name, code (UK)
• email, phone, address, business_num, corp_reg_no, ceo_name
• homepage, fax, logo, admin_memo, options (JSON)
• tenant_st_code (trial/active/none), plan_id, subscription_id
• max_users, trial_ends_at, expires_at, last_paid_at, billing_tp_code
• 저장소: storage_limit, storage_used, storage_warning_sent_at, storage_grace_period_until
• Audit: created_by, updated_by, deleted_by
• Timestamps: created_at, updated_at, deleted_at

인덱스:

• UNIQUE (code)
• INDEX (storage_used)

특징:

• Multi-tenant 시스템의 핵심 테이블
• 구독/결제 관리
• 저장소 용량 관리 (기본 10GB)
• Soft Delete 지원

departments (14 컬럼) - Phase 4 완료

용도: 조직 부서 정보 (계층 구조)

주요 컬럼:

• id (PK), tenant_id, parent_id (Self-referential)
• code, name, description
• is_active, sort_order
• Audit: created_by, updated_by, deleted_by
• Timestamps: created_at, updated_at, deleted_at

인덱스:

• UNIQUE (tenant_id, code)
• INDEX (tenant_id, name)
• INDEX (tenant_id, is_active)
• INDEX (parent_id)

특징:

• Self-referential 관계 (무제한 depth)
• 활성 상태 관리
• 정렬 순서 지원
• Soft Delete 지원

tenant_user_profiles

• 테넌트별 확장 사용자 프로필

department_user

• 사용자-부서 할당
• primary 부서 플래그

제품 관리

categories

• 계층적 제품 분류
• Soft Deletes 적용

category_fields

• 카테고리별 동적 필드 정의

category_templates

• 버전 관리된 카테고리 필드 스냅샷

items (통합 - 2025-12-15)

• 품목 통합 테이블 (기존 products/materials 통합)
• 타입 분류: FG (완제품), PT (부품), SM (부자재), RM (원자재), CS (소모품)
• 주요 컬럼: item_type, code, name, unit, category_id, bom (JSON)
• 1:1 확장 테이블: item_details, item_attributes

item_details

• items 확장 필드 (1:1 관계)
• is_sellable, is_purchasable, is_producible, safety_stock, lead_time 등

item_attributes

• 동적 속성 저장 (1:1 관계)
• attributes (JSON), options (JSON)

classifications

• 그룹별 플랫 코드 테이블
• 예: item_type, payment_method

디자인 및 제조

models

• 디자인 모델 마스터
• 생명주기 상태 관리

model_versions

• 버전 관리된 모델 릴리스
• 상태: DRAFT, RELEASED

bom_templates

• 모델 버전에 연결된 BOM 템플릿

bom_template_items

• 템플릿 BOM 라인 항목
• 수량 및 낭비율 포함

주문 및 운영

orders

• 주문/견적 마스터
• 워크플로우 상태

order_items

• 주문 라인 항목
• 디자인 코드 포함

order_item_components

• 주문 항목별 필수 자재/제품

order_histories

• 주문 변경 추적 및 메모

clients

• 고객/벤더 마스터

재고 및 자재

material_receipts

• 입고 자재 수령
• 로트 추적

material_inspections

• 품질 검사 기록

material_inspection_items

• 검사 체크리스트 항목

lots

• 자재 로트 관리

lot_sales

• 로트 소비 추적

price_histories

• 시간 기반 유효성을 가진 가격 이력

시스템 및 설정

menus (17 컬럼) - Phase 4 완료

용도: 시스템 메뉴 트리 구조 (사이드바, 권한 연동)

주요 컬럼:

• id (PK), tenant_id (nullable), parent_id (Self-referential)
• name, url, icon
• is_active, hidden, is_external, external_url
• sort_order
• Audit: created_by, updated_by, deleted_by
• Timestamps: created_at, updated_at, deleted_at

인덱스:

• INDEX (tenant_id)
• INDEX (parent_id)
• INDEX (sort_order)
• INDEX (tenant_id, is_active, hidden)
• INDEX (tenant_id, deleted_at)
• INDEX (deleted_at)

특징:

• Self-referential 관계 (무제한 depth)
• tenant_id nullable (마스터 메뉴 지원)
• 활성/숨김 상태 토글
• 내부/외부 링크 지원
• Soft Delete 지원

common_codes

• 계층적 마스터 코드
• 테넌트 지원

files

• 다형성 파일 첨부

audit_logs

• 포괄적인 감사 추적
• 13개월 보관

setting_field_defs

• 전역 필드 정의

tenant_field_settings

• 테넌트별 필드 설정

tenant_option_groups / tenant_option_values

• 테넌트 관리 드롭다운 옵션

콘텐츠 관리

boards

• 설정 가능한 게시판 시스템

posts

• 커스텀 필드를 가진 게시판 게시물

board_settings

• 게시판별 동적 필드 정의

board_comments

• 계층적 댓글 시스템

주요 모델 관계

관계 구조

Tenant → Users (many-to-many via user_tenants)
Items → ItemDetails, ItemAttributes (1:1 확장)
Items.bom (JSON) → 자체 참조 BOM 구조
Models → Versions → BOM Templates (design workflow)
Orders → OrderItems → Items (주문 구조)
Categories ↔ Fields ↔ Templates (dynamic forms with versioning)
Audit Logs (polymorphic tracking across all major entities)

공통 컬럼 패턴

필수 컬럼

모든 테이블에 포함되어야 하는 컬럼:

Schema::create('products', function (Blueprint $table) {
    $table->id()->comment('ID');
    $table->foreignId('tenant_id')->comment('테넌트 ID');

    // 비즈니스 컬럼...

    $table->foreignId('created_by')->nullable()->comment('생성자 ID');
    $table->foreignId('updated_by')->nullable()->comment('수정자 ID');
    $table->foreignId('deleted_by')->nullable()->comment('삭제자 ID');
    $table->timestamps();
    $table->softDeletes();
});

컬럼 규칙

• tenant_id: 필수, 인덱스 권장
• created_by, updated_by, deleted_by: nullable, COMMENT 필수
• deleted_at: Soft Delete용
• timestamps: created_at, updated_at

인덱스 최적화

필수 인덱스

• tenant_id - 모든 테이블에 권장
• 검색/정렬에 사용되는 컬럼
• 복합 인덱스 고려

주요 유니크 제약

• models(code) - 모델 코드
• model_versions(version_no) - 버전 번호
• bom_items(parent, order) - BOM 항목 순서

Foreign Key 제약조건

정책

• 개발 환경: 설계 단계에서 제약조건 생성
• 운영 환경: 최소화 또는 제거

이유

• 성능 최적화
• 유연한 데이터 관리
• 마이그레이션 복잡도 감소

감사 로그

테이블 구조

audit_logs:

• tenant_id - 테넌트 ID
• target_type - 대상 모델 타입 (polymorphic)
• target_id - 대상 ID
• action - 액션 타입
• before - 변경 전 데이터 (JSON)
• after - 변경 후 데이터 (JSON)
• actor_id - 수행자 ID
• ip - IP 주소
• ua - User Agent
• created_at - 생성 시간

보관 정책

• 기본 보관 기간: 13개월
• 정리: audit:prune 스케줄러 (매일 03:10)
• 실패 허용: 감사 로그 실패 시 비즈니스 로직 계속 진행

데이터베이스 작업 시 주의사항

마이그레이션 작성

✓ 명확한 파일명 (YYYY_MM_DD_HHMMSS_action_table.php)
✓ up/down 메서드 모두 구현
✓ 롤백 테스트 완료
✓ COMMENT 추가 (tenant_id, created_by 등)

모델 작성

✓ BelongsToTenant scope 적용
✓ ModelTrait 사용
✓ SoftDeletes 적용
✓ tenant_id 필터링 확인

쿼리 작성

✓ tenant_id 필터링 필수
✓ Eager Loading 사용 (N+1 문제 방지)
✓ 인덱스 활용 고려

관련 문서

• API 개발 규칙
• 아키텍처

---

Phase 4 구현 상세 (2025-11-24)

완료된 테이블 (8개)

1. users - 사용자 관리 (Sanctum 인증, 2FA)
2. roles - 역할 관리 (Spatie Permission)
3. permissions - 권한 관리 (Spatie Permission)
4. model_has_roles - 사용자-역할 연결
5. role_has_permissions - 역할-권한 연결
6. departments - 부서 관리 (계층 구조)
7. menus - 메뉴 관리 (트리 구조)
8. tenants - 테넌트 관리 (구독/저장소)

Spatie Permission 통합

// 역할 할당
$user->assignRole('admin');

// 권한 확인
$user->hasPermissionTo('users.view');

// 역할에 권한 할당
$role->syncPermissions(['users.view', 'users.create']);

공통 패턴

• Soft Delete: deleted_at, deleted_by
• Audit: created_by, updated_by, deleted_by
• Multi-tenant: tenant_id (nullable for master data)
• Self-referential: parent_id (departments, menus)
• Active Status: is_active
• Sort Order: sort_order

---

Items 테이블 통합 (2025-12-15)

완료 항목

• ✅ products/materials 테이블 → items 테이블로 통합
• ✅ item_details (확장 필드), item_attributes (동적 속성) 분리
• ✅ BOM 구조 단순화 (child_item_id만 사용)
• ✅ 기존 Product, Material 모델/서비스 삭제

테이블 구조

items (
  id, tenant_id, item_type, code, name, unit,
  category_id, bom JSON, is_active,
  created_by, updated_by, deleted_by, timestamps, soft_delete
)

item_details (
  id, item_id, is_sellable, is_purchasable, is_producible,
  safety_stock, lead_time, is_inspection, ...
)

item_attributes (
  id, item_id, attributes JSON, options JSON
)

---

최종 업데이트: 2025-12-16 Phase 4: 완료 (8개 테이블 상세화) Items 통합: 완료 (2025-12-15)