[Feat] 음악 버전 목록 조회·되돌리기 API 추가 (#26)

[seoyeoki]

개요

같은 곡의 버전을 root_generation_id로 묶고, 버전 목록 조회와 특정 버전으로 되돌리기 API를 추가합니다. 되돌린 이후 버전은 deleted_at으로 soft delete 합니다.

Closes #26, Closes #39

Important

⚠️ 배포 직후 운영 DB 백필 SQL 실행 필수

기존 곡은 root_generation_id가 NULL이라 백필하지 않으면 버전 목록이 404, 되돌리기가 빈 동작이 되고, 그 곡을 수정한 수정본도 NULL root를 이어받아 버전 기능 밖으로 빠집니다.

1. 먼저 수정본이 없는지 확인 (결과가 0이어야 아래 UPDATE가 맞습니다. 0이 아니면 실행하지 말고 별도 백필 쿼리를 작성해야 함)

SELECT COUNT(*) FROM music_generation WHERE parent_generation_id IS NOT NULL AND root_generation_id IS NULL;

2. 백필 실행 (기존 원본 곡이 자기 자신을 root로 갖게 함)

UPDATE music_generation SET root_generation_id = generation_id WHERE root_generation_id IS NULL;

• 실행 시점: main 머지(자동 배포) 후, ddl-auto: update가 root_generation_id·deleted_at 컬럼을 만든 다음
• parent_generation_id는 건드리지 않습니다 (NULL = 최초 생성곡이라는 전제를 코드가 사용)
• 백필 후 기존 곡은 새로 만든 원본 곡과 동일하게 동작합니다 (버전 1개짜리 목록, 되돌리기 삭제 0건)

변경 사항

• 컬럼 추가 (music_generation)
  • root_generation_id: 최초 생성곡은 자기 자신의 ID, 수정본은 부모의 root를 물려받음 (FK 없이 인덱스만)
  • deleted_at: 되돌리기로 무효화된 시각 (soft delete)
• 버전 목록 GET /api/v1/generation/songs/{root_generation_id}/versions
  • 같은 root의 COMPLETED + 미삭제 버전을 생성 순서로 반환, version_no는 컬럼 없이 조회 순서로 계산 (번호가 비지 않음)
  • 경로는 원본(root) ID만 받음. 수정본 ID·없는 ID·타인의 곡은 404
• 되돌리기 POST /api/v1/generation/songs/{generation_id}/revert
  • "돌아갈 버전"의 ID를 받아, 같은 root에서 그보다 이후 버전을 모두 soft delete 하고 삭제 건수 반환
  • 같은 root에 생성 중(PROCESSING) 작업이 있으면 409 GENERATION4001
  • 삭제됐거나 미완료인 버전, 타인의 곡은 404
• 기존 API 영향 ([FEAT] 버전 되돌리기(soft delete)에 따른 기존 API 동작 변경 반영 #39)
  • /api/v1/me/songs에서 삭제된 버전 제외
  • 삭제된 버전에 수정 요청 시 404
• 두 신규 API 인증 필수 (SecurityConfig), Swagger 문서, infra/db/ERD.md 갱신
• [FEAT] 음악 생성 API 프롬프트 추가 및 곡 길이 지정 #25 머지에 맞춰 버전 응답의 duration_seconds도 Double

이슈 본문과 다른 점

• 버전 목록 응답에 prompt/start_time_sec/end_time_sec 없음 (prompt는 #25에서 생겼으나 이 PR 범위 밖, 구간 컬럼은 #27에서 생김)
• 되돌리기·목록에 소유자 검증 추가 (타인의 곡은 404)

프론트 영향

항목	내용
root ID	/me/songs·SSE complete 응답에 root_generation_id가 없음. 최초 생성 응답의 곡 ID를 root로 기억해야 함
내 곡 목록	되돌리기로 삭제된 버전은 사라짐
수정 요청	삭제된 버전 ID로 요청하면 404
되돌리기	생성 중인 버전이 있으면 409 GENERATION4001

범위 외

• 응답에 root_generation_id 노출 (필요하면 별도 이슈)
• 버전 응답의 prompt 추가

테스트

• ./gradlew build 통과 (MockMvc + H2, 신규 14개 포함 44개)
  • 되돌리기: 이후 버전만 삭제, 마지막 버전으로 되돌리면 0건, 되돌린 뒤 새 버전 번호 연속, 진행 중 409(삭제 없음), 다른 곡의 진행 작업은 무관
  • 404: 삭제·미완료 버전, 없는 곡, 타인의 곡, 수정본 ID로 목록 조회 / 401: 비로그인
  • 생성은 자기 자신이 root, 수정은 부모의 root 승계
  • /me/songs에서 삭제 버전 제외, 삭제 버전 수정 요청 404
• MariaDB 로컬 bootRun에서 컬럼 추가·백필 SQL 실행은 확인하지 못했습니다 (테스트는 H2)

🤖 Generated with Claude Code