julian/superport
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

사용하지 않는 파일 정리 전 백업 (Phase 10 완료 후 상태)

Browse Source
This commit is contained in:
JiWoong Sul
2025-08-29 15:11:59 +09:00
parent a740ff10c8
commit d916b281a7
333 changed files with 53617 additions and 22574 deletions
Download Patch File Download Diff File Expand all files Collapse all files

376
docs/migration/API_SCHEMA.md
View File

@@ -1,376 +0,0 @@
# Superport API Schema Documentation
> **최종 업데이트**: 2025-08-13
> **API 버전**: v1
> **Base URL**: `http://43.201.34.104:8080/api/v1`
## 📋 목차
- [인증 시스템](#인증-시스템)
- [API 엔드포인트 목록](#api-엔드포인트-목록)
- [Request/Response 형식](#requestresponse-형식)
- [페이지네이션](#페이지네이션)
- [에러 처리](#에러-처리)
- [상태 코드](#상태-코드)
---
## 🔐 인증 시스템
### JWT Token 기반 인증
- **토큰 타입**: Bearer Token
- **만료 시간**: 24시간
- **권한 레벨**: Admin, Manager, Staff
```http
Authorization: Bearer <JWT_TOKEN>
```
### 권한 매트릭스
| 역할 | 생성 | 조회 | 수정 | 삭제 |
|------|------|------|------|------|
| **Admin** | ✅ | ✅ | ✅ | ✅ |
| **Manager** | ✅ | ✅ | ✅ | ✅ |
| **Staff** | ⚠️ | ✅ | ⚠️ | ❌ |
> ⚠️ = 제한적 권한 (일부 엔드포인트만)
---
## 📡 API 엔드포인트 목록
### 🔑 Authentication (`/auth`)
| Method | Endpoint | 권한 | 설명 |
|--------|----------|------|------|
| `POST` | `/auth/login` | 공개 | 사용자 로그인 |
| `POST` | `/auth/logout` | 공개 | 사용자 로그아웃 |
| `POST` | `/auth/refresh` | 공개 | 토큰 갱신 |
| `GET` | `/me` | 인증필요 | 현재 사용자 정보 |
### 🏢 Companies (`/companies`)
| Method | Endpoint | 권한 | 설명 |
|--------|----------|------|------|
| `GET` | `/companies` | 인증필요 | 회사 목록 조회 (페이지네이션) |
| `POST` | `/companies` | Admin/Manager | 회사 생성 |
| `GET` | `/companies/search` | 인증필요 | 회사 검색 |
| `GET` | `/companies/names` | 인증필요 | 회사명 목록 |
| `GET` | `/companies/branches` | 인증필요 | 지점 정보 목록 |
| `GET` | `/companies/{id}` | 인증필요 | 특정 회사 조회 |
| `PUT` | `/companies/{id}` | Admin/Manager | 회사 정보 수정 |
| `DELETE` | `/companies/{id}` | Admin/Manager | 회사 삭제 (소프트 딜리트) |
| `PATCH` | `/companies/{id}/status` | Admin/Manager | 회사 활성화 상태 변경 |
| `DELETE` | `/companies/{id}/branches/{branch_id}` | Admin/Manager | 지점 삭제 |
### 👥 Users (`/users`)
| Method | Endpoint | 권한 | 설명 |
|--------|----------|------|------|
| `GET` | `/users` | Admin/Manager | 사용자 목록 조회 |
| `POST` | `/users` | Admin | 사용자 생성 |
| `GET` | `/users/{id}` | Admin/Manager | 특정 사용자 조회 |
| `PUT` | `/users/{id}` | Admin | 사용자 정보 수정 |
| `DELETE` | `/users/{id}` | Admin | 사용자 삭제 |
### 🔧 Equipment (`/equipment`)
| Method | Endpoint | 권한 | 설명 |
|--------|----------|------|------|
| `GET` | `/equipment` | 인증필요 | 장비 목록 조회 (페이지네이션) |
| `POST` | `/equipment` | Admin/Manager | 장비 생성 |
| `GET` | `/equipment/{id}` | 인증필요 | 특정 장비 조회 |
| `PUT` | `/equipment/{id}` | Admin/Manager | 장비 정보 수정 |
| `DELETE` | `/equipment/{id}` | Admin/Manager | 장비 삭제 (소프트 딜리트) |
| `PATCH` | `/equipment/{id}/status` | 인증필요 | 장비 상태 변경 |
| `POST` | `/equipment/{id}/history` | 인증필요 | 장비 이력 추가 |
| `GET` | `/equipment/{id}/history` | 인증필요 | 장비 이력 조회 |
### 📄 Licenses (`/licenses`)
| Method | Endpoint | 권한 | 설명 |
|--------|----------|------|------|
| `GET` | `/licenses` | 인증필요 | 라이선스 목록 조회 |
| `POST` | `/licenses` | Admin/Manager | 라이선스 생성 |
| `GET` | `/licenses/{id}` | 인증필요 | 특정 라이선스 조회 |
| `PUT` | `/licenses/{id}` | Admin/Manager | 라이선스 수정 |
| `DELETE` | `/licenses/{id}` | Admin/Manager | 라이선스 삭제 |
### 🏪 Warehouse Locations (`/warehouse-locations`)
| Method | Endpoint | 권한 | 설명 |
|--------|----------|------|------|
| `GET` | `/warehouse-locations` | 인증필요 | 창고 위치 목록 조회 |
| `POST` | `/warehouse-locations` | Admin/Manager | 창고 위치 생성 |
| `GET` | `/warehouse-locations/{id}` | 인증필요 | 특정 창고 위치 조회 |
| `PUT` | `/warehouse-locations/{id}` | Admin/Manager | 창고 위치 수정 |
| `DELETE` | `/warehouse-locations/{id}` | Admin/Manager | 창고 위치 삭제 |
### 📍 Addresses (`/addresses`)
| Method | Endpoint | 권한 | 설명 |
|--------|----------|------|------|
| `GET` | `/addresses` | 인증필요 | 주소 목록 조회 |
| `POST` | `/addresses` | Admin/Manager | 주소 생성 |
| `GET` | `/addresses/{id}` | 인증필요 | 특정 주소 조회 |
| `PUT` | `/addresses/{id}` | Admin/Manager | 주소 수정 |
| `DELETE` | `/addresses/{id}` | Admin/Manager | 주소 삭제 |
### 📊 Overview (`/overview`)
| Method | Endpoint | 권한 | 설명 |
|--------|----------|------|------|
| `GET` | `/overview/stats` | 인증필요 | 대시보드 통계 |
| `GET` | `/overview/recent-activities` | 인증필요 | 최근 활동 내역 |
| `GET` | `/overview/equipment-status` | Staff 이상 | 장비 상태 분포 |
| `GET` | `/overview/license-expiry` | Manager 이상 | 라이선스 만료 요약 |
### 🔍 Lookups (`/lookups`)
| Method | Endpoint | 권한 | 설명 |
|--------|----------|------|------|
| `GET` | `/lookups` | 인증필요 | 전체 조회 데이터 |
| `GET` | `/lookups/type` | 인증필요 | 타입별 조회 데이터 |
### ❤️ Health (`/health`)
| Method | Endpoint | 권한 | 설명 |
|--------|----------|------|------|
| `GET` | `/health` | 공개 | 서버 상태 체크 |
---
## 📄 Request/Response 형식
### 표준 응답 형식
```json
{
"status": "success",
"message": "Operation completed successfully",
"data": { /* 실제 데이터 */ },
"meta": { /* 메타데이터 (페이지네이션 등) */ }
}
```
### 주요 DTO 구조
#### 🏢 Company DTO
**CreateCompanyRequest**:
```json
{
"name": "회사명 (필수)",
"address": "주소 (선택)",
"contact_name": "담당자명 (선택)",
"contact_position": "담당자 직책 (선택)",
"contact_phone": "연락처 (선택)",
"contact_email": "이메일 (선택)",
"company_types": ["타입1", "타입2"],
"remark": "비고 (선택)",
"is_partner": false,
"is_customer": true
}
```
**CompanyResponse**:
```json
{
"id": 1,
"name": "주식회사 테스트",
"address": "서울시 강남구",
"contact_name": "홍길동",
"contact_position": "팀장",
"contact_phone": "010-1234-5678",
"contact_email": "test@company.com",
"company_types": ["고객사", "파트너사"],
"remark": "중요 거래처",
"is_active": true,
"is_partner": false,
"is_customer": true,
"created_at": "2025-08-13T10:00:00Z",
"updated_at": "2025-08-13T10:00:00Z"
}
```
#### 🔧 Equipment DTO
**CreateEquipmentRequest**:
```json
{
"equipment_number": "EQ-001 (필수)",
"category1": "카테고리1 (선택)",
"category2": "카테고리2 (선택)",
"category3": "카테고리3 (선택)",
"manufacturer": "제조사 (필수)",
"model_name": "모델명 (선택)",
"serial_number": "시리얼번호 (선택)",
"purchase_date": "2025-08-13",
"purchase_price": "1000000.00",
"remark": "비고 (선택)"
}
```
**EquipmentResponse**:
```json
{
"id": 1,
"equipment_number": "EQ-001",
"category1": "IT장비",
"category2": "서버",
"category3": "웹서버",
"manufacturer": "삼성전자",
"model_name": "Galaxy Server Pro",
"serial_number": "SN123456789",
"barcode": "BC123456789",
"purchase_date": "2025-08-13",
"purchase_price": "1000000.00",
"status": "available",
"current_company_id": 1,
"current_branch_id": null,
"warehouse_location_id": 1,
"last_inspection_date": "2025-08-01",
"next_inspection_date": "2026-08-01",
"remark": "정상 작동 중",
"created_at": "2025-08-13T10:00:00Z",
"updated_at": "2025-08-13T10:00:00Z"
}
```
#### 🔑 Authentication DTO
**LoginRequest**:
```json
{
"username": "admin",
"password": "password123"
}
```
**LoginResponse**:
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400,
"user": {
"id": 1,
"username": "admin",
"name": "관리자",
"email": "admin@superport.kr",
"role": "admin"
}
}
```
---
## 📄 페이지네이션
### 요청 파라미터
```http
GET /api/v1/companies?page=1&per_page=20&is_active=true
```
### 응답 형식
```json
{
"status": "success",
"data": [ /* 데이터 배열 */ ],
"meta": {
"pagination": {
"current_page": 1,
"per_page": 20,
"total": 150,
"total_pages": 8,
"has_next": true,
"has_prev": false
}
}
}
```
### 소프트 딜리트 필터링
- `is_active=true`: 활성 데이터만
- `is_active=false`: 삭제된 데이터만
- `is_active` 미지정: 모든 데이터
---
## ⚠️ 에러 처리
### 에러 응답 형식
```json
{
"status": "error",
"message": "에러 메시지",
"error": {
"code": "VALIDATION_ERROR",
"details": [
{
"field": "name",
"message": "Company name is required"
}
]
}
}
```
### 에러 코드 목록
| 코드 | 설명 |
|------|------|
| `VALIDATION_ERROR` | 입력 값 검증 실패 |
| `UNAUTHORIZED` | 인증 실패 |
| `FORBIDDEN` | 권한 부족 |
| `NOT_FOUND` | 리소스 없음 |
| `INTERNAL_ERROR` | 서버 내부 오류 |
| `DATABASE_ERROR` | 데이터베이스 오류 |
---
## 📊 상태 코드
| HTTP 코드 | 상태 | 설명 |
|-----------|------|------|
| `200` | OK | 성공 |
| `201` | Created | 생성 성공 |
| `400` | Bad Request | 잘못된 요청 |
| `401` | Unauthorized | 인증 실패 |
| `403` | Forbidden | 권한 부족 |
| `404` | Not Found | 리소스 없음 |
| `422` | Unprocessable Entity | 입력 값 검증 실패 |
| `500` | Internal Server Error | 서버 오류 |
---
## 🔍 Enum 값 정의
### EquipmentStatus
- `available`: 사용 가능
- `inuse`: 사용 중
- `maintenance`: 점검 중
- `disposed`: 폐기
### UserRole
- `admin`: 관리자
- `manager`: 매니저
- `staff`: 일반 직원
---
## 🚀 특별 기능
### 1. 소프트 딜리트 시스템
모든 주요 엔티티에서 `is_active` 필드를 통한 논리적 삭제 지원
### 2. 권한 기반 접근 제어
JWT 토큰의 `role` 클레임을 통한 세밀한 권한 제어
### 3. 페이지네이션 최적화
대량 데이터 처리를 위한 효율적인 페이지네이션
### 4. 실시간 통계
대시보드용 실시간 통계 API 제공
---
**문서 버전**: 1.0
**최종 검토**: 2025-08-13
**담당자**: Backend Development Team

2
docs/migration/CURRENT_STATE.md
View File

@@ -338,7 +338,7 @@ test/
#### 테스트 환경
- **Target API**: `http://43.201.34.104:8080/api/v1`
- **Test Account**: `admin@superport.kr / admin123!`
- **Test Account**: `admin@example.com / password123`
- **Coverage**: 5개 주요 화면 (Company, Equipment, License, User, Overview)
#### 테스트 품질

459
docs/migration/ENTITY_MAPPING.md
View File

@@ -1,459 +0,0 @@
# 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

509
docs/migration/INCOMPATIBILITY.md
View File

@@ -1,509 +0,0 @@
# API 호환성 문제 목록
> **분석 일자**: 2025-08-13
> **대상**: Superport Flutter 앱 vs Backend API Schema
> **기준 문서**: API_SCHEMA.md, ENTITY_MAPPING.md, MIGRATION_GUIDE.md
## 📋 목차
- [심각도 분류](#심각도-분류)
- [Critical Issues](#critical-issues-즉시-수정-필요)
- [Major Issues](#major-issues-우선-수정-필요)
- [Minor Issues](#minor-issues-점진적-개선)
- [Missing Features](#missing-features-신규-구현)
- [마이그레이션 로드맵](#마이그레이션-로드맵)
---
## 🚦 심각도 분류
| 심각도 | 설명 | 대응 시간 | 영향도 |
|--------|------|-----------|--------|
| 🔴 **Critical** | 앱 기능 중단, 데이터 손실 위험 | 즉시 (1일 이내) | 전체 시스템 |
| 🟡 **Major** | 주요 기능 제한, UX 문제 | 1주일 이내 | 핵심 기능 |
| 🟢 **Minor** | 사소한 불편, 최적화 | 1개월 이내 | 개별 기능 |
| 🔵 **Enhancement** | 신규 기능, 성능 개선 | 장기 계획 | 추가 가치 |
---
## 🔴 Critical Issues (즉시 수정 필요)
### 1. API 응답 형식 불일치
**문제점**: 현재 코드와 API 스키마의 응답 구조가 완전히 다름
#### 현재 코드 (잘못됨)
```dart
// lib/data/models/common/api_response.dart
@Freezed(genericArgumentFactories: true)
class ApiResponse<T> with _$ApiResponse<T> {
const factory ApiResponse({
required bool success, // ❌ 잘못된 필드명
required String message,
T? data,
String? error,
}) = _ApiResponse<T>;
}
```
#### API 스키마 (정답)
```json
{
"status": "success", // ✅ 올바른 필드명
"message": "Operation completed successfully",
"data": { /* 실제 데이터 */ },
"meta": { /* 메타데이터 (페이지네이션 등) */ }
}
```
**영향도**: 🔥 **극심함** - 모든 API 호출이 영향받음
**수정 방법**:
```dart
// 수정된 ApiResponse
@Freezed(genericArgumentFactories: true)
class ApiResponse<T> with _$ApiResponse<T> {
const factory ApiResponse({
required String status, // success/error
required String message,
T? data,
ResponseMeta? meta, // 새로 추가
}) = _ApiResponse<T>;
}
// 새로운 메타 클래스
@freezed
class ResponseMeta with _$ResponseMeta {
const factory ResponseMeta({
PaginationMeta? pagination,
}) = _ResponseMeta;
}
```
### 2. 페이지네이션 메타데이터 구조 불일치
**문제점**: 페이지네이션 응답 구조가 API 스키마와 다름
#### 현재 코드 응답 파싱
```dart
// lib/data/datasources/remote/company_remote_datasource.dart (line 88-104)
final responseData = response.data;
if (responseData['success'] == true && responseData['data'] != null) { // ❌
final List<dynamic> dataList = responseData['data'];
final pagination = responseData['pagination'] ?? {}; // ❌
return PaginatedResponse<CompanyListDto>(
items: items,
page: pagination['page'] ?? page,
size: pagination['per_page'] ?? perPage,
totalElements: pagination['total'] ?? 0, // ❌ 필드명 불일치
totalPages: pagination['total_pages'] ?? 1,
// ...
);
}
```
#### API 스키마 올바른 구조
```json
{
"status": "success",
"data": [...],
"meta": {
"pagination": {
"current_page": 1,
"per_page": 20,
"total": 150,
"total_pages": 8,
"has_next": true,
"has_prev": false
}
}
}
```
**수정 방법**:
```dart
// 올바른 응답 파싱
if (responseData['status'] == 'success' && responseData['data'] != null) {
final List<dynamic> dataList = responseData['data'];
final meta = responseData['meta']?['pagination'] ?? {};
return PaginatedResponse<CompanyListDto>(
items: items,
page: meta['current_page'] ?? page,
size: meta['per_page'] ?? perPage,
totalElements: meta['total'] ?? 0,
totalPages: meta['total_pages'] ?? 1,
first: !(meta['has_prev'] ?? false),
last: !(meta['has_next'] ?? false),
);
}
```
### 3. 소프트 딜리트 파라미터 불일치
**문제점**: API는 `is_active` 파라미터를 요구하지만, 일부 코드에서는 `includeInactive` 사용
#### 현재 코드 (혼재)
```dart
// lib/data/datasources/remote/company_remote_datasource.dart (line 72-78)
Future<PaginatedResponse<CompanyListDto>> getCompanies({
// ...
bool? isActive, // ✅ 올바름
bool includeInactive = false, // ❌ API 스키마에 없음
}) async {
final queryParams = {
if (isActive != null) 'is_active': isActive, // ✅ 올바름
'include_inactive': includeInactive, // ❌ 제거해야 함
};
}
```
#### API 스키마 정의
```http
GET /api/v1/companies?page=1&per_page=20&is_active=true
```
- `is_active=true`: 활성 데이터만
- `is_active=false`: 삭제된 데이터만
- `is_active` 미지정: 모든 데이터
**수정 방법**: `includeInactive` 파라미터 제거 및 `is_active`만 사용
---
## 🟡 Major Issues (우선 수정 필요)
### 4. JWT 토큰 구조 변경
**문제점**: JWT 클레임 구조가 변경됨
#### 기존 JWT (추정)
```json
{
"user_id": 1,
"username": "admin",
"role": "admin"
}
```
#### 새로운 JWT 구조
```json
{
"sub": 1, // user_id 대신 sub 사용
"username": "admin",
"role": "admin", // admin|manager|staff
"exp": 1700000000,
"iat": 1699999000
}
```
**영향도**: AuthInterceptor 및 토큰 파싱 로직 수정 필요
### 5. Equipment 상태 Enum 확장
**문제점**: 장비 상태에 새로운 값 추가됨
#### 현재 Equipment 상태
```dart
// lib/data/models/equipment/equipment_dto.dart
enum EquipmentStatus {
@JsonValue('available') available,
@JsonValue('inuse') inuse,
@JsonValue('maintenance') maintenance,
// disposed가 누락됨
}
```
#### API 스키마 Equipment 상태
```dart
enum EquipmentStatus {
available, // 사용 가능
inuse, // 사용 중
maintenance, // 점검 중
disposed, // 폐기 ⬅️ 새로 추가됨
}
```
**수정 방법**: EquipmentStatus enum에 `disposed` 추가
### 6. Company 모델 필드 누락
**문제점**: Company DTO에 새로운 필드들이 누락됨
#### 현재 CompanyResponse
```dart
@freezed
class CompanyResponse with _$CompanyResponse {
const factory CompanyResponse({
// ... 기존 필드들
@JsonKey(name: 'is_partner') @Default(false) bool isPartner,
@JsonKey(name: 'is_customer') @Default(false) bool isCustomer,
// company_types 필드는 이미 있음
}) = _CompanyResponse;
}
```
#### API 스키마에서 추가된 필드
```dart
// CreateCompanyRequest에 추가 필요
@JsonKey(name: 'company_types') List<String>? companyTypes, // ✅ 이미 있음
@JsonKey(name: 'is_partner') bool? isPartner, // ✅ 이미 있음
@JsonKey(name: 'is_customer') bool? isCustomer, // ✅ 이미 있음
```
**상태**: ✅ 이미 대부분 구현됨 (양호)
---
## 🟢 Minor Issues (점진적 개선)
### 7. 에러 응답 처리 개선
**문제점**: 에러 응답 구조가 표준화되지 않음
#### 현재 에러 처리
```dart
// lib/data/datasources/remote/company_remote_datasource.dart
catch (e, stackTrace) {
if (e is ApiException) rethrow;
throw ApiException(message: 'Error creating company: $e');
}
```
#### API 스키마 표준 에러 형식
```json
{
"status": "error",
"message": "에러 메시지",
"error": {
"code": "VALIDATION_ERROR",
"details": [
{
"field": "name",
"message": "Company name is required"
}
]
}
}
```
**개선 방법**: 구조화된 에러 객체 생성
### 8. 권한별 API 접근 제어
**문제점**: 일부 화면에서 사용자 권한 확인 누락
#### 권한 매트릭스 (API 스키마)
| 역할 | 생성 | 조회 | 수정 | 삭제 |
|------|------|------|------|------|
| **Admin** | ✅ | ✅ | ✅ | ✅ |
| **Manager** | ✅ | ✅ | ✅ | ✅ |
| **Staff** | ⚠️ | ✅ | ⚠️ | ❌ |
**현재 상태**: UI에서 권한 체크 미흡
**개선 방법**:
```dart
// 권한 기반 UI 제어
if (currentUser.role == UserRole.staff) {
return SizedBox(); // 삭제 버튼 숨김
}
```
### 9. 날짜/시간 형식 통일
**문제점**: 날짜 필드의 타입과 형식이 일관되지 않음
#### 현재 혼재된 형식
```dart
@JsonKey(name: 'purchase_date') String? purchaseDate, // ❌ String
@JsonKey(name: 'created_at') DateTime createdAt, // ✅ DateTime
```
#### 권장 표준
```dart
@JsonKey(name: 'purchase_date') DateTime? purchaseDate, // ✅ 모두 DateTime
@JsonKey(name: 'created_at') DateTime createdAt,
```
---
## 🔵 Missing Features (신규 구현)
### 10. Lookups API 미구현
**상태**: ❌ 완전히 미구현
#### API 스키마에서 제공
```http
GET /lookups # 전체 마스터 데이터
GET /lookups/type # 타입별 마스터 데이터
```
#### 예상 활용도
- 드롭다운 옵션 동적 로딩
- 장비 카테고리, 제조사 목록
- 상태 코드, 타입 코드 관리
**구현 필요도**: 🟡 **Medium** (성능 최적화에 도움)
### 11. Health Check API 미구현
**상태**: ❌ 완전히 미구현
#### API 스키마
```http
GET /health # 서버 상태 체크
```
**활용 방안**:
- 앱 시작 시 서버 연결 확인
- 주기적 헬스체크 (30초 간격)
- 네트워크 오류와 서버 오류 구분
**구현 필요도**: 🟢 **Low** (운영 편의성)
### 12. Overview API 부분 구현
**상태**: ⚠️ **부분 구현**
#### 구현된 API
- ✅ `/overview/stats` - 대시보드 통계
- ✅ `/overview/license-expiry` - 라이선스 만료 요약
#### 미구현 API
- ❌ `/overview/recent-activities` - 최근 활동 내역
- ❌ `/overview/equipment-status` - 장비 상태 분포
**현재 처리 방식**: 404 에러를 받으면 빈 데이터 반환
```dart
// lib/data/datasources/remote/dashboard_remote_datasource.dart (line 61-65)
if (e.response?.statusCode == 404) {
return Right([]); // 빈 리스트 반환
}
```
---
## 🗓️ 마이그레이션 로드맵
### Phase 1: Critical Issues 해결 (1주일)
#### 1.1 API 응답 형식 통일 (2일)
- [ ] `ApiResponse` 클래스 수정 (`success` → `status`)
- [ ] `ResponseMeta` 클래스 신규 생성
- [ ] 모든 DataSource 응답 파싱 로직 수정
- [ ] ResponseInterceptor 업데이트
#### 1.2 페이지네이션 구조 수정 (1일)
- [ ] `PaginatedResponse` 필드명 수정
- [ ] 메타데이터 중첩 구조 적용 (`meta.pagination`)
- [ ] BaseListController 업데이트
#### 1.3 소프트 딜리트 정리 (2일)
- [ ] `includeInactive` 파라미터 제거
- [ ] `is_active` 파라미터만 사용하도록 통일
- [ ] 모든 DataSource 쿼리 파라미터 정리
### Phase 2: Major Issues 해결 (2주일)
#### 2.1 JWT 구조 업데이트 (3일)
- [ ] AuthInterceptor 토큰 파싱 로직 수정
- [ ] `user_id` → `sub` 변경 적용
- [ ] 권한 체크 로직 업데이트
#### 2.2 Equipment 상태 확장 (1일)
- [ ] `EquipmentStatus` enum에 `disposed` 추가
- [ ] UI에서 폐기 상태 처리 로직 추가
- [ ] 상태별 아이콘 및 색상 추가
#### 2.3 권한 기반 UI 제어 (1주일)
- [ ] 사용자 권한별 UI 요소 표시/숨김
- [ ] API 호출 전 권한 사전 검증
- [ ] 권한 부족 시 안내 메시지
### Phase 3: Enhancement & New Features (1개월)
#### 3.1 Lookups API 구현 (1주일)
- [ ] `LookupRemoteDataSource` 기능 확장
- [ ] 전역 캐싱 시스템 구축
- [ ] 드롭다운 컴포넌트에 동적 로딩 적용
#### 3.2 Health Check 시스템 (3일)
- [ ] 서버 상태 모니터링 위젯 생성
- [ ] 주기적 헬스체크 백그라운드 작업
- [ ] 연결 상태 UI 인디케이터
#### 3.3 Overview API 완성 (1주일)
- [ ] 최근 활동 내역 구현
- [ ] 장비 상태 분포 차트 구현
- [ ] 실시간 업데이트 기능
### Phase 4: 코드 품질 개선 (진행 중)
#### 4.1 Service → Repository 마이그레이션 완료
- [ ] User 도메인 Repository 전환
- [ ] Equipment 도메인 Repository 전환
- [ ] Company 도메인 완전 전환
#### 4.2 테스트 커버리지 확대
- [ ] Domain Layer 단위 테스트 추가
- [ ] API 호환성 회귀 테스트 구축
- [ ] 에러 시나리오 테스트 강화
---
## 📊 호환성 점수
### 현재 호환성 평가
| 영역 | 호환성 점수 | 주요 문제 |
|------|------------|----------|
| **API 응답 형식** | 20% 🔴 | 기본 구조 완전 불일치 |
| **인증 시스템** | 80% 🟡 | JWT 구조 부분 변경 |
| **CRUD 작업** | 85% 🟡 | 소프트 딜리트 일부 누락 |
| **데이터 모델** | 90% 🟢 | 새 필드 일부 누락 |
| **페이지네이션** | 60% 🟡 | 메타데이터 구조 변경 |
| **에러 처리** | 70% 🟡 | 표준화 미흡 |
| **권한 제어** | 85% 🟡 | UI 레벨 권한 체크 부족 |
| **신규 API** | 30% 🔴 | 대부분 미구현 |
### 전체 호환성 점수: **65%** 🟡
---
## 🚨 즉시 조치 사항
### 🔥 Urgent (24시간 내)
1. **API 응답 파싱 에러** - 현재 대부분의 API 호출이 잘못된 응답 구조 사용
2. **페이지네이션 실패** - 목록 조회 시 메타데이터 파싱 오류 가능
### ⚡ High Priority (1주일 내)
3. **소프트 딜리트 불일치** - 삭제 기능의 일관성 문제
4. **JWT 토큰 변경** - 인증 실패 가능성
### 📅 Planned (1개월 내)
5. **신규 API 활용** - 성능 및 기능 개선 기회
6. **권한 시스템 강화** - 보안 개선
---
## 📞 지원 및 문의
### 긴급 이슈 발생 시
1. **Backend API Team**: API 스키마 관련 문의
2. **Frontend Team**: UI/UX 영향도 검토
3. **QA Team**: 호환성 테스트 지원
### 유용한 리소스
- [API_SCHEMA.md](./API_SCHEMA.md) - 완전한 API 명세서
- [CURRENT_STATE.md](./CURRENT_STATE.md) - 현재 프론트엔드 상태
- [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) - 상세 마이그레이션 가이드
---
**호환성 분석 버전**: 1.0
**최종 업데이트**: 2025-08-13
**담당자**: Frontend Architecture Team
> ⚠️ **중요**: 이 문서의 Critical Issues는 앱 안정성에 직접적인 영향을 미칩니다. 즉시 해결이 필요합니다.

202
docs/migration/LICENSE_TO_MAINTENANCE_USER_GUIDE.md Normal file
View File

@@ -0,0 +1,202 @@
# License → Maintenance 시스템 전환 가이드
## 📋 개요
Superport ERP 시스템이 **License 관리 시스템**에서 **Maintenance 관리 시스템**으로 전환됩니다.
이 문서는 시스템 변경사항과 새로운 사용 방법을 안내합니다.
---
## 🔄 주요 변경사항
### 이전 (License 시스템)
- **독립적인 License 관리**: Equipment와 별도로 라이선스 관리
- **만료일 기반 관리**: 라이선스 만료일만 추적
- **단순 비용 관리**: 라이선스 비용만 기록
- **개별 관리**: Equipment와 라이선스를 각각 관리
### 이후 (Maintenance 시스템)
- **통합 관리**: Equipment History 기반 유지보수 관리
- **주기적 관리**: 유지보수 주기와 다음 일정 자동 계산
- **포괄적 관리**: 유지보수 이력, 비용, 일정 통합 관리
- **자동화**: Equipment 입출고와 연동된 자동 추적
---
## 📊 화면별 변경사항
### 1. 메뉴 구조 변경
**이전:**
```
📁 라이선스 관리
├─ 라이선스 목록
├─ 라이선스 등록
└─ 만료 예정 라이선스
```
**이후:**
```
📁 유지보수 관리
├─ 유지보수 일정
├─ 유지보수 등록
├─ 알림 대시보드
└─ 유지보수 이력
```
### 2. 등록 화면 변경
#### License 등록 (이전)
- Equipment 선택
- 라이선스 종류 (온사이트/원격)
- 시작일/만료일
- 비용
- 업체 정보
#### Maintenance 등록 (이후)
- **Equipment History 선택** (입출고 이력 기반)
- 유지보수 유형 (온사이트/원격)
- **유지보수 주기** (개월 단위)
- 시작일 (종료일 자동 계산)
- **다음 유지보수 날짜** (자동 계산)
- 비용
- 상태 (예정/진행중/완료/연체)
### 3. 목록 화면 변경
#### License 목록 (이전)
| Equipment | 라이선스 종류 | 만료일 | 비용 | 상태 |
|-----------|-------------|--------|------|------|
| 서버 #001 | 온사이트 | 2024-12-31 | ₩1,000,000 | 활성 |
#### Maintenance 목록 (이후)
| Equipment | 입출고 정보 | 유지보수 유형 | 주기 | 다음 일정 | 상태 | 비용 |
|-----------|------------|--------------|------|----------|------|------|
| 서버 #001 | 2024-01-01 입고 | 온사이트 | 12개월 | 2024-11-30 | 예정 | ₩1,000,000 |
---
## 🎯 주요 기능 사용법
### 1. 유지보수 등록하기
1. **유지보수 관리** → **유지보수 등록** 메뉴 클릭
2. **Equipment History 선택**
- Equipment 선택 후 해당 입출고 이력 선택
- ⚠️ 주의: Equipment가 아닌 Equipment History를 선택해야 함
3. 유지보수 정보 입력
- 유형: 온사이트(O) 또는 원격(R)
- 주기: 개월 단위 (예: 12개월)
- 시작일 선택
4. **저장** 버튼 클릭
### 2. 유지보수 일정 확인하기
#### 캘린더 뷰
- 월별 유지보수 일정을 캘린더에서 확인
- 색상별 구분:
- 🔴 **빨강**: 연체된 유지보수
- 🟡 **노랑**: 30일 내 예정
- 🟢 **초록**: 예정된 유지보수
- ⚫ **회색**: 완료된 유지보수
#### 리스트 뷰
- 전체 유지보수 목록을 테이블로 확인
- 필터링: 상태, 기간, 유형별
- 정렬: 다음 일정, 비용, Equipment별
### 3. 알림 대시보드 활용하기
**우선순위별 알림:**
- **Critical (긴급)**: 7일 내 만료 또는 연체
- **High (높음)**: 14일 내 만료
- **Medium (중간)**: 30일 내 만료
- **Low (낮음)**: 30일 이후
**대시보드 위젯:**
- 이번 달 예정 유지보수
- 연체된 유지보수
- 총 유지보수 비용
- 완료율 통계
### 4. 유지보수 이력 조회하기
**보기 모드:**
1. **타임라인 뷰**: 시간순 이력 표시
2. **테이블 뷰**: 상세 정보 테이블
3. **분석 뷰**: 통계 및 차트
**필터 옵션:**
- 기간별 (월/분기/년)
- Equipment별
- 유형별 (온사이트/원격)
- 상태별 (완료/진행중)
---
## 💡 유용한 팁
### 자동 기능 활용
1. **자동 일정 계산**: 주기 입력 시 다음 유지보수 날짜 자동 계산
2. **자동 상태 업데이트**: 날짜 경과에 따른 상태 자동 변경
3. **자동 알림**: 만료 30일 전 자동 알림
### 효율적인 관리
1. **일괄 등록**: Excel 업로드로 여러 유지보수 일괄 등록
2. **템플릿 활용**: 자주 사용하는 유지보수 패턴 저장
3. **리포트 생성**: 월별/분기별 유지보수 리포트 자동 생성
---
## ⚠️ 주의사항
### 데이터 마이그레이션
- 기존 License 데이터는 자동으로 Maintenance로 변환됨
- 변환 규칙:
- 라이선스 만료일 → 유지보수 종료일
- 라이선스 종류 → 유지보수 유형
- 만료일 30일 전 → 다음 유지보수 일정
### 권한 변경
- License 관리 권한 → Maintenance 관리 권한으로 자동 이관
- 추가 권한 필요 시 관리자에게 문의
### 임시 조치
- 마이그레이션 후 7일간 이전 데이터 백업 유지
- 문제 발생 시 즉시 IT팀 연락
---
## 📞 지원 및 문의
### 기술 지원
- **내선**: 1234
- **이메일**: it-support@superport.com
- **지원 시간**: 평일 09:00-18:00
### 자주 묻는 질문 (FAQ)
**Q: 기존 라이선스 정보는 어떻게 확인하나요?**
A: 유지보수 이력에서 "마이그레이션됨" 태그가 있는 항목이 기존 라이선스입니다.
**Q: 유지보수 주기를 변경할 수 있나요?**
A: 네, 유지보수 편집에서 주기를 변경하면 다음 일정이 자동 재계산됩니다.
**Q: Equipment History가 없는 장비는 어떻게 하나요?**
A: Equipment 입고 처리를 먼저 진행한 후 유지보수를 등록하세요.
**Q: 여러 유지보수를 한 번에 등록할 수 있나요?**
A: Excel 템플릿을 다운로드하여 일괄 업로드가 가능합니다.
---
## 📝 변경 이력
| 버전 | 날짜 | 내용 |
|------|------|------|
| 1.0 | 2025-08-26 | 최초 작성 |
---
*이 문서는 Superport ERP 시스템 전환 가이드입니다.*
*최신 버전은 시스템 내 도움말 메뉴에서 확인하세요.*

543
docs/migration/MIGRATION_GUIDE.md
View File

@@ -1,543 +0,0 @@
# Superport API Migration Guide
> **최종 업데이트**: 2025-08-13
> **분석 대상**: `/Users/maximilian.j.sul/Documents/flutter/superport_api/`
> **프론트엔드 영향**: Flutter Clean Architecture 기반
## 📋 목차
- [주요 변경사항 요약](#주요-변경사항-요약)
- [Breaking Changes](#breaking-changes)
- [신규 기능](#신규-기능)
- [프론트엔드 마이그레이션](#프론트엔드-마이그레이션)
- [API 엔드포인트 변경사항](#api-엔드포인트-변경사항)
- [데이터베이스 스키마 변경](#데이터베이스-스키마-변경)
- [실행 계획](#실행-계획)
---
## 🚨 주요 변경사항 요약
### ✅ 완료된 주요 기능
1. **소프트 딜리트 시스템 전면 구현**
2. **권한 기반 접근 제어 강화**
3. **API 엔드포인트 표준화**
4. **페이지네이션 최적화**
5. **에러 처리 개선**
### 🔄 변경 영향도 매트릭스
| 영역 | 변경 수준 | 영향도 | 대응 필요도 |
|------|-----------|--------|-------------|
| **Authentication** | 중간 | 🟡 Medium | 토큰 구조 업데이트 |
| **Companies API** | 높음 | 🔴 High | DTO 모델 전면 수정 |
| **Equipment API** | 높음 | 🔴 High | 상태 관리 로직 수정 |
| **Users API** | 중간 | 🟡 Medium | 권한 처리 로직 수정 |
| **Licenses API** | 낮음 | 🟢 Low | 소프트 딜리트 대응 |
| **Overview API** | 신규 | 🔵 New | 새로운 통합 필요 |
---
## ⚠️ Breaking Changes
### 1. 소프트 딜리트 도입
**변경 내용**: 모든 주요 엔티티에서 물리 삭제 → 논리 삭제로 변경
**영향을 받는 API**:
```
DELETE /companies/{id} → is_active = false
DELETE /equipment/{id} → is_active = false
DELETE /licenses/{id} → is_active = false
DELETE /warehouse-locations/{id} → is_active = false
```
**프론트엔드 수정 필요사항**:
```dart
// Before (기존)
class CompanyListRequest {
final int? page;
final int? perPage;
}
// After (수정 필요)
class CompanyListRequest {
final int? page;
final int? perPage;
final bool? isActive; // 추가 필요
}
```
### 2. 응답 형식 표준화
**변경 내용**: 모든 API 응답이 표준 형식으로 통일
**Before**:
```json
{
"data": [...],
"total": 100
}
```
**After**:
```json
{
"status": "success",
"message": "Operation completed successfully",
"data": [...],
"meta": {
"pagination": {
"current_page": 1,
"per_page": 20,
"total": 100,
"total_pages": 5
}
}
}
```
### 3. 권한 시스템 변경
**변경 내용**: JWT 클레임 구조 및 권한 체크 로직 강화
**새로운 JWT 구조**:
```json
{
"sub": 1, // user_id
"username": "admin",
"role": "admin", // admin|manager|staff
"exp": 1700000000,
"iat": 1699999000
}
```
**권한별 접근 제한**:
- `staff`: 조회 권한만, 삭제 권한 없음
- `manager`: 모든 권한, 단 사용자 관리 제외
- `admin`: 모든 권한
---
## 🆕 신규 기능
### 1. Overview API (대시보드용)
**새로운 엔드포인트**:
```
GET /overview/stats # 대시보드 통계
GET /overview/recent-activities # 최근 활동
GET /overview/equipment-status # 장비 상태 분포
GET /overview/license-expiry # 라이선스 만료 요약
```
**통합 예시**:
```dart
// 새로 추가할 UseCase
class GetDashboardStatsUseCase {
Future<Either<Failure, DashboardStats>> call(int? companyId) async {
return await overviewRepository.getDashboardStats(companyId);
}
}
```
### 2. Lookups API (마스터 데이터)
**새로운 엔드포인트**:
```
GET /lookups # 전체 마스터 데이터
GET /lookups/type # 타입별 마스터 데이터
```
**활용 방안**:
- 드롭다운 옵션 동적 로딩
- 캐싱을 통한 성능 최적화
### 3. Health Check API
**새로운 엔드포인트**:
```
GET /health # 서버 상태 체크
```
**프론트엔드 활용**:
- 앱 시작 시 서버 연결 상태 확인
- 주기적 헬스체크 구현
---
## 🎯 프론트엔드 마이그레이션
### Phase 1: DTO 모델 업데이트
#### 1.1 Company DTO 수정
```dart
// 기존 CreateCompanyRequest에 추가
@JsonSerializable()
class CreateCompanyRequest {
// 기존 필드들...
final List<String>? companyTypes; // 추가
final bool? isPartner; // 추가
final bool? isCustomer; // 추가
}
// 새로운 필터링 옵션
@JsonSerializable()
class CompanyListRequest {
final int? page;
final int? perPage;
final bool? isActive; // 추가 (소프트 딜리트)
}
```
#### 1.2 Equipment DTO 수정
```dart
// Equipment 상태 Enum 확장
enum EquipmentStatus {
@JsonValue('available') available,
@JsonValue('inuse') inuse,
@JsonValue('maintenance') maintenance,
@JsonValue('disposed') disposed, // 새로 추가
}
// 페이지네이션 쿼리 확장
@JsonSerializable()
class EquipmentListRequest {
final int? page;
final int? perPage;
final String? status;
final int? companyId;
final int? warehouseLocationId;
final bool? isActive; // 추가
}
```
### Phase 2: Repository 인터페이스 수정
#### 2.1 소프트 딜리트 지원
```dart
abstract class CompanyRepository {
// 기존 메서드 시그니처 수정
Future<Either<Failure, PaginatedResponse<Company>>> getCompanies({
int? page,
int? perPage,
bool? isActive, // 추가
});
// 삭제 메서드 동작 변경 (소프트 딜리트)
Future<Either<Failure, Unit>> deleteCompany(int id);
// 복구 메서드 추가
Future<Either<Failure, Company>> restoreCompany(int id); // 신규
}
```
#### 2.2 새로운 Repository 추가
```dart
// 새로 추가할 Repository
abstract class OverviewRepository {
Future<Either<Failure, DashboardStats>> getDashboardStats(int? companyId);
Future<Either<Failure, PaginatedResponse<Activity>>> getRecentActivities({
int? page,
int? perPage,
String? entityType,
int? companyId,
});
Future<Either<Failure, EquipmentStatusDistribution>> getEquipmentStatusDistribution(int? companyId);
Future<Either<Failure, LicenseExpirySummary>> getLicenseExpirySummary(int? companyId);
}
abstract class LookupRepository {
Future<Either<Failure, Map<String, List<LookupItem>>>> getAllLookups();
Future<Either<Failure, List<LookupItem>>> getLookupsByType(String type);
}
```
### Phase 3: API 클라이언트 수정
#### 3.1 Retrofit 인터페이스 업데이트
```dart
@RestApi()
abstract class SuperportApiClient {
// Overview API 추가
@GET('/overview/stats')
Future<ApiResponse<DashboardStats>> getDashboardStats(
@Query('company_id') int? companyId,
);
@GET('/overview/license-expiry')
Future<ApiResponse<LicenseExpirySummary>> getLicenseExpirySummary(
@Query('company_id') int? companyId,
);
// Lookups API 추가
@GET('/lookups')
Future<ApiResponse<Map<String, List<LookupItem>>>> getAllLookups();
// 기존 API 파라미터 추가
@GET('/companies')
Future<ApiResponse<PaginatedResponse<Company>>> getCompanies(
@Query('page') int? page,
@Query('per_page') int? perPage,
@Query('is_active') bool? isActive, // 추가
);
}
```
#### 3.2 응답 형식 변경 대응
```dart
// 기존 ApiResponse 클래스 수정
@JsonSerializable()
class ApiResponse<T> {
final String status; // 추가
final String? message; // 추가
final T data;
final ResponseMeta? meta; // 변경 (기존 meta와 구조 다름)
}
@JsonSerializable()
class ResponseMeta {
final PaginationMeta? pagination; // 중첩 구조로 변경
}
```
### Phase 4: 상태 관리 업데이트
#### 4.1 Controller 수정
```dart
class CompanyController extends ChangeNotifier {
// 소프트 딜리트 상태 관리
bool _showDeleted = false;
bool get showDeleted => _showDeleted;
void toggleShowDeleted() {
_showDeleted = !_showDeleted;
_loadCompanies(); // 목록 다시 로드
notifyListeners();
}
// 복구 기능 추가
Future<void> restoreCompany(int id) async {
final result = await _restoreCompanyUseCase(id);
result.fold(
(failure) => _handleError(failure),
(company) {
_companies[id] = company;
notifyListeners();
},
);
}
}
```
#### 4.2 새로운 Controller 추가
```dart
class DashboardController extends ChangeNotifier {
DashboardStats? _stats;
List<Activity> _recentActivities = [];
bool _isLoading = false;
// Getters...
Future<void> loadDashboardData() async {
_isLoading = true;
notifyListeners();
// 병렬로 데이터 로드
await Future.wait([
_loadStats(),
_loadRecentActivities(),
]);
_isLoading = false;
notifyListeners();
}
}
```
---
## 📡 API 엔드포인트 변경사항
### 새로 추가된 엔드포인트
| Method | Endpoint | 설명 | 우선순위 |
|--------|----------|------|----------|
| `GET` | `/overview/stats` | 대시보드 통계 | 🔴 높음 |
| `GET` | `/overview/license-expiry` | 라이선스 만료 요약 | 🟡 중간 |
| `GET` | `/overview/equipment-status` | 장비 상태 분포 | 🟡 중간 |
| `GET` | `/overview/recent-activities` | 최근 활동 내역 | 🟢 낮음 |
| `GET` | `/lookups` | 전체 마스터 데이터 | 🟡 중간 |
| `GET` | `/lookups/type` | 타입별 마스터 데이터 | 🟢 낮음 |
| `GET` | `/health` | 서버 상태 체크 | 🟢 낮음 |
### 기존 엔드포인트 변경사항
| Endpoint | 변경 내용 | 마이그레이션 필요도 |
|----------|-----------|---------------------|
| `GET /companies` | `is_active` 파라미터 추가 | 🔴 필수 |
| `GET /equipment` | `is_active` 파라미터 추가 | 🔴 필수 |
| `DELETE /companies/{id}` | 소프트 딜리트로 변경 | 🔴 필수 |
| `DELETE /equipment/{id}` | 권한 체크 강화 | 🟡 권장 |
| 모든 응답 | 표준 형식으로 통일 | 🔴 필수 |
---
## 🗄️ 데이터베이스 스키마 변경
### 새로 추가된 컬럼
| 테이블 | 컬럼 | 타입 | 설명 |
|--------|------|------|------|
| `companies` | `is_active` | `BOOLEAN` | 소프트 딜리트 플래그 |
| `companies` | `is_partner` | `BOOLEAN` | 파트너사 여부 |
| `companies` | `is_customer` | `BOOLEAN` | 고객사 여부 |
| `companies` | `company_types` | `TEXT[]` | 회사 유형 배열 |
| `equipment` | `is_active` | `BOOLEAN` | 소프트 딜리트 플래그 |
| `licenses` | `is_active` | `BOOLEAN` | 소프트 딜리트 플래그 |
| `warehouse_locations` | `is_active` | `BOOLEAN` | 소프트 딜리트 플래그 |
| `addresses` | `is_active` | `BOOLEAN` | 소프트 딜리트 플래그 |
| `users` | `is_active` | `BOOLEAN` | 소프트 딜리트 플래그 |
### 새로 추가된 인덱스
```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_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);
```
---
## 🛠️ 실행 계획
### Phase 1: 백엔드 API 통합 (1주차)
- [ ] Overview API 통합 (`/overview/license-expiry` 우선)
- [ ] 소프트 딜리트 대응 (필터링 로직)
- [ ] 응답 형식 변경 대응
### Phase 2: 프론트엔드 모델 업데이트 (2주차)
- [ ] DTO 클래스 수정 (Freezed 재생성)
- [ ] Repository 인터페이스 확장
- [ ] API 클라이언트 업데이트
### Phase 3: UI/UX 개선 (3주차)
- [ ] 소프트 딜리트 UI 구현 (복구 버튼, 필터링)
- [ ] 대시보드 통계 위젯 구현
- [ ] 권한별 UI 제어 강화
### Phase 4: 성능 최적화 (4주차)
- [ ] Lookups API 캐싱 구현
- [ ] 페이지네이션 최적화
- [ ] 에러 처리 개선
### Phase 5: 테스트 및 배포 (5주차)
- [ ] 단위 테스트 업데이트
- [ ] 통합 테스트 실행
- [ ] 프로덕션 배포
---
## 🧪 테스트 업데이트 가이드
### 1. 단위 테스트 수정
```dart
// Repository 테스트 수정 예시
group('CompanyRepository', () {
test('should return active companies when isActive is true', () async {
// Given
when(mockApiClient.getCompanies(
page: 1,
perPage: 20,
isActive: true, // 추가된 파라미터 테스트
)).thenAnswer((_) async => mockActiveCompaniesResponse);
// When
final result = await repository.getCompanies(
page: 1,
perPage: 20,
isActive: true,
);
// Then
expect(result.isRight(), true);
});
});
```
### 2. Widget 테스트 수정
```dart
testWidgets('should show restore button for deleted companies', (tester) async {
// Given
final deletedCompany = Company(id: 1, name: 'Test', isActive: false);
// When
await tester.pumpWidget(CompanyListItem(company: deletedCompany));
// Then
expect(find.text('복구'), findsOneWidget);
expect(find.byIcon(Icons.restore), findsOneWidget);
});
```
### 3. 통합 테스트 수정
```dart
group('Company CRUD Integration', () {
test('soft delete should set is_active to false', () async {
// Create company
final company = await createTestCompany();
// Delete (soft delete)
await apiClient.deleteCompany(company.id);
// Verify soft delete
final companies = await apiClient.getCompanies(isActive: false);
expect(companies.data.any((c) => c.id == company.id), true);
});
});
```
---
## 🚨 주의사항
### 1. 데이터 마이그레이션
- 기존 삭제된 데이터는 복구 불가능
- 소프트 딜리트 전환 후에만 복구 가능
### 2. 성능 영향
- `is_active` 필터링으로 인한 쿼리 복잡도 증가
- 인덱스 활용으로 성능 최적화 필요
### 3. 권한 관리
- 새로운 권한 체크 로직 확인 필요
- Staff 권한 사용자의 기능 제한 확인
### 4. 캐싱 전략
- Lookups API 응답 캐싱 구현 권장
- 대시보드 통계 캐싱으로 성능 개선
---
## 📞 지원 및 문의
### 개발팀 연락처
- **백엔드 API**: `superport_api` 레포지토리 이슈 생성
- **프론트엔드**: 현재 레포지토리 이슈 생성
- **데이터베이스**: DBA 팀 문의
### 유용한 리소스
- [API_SCHEMA.md](./API_SCHEMA.md) - 완전한 API 명세서
- [ENTITY_MAPPING.md](./ENTITY_MAPPING.md) - 데이터베이스 구조
- 백엔드 소스: `/Users/maximilian.j.sul/Documents/flutter/superport_api/`
---
**마이그레이션 가이드 버전**: 1.0
**최종 검토**: 2025-08-13
**담당자**: Full-Stack Development Team