QRScan 앱 재구성 준비... 바코드 바우처 라고 배포 했던 앱을 정리해 보자...

BarcodeVoucher0407 - Agent Draft

 

0) 문서 목적

이 문서는 BarcodeVoucher0407 프로젝트의 초기 개발 가이드입니다.
목표는 바코드/QR 기반 영수증 적립 및 조회 앱의 MVP를 빠르게 완성하고,
이후 지도/업데이트/고도화 기능으로 확장 가능한 구조를 만드는 것입니다.

---

1) 제품 목표 / 핵심 사용자 시나리오

제품 목표

• 사용자가 영수증의 바코드(또는 QR)를 스캔해 디지털로 보관
• 보관된 영수증을 목록/검색/필터로 빠르게 조회
• 매장 위치와 연계(카카오맵)해 사용처를 시각적으로 확인
• 안정적인 업데이트 전달(In-app Update)

핵심 사용자 시나리오

1. 앱 실행 -> 스캔 버튼 탭
2. 바코드/QR 스캔 -> 코드값 추출
3. 영수증 메타정보(매장명, 금액, 일시, 카테고리, 메모 등) 입력/수정
4. 저장 후 목록에서 확인
5. 상세 화면에서 지도 위치 확인 및 메모 관리

---

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: Long
• updatedAt: Long

Entity: ScanHistory

• id: Long (PK)
• receiptId: Long? (FK)
• rawValue: String
• format: String
• scannedAt: Long
• isSaved: Boolean

DAO 예시

• insertReceipt(receipt)
• updateReceipt(receipt)
• deleteReceipt(id)
• getReceiptById(id)
• observeReceipts() (Flow<List>)
• searchReceipts(query)

인덱스/제약

• barcodeRaw, purchasedAt, storeName 인덱스 권장
• ScanHistory.receiptId FK + CASCADE

---

5) 화면/플로우 초안

주요 화면

1. Splash/Init: 필수 권한/업데이트 체크
2. Receipt List: 최근순 목록, 검색/필터
3. Scan: 카메라 미리보기 + 스캔 가이드
4. Receipt Edit/Detail: 저장/수정/삭제
5. Map: 카카오맵 위치 확인
6. Settings: 스캔 옵션, 테마, 정보

내비게이션

• list -> scan -> edit -> detail
• detail -> 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 체크리스트 작성

---

부록: 구현 우선순위 제안 (짧게)

1. Hilt + Room 기반 골격 완성
2. 스캔 -> 저장 -> 목록/상세까지 E2E 연결
3. 맵/업데이트 기능 순차 통합
4. 테스트 보강 후 MVP 배포