refactor: 스탬프 수집을 진행도 기반으로 변경하여 해외 여정 지원

[hskhsmm]

📝 변경 사항

스탬프 수집 로직을 실제 GPS 위치 기반에서 진행도(누적 거리) 기반으로 변경하여 해외 여정(파리, 뉴욕 등)에서도 스탬프 수집이 가능하도록 개선했습니다.

변경 이유

기존 문제점

• 실제 GPS 위치(위도/경도)로 랜드마크 500m 반경 내 검증
• 해외 랜드마크는 한국에서 절대 수집 불가능 ❌
• 가상 여행 컨셉과 맞지 않는 구현

해결 방안

• ✅ 진행률(누적 거리)만으로 스탬프 수집 가능 여부 판정
• ✅ 사용자가 달린 거리가 랜드마크의 distanceFromStart에 도달하면 수집 가능
• ✅ 한국에서 달리면서 파리/뉴욕 등 해외 여정 진행 가능

주요 변경 내용

1. Service Layer (StampServiceImpl.java)

• ❌ COLLECTION_RADIUS_KM 상수 삭제
• ❌ calculateDistance() (Haversine 거리 계산) 메서드 삭제
• ✅ collectStamp() - 실제 위치 검증 로직 제거
• ✅ canCollectStamp() - 진행률 기반 검증으로 변경

  // 변경 전
  boolean canCollectStamp(userId, progressId, landmarkId, latitude, longitude)
  
  // 변경 후
  boolean canCollectStamp(userId, progressId, landmarkId)

2. Interface (StampService.java)

• ✅ canCollectStamp() 메서드 시그니처 변경 (latitude, longitude 파라미터 제거)

3. Controller (StampController.java)

• ✅ POST /v1/stamps/collect - API 문서 업데이트 (가상 여행 시스템 설명 추가)
• ✅ GET /v1/stamps/check-collection - latitude, longitude 쿼리 파라미터 제거

✅ 수집 조건 (변경 후)

검증 항목:

1. ✅ 권한 확인 (본인의 여정인지)
2. ✅ 중복 확인 (이미 수집한 스탬프인지)
3. ✅ 진행률 확인 (currentDistanceKm >= landmark.distanceFromStart)

제거된 검증:

• ❌ 실제 GPS 위치 검증 (500m 반경)
• ❌ Haversine 거리 계산

예상 플로우

프론트엔드

// 러닝 완료 → 여정 진행률 업데이트 (currentDistanceKm 증가)
// 랜드마크 목록 순회하면서 자동 체크

if (currentDistanceKm >= landmark.distanceFromStart) {
// 스탬프 수집 가능!
POST /v1/stamps/collect {
progressId: 1,
landmarkId: 5,
collectionLocation: { ... } // 선택적 (저장용)
}
}

백엔드

// 진행률 기반 검증
if (progress.getCurrentDistanceKm() < landmark.getDistanceFromStart()) {
throw new IllegalArgumentException(
"아직 이 랜드마크에 도달하지 않았습니다. (현재: 30.5km, 필요: 50.0km)"
);
}

API 변경

Before

GET /v1/stamps/check-collection?progressId=1&landmarkId=5&latitude=48.8584&longitude=2.2945

After

GET /v1/stamps/check-collection?progressId=1&landmarkId=5

테스트 체크리스트

• 누적 거리가 랜드마크에 도달하면 스탬프 수집 성공
• 누적 거리가 부족하면 수집 실패 (명확한 에러 메시지)
• 중복 수집 방지 확인
• 해외 여정(파리, 뉴욕 등) 스탬프 수집 가능 확인
• 여정 진행률 업데이트 후 자동 수집 가능 여부 체크

보안 고려사항

Q: 프론트엔드만 믿으면 조작 가능하지 않나요?

A: 백엔드에서 진행률 검증으로 방어합니다.

• currentDistanceKm는 백엔드에서 실제 러닝 기록이 쌓여야만 증가
• 사용자가 프론트를 조작해도 백엔드 진행률은 변조 불가
• 중복 수집은 DB 유니크 제약으로 차단

관련 이슈

• 해외 여정에서 스탬프 수집 불가능 문제 해결
• 가상 여행 컨셉에 맞는 구현으로 개선

배포 영향도

• Breaking Change: ⚠️ API 파라미터 변경 (latitude, longitude 제거)
• 프론트엔드 수정 필요: GET /v1/stamps/check-collection 호출 부분
• 하위 호환성: POST /v1/stamps/collect는 기존 요청 바디 구조 유지 (latitude/longitude 무시)

---

리뷰 포인트

1. 진행률 기반 검증 로직이 정확한지
2. API 문서가 명확한지
3. 에러 메시지가 사용자 친화적인지
4. 보안 취약점은 없는지

[leepg038292]

여정 기반 획득 로직 확인했습니다.