[바이브코딩]스마트 주유소 찾기

클로드 코드를 이용한 바이브코딩 실전 사례 #3

요즘 중동에서 미국의 이란 침공으로 인해 유가가 급등하면서 많은 이들이 기름값이 조금이라도 싼 곳을 찾아고자 최저가 주요소 앱을 사용한다.하지만 T맵 주유, 카카오맵 주유소, 오피넷 등 기존 서비스는 공통적으로 리터당 단가를 기준으로 주유소를 정렬하여 보여준다. 그러나 이 접근에는 근본적인 한계가 존재한다.

리터당 10원 저렴한 주유소가 10km 떨어져 있다면, 40L를 주유하여 절약하는 400원보다 왕복 20km를 이동하는 데 소모되는 추가 연료비와 시간 비용이 더 클 수 있다. 즉, 단가가 가장 싼 주유소가 실질적으로 가장 경제적인 선택이 아닐 수 있다는 것이다.

기존 앱의 한계를 정리하면 다음과 같다.

이러한 인식에서 출발하여, 이동 비용과 시간 비용을 종합적으로 반영한 실질 총비용 기반의 주유소 추천 앱을 기획하게 되었다.

목표

본 프로젝트의 목표로 생각하는 부분은 다음과 같다.

실질 비용 기반 추천: 주유 가격 + 이동 연료비 + 시간 비용을 종합한 실질 총비용(Real Total Cost)으로 주유소를 순위 정렬한다.

비용 투명성: 순수 연료비, 추가 연료비, 시간 비용의 3가지 구성 요소를 분리 표시하여 사용자가 비용 구조를 직관적으로 이해할 수 있도록 한다.

맞춤 설정: 연비, 주유량, 시간 가치, 평균 이동 속도, 검색 반경을 사용자가 직접 조절하여 자신의 상황에 맞는 추천을 받을 수 있도록 한다.

유가 추세 제공: 최근 가격 추세와 주유 타이밍 추천을 제공하여 추가적인 절약 판단을 돕는다.

핵심 공식

본 앱의 핵심은 다음 공식이다.

실질 총비용 = 단가 × (주유량 + 거리 ÷ 연비) + (거리 ÷ 속도 + 대기시간) × 시간가치

이를 3가지 구성 요소로 분해하면 다음과 같다.

기술 스택 및 아키텍처

하네스 엔지니어링 아키텍처

본 프로젝트의 가장 큰 아키텍처적 특징은 하네스 엔지니어링(Harness Engineering) 패턴의 적용이다. 이는 자동차의 전장 하네스(wiring harness)에서 착안한 개념으로, 인터페이스 계약(Contract)을 중심축으로 두고 구현체(Provider)를 설정 기반으로 교체할 수 있는 구조이다.

계약 (Contracts) → 구현체 (Providers) → DI Container → 설정 (Config)

핵심흐름

contracts/ 디렉토리에 IFuelDataProvider, IMapProvider, ICostCalculator, ITrendAnalyzer 4개의 인터페이스를 정의한다.

providers/ 디렉토리에 각 인터페이스의 구현체를 배치한다. Mock 프로바이더와 실제 API 프로바이더가 동일한 인터페이스를 구현한다.

di/container.ts가 config/app.config.ts의 설정값을 읽어 적절한 구현체를 생성하여 반환한다.

프로바이더 교체 시 설정 파일의 값만 변경하면 되며, 비즈니스 로직이나 UI 코드의 수정이 불필요하다.

기존 순차 방식(PLAN_BASIC)과의 비교

하네스 방식의 가장 큰 장점은 Phase 1에서 하네스를 구축한 뒤, Phase 2의 3개 작업(계산 엔진, API 클라이언트, UI 컴포넌트)을 병렬로 진행할 수 있다는 점이다. Mock 프로바이더가 실제 API를 대체하므로 API 키 없이도 전체 개발 흐름을 시뮬레이션할 수 있다.

모듈 의존관계 다이어그램

모든 모듈은 contracts에 정의된 인터페이스에 의존하며, 구현체(providers, core)는 인터페이스만 알면 된다. di/container가 설정에 따라 적절한 구현체를 조립하여 상위 모듈에 전달한다. 이 구조 덕분에 어떤 계층의 코드를 수정하더라도 다른 계층에 영향을 주지 않는다.

외부 API 연동

오피넷(OPINET) API

한국석유공사가 운영하는 오피넷 API를 통하여 전국 주유소 가격 정보를 조회한다.

KATEC 좌표계 변환 이슈: 오피넷 API는 KATEC(Korean Association of Topographic Engineers Coordinate) 좌표계를 사용한다. GPS가 제공하는 WGS84 좌표를 KATEC으로 변환하여 요청하고, 응답의 KATEC 좌표를 WGS84로 역변환하여야 한다. 이를 위하여 Transverse Mercator 근사 기반의 coordConvert.ts 유틸리티를 직접 구현하였다. 약 10m 이내의 오차가 발생할 수 있으나, 주유소 반경 검색(km 단위)에서는 충분한 정밀도이다.

카카오 모빌리티 API

카카오 모빌리티 Directions API를 통하여 출발지에서 각 주유소까지의 실제 도로 거리와 소요 시간을 계산한다.

화면 구성

본 앱은 4개 화면으로 구성된다.

https://github.com/daehyub71/smart-fuel-finder