leak_test/ob/03_API_Specification.md

# [3단계] 핵심 API 명세서 설계 (API Specification)

본 문서는 누수 시험 시스템(WPF Client)과 중앙 통합 관리 서버(MES/모니터링 Web API) 간의 통신 규격을 정의하는 RESTful API 명세서입니다.

---

## 1. 인증 API (Authentication)

### 1.1 사용자 로그인 (Sign In)
* **Method & URL**: `POST /api/v1/auth/login`
* **설명**: 작업자 ID와 비밀번호를 검증하고 세션 토큰(JWT)을 발급받습니다.

#### 요청 예시 (Request Body)
```json
{
  "operatorId": "test",
  "password": "testPassword123"
}
```

#### 성공 응답 예시 (Response 200 OK)
```json
{
  "success": true,
  "message": "로그인에 성공했습니다.",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userInfo": {
    "operatorId": "test",
    "operatorName": "홍길동",
    "role": "OPERATOR"
  }
}
```

#### 실패 응답 예시 (Response 401 Unauthorized - 계정 정보 불일치)
```json
{
  "success": false,
  "errorCode": "AUTH_FAILED",
  "message": "등록되지 않은 ID이거나 비밀번호가 일치하지 않습니다."
}
```

---

## 2. 계측 데이터 동기화 API (Inspection Data Sync)

### 2.1 검사 데이터 UPSERT 전송 (Upload Inspection Data)
* **Method & URL**: `POST /api/v1/eol/inspect`
* **Headers**: `Authorization: Bearer <Token>`
* **설명**: 장비 검사가 완료된 시점에 실시간 누수 측정 값을 서버로 전송합니다. 시리얼 번호가 이미 존재할 경우 업데이트됩니다.

#### 요청 예시 (Request Body)
```json
{
  "icSn": "202606240001LM01",
  "pcbBarcode": "202606240001LM01",
  "maker": "MOBI",
  "model": "NE1aW_PT",
  "variant1": "V1_STD",
  "variant2": "V2_REV1",
  "operator": "test",
  "line": "LINE_01",
  "lotNo": "LOT_20260624A",
  "jigNo": "JIG_A",
  "channel": "LEFT",
  "specUL": 1.0000,
  "specLL": -1.0000,
  "leakValue": 0.4357,
  "result": "OK"
}
```

#### 성공 응답 예시 (Response 201 Created / 200 OK)
```json
{
  "success": true,
  "message": "검사 데이터가 정상적으로 저장되었습니다.",
  "data": {
    "icSn": "202606240001LM01",
    "recordedAt": "2026-06-24T10:15:30.123Z"
  }
}
```

#### 실패 응답 예시 (Response 400 Bad Request - 유효하지 않은 데이터 형식)
```json
{
  "success": false,
  "errorCode": "INVALID_PARAMETERS",
  "message": "측정 누설값(leakValue)은 필수 수치 정보입니다."
}
```

---

## 3. 검사 이력 조회 API (Inspection Data Query)

### 3.1 조건별 검사 기록 목록 조회 (Retrieve History)
* **Method & URL**: `GET /api/v1/eol/inspects`
* **Headers**: `Authorization: Bearer <Token>`
* **Query Parameters**:
  * `startDate`: 조회 시작일 (Format: `YYYY-MM-DD`)
  * `endDate`: 조회 종료일 (Format: `YYYY-MM-DD`)
  * `result`: 판정 필터 (`OK`, `NG`, 생략 시 전체)
  * `lotNo`: 로트 번호 필터 (일부분 검색 가능)
  * `operator`: 작업자 ID 필터

#### 성공 응답 예시 (Response 200 OK)
```json
{
  "success": true,
  "totalCount": 2,
  "results": [
    {
      "icSn": "202606240001LM01",
      "pcbBarcode": "202606240001LM01",
      "maker": "MOBI",
      "model": "NE1aW_PT",
      "variant1": "V1_STD",
      "variant2": "V2_REV1",
      "operator": "test",
      "productionDate": "2026-06-24T10:15:30Z",
      "line": "LINE_01",
      "lotNo": "LOT_20260624A",
      "jigNo": "JIG_A",
      "channel": "LEFT",
      "specUL": 1.0000,
      "specLL": -1.0000,
      "leakValue": 0.4357,
      "result": "OK"
    },
    {
      "icSn": "202606240002LM02",
      "pcbBarcode": "202606240002LM02",
      "maker": "MOBI",
      "model": "NE1aW_PT",
      "variant1": "V1_STD",
      "variant2": "V2_REV1",
      "operator": "test",
      "productionDate": "2026-06-24T10:16:15Z",
      "line": "LINE_01",
      "lotNo": "LOT_20260624A",
      "jigNo": "JIG_A",
      "channel": "RIGHT",
      "specUL": 1.0000,
      "specLL": -1.0000,
      "leakValue": 1.2541,
      "result": "NG"
    }
  ]
}
```

---

## 4. HTTP 상태 코드 정의 가이드 (Status Codes Definition)

본 연동 API 규격은 직관적이고 표준적인 HTTP Response 상태 코드를 따릅니다.

| 상태 코드 | 의미 | 사용 시점 |
| :--- | :--- | :--- |
| **200 OK** | 성공 | 조회(GET) 성공 및 정상 데이터 업데이트(UPSERT) 성공 시 |
| **201 Created** | 생성 성공 | 신규 검사 데이터 삽입(INSERT)이 데이터베이스에 성공 시 |
| **400 Bad Request** | 잘못된 요청 | 파라미터 누락, 데이터 타입 에러 등 요청 양식이 규칙에 맞지 않을 때 |
| **401 Unauthorized**| 권한 없음 | 로그인 토큰(Bearer Token)이 만료되었거나 누락되어 인증이 안 된 경우 |
| **403 Forbidden** | 접근 거부 | 일반 작업자 권한으로 관리자 API에 직접 접근을 시도할 때 |
| **404 Not Found** | 리소스 없음 | 요청한 엔드포인트 URL 또는 조회 대상 제품 ID를 찾을 수 없을 때 |
| **500 Internal Server Error** | 서버 오류 | 서버 DB 연결 이상, 데이터베이스 데드락, 런타임 처리 오류 발생 시 |