[Feat] 음악 생성 API 프롬프트 추가 및 곡 길이 지정 (#25)

[seoyeoki]

개요

음악 생성 시 사용자 프롬프트(선택)를 받고, 곡 길이를 백엔드 설정값으로 지정해 AI 서버에 항상 전달하며, AI가 보고한 길이를 검증합니다. 생성 길이 상한이 30초이므로 30초를 넘는 허밍은 오류로 거부합니다.

Closes #25

변경 사항

• 프롬프트: POST /api/v1/generation/songs에 선택 필드 prompt(최대 500자) 추가, music_generation.prompt 컬럼에 저장. 비어 있거나 공백이면 null로 저장하고 AI 요청에서 생략. 수정곡은 원본의 prompt를 이어받음
• 곡 길이: 설정값 generation.duration-seconds(기본 30) 도입, 하드코딩 updateDuration(30) 제거. AI 요청에 duration_seconds를 항상 전송
• 완료 콜백 검증: AiTaskCompletionRequest.duration_seconds(nullable Double) 추가
  • 요청 길이와 ±0.1초 초과 차이면 FAILED (정확히 0.1초 차이는 허용, 부동소수점 오차 보정 포함)
  • 보고된 길이가 없으면(구 AI 서버) 검증을 건너뛰고 요청한 길이를 유지
  • 길이 비교는 최초 생성(parent 없음)만 수행. 수정곡은 보고된 길이만 저장
• duration_seconds 타입: MusicGeneration.durationSeconds Integer → Double, AI가 보고한 실제 길이를 저장
• 30초 초과 허밍 거부 (HUMMING4001, 400, "허밍은 최대 30초까지 가능합니다."): 허밍 저장 API(duration_seconds > 30)와 생성 요청(멜로디 마지막 음 끝 시점 > 30.1초, 0.1초 양자화 여유). 생성 요청 검증은 AI 호출 전에 수행
• presigned PUT URL 유효시간 10분 → 30분 (RunPod 콜드스타트·대기열 + 생성 시간 고려)
• Swagger 문서, infra/db/ERD.md 갱신

프론트 영향

항목	내용
녹음 길이	30초 제한 필요. 초과 시 서버가 400 HUMMING4001로 거부
prompt	생성 요청에 선택 필드로 추가 (최대 500자, 초과 시 400 COMMON400, result.prompt에 메시지)
duration_seconds	SSE complete의 result.duration_seconds, /api/v1/me/songs의 contents[].duration_seconds가 정수 → 소수 (예: 29.95). JSON number라 JS/TS는 영향 없음
웹 에디터	노트를 늘려 멜로디가 30.1초를 넘기면 생성 요청이 400 HUMMING4001
길이 불일치	AI 결과 길이가 요청과 0.1초 넘게 다르면 SSE에 FAILED로 전달

배포 시 주의

1. 백엔드 먼저 배포: 추가된 요청 필드는 구 AI 서버가 무시하고, 콜백에 duration_seconds가 없어도 동작합니다. AI 서버의 30초 하드코딩이 제거되므로 AI 서버를 먼저 배포하면 길이를 안 보내는 구 백엔드의 생성이 실패합니다.
2. 운영 DB 수동 작업: ALTER TABLE music_generation MODIFY duration_seconds DOUBLE;
   • ddl-auto: update는 기존 컬럼 타입을 바꾸지 않아, 실행하지 않으면 실제 길이 소수점이 INT로 반올림 저장됩니다.
   • main 머지 시 자동 배포되므로 머지 전에 실행하는 것이 안전합니다 (구 코드도 DOUBLE 컬럼을 문제없이 읽음).
   • prompt 컬럼은 자동으로 추가됩니다.

범위 외

• 수정 API(/modifications)의 prompt 길이 제한, 소유자 검증
• 구간 재생성([FEAT] 음악 구간 재생성 API (오디오 처리는 AI 서버 담당) #27)에서 쓸 modify 요청 규격

테스트

• ./gradlew build 통과 (MockMvc + H2, 신규 14개 포함 31개)
  • 허밍 31초/30초, prompt 501자, 멜로디 30.2초(AI 미호출)/30.1초 경계
  • AI 요청 본문(prompt, duration_seconds 포함·생략), 공백 prompt
  • 콜백: 허용오차 이내·±0.1초 경계·초과(FAILED)·duration_seconds 누락·실패 통보·수정곡, /me/songs 소수 응답
  • 오차 보정값을 0으로 바꾸면 경계 테스트 2개가 실패하는 것 확인
• MariaDB 로컬 bootRun에서 컬럼 추가·소수 저장 확인은 하지 못했습니다 (테스트는 H2)
• 실제 AI 서버(RunPod)와의 연동은 확인하지 못했습니다 (WebClient 요청 본문을 가로채 검증)

🤖 Generated with Claude Code