ADR-DS-040_매장 등록 및 위치 인증

2. 배경 (Context)

플랫폼에서 매장은 슬롯 발행의 주체이며, 사용자에게 노출되는 위치 기반 정보의 기준이 된다. 따라서 매장 등록 과정에서는 매장의 실제 위치를 일정 수준 이상 신뢰할 수 있도록 확인하는 절차가 필요하다.

그러나 매장 등록 단계에서 과도한 인증 절차를 요구하면 다음 문제가 발생할 수 있다.

매장 등록 진입 장벽 증가
초기 파트너 유입 감소
운영 절차 복잡화

플랫폼의 설계 원칙은 다음과 같다.

매장 등록은 최대한 간단하게 유지한다.
운영 가능 여부는 위치 인증 단계에서 제어한다.
위치 기반 서비스이므로 좌표 정확도를 확보한다.

특히 주소 기반 geocoding은 대부분 건물 중심 좌표를 반환하기 때문에 다음 문제가 발생할 수 있다.

대형 건물에서 실제 매장 위치와 좌표 불일치
건물 뒤편 또는 내부 위치 차이
상가/몰 내부 매장의 정확한 위치 표현 불가

따라서 지도 핀 이동을 통한 상세 위치 확정 절차가 필요하다.

3. 결정 (Decision)

매장 등록 및 위치 인증 절차는 다음 구조로 설계한다.

매장 등록

프로필에서 매장 등록을 선택하면 매장 등록 화면으로 이동한다. 매장 등록 시 사용자는 다음 최소 정보를 입력한다.

매장명
연락처
이메일
주소

주소 입력 시 시스템은 geocoding을 수행하여 기본 좌표를 생성한다.

위치 좌표 확정 (Pin Selection)

주소 입력 후 지도 화면을 표시하고 사용자가 직접 위치 핀을 이동하여 매장 좌표를 확정하도록 한다. 핀 확정은 선택 기능이 아니라 필수 단계다.

이 단계의 목적은 다음과 같다.

geocoding 좌표의 건물 중심 문제 해결
매장 입구 또는 실제 위치 지정
GPS 인증 정확도 향상

위치 확정 절차(필수):

주소 입력
geocoding을 통해 기본 좌표 생성
지도 화면 표시
기본 좌표 위치에 핀 표시
사용자가 핀을 이동하여 실제 매장 위치 지정
최종 좌표 저장
location_quality = 'verified'로 저장

매장은 단일 위치 좌표만 가진다.

현재 위치 보조 기능

주소 입력 UI에는 현재 위치 버튼을 제공한다.

동작:

사용자가 현재 위치 버튼 클릭
GPS 위치 획득
지도 중심 이동
핀을 현재 위치로 이동
reverse geocoding으로 주소 자동 입력

이를 통해 매장 위치 입력 과정을 단순화한다.

위치 인증

매장 등록 이후 최초 슬롯 발행 전에 GPS 기반 위치 인증을 수행한다. 슬롯 발행 API/RPC는 매장의 위치 인증 상태를 확인하고, 기준 미충족 시 발행을 거부해야 한다.

인증 방식:

distance(current_gps, store_latlng) <= threshold
AND gps_accuracy <= accuracy_threshold

권장 기준:

threshold ≈ 100m
accuracy_threshold ≈ 30~50m

인증 성공 시 매장은 verified 상태로 전환된다. 인증 실패 시 사용자는 재시도를 수행할 수 있으며, 성공 전까지 슬롯 발행은 차단된다.

매장 상태 모델

매장 상태는 다음과 같이 정의한다.

created
verified
active

설명:

created : 매장 등록 완료
verified : 위치 인증 완료
active : 정상 운영 상태

슬롯 발행은 verified 상태 이후에만 허용한다. 추후 결제방식, 계좌 등록 등 추가 인증 절차 도입 시 active 상태로 전환한다.

상태 필드 소속:

status는 매장 엔티티(partners) 필드다.
한 사용자는 여러 매장을 가질 수 있으므로, status는 사용자 단위가 아니라 매장별로 독립 관리한다.
각 매장은 자신만의 created/verified/active 라이프사이클을 가진다.

구현 기준:

상태 필드(partners.status)를 사용하는 경우 위 상태 모델을 그대로 적용한다.
상태 필드가 없고 location_quality만 사용하는 경우, 최소 게이트를 아래처럼 적용한다.
- unverified / approx: 슬롯 발행 불가
- verified: 슬롯 발행 가능

매장 사진

매장 사진은 등록 단계에서 요구하지 않는다.

매장 사진은 프로필 수정 화면에서 선택적으로 입력할 수 있는 옵션 정보로 취급한다.

주소/위치 변경 시 정책

주소 또는 좌표가 변경되면 위치 신뢰도는 초기화된다.

location_quality = 'unverified'로 전환
슬롯 발행 차단
재인증 성공 후 발행 허용

권한(Role)과 상태(Status) 분리

권한과 상태는 서로 다른 책임을 가진다.

profiles.role: 계정 권한(예: user, publisher_pending, publisher)
partners.status: 매장 운영 상태(예: created, verified, active)

profiles.role은 “이 계정이 무엇을 할 수 있는가"를, partners.status는 “이 매장이 발행 가능한 상태인가"를 판단한다.

4. 대안 (Alternatives Considered)

대안 A — 주소 기반 자동 좌표 사용

설명 주소 입력 후 geocoding 좌표를 그대로 매장 위치로 사용한다.

장점

구현 단순
사용자 입력 단계 감소

단점

대형 건물에서 위치 오차 발생
매장 입구 위치 표현 불가

채택하지 않은 이유 위치 기반 서비스에서 좌표 정확도는 중요한 요소이기 때문이다.

대안 B — GPS 좌표 자동 등록

설명 매장 등록 시 GPS 좌표를 직접 저장한다.

장점

실제 위치 반영 가능

단점

건물 내부에서 GPS 정확도 저하
등록 과정에서 실패 가능

채택하지 않은 이유 GPS는 실내 환경에서 오차가 발생할 수 있기 때문이다.

대안 C — 사업자 인증 기반 등록

설명 사업자 등록증 제출을 통해 매장을 인증한다.

장점

높은 신뢰도

단점

등록 장벽 증가
초기 파트너 확보 어려움

채택하지 않은 이유 초기 서비스 단계에서는 등록 장벽 최소화가 더 중요하기 때문이다.

5. 결과 (Consequences)

긍정적 결과

매장 등록 절차가 단순하게 유지된다.
지도 핀 이동을 통해 위치 정확도가 향상된다.
GPS 인증으로 최소 수준의 매장 위치 신뢰성을 확보할 수 있다.

부정적 결과

GPS 인증은 실내 환경에서 실패할 수 있다.
매장 위치 정확도는 사용자의 핀 이동 정확도에 의존한다.
주소/좌표 변경 시 재검증이 필요해 운영 단계가 추가된다.

6. 영향 범위 (Impact)

기술 구조

매장 위치 좌표 필드 추가
geocoding 및 reverse geocoding 로직 필요
GPS 기반 위치 인증 로직 필요
슬롯 발행 시점의 verified 게이트 검사 필요

지도 기반 위치 선택 화면 필요
현재 위치 버튼 제공
인증 실패 시 재시도 UX 및 오류 안내 필요

운영 정책

슬롯 발행은 verified 매장만 허용
주소/좌표 변경 매장은 재검증 전 발행 불가

7. 재검토 조건 (Revisit Conditions)

다음 조건이 발생하면 본 결정을 재검토한다.

매장 위치 오류 사례가 증가하는 경우
GPS 인증 실패율이 일정 수준 이상 발생하는 경우
매장 인증 요구 수준이 높아지는 경우
플랫폼 규모 확대에 따라 추가 인증 방식이 필요한 경우

Template v2 Addendum

In Scope

Merchant registration and location verification policy

Out of Scope

Settlement policy and redemption feature policy

Boundaries

Merchant onboarding policy is DS-040. Payment connector policy is DS-065.

Source of Truth (SoT)

Onboarding/location: ADR-DS-040; usage-verification linkage: ADR-DS-020 and ADR-DS-021.

Validation

Detect state/constraint violations via tests and batch checks.
Recovery and reprocessing must be idempotent.

Revisit Conditions

KPI threshold breach (reservation failure, expiry ratio, payment confirmation failure)
External dependency change (PG, regulation, location API)

Buy me a coffee

ADR-DS-031_감사로그 최소 스키마 ADR-DS-060_선결제 기반 슬롯