BarcodeVoucher0407 - Agent Draft
0) 문서 목적
이 문서는 BarcodeVoucher0407 프로젝트의 초기 개발 가이드입니다.
목표는 바코드/QR 기반 영수증 적립 및 조회 앱의 MVP를 빠르게 완성하고,
이후 지도/업데이트/고도화 기능으로 확장 가능한 구조를 만드는 것입니다.
1) 제품 목표 / 핵심 사용자 시나리오
제품 목표
- 사용자가 영수증의 바코드(또는 QR)를 스캔해 디지털로 보관
- 보관된 영수증을 목록/검색/필터로 빠르게 조회
- 매장 위치와 연계(카카오맵)해 사용처를 시각적으로 확인
- 안정적인 업데이트 전달(In-app Update)
핵심 사용자 시나리오
- 앱 실행 -> 스캔 버튼 탭
- 바코드/QR 스캔 -> 코드값 추출
- 영수증 메타정보(매장명, 금액, 일시, 카테고리, 메모 등) 입력/수정
- 저장 후 목록에서 확인
- 상세 화면에서 지도 위치 확인 및 메모 관리
2) 기술 스택 제안과 선택 이유
- Kotlin + Jetpack Compose: UI 생산성, 상태 기반 화면 구성
- Hilt: 의존성 주입 표준화, 테스트 용이성 향상
- Room: 오프라인 우선 로컬 저장, 구조화된 쿼리 지원
- Barcode/QR Scanner (ML Kit 또는 ZXing 계열): 빠른 스캔 구현
- Play Core In-app Update: 앱 내 업데이트 UX 개선
- Kakao Map API: 매장 위치/지도 시각화
- Coroutines + Flow: 비동기 처리, 반응형 데이터 스트림
- DataStore: 사용자 설정/간단 상태 영속화
3) 권장 프로젝트 구조
초기에는 단일 모듈(app)로 시작하고, 기능 확장 시 멀티모듈 전환을 권장합니다.
단일 모듈 패키지 구조(초기)
com.billcorea.barcodevoucher0407
core/(공통 유틸, Result, Dispatcher, Base)di/(Hilt Module)data/
local/(Room DB, DAO, Entity)remote/(향후 서버 연동 시)repository/(구현체)
domain/
model/repository/(인터페이스)usecase/
feature/
scan/receipt_list/receipt_detail/map/settings/
ui/(theme, common components)
멀티모듈 전환 후보(확장)
core-common,core-ui,data-local,feature-scan,feature-receipt,feature-map
4) 데이터 모델(Room) 초안
MVP 기준 최소 모델 + 확장 가능한 형태
Entity: Receipt
id: Long(PK, autoGenerate)barcodeRaw: String(원본 코드값, index)barcodeType: String(QR_CODE,EAN_13등)storeName: String?totalAmount: Long?currency: String?(예: KRW)purchasedAt: Long?(epoch millis)memo: String?imageUri: String?(선택: 영수증 사진)lat: Double?lng: Double?createdAt: LongupdatedAt: Long
Entity: ScanHistory
id: Long(PK)receiptId: Long?(FK)rawValue: Stringformat: StringscannedAt: LongisSaved: Boolean
DAO 예시
insertReceipt(receipt)updateReceipt(receipt)deleteReceipt(id)getReceiptById(id)observeReceipts()(Flow<List>)searchReceipts(query)
인덱스/제약
barcodeRaw,purchasedAt,storeName인덱스 권장ScanHistory.receiptIdFK + CASCADE
5) 화면/플로우 초안
주요 화면
- Splash/Init: 필수 권한/업데이트 체크
- Receipt List: 최근순 목록, 검색/필터
- Scan: 카메라 미리보기 + 스캔 가이드
- Receipt Edit/Detail: 저장/수정/삭제
- Map: 카카오맵 위치 확인
- Settings: 스캔 옵션, 테마, 정보
내비게이션
list -> scan -> edit -> detaildetail -> map
6) 아키텍처 가이드
- 패턴: MVVM + Repository + UseCase
- 상태:
UiState(Loading/Success/Error) + 단방향 데이터 흐름 - 비동기:
viewModelScope+Flow - DI: Hilt로
Database,Dao,Repository,UseCase주입 - 에러 정책: 도메인 에러 타입 분리(
Validation,Camera,Database,Map)
7) 단계별 구현 로드맵 (MVP -> 확장)
Phase 1 - MVP (핵심 기능)
- Hilt/Room 기본 세팅
- Receipt Entity/DAO/Repository 구현
- 스캔 화면 + 코드값 저장
- 목록/상세/수정/삭제
- 기본 테스트(DAO + ViewModel)
Phase 2 - 사용자 경험 강화
- 검색/필터/정렬
- 영수증 이미지 첨부
- 스캔 실패/중복 처리 UX 개선
- DataStore 설정화
Phase 3 - 고도화 기능
- Kakao Map 연동(상세 -> 지도)
- In-app Update 적용
- 통계/리포트(월별 금액, 카테고리)
8) 주요 리스크와 대응
- 스캔 인식률 문제: 가이드 오버레이, 재시도 UX, 라이브러리 A/B 검토
- 권한 거부 이슈: 권한 사전 안내 + 대체 흐름 제공
- 지도 API 키 관리:
local.properties/CI Secret 사용, 하드코딩 금지 - 업데이트 정책 충돌: immediate/flexible 전략 분리 및 QA 시나리오 확보
- 데이터 신뢰성: 트랜잭션/중복 체크/마이그레이션 테스트
9) 테스트 전략
- Unit Test: UseCase, ViewModel 상태 전이
- DAO Test: in-memory Room DB로 CRUD/검색 검증
- UI Test: 리스트/상세/스캔 진입 플로우
- 통합 점검: 업데이트 체크, 맵 진입, 권한 케이스
권장 기준:
- 핵심 도메인 로직 테스트 우선
- DB 스키마 변경 시 마이그레이션 테스트 필수
10) 초기 To-do 체크리스트
환경/의존성
- Hilt 관련 Gradle 플러그인 및 의존성 추가
- Room(KSP/KAPT 포함) 의존성 추가
- 스캔 라이브러리(ML Kit 또는 ZXing) 선택/적용
- In-app Update 의존성 추가
- Kakao Map SDK 의존성 및 키 설정
코드 베이스
-
Application+@HiltAndroidApp구성 -
AppDatabase, Entity, DAO 생성 - Repository + UseCase + ViewModel 연결
- Compose Navigation 그래프 구성
- 샘플 더미 데이터/프리뷰 작성
품질/운영
- 기본 테스트 템플릿 작성
- 에러 로깅/크래시 대응 정책 확정
- 릴리스 전 권한/업데이트/지도 QA 체크리스트 작성
부록: 구현 우선순위 제안 (짧게)
- Hilt + Room 기반 골격 완성
- 스캔 -> 저장 -> 목록/상세까지 E2E 연결
- 맵/업데이트 기능 순차 통합
- 테스트 보강 후 MVP 배포
댓글 없음:
댓글 쓰기