sam-docs/history/2025-09/database-schema.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)
```sql
-- 테넌트(회사/조직) 마스터
- 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)
```sql
-- 사용자 계정 마스터
- 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)
```sql
-- 사용자-테넌트 매핑 (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) - 가장 큰 테이블
```sql
-- 제품 카탈로그 마스터
- 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)
```sql
-- 자재 마스터
- 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)
```sql
-- 계층형 카테고리 시스템
- 동적 필드 정의 지원
- 버전 관리 (category_templates)
```

### 4. **BOM 및 설계 관리**

#### `models` (16KB)
```sql
-- 설계 모델 마스터
- 제품 설계의 상위 개념
```

#### `model_versions` (16KB)
```sql
-- 모델 버전 관리
- DRAFT/RELEASED 상태 관리
- 버전별 BOM 연결
```

#### `bom_templates` (16KB)
```sql
-- BOM 템플릿
- 모델 버전별 BOM 정의
```

#### `bom_template_items` (16KB)
```sql
-- BOM 아이템
- 자재/제품 구성 요소
- 수량, 손실률 등 관리
```

#### `product_components` (80KB)
```sql
-- 제품 구성 요소
- ref_type: MATERIAL|PRODUCT
- 다형성 관계 지원
```

### 5. **주문 및 견적 관리**

#### `orders` (80KB)
```sql
-- 주문/견적 마스터
- 워크플로우 상태 관리
```

#### `order_items` (64KB)
```sql
-- 주문 항목
- 설계 코드 연결
```

#### `order_item_components` (64KB)
```sql
-- 주문별 소요 자재/제품
```

#### `order_histories` (64KB)
```sql
-- 주문 변경 이력
```

### 6. **감사 로그 시스템**

#### `audit_logs` (16KB) - 최신 추가
```sql
-- 통합 감사 로그
- 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)
```sql
-- 자재 입고
- 로트 추적 지원
```

#### `lots` (48KB)
```sql
-- 로트 관리
```

#### `material_inspections` (32KB)
```sql
-- 품질 검사
```

### 8. **시스템 및 설정**

#### `api_keys` (32KB)
```sql
-- API 키 관리
- 활성 상태 관리
```

#### `classifications` (48KB)
```sql
-- 코드 테이블
- 그룹별 코드 관리
```

#### `setting_field_defs` (32KB)
```sql
-- 글로벌 필드 정의
```

#### `tenant_field_settings` (32KB)
```sql
-- 테넌트별 필드 설정
```

### 9. **게시판 시스템**

#### `boards` (32KB)
```sql
-- 게시판 설정
```

#### `posts` (64KB)
```sql
-- 게시물
- 동적 필드 지원
```

#### `board_comments` (80KB)
```sql
-- 계층형 댓글
```

## 🔍 데이터베이스 특징

### **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
**검증 상태**: ✅ 모든 테이블 스키마 정상 확인
**다음 검토**: 주요 업데이트시 또는 분기별