dpdpdndn 블로그

PRD

NEW13 min read

외부 연동 정비 PRD

Background

sports-application은 이미 상당한 외부 연동 모킹 인프라와 그 전환 메커니즘을 갖추고 있다. mock-pg/는 kakao·toss·naver·danal·bank_transfer·card 6개 PG사를 스키마 준수 수준으로 모킹하며 멱등성 테스트까지 갖췄다. mock-servers/README.md는 이미 mock 대상별 매핑 표를 문서화하고 있다 — kakao-local은 Kakao Local REST(주소→좌표, 실 API dapi.kakao.com)를, data-go-kr은 공공체육시설 + 기상청 단기예보 2개 서비스(실 API apis.data.go.kr/1360000/VilageFcstInfoService_2.0 등)를, solapi는 SOLAPI SMS 발송을 모사한다. 전환 메커니즘도 이미 구현돼 있다 — 백엔드 Gateway는 base-url+api-key를 env로 받아 키가 없으면 mock host(localhost:910x)를, 키가 있으면 실 API host를 바라본다. 코드 변경 없이 env만 교체하면 mock→실연동이 전환된다.

domain/facility.PublicSportsFacilityGateway·GeocodingGateway, domain/weather.WeatherGateway는 이미 이 메커니즘을 사용한다. infrastructure/weather/gateway/KmaWeatherGatewayImpl이 기상청 단기예보 연동 구현체로 이미 존재하며, data-go-kr mock 서버가 서빙하는 2개 서비스(공공체육시설, 기상청 단기예보)는 동일 호스트·동일 인증키(DATA_GO_KR_SERVICE_KEY)를 공유한다 — 즉 공공데이터포털 키 발급 1건으로 facility와 weather 두 도메인의 실연동이 동시에 가능해진다.

요구사항은 “가급적 무료로 외부 API를 연동하되 안 되면 mock 서버로 대체”를 원칙으로 제시한다. 이미 구현·문서화된 전환 메커니즘이 있으므로, 이 과제의 실체는 “구현체를 새로 만드는 것”이 아니라 **“실제 키를 발급받아 env를 설정하고, 실 API 응답이 기존 mock 스키마와 일치하는지 검증하는 것”**이다. 또한 요구사항이 언급한 “체육관, 공원, 날씨, 맵 등 외에 과제 진행 중 필요한 외부 데이터”에 대한 추가 발굴도 아직 이뤄지지 않았다.

Problem Definition

  • 실제 키 발급·env 설정·실 API 응답 검증이 수행된 적이 없다 — 전환 메커니즘은 존재하지만 “실행”된 적이 없다.
  • 발급 주체 기준으로 무엇이 전환 가능한지 정리된 적이 없다 — kakao-local(카카오 계정 발급)과 data-go-kr(공공데이터포털 계정 발급, facility+weather 공유)은 서로 다른 발급 주체이며, solapi는 사업자 발신번호가 필요해 개인 프로젝트에서 전환이 사실상 불가능하다는 점이 문서화된 적이 없다.
  • 전환 판정 기준(요청 한도가 어느 수준이면 전환하는지)이 수치화된 적이 없다.
  • 스포츠앱 유즈케이스에 도움이 될 수 있는 추가 외부 데이터(대중교통, 대기질, 지역 행사 등)가 발굴된 적이 없다.

Goals / Non-Goals

Goals

  • 발급 주체(카카오, 공공데이터포털, SOLAPI) 3곳 각각의 실제 무료 API 요청 한도·인증 방식을 조사한 표를 작성한다 — mock-servers/README.md의 기존 매핑 표를 조사표의 출발점으로 삼는다.
  • 전환 판정 기준을 수치화한다: 무료 API의 일일 요청 한도가 1,000건 이상이면 실연동으로 전환하고, 미만이면 mock을 유지하며 사유를 기록한다.
  • 전환 가능 판정된 발급 주체는 실제 키를 발급받아 env(KAKAO_REST_API_KEY, DATA_GO_KR_SERVICE_KEY 등)를 설정하고, 실 API 응답이 기존 mock 스키마와 일치하는지 검증한다.
  • 전환이 불가능한 항목(SOLAPI, 결제 PG)은 mock 유지 사유를 문서로 남긴다.
  • 현재 다루지 않는 신규 외부 데이터 소스 후보를 3개 이상 발굴하고 스포츠앱 유즈케이스 연계 아이디어와 함께 문서화한다.

Non-Goals

  • 결제 PG(토스페이먼츠·네이버페이·카카오페이) 실계약 연동 — 개인 프로젝트 특성상 사업자 계약이 불가능하므로 mock을 유지한다.
  • 발굴한 신규 외부 데이터 소스의 실제 기능 개발 — 이 과제는 발굴·문서화까지이며, 기능 개발은 별도 과제로 검토한다(Open Questions).
  • [상시 트래픽 시뮬레이터](../상시 트래픽 시뮬레이터/PRD.md)가 발생시키는 대량 조회 트래픽을 실연동 API로 흘려보내는 것 — 무료 API의 일일 요청 한도를 보호하기 위해, 상시 트래픽 시뮬레이터의 대량 조회는 실연동 전환 여부와 무관하게 계속 mock을 사용한다(아래 NFR 참조).

User Scenarios

페르소나: 백엔드 개발자(본인).

  1. 해피 패스 — 조사표 활용: facility 도메인을 개발하다가 “이 데이터가 실제 API인지 mock인지” 궁금할 때 mock-servers/README.md + 본 과제 조사표를 확인해 즉시 판단한다.
  2. 해피 패스 — 실연동 전환: 공공데이터포털 키(DATA_GO_KR_SERVICE_KEY) 1건을 발급받아 env에 설정하면, 코드 변경 없이 facility(공공체육시설)와 weather(기상청 단기예보) 두 도메인이 동시에 실연동으로 전환된다.
  3. 예외 — 요청 한도 부족: SOLAPI처럼 실연동에 사업자 발신번호가 필요해 개인 프로젝트에서 전환 불가능한 경우, mock 유지 사유로 기록하고 결제 PG와 함께 분류한다.
  4. 빈 상태: 아직 조사되지 않은 신규 데이터 소스 후보는 “발굴 대기” 상태로 표에 기록된다.

Benchmarking

제품명카테고리참조 패턴URL
Kakao Local REST (dapi.kakao.com)주소→좌표 지오코딩 Open APIREST API Key 발급 후 무료로 사용 가능하며, mock-servers/kakao-local이 모사하는 실 API의 정확한 대상 — EXTERNAL_GEOCODING_BASE_URL env 전환의 실체Kakao 지도 Web API
공공데이터포털 기상청 단기예보(VilageFcstInfoService_2.0)정부 공공데이터 Open API인증키(DATA_GO_KR_SERVICE_KEY) 1건으로 공공체육시설·기상청 단기예보 2개 서비스를 함께 사용할 수 있으며, 무료로 제공되고 상업적 활용도 조건부 허용 — mock-servers/data-go-kr이 모사하는 실 API의 정확한 대상공공데이터포털 활용법

Functional Requirements

ID요구사항우선순위
FR-1mock-servers/README.md의 매핑 표를 출발점으로, 발급 주체 3곳(카카오, 공공데이터포털, SOLAPI) 각각의 일일 요청 한도·인증 방식·발급 절차를 조사한 표를 작성한다P0
FR-2전환 판정 기준(일일 요청 한도 1,000건 이상 → 전환, 미만 → mock 유지)을 적용해 카카오·공공데이터포털 키를 발급받고, KAKAO_REST_API_KEY/DATA_GO_KR_SERVICE_KEY env를 설정한 뒤 실 API 응답이 기존 mock 스키마와 일치하는지 검증한다(구현체 신규 개발이 아니라 키 발급+env 설정+응답 검증이다)P0
FR-3공공데이터포털 키 전환이 facility(공공체육시설)와 weather(기상청 단기예보) 두 도메인에 동시 적용됨을 확인한다(동일 키 공유)P0
FR-4신규 외부 데이터 소스 후보를 3개 이상 발굴해 스포츠앱 유즈케이스 연계 아이디어와 함께 문서화한다P1
FR-5SOLAPI(사업자 발신번호 필요)는 전환 불가 항목으로 분류하고, 결제 PG와 함께 “mock 유지 사유” 표에 기록한다P1

Non-Functional Requirements

  • 실연동으로 전환한 API는 개발·정합성 검증 목적의 저빈도 호출에 한정한다 — [상시 트래픽 시뮬레이터](../상시 트래픽 시뮬레이터/PRD.md)의 대량 조회 트래픽은 무료 API 요청 한도를 보호하기 위해 계속 mock을 사용한다(Non-Goals 참조).
  • API 키는 .zshrc 등 환경변수로만 주입한다 — 코드·문서에 평문 노출 0건을 유지한다.

Operations

  • 실연동 전환된 외부 API 호출(개발용 저빈도 호출)의 실패율·레이턴시를 [옵저버빌리티 스택 도입](../옵저버빌리티 스택 도입/PRD.md) 대시보드에 노출한다.
  • 무료 API의 일일 요청 한도 80% 도달 시 알림을 발송한다([지능형 장애 알림](../지능형 장애 알림/PRD.md) 채널 활용 여부는 해당 과제와 조율).

Success Metrics

  • 조사표가 발급 주체 3곳(카카오, 공공데이터포털, SOLAPI) 전체를 커버한다.
  • 공공데이터포털 키 발급으로 facility·weather 2개 도메인이 동시에 실연동 전환 완료.
  • 카카오 키 발급으로 facility의 지오코딩이 실연동 전환 완료.
  • 신규 발굴 외부 데이터 소스 3개 이상 문서화 완료.

Milestones

  • M1: 발급 주체 3곳 조사표 작성(FR-1).
  • M2: 전환 판정 기준 적용, 카카오·공공데이터포털 실연동 전환(FR-2, FR-3).
  • M3: SOLAPI mock 유지 분류, 신규 데이터 소스 발굴(FR-4, FR-5).

의존 없음 — [도메인 경계 재설계](../도메인 경계 재설계/PRD.md)와 독립적으로 병행 가능하다.

Open Questions

  • 신규 발굴 데이터 소스를 실제 기능으로 개발할지 여부와, 개발한다면 어느 과제로 편입할지 결정이 필요하다.
  • 전환 판정 기준(일일 요청 한도 1,000건)이 향후 실제 사용량 대비 적정한지, 실연동 이후 재조정이 필요한지는 M2 진행 중 재검토한다.

Document History

날짜변경 내용
2026-07-03최초 작성
2026-07-03재검수 1차 반영: AS-IS 대량 정정(KmaWeatherGatewayImpl 기존 구현, mock-servers/README.md 기존 매핑 문서, data-go-kr의 공공체육시설+기상청 2종 서빙, facility·weather 키 공유 확인), FR-2를 “구현체 전환”에서 “키 발급+env 설정+응답 검증”으로 재정의, 조사 단위를 “mock 5개”에서 “발급 주체 3곳”으로 재구성, 전환 판정 기준 수치화(일 한도 1,000건), SOLAPI를 PG와 함께 mock 유지 후보로 선분류, Benchmarking을 실제 전환 대상(dapi.kakao.com, VilageFcstInfoService)에 맞게 수정

그래프 뷰