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 엔드포인트 목록
• Request/Response 형식
• 페이지네이션
• 에러 처리
• 상태 코드

---

🔐 인증 시스템

JWT Token 기반 인증

• 토큰 타입: Bearer Token
• 만료 시간: 24시간
• 권한 레벨: Admin, Manager, Staff

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 형식

표준 응답 형식

{
  "status": "success",
  "message": "Operation completed successfully",
  "data": { /* 실제 데이터 */ },
  "meta": { /* 메타데이터 (페이지네이션 등) */ }
}

주요 DTO 구조

🏢 Company DTO

CreateCompanyRequest:

{
  "name": "회사명 (필수)",
  "address": "주소 (선택)",
  "contact_name": "담당자명 (선택)",
  "contact_position": "담당자 직책 (선택)",
  "contact_phone": "연락처 (선택)",
  "contact_email": "이메일 (선택)",
  "company_types": ["타입1", "타입2"],
  "remark": "비고 (선택)",
  "is_partner": false,
  "is_customer": true
}

CompanyResponse:

{
  "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:

{
  "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:

{
  "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:

{
  "username": "admin",
  "password": "password123"
}

LoginResponse:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "user": {
    "id": 1,
    "username": "admin",
    "name": "관리자",
    "email": "admin@superport.kr",
    "role": "admin"
  }
}

---

📄 페이지네이션

요청 파라미터

GET /api/v1/companies?page=1&per_page=20&is_active=true

응답 형식

{
  "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 미지정: 모든 데이터

---

⚠️ 에러 처리

에러 응답 형식

{
  "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