2026/05/09

프레시틱 (Freshtic) 개발 작업 히스토리

프로젝트 개요

프로젝트명: Freshtic (Fresh + Tactic)

목적: 유통기한(또는 사용자 정의 기한) 관리를 통해 음식물 폐기(낭비)를 줄이는 로컬 중심 Android 앱

버전: v1.0 (오프라인 완결)

개발 기간: 2026.02.17 ~

기술 스택: Kotlin, Jetpack Compose, Room, Hilt, WorkManager (예정), CameraX + ML Kit (예정)

📋 Plan.pptx 대비 진행 상황

✅ 완료된 단계

1단계: 프로젝트 설정 및 테마 적용 ✅ 100% 완료

Plan 요구사항:

프로젝트 초기 설정

Material 3 테마 적용

색상 시스템 (Light/Dark)

타이포그래피 (Noto Sans KR)

구현 완료:

✅ Kotlin 2.3.10, KSP 2.3.2 적용
✅ Gradle 9.0.1, AGP 최신 버전
✅ Hilt 2.59.1 설정 완료
✅ Room 2.8.4 설정 완료
✅ Material 3 테마 완전 구현
   - Color.kt: Light/Dark 색상 각 38개 정의
   - Theme.kt: lightScheme, darkScheme 완성
   - Type.kt: Material 3 Typography 전체 정의
✅ Google Fonts (Noto Sans KR) 적용
   - font_certs.xml 생성
   - ui-text-google-fonts 라이브러리 추가
✅ AndroidManifest.xml 카메라 권한 설정

파일 구조:

ui/theme/
├── Color.kt          # 76개 색상 (Light/Dark/Contrast variants)
├── Theme.kt          # Material 3 테마 설정
└── Type.kt           # Noto Sans KR 타이포그래피

res/values/
└── font_certs.xml    # Google Fonts 인증서

2단계: 데이터 레이어 구축 (Room Database) ✅ 100% 완료

Plan 요구사항:

Entity 정의 (ItemEntity, BarcodeCacheEntity)

Enum 클래스 (DateType, StorageType, ItemStatus)

TypeConverter (LocalDate, Instant, Enum)

DAO 인터페이스 (ItemDao, BarcodeCacheDao)

Database 클래스

Repository 패턴 적용

구현 완료:

✅ Domain Model (Enum 클래스)
   - DateType: EXPIRY(유통기한), USER_DEFINED(사용자 정의)
   - StorageType: ROOM(실온), FRIDGE(냉장), FREEZER(냉동)
   - ItemStatus: ACTIVE(활성), CONSUMED(소비), TRASHED(폐기)

✅ Room Entity
   - ItemEntity: 11개 필드, 인덱스 3개 (status, targetDate, barcode)
   - BarcodeCacheEntity: 바코드 재스캔 시 상품명 자동완성

✅ TypeConverter
   - LocalDate ↔ Long (epochDay)
   - Instant ↔ Long (epochMilli)
   - Enum ↔ String (name)

✅ DAO 인터페이스
   - ItemDao: 14개 메서드
     * CRUD 기본 (insert, update, delete, getById)
     * 홈 화면용 쿼리 (getAllActive, getUpcoming, getExpired)
     * 검색/필터 (searchByName, getByStorageType)
     * 알림용 (getAllActiveItems)
   - BarcodeCacheDao: 4개 메서드 (upsert, getByBarcode, deleteOld)

✅ Repository
   - ItemRepository: 비즈니스 로직 중앙 관리
   - 바코드 캐시 자동 upsert
   - WorkManager 연동 준비 (TODO 마커)

✅ Hilt DI
   - DatabaseModule: Database, DAO 제공

파일 구조:

domain/model/
├── DateType.kt
├── ItemStatus.kt
└── StorageType.kt

data/local/
├── entity/
│   ├── ItemEntity.kt
│   └── BarcodeCacheEntity.kt
├── dao/
│   ├── ItemDao.kt
│   └── BarcodeCacheDao.kt
├── converter/
│   └── RoomTypeConverters.kt
└── db/
    └── FreshticDatabase.kt

data/repository/
└── ItemRepository.kt

di/
└── DatabaseModule.kt

Plan 대비 차이점:

✅ Plan의 모든 쿼리 요구사항 구현됨

✅ 인덱스 최적화 적용 (Plan 권장사항)

⚠️ WorkManager 알림 연동은 아직 TODO (4단계 예정)

3단계: UI 기본 구조 및 네비게이션 ✅ 85% 완료

Plan 요구사항:

5개 화면 구현 (홈, 스캔, 등록/수정, 상세, 설정)

Navigation 설정

각 화면 기본 UI

ViewModel 연동

구현 완료:

✅ Navigation 설정
   - Screen.kt: 5개 라우트 정의
   - FreshticNavGraph.kt: 네비게이션 그래프
   - 딥링크 지원 (freshtic://items/{itemId})
   - 파라미터 전달 (itemId)

✅ 홈 화면 (HomeScreen.kt + HomeViewModel.kt)
   - 임박 섹션 (0~3일) ✅
   - 전체 목록 (targetDate 오름차순) ✅
   - D-day 자동 계산 및 색상 구분 ✅
   - FAB (+버튼) → 스캔 화면 이동 ✅
   - Empty/Loading 상태 처리 ✅
   - Flow 기반 실시간 업데이트 ✅

✅ 바코드 스캔 화면 (BarcodeScanScreen.kt)
   - 기본 레이아웃 완성 ✅
   - "직접 입력" 버튼 → 등록 화면 이동 ✅
   - ⚠️ CameraX + ML Kit 구현 예정 (TODO)

✅ 등록/수정 화면 (AddEditItemScreen.kt + AddEditItemViewModel.kt)
   - 기본 레이아웃 완성 ✅
   - itemId 파라미터 처리 ✅
   - ⚠️ 폼 필드 구현 예정 (다음 단계)

✅ 상세 화면 (ItemDetailScreen.kt + ItemDetailViewModel.kt)
   - 기본 레이아웃 완성 ✅
   - Loading/Error/Success 상태 처리 ✅
   - 소비/폐기 버튼 UI ✅
   - ⚠️ 실제 동작 구현 예정 (다음 단계)

✅ 설정 화면 (SettingsScreen.kt)
   - 알림 on/off Switch ✅
   - 앱 정보 표시 ✅
   - ⚠️ 실제 설정 저장 로직 예정 (4단계)

✅ MainActivity 통합
   - FreshticNavGraph 적용 ✅
   - enableEdgeToEdge ✅

파일 구조:

navigation/
├── Screen.kt
└── FreshticNavGraph.kt

ui/
├── home/
│   ├── HomeScreen.kt
│   └── HomeViewModel.kt
├── scan/
│   └── BarcodeScanScreen.kt
├── addedit/
│   ├── AddEditItemScreen.kt
│   └── AddEditItemViewModel.kt
├── detail/
│   ├── ItemDetailScreen.kt
│   └── ItemDetailViewModel.kt
└── settings/
    └── SettingsScreen.kt

Plan 대비 차이점:

✅ 모든 화면 기본 구조 완성

✅ Material 3 디자인 적용 (Plan 요구사항)

⚠️ Icons 라이브러리 미사용 (Text로 대체, 추후 추가 예정)

⚠️ 검색/필터 UI는 다음 단계 예정

⚠️ 하단 배너 광고는 추후 구현 예정

🚧 진행 중 / 예정 단계

4단계: 상세 기능 구현 🔄 0% (다음 단계)

Plan 요구사항:

등록 폼 완전 구현
- 상품명 입력 (필수)
- 날짜 선택 (DatePicker)
- 날짜 타입 선택 (유통기한 / 내가 정한 기한)
- 보관 타입 선택 (실온/냉장/냉동)
- 메모 입력 (선택)
- 사진 첨부 (선택)
- 바코드 자동 채우기

상세 화면 완성
- 모든 정보 표시
- 소비/폐기 처리 로직
- Undo 스낵바 (Plan 권장사항)

검색/필터 기능
- 상품명 검색
- 보관 타입 필터
- 상태 필터 (정상/임박/만료)

예상 파일:

ui/addedit/
├── components/
│   ├── DateTypeSelector.kt
│   ├── StorageTypeSelector.kt
│   └── DatePickerDialog.kt

5단계: 바코드 스캔 구현 🔄 0% (예정)

Plan 요구사항:

CameraX 통합

ML Kit Barcode Scanner

권한 처리 (CAMERA)

스캔 성공/실패 처리

토치, 사진 모드 전환

저조도/흔들림 대응

필요 라이브러리:

// build.gradle.kts 추가 예정
implementation("androidx.camera:camera-camera2")
implementation("androidx.camera:camera-lifecycle")
implementation("androidx.camera:camera-view")
implementation("com.google.mlkit:barcode-scanning")

6단계: 알림 시스템 (WorkManager) 🔄 0% (예정)

Plan 요구사항:

ExpiryNotificationWorker 구현

RescheduleExpiryWorker 구현

D-3 (20:00) 알림

D-0 (20:00) 알림

UniqueWork 관리 (expiry_${itemId}_D3/D0)

Tag 관리 (expiry_notifications)

소비/폐기 시 알림 취소

설정 변경 시 재스케줄링

예상 파일 구조:

worker/
├── ExpiryNotificationWorker.kt
├── RescheduleExpiryWorker.kt
└── WorkerKeys.kt

notification/
├── NotificationHelper.kt
└── NotificationChannels.kt

7단계: 광고 통합 🔄 0% (예정)

Plan 요구사항:

Google AdMob 통합

홈 화면 하단 배너 광고 1개

광고 로딩 실패 처리

📊 전체 진행률

단계	항목	진행률	상태
1	프로젝트 설정 및 테마	100%	✅ 완료
2	데이터 레이어 (Room)	100%	✅ 완료
3	UI 기본 구조	85%	✅ 완료
4	상세 기능 구현	0%	🔄 예정
5	바코드 스캔	0%	🔄 예정
6	알림 시스템	0%	🔄 예정
7	광고 통합	0%	🔄 예정
전체	MVP 완성도	~40%	🚀 진행 중

🏗️ 현재 아키텍처

Clean Architecture 구조

app/
├── data/                    # 데이터 레이어
│   ├── local/              # Room Database
│   │   ├── entity/         # DB 엔티티
│   │   ├── dao/            # DB 접근
│   │   ├── converter/      # 타입 변환
│   │   └── db/             # Database 클래스
│   └── repository/         # Repository 패턴
│
├── domain/                  # 도메인 레이어
│   └── model/              # 비즈니스 모델 (Enum)
│
├── ui/                      # Presentation 레이어
│   ├── home/               # 홈 화면
│   ├── scan/               # 스캔 화면
│   ├── addedit/            # 등록/수정 화면
│   ├── detail/             # 상세 화면
│   ├── settings/           # 설정 화면
│   └── theme/              # Material 3 테마
│
├── navigation/              # 네비게이션
│
├── di/                      # Dependency Injection
│
└── worker/                  # Background 작업 (예정)

의존성 그래프

UI Layer (Compose + ViewModel)
    ↓
Repository Layer
    ↓
Data Source Layer (Room DAO)
    ↓
Database (Room)

🔧 기술적 특징

1. LocalDate / Instant 사용

Java 8+ Date/Time API 활용

Room TypeConverter로 자동 변환

타임존 안전성 확보 (Plan 요구사항)

2. Flow 기반 반응형 프로그래밍

// 실시간 데이터 업데이트
fun getAllActiveItems(): Flow<List<ItemEntity>>

3. Material 3 디자인 시스템

Dynamic Color 지원 (Android 12+)

Light/Dark 테마 완벽 지원

Noto Sans KR 폰트 적용

4. Hilt 의존성 주입

Singleton Repository

ViewModel 자동 주입

Database 모듈 분리

5. Navigation Component

Type-safe navigation

딥링크 지원

SavedStateHandle 파라미터 전달

📝 Plan.pptx 준수 사항

✅ 완벽히 준수한 항목

데이터 설계
- ✅ targetDate 하나로 통일 (dateType으로 구분)
- ✅ 인덱스 (status, targetDate, barcode)
- ✅ TypeConverter 정확히 구현
- ✅ BarcodeCacheEntity 정책대로 구현

DAO 설계
- ✅ Plan의 모든 쿼리 구현
- ✅ 표시 상태 계산 로직 (targetDate 기준)
- ✅ Flow 기반 반응형

Repository 책임
- ✅ DB 변경 후 스케줄 연동 (TODO 준비)
- ✅ 바코드 캐시 upsert

UI/플로우
- ✅ 5개 화면 모두 생성
- ✅ 홈 임박 섹션 구현
- ✅ D-day 계산 및 표시

⚠️ 부분 구현 / 예정 항목

바코드 스캔
- ⚠️ 기본 UI만 완성
- 🔄 CameraX + ML Kit 구현 예정

등록 폼
- ⚠️ 기본 레이아웃만 완성
- 🔄 모든 필드 구현 예정

알림 시스템
- ⚠️ Repository에 TODO 마커만
- 🔄 WorkManager 구현 예정

광고
- 🔄 AdMob 통합 예정

❌ Plan과 다른 점

Icons 사용
- Plan: Material Icons 사용 예상
- 실제: Text로 임시 대체 (빌드 속도 우선)
- 계획: 추후 material-icons-extended 추가

OCR 유통기한 인식
- Plan: Won't for v1 (명시적 제외)
- 실제: 구현 안 함 (Plan 준수)

커뮤니티 기능
- Plan: Won't for v1 (명시적 제외)
- 실제: 구현 안 함 (Plan 준수)

🐛 알려진 이슈 및 해결

1. Kotlin/Hilt 버전 호환성

문제: Kotlin 2.3.2 + KSP 호환 이슈

해결: Kotlin 2.3.10, KSP 2.3.2로 조정

2. 파일 인코딩 문제

문제: PowerShell 정규식으로 한글 깨짐

해결: 파일별 수동 수정

3. Material Icons 의존성

문제: icons 라이브러리 누락

해결: Text로 임시 대체 (빌드 우선)

📚 다음 작업 우선순위

즉시 착수 (4단계)

✅ 등록 폼 완전 구현
- DatePicker 통합
- 모든 필드 검증
- 저장 로직 완성

✅ 상세 화면 완성
- 소비/폐기 처리
- Undo 기능

✅ 검색/필터 UI

중요 (5단계)

🔄 바코드 스캔
- CameraX 설정
- ML Kit 통합
- 권한 처리

핵심 기능 (6단계)

🔄 알림 시스템
- WorkManager 구현
- D-3, D-0 알림
- 스케줄 관리

부가 기능 (7단계)

🔄 광고 통합

🔄 Material Icons 추가

🔄 최종 테스트 및 최적화

🎯 v1.0 릴리즈 체크리스트

프로젝트 설정

Room Database

Navigation 설정

홈 화면

등록 폼 (진행 중)

바코드 스캔

알림 시스템

최종 테스트

릴리즈 빌드

예상 완성도: 40% → 100% (약 60% 남음)

📌 참고 문서

documents/plan.pptx - 전체 기획안

documents/README.md - Material Theme 가이드

gradle/libs.versions.toml - 의존성 버전 관리

마지막 업데이트: 2026-02-17
작성자: AI Assistant
프로젝트 상태: 🚀 활발히 개발 중

#스하리1000명프로젝트,
¿Perdido en Corea? Incluso si no hablas coreano, esta aplicación te ayuda a moverte fácilmente.
Simplemente hable su idioma: traduce, busca y muestra resultados en su idioma.
¡Genial para viajeros! Admite más de 10 idiomas, incluidos inglés, japonés, chino, vietnamita y más.
¡Pruébalo ahora!
https://play.google.com/store/apps/details?id=com.billcoreatech.opdgang1127

2026/05/08

오늘의 이야기

🔍 프로젝트 진단 | Health501 아키텍처 & 코드 품질 개선 로드맵

📊 개요 (Executive Summary)

작업 일자: 2025-12-15

작업 유형: 프로젝트 전반 분석 및 개선 방안 도출

목적: Health501 프로젝트의 현재 상태를 진단하고, 유지보수성·확장성·안정성 향상을 위한 구체적 개선 로드맵 수립

핵심 발견: 아키텍처 문서(ARCHITECTURE.md)와 실제 코드 구조 간 불일치, 테스트 커버리지 부족, 보안 취약점 존재

🎯 핵심 목표: 문서화된 원칙을 실제 코드에 반영하여 장기적으로 확장 가능한 프로젝트 기반 마련

🏗️ 1. 아키텍처 레이어 분리 (최우선 과제)

현재 상태 분석

문제점:

ARCHITECTURE.md에는 명확한 3계층 구조(UI → Domain → Data)가 정의되어 있으나, 실제 코드에는 domain 레이어가 존재하지 않음

ViewModel이 직접 Manager 클래스를 호출하여 비즈니스 로직이 UI 레이어에 혼재

데이터 레이어와 UI 레이어가 강결합되어 테스트 및 변경이 어려움

현재 구조:

app/src/main/java/com/billcoreatech/health501/
├── viewmodels/
│   ├── HealthConnectViewModel.kt  (← HealthConnectManager 직접 호출)
│   └── CoupangViewModel.kt
├── data/
│   ├── HealthConnectManager.kt
│   └── HealthConnectUtil.kt
└── (domain 레이어 부재)

개선 방안

목표 구조:

app/src/main/java/com/billcoreatech/health501/
├── presentation/  (기존 presentaion 오타도 수정)
│   ├── viewmodels/
│   └── screens/
├── domain/  ← 새로 생성
│   ├── model/
│   │   ├── Result.kt (sealed interface)
│   │   ├── StepData.kt
│   │   └── ExerciseSessionData.kt
│   └── usecase/
│       ├── GetTodayStepsUseCase.kt
│       ├── GetExerciseSessionsUseCase.kt
│       ├── SyncWearDataUseCase.kt
│       └── GetWeeklyStatsUseCase.kt
└── data/
    ├── repository/  ← 새로 생성
    │   ├── HealthDataRepository.kt
    │   ├── HealthDataRepositoryImpl.kt
    │   └── WearSyncRepository.kt
    └── datasource/
        ├── HealthConnectDataSource.kt (기존 Manager 래핑)
        └── WearDataSource.kt

구현 예시 (UseCase 패턴)

// domain/usecase/GetTodayStepsUseCase.kt
class GetTodayStepsUseCase @Inject constructor(
    private val healthRepository: HealthDataRepository
) {
    suspend operator fun invoke(): Result<Long> = withContext(Dispatchers.IO) {
        try {
            val steps = healthRepository.getTodaySteps()
            Result.Success(steps)
        } catch (e: Exception) {
            Result.Error(e.message ?: "Unknown error")
        }
    }
}

// domain/model/Result.kt
sealed interface Result<out T> {
    data class Success<T>(val data: T) : Result<T>
    data class Error(val message: String) : Result<Nothing>
    object Loading : Result<Nothing>
}

// data/repository/HealthDataRepositoryImpl.kt
class HealthDataRepositoryImpl @Inject constructor(
    private val healthConnectDataSource: HealthConnectDataSource
) : HealthDataRepository {
    override suspend fun getTodaySteps(): Long {
        return healthConnectDataSource.readTodaySteps()
    }
}

// ViewModel에서 사용
@HiltViewModel
class HealthConnectViewModel @Inject constructor(
    private val getTodayStepsUseCase: GetTodayStepsUseCase
) : ViewModel() {

    val stepsState: StateFlow<Result<Long>> = flow {
        emit(Result.Loading)
        emit(getTodayStepsUseCase())
    }.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), Result.Loading)
}

우선순위: 긴급 (Phase 1)

예상 소요 시간: 1-2주

기대 효과:

비즈니스 로직과 UI 로직의 명확한 분리

테스트 용이성 대폭 향상 (UseCase 단위 테스트 가능)

코드 재사용성 증가 (Wear 앱과 공유 가능)

🧪 2. 테스트 커버리지 강화

현재 상태

문제점:

전체 테스트 파일: 3개 (AiAutoSelectorTest.kt, AiWeightsLoadTest.kt, ExampleUnitTest.kt)

핵심 비즈니스 로직(ViewModel, Manager, Sync)에 대한 테스트 전무

TESTING.md에 domain ≥80%, data ≥70% 목표가 명시되어 있으나 실제 커버리지는 추정 10% 미만

개선 계획

레이어	테스트 대상	테스트 유형	목표 커버리지
Domain	UseCase 클래스들	Unit Test (MockK)	80%+
Data	Repository, DataSource	Unit Test + Integration Test	70%+
ViewModel	상태 관리, 비즈니스 흐름	Unit Test (Turbine for Flow)	60%+
UI	핵심 화면 플로우	Compose UI Test	50%+

필수 테스트 파일 목록

app/src/test/java/com/billcoreatech/health501/
├── domain/
│   └── usecase/
│       ├── GetTodayStepsUseCaseTest.kt
│       ├── GetExerciseSessionsUseCaseTest.kt
│       └── SyncWearDataUseCaseTest.kt
├── data/
│   ├── repository/
│   │   ├── HealthDataRepositoryTest.kt
│   │   └── WearSyncRepositoryTest.kt
│   └── datasource/
│       └── HealthConnectDataSourceTest.kt
├── viewmodels/
│   ├── HealthConnectViewModelTest.kt
│   └── CoupangViewModelTest.kt
└── testutil/
    ├── FakeHealthConnectClient.kt
    ├── FakeWearDataSyncManager.kt
    └── TestDispatchers.kt

테스트 도구 추가 (build.gradle.kts)

dependencies {
    // 기존 의존성...

    // 테스트 라이브러리 추가
    testImplementation("io.mockk:mockk:1.13.9")
    testImplementation("app.cash.turbine:turbine:1.0.0")
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0")
    testImplementation("androidx.arch.core:core-testing:2.2.0")

    // Compose UI 테스트
    androidTestImplementation("androidx.compose.ui:ui-test-junit4")
    debugImplementation("androidx.compose.ui:ui-test-manifest")
}

우선순위: 긴급 (Phase 2)

예상 소요 시간: 2-3주

🔒 3. 보안 강화 (API 키 관리)

취약점 분석

현재 코드 (app/build.gradle.kts):

// 48-49행: 심각한 보안 문제
resValue("string", "cupang_access_key", cupangAccessKey)
resValue("string", "cupang_secret_key", cupangSecretKey)

// 53행: 디버그 로그로 키 길이 노출
println("[CoupangKeys@Gradle] access.len=${cupangAccessKey.length}, secret.len=${cupangSecretKey.length}")

문제점:

API 키가 res/values/strings.xml에 평문으로 포함되어 APK 디컴파일 시 즉시 노출

ProGuard/R8 난독화로도 리소스 파일은 보호 불가

SECURITY.md에는 Keystore 기반 암호화 권장하나 미구현

개선 방안 (3단계)

Step 1: BuildConfig로 이동 (즉시 적용 가능)

// app/build.gradle.kts
android {
    defaultConfig {
        // resValue 삭제하고 BuildConfig로 변경
        buildConfigField("String", "CUPANG_ACCESS_KEY", "\"${cupangAccessKey}\"")
        buildConfigField("String", "CUPANG_SECRET_KEY", "\"${cupangSecretKey}\"")
    }

    buildFeatures {
        buildConfig = true  // BuildConfig 활성화
    }
}

// 사용 방법
// Before: context.getString(R.string.cupang_access_key)
// After:  BuildConfig.CUPANG_ACCESS_KEY

Step 2: ProGuard 규칙 강화

# proguard-rules.pro
-keepclassmembers class com.billcoreatech.health501.BuildConfig {
    !public <fields>;
}

# 난독화 강화
-repackageclasses 'o'
-allowaccessmodification

Step 3: NDK 또는 서버 프록시 (장기 과제)

NDK 방식: C++ 네이티브 레이어에서 키 관리 (역공학 난이도 ↑)

서버 프록시 방식 (권장): 앱은 자체 서버를 호출하고, 서버가 Coupang API를 호출하여 키 노출 완전 차단

즉시 적용 사항

// 디버그 로그 제거
// println("[CoupangKeys@Gradle] access.len=${cupangAccessKey.length}...") ← 삭제

// 또는 릴리스 빌드에서만 제거
if (gradle.startParameter.taskNames.any { it.contains("Debug", ignoreCase = true) }) {
    println("[Dev] Coupang keys loaded (debug only)")
}

우선순위: 긴급 (Phase 1)

예상 소요 시간: 1-2일

🚀 4. 상태 관리 개선

현재 문제점

HealthConnectViewModel.kt 분석:

// 일관성 없는 상태 관리 패턴 혼용
var uiState: UiState by mutableStateOf(UiState.Uninitialized)  // Compose State
val _stepsTotal = MutableStateFlow(0L)  // StateFlow
val stepsTotal: StateFlow<Long> = _stepsTotal
var hasPermission = mutableStateOf(false)  // 또 다른 mutableStateOf

// 총 20개 이상의 개별 상태 프로퍼티가 산재

개선 방안: 단일 UiState 패턴

// 통합된 상태 클래스
data class HealthUiState(
    val isLoading: Boolean = false,
    val stepsToday: Long = 0L,
    val sessions: List<ExerciseSession> = emptyList(),
    val sessionMetrics: ExerciseSessionData = ExerciseSessionData(""),
    val bucketData: List<BucketData> = emptyList(),
    val permissionsGranted: Boolean = false,
    val backgroundReadAvailable: Boolean = false,
    val error: String? = null,
    val currentDateTime: ZonedDateTime = ZonedDateTime.now()
)

// ViewModel
@HiltViewModel
class HealthConnectViewModel @Inject constructor(
    private val getTodayStepsUseCase: GetTodayStepsUseCase,
    private val getExerciseSessionsUseCase: GetExerciseSessionsUseCase
) : ViewModel() {

    private val _uiState = MutableStateFlow(HealthUiState())
    val uiState: StateFlow<HealthUiState> = _uiState.asStateFlow()

    fun loadTodayData() {
        viewModelScope.launch {
            _uiState.update { it.copy(isLoading = true) }

            when (val result = getTodayStepsUseCase()) {
                is Result.Success -> {
                    _uiState.update {
                        it.copy(
                            stepsToday = result.data,
                            isLoading = false
                        )
                    }
                }
                is Result.Error -> {
                    _uiState.update {
                        it.copy(
                            error = result.message,
                            isLoading = false
                        )
                    }
                }
            }
        }
    }
}

// Compose UI에서 사용
@Composable
fun HealthScreen(viewModel: HealthConnectViewModel = hiltViewModel()) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    when {
        uiState.isLoading -> LoadingIndicator()
        uiState.error != null -> ErrorMessage(uiState.error!!)
        else -> StepsDisplay(uiState.stepsToday)
    }
}

장점:

단일 진실 공급원(Single Source of Truth)

Compose recomposition 최적화 (불필요한 재구성 최소화)

상태 변경 추적 용이 (디버깅 개선)

테스트 단순화

우선순위: 중요 (Phase 2)

예상 소요 시간: 3-5일

📦 5. 빌드 & 의존성 최적화

개선 사항

5.1 gradle.properties 최적화

# 빌드 속도 개선 설정 추가
org.gradle.caching=true
org.gradle.parallel=true
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g -XX:+HeapDumpOnOutOfMemoryError
kotlin.incremental=true
kotlin.incremental.usePreciseJavaTracking=true

# Configuration cache (Gradle 8.x)
org.gradle.configuration-cache=true
org.gradle.configuration-cache.problems=warn

5.2 libs.versions.toml 번들링

[bundles]
lifecycle = [
    "androidx-lifecycle-runtime",
    "androidx-lifecycle-viewmodel-compose",
    "androidx-lifecycle-runtime-compose"
]

compose = [
    "androidx-compose-ui",
    "androidx-compose-ui-graphics",
    "androidx-compose-ui-tooling-preview",
    "androidx-compose-material3"
]

ktor = [
    "ktor-client-core",
    "ktor-client-okhttp",
    "ktor-client-logging",
    "ktor-client-content-negotiation",
    "ktor-serialization-kotlinx-json"
]

# 사용
dependencies {
    implementation(libs.bundles.lifecycle)
    implementation(libs.bundles.compose)
    implementation(libs.bundles.ktor)
}

5.3 불필요한 의존성 검토

// app/build.gradle.kts
// ❓ 검토 필요
implementation(libs.services.fitness)  // Health Connect 사용 시 필요성 재평가
implementation(libs.dialog.core)       // Material3 Dialog로 대체 가능
implementation(libs.dialog.lifecycle)  // 상동

우선순위: 일반 (Phase 3)

🌐 6. 네트워크 레이어 개선

현재 상태

Ktor Client가 NetworkModule.kt에만 정의되어 있으며, 에러 핸들링·재시도·타임아웃 정책이 미흡합니다.

개선 구조

data/network/
├── KtorClientFactory.kt
├── NetworkErrorHandler.kt
├── ApiResponse.kt (sealed class)
├── interceptor/
│   ├── AuthInterceptor.kt
│   └── LoggingInterceptor.kt
└── service/
    └── CoupangApiService.kt

구현 예시

// data/network/ApiResponse.kt
sealed interface ApiResponse<out T> {
    data class Success<T>(val data: T) : ApiResponse<T>
    data class Error(val code: Int, val message: String) : ApiResponse<Nothing>
    object NetworkError : ApiResponse<Nothing>
    object Timeout : ApiResponse<Nothing>
}

// di/NetworkModule.kt (개선)
@Provides
@Singleton
fun provideHttpClient(): HttpClient = HttpClient(OkHttp) {
    install(ContentNegotiation) {
        json(Json {
            ignoreUnknownKeys = true
            isLenient = true
        })
    }

    install(Logging) {
        logger = Logger.ANDROID
        level = if (BuildConfig.DEBUG) LogLevel.BODY else LogLevel.NONE
    }

    install(HttpTimeout) {
        requestTimeoutMillis = 30_000
        connectTimeoutMillis = 15_000
        socketTimeoutMillis = 30_000
    }

    install(HttpRequestRetry) {
        retryOnServerErrors(maxRetries = 3)
        exponentialDelay()
    }

    defaultRequest {
        header("User-Agent", "Health501/${BuildConfig.VERSION_NAME}")
        header("Accept", "application/json")
    }
}

우선순위: 중요 (Phase 2)

🔧 7. 코드 품질 개선

즉시 수정 사항

7.1 패키지 오타 수정

현재: app/src/main/java/com/billcoreatech/health501/presentaion/
수정: app/src/main/java/com/billcoreatech/health501/presentation/

7.2 TODO 해결

// StepsStateListenerService.kt:26
// TODO: forward to a repository / shared flow if needed.

// 개선 방안: Repository 패턴 도입 시 함께 해결
class StepsStateListenerService : Service() {
    @Inject lateinit var stepsRepository: StepsRepository

    override fun onStepsChanged(steps: Long) {
        viewModelScope.launch {
            stepsRepository.updateSteps(steps)  // Repository로 전달
        }
    }
}

7.3 Extension Functions 정리

// util/Extensions.kt (새로 생성)
fun ZonedDateTime.toFormattedString(pattern: String = "yyyy-MM-dd HH:mm"): String =
    this.format(DateTimeFormatter.ofPattern(pattern))

fun Long.toStepString(): String = DecimalFormat("#,###").format(this)

fun Context.hasPermission(permission: String): Boolean =
    ContextCompat.checkSelfPermission(this, permission) == PackageManager.PERMISSION_GRANTED

우선순위: 긴급 (Phase 1 - 오타 수정만)

🤖 8. CI/CD 파이프라인 구축

GitHub Actions 워크플로우

# .github/workflows/ci.yml
name: CI Pipeline

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Cache Gradle packages
        uses: actions/cache@v3
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}

      - name: Grant execute permission for gradlew
        run: chmod +x gradlew

      - name: Run unit tests
        run: ./gradlew testDebugUnitTest --stacktrace

      - name: Run lint
        run: ./gradlew lintDebug

      - name: Upload test results
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: test-results
          path: app/build/reports/tests/

      - name: Upload lint results
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: lint-results
          path: app/build/reports/lint-results-debug.html

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Build debug APK
        run: ./gradlew assembleDebug

      - name: Upload APK
        uses: actions/upload-artifact@v3
        with:
          name: app-debug
          path: app/build/outputs/apk/debug/app-debug.apk

우선순위: 중요 (Phase 3)

📊 9. 우선순위별 로드맵

Phase	기간	작업 항목	우선순위	기대 효과
Phase 1 (즉시)	1주	✅ presentaion → presentation 수정 ✅ API 키 BuildConfig로 이동 ✅ 디버그 로그 민감정보 제거 ✅ gradle.properties 최적화	긴급	보안 취약점 해결 빌드 속도 향상
Phase 2 (단기)	2-3주	🏗️ Domain 레이어 구축 🏗️ Repository 패턴 도입 🏗️ UseCase 클래스 작성 🏗️ 상태 관리 통합 (단일 UiState)	긴급	아키텍처 정립 테스트 가능성 향상
Phase 3 (중기)	1개월	🧪 테스트 커버리지 70%+ 달성 🧪 Mock/Fake 구현 🌐 네트워크 에러 핸들링 강화 🤖 CI/CD 파이프라인 구축	중요	안정성 향상 자동화 구축
Phase 4 (장기)	2-3개월	📊 Firebase Analytics 통합 📊 Crashlytics 추가 🚀 성능 프로파일링 🚀 멀티모듈화 검토	일반	모니터링 확장성 확보

📈 10. 성과 측정 지표 (KPI)

측정 가능한 개선 목표

지표	현재	목표 (3개월 후)	측정 방법
테스트 커버리지	~10%	70%+	JaCoCo 리포트
빌드 시간 (Clean Build)	측정 필요	-30% 개선	Gradle Build Scan
Lint 경고	측정 필요	0건 (Critical)	./gradlew lint
코드 중복도	측정 필요	<5%	Detekt 정적 분석
평균 메서드 길이	측정 필요	<30 LOC	SonarQube

💭 회고 및 고찰

핵심 인사이트

문서 vs 실제 코드의 괴리: ARCHITECTURE.md, TESTING.md에 명시된 원칙들이 실제 구현되지 않은 상태. 이는 프로젝트 초기에 이상적 구조를 설계했으나, 실제 개발 과정에서 우선순위나 시간 제약으로 인해 단계적 구현이 이뤄지지 않았음을 시사

기술 부채의 누적: 초기에는 빠른 프로토타이핑을 위해 ViewModel에서 직접 Manager를 호출하는 방식을 택했으나, 이제 프로젝트가 성숙 단계에 접어들면서 리팩터링 필요성이 대두

보안에 대한 인식 부족: API 키를 string resource로 노출하는 것은 초보적 실수. 민감정보 관리에 대한 체계적 접근 필요

테스트 문화 부재: AI 관련 유틸만 테스트되고 핵심 비즈니스 로직은 테스트가 없다는 것은 개발 과정에서 테스트 우선 접근(TDD)이 적용되지 않았음을 의미

프로젝트의 강점

✅ 현대적 기술 스택 채택 (Compose, Hilt, Kotlin Coroutines, Flow)

✅ Version Catalog로 의존성 중앙 관리

✅ 명확한 문서화 (ARCHITECTURE.md, TESTING.md, SECURITY.md)

✅ AI 모델 자동 선택 유틸 등 독창적 기능 구현

✅ Phone + Wear OS 통합 프로젝트로 복잡도 관리

장기적 비전

이번 개선 로드맵을 통해 Health501은 다음과 같은 장기적 이점을 얻을 수 있습니다:

확장성: 새로운 기능 추가 시 명확한 레이어 구조로 인해 변경 영향 범위를 최소화

협업 효율성: 팀원이 추가되어도 일관된 패턴으로 인해 온보딩 시간 단축

유지보수성: 높은 테스트 커버리지로 리그레션 방지 및 안전한 리팩터링 가능

품질 보증: CI/CD를 통한 자동화된 검증으로 버그 조기 발견

📋 다음 단계 (Next Actions)

즉시 착수 가능한 작업 (오늘~이번 주)

presentaion → presentation 패키지 리네임

git mv app/src/main/java/com/billcoreatech/health501/presentaion \
       app/src/main/java/com/billcoreatech/health501/presentation

API 키 보안 강화
- app/build.gradle.kts 수정 (resValue → buildConfigField)
- CoupangViewModel.kt에서 사용 방식 변경
- 디버그 로그 제거

gradle.properties 최적화
- 캐싱, 병렬 빌드 활성화
- JVM 힙 메모리 증가

domain 패키지 구조 생성

mkdir -p app/src/main/java/com/billcoreatech/health501/domain/{model,usecase}
mkdir -p app/src/main/java/com/billcoreatech/health501/data/repository

Result.kt sealed interface 작성
- Success, Error, Loading 상태 정의
- 전체 프로젝트에서 일관되게 사용

주간 목표 설정 (Week 1-2)

[ ] Phase 1 모든 작업 완료

[ ] GetTodayStepsUseCase 구현 및 테스트 작성

[ ] HealthDataRepository 인터페이스 및 구현체 작성

[ ] HealthConnectViewModel 리팩터링 (UseCase 통합)

[ ] CI/CD 워크플로우 초안 작성

🎓 학습 자료 및 참고 문서

Android Architecture Guide (Official)

Testing Kotlin Flows

Compose UI Testing

Android Architecture Samples (GitHub)

Ktor Client Documentation

Detekt - Static Code Analysis

오늘의 이야기

Han Tarot 앱 개발 기획안 (수정버전)

작성일: 2026-03-21

1. 문서 목적

이 문서는 업로드된 기획/실행 문서를 바탕으로 Han Tarot 앱을 실제로 출시 가능한 수준의 MVP로 개발하기 위한 실행 계획을 정리한 문서다.

원문 문서에서 제시한 핵심 방향은 다음과 같다.

이 앱은 점술 중심이 아니라 자기 성찰과 마음 치유를 돕는 상담형 타로 앱이다.

기술 스택은 Android / Kotlin / Hilt / Room / Jetpack Compose를 기준으로 한다.

전체 사용자 흐름은 카드 뽑기 → 해석 → 상담 질문 → 기록 → 치유 메시지로 이어진다.

MVP 기준 핵심 기능은 랜덤 카드 추출, 1장/3장 스프레드, 해석 엔진, 저널링, 확언/명상 화면이다.

2. Han Tarot 제품 정의

2-1. 제품 한 줄 정의

Han Tarot는 한국 전통 미감의 타로 카드를 통해 사용자의 감정과 생각을 비추는 자기 성찰형 타로 상담 앱이다.

2-2. 제품 콘셉트

한국 전통풍 카드 일러스트와 한복, 금박, 먹·수채화 감성

예언보다 정서적 안정과 자기 이해에 집중하는 해석

상담형 질문과 저널 저장을 통해 기록 습관 형성

오프라인에서도 동작 가능한 개인용 힐링 앱

2-3. 핵심 가치

감정 탐색: 지금 내 마음이 어떤 상태인지 알아차리기

자기 성찰: 카드 해석을 통해 내 상황을 객관화하기

기록 습관: 짧은 문장이라도 남겨서 감정 변화를 추적하기

정서적 안정: 확언과 명상 문구로 세션을 부드럽게 마무리하기

3. 개발 범위 정의

3-1. MVP 범위

이번 1차 개발에서는 아래 범위만 완성해도 출시 가능한 MVP가 된다.

홈 화면

1장 / 3장 스프레드 선택

카드 셔플 및 카드 뽑기

카드 이미지 표시 및 해석 결과 화면

상담형 후속 질문 1~2개 제시

저널 저장 및 목록 조회

확언 / 명상 마무리 화면

설정(문구 톤, 앱 소개, 문의 링크 정도의 최소 구성)

3-2. 이번 MVP에서 제외할 항목

서버 연동

로그인 / 회원가입

AI API 호출

커뮤니티

카드 역방향 고도화 규칙

켈틱 크로스 등 고급 스프레드

다국어 지원

결제 / 구독

3-3. 전제 조건

이 문서는 아래 전제를 두고 작성했다.

개발자는 1인 또는 소규모 팀이다.

이미 제작한 카드 이미지는 앱 번들 리소스로 탑재 가능하다.

Android 앱은 Kotlin + Compose + Hilt + Room 기반으로 개발한다.

MVP는 로컬 데이터 기반으로 먼저 완성한다.

4. 권장 앱 구조

원문 문서의 Clean Architecture 방향은 그대로 유지하는 것이 좋다. 다만 실제 개발 속도를 위해 너무 과도한 추상화는 피한다.

4-1. 추천 모듈/패키지 구조

com.hantarot.app
├─ core
│  ├─ ui
│  ├─ designsystem
│  ├─ model
│  └─ util
├─ data
│  ├─ local
│  │  ├─ dao
│  │  ├─ entity
│  │  ├─ database
│  │  └─ seed
│  ├─ mapper
│  └─ repository
├─ domain
│  ├─ model
│  ├─ repository
│  └─ usecase
├─ feature
│  ├─ splash
│  ├─ home
│  ├─ spread
│  ├─ draw
│  ├─ reading
│  ├─ counseling
│  ├─ journal
│  ├─ meditation
│  └─ settings
├─ navigation
└─ di

4-2. 구조 운영 원칙

feature 단위로 화면과 ViewModel 묶기

공용 UI는 core/designsystem 으로 분리

Room Entity와 Domain Model은 분리

해석 로직은 domain/usecase, domain/model, TarotEngine 쪽에 집중

문구 템플릿은 하드코딩보다 JSON 또는 local seed 리소스로 관리

5. 화면 구성과 작업 순서

개발은 화면을 예쁘게 만드는 것보다 사용 흐름을 먼저 완성하는 순서로 진행하는 것이 가장 빠르다.

5-1. 화면 목록

Splash / Intro

HomeScreen

SpreadSelectBottomSheet

DrawCardScreen

ReadingScreen

CounselingScreen

JournalSaveDialog / JournalWriteSection

JournalListScreen

JournalDetailScreen

MeditationScreen

SettingsScreen

5-2. 실제 개발 순서 추천

1단계: 뼈대 완성

앱 테마, 컬러, 폰트, 공통 버튼/카드 UI 구성

Navigation 세팅

Hilt 세팅

Room DB 세팅

카드 seed 데이터 import

2단계: 핵심 사용자 흐름 완성

HomeScreen

Spread 선택

카드 셔플/선택

ReadingScreen

3단계: 상담과 기록 연결

CounselingScreen

Journal 저장

Journal 목록/상세

4단계: 감정 안정 마무리 흐름 추가

MeditationScreen

Affirmation 표시

세션 종료 UX

5단계: 품질 보완

애니메이션

빈 상태 처리

예외 처리

문구 다듬기

6. 실행 가능한 개발 기간

원문 문서는 8주 일정을 예시로 제시하고 있다. 실제로도 이 일정은 무리가 없고 현실적이다. 다만 1인 개발 기준으로는 7~8주, 디자인 수정과 문구 다듬기까지 포함하면 8주를 권장한다.

6-1. 최종 추천 일정

최소 구현: 5주

안정적인 MVP: 8주

출시 직전 polish 포함: 9주

이 문서에서는 8주 MVP 일정을 기준으로 제안한다.

7. 8주 개발 로드맵

Week 1 — 기획 확정 및 리소스 정리

목표

앱의 정체성과 MVP 범위 확정

카드 이미지 및 해석 데이터 정리

홈 화면과 핵심 플로우 목업 확정

작업

앱명, 아이콘, 컬러 시스템 확정

카드 리소스 파일명 규칙 통일

카드 데이터 구조 정의

홈/드로우/리딩/저널 플로우 확정

문구 톤 가이드 작성

산출물

화면 플로우 다이어그램

카드 메타 데이터 시트

UI 목업 초안

개발 체크리스트

Week 2 — 프로젝트 초기 세팅

목표

개발 가능한 앱 골격 완성

작업

Android Studio 프로젝트 구성

Hilt 설정

Room Database 생성

Navigation 설정

Design System 기초 컴포넌트 작성

Seed 데이터 로딩 구조 작성

산출물

앱 실행 가능한 기본 프로젝트

카드/저널 DB 동작 확인

공통 버튼, 카드, 다이얼로그 UI 컴포넌트

Week 3 — 홈 화면 및 카드 뽑기 기능

목표

사용자가 실제로 카드를 뽑을 수 있게 만들기

작업

Splash / HomeScreen 구현

SpreadSelectBottomSheet 구현

DrawCardScreen 구현

1장 / 3장 스프레드 로직 구현

셔플 애니메이션 간단 구현

산출물

홈에서 카드 뽑기까지 이동 완료

선택된 카드 ID 전달 완료

Week 4 — 해석 화면 및 해석 엔진 연결

목표

카드 결과를 사용자가 읽을 수 있도록 만들기

작업

ReadingScreen 구현

ReadingUiState 설계

간단한 해석 엔진 구현

카드 키워드, 요약 문장, 확언 생성

1장 / 3장 별 표시 방식 정리

산출물

카드 뽑기 후 해석 화면 표시

질문 기반 해석 결과 출력

Week 5 — 상담형 질문 흐름 구현

목표

타로 앱에서 상담형 경험이 느껴지도록 만들기

작업

CounselingScreen 구현

후속 질문 생성 규칙 추가

사용자 입력창 구성

세션별 입력 임시 상태 저장

다음 질문/건너뛰기 흐름 구현

산출물

읽기 → 입력 → 저장 전 단계까지 자연스럽게 연결

Week 6 — 저널 저장/조회 + 명상 화면

목표

사용자의 기록과 마무리 경험까지 완성

작업

JournalEntity 저장 구현

JournalListScreen, JournalDetailScreen 구현

MeditationScreen 구현

감정 태그 저장

확언 카드/명상 문구 마무리 구성

산출물

완전한 1회 세션 종료 플로우 완성

이전 기록 조회 가능

Week 7 — 디자인 polish 및 QA

목표

출시 가능한 수준의 완성도 확보

작업

애니메이션 보완

홈 화면 문구 튜닝

버튼 레이블, 빈 상태, 오류 상태 문구 정리

TalkBack/접근성 최소 점검

성능 점검

산출물

앱 전반 UX 개선

버그 리스트와 수정본

Week 8 — MVP 배포 준비

목표

내부 테스트 또는 비공개 베타 배포

작업

아이콘/스플래시/스크린샷 정리

앱 설명문 초안 작성

versionCode / versionName 정리

Firebase Crashlytics / Analytics 선택 적용

비공개 테스트 배포

산출물

베타 APK/AAB

테스트 체크리스트

다음 버전 백로그

8. 작업 우선순위

8-1. Must Have

홈 화면

1장 / 3장 뽑기

해석 결과

상담 질문 1세트

저널 저장/조회

명상/확언 화면

8-2. Should Have

카드 뒤집기 애니메이션

최근 기록 미리보기

감정 태그

홈 화면 오늘의 질문 추천

8-3. Nice to Have

역방향 카드 별도 연출

사운드 효과

배경 음악

다국어 지원

AI 맞춤 상담

9. 초기 화면 구성 기획

초기 화면은 사용자가 앱의 정체성을 3초 안에 이해하게 만들어야 한다.

핵심은 다음 네 가지다.

앱 이름과 정체성 전달

오늘의 질문으로 진입 유도

바로 카드 뽑기 시작 버튼 제공

최근 기록이나 빠른 진입 포인트 제공

9-1. 첫 진입 구조

Splash
→ HomeScreen
→ [오늘의 질문 선택]
→ [1장 / 3장 선택]
→ DrawCardScreen

9-2. 홈 화면에 반드시 들어가야 할 요소

상단 브랜드 영역

한 줄 설명

오늘의 질문 카드

주 액션 버튼

보조 메뉴 버튼 3개

최근 기록 1~2개 미리보기

10. HomeScreen 목업

10-1. 와이어프레임 목업

┌─────────────────────────────────────┐
│ [앱 아이콘] Han Tarot                │
│ Korean Reflection Tarot             │
│ 예언이 아닌, 마음을 비추는 거울       │
├─────────────────────────────────────┤
│ [Hero Card / 오늘의 질문]            │
│ 오늘 당신이 가장 먼저 돌봐야 할       │
│ 감정은 무엇인가요?                   │
│                                     │
│ [오늘의 카드 시작하기]               │
├─────────────────────────────────────┤
│ [메뉴 버튼 1] Daily Tarot           │
│ 오늘의 카드 한 장을 뽑아보세요        │
├─────────────────────────────────────┤
│ [메뉴 버튼 2] 3 Card Spread         │
│ 과거 · 현재 · 미래를 살펴보세요      │
├─────────────────────────────────────┤
│ [메뉴 버튼 3] Journal               │
│ 지난 기록과 감정의 흐름을 확인하세요  │
├─────────────────────────────────────┤
│ [메뉴 버튼 4] Tarot Reading          │
│  타로 이미지의 생성 프롬프트를 확인하세요  │
├─────────────────────────────────────┤
│ 최근 기록                            │
│ - 3월 14일 / 감정 태그: 불안          │
│ - 3월 12일 / 감정 태그: 회복          │
└─────────────────────────────────────┘

10-2. 영역별 배치 가이드

A. 상단 브랜드 영역

위치: 상단 SafeArea 안쪽, 좌우 24dp

구성:
- 좌측 또는 중앙: 앱명 Han Tarot
- 보조 문구: Korean Reflection Tarot
- 서브 카피: 예언이 아닌, 마음을 비추는 거울

배경: 다크 네이비 또는 다크 버건디

포인트: 골드 텍스트/장식선

B. Hero Question Card

위치: 브랜드 영역 바로 아래

역할: 사용자가 가장 먼저 읽는 문구

버튼: 오늘의 카드 시작하기

스타일: 큰 카드, 부드러운 라운드, 약한 금박 테두리

C. 메뉴 영역

위치: Hero 아래 세로 스택

추천 메뉴:
- Daily Tarot
- 3 Card Spread
- Journal

컴포넌트: HanTarotMenuButton

D. 최근 기록 영역

위치: 화면 하단

최근 세션 1~2건만 노출

전체 보기 버튼은 우측 상단 작게 배치

11. 초기 화면 문구 제안

11-1. 앱 상단 카피

후보 A

Han Tarot

Korean Reflection Tarot

예언이 아닌, 마음을 비추는 거울

후보 B

Han Tarot

A gentle tarot for reflection

오늘의 감정을 카드로 마주해보세요

후보 C

Han Tarot

Korean Mystic Reflection

당신의 마음을 천천히 읽어보는 시간

11-2. 오늘의 질문 카드 문구

11-3. 버튼 문구

메인 CTA

오늘의 카드 시작하기

지금 카드 뽑기

오늘의 질문으로 시작하기

보조 버튼

Daily Tarot

3 Card Spread

Journal

지난 기록 보기

11-4. 빈 상태 문구

최근 기록 없음

아직 남겨진 기록이 없어요.

오늘의 첫 카드를 뽑고 마음의 기록을 시작해보세요.

12. 디자인 시스템 초안

12-1. 컬러

Background: #120D18

Surface: #1E1623

Gold Primary: #D4AF37

Gold Light: #FFE7A3

Ivory Text: #F6F0E8

Sub Text: #D8CFC3

Accent Red: #8C2F39

12-2. 타이포그래피 방향

제목: 고전적 느낌의 serif 계열 또는 display 계열

본문: 읽기 쉬운 sans-serif

앱 내부 실제 구현은 Android 기본 폰트로 시작하고, 추후 커스텀 폰트 적용

12-3. 공통 컴포넌트

HanTarotPrimaryButton

HanTarotMenuButton

HanTarotQuestionCard

TarotCardBack

TarotCardFront

AffirmationCard

EmotionChip

13. 데이터 설계 제안

원문 문서의 CardEntity, JournalEntity 방향은 MVP에 적합하다. 실제 앱에서는 아래 정도만 먼저 가져가면 충분하다.

13-1. CardEntity

data class CardEntity(
    val id: Int,
    val nameKo: String,
    val nameEn: String,
    val arcanaType: String,
    val suit: String?,
    val number: Int?,
    val imageAsset: String,
    val uprightMeaning: String,
    val reversedMeaning: String,
    val affirmation: String,
    val meditationMessage: String,
    val keywords: String
)

13-2. JournalEntity

data class JournalEntity(
    val id: Long,
    val spreadType: String,
    val userQuestion: String,
    val selectedCardIds: String,
    val interpretationSummary: String,
    val counselingMessage: String,
    val userReflection: String,
    val emotionTag: String?,
    val createdAt: Long
)

13-3. 추가 권장 필드

JournalEntity 에 아래 필드는 있으면 좋다.

affirmationShown: Boolean

sessionDurationSec: Int?

spreadTitle: String?

단, MVP에서는 없어도 된다.

14. 해석 엔진 구현 전략

초기 MVP에서는 AI API 없이도 충분히 구현 가능하다.

14-1. 규칙 기반 해석 엔진

입력:

사용자 질문

카드 목록

카드 키워드

스프레드 타입

출력:

해석 요약 2~4문장

후속 질문 1~2개

확언 1개

명상 문구 1개

14-2. 구현 순서

카드별 기본 키워드 정리

질문 카테고리 분류
- 감정
- 관계
- 진로
- 회복

공통 키워드 상위 3개 추출

템플릿 문장 조합

후속 질문 생성

14-3. MVP 품질 기준

해석은 절대 단정적이지 않다.

불안, 공포, 운명 확정 표현을 피한다.

자기 관찰형 문장을 사용한다.

마지막 문장은 부드러운 행동 제안으로 끝낸다.

예:

“지금의 당신은 답을 급하게 찾기보다 자신의 감정을 차분히 들여다볼 필요가 있어 보입니다.”

“오늘의 카드는 해결보다 이해가 먼저라는 메시지를 전합니다.”

15. 개발 리스크와 대응

15-1. 리스크

카드 이미지 리소스 관리가 복잡해질 수 있음

화면 수가 늘어나며 상태 관리가 꼬일 수 있음

해석 문구가 점술처럼 보일 위험이 있음

디자인에 시간을 너무 많이 쓰면 개발이 늦어짐

15-2. 대응

이미지 네이밍 규칙 고정

화면별 UiState, UiEvent 분리

문구 가이드 별도 문서화

3주차 전까지는 “동작 우선, 미감 후순위” 원칙 유지

16. 출시 전 체크리스트

기능

홈에서 1장 / 3장 진입 가능

카드 셔플 및 선택 정상 동작

해석 결과 정상 출력

상담 질문 입력 가능

저널 저장 및 목록 조회 가능

명상/확언 화면 정상 노출

UX

첫 진입 2초 내

빈 상태 문구 있음

네트워크 없어도 동작

버튼 용어 통일

오탈자 검수 완료

배포

앱 아이콘 적용

스플래시 적용

버전명 설정

테스트용 스크린샷 준비

17. 최종 제안

Han Tarot는 일반적인 타로 앱보다 브랜드 미감과 문구 품질이 훨씬 중요하다. 이미 카드 일러스트가 강력한 자산이므로, MVP에서는 기능을 욕심내기보다 아래 세 가지에 집중하는 것이 가장 효과적이다.

홈 → 카드 뽑기 → 해석 → 기록 흐름을 막힘 없이 완성하기

공감형 문구 톤을 일정하게 유지하기

한국 전통 미감을 일관된 UI로 보여주기

따라서 최적의 실행 전략은 다음과 같다.

8주 MVP 일정으로 간다

1장/3장 스프레드만 먼저 완성한다

로컬 기반 규칙형 해석 엔진으로 시작한다

홈 화면 카피와 디자인 완성도를 높인다

18. 바로 다음 액션

개발 시작 직전에 바로 해야 할 일은 아래 순서가 가장 좋다.

카드 데이터 CSV 또는 JSON 정리

HomeScreen 확정 목업 제작

Design System 컴포넌트 3종 제작
- PrimaryButton
- MenuButton
- QuestionCard

Room + SeedData 세팅

Draw → Reading 플로우 구현 시작

부록 A. HomeScreen Compose 초안 구조

Column(
    modifier = Modifier
        .fillMaxSize()
        .background(Color(0xFF120D18))
        .padding(20.dp)
) {
    BrandHeader()
    Spacer(Modifier.height(20.dp))
    TodayQuestionHeroCard()
    Spacer(Modifier.height(16.dp))
    HanTarotMenuButton(title = "Daily Tarot", ...)
    Spacer(Modifier.height(12.dp))
    HanTarotMenuButton(title = "3 Card Spread", ...)
    Spacer(Modifier.height(12.dp))
    HanTarotMenuButton(title = "Journal", ...)
    Spacer(Modifier.height(20.dp))
    RecentJournalSection()
}

부록 B. 추천 홈 화면 문구 조합

조합안 1

Han Tarot

Korean Reflection Tarot

예언이 아닌, 마음을 비추는 거울

오늘의 카드 시작하기

조합안 2

Han Tarot

A gentle tarot for reflection

오늘 당신이 가장 먼저 돌봐야 할 감정은 무엇인가요?

지금 카드 뽑기

조합안 3

Han Tarot

Korean Mystic Reflection

당신의 마음을 천천히 읽어보는 시간

오늘의 질문으로 시작하기

오늘의 이야기

#billcorea #운동동아리관리앱
🏸 Schneedle, eine unverzichtbare App für Badmintonvereine!
👉 Matchplay – Punkte aufzeichnen und Gegner finden 🎉
Perfekt für überall, alleine, mit Freunden oder im Club! 🤝
Wenn Sie Badminton mögen, probieren Sie es unbedingt aus

Zur App gehen 👉 https://play.google.com/store/apps/details?id=com.billcorea.matchplay

오늘의 이야기

In-App Update 기능 구현 완료 보고서

📋 개요

Google Play In-App Update API (v2.1.0)를 이용하여 DayCnt415 앱에 인앱 업데이트 기능을 추가했습니다.

구현 날짜: 2026-03-10
상태: ✅ 완료 및 테스트 가능

🎯 기능 설명

1. 두 가지 업데이트 모드 지원

✅ IMMEDIATE 모드 (강제 업데이트)

언제 사용: 중요한 보안 업데이트나 필수 기능 업데이트

사용자 경험: 스킵 불가능, 뒤로가기 버튼 비활성화

트리거 조건: 우선순위 ≥ 4 또는 버전 차이 > 5

UI: 설치 진행률 표시, 중단 불가

✅ FLEXIBLE 모드 (선택적 업데이트)

언제 사용: 일반 기능 개선사항 또는 버그 픽스

사용자 경험: 나중에, 지금 업데이트 버튼 제공

트리거 조건: 모든 업데이트 사용 가능 (우선순위 < 4)

UI: 다운로드 진행률 표시, 유연한 설치 옵션

🏗️ 아키텍처

레이어 구조

AppUpdateProvider (Compose Root)
    ↓
UpdateViewModel (상태 관리)
    ↓
AppUpdateService (비즈니스 로직)
    ↓
Google Play Core Library (네이티브 API)

컴포넌트 설명

컴포넌트	파일경로	책임
AppUpdateService	`domain/service/AppUpdateService.kt`	Play Core API 래핑, 라이프사이클 관리, 상태 모니터링
UpdateViewModel	`presentation/viewmodel/UpdateViewModel.kt`	StateFlow 기반 상태 관리, UI 로직
AppUpdateDialog	`presentation/ui/components/AppUpdateDialog.kt`	Compose UI (IMMEDIATE/FLEXIBLE 모드)
UpdateAvailableBanner	`presentation/ui/components/AppUpdateDialog.kt`	저우선순위 업데이트 배너
AppUpdateProvider	`presentation/ui/screens/AppUpdateProvider.kt`	Compose 루트 래퍼, 라이프사이클 동기화
UpdateModule	`di/UpdateModule.kt`	Hilt 의존성 주입 설정

📁 생성된 파일

1. 도메인 계층

app/src/main/java/com/billcoreatech/daycnt415/domain/service/
└── AppUpdateService.kt
    ├── AppUpdateService 클래스 (Play Core API 래핑)
    ├── UpdateInstallState sealed class (설치 상태)
    └── UpdateAvailableState data class (업데이트 정보)

주요 메서드:

checkForAppUpdate(): Task<AppUpdateInfo> - 업데이트 확인

startImmediateUpdateFlow() - 강제 업데이트 시작

startFlexibleUpdateFlow() - 선택적 업데이트 시작

completeUpdate() - 다운로드된 업데이트 설치

registerInstallStateUpdatedListener() - 상태 모니터링 시작

unregisterInstallStateUpdatedListener() - 상태 모니터링 종료

2. 프레젠테이션 계층 (ViewModel)

app/src/main/java/com/billcoreatech/daycnt415/presentation/viewmodel/
└── UpdateViewModel.kt
    ├── UpdateViewModel 클래스 (@HiltViewModel)
    ├── UpdateUiState data class
    └── UpdateType enum

주요 메서드:

checkForUpdate() - 업데이트 확인 (자동 호출)

startImmediateUpdate(activity) - 강제 업데이트 시작

startFlexibleUpdate(activity) - 선택적 업데이트 시작

installUpdate() - 다운로드 완료 후 설치

dismissUpdateDialog() - 다이얼로그 닫기

onActivityResumed() / onActivityPaused() - 라이프사이클 관리

3. 프레젠테이션 계층 (UI)

app/src/main/java/com/billcoreatech/daycnt415/presentation/ui/
├── components/
│   └── AppUpdateDialog.kt
│       ├── AppUpdateDialog Composable (메인 다이얼로그)
│       ├── DownloadProgressSection (진행률 표시)
│       ├── CompletedDownloadSection (완료 표시)
│       └── UpdateAvailableBanner (저우선순위 배너)
└── screens/
    └── AppUpdateProvider.kt
        └── AppUpdateProvider Composable (루트 래퍼)

4. DI 설정

app/src/main/java/com/billcoreatech/daycnt415/di/
└── UpdateModule.kt
    ├── AppUpdateManager 제공
    └── AppUpdateService 제공

🔄 데이터 흐름

상태 전이 다이어그램

IDLE
  ↓
CHECK_AVAILABLE
  ├─→ updateAvailable=false → IDLE
  └─→ updateAvailable=true
       ↓
    [USER SEES DIALOG]
       ├─→ IMMEDIATE MODE
       │    ├─→ DOWNLOADING
       │    ├─→ INSTALLED
       │    └─→ (스킵 불가)
       │
       └─→ FLEXIBLE MODE
            ├─→ "나중에" 클릭
            │    └─→ IDLE (다이얼로그 닫음)
            │
            └─→ "지금 업데이트" 클릭
                 ├─→ DOWNLOADING
                 ├─→ DOWNLOADED
                 ├─→ "지금 설치" 클릭
                 ├─→ INSTALLING
                 └─→ INSTALLED

UpdateUiState 필드

data class UpdateUiState(
    val updateAvailable: Boolean = false,           // 업데이트 가능 여부
    val updatePriority: Int = 0,                    // 우선순위 (0-5)
    val clientVersionStalenessDays: Int? = null,    // 버전 경과 일수
    val appUpdateInfo: AppUpdateInfo? = null,       // 업데이트 정보
    val isCheckingForUpdate: Boolean = false,       // 확인 중
    val isUpdating: Boolean = false,                // 업데이트 중
    val isDownloading: Boolean = false,             // 다운로드 중
    val isDownloadCompleted: Boolean = false,       // 다운로드 완료
    val downloadProgress: Int = 0,                  // 진행률 (0-100)
    val shouldShowUpdateDialog: Boolean = false,    // 다이얼로그 표시
    val updateType: UpdateType = UpdateType.NONE,   // IMMEDIATE/FLEXIBLE
    val errorMessage: String? = null                // 에러 메시지
)

🛠️ 통합 방법

1. MainActivity 수정 (이미 완료됨)

@AndroidEntryPoint
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()

        setContent {
            DaycntTheme {
                Surface(modifier = Modifier.fillMaxSize()) {
                    AppUpdateProvider {  // ← 추가됨
                        DayCntNavGraph()
                    }
                }
            }
        }
    }
}

2. MyApplication.kt (이미 구성됨)

@HiltAndroidApp
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // Hilt 자동으로 초기화됨
    }
}

3. AndroidManifest.xml (변경 없음)

기존 권한 유지

Play Core 라이브러리는 매니페스트 병합으로 자동 추가

📊 상태 구독 예시 (필요시 추가 화면에서 사용)

@Composable
fun SomeScreen() {
    val updateViewModel: UpdateViewModel = hiltViewModel()
    val uiState by updateViewModel.uiState.collectAsStateWithLifecycle()

    // 업데이트 진행률 표시
    if (uiState.isDownloading) {
        Text("다운로드: ${uiState.downloadProgress}%")
    }

    // 커스텀 UI 추가 가능
    if (uiState.updateAvailable && !uiState.shouldShowUpdateDialog) {
        UpdateAvailableBanner(
            isVisible = true,
            updatePriority = uiState.updatePriority,
            onUpdateClick = { updateViewModel.startFlexibleUpdate(context as Activity) },
            onDismiss = { updateViewModel.dismissUpdateDialog() }
        )
    }
}

🧪 테스트 방법

Google Play Console 설정

내부 테스트 트랙 활용:
- Google Play Console → 출시 → 내부 테스트
- 새 버전 APK 업로드 (versionCode 증가)
- 테스트 기기 추가

테스트 우선순위 설정:
- Google Play Console → 설정 → 우선순위
- IMMEDIATE: 우선순위 4 이상
- FLEXIBLE: 우선순위 1-3

로컬 테스트 (선택):
- Play Core 라이브러리의 FakeAppUpdateManager 사용
- 단위 테스트 작성

테스트 체크리스트

IMMEDIATE 모드 업데이트 다이얼로그 표시

FLEXIBLE 모드 업데이트 다이얼로그 표시

다운로드 진행률 표시 (FLEXIBLE 모드)

"나중에" 버튼 동작 (FLEXIBLE 모드)

"지금 설치" 버튼 동작 (FLEXIBLE 모드)

설치 완료 후 자동 재시작

네트워크 오류 처리

Activity 회전 시 상태 유지

🔐 에러 처리

UpdateViewModel의 에러 처리 전략

// 1. 업데이트 확인 실패
try {
    val appUpdateInfo = appUpdateService.checkForAppUpdate().await()
} catch (e: Exception) {
    _uiState.value = _uiState.value.copy(
        errorMessage = e.message ?: "Failed to check for update"
    )
}

// 2. 업데이트 시작 실패
if (!success) {
    _uiState.value = _uiState.value.copy(
        errorMessage = "Failed to start update"
    )
}

// 3. 설치 실패
UpdateInstallState.Failed → errorMessage 업데이트

에러 로깅

모든 에러는 android.util.Log로 기록됨:

TAG: "UpdateViewModel", "AppUpdateService", "AppUpdateProvider"

Level: ERROR (심각) 또는 WARNING (경미)

📈 로깅 포인트

AppUpdateService 로깅

checkForAppUpdate(): 업데이트 확인 시작

startImmediateUpdateFlow(): 강제 업데이트 시작

startFlexibleUpdateFlow(): 선택적 업데이트 시작

registerInstallStateUpdatedListener(): 상태 모니터링 시작

설치 상태 변경: PENDING, DOWNLOADING, DOWNLOADED, INSTALLING, INSTALLED, FAILED, CANCELED

UpdateViewModel 로깅

업데이트 확인 결과 (우선순위, 경과일수)

설치 상태 업데이트

에러 발생

AppUpdateProvider 로깅

에러 메시지: "Update error: ..."

🚀 향후 개선 사항

Phase 1 (기본 기능 - 완료)

✅ IMMEDIATE/FLEXIBLE 모드 구현

✅ Compose UI 통합

✅ Hilt DI 설정

✅ 라이프사이클 관리

Phase 2 (선택 사항)

Firebase Crashlytics 연동 (업데이트 이벤트 기록)

Timber 로깅 통합

업데이트 버전 정보 표시 (현재 vs 최신)

네트워크 재시도 로직

앱 내 알림 (Snackbar) 추가

Phase 3 (고급 기능)

예약된 업데이트 (특정 시간대에만 업데이트)

업데이트 거부 이유 추적

A/B 테스트 (업데이트 UI 변형)

단위 테스트 추가 (FakeAppUpdateManager 사용)

📚 참고 자료

Google Play In-App Update API 공식 문서

Play Core Library (v2.1.0)

Kotlin Coroutines + Google Tasks

🎓 학습 포인트

이 구현에서 다룬 안드로이드 개념

Google Play Core Library: 인앱 업데이트, 인앱 리뷰 등

Compose Lifecycle: DisposableEffect, LaunchedEffect

StateFlow: 반응형 상태 관리

Hilt Dependency Injection: 싱글톤 패턴, 의존성 주입

Coroutines: Task.await() 활용

Activity 라이프사이클: onResume(), onPause()

✅ 완료 체크리스트

AppUpdateService 구현

UpdateViewModel 구현

AppUpdateDialog Composable 구현

UpdateModule (Hilt) 구현

MainActivity 통합

빌드 성공

문서 작성

테스트 기기에서 테스트 (배포 후)

Google Play Console 설정 및 내부 테스트 트랙 배포

📞 문제 해결

Q: "컴파일 에러: Cannot infer type for type parameter"

A: Task 객체의 제네릭 타입을 명시적으로 지정하세요: appUpdateService.checkForAppUpdate().await<AppUpdateInfo>()

Q: "업데이트 다이얼로그가 표시되지 않습니다"

Google Play Console에서 새 버전(높은 versionCode)이 업로드되었는지 확인

내부 테스트 트랙에서 테스트하고 있는지 확인

테스트 기기가 해당 트랙에 추가되었는지 확인

앱을 재시작하고 Play Store 앱 업데이트 확인

Q: "Activity가 null입니다"

A: LocalContext.current가 Activity로 캐스트되지 않을 수 있습니다. @SuppressLint("ContextCastToActivity") 사용하고 null 체크하세요.

작성 일자: 2026-03-10
최종 상태: ✅ 완료 및 빌드 성공