dpdpdndn 블로그

BE-02-region-seed-and-resolver

NEW3 min read

[BE-02] Region 마스터 seed(MySQL) + RegionResolveGateway 구현

작업 내용 (설계 의도)

변경 사항

행정표준코드 Region 마스터를 MySQL에 정적 seed하고, 주소→표준코드 해석 구현체를 작성한다. BE-01의 계약을 구현한다. 근거 TDD: ../TDD.md FR-1·“방안 비교 지역 정규화”.

  • Flyway V38__create_and_seed_regions.sql(다음 순번) — regions(id PK, sido_code VARCHAR(2), sido_name, sigungu_code VARCHAR(5), sigungu_name, created_at DATETIME(6)). FK·ENUM·JSON·BOOLEAN 금지, 전 컬럼 COMMENT, sigunguCode UNIQUE 인덱스(ALGORITHM=INPLACE, LOCK=NONE). 17개 시도 + 시군구 seed(멱등 INSERT). DDL·seed 데이터 상세는 senior-dba design-db 확정 후 private-mysql-implementer 작성.
  • infrastructure/facility/region/RegionJpaEntity.kt + RegionJpaRepository.kt(파생 쿼리) — @Query 금지, 복잡 조회는 CustomImpl.
  • infrastructure/facility/region/RegionResolveGatewayImpl.kt — 주소 문자열에서 시도명·시군구명 토큰 추출(정규화: “부산”↔“부산광역시”) → regions 조회 → FacilityRegion. sidoHint가 있으면 우선. 미매핑·빈 주소 → FacilityRegion.UNSPECIFIED(예외 금지, 경고 로그). regions 미적재 시 전건 UNSPECIFIED.

롤백

  • 마이그레이션 실패 시 역방향 DDL DROP TABLE regions(참조가 코드값이라 안전, 파일 상단 주석에 명시).

의존

  • BE-01

다이어그램

처리 흐름

sequenceDiagram
    participant S as FacilityDomainService
    participant G as RegionResolveGatewayImpl
    participant R as RegionJpaRepository
    S->>G: resolve(address, sidoHint)
    G->>G: 시도·시군구명 토큰 추출·정규화
    G->>R: findBySigunguName / findBySidoName
    alt 매핑 성공
        R-->>G: RegionJpaEntity
        G-->>S: FacilityRegion(코드·명칭)
    else 미매핑
        G-->>S: FacilityRegion.UNSPECIFIED
    end

클래스 의존

flowchart LR
    Impl[RegionResolveGatewayImpl] --> Repo[RegionJpaRepository]
    Impl -.->|impl| Gw[RegionResolveGateway]
    Impl --> VO[FacilityRegion]

테스트 케이스

  • “부산광역시 해운대구 …” 주소는 부산 시도코드·해운대구 시군구코드로 해석된다
  • “부산 해운대구”처럼 약식 시도명도 정규화되어 해석된다
  • 매핑 불가한 주소는 FacilityRegion.UNSPECIFIED를 반환한다(예외 없음)
  • 빈 주소는 UNSPECIFIED를 반환한다
  • sidoHint가 주어지면 주소 파싱보다 우선 적용된다
  • regions 미적재 상태에서 resolve는 UNSPECIFIED를 반환한다

그래프 뷰