feat: 공유집(앨범) 목록 조회 응답에 앨범 추가순 사진 3장 썸네일 추가

[hamtorygoals]

📌 Summary

• close [fix] 공유집(앨범) 목록 조회 응답에 썸네일(첫 사진 3장) 필드 누락 #99
• 공유집(앨범) 목록 조회(ALBUM-01) 응답에 앨범 카드용 사진 3장 썸네일(thumbnails)을 추가했습니다.
• 정렬 기준은 사진이 찍힌/업로드된 시각이 아니라 그 사진이 이 앨범에 추가된 시각(SharedAlbumPhoto.createdAt)입니다.
• Swagger 예시 생성기의 고정 재귀 깊이 상한을 순환 감지 방식으로 교체해 4단계 이상 중첩된 필드도 실제 예시가 채워지도록 함께 고쳤습니다.

✅ Tasks

• SharedAlbumPhotoRepository에 앨범별 최초 추가 사진 조회 쿼리 추가
• SharedAlbumListResponse.Item에 thumbnails 필드 추가
• SharedAlbumService에서 썸네일 presign 매핑 로직 구현
• Swagger 문서(Operation 설명, @Schema) 반영
• 단위 테스트·통합 테스트 추가
• API 명세서(06-shared-album.md)·iOS 연동 가이드·의사결정 로그 업데이트

🔥 Troubleshooting

• 최초 구현은 정렬 기준을 coalesce(photo.takenAt, photo.createdAt)(PHOTO-01과 동일한 정렬 키)로 재사용했는데, 코드 리뷰 중 PHOTO-07(기존 사진을 다른 앨범에 추가)을 쓰면 "앨범에 먼저 저장된 순서"와 "사진이 찍힌 순서"가 어긋난다는 걸 확인해 SharedAlbumPhoto.createdAt(앨범 매핑 생성 시각) 기준으로 수정했습니다. 이 정렬 키는 shared_album_photo(shared_album_id, created_at) 인덱스로 커버돼 성능도 함께 개선됐습니다.
• thumbnails 필드가 4단계 중첩(items → Item → thumbnails → Thumbnail)이라 Swagger 예시 생성기의 고정 depth 상한(3)에 걸려 NullPointerException이 났습니다. 근본 원인이 하드코딩된 깊이 제한이라 판단해, 타입 방문 이력 기반 순환 감지로 교체했습니다(다른 컨트롤러의 기존 예시에는 영향 없음을 확인).

📸 API Test Results

• Swagger UI에서 ALBUM-01 응답 예시에 thumbnails 3장이 채워져 표시되는 것 확인(수정 전에는 빈 배열)
• 통합 테스트에서 촬영 시각과 앨범 추가 순서를 의도적으로 반대로 배치해 정렬 기준을 검증(버그 재현 버전으로 되돌려 테스트가 실패하는 것까지 확인 후 복원)
• JDK 21 ./gradlew test --rerun: 220개 통과, 실패 0개

🔍 To Reviewer

• SharedAlbumPhoto.createdAt(앨범 매핑 생성 시각) 기준 정렬이 "앨범에 가장 먼저 저장된 사진"이라는 기획 의도에 맞는지 확인해주세요.
• 썸네일이 아직 READY가 아닌 사진은 건너뛰고 채워 넣지 않는 정책(배열 길이가 0~3일 수 있음)이 프론트 요구사항과 맞는지 확인해주세요.