편집 — A-05

# 프로젝트 문서 추가용 (v2.4)목적

홈 검색바 우측에 📷 아이콘을 추가하여, 사용자가 **나무 사진 1장(수형)**으로 빠르게 후보를 얻고 필요 시에만 잎/열매/수피 추가 촬영을 넛지하는 “소프트 UX”로 정확도를 끌어올린다.

## UX 원칙 (중요)

❌ 처음부터 “여러 장 찍어라”는 의도 노출 금지

✅ 1장(수형) → 결과 TOP3 → 애매하면 추가 촬영 권유 흐름 고정

✅ 결과는 “단정”이 아니라 확률(신뢰도) 기반으로 표시

✅ “틀렸는데 당당” 방지를 위해 비교하기를 항상 제공

## 화면/흐름 정의
### 1) Home 검색바 확장

기존: 🔍 검색

추가: 우측 끝 📷 아이콘 버튼

탭 → 카메라 촬영 or 갤러리 선택(권장: 둘 다)

권한: CAMERA(촬영 시), READ_MEDIA_IMAGES(갤러리 선택 시, Android 13+)

표기 예:

🔍 수종명 검색 📷

### 2) 1차 촬영 안내(수형 1장)

안내 문구(짧게):

💡 “나무 전체가 보이게 조금 멀리서 찍어주세요”

### 3) 인식 결과 화면 (TOP3 + 확률)

표시 규칙(예시):

소나무 (Pinus densiflora) — 80%

곰솔 (Pinus thunbergii) — 50%

리기다소나무 (Pinus rigida) — 30%

* UI 요소:

⭐ 별점(선택) + 퍼센트 + 막대(bar) 중 1개만(과한 연출 금지)

버튼:

[상세보기] (도감 상세로 연결)

[⚖️ 비교하기] (TOP1 vs TOP2 기본)

[📷 추가 촬영] (넛지)

[닫기/홈]

### 4) 추가 촬영 넛지(조건부)

* 넛지 트리거:

TOP1 확률이 낮음(예: < 0.60) 또는 TOP1~TOP2 격차가 작음(예: < 0.15)

또는 사용자가 “확실하게” 버튼 탭

넛지 문구(짧게):

💡 “잎/열매/수피를 가까이 찍으면 더 정확해져요”

* 추가 촬영은 선택:

[📷 추가 촬영] [나중에]

무료/유료 카운트 규칙

무료: 하루 N회(권장 1~3회)

카운트 방식(권장):

“수형 + 추가촬영(선택)”을 1세트 = 1회로 계산

즉, 추가촬영 때문에 과금처럼 느껴지지 않게 설계

초과 시 안내(짧게):

🔒 “오늘의 무료 인식이 끝났어요. 프리미엄은 무제한 인식이 가능합니다.”

신뢰도/오답 방어 정책

TOP1 확률이 매우 낮을 때(예: < 0.45)

단정 금지

문구:

“정확한 인식이 어려워요. 다른 각도에서 다시 찍어주세요.”

TOP3는 보여주되 “후보”임을 강조

데이터 매칭 정책 (API 결과 → 도감 연결)

외부 API는 보통 학명(Scientific name) 중심으로 결과를 반환한다.

앱 내부는 species.json에 학명 필드 추가(권장):

scientific_name: "Pinus densiflora"

매칭 우선순위:

학명 exact match

영문명/ID 보조 매칭

매칭 실패 시: “도감에 없는 후보”로 표시하고 웹검색 유도는 금지(오프라인 우선)
→ 대신 “다시 촬영/추가 촬영”만 제공

구현 범위 (P0 / P1)
P0 (필수)

홈 검색바 📷 버튼 추가

촬영/갤러리 선택 → 이미지 1장 업로드

외부 AI API 호출(네트워크)

결과 TOP3 표시 + 비교하기 연결

무료 횟수 제한(일 단위 리셋) + 초과 시 유료 안내

P1 (권장)

인식 히스토리(최근 10개)

실패/타임아웃 재시도 UX(1회)

네트워크 불가 시 안내(오프라인 문구)

파일/모듈 위치 제안 (코드 정리용)

ui/home/HomeScreen.kt : 검색바 + 📷 버튼

ui/recognition/RecognitionFlow.kt : 촬영/갤러리/결과 화면

data/recognition/RecognitionApi.kt : API 호출

data/recognition/RecognitionRepository.kt : 결과 정리 + 도감 매칭

data/store/UsageStore.kt : 일일 무료 횟수 카운트(DataStore)

model/RecognitionResult.kt : TOP 후보 모델

## 제목, - 목록, **굵게**, `코드` 사용 가능

미리보기