dpdpdndn 블로그

BE-06-facility-region-query-api

NEW3 min read

[BE-06] 시설 조회·통계 전국 확장 — Criteria·DomainService·API·MCP

작업 내용 (설계 의도)

변경 사항

시설 조회·통계·MCP를 시/도·시군구 표준코드 기준으로 확장한다. 기존 gu 파라미터·응답·통계는 완전 하위호환 유지. FacilityDomainService(CSV 적재 포함)를 단독 소유해 BE-07(owner/import 쓰기 경로)과 파일 충돌을 피한다. 근거 TDD: ../TDD.md FR-4.

  • application/facility/dto/FacilityCriteria.kt — sidoCode·sigunguCode 추가(gu·type 유지), effectiveSidoCode()/effectiveSigunguCode(), toPageable 유지.
  • domain/facility/service/FacilityDomainService.kt — RegionResolveGateway 주입. list(...)가 region 필터 지원(신규 findAll 위임), aggregateRegionType() 위임 추가. register·bulkImport는 attributes.address(또는 CSV sido)로 region 해석 후 저장(미해석 UNSPECIFIED). 기존 gu 메서드 유지.
  • application/facility/usecase/ListFacilitiesUseCase.kt — criteria region 전달(변경 최소). GetRegionTypeStatsUseCase.kt(신규) — aggregateRegionType 위임. GetGuTypeStatsUseCase 유지.
  • presentation/facility/dto/response/FacilityResponse.kt — sidoCode/sidoName/sigunguCode/sigunguName 추가(gu 유지). RegionTypeCountResponse.kt(신규). GuTypeCountResponse 유지.
  • presentation/facility/controller/FacilityApiController.kt — listFacilities에 sidoCode·sigunguCode optional 파라미터 추가, GET /stats/region-type 추가. ?gu=·/stats/gu-type 유지.
  • presentation/mcp/controller/McpFacilityTools.kt — getFacilities에 sido/sigungu 파라미터 추가(설명 갱신). McpFacilityStatsTools.kt — region-type 통계 tool 추가 또는 기존 확장. scope 무변경.

롤백

  • 신규 파라미터·엔드포인트는 추가만 — 미사용 시 기존 gu 경로로 자동 하위호환. 코드 롤백만으로 안전.

의존

  • BE-04, BE-02

다이어그램

처리 흐름

sequenceDiagram
    participant C as FacilityApiController
    participant U as ListFacilitiesUseCase
    participant S as FacilityDomainService
    participant R as FacilityRepository
    C->>U: execute(criteria[sidoCode])
    U->>S: list(sidoCode,sigunguCode,gu,type)
    S->>R: findAll(...)
    R-->>S: Page<Facility>
    S-->>U: Page
    U-->>C: Page<FacilityResponse>

클래스 의존

flowchart LR
    Ctl[FacilityApiController] --> UC[ListFacilitiesUseCase]
    Mcp[McpFacilityTools] --> UC
    UC --> Svc[FacilityDomainService]
    Svc --> Repo[FacilityRepository]
    Svc --> Reg[RegionResolveGateway]

테스트 케이스

  • sidoCode=부산 필터 시 부산 시설만 반환되고 서울 중구·부산 중구가 구분된다
  • 기존 gu 파라미터만 준 요청은 종전과 동일 결과를 반환한다(하위호환)
  • /stats/region-type은 시도·시군구·유형별 count를 반환한다
  • /stats/gu-type은 기존과 동일하게 동작한다
  • MCP getFacilities에 sido 파라미터를 주면 해당 시/도 시설만 조회된다
  • region 없는 legacy 문서는 응답에서 미지정으로 노출된다

그래프 뷰