# 백엔드 API 구현 요청 사항

## 1. 시리얼 번호 중복 체크 API

### 요청 사항
장비 입고 시 시리얼 번호 중복을 방지하기 위한 API가 필요합니다.

### API 스펙

#### Endpoint
```
POST /api/v1/equipment/check-serial
```

#### Request Body
```json
{
  "serialNumber": "SN123456789"
}
```

#### Response

**성공 (200 OK) - 사용 가능한 시리얼 번호**
```json
{
  "available": true,
  "message": "사용 가능한 시리얼 번호입니다."
}
```

**성공 (200 OK) - 중복된 시리얼 번호**
```json
{
  "available": false,
  "message": "이미 등록된 시리얼 번호입니다.",
  "existingEquipment": {
    "id": 123,
    "name": "장비명",
    "companyName": "회사명",
    "warehouseLocation": "창고 위치"
  }
}
```

**실패 (400 Bad Request) - 잘못된 요청**
```json
{
  "error": "시리얼 번호를 입력해주세요."
}
```

### 구현 요구사항

1. **중복 체크 로직**
   - equipment 테이블의 serial_number 컬럼에서 중복 확인
   - 대소문자 구분 없이 체크 (case-insensitive)
   - 공백 제거 후 비교 (trim)

2. **성능 고려사항**
   - serial_number 컬럼에 인덱스 필요
   - 빠른 응답을 위한 최적화

3. **보안 고려사항**
   - SQL Injection 방지
   - Rate limiting 적용 (분당 60회 제한)

### 프론트엔드 통합 코드

```dart
// services/equipment_service.dart
Future<bool> checkSerialNumberAvailability(String serialNumber) async {
  final response = await dio.post(
    '/equipment/check-serial',
    data: {'serialNumber': serialNumber},
  );
  
  if (response.statusCode == 200) {
    return response.data['available'] ?? false;
  }
  throw Exception('시리얼 번호 확인 실패');
}

// controllers/equipment_form_controller.dart
Future<String?> validateSerialNumber(String? value) async {
  if (value == null || value.isEmpty) {
    return '시리얼 번호를 입력해주세요.';
  }
  
  // 실시간 중복 체크
  final isAvailable = await _equipmentService.checkSerialNumberAvailability(value);
  if (!isAvailable) {
    return '이미 등록된 시리얼 번호입니다.';
  }
  
  return null;
}
```

## 2. 벌크 시리얼 번호 체크 API (추가 제안)

### 요청 사항
여러 장비를 한 번에 등록할 때 시리얼 번호들을 일괄 체크하는 API

### API 스펙

#### Endpoint
```
POST /api/v1/equipment/check-serial-bulk
```

#### Request Body
```json
{
  "serialNumbers": ["SN001", "SN002", "SN003"]
}
```

#### Response
```json
{
  "results": [
    {
      "serialNumber": "SN001",
      "available": true
    },
    {
      "serialNumber": "SN002",
      "available": false,
      "existingEquipmentId": 456
    },
    {
      "serialNumber": "SN003",
      "available": true
    }
  ],
  "summary": {
    "total": 3,
    "available": 2,
    "duplicates": 1
  }
}
```

## 3. 시리얼 번호 유니크 제약 조건

### 데이터베이스 스키마 변경 요청

```sql
-- equipment 테이블에 유니크 제약 조건 추가
ALTER TABLE equipment 
ADD CONSTRAINT unique_serial_number 
UNIQUE (serial_number);

-- 성능을 위한 인덱스 추가 (이미 유니크 제약에 포함되지만 명시적으로)
CREATE INDEX idx_equipment_serial_number 
ON equipment(LOWER(TRIM(serial_number)));
```

## 구현 우선순위

1. **Phase 1 (즉시)**: 단일 시리얼 번호 체크 API
2. **Phase 2 (선택)**: 벌크 시리얼 번호 체크 API
3. **Phase 3 (필수)**: DB 유니크 제약 조건

## 예상 일정

- API 구현: 2-3시간
- 테스트: 1시간
- 배포: 30분

---

작성일: 2025-01-09
작성자: Frontend Team
상태: 백엔드 팀 검토 대기중