startover/docs/master-data/beta-master-data.md

# Startover 베타 마스터 데이터 초안

## 목적

이 문서는 Startover 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` 테스트를 이 마스터 데이터를 기준으로 작성