🐛 HealthKit 기록 실패 복구 처리

[gaeng2y]

📝 Summary

HealthKit 수분 기록 쓰기 실패가 앱, AppIntent, Watch에서 조용한 성공으로 처리되지 않도록 복구 가능한 실패 상태를 전달합니다.

🎯 Type of Change

• ✨ New feature (새로운 기능 추가)
• 🐛 Bug fix (버그 수정)
• 🔧 Configuration (설정 변경)
• ♻️ Refactoring (코드 리팩토링)
• 📝 Documentation (문서 수정)
• 🎨 UI/UX (디자인 변경)
• ⚡ Performance (성능 개선)
• 🛡️ Security (보안 강화)
• 🧪 Test (테스트 추가/수정)
• 🔨 Build (빌드 시스템 수정)

🔗 Related Issues

• Closes HealthKit 수분 기록 실패를 앱·AppIntent·Watch에 복구 가능 상태로 전달 #219

📋 Changes Made

Added

• HydrationWriteResult / HydrationWriteFailureReason를 추가해 HealthKit 쓰기 성공/실패를 Domain 경계에서 표현
• Watch mutation 결과 모델을 추가해 snapshot과 쓰기 결과를 함께 전달
• 앱/Watch 실패 안내 문구 및 ViewModel 테스트 추가

Changed

• 앱 물 기록/초기화 흐름이 HealthKit 쓰기 성공 후에만 refresh, undo, Widget timeline reload, 성공 analytics를 실행하도록 변경
• AppIntent가 HealthKit 저장 실패 시 성공 dialog, Widget reload, water_logged analytics를 실행하지 않도록 변경
• Watch 기록/초기화 실패 시 snapshot을 성공처럼 갱신하지 않고 사용자 안내 메시지를 표시하도록 변경
• hydration logging, reliability recovery, analytics 문서에 HealthKit 쓰기 실패 처리 기준 반영

Fixed

• Data layer에서 로깅 후 삼켜지던 HealthKit 쓰기 실패가 앱, AppIntent, Watch 진입점까지 전달되지 않던 문제 수정
• 권한 철회로 인한 쓰기 실패가 설정 이동 CTA 없이 성공처럼 보일 수 있던 문제 수정

Removed

• 없음

🔍 Technical Details

• DrinkWaterUseCase / DrinkWaterRepository의 수분 쓰기 API를 HydrationWriteResult 반환 방식으로 변경했습니다.
• DrinkWaterHealthKitDataSource와 Watch HealthKit data source에서 HealthKitError / HKError를 domain-safe failure reason으로 매핑합니다.
• 실패 analytics는 water_log_failed.failure_reason으로 기록하며, 일반 HealthKit 저장 실패는 healthkit_write_failed로 구분합니다.
• HealthKit source of truth 정책은 유지하고, 실패한 기록을 로컬 pending queue나 별도 원장으로 저장하지 않습니다.

📸 Screenshots / Videos

Before

첨부 없음

After

첨부 없음

✅ Testing

Test Plan

• 앱 빌드 성공
• Debug 모드 정상 작동
• Release 모드 정상 작동
• 기존 기능 영향 없음
• Widget Extension 정상 작동 (해당시)

Test Environment

• iOS Version: N/A
• Device: N/A
• Xcode Version: 로컬 Xcode 환경에서 CoreSimulator/iOS platform 불일치 확인

Test Results

• tuist generate 통과
• make lint 통과
• make arch-check 통과
• git diff --check 통과
• 변경 Domain/Data/WatchData slice swiftc -typecheck 통과
• xcodebuild test / generic iOS build는 로컬 환경의 CoreSimulator 버전 불일치 및 iOS 26.5 platform 미설치로 destination 확인 단계에서 실패

🚨 Breaking Changes

• Yes (아래에 설명)
• No

DrinkWaterUseCase, DrinkWaterRepository, Watch hydration mutation API가 쓰기 결과를 반환하도록 바뀌었습니다. 현재 repo 내부 호출부와 테스트 mock은 함께 갱신했습니다.

📌 Additional Notes

• 실패한 HealthKit 쓰기는 성공 analytics, undo, Widget timeline reload를 발생시키지 않습니다.
• 권한 관련 실패는 설정 이동 CTA를 제공하고, 일반 저장 실패는 재시도 가능한 오류로 안내합니다.

👀 Review Checklist

• 코드가 프로젝트의 코딩 컨벤션을 따르고 있나요?
• 새로운 의존성이 필요한가요?
• 문서 업데이트가 필요한가요?
• 데이터베이스 마이그레이션이 필요한가요?
• 환경 설정 변경이 필요한가요?