sam-docs/system/database/README.md

# 데이터베이스 스키마 현황

> **최종 갱신**: 2026-02-27
> **DB**: MySQL 8.0 (samdb + sam_stat)
> **마이그레이션**: 459개 (api/에서만 관리)

---

## 1. 규모 요약

| 항목 | 수량 |
|------|------|
| Eloquent 모델 | 220 |
| 도메인 그룹 | 32 |
| 마이그레이션 | 459 (메인 437 + 통계 22) |
| DB 연결 | 2 (samdb, sam_stat) |

---

## 2. 도메인별 모델 분포

| 도메인 | 모델 수 | 주요 엔티티 | 상세 |
|--------|---------|------------|------|
| Tenants | 56 | Tenant, Department, Approval, Payment, Stock 등 | [tenants.md](tenants.md) |
| Stats | 21 | StatFinanceDaily, DimClient, DimDate 등 | [stats.md](stats.md) |
| Documents | 15 | Document, DocumentTemplate, DocumentApproval 등 | [documents.md](documents.md) |
| Commons | 10 | Category, File, Menu, Tag, Classification | [commons.md](commons.md) |
| Quote | 8 | Quote, QuoteItem, QuoteFormula, QuoteRevision | [sales.md](sales.md) |
| Production | 8 | WorkOrder, WorkOrderItem, WorkResult 등 | [production.md](production.md) |
| Orders | 8 | Order, OrderItem, OrderNode, Client 등 | [sales.md](sales.md) |
| ItemMaster | 8 | ItemField, ItemPage, ItemBomItem, CustomTab 등 | [products.md](products.md) |
| Products | 6 | Product, ProductComponent, Part, Price | [products.md](products.md) |
| Interview | 5 | InterviewTemplate, InterviewSession 등 | [hr.md](hr.md) |
| Construction | 5 | Contract, HandoverReport, StructureReview | [production.md](production.md) |
| Boards | 5 | Board, Post, BoardSetting, PostCustomFieldValue | [commons.md](commons.md) |
| Members | 4 | User, UserTenant, UserRole, UserMenuPermission | [tenants.md](tenants.md) |
| Materials | 4 | Material, MaterialReceipt, MaterialInspection | [production.md](production.md) |
| ESign | 4 | EsignContract, EsignSigner, EsignSignField | [documents.md](documents.md) |
| Design | 4 | DesignModel, ModelVersion, BomTemplate | [products.md](products.md) |
| Qualitys | 3 | Inspection, Lot, LotSale | [production.md](production.md) |
| Permissions | 3 | Permission, Role, PermissionOverride | [tenants.md](tenants.md) |
| Items | 3 | Item, ItemDetail, ItemReceipt | [products.md](products.md) |
| BadDebts | 3 | BadDebt, BadDebtDocument, BadDebtMemo | [finance.md](finance.md) |
| Estimate | 2 | Estimate, EstimateItem | [sales.md](sales.md) |
| Audit | 2 | AuditLog, TriggerAuditLog | [commons.md](commons.md) |
| Root Level | 27 | ApiKey, Process, NumberingSequence 등 | 각 도메인 문서 참조 |

---

## 3. 핵심 엔티티 관계도

### 인증 + 멀티테넌시

```
User
  ├─ hasMany UserTenant (pivot: is_active, is_default)
  │   └─ belongsTo Tenant
  ├─ hasMany UserRole
  └─ hasMany UserMenuPermission

Tenant
  ├─ hasMany Department (계층 구조, parent_id)
  │   └─ belongsToMany User (department_user pivot)
  ├─ hasMany TenantUserProfile (테넌트별 직원 프로필)
  └─ hasMany [모든 tenant-scoped 모델]
```

### 제품 + 설계

```
Product
  ├─ belongsTo Category (계층 분류)
  ├─ hasMany ProductComponent (BOM)
  ├─ hasMany Part, Price
  └─ morphMany File

DesignModel
  └─ hasMany ModelVersion
      └─ hasMany BomTemplate
          └─ hasMany BomTemplateItem
```

### 견적 → 수주 → 생산 흐름

```
Quote (견적)
  ├─ belongsTo Client
  ├─ hasMany QuoteItem
  └─ → Order 변환

Order (수주)
  ├─ belongsTo Quote, Client
  ├─ hasMany OrderItem (options JSON)
  ├─ hasMany OrderNode (설계 분해)
  └─ hasMany WorkOrder

WorkOrder (작업지시)
  ├─ belongsTo Order, Process
  ├─ hasMany WorkOrderItem (options JSON)
  ├─ hasMany WorkOrderStepProgress
  └─ hasMany WorkResult (작업실적)
```

### 문서 + 전자결재

```
Document
  ├─ belongsTo DocumentTemplate
  ├─ morphTo linkable (다형 - Order, Quote 등)
  ├─ hasMany DocumentApproval (결재 단계)
  └─ hasMany DocumentData (동적 폼)

DocumentTemplate
  ├─ hasMany Section → Field → Item
  └─ hasMany ApprovalLine (결재선)
```

---

## 4. 공통 패턴

### 트레이트 사용 현황

| 트레이트 | 적용 모델 수 | 역할 |
|---------|-------------|------|
| BelongsToTenant | ~160 (73%) | tenant_id 자동 스코핑 |
| Auditable | ~150 (68%) | created_by, updated_by, deleted_by |
| SoftDeletes | ~150 (68%) | 논리 삭제 (deleted_at) |
| ModelTrait | ~80 (36%) | 날짜 처리, is_active 스코프 |
| HasRoles (Spatie) | 3 | RBAC 권한 관리 |
| HasApiTokens (Sanctum) | 1 (User) | API 토큰 관리 |

### 표준 컬럼 구조

모든 비즈니스 테이블의 공통 컬럼:
```
id                 PK
tenant_id          FK (멀티테넌시)
created_by         FK → users (감사)
updated_by         FK → users (감사)
deleted_by         FK → users (감사)
created_at         timestamp
updated_at         timestamp
deleted_at         timestamp (논리삭제)
is_active          boolean
sort_order         integer
options            JSON (유연한 속성 저장)
```

### DB 설계 패턴

| 패턴 | 사용 예시 |
|------|----------|
| 계층 구조 (Self-Reference) | Category, Department (parent_id) |
| 다형 관계 (Polymorphic) | File, PermissionOverride (morphable_type/id) |
| EAV (Entity-Attribute-Value) | PostCustomFieldValue, CategoryField |
| JSON 컬럼 | Product.bom, OrderItem.options, WorkOrderItem.options |
| Pivot 테이블 | user_tenants, department_user |
| BOM/Tree | ProductComponent, BomTemplateItem |
| 버전 관리 | ModelVersion, QuoteRevision, OrderVersion |
| 상태 코드 | Order.status (DRAFT/CONFIRMED/IN_PRODUCTION) |

### JSON options 컬럼 정책

> **FK/조인키만** 테이블 컬럼으로 추가.
> **나머지 속성은** `options` 또는 `attributes` JSON에 저장.
> 이유: 멀티테넌시 환경에서 테넌트별 스키마 변경 없이 유연한 관리.

---

## 5. DB 연결

| 연결명 | DB | 용도 |
|--------|-----|------|
| mysql (기본) | samdb | 모든 비즈니스 데이터 |
| sam_stat | sam_stat | 통계/집계 전용 (21 모델) |
| chandj | chandj | 레거시 5130 (마이그레이션 대상) |

---

## 6. 도메인별 상세 문서

| 문서 | 포함 도메인 |
|------|-----------|
| [tenants.md](tenants.md) | Tenants, Members, Permissions |
| [products.md](products.md) | Products, ItemMaster, Items, Design |
| [sales.md](sales.md) | Orders, Quote, Estimate |
| [production.md](production.md) | Production, Construction, Materials, Qualitys |
| [finance.md](finance.md) | Finance (Tenants 하위), BadDebts |
| [hr.md](hr.md) | HR (Tenants 하위), Interview |
| [documents.md](documents.md) | Documents, ESign |
| [commons.md](commons.md) | Commons, Boards, Audit |
| [stats.md](stats.md) | Stats (sam_stat DB) |