자기 성찰 타로 상담 앱 실행 로드맵 (MVP 기준)

1) 제품 방향

제품 한 줄 정의: 예언이 아니라, 사용자의 감정과 생각을 비추는 자기 성찰형 타로 상담 앱

앱 목표: 카드 해석, 상담형 질문, 저널 기록, 치유 메시지를 통해 감정 탐색과 정서적 안정을 돕는다.

핵심 사용자: 감정 정리가 필요한 사용자, 가벼운 셀프 상담을 원하는 사용자, 타로를 심리적 도구로 쓰고 싶은 사용자

핵심 가치: 자기 성찰, 정서적 안정, 기록 습관, 감정 탐색, 치유 경험

2) MVP 범위 (필수)

랜덤 카드 추출 (공정한 무작위 셔플)

스프레드: 1장 / 3장 우선 구현

해석 엔진: 카드 의미 + 사용자 질문 맥락 기반 상담 메시지 생성

저널링: 상담 내용 저장/조회, 회고 기록

세션 종료 치유 콘텐츠: 긍정 확언(Affirmation), 명상/호흡 메시지

3) 사용자 경험 흐름

홈에서 오늘의 질문 선택

스프레드 선택 후 카드 추출

카드 해석 + 공감형 상담 메시지 확인

후속 질문에 사용자 응답 입력

저널 저장

확언/명상 메시지 확인 후 세션 종료

4) 기능 설계 요약

4-1. 콘텐츠/데이터

카드 정보: 카드명, 키워드, 정/역방향 의미, 확언, 명상 문구

저널 정보: 질문, 선택 카드, 해석 요약, 상담 메시지, 사용자 회고, 감정 태그, 생성 시각

4-2. 해석 엔진 원칙

입력: 사용자 질문 + 선택 카드 + 모드(개인용/상담 모드)

처리: 카드 의미 추출 -> 질문 맥락 분류 -> 조합 해석 -> 상담 메시지 -> 후속 질문 생성

출력: 해석 결과, 후속 질문, 확언 문구

중요 가이드: 미래 예언형 문장 금지, 감정 탐색/자기 이해 중심 어조 유지

4-3. UI/UX

기본 플로우: 카드 뽑기 -> 해석 -> 상담 질문 -> 기록 -> 치유 메시지

화면 후보: Home, DrawCard, Reading, Counseling, Journal, Meditation

디자인 방향: 안정감 있는 색감, 부드러운 애니메이션, 공감형 문구 중심

5) 기술/구조 계획

기술 스택: Kotlin, Jetpack Compose, Coroutines, Navigation

로컬 데이터: Room 기반 카드/저널 저장

DI: Hilt 도입 검토(MVP 초기에는 단순 구조 우선, 복잡도 증가 시 적용)

아키텍처: 현재 단순 Compose 구조 유지, 이후 Presentation/Domain/Data 레이어로 점진 분리

6) 비기능 요구사항

오프라인에서도 카드 조회/저널 저장 동작

첫 화면 진입 속도 목표: 2초 내

문구 품질: 비판적 표현 없이 중립적/공감적 톤 유지

UX 품질: 불안 조장 표현 지양, 안정감 있는 경험 유지

7) 8주 실행 일정(초안)

1주차: 기획 확정, 와이어프레임, DB 스키마 정의

2주차: Navigation/데이터 계층 기초, Room 세팅

3주차: 카드 셔플/추출 + 1장/3장 스프레드

4주차: 해석 화면 + 해석 엔진 1차 연결

5주차: 상담 질문 흐름 + 사용자 입력 UI

6주차: 저널 저장/조회 + 확언/명상 화면

7주차: 디자인 보정, 문구 튜닝, QA

8주차: MVP 배포 및 베타 피드백 수집

8) 출시 후 확장 백로그

스프레드 확장: 5장, 켈틱 크로스

감정 태그 기반 개인화 리포트

AI 기반 맞춤형 상담 강화

커뮤니티 기능(경험 공유)

전문가/상담가 연계 세션

9) 핵심 메시지

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

10) 현재 구현 상태 점검 (코드 기준, 2026-03-16)

홈 화면 기본 구성(브랜드/히어로/메뉴/상단 앱바) 구현

Home -> ReadingList -> ReadingDetail Navigation 기본 흐름 구현

앱 시작 시 raw/hanbok_prompt.txt 기반 Room 초기 적재 구현

raw/tarot_app_cards_ko.json 기반 카드 한글명/키워드/의미 보강 로직 구현

리딩 목록에서 카드 이미지 + 한글 프롬프트 요약 + 상세 이동 구현

리딩 상세에서 한글/영문 프롬프트, 키워드, 의미 전체 스크롤 조회 구현

스프레드 선택(1장/3장) 전용 화면/상태 모델 고정

카드 드로우(중복 없는 랜덤 선택) 세션 플로우 구현

상담 입력(Counseling) 화면 및 후속 질문 플로우 구현

Journal Entity/DAO/저장-목록-상세 흐름 구현

세션 종료용 확언/명상(Meditation) 화면 구현

11) Home 이후 실행 체크리스트 (우선순위 + DoD)

P0 (이번 스프린트 필수)

스프레드 선택 흐름 고정 (1장, 3장)

카드 추출(셔플/중복 없는 랜덤 선택) 완료

리딩 결과 화면에서 선택 카드 + 질문 + 해석 요약 표시

홈 -> 스프레드 -> 드로우 -> 리딩 단일 플로우 완성

완료 기준(DoD)

홈에서 시작해 리딩 결과까지 한 번에 이동 가능

시스템 뒤로가기 시 흐름이 깨지지 않음

P1 (P0 직후)

상담 질문 1~2개 입력 화면 연결

세션 결과를 Journal로 저장

Journal 목록/상세 조회 연결

상세 화면에서 한글 데이터/카드 이미지/본문 전체 확인 가능

완료 기준(DoD)

리딩 -> 상담 입력 -> 저널 저장 -> 목록/상세 조회까지 끊김 없음

P2 (품질/마무리)

세션 종료용 확언/명상 화면 연결

빈 상태/오류 상태 문구 정리

오탈자/한국어 톤(자연스러운 번역) 최종 점검

릴리즈 전 QA 체크리스트 정리

12) 2주 스프린트 실행안

Week 1: 핵심 플로우 고정

Route/인자 규칙 확정 (spreadType, sessionId)

Draw + Reading 구현 마무리

ViewModel 세션 상태(spreadType, selectedCardIds, userQuestion) 고정

더미 문구 제거 및 실제 데이터 연결

반영 메모 (2026-03-17)

Reading 요약이 카드 DB의 keywords / meanings / 사용자 질문을 기반으로 생성되도록 연결

Meditation 마무리 문구와 확언이 선택 카드/감정 태그 기반 파생 문구를 사용하도록 전환

홈 최근 기록 카드가 날짜/감정 태그뿐 아니라 실제 질문/요약/선택 카드명을 노출하도록 보강

Week 2: 세션 완결 + QA

Counseling 입력 흐름 연결

Journal 저장/목록/상세 완성

Meditation(확언/명상) 종료 화면 연결

리소스 매핑/오류 처리/빈 상태/문구 톤 최종 점검

13) 오늘 바로 시작할 작업 (1 -> 2 순서)

Route/인자 표 확정

Draw/Reading 상태 모델 고정

리딩 결과 화면 최소 스펙(카드/요약/다음 액션) 잠금

Journal 저장 스키마 + DAO 쿼리 확정

13-1) Route/인자 표 확정

목표: Navigation 계약을 먼저 고정해 화면 연결 재작업을 줄인다.

세부 작업
- 라우트 후보 확정: Home, SpreadSelect, Draw, Reading, Counseling, JournalList, JournalDetail, Meditation
- 인자 분류: 필수/선택/없음 (spreadType, sessionId, journalId)
- 뒤로가기/딥링크 대응 기준 정리

산출물: Route/인자 표 v1 + TarotNavRoutes 반영 기준

완료 기준(DoD): 모든 화면의 인자 규칙이 문서와 코드에서 동일

예상 소요: 1.5 ~ 2시간

route	인자	타입	필수	예시
`home`	-	-	-	`home`
`draw/{spreadType}`	`spreadType`	String	Y	`draw/three_card`
`reading/{sessionId}`	`sessionId`	Long	Y	`reading/1710572400000`
`counseling/{sessionId}`	`sessionId`	Long	Y	`counseling/1710572400000`
`journal/detail/{journalId}`	`journalId`	Long	Y	`journal/detail/42`
`meditation?sessionId={sessionId}`	`sessionId`	Long	N	`meditation?sessionId=1710572400000`

13-2) Draw/Reading 상태 모델 고정

목표: ViewModel 단일 상태원천(SSOT)으로 Draw와 Reading을 일관되게 연결한다.

세부 작업
- TarotViewModel에 세션 상태 필드 정의
- 이벤트 목록 확정 (onSpreadSelected, onQuestionChanged, drawCards, clearSession)
- UI 로컬 상태와 ViewModel 상태 경계 명시

산출물: SessionState 필드 표 v1 + 이벤트 계약

완료 기준(DoD): Draw/Reading이 동일 상태 모델을 참조하고 상태 전달이 끊기지 않음

예상 소요: 2 ~ 3시간

필드명	타입	용도	갱신 시점
`sessionId`	Long?	세션 식별자	스프레드 시작 시 생성
`spreadType`	String	`one_card`/`three_card` 구분	스프레드 선택 시
`userQuestion`	String	사용자 질문 원문	홈/상담 입력 시
`selectedCardIds`	List	중복 없는 카드 번호	Draw 완료 시
`readingSummary`	String	리딩 요약	Reading 계산 후
`nextAction`	String	다음 CTA 분기	Reading 진입 시
`isLoading`	Boolean	로딩 상태	Draw/저장 중
`errorMessage`	String?	에러 노출	실패 시

13-3) 리딩 결과 화면 최소 스펙 잠금

목표: P0 범위를 고정해 과도한 화면 확장을 방지한다.

세부 작업
- 필수 UI 3요소 고정: 선택 카드 썸네일, 요약 텍스트(2~~4줄), 다음 액션 버튼(1~~2개)
- P1 이관 항목 분리: 심화 해석/부가 텍스트
- 빈 상태/오류 상태 문구 확정

산출물: Reading 최소 스펙 체크리스트

완료 기준(DoD): 리딩 진입 시 필수 3요소가 항상 보이고 다음 화면 이동이 일관됨

예상 소요: 1.5 ~ 2.5시간

13-4) Journal 저장 스키마 + DAO 쿼리 확정

목표: 세션 저장/조회의 DB 계약을 먼저 고정한다.

세부 작업
- JournalEntity 필드 확정 (질문, 카드목록, 요약, 상담응답, 감정태그, 생성시각)
- JournalDao 최소 쿼리 확정 (insert, list, detail, recent)
- TarotDatabase 버전 업 및 마이그레이션 정책 결정

산출물: JournalEntity/JournalDao 설계표 v1

완료 기준(DoD): 저장 1건/목록 조회/상세 조회를 커버하는 쿼리 셋 정의 완료

예상 소요: 2 ~ 3시간

추가 반영 메모 (2026-03-17)

TarotRepositoryDataSource 도입으로 TarotViewModel JVM 단위 테스트 가능 구조로 정리

MainDispatcherRule, TarotViewModelTest 추가로 리딩 요약 생성 / Journal 저장 회귀 검증 자동화

JournalDaoTest 추가로 최신순 목록 / 상세 조회 / DB 재오픈 후 데이터 유지 검증

MIGRATION_4_5 명시적 Room 마이그레이션 추가

DB 정책: 4 -> 5는 비파괴 마이그레이션 적용, 1~3 구버전은 destructive fallback 유지

14) QA 체크리스트 문서

MVP QA 체크리스트 작성: documents/qa_checklist_mvp.md

15) QA/테스트/마이그레이션 진행 상태 (2026-03-17)

TarotViewModel 최소 회귀 테스트 추가

JournalDao 저장/조회/재오픈 테스트 추가

TarotDatabase 4 -> 5 마이그레이션 정책 코드 반영 및 테스트 추가

시스템 뒤로가기 동작을 BackHandler로 세션/저널/프롬프트 화면에 명시적 반영

명상/확언 문구 톤을 차분한 반성형 문장으로 보강하고 테스트 추가

기본 테마를 medium contrast 색상표와 surfaceContainer* 계열 배경으로 조정해 다크/라이트 대비 보강

16) 코드 품질 정리 (2026-03-17)

JournalScreens.kt CardDetailBlock: 영문 카드명 중복 표시 버그 수정 → cardNameKo 우선 주 타이틀, 영문명은 부제목으로 분리

TarotSummaryScreen.kt: 홈 화면 Journal 직접 이동 버튼 복원 (EditNote 아이콘, 3 Card Spread 아래 배치)

TarotSessionFlowScreens.kt: 미사용 SimpleTodoScreen 제거

TarotReadingScreens.kt: 미사용 private DetailCard 제거

TarotViewModel.kt: 미사용 public observeJournalDetail / clearSessionError 제거

TarotViewModel.kt buildReadingSummary: 카드명을 cardNameKo 우선 사용으로 리딩 요약 문구 한국어화

17) AI 도입

기본 전략: 온디바이스 우선(MediaPipe LLM) + 서버 폴백(선택적)

폴백 순서(고정): on-device -> server(optional) -> rule-based

보안 원칙:
- 평문 API 키를 문서/코드/Git 이력에서 제거
- 기존 노출 키는 즉시 폐기(revoke) 후 신규 발급
- 키는 local.properties 또는 CI Secret으로만 주입

17-1) 보안/운영 준비 (즉시)

working_plan.md 포함 문서 내 실제 키/토큰 제거

네트워크 폴백을 사용할 경우, 질문 텍스트의 PII 마스킹 규칙 확정

로그 정책 확정: 사용자 질문 원문/응답 원문의 로그 저장 금지

17-2) 구현 전 아키텍처 고정

TarotAiService 계약 고정(입력: 질문/카드/키워드, 출력: 해석/확언)

실패 코드 표준화(모델 미로딩/타임아웃/네트워크 실패/안전필터)

AiModule에서 전략 스위칭(온디바이스만 / 폴백 허용) 플래그 고정

17-3) 빌드/의존성 준비

온디바이스 추론 자산(모델 파일) 배치 경로와 크기 정책 확정

서버 폴백 사용 시 네트워크 권한/클라이언트 의존성 추가 범위 확정

Debug/Release별 AI 설정 분리(성능 로그는 Debug 전용)

17-4) 테스트/QA 준비

폴백 회귀 테스트: on-device 실패 시 server 또는 rule-based로 정상 전환

프롬프트 품질 테스트: 질문-카드 연관성, 확언 톤(비예언/비단정) 검증

저널 저장 연동 테스트: AI 결과 저장/조회/재진입 시 일관성 검증

17-5) 다음 코딩 라운드 최소 마일스톤

보안 정리(키 폐기 + 비밀 주입 경로 확정)

AI 서비스 계약/DI 고정

서버 폴백 Mock 연결

ViewModel 연동 + 단위 테스트 보강

QA 체크리스트 반영

17-6) 참고 코드 (키는 환경변수/시크릿에서만 주입)

import os
import requests

GROQ_API_URL = "https://api.groq.com/openai/v1/chat/completions"


def groq_chat(messages, model="llama-3.3-70b-versatile", max_tokens=500, temperature=0.7):
    api_key = os.environ.get("GROQ_API_KEY", "")
    if not api_key:
        raise RuntimeError("GROQ_API_KEY is not set")

    resp = requests.post(
        GROQ_API_URL,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={
            "model": model,
            "messages": messages,
            "max_tokens": max_tokens,
            "temperature": temperature,
        },
        timeout=30,
    )
    resp.raise_for_status()
    data = resp.json()
    return data["choices"][0]["message"]["content"]

def example_tarot():    
  respText = groq_chat([
        {
            "role": "system",
            "content": "당신은 한국어 타로 상담 전문가입니다. "
                       "카드의 상징과 의미를 따뜻하게 해석해 주세요. "
                       "5~8문장으로 답변합니다."
        },
        {
            "role": "user",
            "content": "질문: 올해 이직을 해도 괜찮을까요?\n"
                       "뽑은 카드: 태양(The Sun), 운명의 수레바퀴(Wheel of Fortune), 힘(Strength)\n"
                       "타로 해석을 해주세요."
        },
    ])   
  print(respText)

2026-03-27 작업 현황 및 업데이트 (자동 요약)

이 문서는 현재 저장소 코드와 최근 수정사항을 바탕으로 자동으로 생성한 진행 현황입니다. 아래 내용은 "적용됨", "부분 적용/확인 필요", "미실행/추가 필요"로 구분되어 있습니다.

1) 주요 적용됨

GroqClient.groqChat 유틸이 app/src/main/java/.../ai/TarotAiService.kt에 Ktor(OkHttp) 기반으로 구현되어 있음.

app/build.gradle.kts에 Ktor, OkHttp, kotlinx-serialization-json, Material Dialogs 등의 의존성이 추가됨.

Kotlin Serialization 플러그인(alias)와 런타임 의존성이 버전 카탈로그와 app 모듈에 추가되어 @Serializable 클래스의 직렬화가 가능하도록 설정함.

MeditationFinishScreen(구성: TarotSessionFlowScreens.kt)에 Groq 호출을 이용한 AI 명상 가이드/확언 통합 로직이 추가됨(LaunchedEffect에서 Groq 호출, 실패시 로컬 폴백).

시스템 프롬프트에 "앱 기본 언어로 응답" 지시문을 추가함(명상 가이드/확언 프롬프트).

Settings 화면(app/src/main/java/.../presentation/SettingsScreen.kt)에 Material Dialog를 이용한 Groq 동의/철회 로직이 구현되어 있으며, SharedPreferences에 동의 상태와 타임스탬프를 저장/삭제함.

2) 부분 적용 / 확인 필요

Kotlin Serialization 플러그인과 라이브러리 의존성은 추가되었으나, 실제 직렬화기 생성(빌드 성공)은 로컬 Gradle 빌드를 통해 확인해야 함. 현재 사용자의 환경에서 JAVA_HOME 문제로 빌드가 차단되어 있어 검증 불가.

동적 drawable 조회를 위해 context.resources.getIdentifier(...)을 사용하고 있음 — 유연성에는 유리하나 Lint/IDE 경고가 존재함. 정적 R 매핑으로 대체하거나 자동 매핑을 생성하여 경고를 제거할 수 있음.

앱 전체 다이얼로그를 MaterialDialog로 통일하는 작업은 일부 컴포저블에 반영되었으나, 모든 다이얼로그(예: ExitAppConfirmDialog, MandatoryUpdateDialog 등) 변환 여부는 추가 점검 필요.

3) 미실행 / 추가 필요

온디바이스 AI(MediaPipe LLM) 모델 파일 배치, 추론 런타임 통합 및 용량/권한 정책 정리(완료되지 않음).

TarotAiService 전략(온디바이스 우선 -> 서버 폴백) 및 DI(AiModule) 고정, ViewModel 연동과 회귀 테스트 보강 필요.

보안/운영 항목 정리: API 키 폐기/마스킹, PII 마스킹 규칙, 로그 정책(사용자 질문 원문 저장 금지) 적용 필요.

BuildConfig.GROQ_API_KEY 주입은 local.properties를 사용하도록 되어 있으나, 실제 키 삽입과 CI secret 설정은 수동 작업이 필요함.

4) 로컬 검증/테스트 권장 순서
a) JDK 경로(JAVA_HOME)를 로컬 세션에 설정한 후 프로젝트 빌드 및 직렬화기 생성 확인:

$env:JAVA_HOME = 'C:\Program Files\Java\jdk-17'  # 실제 설치 경로로 변경
./gradlew.bat :app:assembleDebug --no-daemon

b) 단위 테스트 실행(성공 시 코드 변경의 회귀 방지 확인):

./gradlew.bat :app:testDebugUnitTest --no-daemon

c) Groq API 호출 실험 전에 local.properties에 GROQ_API_KEY 추가(절대 커밋 금지):

# local.properties (로컬 전용)
GROQ_API_KEY=sk_live_xxx

d) 앱 플로우 확인

Settings -> Groq 동의 토글 및 동의/철회 다이얼로그 동작

Draw -> Reading -> MeditationFinish: Groq 응답으로 명상/확언 생성(실제 API 키 필요)

5) 우선순위가 높은 다음 작업 제안

1순위: 로컬 환경에서 Gradle 빌드를 성공시켜 직렬화 플러그인 적용 및 Groq 통신(직렬화 문제 해결)을 검증하세요.

2순위: TarotAiService 전략 분리(AiModule), 온디바이스 모델 준비 계획 수립.

3순위: 보안 정책 정리(키 관리, 로그 규칙, PII 마스킹) 및 문서화.

4순위: 앱 전역 다이얼로그를 Material Dialog로 통일 및 getIdentifier 경고 제거 전략 적용.

원하시면 제가 다음을 수행하겠습니다:

(A) getIdentifier 경고를 제거하는 자동 리소스 매핑 생성 스크립트 및 코드 적용

(B) GroqClient가 API 키가 없을 때 안전히 동작하도록 방어 로직 추가(테스트 친화적)

2026/05/13