프로젝트 개요

이마트 모바일앱 내 신규 O2O 게이미피케이션 서비스 "워크이마트"의 프론트엔드 전체를 구축했습니다. 오프라인 매장 QR 스캔에서 걸음수 측정, 7종 미션 수행, 랜덤 리워드 지급, 결제 연동까지의 전체 사용자 플로우를 단독으로 설계·구현하고, QA 5차 대응을 거쳐 운영 배포를 완료했습니다.

📝

커밋

234개

🔗

API 연동

14개 엔드포인트

🎯

미션

7종 구현

✅

QA

5차 대응 → 배포

핵심 기술 결정 (판별하는 능력)

1. 게이트 진입 상태머신 설계 (8 Cases)

서비스 가능 여부, 최초/재방문 여부, 진입 경로(QR/앱), 측정 중 여부의 조합으로 8가지 분기 케이스를 식별했습니다. 각 케이스별 네이티브 콜백(startWalk/stopWalk) 호출 순서와 API 의존성을 결정했습니다. 특히 already_measuring 콜백을 success와 동일하게 처리하는 결정은 QA 3차에서 발견된 엣지 케이스를 기반으로 내린 판단이었습니다.

2. 네이티브↔웹 비동기 조율 패턴

stopWalk→startWalk 순차 호출(충돌 방지)과 서비스 불가 시 fire-and-forget 패턴을 분리했습니다. 콜백 status별 분기(success/already_measuring/cancelled/invalid_qr/noti_denied 등)를 설계하고, started 분기와 결합하여 /start API 호출 필요 여부를 결정하는 이중 분기 구조를 확립했습니다.

3. 에러 처리 체계 구축

비즈니스 에러(HTTP 200 + status 400) 패턴을 식별하고, $onErrorData + resultCode별 분기 체계를 설계했습니다. API transform 레이어에서 에러 응답 시 transform 적용을 방지하여 resultCode를 보존하는 구조적 해결을 적용했습니다.

4. Composable 아키텍처 — 오케스트레이션 훅 역할별 분리

gate/mission/reward/diary 도메인별 composable 폴더 구조를 설계했습니다. 단일 오케스트레이션 훅을 역할별(state 관리, 비즈니스 액션, 네이티브 브릿지)로 분리하고, 타입 파일을 출처와 방향 기준으로 재정립했습니다(API Response vs Entity vs Labels). 이 작업 과정에서 프로젝트 컨벤션 문서를 확립했습니다.

  1. QR 스캔 진입
  2. 상태머신 Gate (8 Cases)
  3. 걸음수 측정
  4. 7종 미션 수행
  5. 랜덤 리워드
  6. 결제 연동

도메인 암묵지 축적

오프라인 매장 운영 시간대(10:00~22:59)와 자정 초기화 규칙이 UX 플로우에 미치는 영향을 파악했습니다. 이마트페이 결제 타이밍 3가지 시나리오(사전 결제, 미션 내 결제, 이탈 후 결제)별 미션 상태 처리를 설계했으며, 임직원 CID 제외와 테스터 허용 목록 관리, 로얄/비로얄 고객 분기도 구현했습니다.

바코드 미션에서는 로컬 products 목록 매칭 후 fire-and-forget API 호출 패턴을 적용하여 UX 즉시 응답과 서버 기록을 분리했습니다. 리워드 시스템은 꽝 없음(최소 1원) + 포인트카드 적립 필수 + 당일 결제 건 한정 + 익일 지급 규칙으로 구성되어 있었습니다.

Composable 아키텍처/
  • gate/
    • 상태머신 (8 Cases)
    • orchestrateEntry
  • mission/
    • 7종 미션 핸들러
    • 바코드 로컬 매칭
  • reward/
    • 랜덤 리워드 지급
    • 포인트카드 적립
  • diary/
    • walking-log
    • ranking

정량 지표

커밋 234개(feat/fix/refactor/test/chore)를 작성하고 PR 다수를 머지했습니다. API 14개 엔드포인트(gate/main/start/missions/complete/reward/barcode/ranking/diary/banners/products/reward-summary/walking-log)를 연동했으며, 미션 7종(QR스캔/걷기/바코드/이마트페이/디지털전단/일반이벤트/룰렛)을 구현했습니다. QA 5차 대응과 디자인 검수를 거쳐 2026.05.28에 운영 배포를 완료했고, 요구사항 v4.1~v4.4 전체 버전에서 12건 변경사항을 반영했습니다.

커리어 판정

판별하는 능력(구조 결정권 + 도메인 암묵지)이 핵심입니다. 단순 UI 구현이 아닌, 네이티브↔웹 비동기 상태머신 설계와 O2O 비즈니스 규칙 판별이 이 프로젝트의 핵심 가치였습니다. 이 프로젝트에서 쌓인 것은 세 가지입니다: (1) 복잡한 상태 전이를 코드로 모델링하는 설계 판단력, (2) 오프라인 매장 운영 규칙이 프론트엔드 플로우에 미치는 영향을 예측하는 도메인 판별력, (3) 네이티브 브릿지 콜백 패턴 설계 경험입니다.

증거물 (아티팩트)

  • 요구사항 명세서 v4.2 (상태 분기 매트릭스 + BDD 시나리오 + API 명세 통합 문서) — 기획↔개발 간 계약 문서로 기능
  • Composable 아키텍처 컨벤션 문서 (AGENTS.md) — 이 프로젝트를 통해 팀 전체 컨벤션으로 확립
  • 에러 처리 체계 ($onErrorData + resultCode 분기) — 프로젝트 공통 패턴으로 채택
  • 타입 파일 분리 기준 문서 (출처×방향 매트릭스) — 팀 타입 설계 가이드라인