mycode/myApp/HaruDanim/Docs/plan-1.5.md

하루 다님 1.5 확정 계획

상태: 구현 대기 — 사용자가 "진행"이라고 지시할 때만 착수한다. 그 전까지 코드 무변경. 작성 2026-08-20. 근거: 2026-08-20 세션에서 사용자 위시리스트 → 분석 보고 2회 → 사용자 결정 4건(아래 결정 이력)으로 확정. 구현 시 이 문서를 명세로 삼고, 완료된 항목은 CLAUDE.md 현행 명세에 흡수한 뒤 이 문서에 완료 표기할 것.

0. 범위 요약

#	기능	과금	규모
1	워치 행동 컴플리케이션 (기간 선택·미니 행동 화면 착지)	프리미엄(워치 자체가 프리미엄)	중간
2	건강 데이터 통합 — 모음 탭 타일(표시) + 건강 다짐	타일 무료 + 건강 다짐 프리미엄	큼
3	도움말(HelpView) 전체 문구 한국어 자연화 (2026-08-12 예약분)	—	중간

제외 확정: 하위 OS 인하(§4 기각 기록), 워치 스마트 스택 인터랙티브 위젯, 모음 탭 스와이프 페이지 배치.

1. 결정 이력 (2026-08-20 사용자 답변)

1. 컴플리케이션 탭 착지 = 미니 행동 화면 신설 (기존 목록 스크롤 기각)
2. 건강 타일 배치 = 타일 줄 + 접기 (스와이프 페이지 기각 — 목표 카드 가로 페이징·배치 편집 드래그와 제스처 충돌, 발견성 낮음)
3. 건강 다짐 v1 지표 = "지표 더 추가" 선택 — 구체 세트는 미지정. 아래 §3.4의 8종 제안을 착수 시 사용자 확인으로 확정할 것 (수면 주간 합산은 선택지에서 미채택 → v1 제외)
4. 과금 = 타일 무료 + 건강 다짐 프리미엄
5. (앞선 보고에서) 하위 OS 철회, 스마트 스택 불요, 표시 기간 옵션은 달력 주기+롤링 둘 다, 건강은 표시·다짐을 한 버전에 통합(감수사항 3건 §3.1 전제)
6. 후속 추가(2026-08-20): ①컴플리케이션 착지 미니 화면은 뒤로가기로 워치 앱 메인 복귀(push 구조 필수) ②모음 탭 건강 섹션은 설정에서 표시 on/off + 즐겨찾기·나머지 행동·건강 3섹션 순서 지정(목표 카드 선택 설정 아래 배치). 이후 추가 요구는 사용자가 그때그때 전달 예정 — 이 문서에 계속 반영할 것

2. 기능 1 — 워치 행동 컴플리케이션

스펙

• 옵트인+기간 설정(아이폰): 행동 편집 화면에 '애플워치 컴플리케이션' 토글, 켜면 표시 기간 선택: 하루 / 이번 주 / 이번 달 / 지난 7일 / 지난 30일. 저장은 기기 로컬 LocalPrefs 신설 키(uuid→기간 맵, local.watchGoals와 동일 계열 — 워치는 이 아이폰과 페어링이므로 기기 로컬이 자연스러움).
• 표시: 원형=행동 아이콘 + 큰 값(횟수형 "N회", 시간형 압축 표기 "47분"·"1:12"류). corner/inline/rectangular 대응(rectangular는 아이콘+이름+값). 측정 중이면 노란 시그널 + 실시간 타이머 — '현재 현황' 컴플리케이션의 tickingBase 방식(스냅숏 시점 − 누적초)과 유령 타이머 2시간 안전장치(runningTrustInterval) 재사용. 주·월 기간에도 tickingBase 산식 동일 적용 가능.
• 탭 동작: widgetURL 딥링크 → 워치 앱 미니 행동 화면(신설): 아이콘+이름+설정 기간 누적값+큼직한 실행/종료(횟수형은 +1) 버튼. 실행은 기존 run 명령 재사용. 자동 실행 금지(손목 오탭 방지 — 명시적 버튼 탭 문법 유지). 뒤로가기 필수(사용자 요구 2026-08-20): 미니 화면은 워치 앱 첫 화면(메인 목록) 위에 push로 착지 — 뒤로가기 한 번에 기존 메인으로 복귀, 앱을 종료·재실행할 필요가 없어야 함(딥링크가 고립 화면이 되지 않게 내비게이션 스택 구성).
• recommendations: 옵트인 행동 전부 나열(상한 금지 — §11 규칙), 기간은 아이폰 설정값이 반영된 단일 항목. 스냅숏 적용 시 기존 invalidateConfigurationRecommendations() 경로로 자동 갱신.
• 갱신 특성(의도된 한계): 기존 컴플리케이션과 동일 — 스냅숏 push + 15분 .after 타임라인. 아이폰 +1 직후 페이스 반영은 수 분 지연 가능, 측정 시작/종료는 transferCurrentComplicationUserInfo 즉시 푸시 경로 기존과 동일.

데이터 배선

• WatchActionInfo에 optional 필드 추가: 설정 기간 식별 + 그 기간 누적값(예: complicationPeriodRaw, periodValue). 구버전 캐시 호환은 기존 optional 패턴(isFavorite·runningActionID 선례). makeSnapshot이 옵트인된 행동만 기간값을 계산(페이로드 절약).
• 롤링 창은 1.4의 DayMath.rollingRange 재사용. ⚠️ StatSpan enum 케이스 추가 금지(§6.6 경고 준수) — 기간+롤링 플래그로 처리. 수치는 통계 탭과 동일해야 함(Aggregator 경유).

영향 파일(예상)

WatchShared/WatchPayload.swift(필드) · IOS/Core/WatchSyncManager.swift(makeSnapshot) · Haru_DanimWatchWidgets/(신규 컴플리케이션 1종) · 워치 앱(미니 행동 화면 + widgetURL 라우팅) · IOS/Views/ActionViews.swift(편집 토글+기간 선택) · Shared/LocalPrefs.swift(신설 키) · l10n: IOS+워치 카탈로그.

검증

-complicationPreview에 신규 종 포함, 워치 심 11.5·26.2 렌더, 기간별 수치를 통계 탭과 대조, 구버전 스냅숏 캐시 폴백(기간 필드 없음 → 하루 폴백), 딥링크 착지·실행·오탭 시나리오, ko/en/ja.

3. 기능 2 — 건강 데이터 통합 (HealthKit)

3.1 전제 (사용자 감수 확정)

1. 위젯의 건강 수치는 실시간이 아님 — 마지막 앱 갱신+백그라운드 딜리버리(걸음 등 누적형은 시스템상 최대 시간당 1회) 기준.
2. 기기별 데이터 편차 상태 신설 — 아이폰=완전 / 아이패드=사용자가 시스템 건강 iCloud 동기화를 켠 경우만 / 맥(Designed for iPad)=HealthKit 없음 → 타일 섹션 숨김·건강 다짐은 "이 기기에선 건강 데이터 없음" 상태('수행일 아님' 패턴 계열의 새 표시 상태).
3. 큰 버전 — 내부 2단계(타일 먼저 완성 → 다짐 얹기) 순서로 구현, TestFlight 자가 테스트 기간 넉넉히.

3.2 아키텍처 — HealthCache (핵심)

• 메인 앱만 HealthKit을 조회해 App Group에 "지표×dayKey→값" 캐시를 유지(포그라운드 진입 + HKObserverQuery/백그라운드 딜리버리 때 갱신 후 위젯 리로드). 화면·위젯·시리·판정·연속 계산은 전부 이 캐시를 동기 조회 — QuestProgress의 동기 계산 세계를 깨지 않는다. 위젯 확장은 HealthKit 직접 조회 불가이므로 캐시가 유일 경로.
• 워치: 워치에서 HK 직조회하지 않음 — 건강 다짐 값도 다른 다짐처럼 아이폰이 계산해 스냅숏에 실어 보냄(스냅숏이 곧 캐시 push, 추가 구조 불요).
• ⚠️ 심사 지침 5.1.3 — HealthKit 데이터를 iCloud(CloudKit)에 저장 금지: HK 값은 절대 SwiftData/CloudKit에 넣지 않는다(App Group 캐시는 기기 로컬이라 무방). 다짐의 정의(지표·목표량·방향·수면 구간)는 일반 데이터이므로 동기화 OK. → "정의는 동기화, 값은 기기별 자기 HealthKit"이 동기화 모델의 전부.
• 읽기 권한은 거부돼도 감지 불가(빈 값이 옴 — 애플 프라이버시 설계) → "표시할 데이터 없음" 상태로 흡수, 권한 재요청 유도 문구는 안내 수준만.

3.3 타일(표시 전용, 무료)

• 형태: 가로 스크롤 컴팩트 타일 줄 + 접기(즐겨찾기/나머지 섹션과 같은 접힘 문법, 접힘 상태 기기 로컬).
• 모음 탭 배치 = 설정으로 제어(사용자 요구 2026-08-20): 설정 탭 모음 탭 영역(목표 카드 선택 아래)에 ①건강 데이터 표시 on/off ②표시 시 즐겨찾기 / 나머지 행동 / 건강 데이터 3섹션의 표시 순서 지정 UI 신설(기기 로컬 저장 — 보기 설정 계층). 목표 현황 카드·'현재 진행 중' 영역은 기존대로 상단 고정, 순서 지정 대상은 위 3섹션만(다른 해석 원하면 착수 전 확인).
• 우상단 버튼 → 지표 선택 시트(표시할 지표 체크+순서, 기기 로컬 — 표시 지표는 다짐 가능 8종보다 넓게 제공 가능).
• 상태 처리: 맥=섹션 숨김 / 권한 없음·데이터 없음=상태 문구 타일 / 아이패드=자기 HK 기준.
• 운동은 종목별 집계 가능(HKWorkout.workoutActivityType) — 타일 v1은 '운동 시간(엑서사이즈 분)' 기준, 종목별은 후속 후보로만.

3.4 건강 다짐 (프리미엄)

• 모델: Quest에 건강 대상 필드 신설(예: healthMetricRaw 기본 "" — §3 CloudKit 규칙 준수: 기본값+스키마 안전). 대상 3유형째(행동/꼬리표/건강 지표). 수면 구간 필드(시작·끝 분, 기본값) 추가.
• v1 지표 세트(제안 8종 — 착수 시 사용자 확인으로 확정): 걸음 수(회 표기 계열) · 운동 시간 · 수면(특수) · 활동 에너지(kcal) · 이동 거리(km) · 스탠드 시간 · 마음챙김 분 · 물 섭취(L). 수면 외 7종은 전부 "논리적 하루 창의 누적 수량"으로 구조 동일 — 한 어댑터로 처리.
• 수면 귀속 규칙(사용자 설계, 2026-08-20): 다짐 전용 수면 구간(기본 전날 21:00 ~ 당일 09:00, 사용자 지정 가능) 안의 수면 합을 '깨어난 날' 하루에 통귀속. ⚠️ 시간 세션의 겹침 분할과 다른 규칙이지만 의도된 예외(수면은 깬 날의 것으로 세는 도메인 관습 — deadlineMinutes와 같은 '다짐 전용 측정 창' 계열의 확장). 소스 중복(아이폰+워치 동시 기록)은 '잠듦' 구간 합집합 병합. 하루 단위 전용(요일 스케줄 가능), 주간 합산 다짐 v1 제외.
• 진행률 의미론 — 기존 §4.2와 완전 동일 유지: atLeast 게이지 min(값/목표,1)·퍼센트 초과 표기, atMost, 마감 시각(누적형 지표에 적용 가능), 연속 달성(하루 버킷·시작일 하한·400일 상한), 판정 시점 클리핑, 주기 몫 완료, 수행일 아님. HealthProgress 어댑터가 QuestProgress와 같은 수치 계약을 지키고, 값 공급원만 HealthCache로 다름.
• 과금 게이트: 건강 다짐 생성 = 프리미엄(PremiumManager 경유 — canAddQuest에 건강 분기 또는 전용 판정). 만료 정책은 기존 원칙(이미 만든 것은 유지, 추가 생성만 제한)을 따를지 착수 시 확정.
• 파급 표면(전수): QuestEditorView(대상 3유형째+지표 픽커+수면 구간 UI — CollapsibleTimeWheel 재사용) · 목표 탭 행 · 모음 카드 · 일기 '이 날의 목표'(과거 날짜는 캐시/실조회) · 위젯 ②③④(캐시 조회) · 워치(스냅숏 동승) · 시리 다짐 조회 · evaluateIfEnded 판정 · CSV(다짐 CSV에 건강 다짐 행 — 기록 CSV 무영향, 가져오기 비대상 유지 §6.8) · 무료 한도 카운트(목표당 3개에 귀속).

3.5 심사·문서 체크리스트

• HealthKit 엔타이틀먼트 + NSHealthShareUsageDescription(ko/en/ja — InfoPlist.xcstrings).
• Docs/PRIVACY.md에 건강 데이터 문단 추가 필수(5.1.3 요구): 읽기 전용·기기 밖 전송 없음·iCloud 저장 없음 명시. 개인정보 라벨 "데이터 수집 안 함" 유지 가능(개발자 서버 전송 없음).
• 결제 화면(PremiumView) 기능 목록에 '건강 다짐' 추가, 도움말 신규 주제(§5), Marketing 자료 갱신(§6).

3.6 검증

• -progressSelfTest에 건강 어댑터 시리즈 추가(HealthCache 주입식 인메모리 — 실 HK 비의존): 수면 구간 경계(자정 걸침·구간 밖 수면·하루 시작 시간 05:00 조합), atLeast 캡·초과, 연속, 판정 클리핑.
• 시뮬 검증용 캐시 시드 인자(예: -seedHealthCache) 신설 — 시뮬레이터 HK 실데이터 없이 전 표면 렌더 확인.
• 기기별 상태: 맥 분기 -forceMacLayout, 권한 없음/데이터 없음 상태, 아이패드 심.

4. 하위 OS 인하 — 기각 기록 (재제안 방지)

2026-08-20 검토 후 사용자 철회. 근거(재검토 시 참고): ①iOS 17·18은 지원 아이폰 목록 동일(XS/XR 이후) → 인하해도 신규 커버 아이폰 0대, 노치 중 미지원은 iPhone X(iOS 16 최대)뿐 ②iPadOS 17 인하 시 추가는 iPad 6세대·Pro 10.5"·Pro 12.9" 2세대(2017~18) 3기종뿐 ③iOS 16 이하는 SwiftData(17+)라 데이터층 재작성 = 불가 ④17 지원 실비용: LiveActivityIntent(17.2 도입) 채택 인텐트 4종 구조 수술 + 제어 센터 API 3곳·ControlWidget 18 가드 + 심볼 감사·QA 라인 추가 + 17 SwiftData 안정성 리스크. 재검토 트리거: 구형 기기 사용자의 실제 설치 문의 발생 시(아이패드만 따로 인하 불가 — 배포 타깃 공용 유의).

5. 기능 3 — 도움말 한국어 자연화 (예약분, 사용자 지시 2026-08-12)

• HelpView 전체 문구를 한국어 기준으로 재작성 — 말투 컨셉(~해요체) 유지, 번역투·어색한 단어 선택·문장 구성 정리. en/ja도 함께 재검토.
• 1.5 신규 기능 주제 추가와 병행: 행동 컴플리케이션(워치 그룹), 건강 타일·건강 다짐(그룹 배치는 구현 시 결정, 이미지는 그룹당 대표 1주제 원칙 유지).
• l10n 루틴(§2.3) 필수, 도움말 스크린샷은 문구·화면 변화 정도 보고 재촬영 판단.

6. 공통 마무리 작업 (출시 전)

• MARKETING_VERSION 1.5, Marketing/AppStore/whats-new-1.5.txt, 프로모션 텍스트 1.5판.
• 스크린샷: 모음 탭에 건강 타일이 들어가면 01-main 계열 재촬영 대상 — 착수 시 판단(Marketing/README 절차).
• 자가 검증 전체 회귀(-progressSelfTest 확장분 포함 4종+신규 인자), Debug/Store/워치 빌드, 26+18.5 심 QA.
• CLAUDE.md 현행 명세 갱신(§6.1 모음 탭·§6.4 다짐·§11 워치·§14 인자 등) + 이 문서 완료 표기.

7. 구현 순서 제안

① 행동 컴플리케이션 → ② 건강 타일(권한·HealthCache 기반 공사 포함) → ③ 건강 다짐(어댑터→편집기→전 표면) → ④ 도움말 자연화(신규 주제 포함, 문구가 확정된 마지막에) → ⑤ 마무리(§6). 단계마다 빌드+심 검증+커밋.

8. 착수 시 사용자에게 확인할 것

1. §3.4 지표 8종 제안 확정(빼기/더하기 — 사용자가 "지표 더 추가"만 선택하고 세트는 미지정)
2. 건강 다짐 프리미엄 만료 시 처리(기존 원칙대로 "이미 만든 건 유지"면 확인만)
3. 도움말 스크린샷 재촬영 범위