sam-docs/specs/database-schema.md

SAM 데이터베이스 스키마

업데이트: 2026-01-29 데이터베이스: samdb (MySQL 8.0.44) 전체 테이블: 219개

---

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

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

products

• 제품 카탈로그
• 타입 분류: PRODUCT, PART, SUBASSEMBLY

product_components

• BOM 관계
• MATERIAL 또는 PRODUCT 참조

materials

• 자재 마스터
• 동적 속성 지원

classifications

• 그룹별 플랫 코드 테이블
• 예: product_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)
Products ↔ Materials (via product_components with ref_type)
Models → Versions → BOM Templates (design workflow)
Orders → Items → Components (order breakdown)
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

---

최종 업데이트: 2026-01-30 Phase 4: 완료 (8개 테이블 상세화) 테이블 수 갱신: samdb 219개 + sam_stat 20개 = 239개

---

sam_stat 데이터베이스 (통계 전용)

별도 MySQL 데이터베이스. Laravel sam_stat 커넥션 사용. 마이그레이션 경로: database/migrations/stats/

메타/관리 테이블

테이블	설명	주요 컬럼
stat_definitions	통계 정의 마스터	domain, stat_type, table_name, is_active
stat_job_logs	집계 작업 로그	tenant_id, job_type, target_date, status, records_processed, duration_ms

차원 테이블

테이블	설명	주요 컬럼
dim_date	날짜 차원 (2020~2030)	date, year, quarter, month, day, day_of_week, is_weekend, is_holiday
dim_client	고객 차원 (samdb 동기화)	tenant_id, source_client_id, client_name, group_name
dim_product	제품 차원 (samdb 동기화)	tenant_id, source_product_id, product_name, product_type

일간 팩트 테이블 (7개)

테이블	도메인	UK	주요 지표
stat_sales_daily	매출/수주	(tenant_id, stat_date)	order_count/amount, sales_count/amount, new/active_client_count, shipment_count/amount
stat_finance_daily	재무/회계	(tenant_id, stat_date)	deposit/withdrawal count/amount, net_cashflow, purchase_count/amount, bank_balance_total
stat_production_daily	생산/작업	(tenant_id, stat_date)	work_order_count, completed/in_progress_count, defect_count/rate, total_quantity
stat_inventory_daily	재고	(tenant_id, stat_date)	receipt_count/quantity, shipment_count/quantity, total_stock_value, low_stock_count
stat_quote_pipeline_daily	견적/영업	(tenant_id, stat_date)	new/sent/won/lost_quote_count, pipeline_value, conversion_rate, avg_quote_amount
stat_hr_attendance_daily	인사/근태	(tenant_id, stat_date)	total/present/absent/late/leave_count, overtime_hours, attendance_rate
stat_system_daily	시스템/감사	(tenant_id, stat_date)	api_request/error_count, active_user_count, audit_create/update/delete_count, fcm_sent/failed_count

월간 요약 테이블 (4개)

테이블	도메인	UK	주요 지표
stat_sales_monthly	매출/수주	(tenant_id, stat_year, stat_month)	order/sales/shipment count/amount, unique_client_count, avg_order_amount, mom/yoy_growth_rate
stat_finance_monthly	재무/회계	(tenant_id, stat_year, stat_month)	deposit/withdrawal/purchase_total, net_cashflow, bank_balance_end, mom_cashflow_change
stat_production_monthly	생산/작업	(tenant_id, stat_year, stat_month)	total_work_orders, completed/in_progress_count, avg_defect_rate, total_production_quantity
stat_project_monthly	건설/프로젝트	(tenant_id, stat_year, stat_month)	active/completed_site_count, new_contract_count/amount, gross_profit/rate

KPI/알림/이벤트 테이블

테이블	설명	주요 컬럼
stat_kpi_targets	KPI 목표값	tenant_id, domain, metric_code, target_year/month, target_value, actual_value
stat_alerts	통계 알림	tenant_id, domain, alert_type, severity(enum: info/warning/critical), title, message, is_read, is_resolved
stat_events	실시간 이벤트 로그	tenant_id, domain, event_type, entity_type, entity_id, payload(JSON), occurred_at
stat_snapshots	상태 스냅샷	tenant_id, snapshot_date, domain, snapshot_type, data(JSON)

Artisan 커맨드

커맨드	설명
stat:aggregate-daily	일간 통계 집계 (스케줄러: 매일 01:00)
stat:aggregate-monthly	월간 통계 집계 (스케줄러: 매월 1일 02:00)
stat:sync-dimensions	차원 테이블 동기화 (스케줄러: 매일 00:30)
stat:backfill --from= --to=	과거 데이터 일괄 백필
stat:verify --date=	원본 DB vs sam_stat 정합성 검증

API 엔드포인트

Method	Path	설명
GET	/api/v1/stats/summary	대시보드 통계 요약
GET	/api/v1/stats/daily	도메인별 일간 통계 (domain, start_date, end_date)
GET	/api/v1/stats/monthly	도메인별 월간 통계 (domain, year, month?)
GET	/api/v1/stats/alerts	통계 알림 목록 (limit?, unread_only?)