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)

{
  "operatorId": "test",
  "password": "testPassword123"
}

성공 응답 예시 (Response 200 OK)

{
  "success": true,
  "message": "로그인에 성공했습니다.",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userInfo": {
    "operatorId": "test",
    "operatorName": "홍길동",
    "role": "OPERATOR"
  }
}

실패 응답 예시 (Response 401 Unauthorized - 계정 정보 불일치)

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

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

{
  "success": true,
  "message": "검사 데이터가 정상적으로 저장되었습니다.",
  "data": {
    "icSn": "202606240001LM01",
    "recordedAt": "2026-06-24T10:15:30.123Z"
  }
}

실패 응답 예시 (Response 400 Bad Request - 유효하지 않은 데이터 형식)

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

{
  "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 연결 이상, 데이터베이스 데드락, 런타임 처리 오류 발생 시