Files

T

Johngreen 16bd2cb92a 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

6.9 KiB

Raw Blame History

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. 확장 전략

향후 수도권/전국 확장 시 업종은 아래 방식으로 넓힌다.

FNB 하위 세분화
RETAIL 추가
SERVICE 추가
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를 기준으로 저장한다.
베타 종료 후 확장성을 해치지 않도록 전국 구조를 염두에 둔 코드 체계를 유지한다.

다음 단계

이 문서를 기준으로 RegionHierarchy, IndustryTaxonomy 모델을 schema.prisma에 반영
초기 seed 파일 생성
U002, U003, I003 테스트를 이 마스터 데이터를 기준으로 작성

6.9 KiB Raw Blame History