feat(region): 지역 마스터(1·2차 시군구) 모델 + 조회/검색 API + 수도권 시드

[chanwoo7]

Summary

인기 매장 리스트 · 픽업 필터(figma 명세) 백엔드 작업의 PR1 / 지역(Region) 기반입니다. 지역 선택 바텀시트(화면 02·03·04)를 받치는 지역 마스터 데이터 + 조회/검색 API를 신설했습니다.

기존 Store는 address_city/district/neighborhood free-text만 보유해 지역 필터가 불가능했습니다. 1·2차 계층 지역 마스터를 신설하고, 매장을 표준 시군구에 매핑할 기반을 마련했습니다.

Scope

• Prisma: Region 모델 신설(self-FK 계층 — level 1 광역그룹 / level 2 시군구) + Store.region_id FK + 마이그레이션
• 시드: 공공데이터포털 "국토교통부_전국 법정동"(이용허락 제한 없음) 기반 수도권 Region 생성기·JSON·seed
  • 1차 6개(전국 / 서울 북부·남부 / 경기 북부·남부 / 인천), 2차 82개 시군구(서울 25 · 인천 10 · 경기 47)
  • 1차 배정 규칙: 서울 = 한강 북/남, 경기 = 경기북부청 관할 기준, 인천 = 단일
  • 2차 추출 규칙: "동(洞)을 직접 보유한 표준 시군구"(경기 일반시는 구 단위 — 수원시영통구 등)
  • 원본 CSV는 gitignore, 파싱 산출 JSON만 커밋(재현성 + 환각 0)
• region feature: regionGroups / regions(parentId) / searchRegions(input) — 비로그인 public query
• 테스트: service 통합 · resolver 통합 · DTO 검증 23개

진행 상황

전체 4개 PR 중 1번째:

• ✅ PR1 지역 마스터 + 조회/검색 (이 PR)
• ⬜ PR2 인기 매장 리스트 + 랭킹 배치(지역 필터 연동)
• ⬜ PR3 매장 찜 토글
• ⬜ PR4 홈 전역 픽업 날짜/시간 슬롯

Impact

• DB: region 테이블 신설. store.region_id nullable 추가(기존 매장 무영향). FK ON DELETE SET NULL.
• API: public query 3종 신규. 기존 스키마/리졸버 변경 없음.
• 시드: 지역 마스터 추가(영구 데이터 — resetSeedScope 비대상) + 기존 시드 매장 2곳 region 연결.
• 의존 방향 / Prisma-ban / SDL↔DTO 동기 게이트 통과(arch:check · dto:check).

Test plan

• yarn validate 전체 통과 — 148 suites / 1275 tests / 커버리지 임계(96·86·92·96) 충족
• region 신규 23개: 1·2차 조회, hasChildren, sort_order, soft-delete·비활성 제외, parentId 404/BadRequest, 검색의 parentName·limit·빈 검색어 처리
• 수동 흐름: regionGroups → regions(parentId) → searchRegions(keyword)

후속(이 PR 범위 밖)

• 2차 생활권 큐레이션(spec의 "청라/검단/서구" 등 묶음): 기획 매핑표 확정 후 시드 확장. 현재는 표준 시군구 단위로 출발.
• nearbyRegions(현재 위치 주변): Region 좌표 데이터 확보 후
• 인기 매장 리스트 · 매장 찜 · 픽업 슬롯: PR2~4

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1c447640-3d38-4922-acb9-ca092ccfe01d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/region-master

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🧹 knip — dead-code 리포트

요약 항목 없음

전체 리포트

(knip 출력 없음 — 이슈 0이거나 실행 실패)

청소 후보(오탐 가능) · 기준 docs/guide/architecture-conventions.md

[github-actions]

🩺 NestJS Doctor — 88/100 (Good)

진단 248건 (error 0).

Category	error	warning	info
architecture	0	0	10
correctness	0	104	0
performance	0	24	14
schema	0	0	83
security	0	13	0

architecture / security 상위 항목

• info architecture/architecture/no-barrel-export-internals: Barrel file re-exports internal type 'IAuditLogRepository'.
• warning security/security/no-exposed-env-vars: Direct 'process.env.NODE_ENV' access in 'AuthController'. Use ConfigService instead.
• warning security/security/require-guards-on-endpoints: Endpoint 'start' has no @UseGuards() at class or method level.
• warning security/security/require-guards-on-endpoints: Endpoint 'callback' has no @UseGuards() at class or method level.
• warning security/security/require-guards-on-endpoints: Endpoint 'refresh' has no @UseGuards() at class or method level.
• warning security/security/require-guards-on-endpoints: Endpoint 'logout' has no @UseGuards() at class or method level.
• warning security/security/require-guards-on-endpoints: Endpoint 'sellerLogin' has no @UseGuards() at class or method level.
• warning security/security/require-guards-on-endpoints: Endpoint 'sellerRefresh' has no @UseGuards() at class or method level.
• warning security/security/require-guards-on-endpoints: Endpoint 'sellerLogout' has no @UseGuards() at class or method level.
• warning security/security/require-guards-on-endpoints: Endpoint 'devIssueToken' has no @UseGuards() at class or method level.
• info architecture/architecture/no-barrel-export-internals: Barrel file re-exports internal module '@/features/conversation/repositories/conversation.repository'.
• info architecture/architecture/no-barrel-export-internals: Barrel file re-exports internal type 'ConversationRepository'.
• info architecture/architecture/no-barrel-export-internals: Barrel file re-exports internal module '@/features/order/repositories/order.repository'.
• info architecture/architecture/no-barrel-export-internals: Barrel file re-exports internal type 'OrderRepository'.
• info architecture/architecture/no-barrel-export-internals: Barrel file re-exports internal module '@/features/product/repositories/product.repository'.

오탐 포함 가능 · 기준 docs/guide/architecture-conventions.md

[codecov]

Codecov Report

❌ Patch coverage is 98.14815% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../features/region/services/region-mappers.helper.ts	87.50%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟢	Statements	97.44%	3612/3707
🟢	Branches	93.76%	1142/1218
🟢	Functions	94.21%	667/708
🟢	Lines	97.7%	3308/3386

Test suite run success

1275 tests passing in 148 suites.

Report generated by 🧪jest coverage report action from 735e155