BE-08-airquality-query-api

[BE-08] 대기질 조회 API — UseCase + Controller + Response

작업 내용 (설계 의도)

변경 사항

좌표 기준 대기질을 조회하는 읽기 전용 엔드포인트를 신설한다. 모바일 시설 상세·예약 화면(FR-12/13)이 예약 전 호출하며, 경고/확인은 FE UX 게이트로 처리한다. 예약 UseCase와 무결합 — graceful degrade 보장. BE-03 계약에만 의존해 BE-05(Gateway 구현)와 병렬. 근거 TDD: ../TDD.md “방안 비교 대기질 예약 경계”·FR-12~14.

• application/airquality/usecase/GetAirQualityUseCase.kt — execute(lat,lng): AirQuality. AirQualityDomainService만 호출(10줄 이내), @Transactional 불필요(외부 조회).
• application/airquality/dto/AirQualityResponse.kt — pm10/pm25/pm10Grade/pm25Grade/representativeGrade/stationName/measuredAt + of(airQuality). empty는 값 null·등급 UNKNOWN으로 그대로 노출(“정보없음”).
• presentation/airquality/controller/AirQualityApiController.kt — GET /air-quality?lat&lng → 200 AirQualityResponse. 실패도 200(빈 값). 좌표 누락·비수치는 400.

의존

• BE-03

다이어그램

처리 흐름

sequenceDiagram
    participant M as Mobile
    participant C as AirQualityApiController
    participant U as GetAirQualityUseCase
    participant S as AirQualityDomainService
    M->>C: GET /air-quality?lat&lng
    C->>U: execute(lat,lng)
    U->>S: current(lat,lng)
    S-->>U: AirQuality
    U-->>C: AirQuality
    C-->>M: 200 AirQualityResponse

클래스 의존

flowchart LR
    Ctl[AirQualityApiController] --> UC[GetAirQualityUseCase]
    UC --> Svc[AirQualityDomainService]
    Ctl --> Resp[AirQualityResponse]

테스트 케이스

• 정상 측정값이면 200과 pm10/pm25·대표 등급을 반환한다
• Gateway degrade(empty)면 200과 정보없음(값 null·UNKNOWN)을 반환한다(예약 진행 가능)
• lat 또는 lng 누락 시 400을 반환한다
• 비수치 좌표 파라미터는 400을 반환한다