[Feat] TTS 음성 선택 버전 호환 추가

[MinHeokChoi]

✨ PR 유형

어떤 변경 사항이 있나요??

• 새로운 기능 추가
• 버그 수정
• 사용자 UI 디자인 변경 및 추가
• 코드에 영향을 주지 않는 변경사항(오타 수정, 탭 사이즈 변경, 변수명 변경)
• 코드 리팩토링
• 주석 추가 및 수정
• 문서 수정
• 테스트 추가, 테스트 리팩토링
• 빌드 부분 혹은 패키지 매니저 수정
• 파일 혹은 폴더명 수정
• 파일 혹은 폴더 삭제

🛠️ 작업내용

• 백엔드 PR Team-Moru/moru-server#125의 계약에 맞춰 음성 변경 응답과 루틴 TTS step DTO/도메인 모델에 selectionVersion: Int64?를 추가했습니다.
• 버전 0은 유효하게 보존하고, 필드 누락은 nil로 디코딩해 구 서버 응답과 호환되도록 했습니다. 방어적으로 음수 값은 신뢰하지 않습니다.
• 현재 선택 버전과 step 버전이 모두 신뢰 가능할 때만 일치 여부를 검사합니다. 둘 중 하나라도 없으면 기존 원격 TTS 재생 정책을 유지하고, 둘 다 있으면서 불일치하면 COMPLETED step도 PENDING과 같은 기존 fallback 흐름을 사용합니다.
• PATCH 성공 응답에서 받은 버전을 memberID별 UserDefaults에 저장합니다. 같은 기기에서는 앱 프로세스 종료·재실행 또는 같은 계정 재로그인 후에도 복원해 버전을 계속 비교합니다.
• 구 서버처럼 PATCH 응답에 버전이 없으면 해당 회원의 오래된 로컬 버전을 삭제합니다. 다른 회원의 저장 값은 건드리지 않아 계정 격리를 유지합니다.
• 기존 RoutineTTSWarmupCoordinator.serverVoiceSelectionDidChange의 prepared plan 제거, 계정별 캐시 삭제, 재워밍 흐름을 그대로 사용했습니다. UI, SwiftData 스키마, 기존 PENDING/FAILED fallback 정책은 변경하지 않았습니다.
• 관련 iOS 작업 범위와 가장 가까운 기존 이슈 #96을 사용해 feat/#96-tts-selection-version 브랜치에서 작업했습니다. 별도 iOS 이슈는 생성하지 않았습니다.

🧪 테스트 결과

• 관련 테스트 52/52 통과
  • 버전 일치 + COMPLETED 원격 재생 가능
  • 버전 불일치 + COMPLETED 원격 재생 차단
  • 현재/step 버전 누락 시 구 서버 호환 재생 유지
  • 음성 변경 뒤 현재 계정의 이전 캐시/prepared plan 미사용
  • DTO 버전 0, 누락, 음수 방어 및 PATCH 버전 전달 검증
  • 앱 재실행을 모사한 coordinator 재생성 뒤 저장 버전 복원
  • UserDefaults 버전 0 영속화와 회원별 격리
  • PATCH 버전 누락 시 현재 회원 값만 제거
• 알려진 3건을 제외한 전체 MoruTests 875/875 통과
• Scripts/check-iphone-functional-gate.sh
• Scripts/check-swiftdata-boundary.sh
• iPhone 16 / iOS 26.5 Simulator Debug build
• generic iPhone Debug build (CODE_SIGNING_ALLOWED=NO)
• generic iPhone Release build (CODE_SIGNING_ALLOWED=NO)
• git diff --check, Info.plist/project.pbxproj plutil -lint
• 제외한 기존 테스트 3건
  • FinalScreenVisualTests.testMainScreensRenderAtReferenceAccessibilitySizes: golden hash 허용 거리 24 대비 28
  • FinalScreenVisualTests.testSessionEmptyStatesRenderAtReferenceAccessibilitySizes: golden hash 허용 거리 24 대비 50
  • RoutineTTSAudioStorageTests.testPurgeCancelsOldLoadAndDoesNotRemoveSameKeyReplacement: 전체 실행 중 gate 대기에서 멈춰 중단됐고 단독 직렬 실행에서도 같은 기존 timing race를 재현했습니다.
  • 이번 변경은 UI/asset과 RoutineTTSAudioCache 구현을 수정하지 않아 세 테스트는 변경하지 않았습니다.
• 실기기 + 배포된 신 백엔드 E2E: 백엔드 PR #125가 아직 미머지/미배포라 미검증

📋 추후 진행 상황

• 백엔드 PR 🎨 Design: 예상 루틴 시간 및 루틴 정리 중 애니메이션 추가 #125 머지·배포 후 실기기에서 음성 변경 → 기존 루틴 PENDING → 재합성 완료 → 앱 재실행 → 새 음성 재생 흐름을 E2E 검증해야 합니다.
• 같은 기기의 앱 재실행은 이번 로컬 저장으로 지원합니다. 저장 값은 실제 PATCH 성공 응답에서만 만들며 서버가 버전을 주지 않으면 삭제하므로 값을 임의로 추측하지 않습니다.
• 현재 제품을 단일 기기로 운영한다는 전제에서는 추가 조회 API가 필수는 아닙니다.
• 향후 다중 기기 또는 관리자/서버 측 음성 변경을 지원한다면 GET /routine-tts/{routineGroupId}/tts에 인증 회원의 원자적인 optional currentSelectionVersion: Long을 추가해야 다른 기기에서 바뀐 값을 정확히 알 수 있습니다.

📌 리뷰 포인트

• optional 필드 누락이 디코딩 실패나 원격 TTS 차단으로 이어지지 않고 0이 유효한 버전으로 처리되는지 확인해 주세요.
• 로컬 버전이 회원별로 저장·복원되고 구 서버 PATCH 응답에서는 현재 회원 값만 제거되는지 확인해 주세요.
• 복원한 버전이 새 AccountSessionIdentity에 다시 묶이고 기존 actor 취소/동시성 및 캐시 격리를 유지하는지 확인해 주세요.
• 버전 불일치가 기존 PENDING fallback을 재사용하며 stale 원격 plan/download를 만들지 않는지 확인해 주세요.

✅ Checklist

PR이 다음 요구 사항을 충족하는지 확인해주세요!!!

• 커밋 메시지 컨벤션에 맞게 작성했습니다
  • 해당 링크: 깃 모지 컨벤션
• 유지-보수를 위해 필요한 주석을 작성했습니다
  • 해당 링크: Xcode 주석 정리

[coderabbitai]

Important

Review available on request

• 🔍 Trigger review

Reviews should be triggered manually for repositories with fewer than 10 stars. Select Trigger review above or comment @coderabbitai review to review the latest changes. For a full review, comment @coderabbitai full review.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4170b3c1-5610-42d3-954e-2af4c7aed4fc

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}