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 예약분)	—	중간
4	업데이트 신기능 소개 팝업(버전당 1회, 全기기 업데이트 안내 포함)	무료	소

제외 확정: 하위 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섹션 순서 지정(목표 카드 선택 설정 아래 배치). 이후 추가 요구는 사용자가 그때그때 전달 예정 — 이 문서에 계속 반영할 것
7. 후속 승인·추가(2026-08-22): §8 세 건 전부 승인(③ 표시 전용 상속 / 데이터 없는 기기 모수 제외+판정 보류 / 건강 다짐 v1 마감 시각 미지원). 추가 요구: 건강 데이터의 특성(하루 경계·수면 귀속 규칙·값 신선도·기기별 편차)을 도움말에 상세히 설명하고, 건강 데이터를 보는 화면(모음 탭 타일 영역)에도 해당 안내 가이드 문구를 표기할 것. 1.5 도움말 작업은 자연화(예약분)+신규 주제+이 안내를 한 묶음으로 진행. 안정성 최우선 지시: 1.4 기능은 오류 없이 그대로 유지된 채 1.5가 얹혀야 함 — §10 위험 검토가 그 근거 문서
8. 2차 답변(2026-08-22): ①지표 8종 확정 + 운동 세부 종목 다짐 추가(사용자 핵심 니즈 — §3.4) ②프리미엄 만료 처리=기존 원칙(만든 건 유지 — "돈 내고 쓴 기간에 한 건 인정") ③스크린샷=기존 전부 폐기, 아이폰·아이패드 각 10장 신규(스타일 동일·구성 일신 — §6) ④whats-new에 全기기 업데이트 완화 문구 ⑤업데이트 신기능 소개 팝업 신설(§11) ⑥CloudKit 스키마 배포=사용자 기억 없음 → 아리나가 구현 중 확인·준비하고 콘솔 작업 필요 시 시점·절차를 사용자에게 안내(§3.5). 이 반영은 "기록 용도 문서 수정만 허용(코드·프로젝트 파일 금지)" 상태에서 수행

2. 기능 1 — 워치 행동 컴플리케이션 ✅구현 완료(2026-08-22 — 빌드 4종·자가 검증 106건×2심·시각 QA[워치 26.2 실데이터/11.5 빈 상태·미니 화면 뒤로가기·편집기 섹션] 통과)

스펙

• 옵트인+기간 설정(아이폰): 행동 편집 화면에 '애플워치 컴플리케이션' 토글, 켜면 표시 기간 선택: 하루 / 이번 주 / 이번 달 / 지난 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-22 — 타일·순서 설정·지표 선택·안내 시트·CTA·HealthCache·엔타이틀먼트, 26.5+18.5 시각 QA·회귀 106건 그린. ⚠️QA 도구 주의: simctl spawn defaults의 앱그룹 도메인 쓰기가 18.5 심에선 앱그룹 컨테이너에 닿지 않음 — 26.5는 닿음, 검증 시 참고)

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

3.4 건강 다짐 (프리미엄)

• 모델: Quest에 건강 대상 필드 신설(예: healthMetricRaw 기본 "" — §3 CloudKit 규칙 준수: 기본값+스키마 안전). 대상 3유형째(행동/꼬리표/건강 지표). 수면 구간 필드(시작·끝 분, 기본값) 추가.
• v1 지표 세트(확정 2026-08-22): 걸음 수 · 운동 시간 · 수면(특수) · 활동 에너지(kcal) · 이동 거리(km) · 스탠드 시간 · 마음챙김 분 · 물 섭취(L) — 8종. 수면 외 7종은 전부 "논리적 하루 창의 누적 수량"으로 구조 동일 — 한 어댑터로 처리.
• 운동 세부 종목 다짐(확정 2026-08-22 — 사용자 핵심 니즈): '운동'은 전체 합산 외에 종목별 다짐 지원(예: 달리기 30분 이상) — HKWorkout의 종목별 duration 합산(기록된 운동 기준). healthMetricRaw에 종목 파라미터 인코딩(예: workout.running), HealthCache 키도 지표+종목으로 확장(위험 구조는 8종과 동일 — 누적 수량 패턴). 종목 이름은 API가 현지화를 제공하지 않음 → 자체 큐레이션 목록(20종 내외: 달리기·걷기·사이클·수영·근력 운동·요가·필라테스·등산·축구·야구·농구·테니스·배드민턴·골프·줄넘기·복싱·댄스·스트레칭·HIIT·기타)을 ko/en/ja 직접 명명 — 구현 중 목록을 사용자에게 제시해 실사용 종목 포함 확인(비차단), 이후 추가는 케이스+문자열 3개로 저비용. ⚠️'운동 시간'(엑서사이즈 분, 활동 링 기준)과 종목별(기록된 운동 시간)은 값 기준이 다름 — 가이드 문구·도움말에 차이 설명 필수.
• 수면 귀속 규칙(사용자 설계, 2026-08-20): 다짐 전용 수면 구간(기본 전날 21:00 ~ 당일 09:00, 사용자 지정 가능) 안의 수면 합을 '깨어난 날' 하루에 통귀속. ⚠️ 시간 세션의 겹침 분할과 다른 규칙이지만 의도된 예외(수면은 깬 날의 것으로 세는 도메인 관습 — deadlineMinutes와 같은 '다짐 전용 측정 창' 계열의 확장). 소스 중복(아이폰+워치 동시 기록)은 '잠듦' 구간 합집합 병합. 하루 단위 전용(요일 스케줄 가능), 주간 합산 다짐 v1 제외.
• 진행률 의미론 — 기존 §4.2와 완전 동일 유지: atLeast 게이지 min(값/목표,1)·퍼센트 초과 표기, atMost, 연속 달성(하루 버킷·시작일 하한·400일 상한), 판정 시점 클리핑, 주기 몫 완료, 수행일 아님. 단 마감 시각 옵션은 건강 다짐 v1 미지원(§8ⓔ 확정 — 캐시가 하루 단위 값이라 부분 창 미지원, 편집기에서 숨김). HealthProgress 어댑터가 QuestProgress와 같은 수치 계약을 지키고, 값 공급원만 HealthCache로 다름.
• 과금 게이트: 건강 다짐 생성 = 프리미엄(PremiumManager 경유 — canAddQuest에 건강 분기 또는 전용 판정). 만료 정책 확정(2026-08-22): 기존 원칙 그대로 — 이미 만든 건강 다짐은 만료 후에도 유지·표시, 추가 생성만 제한.
• 파급 표면(전수): QuestEditorView(대상 3유형째+지표 픽커+수면 구간 UI — CollapsibleTimeWheel 재사용) · 목표 탭 행 · 모음 카드 · 일기 '이 날의 목표'(과거 날짜는 캐시/실조회) · 위젯 ②③④(캐시 조회) · 워치(스냅숏 동승) · 시리 다짐 조회 · evaluateIfEnded 판정 · CSV(다짐 CSV에 건강 다짐 행 — 기록 CSV 무영향, 가져오기 비대상 유지 §6.8) · 무료 한도 카운트(목표당 3개에 귀속).
• 이중 상태 정규화(혼합 버전 대비 — 2026-08-22 검토): 구버전(1.0~1.4) 편집기가 "대상 없음"으로 보이는 건강 다짐에 행동/꼬리표를 지정·저장하면 지표+행동이 공존할 수 있음 → 판독 규칙은 행동/꼬리표 우선(사람의 최신 의도 존중), 1.5 편집기는 저장 시 반대편 필드를 정리해 일관 상태 복원.

3.5 심사·문서 체크리스트

• HealthKit 엔타이틀먼트 + NSHealthShareUsageDescription(ko/en/ja — InfoPlist.xcstrings).
• Docs/PRIVACY.md에 건강 데이터 문단 추가 필수(5.1.3 요구): 읽기 전용·기기 밖 전송 없음·iCloud 저장 없음 명시. 개인정보 라벨 "데이터 수집 안 함" 유지 가능(개발자 서버 전송 없음).
• 결제 화면(PremiumView) 기능 목록에 '건강 다짐' 추가, 도움말 신규 주제(§5), Marketing 자료 갱신(§6).
• CloudKit 스키마 배포 체크(2026-08-22 — 사용자 기억 없음, 아리나 주도): 착수 첫 단계에서 개발 환경 스키마 생성·CloudKit 콘솔 상태 확인(1.3의 DiaryPageItem 필드 8개가 프로덕션에 있는지도 함께 판독 — 당시 배포 이력 불명). 출시 게이트에서 프로덕션 배포가 필요하면 콘솔 작업은 사용자 계정이 필요 → 아리나가 정확한 절차를 안내하고 사용자가 실행. 배포 없이 1.5를 내보내면 새 필드 동기화가 실패할 수 있으므로 출시 전 필수 관문.

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주제 원칙 유지). 건강 주제는 특성 설명을 상세히(사용자 요구 2026-08-22): 하루 경계 처리, 수면 구간·깨어난 날 귀속, 위젯 신선도(실시간 아님), 기기별 편차(아이폰/아이패드/맥), 판정 보류 규칙, 데이터가 기기 밖으로 나가지 않는다는 점 — 모음 탭 가이드 문구(§3.3)와 동일 내용의 확장판.
• l10n 루틴(§2.3) 필수, 도움말 스크린샷은 문구·화면 변화 정도 보고 재촬영 판단.

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

• MARKETING_VERSION 1.5, Marketing/AppStore/whats-new-1.5.txt("여러 기기를 쓰면 모든 기기에서 업데이트" 완화 문구 포함 — 확정 2026-08-22), 프로모션 텍스트 1.5판.
• 스크린샷 전면 신규 제작(확정 2026-08-22): 기존 세트 전부 폐기, 아이폰 10장·아이패드 10장 × ko/en/ja 신규(스타일은 현재와 동일, 구성·이미지 일신 — 1.5 기능 반영. 워치 합성 1장 유지 여부는 시안 때 결정). 촬영·합성은 Marketing/README 절차 준용, 장면 구성 시안은 마무리 단계에서 사용자 확인.
• 자가 검증 전체 회귀(-progressSelfTest 확장분 포함 4종+신규 인자), Debug/Store/워치 빌드, 26+18.5 심 QA.
• CLAUDE.md 현행 명세 갱신(§6.1 모음 탭·§6.4 다짐·§11 워치·§14 인자 등) + 이 문서 완료 표기.

7. 구현 순서 제안

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

8. 건강 다짐 × 위젯 전수 점검 (2026-08-20 후속 분석 — 사용자 질문 "③ 인터랙티브 위젯 처리")

• ③ 다짐 링(인터랙티브): 건강 다짐 셀은 꼬리표 대상 다짐과 동일 문법 — 버튼 없는 표시 전용 셀, 탭=앱 열기(§10에 '의도된 동작'으로 기존 문서화). 누적값 줄은 HealthCache 값, atMost·주기 몫 완료 등 표시 상태 전부 상속. 셀에 지표 심볼 소표기(디자인 디테일). ✅확정(사용자 승인 2026-08-22)
• 무관(행동·세션 전용): ① 행동 실행 · ⑥ 현재 진행 중 · 제어 센터 · Live Activity.
• 표시 전용이라 구조 무관, 캐시 값만 소비: ② 목표 바 · ④ 다짐 그리드 · 잠금화면(다짐 점·게이지 포함).
• ⑤ 행동 통계 = 건강 비대상 선언 — 통계 탭·⑤는 행동 기반, 건강 표시는 모음 탭 타일 담당(범위 못 박기).
• 위젯 공통: ⓐ갱신 경로 신설 — DataChange.commit 외에 백그라운드 딜리버리→캐시 갱신→reloadAllTimelines(주기 폴링 아님, §10 예산 전략과 충돌 없음. 신선도=시간 단위 감수 §3.1) ⓑ하루 경계는 기존 타임라인 안전망으로 새 날 0 리셋 자동 ⓒ데이터 없는 기기(맥 데스크톱 위젯·건강 미동기화 아이패드): 건강 다짐 셀을 '수행일 아님' 문법 재사용(② 대시·③ 문구·④ 흐림)으로 '데이터 없음' 표시 + combinedSpanRatio 모수에서 제외(§4.3 하루 span 선례와 동일 문법) ✅확정(사용자 승인 2026-08-22) ⓓ③④ 슬롯 픽커에 건강 다짐 표시명 노출, 과금은 위젯=프리미엄이라 자연 정합.
• 파생 결정 2건: ⓔ건강 다짐 v1 마감 시각 옵션 미지원(숨김) 추천 — 캐시가 하루 단위 값이라 부분 창은 시간대 캐시가 따로 필요, 실익 대비 과함(수면은 자체 구간 보유. §3.4의 "마감 적용 가능" 표기는 이 결정으로 대체) ✅확정(사용자 승인 2026-08-22) ⓕ판정 보류 규칙(중요): 건강 다짐 포함 목표의 자동 판정(evaluateIfEnded)은 건강 데이터 가용 기기에서만 실행 — 불가 기기(맥 등)에선 보류해 다음 가용 기기 실행 때 판정(빈 캐시로 미달성 오판→CloudKit 전파 방지) ✅확정(사용자 승인 2026-08-22)

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

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

(§8의 3건은 2026-08-22 사용자 승인으로 확정 — 결정 이력 7 참조)

10. 구현 전 정밀 위험 검토 (2026-08-22 — "1.4 무결 보존" 지시에 따른 전수 점검)

10.1 실코드로 확인된 안전 근거 3건

• R1 크로스 버전 동기화(최대 우려 해소): 1.5가 만든 건강 다짐이 CloudKit으로 1.4 기기에 내려가면 targetAction·targetTag 둘 다 nil인 다짐으로 보인다 — 1.4 코드는 이미 Quest.targetName이 "대상 없음"(Models.swift:422, l10n 완비)·targetSymbol이 tag.fill로 폴백하고, 진행률은 targetActions 빈 배열이라 0%(atLeast) 안전 강등. 크래시 경로 없음(실코드 확인). 잔여 무해 오표시: atMost 건강 다짐이 1.4에서 '한도 지킴'으로 보임 + 1.4 편집기로 그 다짐을 열어 저장하면 대상이 바뀔 수 있음(사용자 규모·단일 기기 위주로 위험 수용, 구현 시 재확인)
• R2 QuestProgress 이음새: 값 산출이 agg.seconds/count(for: quest.targetActions, …) 5개 지점(current 149-150 · spanProgress 267-268 · 287-288 · streak 411)으로 수렴 — 단일 값 공급 헬퍼로 묶어 기록/건강(캐시) 분기하면 수학 로직 무변경. 기존 -progressSelfTest 49건 무변경 통과가 1.4 보존의 회귀 증거(주기 몫 완료 때와 같은 검증 문법)
• R3 워치 스냅숏 호환: 직렬화가 JSONEncoder/Decoder(WatchPayload.swift:57-61) — 구워치×새스냅숏=미지 키 무시, 새워치×구캐시=optional nil. 양방향 안전(isFavorite·runningActionID 선례 동일)

10.2 위험 등록부 (상=회귀 가능성 실재 / 중=설계로 예방 / 하=QA로 커버)

• [상] R4 MainView 금지구역: 건강 섹션·3섹션 순서는 §6.1 실기기 버그 이력 지대(iPad 비-lazy AdaptiveColumnsLayout·셀 높이 규칙·드래그 델리게이트)를 지나감. 완화: actionGrid 빌더·레이아웃 코드 무변경, 건강 섹션은 독립 뷰로 VStack 순서만 재배열, 편집(배치) 모드에서는 건강 섹션 숨김(드롭 델리게이트 상호작용 원천 차단), 순서 기본값=즐겨찾기→나머지→건강+표시 기본 ON(첫 타일은 권한 CTA — 권한 요청은 탭에서만)
• [상] R5 판정 무결: evaluateIfEnded는 아무 기기에서나 실행 — 건강 다짐 없는 목표의 판정 경로는 분기 없이 기존 코드 그대로(래핑 금지). 건강 포함 목표만: 판정은 인앱이므로 판정 시점 HK 실조회(권위 경로 — 캐시 희소성 무관, judgmentReference 클리핑 자연 충족), 가용성 없으면 보류(§8ⓕ)
• [상] R6 l10n 대량 변경: 자연화+신규 문자열+가이드 문구 = §2.3 오염 함정(Xcode 재저장 stale 대란 실전 이력) 최대 노출 구간. 완화: 자연화는 마지막 단계로 분리, 단계마다 타깃별 sync·전 카탈로그 missing/stale 0 확인, DEBUG manual 문자열 불가침
• [중] R7 makeSnapshot 비용: 기간값은 옵트인 행동만 계산, -seedBulk 1만 건으로 커밋→푸시 지연 실측(필요 시 기간 창 1회 페치+버킷 공유 — StatsData 문법)
• [중] R8 수면 귀속 총칙: "수면 구간의 끝이 속한 논리적 하루에 귀속"으로 일반화 — 하루 시작 시간이 어떤 값이어도 정의됨(끝=하루 시작 정각이면 그 하루 포함 명시). 구간 길이 UI 상한(예 20시간). 구간·하루 시작 변경 시 재계산은 기존 설정 변경 동작과 동일(값은 HK 소유라 정의만 변경)
• [중] R9 스트릭 백필: 권한 승인 시 과거 400일 1회 백그라운드 백필 — 완료 전 연속 과소 표시 과도기(가이드 문구 한 줄). 캐시 보존 지표당 400일
• [중] R10 초기화 상호작용: '전체 초기화'에 HealthCache·건강 로컬 키 청소 추가(-dataResetTest 확장). 범위 삭제는 무관(값이 HK 소유)
• [중] R11 엔타이틀먼트 격리: HealthKit 엔타이틀먼트·usage description은 iOS 앱 타깃만 — 위젯·워치 타깃 무변경(프로비저닝·심사 잡음 방지)
• [중] R12 컴플리케이션 구성 잔존: 옵트아웃/삭제 행동이 페이스에 남으면 첫 옵트인 행동 폴백→없으면 빈 상태+해결 안내(§11 목표 폴백 문법). recommendations description은 Text(verbatim:)만(§11 즉사 경고)
• [하] R13 iOS 18 하한: 신규 API 전부 iOS 18/watchOS 10 이하 확인(HK 통계·옵저버 쿼리는 구식 API라 안전), 18.5 심 Release 포함 빌드 확인(플랫폼 행 컴파일러 크래시 전례 — 제네릭 중첩 코디네이터 패턴 회피)
• [하] R14 위젯 규칙: 건강 셀은 버튼 없음이라 invalidatable/히트 영역 함정 해당 적음, 하루 경계는 기존 타임라인 안전망으로 새 날 0 리셋 자동(§8ⓑ)
• [하] R15 도움말 이미지: 자연화는 문구 변경이라 예시 이미지 18장 재촬영 원칙 불필요(앱 화면 예시), 모음 탭 이미지만 건강 타일 반영 여부 판단(§9-3) — ※스토어 스크린샷은 별개로 전면 신규(§6, 2026-08-22 확정)
• [기록] R16 혼합 버전(1.0~1.4 × 1.5) 검토 결과(2026-08-22): 1.0 RC(f05e611) 실코드로 targetName "대상 없음"·targetActions [] 폴백이 1.0부터 존재 확인 — 전 버전 안전 강등, 대상 강제 언래핑 0, KVS 무변경, 워치는 과도기만(R3). 잔여 특이 2건: ⓐ구버전 기기가 건강 포함 목표를 먼저 자동 판정하면 미달성 오판 가능 — 1.5 기기에서 종료일 재저장→재판정으로 회복, 팝업(§11)·whats-new 全기기 업데이트 안내로 완화 ⓑ구버전 편집 시 이중 상태 — §3.4 정규화 규칙으로 해소

10.3 안정성 실행 수칙 (전 단계 공통 — 사용자 지시 2026-08-22 "1.4 무결 보존")

1. 격리 원칙: 신규 코드는 신규 파일 우선(HealthStore/HealthCache/HealthProgress·신규 컴플리케이션·미니 화면), 기존 파일은 가산적 분기만. 금지구역(§6.1 lazy·§6.5 휠 구조·§10 invalidatable·§11 verbatim·§6.6 StatSpan) 진입 전 재확인
2. 단계 게이트: §7 순서의 각 단계 끝마다 자가 검증 전체(기존 49·20·27·10 + 신규) ALL PASS + Debug/Store/워치 빌드 + 26·18.5 심(워치 11.5·26.2) 시각 QA + 커밋. 이전 단계 그린 없이 다음 단계 진입 금지
3. 출시 게이트: 전 단계 완료 후 TestFlight 실기기 소킹(사용자) → PRIVACY.md·심사 체크(§3.5) 동반 제출

11. 기능 4 — 업데이트 신기능 소개 팝업 (2026-08-22 사용자 추가)

• 업데이트 후 첫 실행 시 스플래시 뒤 버전당 1회 표시되는 신기능 소개 시트(통상의 "이번 업데이트" 팝업 관습): 1.5 신기능 카드(행동 컴플리케이션·건강 타일·건강 다짐·도움말 개편) + "여러 기기를 쓰신다면 모든 기기에서 업데이트해 주세요" 안내 1줄(혼합 버전 완화 — §10 R16 연계).
• 표시 규칙: standard defaults에 마지막 표시 버전 기록(예: whatsnew.lastShownVersion) — 저장된 버전과 현재 버전이 다르고 소개 콘텐츠가 있는 버전일 때만 표시, 닫는 즉시 기록(재표시 없음). 신규 설치는 미표시(첫 실행 안내는 온보딩 담당 — 최초 실행 시 현재 버전을 시드). 온보딩과 동시 표시 금지(온보딩이 우선).
• 구조는 OnboardingView 스타일 재사용, 향후 버전에서 콘텐츠만 교체 가능한 구조로. l10n 3언어, 검증 인자(예: -showWhatsNew) 신설.