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