feat: Re:Link MVP 초기 구현 - 도메인/서비스/프론트엔드 전체

- 모노레포 구조 (Turborepo + pnpm): @relink/domain, @relink/shared, @relink/infrastructure, @relink/database, @relink/web - 도메인 레이어: 매장(store), 매칭(matching), 업체(vendor), 보조금(subsidy), 계약/에스크로(contract) TDD 완료 (158 단위 테스트) - 서비스 레이어: 전 도메인 서비스 함수 + 통합 테스트 (58 테스트) - 프론트엔드: Next.js 15 App Router, 13개 페이지 (사용자 6 + 관리자 7) - 인프라: PostgreSQL 16 + PostGIS, Prisma ORM, Docker Compose, AuditLog + OutboxEvent 패턴 - .env 파일 포함 (로컬 개발 기본값만 포함, 실제 시크릿 없음) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-07 17:39:56 +09:00
commit 16bd2cb92a
170 changed files with 23628 additions and 0 deletions
@@ -0,0 +1,223 @@
+# Re:Link 베타 마스터 데이터 초안
+
+## 목적
+
+이 문서는 Re:Link MVP 베타에서 사용할 지역/업종 마스터 데이터의 구조와 초기 seed 원칙을 정의한다.
+
+핵심 목표는 아래 3가지다.
+
+- 지역과 업종을 코드 하드코딩 없이 운영 플래그로 제어한다.
+- 베타 범위 `강남/마포`, `F&B`를 코드 수정 없이 켜고 끌 수 있게 만든다.
+- 이후 Phase 2에서 수도권/광역시 확장 시 seed 추가만으로 확장 가능하게 만든다.
+
+## 기본 원칙
+
+- enum이 아니라 테이블 기반으로 관리한다.
+- 내부 참조 키는 `code`를 사용한다.
+- 실제 트랜잭션 테이블은 가능한 한 leaf 노드를 참조한다.
+- 베타 노출 여부는 `isBetaEnabled` 플래그로 제어한다.
+- seed는 `id` 기준이 아니라 `code` 기준 upsert로 관리한다.
+- seed 파일은 코드 안 배열이 아니라 별도 파일로 관리한다.
+
+권장 저장 위치:
+
+- `packages/database/seeds/master-data/regions.v1.csv`
+- `packages/database/seeds/master-data/industries.v1.csv`
+
+## 1. 지역 마스터 설계
+
+### 1-1. 권장 모델: `RegionHierarchy`
+
+단일 계층 테이블 + self relation 구조를 사용한다.
+
+권장 필드:
+
+- `id`
+- `code`
+- `nameKo`
+- `fullNameKo`
+- `regionType`
+- `parentId`
+- `depth`
+- `pathCode`
+- `sortOrder`
+- `isActive`
+- `isBetaEnabled`
+- `latitude`
+- `longitude`
+- `externalCode`
+
+운영 원칙:
+
+- `Store.regionClusterId`는 운영 단위인 `BETA_CLUSTER`를 가리킨다.
+- `Store.regionLeafId`는 실제 행정/상권 leaf를 가리킨다.
+- 검색과 집계는 우선 `regionClusterId` 기준으로 단순화한다.
+- 향후 지도/거리 기반 고도화 시 `latitude`, `longitude`를 활용한다.
+
+### 1-2. 지역 타입
+
+- `COUNTRY`
+- `SIDO`
+- `SIGUNGU`
+- `ADMIN_DONG`
+- `COMMERCIAL_AREA`
+- `BETA_CLUSTER`
+
+### 1-3. 초기 베타 지역 seed
+
+아래 값은 초안이다. 실제 서비스 운영 단위는 `BETA_CLUSTER`를 기준으로 한다.
+
+| code | nameKo | regionType | parentCode | depth | isBetaEnabled |
+|------|--------|------------|------------|-------|---------------|
+| `KR` | 대한민국 | `COUNTRY` | - | 0 | false |
+| `KR.SEOUL` | 서울특별시 | `SIDO` | `KR` | 1 | false |
+| `KR.SEOUL.GANGNAM` | 강남구 | `SIGUNGU` | `KR.SEOUL` | 2 | false |
+| `KR.SEOUL.MAPO` | 마포구 | `SIGUNGU` | `KR.SEOUL` | 2 | false |
+| `KR.SEOUL.GANGNAM.YEOKSAM` | 역삼 | `COMMERCIAL_AREA` | `KR.SEOUL.GANGNAM` | 3 | true |
+| `KR.SEOUL.GANGNAM.SEOLLEUNG` | 선릉 | `COMMERCIAL_AREA` | `KR.SEOUL.GANGNAM` | 3 | true |
+| `KR.SEOUL.GANGNAM.NONHYEON` | 논현 | `COMMERCIAL_AREA` | `KR.SEOUL.GANGNAM` | 3 | true |
+| `KR.SEOUL.MAPO.HONGDAE` | 홍대 | `COMMERCIAL_AREA` | `KR.SEOUL.MAPO` | 3 | true |
+| `KR.SEOUL.MAPO.HAPJEONG` | 합정 | `COMMERCIAL_AREA` | `KR.SEOUL.MAPO` | 3 | true |
+| `KR.SEOUL.MAPO.YEONNAM` | 연남 | `COMMERCIAL_AREA` | `KR.SEOUL.MAPO` | 3 | true |
+| `KR.BETA.GANGNAM_CORE` | 강남권 베타 클러스터 | `BETA_CLUSTER` | `KR.SEOUL.GANGNAM` | 3 | true |
+| `KR.BETA.MAPO_CORE` | 마포권 베타 클러스터 | `BETA_CLUSTER` | `KR.SEOUL.MAPO` | 3 | true |
+
+### 1-4. 클러스터 연결 원칙
+
+운영상 `역삼/선릉/논현`은 하나의 베타 클러스터 `KR.BETA.GANGNAM_CORE`로 묶고, `홍대/합정/연남`은 `KR.BETA.MAPO_CORE`로 묶는다.
+
+이유:
+
+- 검색/매칭/집계를 단순화할 수 있다.
+- 베타 성과를 클러스터 단위로 운영할 수 있다.
+- 이후 개별 상권 단위 성능을 본 뒤 세분화하기 쉽다.
+
+## 2. 업종 마스터 설계
+
+### 2-1. 권장 모델: `IndustryTaxonomy`
+
+단일 계층 테이블 + self relation 구조를 사용한다.
+
+권장 필드:
+
+- `id`
+- `code`
+- `nameKo`
+- `parentId`
+- `depth`
+- `sortOrder`
+- `isLeaf`
+- `isActive`
+- `isBetaEnabled`
+- `externalCode`
+- `searchAliases`
+
+운영 원칙:
+
+- `Store.industryLeafId`는 leaf 업종만 가리킨다.
+- 상위 카테고리 필터는 hierarchy를 따라 계산한다.
+- 검색 자동완성과 유사어 처리를 위해 `searchAliases`를 둘 수 있다.
+
+### 2-2. 초기 베타 업종 seed
+
+베타는 F&B만 우선 켠다.
+
+| code | nameKo | parentCode | depth | isLeaf | isBetaEnabled |
+|------|--------|------------|-------|--------|---------------|
+| `FNB` | 음식점/카페 | - | 0 | false | true |
+| `FNB.CAFE` | 카페 | `FNB` | 1 | true | true |
+| `FNB.BAKERY` | 베이커리 | `FNB` | 1 | true | true |
+| `FNB.KOREAN` | 한식 | `FNB` | 1 | true | true |
+| `FNB.CHICKEN` | 치킨 | `FNB` | 1 | true | true |
+| `FNB.BAR` | 주점 | `FNB` | 1 | true | true |
+| `FNB.DESSERT` | 디저트 | `FNB` | 1 | true | true |
+| `FNB.FASTCASUAL` | 간편식/패스트캐주얼 | `FNB` | 1 | true | true |
+
+### 2-3. 확장 전략
+
+향후 수도권/전국 확장 시 업종은 아래 방식으로 넓힌다.
+
+1. `FNB` 하위 세분화
+2. `RETAIL` 추가
+3. `SERVICE` 추가
+4. `OFFICE/ETC` 추가
+
+초기 MVP에서는 업종 수를 억지로 늘리지 않는다.
+
+## 3. 마스터 데이터 조회 정책
+
+### 3-1. 기본 API 원칙
+
+`GET /api/v1/master-data`
+
+반환 예시 범위:
+
+- 베타 가능 지역 클러스터 목록
+- 베타 가능 leaf 업종 목록
+- 각 항목의 `code`, `nameKo`, `parentCode`, `isBetaEnabled`
+
+### 3-2. 응답 정책
+
+- 기본 사용자는 `isActive = true`, `isBetaEnabled = true`만 받는다.
+- 운영자는 전체 항목을 조회할 수 있다.
+- 삭제 대신 `isActive = false`로 비활성화한다.
+
+## 4. seed 전략
+
+### 4-1. 파일 기준 관리
+
+seed 원본은 코드 내 하드코딩 배열이 아니라 파일 기반으로 관리한다.
+
+예시:
+
+- `regions.v1.csv`
+- `industries.v1.csv`
+
+권장 컬럼:
+
+- `code`
+- `name_ko`
+- `parent_code`
+- `depth`
+- `sort_order`
+- `is_leaf`
+- `is_active`
+- `is_beta_enabled`
+
+### 4-2. upsert 기준
+
+- `id`가 아니라 `code` 기준 upsert
+- 기존 row가 있으면 `name`, `sortOrder`, `isBetaEnabled`만 보정
+- 운영 중 이미 참조 중인 row는 삭제하지 않는다
+
+### 4-3. 버전 관리
+
+가능하면 `MasterDataVersion` 또는 seed 파일명 자체로 버전을 남긴다.
+
+예시:
+
+- `regions.v1.csv`
+- `regions.v2.csv`
+
+## 5. 구현 체크리스트
+
+- [ ] `RegionHierarchy` 모델 생성
+- [ ] `IndustryTaxonomy` 모델 생성
+- [ ] `code` unique index 생성
+- [ ] `parentId` self relation 연결
+- [ ] `isBetaEnabled`, `isActive` 플래그 추가
+- [ ] 베타 지역/업종 seed 파일 작성
+- [ ] `GET /api/v1/master-data` 응답 계약 고정
+
+## 6. 주의사항
+
+- `강남`, `마포`, `F&B`를 앱 코드에 하드코딩하지 않는다.
+- seed 값이 정책의 소스 오브 트루스가 되도록 운영 플래그를 사용한다.
+- `Store`에는 사람이 읽는 이름보다 `regionClusterId`, `industryLeafId` FK를 기준으로 저장한다.
+- 베타 종료 후 확장성을 해치지 않도록 전국 구조를 염두에 둔 코드 체계를 유지한다.
+
+## 다음 단계
+
+1. 이 문서를 기준으로 `RegionHierarchy`, `IndustryTaxonomy` 모델을 `schema.prisma`에 반영
+2. 초기 seed 파일 생성
+3. `U002`, `U003`, `I003` 테스트를 이 마스터 데이터를 기준으로 작성