superport/docs/migration/ENTITY_MAPPING.md

Superport Database Entity Mapping

최종 업데이트: 2025-08-13
데이터베이스: PostgreSQL
ORM: SeaORM (Rust)

📋 목차

• 엔티티 관계도 (ERD)
• 엔티티 정의
• 관계 매핑
• 인덱스 및 제약조건
• 소프트 딜리트 구조

---

🗺️ 엔티티 관계도 (ERD)

                    ┌─────────────┐
                    │  addresses  │
                    │─────────────│
                    │ id (PK)     │
                    │ si_do       │
                    │ si_gun_gu   │
                    │ eup_myeon_  │
                    │ dong        │
                    │ detail_     │
                    │ address     │
                    │ postal_code │
                    │ is_active   │
                    │ created_at  │
                    │ updated_at  │
                    └─────────────┘
                           │
                           │ 1:N
                           ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ companies   │    │ company_    │    │ warehouse_  │
│─────────────│    │ branches    │    │ locations   │
│ id (PK)     │◄──►│─────────────│    │─────────────│
│ name        │ 1:N│ id (PK)     │    │ id (PK)     │
│ address     │    │ company_id  │    │ name        │
│ address_id  │    │ (FK)        │    │ code (UQ)   │
│ contact_*   │    │ branch_name │    │ address_id  │
│ company_    │    │ address     │    │ (FK)        │
│ types       │    │ phone       │    │ manager_*   │
│ remark      │    │ address_id  │    │ capacity    │
│ is_active   │    │ (FK)        │    │ is_active   │
│ is_partner  │    │ manager_*   │    │ remark      │
│ is_customer │    │ remark      │    │ created_at  │
│ created_at  │    │ created_at  │    │ updated_at  │
│ updated_at  │    │ updated_at  │    └─────────────┘
└─────────────┘    └─────────────┘           │
       │                                     │
       │ 1:N                                │ 1:N
       ▼                                     ▼
┌─────────────┐                    ┌─────────────┐
│ licenses    │                    │ equipment   │
│─────────────│                    │─────────────│
│ id (PK)     │                    │ id (PK)     │
│ company_id  │                    │ manufacturer│
│ (FK)        │                    │ serial_     │
│ branch_id   │                    │ number (UQ) │
│ (FK)        │                    │ barcode     │
│ license_key │                    │ equipment_  │
│ (UQ)        │                    │ number (UQ) │
│ product_    │                    │ category1   │
│ name        │                    │ category2   │
│ vendor      │                    │ category3   │
│ license_    │                    │ model_name  │
│ type        │                    │ purchase_*  │
│ user_count  │                    │ status      │
│ purchase_*  │                    │ current_    │
│ expiry_date │                    │ company_id  │
│ is_active   │                    │ (FK)        │
│ remark      │                    │ current_    │
│ created_at  │                    │ branch_id   │
│ updated_at  │                    │ (FK)        │
└─────────────┘                    │ warehouse_  │
                                   │ location_id │
                                   │ (FK)        │
                                   │ inspection_*│
                                   │ is_active   │
                                   │ remark      │
                                   │ created_at  │
                                   │ updated_at  │
                                   └─────────────┘
                                          │
                                          │ 1:N
                                          ▼
                                   ┌─────────────┐
                                   │ equipment_  │
                                   │ history     │
                                   │─────────────│
                                   │ id (PK)     │
                                   │ equipment_  │
                                   │ id (FK)     │
                                   │ transaction_│
                                   │ type        │
                                   │ quantity    │
                                   │ transaction_│
                                   │ date        │
                                   │ remarks     │
                                   │ created_by  │
                                   │ user_id     │
                                   │ created_at  │
                                   └─────────────┘

┌─────────────┐                    ┌─────────────┐
│ users       │                    │ user_tokens │
│─────────────│ 1:N               │─────────────│
│ id (PK)     │◄──────────────────►│ id (PK)     │
│ username    │                    │ user_id     │
│ (UQ)        │                    │ (FK)        │
│ email (UQ)  │                    │ token       │
│ password_   │                    │ expires_at  │
│ hash        │                    │ created_at  │
│ name        │                    └─────────────┘
│ phone       │
│ role        │
│ is_active   │
│ created_at  │
│ updated_at  │
└─────────────┘

---

📊 엔티티 정의

1. addresses (주소 정보)

pub struct Model {
    pub id: i32,                    // 기본키
    pub si_do: String,              // 시/도 (필수)
    pub si_gun_gu: String,          // 시/군/구 (필수)
    pub eup_myeon_dong: String,     // 읍/면/동 (필수)
    pub detail_address: Option<String>, // 상세주소
    pub postal_code: Option<String>, // 우편번호
    pub is_active: bool,            // 소프트 딜리트 플래그
    pub created_at: Option<DateTimeWithTimeZone>,
    pub updated_at: Option<DateTimeWithTimeZone>,
}

2. companies (회사 정보)

pub struct Model {
    pub id: i32,                    // 기본키
    pub name: String,               // 회사명 (필수)
    pub address: Option<String>,    // 주소 (레거시)
    pub address_id: Option<i32>,    // 주소 FK
    pub contact_name: Option<String>, // 담당자명
    pub contact_position: Option<String>, // 담당자 직책
    pub contact_phone: Option<String>, // 담당자 전화번호
    pub contact_email: Option<String>, // 담당자 이메일
    pub company_types: Option<Vec<String>>, // 회사 유형 배열
    pub remark: Option<String>,     // 비고
    pub is_active: Option<bool>,    // 활성화 상태
    pub is_partner: Option<bool>,   // 파트너사 여부
    pub is_customer: Option<bool>,  // 고객사 여부
    pub created_at: Option<DateTimeWithTimeZone>,
    pub updated_at: Option<DateTimeWithTimeZone>,
}

3. company_branches (회사 지점)

pub struct Model {
    pub id: i32,                    // 기본키
    pub company_id: i32,            // 회사 FK (필수)
    pub branch_name: String,        // 지점명 (필수)
    pub address: Option<String>,    // 주소
    pub phone: Option<String>,      // 전화번호
    pub address_id: Option<i32>,    // 주소 FK
    pub manager_name: Option<String>, // 관리자명
    pub manager_phone: Option<String>, // 관리자 전화번호
    pub remark: Option<String>,     // 비고
    pub created_at: Option<DateTimeWithTimeZone>,
    pub updated_at: Option<DateTimeWithTimeZone>,
}

4. warehouse_locations (창고 위치)

pub struct Model {
    pub id: i32,                    // 기본키
    pub name: String,               // 창고명 (필수)
    pub code: String,               // 창고 코드 (고유)
    pub address_id: Option<i32>,    // 주소 FK
    pub manager_name: Option<String>, // 관리자명
    pub manager_phone: Option<String>, // 관리자 전화번호
    pub capacity: Option<i32>,      // 수용 용량
    pub is_active: Option<bool>,    // 활성화 상태
    pub remark: Option<String>,     // 비고
    pub created_at: Option<DateTimeWithTimeZone>,
    pub updated_at: Option<DateTimeWithTimeZone>,
}

5. users (사용자)

pub struct Model {
    pub id: i32,                    // 기본키
    pub username: String,           // 사용자명 (고유)
    pub email: String,              // 이메일 (고유)
    pub password_hash: String,      // 비밀번호 해시 (필수)
    pub name: String,               // 실명 (필수)
    pub phone: Option<String>,      // 전화번호
    pub role: UserRole,             // 권한 (Enum: admin/manager/staff)
    pub is_active: Option<bool>,    // 활성화 상태
    pub created_at: Option<DateTimeWithTimeZone>,
    pub updated_at: Option<DateTimeWithTimeZone>,
}

6. user_tokens (사용자 토큰)

pub struct Model {
    pub id: i32,                    // 기본키
    pub user_id: i32,               // 사용자 FK
    pub token: String,              // 리프레시 토큰
    pub expires_at: DateTimeWithTimeZone, // 만료 시간
    pub created_at: Option<DateTimeWithTimeZone>,
}

7. equipment (장비)

pub struct Model {
    pub id: i32,                    // 기본키
    pub manufacturer: String,       // 제조사 (필수)
    pub serial_number: Option<String>, // 시리얼 번호 (고유)
    pub barcode: Option<String>,    // 바코드
    pub equipment_number: String,   // 장비 번호 (고유)
    pub category1: Option<String>,  // 카테고리 1
    pub category2: Option<String>,  // 카테고리 2
    pub category3: Option<String>,  // 카테고리 3
    pub model_name: Option<String>, // 모델명
    pub purchase_date: Option<Date>, // 구매일
    pub purchase_price: Option<Decimal>, // 구매가격
    pub status: Option<EquipmentStatus>, // 상태 (Enum)
    pub current_company_id: Option<i32>, // 현재 회사 FK
    pub current_branch_id: Option<i32>, // 현재 지점 FK
    pub warehouse_location_id: Option<i32>, // 창고 위치 FK
    pub last_inspection_date: Option<Date>, // 마지막 점검일
    pub next_inspection_date: Option<Date>, // 다음 점검일
    pub remark: Option<String>,     // 비고
    pub is_active: bool,            // 활성화 상태
    pub created_at: Option<DateTimeWithTimeZone>,
    pub updated_at: Option<DateTimeWithTimeZone>,
}

8. equipment_history (장비 이력)

pub struct Model {
    pub id: i32,                    // 기본키
    pub equipment_id: i32,          // 장비 FK (필수)
    pub transaction_type: String,   // 거래 유형 (필수)
    pub quantity: i32,              // 수량 (필수)
    pub transaction_date: DateTimeWithTimeZone, // 거래일 (필수)
    pub remarks: Option<String>,    // 비고
    pub created_by: Option<i32>,    // 생성자 FK
    pub user_id: Option<i32>,       // 사용자 FK
    pub created_at: Option<DateTimeWithTimeZone>,
}

9. licenses (라이선스)

pub struct Model {
    pub id: i32,                    // 기본키
    pub company_id: Option<i32>,    // 회사 FK
    pub branch_id: Option<i32>,     // 지점 FK
    pub license_key: String,        // 라이선스 키 (고유)
    pub product_name: Option<String>, // 제품명
    pub vendor: Option<String>,     // 공급업체
    pub license_type: Option<String>, // 라이선스 유형
    pub user_count: Option<i32>,    // 사용자 수
    pub purchase_date: Option<Date>, // 구매일
    pub expiry_date: Option<Date>,  // 만료일
    pub purchase_price: Option<Decimal>, // 구매가격
    pub remark: Option<String>,     // 비고
    pub is_active: Option<bool>,    // 활성화 상태
    pub created_at: Option<DateTimeWithTimeZone>,
    pub updated_at: Option<DateTimeWithTimeZone>,
}

---

🔗 관계 매핑

1:N 관계

부모 테이블	자식 테이블	외래키	관계 설명
addresses	companies	address_id	주소 → 회사
addresses	company_branches	address_id	주소 → 지점
addresses	warehouse_locations	address_id	주소 → 창고
companies	company_branches	company_id	회사 → 지점
companies	equipment	current_company_id	회사 → 장비
companies	licenses	company_id	회사 → 라이선스
company_branches	equipment	current_branch_id	지점 → 장비
company_branches	licenses	branch_id	지점 → 라이선스
warehouse_locations	equipment	warehouse_location_id	창고 → 장비
equipment	equipment_history	equipment_id	장비 → 이력
users	user_tokens	user_id	사용자 → 토큰

관계 제약조건

• CASCADE DELETE: companies → company_branches
• NO ACTION: 나머지 모든 관계 (데이터 무결성 보장)
• UNIQUE 제약: serial_number, equipment_number, license_key, warehouse_code

---

📇 인덱스 및 제약조건

기본키 (Primary Key)

모든 테이블에서 id 컬럼이 SERIAL PRIMARY KEY

고유 제약조건 (Unique Constraints)

-- 사용자
UNIQUE(username)
UNIQUE(email)

-- 장비
UNIQUE(serial_number)
UNIQUE(equipment_number)

-- 라이선스
UNIQUE(license_key)

-- 창고 위치
UNIQUE(code)

인덱스 (Indexes)

-- 소프트 딜리트용 인덱스
CREATE INDEX idx_companies_is_active ON companies(is_active);
CREATE INDEX idx_equipment_is_active ON equipment(is_active);
CREATE INDEX idx_licenses_is_active ON licenses(is_active);
CREATE INDEX idx_warehouse_locations_is_active ON warehouse_locations(is_active);
CREATE INDEX idx_addresses_is_active ON addresses(is_active);
CREATE INDEX idx_users_is_active ON users(is_active);

-- 복합 인덱스 (성능 최적화)
CREATE INDEX idx_company_branches_company_id_is_active 
    ON company_branches(company_id, is_active);
CREATE INDEX idx_equipment_company_id_is_active 
    ON equipment(company_id, is_active);
CREATE INDEX idx_licenses_company_id_is_active 
    ON licenses(company_id, is_active);

---

🗑️ 소프트 딜리트 구조

소프트 딜리트 적용 테이블

• ✅ companies
• ✅ equipment
• ✅ licenses
• ✅ warehouse_locations
• ✅ addresses
• ✅ users
• ❌ equipment_history (이력은 보존)
• ❌ user_tokens (자동 만료)
• ❌ company_branches (회사와 함께 삭제)

소프트 딜리트 동작 방식

-- 삭제 (소프트 딜리트)
UPDATE companies SET is_active = false WHERE id = 1;

-- 조회 (활성 데이터만)
SELECT * FROM companies WHERE is_active = true;

-- 조회 (삭제된 데이터만)
SELECT * FROM companies WHERE is_active = false;

-- 복구
UPDATE companies SET is_active = true WHERE id = 1;

연관된 데이터 처리 규칙

1. 회사 삭제 시:

   • 회사: is_active = false
   • 지점: CASCADE DELETE (물리 삭제)
   • 장비: current_company_id = NULL
   • 라이선스: is_active = false

2. 장비 삭제 시:

   • 장비: is_active = false
   • 이력: 유지 (삭제 안됨)

3. 사용자 삭제 시:

   • 사용자: is_active = false
   • 토큰: 물리 삭제

---

📈 Enum 타입 정의

UserRole

pub enum UserRole {
    Admin,      // 관리자
    Manager,    // 매니저
    Staff,      // 일반 직원
}

EquipmentStatus

pub enum EquipmentStatus {
    Available,   // 사용 가능
    Inuse,      // 사용 중
    Maintenance, // 점검 중
    Disposed,   // 폐기
}

---

🔄 마이그레이션 이력

Migration 001: 기본 테이블 생성

• 모든 핵심 테이블 생성
• 기본 관계 설정

Migration 002: 회사 타입 필드 추가

• company_types 배열 필드
• is_partner, is_customer 플래그

Migration 003: 소프트 딜리트 구현

• 모든 테이블에 is_active 필드 추가
• 성능 최적화용 인덱스 생성

Migration 004: 관계 정리

• 불필요한 관계 제거
• 제약조건 최적화

Migration 005: 제약조건 수정

• CASCADE 규칙 조정
• 외래키 제약조건 강화

---

문서 버전: 1.0
최종 검토: 2025-08-13
담당자: Database Engineering Team