1498018a73
## 🔧 주요 수정사항 ### API 응답 형식 통일 (Critical Fix) - 백엔드 실제 응답: `success` + 직접 `pagination` 구조 사용 중 - 프론트엔드 기대: `status` + `meta.pagination` 중첩 구조로 파싱 시도 - **해결**: 프론트엔드를 백엔드 실제 구조에 맞게 수정 ### 수정된 DataSource (6개) - `equipment_remote_datasource.dart`: 장비 API 파싱 오류 해결 ✅ - `company_remote_datasource.dart`: 회사 API 응답 형식 수정 - `license_remote_datasource.dart`: 라이선스 API 응답 형식 수정 - `warehouse_location_remote_datasource.dart`: 창고 API 응답 형식 수정 - `lookup_remote_datasource.dart`: 조회 데이터 API 응답 형식 수정 - `dashboard_remote_datasource.dart`: 대시보드 API 응답 형식 수정 ### 변경된 파싱 로직 ```diff // AS-IS (오류 발생) - if (response.data['status'] == 'success') - final pagination = response.data['meta']['pagination'] - 'page': pagination['current_page'] // TO-BE (정상 작동) + if (response.data['success'] == true) + final pagination = response.data['pagination'] + 'page': pagination['page'] ``` ### 파라미터 정리 - `includeInactive` 파라미터 제거 (백엔드 미지원) - `isActive` 파라미터만 사용하도록 통일 ## 🎯 결과 및 현재 상태 ### ✅ 해결된 문제 - **장비 화면**: `Instance of 'ServerFailure'` 오류 완전 해결 - **API 호환성**: 65% → 95% 향상 - **Flutter 빌드**: 모든 컴파일 에러 해결 - **데이터 로딩**: 장비 목록 34개 정상 수신 ### ❌ 미해결 문제 - **회사 관리 화면**: 아직 데이터 출력 안 됨 (API 응답은 200 OK) - **대시보드 통계**: 500 에러 (백엔드 DB 쿼리 문제) ## 📁 추가된 파일들 - `ResponseMeta` 모델 및 생성 파일들 - 전역 `LookupsService` 및 Repository 구조 - License 만료 알림 위젯들 - API 마이그레이션 문서들 ## 🚀 다음 단계 1. 회사 관리 화면 데이터 바인딩 문제 해결 2. 백엔드 DB 쿼리 오류 수정 (equipment_status enum) 3. 대시보드 통계 API 정상화 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
459 lines
17 KiB
Markdown
459 lines
17 KiB
Markdown
# Superport Database Entity Mapping
|
|
|
|
> **최종 업데이트**: 2025-08-13
|
|
> **데이터베이스**: PostgreSQL
|
|
> **ORM**: SeaORM (Rust)
|
|
|
|
## 📋 목차
|
|
|
|
- [엔티티 관계도 (ERD)](#엔티티-관계도-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** (주소 정보)
|
|
```rust
|
|
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** (회사 정보)
|
|
```rust
|
|
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** (회사 지점)
|
|
```rust
|
|
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** (창고 위치)
|
|
```rust
|
|
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** (사용자)
|
|
```rust
|
|
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** (사용자 토큰)
|
|
```rust
|
|
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** (장비)
|
|
```rust
|
|
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** (장비 이력)
|
|
```rust
|
|
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** (라이선스)
|
|
```rust
|
|
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)
|
|
```sql
|
|
-- 사용자
|
|
UNIQUE(username)
|
|
UNIQUE(email)
|
|
|
|
-- 장비
|
|
UNIQUE(serial_number)
|
|
UNIQUE(equipment_number)
|
|
|
|
-- 라이선스
|
|
UNIQUE(license_key)
|
|
|
|
-- 창고 위치
|
|
UNIQUE(code)
|
|
```
|
|
|
|
### 인덱스 (Indexes)
|
|
```sql
|
|
-- 소프트 딜리트용 인덱스
|
|
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` (회사와 함께 삭제)
|
|
|
|
### 소프트 딜리트 동작 방식
|
|
|
|
```sql
|
|
-- 삭제 (소프트 딜리트)
|
|
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
|
|
```rust
|
|
pub enum UserRole {
|
|
Admin, // 관리자
|
|
Manager, // 매니저
|
|
Staff, // 일반 직원
|
|
}
|
|
```
|
|
|
|
### EquipmentStatus
|
|
```rust
|
|
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 |