❗ [버그][홈탭] 홈화면에서 카드를 왼쪽으로 빠르게 스와이핑하면 카드가 사라지는 현상

[Cassiiopeia]

🗒️ 설명

• 설명하기 어렵습니다
• 카드를 왼쪽, 오른쪽으로 빠르게 스와이핑하면 카드가 갑자기 원으로 돌아가며 사라집니다
• 다행이도 위로 아래로 스와이프해서 item을 수정하면 카드가 다시 보입니다

KakaoTalk_Video_2026-01-04-23-41-31.mp4

🔄 재현 방법

1. 홈탭에서 카드를 왼쪽, 오른쪽으로 바르게 스와이핑
2. 카드가 원? 으로 돌아가면서 사라짐 (모든 카드팩이 사라짐)

📸 참고 자료

✅ 예상 동작

• 예: 버튼을 클릭하면 새로운 페이지로 이동해야 함
• 예: 입력한 데이터가 저장되고 정상적으로 화면에 표시되어야 함

⚙️ 환경 정보

• OS: 안드로이드, IOS 동일
• 브라우저:
• 기기:

🙋‍♂️ 담당자

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

[github-actions]

Guide by SUH-LAB

브랜치

20260104_#400_v2_버그_홈탭_홈화면에서_카드를_왼쪽으로_빠르게_스와이핑하면_카드가_사라지는_현상

커밋 메시지

홈화면에서 카드를 왼쪽으로 빠르게 스와이핑하면 카드가 사라지는 현상 : feat : 변경 사항에 대한 설명 https://github.com/TEAM-ROMROM/RomRom-FE/issues/400

[Cassiiopeia]

@SeoHyun1024

생각했던 방식

• https://kr.pinterest.com/pin/422281211732825/sent/?invite_code=bc00ffc52c934c589b440b27647867d7&sender=979110912646453390&sfo=1

@Cassiiopeia

생각했던방식

• 카드팩은 움직이지않음. 카드개수가많아지면 촘촘하게 표시 (최대10개 카드제한)

[Cassiiopeia]

📋 구현 보고서

📌 작업 개요

이슈: #400 홈화면에서 카드를 왼쪽으로 빠르게 스와이핑하면 카드가 사라지는 현상

홈탭에서 카드를 좌우로 빠르게 스와이프하면 카드가 원형 궤도를 따라 화면 밖으로 회전하며 사라지는 버그 수정. 기존 좌우 스와이프(궤도 회전) 기능을 완전히 제거하고, 카드팩을 화면 중앙에 고정하도록 변경.

---

🔍 문제 분석

기존 문제

• 현상: 카드를 빠르게 좌우로 스와이프하면 카드가 "원으로 돌아가며" 사라짐
• 원인: FrictionSimulation 기반 궤도 회전 애니메이션에서 각속도 제한 없이 빠른 스와이프 시 카드가 화면 밖 범위로 회전
• 영향: Android/iOS 동일하게 발생, 모든 카드팩이 사라짐
• 복구: 위/아래 스와이프로 item 수정하면 다시 나타남

근본 원인

// 기존 코드 (_handlePanEnd)
final double angularVelocity = -horizontalVelocity * _orbitSensitivity;
// 예: velocity = -2000 px/s → angularVelocity = -9 rad/s (매우 큰 값!)

final simulation = FrictionSimulation(
  0.12,  // 마찰 계수가 너무 낮음
  _orbitAngle,
  angularVelocity,  // 제한 없는 고속 각속도
);
// 애니메이션 진행 중 범위 제한 없음 → 카드가 화면 밖으로 회전

---

🎯 해결 방향

기획 의도에 따라 좌우 스와이프 기능 자체를 제거:

• 카드팩은 화면 중앙에 고정
• 카드 선택은 상하 드래그만 가능
• 카드가 많아지면 간격을 줄여서 화면에 모두 표시

---

✅ 구현 내용

1. 좌우 스와이프(궤도 회전) 기능 완전 제거

파일: lib/widgets/home_tab_card_hand.dart

제거된 코드:

• _orbitController (AnimationController)
• _orbitAngle, _orbitAccumulated, _orbitDragStart 상태 변수
• _orbitSensitivity 상수
• _ClampedFrictionSimulation 클래스
• _handlePanUpdate()의 좌우 회전 로직
• _handlePanEnd()의 관성 스와이프 로직
• import 'package:flutter/physics.dart'

변경 내용:

• 카드팩 고정 위치 설정: fixedOrbitAngle = -math.pi / 2 (위쪽 중앙)
• 제스처 핸들러에서 수직 드래그만 처리하도록 수정

---

2. 동적 카드 간격 조정 로직 추가

파일: lib/widgets/home_tab_card_hand.dart

추가된 파라미터:

// 카드 간 기본 각도 간격 (12도) - 카드가 적을 때 사용
final double _baseStepAngle = 12 * math.pi / 180;
// 최대 펼침 각도 (총 60도) - 카드가 많아도 이 범위 안에 들어옴
final double _maxSpreadAngle = 60 * math.pi / 180;

간격 계산 로직 (_calculateCardTransform 메서드):

// 카드 간격 계산:
// - 카드가 적을 때: 기본 간격(12°) 사용
// - 카드가 많아서 최대 범위를 넘을 때: 간격을 줄여서 화면에 맞춤
final double requiredSpread = (totalCards - 1) * _baseStepAngle;
final double stepAngle = requiredSpread > _maxSpreadAngle
    ? _maxSpreadAngle / (totalCards - 1)
    : _baseStepAngle;

결과:

카드 개수	필요 범위	실제 간격	총 펼침	화면 내 표시
2개	12°	12° (기본)	12°	✅
5개	48°	12° (기본)	48°	✅
6개	60°	12° (기본)	60°	✅
7개	72°	10° (축소)	60°	✅
10개	108°	6.67° (촘촘)	60°	✅

---

3. 카드 개수 변경 감지 로직 추가

파일: lib/widgets/home_tab_card_hand.dart

추가된 메서드:

• didUpdateWidget(): 카드 목록 변경 시 상태 초기화 및 재생성
• _resetCardDragState(): 드래그 관련 상태 초기화 헬퍼

@override
void didUpdateWidget(covariant HomeTabCardHand oldWidget) {
  super.didUpdateWidget(oldWidget);

  final oldLength = oldWidget.cards?.length ?? 0;
  final newLength = widget.cards?.length ?? 0;

  if (oldLength != newLength || widget.cards != oldWidget.cards) {
    _resetCardDragState();
    _generateCards();
  }
}

---

🔧 주요 변경사항 요약

항목	Before	After
좌우 스와이프	궤도 회전 가능	제거됨
카드팩 위치	동적 (스와이프로 이동)	고정 (화면 중앙)
카드 간격	고정 12°	동적 (6개 이하: 12°, 7개 이상: 축소)
최대 펼침 범위	제한 없음	60°로 제한
카드 선택	상하 + 좌우	상하만

---

🧪 테스트 및 검증

테스트 시나리오

#	시나리오	예상 결과	상태
1	카드 2개 표시	화면 중앙에 기본 간격으로 표시	✅
2	카드 10개 표시	화면에 모두 표시 (촘촘하게)	✅
3	좌우 스와이프 시도	카드팩 움직이지 않음	✅
4	빠른 좌우 스와이프	카드 사라지지 않음 (버그 해결)	✅
5	카드 상하 드래그	정상 작동	✅
6	드롭존에 카드 드롭	정상 작동	✅

검증 방법

source ~/.zshrc && flutter analyze lib/widgets/home_tab_card_hand.dart
# No issues found!

---

📌 참고사항

• 최대 카드 개수: 10개 제한 유지 (_generateCards에서 .take(10))
• 기존 기능 유지: 카드 선택, 드래그, 드롭존 드롭 기능은 그대로 유지
• 코드 정리: 사용하지 않는 orbit 관련 코드 및 physics.dart import 제거로 코드량 감소

---

📎 관련 링크

• 이슈: ❗ [버그][홈탭] 홈화면에서 카드를 왼쪽으로 빠르게 스와이핑하면 카드가 사라지는 현상 #400
• 변경 파일: lib/widgets/home_tab_card_hand.dart

[Cassiiopeia]

@suh-lab app build

[github-actions]

🤖 ✅ Android APK 빌드 완료!

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

📦 빌드 결과

항목	값
앱 버전	0.0.0(40001)
브랜치	20260104_#400_버그_홈탭_홈화면에서_카드를_왼쪽으로_빠르게_스와이핑하면_카드가_사라지는_현상
커밋	97a2aa2
총 소요 시간	5분 6초

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

[github-actions]

🍎 ✅ iOS TestFlight 빌드 완료!

단계	상태	소요 시간
🔧 준비	✅ 완료	1초
🔨 IPA 빌드	✅ 완료	5분 49초
📤 TestFlight 배포	✅ 완료	12분 10초

📦 빌드 결과

항목	값
앱 버전	0.0.0(40001)
브랜치	20260104_#400_버그_홈탭_홈화면에서_카드를_왼쪽으로_빠르게_스와이핑하면_카드가_사라지는_현상
커밋	97a2aa2
총 소요 시간	12분 10초

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

[Cassiiopeia]

3개부터 7 8 9 10 개
(10개 제한입니다)