docs: 1.5 확정 계획 문서화 (Docs/plan-1.5.md) — 구현 대기

- 워치 행동 컴플리케이션: 옵트인+기간 선택, 미니 행동 화면 착지(뒤로가기로 메인 복귀)
- 건강 데이터 통합: 타일 무료+건강 다짐 프리미엄, HealthCache, 수면 구간 귀속,
  모음 탭 3섹션(즐겨찾기·나머지·건강) 순서 설정
- 도움말 한국어 자연화(예약분) 포함, 하위 OS 인하 기각 근거 기록(§4)
- CLAUDE.md 📌를 계획서 포인터로 갱신 — 사용자 "진행" 지시 전까지 코드 무변경

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WtZwRRjbtM9pZJDM4FkTq6

myApp/HaruDanim/Docs/plan-1.5.md

@@ -0,0 +1,108 @@
+# 하루 다님 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. 도움말 스크린샷 재촬영 범위