superport/docs/migration/API_SCHEMA.md

# 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