프로젝트 작업지시서

프로젝트명: TreeStudy (수목 현장 식별/학습 도구)
목표: 현장에서 10초 내 헷갈리는 수종을 빠르게 확정할 수 있는 오프라인 우선 앱
현재 단계: Phase 1 진행 중 (진행률 70%)

---

완료 항목

• ✅ 프로젝트 생성 (Android Studio, Kotlin, Min SDK 26)
• ✅ Phase 1 데이터 생성 (species_phase1.json, 20종)
• ✅ assets 폴더 구성 (lite 이미지 2장/종)
• ✅ 기본 UI 흐름 (Home → 목록 → 상세 화면)
• ✅ JSON 파싱 및 수종 표시 정상 동작 확인
• ✅ 검색 자동완성 구현 (수종명/별칭/ID 매칭 + 점수 기반 정렬, 최대 12개)
• ✅ “최근 본(최대 10개)” 기록/표시 기능 구현 (RecentStore + collectAsState)
• ✅ 카테고리 4타일(2x2) 메인 UI 적용 (대표 이미지 오버레이 + 라운드 처리)
• ✅ Category enum/모델 타입 충돌 이슈 해결 (Category? ↔ String 비교 오류 정리 완료)
• ✅ 카테고리 타일 이미지 리소스 연동 완료 (res/drawable + 파일명 규칙 적용)
• ✅ 다크/라이트 테마 전환 UX 개선 (해/달 아이콘 적용, 전환 이펙트 이질감 완화)
• ✅ 카테고리 카드 텍스트 처리 변경 (반투명 칩 제거 → 큰 텍스트 + Shadow로 가독성 확보)
• ✅ 카테고리 카드 하단 스크림(그라데이션) 보강으로 텍스트 가독성 안정화
• ✅ 카테고리 카드 배경 이미지 일부 교체 완료 (활엽 교목 / 관목·조경)
• ✅ 카테고리 화면 상단 타이틀 텍스트 제거/정리(TopAppBar title 공백 처리)
• ✅ 카테고리 배너 이미지 표시 적용(카테고리별 R.drawable webp 매핑 + 오버레이 적용)
• ✅ 세그먼트 UI 정리(전체 외곽 테두리 제거, 체크 아이콘 제거, 버튼 경계만 유지)
• ✅ 컴포저블 위치 정리 및 참조 오류 해결(CategoryBanner/CategorySegment를 CategoryScreen.kt에 고정, R import로 drawable 참조 오류 해소)
• ✅ 카테고리 화면 레이아웃/여백 1차 정돈(배너+세그먼트+리스트 흐름 안정화)

// ------------------------------------------ //
// ------------------------------------------ //

1. 프로젝트 개요

핵심 가치

• 오프라인에서 빠르게 동작 (로딩/검색 최소화)
• 야외 가독성 우선 (큰 글씨/큰 버튼/고대비)
• 최소 정보로 판별 지원 (카테고리 → 검색 → 상세 → 비교)

성공 기준 (Phase 1)

• Lite 앱 50MB 이하 (종당 이미지 2장만 내장)
• 오프라인 상태에서 즉시 사용 가능
• 핵심 판별 포인트로 10초 내 종 확정 가능

금지 사항

• 조사 목록 별도 저장/내보내기 기능 (실무 플랫폼과 중복, 흐름 악화)
• Pro 유도용 블러/가림 UI (낚시 UI 금지)
• localStorage/sessionStorage 사용 (지원 안 됨)

// ------------------------------------------ //
// ------------------------------------------ //

2. Phase 구분 및 진행 상황

Phase 1 (현재 진행 중)

목표

• Top 20 수종 탑재
• Lite(2장/종) + Full팩 다운로드 구조
• 기본 검색(수종명/별칭), 카테고리, 상세, 비교, 최근본

진행 중 작업

• 한글명 표시 (name_ko 필드 추가)
• 검색 기능 구현 (자동완성)
• 비교 화면 (2종 고정)

블로커/이슈

• JSON 주석 파싱 실패 → 해결 완료 (주석 제거)
• 없는 수종 데이터 PASS 처리 필요

---

Phase 2 (예정)

추가 기능

• Top 50 수종 확대
• 비교쌍 확장 (침엽/과실/관목 혼동군)
• 싱크 스크롤 비교 (좌우 동기화)
• 형태 필터 칩 (태그 품질 검증 후)

---

Phase 3 (계획)

고급 기능

• 내 사진 촬영 후 도감 사진과 나란히 비교
• 리포트 내보내기 (PDF/Excel)
• 광고/후원/프로모션 정교화

// ------------------------------------------ //
// ------------------------------------------ //

3. 개발 스펙

필수 화면 5개

1) Splash

• 로고 + 짧은 로딩

2) Home

• 상단: 큰 검색바 (고정)
• 본문: 카테고리 카드 (침엽·상록 / 과실·열매 / 활엽 교목 / 관목·조경)
• 섹션: 최근 본 (최대 10개, 30일 보관)

3) Category List

• 카드/리스트: 썸네일 + 수종명 (큰 글씨)
• 정렬: 빈출순 (rank 기준)

4) Species Detail

• 상단: 대표 사진 (habit)
• 핵심 판별 포인트 3~5줄
• 사진 섹션: habit / leaf / bark / fruit (탭/그리드)
• Lite는 2장만, 나머지는 "Full 팩 필요" 슬롯 표시
• 버튼: [유사종 비교] [즐겨찾기]
• 이미지 뷰어: 핀치 줌 필수

5) Compare (2종 비교)

• A vs B 고정
• 결정타 1줄 + 파트별 차이 포인트
• 사진 항목별 나란히 표시
• 하단: "이것도 비슷해요" 칩 (3~5개, 원클릭 교체)

---

데이터 스키마

species.json

[
  {
    "id": "persimmon",
    "name_ko": "감나무",
    "aliases": ["감", "감나무"],
    "category": "FRUIT_TREE",
    "rank": 1,
    "key_points": [
      "판별포인트 1",
      "판별포인트 2",
      "판별포인트 3"
    ],
    "similar_ids": ["jujube"],
    "images": {
      "thumb": "thumbs/persimmon.webp",
      "lite": {
        "habit": "habit.webp",
        "detail": "detail.webp"
      },
      "full": {
        "habit": ["packs/full/persimmon/habit_01.webp"],
        "leaf": ["packs/full/persimmon/leaf_01.webp"],
        "bark": ["packs/full/persimmon/bark_01.webp"],
        "fruit": ["packs/full/persimmon/fruit_01.webp"]
      }
    }
  }
]

경로 규칙:
- Android assets 내부에서는 assets/ 접두어 없이 접근
- lite 이미지는 파일명만 저장 (앱에서 lite/${id}/${파일명} 조합)
- thumb는 thumbs/${id}.webp 경로
- JSON은 표준 JSON만 허용 (주석/트레일링 콤마 금지)
- ID는 폴더명과 100% 동일해야 함 (대소문자 포함)
- 문서 표/JSON/폴더명 3개 중 하나라도 다르면 PASS 처리

---

comparisons.json

[
  {
    "id": "thuja_vs_juniper",
    "a": "thuja",
    "b": "juniper",
    "title": "측백나무 vs 향나무",
    "decisive": "결정타 1줄 설명",
    "points": {
      "leaf": ["차이점 1", "차이점 2"],
      "bark": ["차이점 1"],
      "fruit": ["차이점 1"],
      "habit": ["차이점 1"]
    }
  }
]

비교 카드 노출 규칙:
- a와 b 수종이 둘 다 존재할 때만 노출
- 하나라도 없으면 자동 숨김 (Phase 2에서 종 추가 시 자동 활성화)

---

폴더 구조

Lite (앱 내장)

app/src/main/assets/
├── data/
│   └── species_phase1.json
├── lite/
│   └── <species_id>/
│       ├── habit.webp
│       └── detail.webp
└── thumbs/
    └── <species_id>.webp

Full Pack (다운로드/오프라인)

packs/full/<species_id>/
├── habit_01.webp
├── leaf_01.webp
├── bark_01.webp
└── fruit_01.webp

---

카테고리 Enum (고정 키)

• CONIFER_EVERGREEN - 침엽·상록
• FRUIT_TREE - 과실·열매
• BROADLEAF_TREE - 활엽 교목
• SHRUB_LANDSCAPE - 관목·조경

---

컴포넌트 우선순위

P0 (필수)

1. 로컬 데이터 로딩 (JSON)
2. 검색 (수종명 + 별칭) + 자동완성
3. 최근 본 기록 (로컬 저장, 최대 10개, 30일 보관)
4. 상세 페이지 이미지 핀치 줌 (구현: Transformable 기본 우선)
5. 비교 기능 (2종) + 조건부 노출
6. Lite/Full 팩 경로 분리 + 슬롯 표시

P1 (권장)

1. 즐겨찾기 (로컬)
2. 다운로드 팩 UI (Wi-Fi 권장/용량 표시/진행률/재시도)

P2 (후순위)

1. 싱크 스크롤 비교
2. 형태 필터 칩
3. 내 사진 촬영 비교
4. 리포트 내보내기

---

데이터 자동화 스크립트 요구사항

입력 폴더 (원본)

raw/<species_id>/
├── habit/*.jpg
├── leaf/*.jpg
├── bark/*.jpg
└── fruit/*.jpg

출력

• Lite 이미지 (2장/종) + 썸네일 생성
• Full 이미지 WebP 변환
• species.json 경로 자동 갱신
• Validator 리포트 (누락/오타/규칙 위반)

Validator 필수 체크 항목

• species.json id ↔ 폴더 존재 여부 일치
• Lite 필수 2장 (habit + detail) 누락 탐지
• 파일명 규칙 위반 탐지
• 중복/0바이트/손상 파일 체크
• EXIF 제거 여부 확인

// ------------------------------------------ //
// ------------------------------------------ //

4. 작업 로그 (최신순)

2026-02-15

완료

• Android Studio 새 프로젝트 생성
• App: TreeStudy
• Package: com.reuno.treestudy
• Min SDK: 26, Kotlin DSL
• 실기기(A33) Run 확인 OK
• Phase 1 데이터 생성 (PC)
• species_phase1.json 생성
• assets/lite// 이미지 2장 세트 구성
• 앱 assets 구성 (Android)
• 경로: app/src/main/assets/
• data/species_phase1.json
• lite//
• MVP UI 흐름 완료
• Home: Phase 1 수종 목록 표시
• 목록 → 상세 진입
• 상세: habit 1장 + detail 1장 표시 성공

수정

• JSON 주석 제거
• 원인: species_phase1.json 상단 // 주석으로 파싱 실패
• 조치: 주석 제거 → 정상 로딩

Next

• 한글명 표시 필드 추가 (name_ko)
• 검색 기능 (자동완성) 1차 구현
• 비교 기능 (comparisons_phase1.json 포맷 확정)
• 썸네일 적용 검토

// ------------------------------------------ //
// ------------------------------------------ //

5. 부록

Top 20 수종 (Phase 1)

순위	한글명	ID (영문)	카테고리
1	감나무	persimmon	FRUIT_TREE
2	소나무	pine	CONIFER_EVERGREEN
3	대추나무	jujube	FRUIT_TREE
4	단풍나무	maple	BROADLEAF_TREE
5	매실나무	maesil_plum	FRUIT_TREE
6	배나무	pear	FRUIT_TREE
7	복숭아나무	peach	FRUIT_TREE
8	사철나무	euonymus_japonicus	SHRUB_LANDSCAPE
9	자두나무	plum	FRUIT_TREE
10	뽕나무	mulberry	FRUIT_TREE
11	영산홍	azalea_youngsan	SHRUB_LANDSCAPE
12	사과나무	apple	FRUIT_TREE
13	무궁화	rose_of_sharon	SHRUB_LANDSCAPE
14	아로니아	aronia	FRUIT_TREE
15	주목	yew	CONIFER_EVERGREEN
16	향나무	juniper	CONIFER_EVERGREEN
17	두릅나무	angelica_tree	BROADLEAF_TREE
18	측백나무	thuja	CONIFER_EVERGREEN
19	장미	rose	SHRUB_LANDSCAPE
20	포도나무	grapevine	FRUIT_TREE

---

Top 50 수종 (Phase 2 확장)

A) 과실·열매 (17종)

• 감나무 (1122)
• 대추나무 (1038)
• 매실나무 (752)
• 배나무 (740)
• 복숭아나무 (674)
• 자두나무 (474)
• 뽕나무 (470)
• 사과나무 (445)
• 아로니아 (394)
• 포도나무 (338)
• 앵두나무 (292)
• 보리수 (306)
• 오가피 (272)
• 모과 (270)
• 살구나무 (253)
• 블루베리 (238)
• 호두나무 (207)

---

B) 침엽·상록 (10종)

• 소나무 (1043)
• 주목 (370)
• 향나무 (361)
• 측백나무 (339)
• 은행나무 (282)
• 반송 (272)
• 에메랄드그린 (209)
• 노간주나무 (추가/교체)
• 편백나무 (추가/교체)
• 전나무 (추가/교체)

---

C) 활엽 교목 (8종)

• 단풍나무 (772)
• 두릅나무 (359)
• 느릅나무 (266)
• 옻나무 (238)
• 느티나무 (222)
• 가죽나무 (211)
• 산수유 (206)
• 버드나무 (157)

---

D) 관목·조경·화목 (12종)

• 사철나무 (479)
• 영산홍 (461)
• 무궁화 (431)
• 장미 (338)
• 회양목 (318)
• 남천 (281)
• 화살나무 (209)
• 라일락 (205)
• 철쭉 (205)
• 산딸나무 (추가/교체)
• 꽝꽝나무 (추가/교체)
• 해당화 (113, 2차 후보)

// ------------------------------------------ //

비교쌍 10개 (Phase 1 우선)

Phase 1 즉시 노출 5쌍 (Top 20 내 양쪽 존재)
1. 측백나무 vs 향나무
2. 매실나무 vs 자두나무
3. 자두나무 vs 복숭아나무
4. 사과나무 vs 배나무
5. 감나무 vs 대추나무

Phase 2 종 필요 (데이터만 준비, 자동 숨김)
6. 향나무 vs 노간주나무
7. 주목 vs 노간주나무
8. 측백나무 vs 에메랄드그린
9. 전나무 vs 독일가문비나무
10. 매실나무 vs 살구나무

노출 규칙: Phase 1에서는 즉시 노출 5쌍만 활성화, 나머지는 종 추가 시 자동 활성화

---

비교쌍 20개 전체 (확장)

침엽/상록 핵심 (9쌍)

1. 측백나무 vs 향나무
2. 향나무 vs 노간주나무
3. 측백나무 vs 에메랄드그린
4. 향나무 vs 에메랄드그린
5. 주목 vs 향나무
6. 주목 vs 측백나무
7. 소나무 vs 반송
8. 소나무 vs 잣나무
9. 전나무 vs 편백나무

그룹: 측백/향나무/노간주/에메랄드그린/주목 (2개 선택 비교)

---

과실·장미과 혼동군 (6쌍)

1. 매실나무 vs 살구나무
2. 매실나무 vs 자두나무
3. 자두나무 vs 복숭아나무
4. 체리나무 vs 앵두나무
5. 감나무 vs 대추나무
6. 배나무 vs 팥배나무

---

관목/조경 혼동군 (5쌍)

1. 회양목 vs 꽝꽝나무
2. 산수유 vs 산딸나무
3. 영산홍 vs 철쭉
4. 남천 vs 화살나무
5. 사과나무 vs 배나무

// ------------------------------------------ //
// ------------------------------------------ //

다운로드팩 구조 (유료화 대비)

기본 원칙

• 팩은 단일 zip + manifest.json + 해시(sha256)
• 다운로드 → 검증 → 압축해제 → 설치 완료 마킹
• 검증 실패 시: 설치 안 됨 처리 (손상/부분 설치 방지)

팩 단위 (권장)

• Phase 1: Full Pack 1개로 시작
• Phase 2: 카테고리별 팩 (침엽·상록팩 / 과실팩 / 조경·관목팩)
• 내부 구조는 다중 팩 확장 가능하게 설계

유료(Pro) 구성 (예: 3,900원)

Lite (무료)
- 종당 2~3장 (habit + detail + fruit)
- 비교 기능 동일 제공
- 오프라인은 Lite만 보장

Pro (유료)
- Full 사진팩 오프라인 제공
- 사진 수 확장 (파트별 다장) + 줌 최적화
- 팩 설치/업데이트/복구 UX
- (Phase 2) 싱크 스크롤 비교 전용

// ------------------------------------------ //
// ------------------------------------------ //

문서 이력

• v2.4 (2026-02-17): 홈 검색바 📷 사진인식 도입 기획 확정 (세부 사항은 개별 Photo Recognition 문서 참조)
• v2.3 (2026-02-15): 카테고리 화면 UI 정리(TopAppBar 타이틀 제거/정리), 카테고리 배너 이미지(R.drawable.webp) 연동 및 표시 정상화, 세그먼트 체크 아이콘 제거 및 외곽 테두리 제거(버튼 경계만 유지), CategoryBanner/CategorySegment 위치 정리(CategoryScreen.kt로 정착), R.drawable 참조/임포트 이슈 해결
• v2.2 (2026-02-15): 다크/라이트 테마 전환 UX 정리(해/달 아이콘), 전환 이펙트 이질감 개선, 카테고리 카드 텍스트 칩 제거(텍스트+섀도우로 대체), 카드 하단 스크림 보강, 활엽/조경 카테고리 배경 이미지 교체
• v2.1 (2026-02-15): 경로 표기 통일, ID/폴더명 규칙 명시, Phase1 비교 5쌍 우선순위 명확화
• v2.0 (2026-02-15): 5개 섹션 재구조화, 아이콘 최소화, 수평선 구분 추가
• v1.0 (2026-02-14): 초안 작성 (합의/보류/폐기 로그 포함)