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
Stats	21	StatFinanceDaily, DimClient, DimDate 등	stats.md
Documents	15	Document, DocumentTemplate, DocumentApproval 등	documents.md
Commons	10	Category, File, Menu, Tag, Classification	commons.md
Quote	8	Quote, QuoteItem, QuoteFormula, QuoteRevision	sales.md
Production	8	WorkOrder, WorkOrderItem, WorkResult 등	production.md
Orders	8	Order, OrderItem, OrderNode, Client 등	sales.md
ItemMaster	8	ItemField, ItemPage, ItemBomItem, CustomTab 등	products.md
Products	6	Product, ProductComponent, Part, Price	products.md
Interview	5	InterviewTemplate, InterviewSession 등	hr.md
Construction	5	Contract, HandoverReport, StructureReview	production.md
Boards	5	Board, Post, BoardSetting, PostCustomFieldValue	commons.md
Members	4	User, UserTenant, UserRole, UserMenuPermission	tenants.md
Materials	4	Material, MaterialReceipt, MaterialInspection	production.md
ESign	4	EsignContract, EsignSigner, EsignSignField	documents.md
Design	4	DesignModel, ModelVersion, BomTemplate	products.md
Qualitys	3	Inspection, Lot, LotSale	production.md
Permissions	3	Permission, Role, PermissionOverride	tenants.md
Items	3	Item, ItemDetail, ItemReceipt	products.md
BadDebts	3	BadDebt, BadDebtDocument, BadDebtMemo	finance.md
Estimate	2	Estimate, EstimateItem	sales.md
Audit	2	AuditLog, TriggerAuditLog	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, Members, Permissions
products.md	Products, ItemMaster, Items, Design
sales.md	Orders, Quote, Estimate
production.md	Production, Construction, Materials, Qualitys
finance.md	Finance (Tenants 하위), BadDebts
hr.md	HR (Tenants 하위), Interview
documents.md	Documents, ESign
commons.md	Commons, Boards, Audit
stats.md	Stats (sam_stat DB)