sam-api/DATABASE_SCHEMA_2025-09-19.md

SAM 데이터베이스 스키마 보고서

점검일시: 2025-09-19 19:50 KST 데이터베이스: samdb (MySQL 8.0.43) 연결정보: 127.0.0.1:3306 (samuser)

📊 전체 현황

• 총 테이블 수: 70개
• 전체 DB 크기: 3.42 MB
• 연결 상태: 정상 (1 active connection)
• 엔진: InnoDB
• 문자셋: utf8mb4_unicode_ci

🏗️ 핵심 테이블 구조

1. Multi-Tenant 기반 구조

tenants (80KB)

-- 테넌트(회사/조직) 마스터
- id: bigint (PK, auto_increment)
- company_name: varchar(100) -- 회사명
- code: varchar(50) UNIQUE -- 테넌트 코드
- email, phone, address: 연락처 정보
- business_num: varchar(12) -- 사업자번호
- corp_reg_no: varchar(13) -- 법인등록번호
- ceo_name, homepage, fax, logo: 추가 정보
- admin_memo: text -- 관리자 메모
- options: json -- 설정 옵션
- tenant_st_code: varchar(20) -- 상태 코드
- plan_id, subscription_id: 구독 관련
- max_users: int -- 최대 사용자 수
- trial_ends_at, expires_at, last_paid_at: 구독 일정
- billing_tp_code: varchar(20) DEFAULT 'monthly'
- created_at, updated_at, deleted_at

users (48KB)

-- 사용자 계정 마스터
- id: bigint (PK, auto_increment)
- user_id: varchar(100) UNIQUE -- 사용자 ID
- phone: varchar(30)
- options: json
- name: varchar(255)
- email: varchar(255) UNIQUE
- email_verified_at: timestamp
- password: varchar(255)
- last_login_at: timestamp
- two_factor_secret, two_factor_recovery_codes: 2FA 관련
- two_factor_confirmed_at: timestamp
- remember_token: varchar(100)
- current_team_id: bigint
- profile_photo_path: varchar(2048)
- created_at, updated_at, deleted_at

user_tenants (48KB)

-- 사용자-테넌트 매핑 (M:N)
- user_id ↔ tenant_id
- is_active, is_default 플래그

2. 권한 관리 시스템

Spatie Permission 기반

• permissions (48KB): 권한 정의
• roles (48KB): 역할 정의
• model_has_permissions (64KB): 모델별 권한 할당
• model_has_roles (48KB): 모델별 역할 할당
• role_has_permissions (32KB): 역할별 권한 매핑

확장 권한 시스템

• permission_overrides (64KB): 수동 권한 재정의
• departments (80KB): 부서별 계층 구조
• department_user (16KB): 사용자-부서 매핑

3. 제품 및 자재 관리

products (432KB) - 가장 큰 테이블

-- 제품 카탈로그 마스터
- id: bigint (PK)
- tenant_id: bigint (테넌트 격리)
- code: varchar(30) -- 제품 코드 (테넌트별 유니크)
- name: varchar(100)
- unit: varchar(10) -- 단위
- category_id: bigint (FK → categories)
- product_type: varchar(30) DEFAULT 'PRODUCT'
- attributes: json -- 동적 속성
- description: varchar(255)
- is_sellable: tinyint DEFAULT 1
- is_purchasable: tinyint DEFAULT 0
- is_producible: tinyint DEFAULT 1
- is_active: tinyint DEFAULT 1
- created_by, updated_by: bigint
- created_at, updated_at, deleted_at

materials (336KB)

-- 자재 마스터
- id: bigint (PK)
- tenant_id: bigint
- category_id: bigint (nullable)
- name: varchar(100)
- item_name: varchar(255)
- specification: varchar(100)
- material_code: varchar(50) UNIQUE
- unit: varchar(10)
- is_inspection: char(1) DEFAULT 'N'
- search_tag: text
- remarks: text
- attributes, options: json
- created_by, updated_by: bigint
- created_at, updated_at, deleted_at

categories (80KB)

-- 계층형 카테고리 시스템
- 동적 필드 정의 지원
- 버전 관리 (category_templates)

4. BOM 및 설계 관리

models (16KB)

-- 설계 모델 마스터
- 제품 설계의 상위 개념

model_versions (16KB)

-- 모델 버전 관리
- DRAFT/RELEASED 상태 관리
- 버전별 BOM 연결

bom_templates (16KB)

-- BOM 템플릿
- 모델 버전별 BOM 정의

bom_template_items (16KB)

-- BOM 아이템
- 자재/제품 구성 요소
- 수량, 손실률 등 관리

product_components (80KB)

-- 제품 구성 요소
- ref_type: MATERIAL|PRODUCT
- 다형성 관계 지원

5. 주문 및 견적 관리

orders (80KB)

-- 주문/견적 마스터
- 워크플로우 상태 관리

order_items (64KB)

-- 주문 항목
- 설계 코드 연결

order_item_components (64KB)

-- 주문별 소요 자재/제품

order_histories (64KB)

-- 주문 변경 이력

6. 감사 로그 시스템

audit_logs (16KB) - 최신 추가

-- 통합 감사 로그
- id: bigint (PK)
- tenant_id: bigint (테넌트 격리)
- target_type: varchar(100) -- 대상 모델
- target_id: bigint -- 대상 ID
- action: varchar(50) -- 액션 (created, updated, deleted 등)
- before: json -- 변경 전 데이터
- after: json -- 변경 후 데이터
- actor_id: bigint -- 수행자
- ip: varchar(45) -- IP 주소
- ua: varchar(255) -- User Agent
- created_at: timestamp DEFAULT CURRENT_TIMESTAMP

-- 최적화된 인덱스
- ix_audit_tenant_actor_created (tenant_id, actor_id, created_at)
- ix_audit_tenant_target_created (tenant_id, target_type, target_id, created_at)

7. 인벤토리 관리

material_receipts (32KB)

-- 자재 입고
- 로트 추적 지원

lots (48KB)

-- 로트 관리

material_inspections (32KB)

-- 품질 검사

8. 시스템 및 설정

api_keys (32KB)

-- API 키 관리
- 활성 상태 관리

classifications (48KB)

-- 코드 테이블
- 그룹별 코드 관리

setting_field_defs (32KB)

-- 글로벌 필드 정의

tenant_field_settings (32KB)

-- 테넌트별 필드 설정

9. 게시판 시스템

boards (32KB)

-- 게시판 설정

posts (64KB)

-- 게시물
- 동적 필드 지원

board_comments (80KB)

-- 계층형 댓글

🔍 데이터베이스 특징

Multi-Tenant Architecture

• 모든 주요 테이블에 tenant_id 컬럼으로 데이터 격리
• 테넌트별 코드 유니크 제약 (tenant_id, code)
• 글로벌 스키마 + 테넌트별 데이터 패턴

동적 필드 시스템

• attributes, options JSON 컬럼 활용
• 카테고리별 동적 필드 정의 지원
• 버전 관리된 템플릿 시스템

감사 추적

• 통합 감사 로그 시스템 구현
• 변경 전후 데이터 JSON 저장
• 성능 최적화된 인덱스 구조

BOM 관리

• 계층적 제품 구성 관리
• 자재/제품 다형성 참조
• 설계 버전별 BOM 템플릿

권한 관리

• Spatie Permission + 커스텀 확장
• 부서별 계층 권한
• 시간 기반 권한 재정의

⚠️ 주의사항

데이터 무결성

• Foreign Key 제약조건 최소화 (성능 고려)
• 애플리케이션 레벨에서 참조 무결성 관리
• Soft Delete 패턴 적용 (deleted_at)

성능 고려사항

• 대용량 테이블: products (432KB), materials (336KB)
• JSON 컬럼 활용으로 스키마 유연성 확보
• 테넌트별 데이터 분리로 쿼리 성능 최적화

백업 및 복원

• 테넌트별 데이터 분리 백업 가능
• 감사 로그 별도 보관 정책 필요 (13개월 보존)
• JSON 데이터 백업시 인코딩 주의

---

보고서 생성: Claude Code 검증 상태: ✅ 모든 테이블 스키마 정상 확인 다음 검토: 주요 업데이트시 또는 분기별