⚙️[기능추가][프로필] 프로필 사진 업로드 시 원형 미리보기 및 조정 UI 추가

[Cassiiopeia]

📝 현재 문제점

• 프로필 사진 업로드 시 미리보기 없이 바로 업로드되어 사용자가 결과물을 사전에 확인할 수 없음
• 프로필 이미지가 원형으로 표시되지만, 업로드 전에 어떻게 잘릴지 확인하거나 위치/크기를 조정할 수 없음
• 원하지 않는 영역이 잘리거나 의도와 다른 결과가 나올 경우 다시 업로드해야 하는 불편함이 있음

🛠️ 해결 방안 / 제안 기능

• 프로필 사진 선택 후 원형 크롭 미리보기 UI를 제공
• 사용자가 이미지 확대/축소, 위치 이동을 통해 원형 영역 내 표시될 부분을 직접 조정할 수 있도록 함
• 조정 완료 후 확인 버튼을 눌러 최종 업로드 진행

⚙️ 작업 내용

• 이미지 선택 시 원형 크롭 미리보기 모달/화면 추가
• 이미지 확대/축소(핀치 줌 또는 슬라이더) 기능 구현
• 이미지 드래그를 통한 위치 조정 기능 구현
• 원형 마스크 오버레이로 최종 결과물 미리보기 제공
• 확인/취소 버튼을 통한 업로드 흐름 처리

🙋‍♂️ 담당자

• 백엔드: 이름
• 프론트엔드: @Cassiiopeia
• 디자인: 이름

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260327_#533_프로필_사진_업로드_시_원형_미리보기_및_조정_UI_추가

커밋 메시지

프로필 사진 업로드 시 원형 미리보기 및 조정 UI 추가 : feat : {변경 사항에 대한 설명} https://github.com/TEAM-ROMROM/RomRom-FE/issues/533

[Cassiiopeia]

프로필 사진 업로드 시 원형 미리보기 및 조정 UI 추가

이슈: #533

---

📌 작업 개요

프로필 사진 선택 후 미리보기 없이 즉시 업로드되던 기존 흐름을 개선. 이미지 선택 시 원형 크롭 전용 화면(풀스크린)을 제공하여 사용자가 드래그/핀치줌으로 원형 표시 영역을 조정한 뒤 업로드 진행하도록 구현.

---

🎯 구현 목표

• 갤러리에서 이미지 선택 후 원형 크롭 조정 화면 제공
• 드래그(위치 이동) 및 핀치줌(확대/축소)으로 원형 영역 내 표시 영역 조정
• 확인/취소 버튼으로 업로드 흐름 처리
• iOS / Android 양 플랫폼에서 일관된 UX 제공

---

✅ 구현 내용

1. image_cropper 패키지 추가

• 파일: pubspec.yaml
• 변경 내용: image_cropper: ^9.1.0 추가 (알파벳 순 image_picker 바로 위)
• 이유: Flutter 공식 이미지 크롭 패키지. iOS/Android 네이티브 크롭 UI를 제공하여 별도 화면 구현 없이 안정적인 크롭 기능 제공

2. onPickImage() 메서드 수정

• 파일: lib/screens/my_page/my_profile_edit_screen.dart
• 변경 내용: 갤러리 선택 직후 ImageCropper().cropImage() 호출하여 원형 크롭 화면 삽입. 크롭 확인 후 XFile(croppedFile.path)로 변환하여 기존 ImageApi().uploadImages() 에 전달
• 이유: 기존 업로드 API를 그대로 활용하면서 크롭 단계만 중간에 삽입하는 최소 변경 방식 채택

3. 저장 버튼 중복 클릭 방지 적용

• 파일: lib/screens/my_page/my_profile_edit_screen.dart
• 변경 내용: _isSaving 플래그 추가. 저장 버튼 onTap에서 _isSaving 체크 후 진행 중이면 early return. try-finally로 항상 해제
• 이유: CLAUDE.md 중복 요청 방지 패턴 적용. 빠른 연속 탭으로 인한 API 중복 호출 방지

4. Android 이미지 접근 권한 추가

• 파일: android/app/src/main/AndroidManifest.xml
• 변경 내용: READ_MEDIA_IMAGES (Android 13+), READ_MEDIA_VISUAL_USER_SELECTED (Android 14+ 부분 허용), READ_EXTERNAL_STORAGE (Android 12 이하, maxSdkVersion="32") 권한 추가
• 이유: 갤러리 접근에 필요한 권한 명시. 미선언 시 일부 기기/OS 버전에서 갤러리 접근 불가

5. UCropActivity 등록 및 속성 추가

• 파일: android/app/src/main/AndroidManifest.xml
• 변경 내용: com.yalantis.ucrop.UCropActivity 선언 추가 (android:exported="false", screenOrientation="portrait")
• 이유: image_cropper 내부 엔진인 UCrop이 사용하는 Activity. 명시적 등록으로 충돌 방지

---

🔧 주요 변경사항 상세

크롭 흐름 변경

[변경 전]
갤러리 선택 → 즉시 서버 업로드 → 미리보기 갱신

[변경 후]
갤러리 선택 → 원형 크롭 화면 (풀스크린) → 확인 → 서버 업로드 → 미리보기 갱신
취소(갤러리) / 취소(크롭) → 아무 변화 없음

크롭 UI 설정 (iOS/Android 각각)

• 공통: CropStyle.circle (원형 마스크), 1:1 비율 고정
• Android: 앱 브랜드 색상 적용 (AppColors.primaryBlack 툴바, AppColors.primaryYellow 조작 색상)
• iOS: 화면 회전 및 비율 변경 비활성화

업로드 실패 처리 개선

업로드 실패 시 finally 블록에서 _isProfileEdited가 false인 경우 _showProfileSaveButton도 false로 리셋. 실패했는데 저장 버튼이 비활성 상태로 남아있는 UX 혼란 방지.

특이사항:

• imageFile 변수 제거: 기존 코드에 선언되어 있었으나 변경된 흐름에서 미사용. 로딩 UI 조건도 _hasImageBeenTouched만으로 단순화
• 크롭 중에는 로딩 스피너 미표시 (크롭 완료 확인 후 업로드 시작 시점에 표시)

---

📦 의존성 변경

패키지	버전	용도
image_cropper	^9.1.0	원형 이미지 크롭 UI 제공

---

🧪 테스트 및 검증

확인 필요 항목:

• 갤러리 이미지 선택 → 원형 크롭 화면 표시
• 드래그로 이미지 위치 조정
• 핀치줌으로 이미지 크기 조정
• 확인 버튼 → 크롭된 이미지가 프로필 미리보기에 반영
• 취소(갤러리 단계 / 크롭 단계) → 기존 프로필 이미지 유지
• 저장 버튼 빠른 연속 탭 → API 1회만 호출 확인
• Android 13+ / 12 이하 기기에서 갤러리 권한 정상 요청 확인

---

📌 참고사항

• 인터넷 연결 후 flutter pub get → flutter analyze 실행 필요
• image_cropper v9.x는 내부적으로 UCrop 라이브러리 사용. AndroidManifest에 수동 등록 완료
• iOS 별도 Info.plist 권한 설정은 기존 image_picker 설정으로 공유 가능 (NSPhotoLibraryUsageDescription)

[Cassiiopeia]

@suh-lab app build

[github-actions]

🤖 ✅ Android APK 빌드 완료!

단계	상태	소요 시간
🔧 준비	✅ 완료	-
🔨 APK 빌드	✅ 완료	-
📤 업로드	✅ 완료	6분 2초

📦 빌드 결과

항목	값
앱 버전	0.0.0(53301)
브랜치	20260218_#533_프로필_사진_업로드_시_원형_미리보기_및_조정_UI_추가
커밋	8640898
총 소요 시간	6분 2초

📦 아티팩트 다운로드
🔗 워크플로우 실행 로그

[github-actions]

🍎 ✅ iOS TestFlight 빌드 완료!

단계	상태	소요 시간
🔧 준비	✅ 완료	2분 37초
🔨 IPA 빌드	✅ 완료	10분 19초
📤 TestFlight 배포	✅ 완료	17분 15초

📦 빌드 결과

항목	값
앱 버전	0.0.0(53301)
브랜치	20260218_#533_프로필_사진_업로드_시_원형_미리보기_및_조정_UI_추가
커밋	8640898
총 소요 시간	17분 15초

📱 TestFlight에서 테스트 앱을 다운로드할 수 있습니다.
🔗 워크플로우 실행 로그