[FEAT] MIDI 이벤트 저장 API 구현

src/main/java/com/mr/domain/playing/constant/MidiEventConstants.java

@@ -0,0 +1,10 @@
+package com.mr.domain.playing.constant;
+
+import lombok.AccessLevel;
+import lombok.NoArgsConstructor;
+
+@NoArgsConstructor(access = AccessLevel.PRIVATE)
+public final class MidiEventConstants {
+
+    public static final int MAX_MIDI_EVENT_COUNT = 100_000;
+}

src/main/java/com/mr/domain/playing/controller/PlayingController.java

@@ -0,0 +1,45 @@
+package com.mr.domain.playing.controller;
+
+import com.mr.domain.playing.dto.req.MidiEventSaveRequest;
+import com.mr.domain.playing.dto.res.MidiEventSaveResponse;
+import com.mr.domain.playing.service.PlayingService;
+import com.mr.global.apipayload.ApiResponse;
+import com.mr.global.security.principal.CustomUserDetails;
+import io.swagger.v3.oas.annotations.Operation;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/api/playings")
+public class PlayingController {
+
+    private final PlayingService playingService;
+
+    @Operation(
+            summary = "MIDI 이벤트 저장",
+            description = "연주 세션에 대한 MIDI 이벤트를 저장하고 연주를 완료 상태로 변경합니다."
+    )
+    @PostMapping("/{playingId}/midi-events")
+    public ApiResponse<MidiEventSaveResponse> saveMidiEvents(
+            @AuthenticationPrincipal CustomUserDetails userDetails,
+            @PathVariable Long playingId,
+            @Valid @RequestBody MidiEventSaveRequest request
+    ){
+        Long userId = userDetails.getUserId();
+
+        MidiEventSaveResponse response = playingService.saveMidiEvents(
+                userId,
+                playingId,
+                request
+        );
+
+        return ApiResponse.onSuccess(response);
+    }
+}

src/main/java/com/mr/domain/playing/dto/req/MidiEventSaveRequest.java

@@ -0,0 +1,45 @@
+package com.mr.domain.playing.dto.req;
+
+import com.mr.domain.playing.entity.enums.MidiType;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.Size;
+
+import java.util.List;
+
+import static com.mr.domain.playing.constant.MidiEventConstants.MAX_MIDI_EVENT_COUNT;
+
+public record MidiEventSaveRequest (
+        @NotEmpty(message = "MIDI 이벤트 목록은 필수입니다")
+        @Size(max = MAX_MIDI_EVENT_COUNT, message = "MIDI 이벤트는 최대 100,000개까지 저장할 수 있습니다.")
+        List<@Valid MidiEventRequest> events
+) {
+
+    public record MidiEventRequest (
+
+        @NotNull(message = "MIDI 이벤트 순서 값은 필수입니다.")
+        @Min(value = 0, message = "MIDI 이벤트 순서 값은 0 이상이어야 합니다.")
+        Integer sequence,
+
+        @NotNull(message = "MIDI 이벤트 타입은 필수입니다.")
+        MidiType type,
+
+        @NotNull(message = "MIDI 피치 값은 필수입니다.")
+        @Min(value = 0, message = "MIDI 피치 값은 0 이상이어야 합니다.")
+        @Max(value = 127, message = "MIDI 피치 값은 127 이하여야 합니다.")
+        Integer pitch,
+
+        @NotNull(message = "MIDI 입력 강도 값은 필수입니다.")
+        @Min(value = 0, message = "MIDI 입력 강도 값은 0 이상이어야 합니다.")
+        @Max(value = 127, message = "MIDI 입력 강도 값은 127 이하여야 합니다.")
+        Integer velocity,
+
+        @NotNull(message = "MIDI 이벤트 발생 시간은 필수입니다.")
+        @Min(value = 0, message = "MIDI 이벤트 발생 시간은 0 이상이어야 합니다.")
+        Long timestampMs
+    ) {
+    }
+}

src/main/java/com/mr/domain/playing/dto/res/MidiEventSaveResponse.java

@@ -0,0 +1,11 @@
+package com.mr.domain.playing.dto.res;
+
+public record MidiEventSaveResponse(
+        Long playingId,
+        int savedCount
+) {
+
+    public static MidiEventSaveResponse of(Long playingId, int savedCount) {
+        return new MidiEventSaveResponse(playingId, savedCount);
+    }
+}

src/main/java/com/mr/domain/playing/entity/MidiEventData.java

@@ -3,7 +3,7 @@
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.mr.domain.playing.entity.enums.MidiType;
-import com.mr.domain.playing.exception.PlayingErrorStatus;
+import com.mr.domain.playing.exception.MidiEventErrorStatus;
 import com.mr.global.apipayload.exception.GeneralException;
 import lombok.Getter;
 
@@ -54,31 +54,31 @@ public static MidiEventData of(
 
     private static void validateSequence(Integer sequence) {
         if (sequence == null || sequence < 0) {
-            throw new GeneralException(PlayingErrorStatus.INVALID_MIDI_SEQUENCE);
+            throw new GeneralException(MidiEventErrorStatus.INVALID_MIDI_SEQUENCE);
         }
     }
 
     private static void validateMidiType(MidiType type) {
         if (type == null) {
-            throw new GeneralException(PlayingErrorStatus.MISSING_MIDI_TYPE);
+            throw new GeneralException(MidiEventErrorStatus.INVALID_MIDI_TYPE);
         }
     }
 
     private static void validatePitch(Integer pitch) {
         if (pitch == null || pitch < 0 || pitch > 127) {
-            throw new GeneralException(PlayingErrorStatus.INVALID_PITCH_RANGE);
+            throw new GeneralException(MidiEventErrorStatus.INVALID_PITCH_RANGE);
         }
     }
 
     private static void validateVelocity(Integer velocity) {
         if (velocity == null || velocity < 0 || velocity > 127) {
-            throw new GeneralException(PlayingErrorStatus.INVALID_VELOCITY_RANGE);
+            throw new GeneralException(MidiEventErrorStatus.INVALID_VELOCITY_RANGE);
         }
     }
 
     private static void validateTimestampMs(Long timestampMs) {
         if (timestampMs == null || timestampMs < 0) {
-            throw new GeneralException(PlayingErrorStatus.INVALID_TIMESTAMP);
+            throw new GeneralException(MidiEventErrorStatus.INVALID_TIMESTAMP);
         }
     }
 }

src/main/java/com/mr/domain/playing/entity/Playing.java

@@ -3,6 +3,7 @@
 import com.mr.domain.backingTrack.entity.BackingTrack;
 import com.mr.domain.playing.entity.enums.PlayingMode;
 import com.mr.domain.playing.entity.enums.PlayingStatus;
+import com.mr.domain.playing.exception.MidiEventErrorStatus;
 import com.mr.domain.playing.exception.PlayingErrorStatus;
 import com.mr.domain.user.entity.User;
 import com.mr.global.apipayload.exception.GeneralException;
@@ -36,6 +37,8 @@
 import java.util.Objects;
 import java.util.Set;
 
+import static com.mr.domain.playing.constant.MidiEventConstants.MAX_MIDI_EVENT_COUNT;
+
 @Entity
 @Table(
         name = "playing",
@@ -55,7 +58,6 @@ public class Playing extends BaseCreatedDeletedEntity {
     private static final long MAX_DURATION_MS = MAX_DURATION_SEC * 1000L;
 
     private static final long MIDI_TIMESTAMP_TOLERANCE_MS = 500L;       // 실제 연주 시간과 MIDI 이벤트 수집 종료 시점 간 허용 오차
-    private static final int MAX_MIDI_EVENT_COUNT = 100_000;
 
     @Id
     @GeneratedValue(strategy = GenerationType.IDENTITY)
@@ -187,42 +189,32 @@ public static Playing createBackingTrack(
 
     // 연주 완료 시 전체 MIDI 데이터를 저장하고 완료 상태로 전환
     public void completeWithMidiData(
-            List<MidiEventData> midiData
+            List<MidiEventData> requestedMidiData
     ) {
         validateCompletableStatus();
-        validateMidiData(midiData);
+        validateMidiData(requestedMidiData);
 
         LocalDateTime completedAt = LocalDateTime.now();
         long savedDurationMs = calculateDurationMs(this.startedAt, completedAt);
 
-        // 실제 연주 시간에 500ms의 오차를 허용하되, 최대 10분까지만 저장
-        long allowedTimestampMs = Math.min(savedDurationMs + MIDI_TIMESTAMP_TOLERANCE_MS,
-                MAX_DURATION_MS);
+        List<MidiEventData> normalizedMidiData = normalizeMidiData(requestedMidiData, savedDurationMs);
+        validateNormalizedMidiData(normalizedMidiData);
 
-        List<MidiEventData> sortedMidiData = midiData.stream()
-                .filter(event -> event.getTimestampMs() <= allowedTimestampMs)
-                .sorted(
-                        Comparator.comparingLong(MidiEventData::getTimestampMs)
-                        .thenComparingInt(MidiEventData::getSequence))
-                .toList();
+        this.midiData = new ArrayList<>(normalizedMidiData);
+        this.endedAt = calculateEndedAt(completedAt);
+        this.durationSec = convertToDurationSec(savedDurationMs);
+        this.status = PlayingStatus.COMPLETED;
+    }
 
-        if (sortedMidiData.isEmpty()) {
-            throw new GeneralException(
-                    PlayingErrorStatus.EMPTY_MIDI_EVENTS
-            );
+    public void validatePlayingOwner(Long userId) {
+        if (userId == null || this.user == null || !Objects.equals(this.user.getUserId(), userId)) {
+            throw new GeneralException(PlayingErrorStatus.PLAYING_ACCESS_DENIED);
         }
-
-        LocalDateTime maxEndedAt = this.startedAt.plusSeconds(MAX_DURATION_SEC);
-
-        this.midiData = new ArrayList<>(sortedMidiData);
-        this.endedAt = completedAt.isAfter(maxEndedAt) ? maxEndedAt : completedAt;
-        this.durationSec = Math.toIntExact(Duration.ofMillis(savedDurationMs).toSeconds());
-        this.status = PlayingStatus.COMPLETED;
     }
 
     private void validateCompletableStatus() {
         if (this.status != PlayingStatus.IN_PROGRESS) {
-            throw new GeneralException(PlayingErrorStatus.INVALID_PLAYING_STATUS);
+            throw new GeneralException(MidiEventErrorStatus.PLAYING_NOT_IN_PROGRESS);
         }
 
         if (startedAt == null) {
@@ -232,15 +224,19 @@ private void validateCompletableStatus() {
 
     private static void validateMidiData(List<MidiEventData> midiData) {
         if (midiData == null || midiData.isEmpty()) {
-            throw new GeneralException(PlayingErrorStatus.EMPTY_MIDI_EVENTS);
+            throw new GeneralException(MidiEventErrorStatus.EMPTY_MIDI_EVENTS);
         }
 
         if (midiData.size() > MAX_MIDI_EVENT_COUNT) {
-            throw new GeneralException(PlayingErrorStatus.EXCEEDED_MIDI_EVENT_COUNT);
+            throw new GeneralException(MidiEventErrorStatus.EXCEEDED_MIDI_EVENT_COUNT);
         }
 
         if (midiData.stream().anyMatch(Objects::isNull)) {
-            throw new GeneralException(PlayingErrorStatus.INVALID_MIDI_EVENT);
+            throw new GeneralException(MidiEventErrorStatus.INVALID_MIDI_EVENT);
+        }
+
+        if (midiData.stream().anyMatch(Playing::hasInvalidEventOrder)) {
+            throw new GeneralException(MidiEventErrorStatus.INVALID_MIDI_EVENT);
         }
 
         Set<MidiEventOrder> seenOrders = new HashSet<>();
@@ -253,12 +249,22 @@ private static void validateMidiData(List<MidiEventData> midiData) {
 
             if (!seenOrders.add(order)) {
                 throw new GeneralException(
-                        PlayingErrorStatus.DUPLICATE_MIDI_SEQUENCE
+                        MidiEventErrorStatus.DUPLICATE_MIDI_SEQUENCE
                 );
             }
         }
     }
 
+    private static void validateNormalizedMidiData(
+            List<MidiEventData> normalizedMidiData
+    ) {
+        if (normalizedMidiData.isEmpty()) {
+            throw new GeneralException(
+                    MidiEventErrorStatus.EMPTY_MIDI_EVENTS
+            );
+        }
+    }
+
     private record MidiEventOrder(
             Long timestampMs,
             Integer sequence
@@ -277,6 +283,25 @@ private static long calculateDurationMs(
         return Math.min(durationMs, MAX_DURATION_MS);
     }
 
+    private LocalDateTime calculateEndedAt(
+            LocalDateTime completedAt
+    ) {
+        LocalDateTime maxEndedAt =
+                this.startedAt.plusSeconds(MAX_DURATION_SEC);
+
+        return completedAt.isAfter(maxEndedAt)
+                ? maxEndedAt
+                : completedAt;
+    }
+
+    private static int convertToDurationSec(
+            long durationMs
+    ) {
+        return Math.toIntExact(
+                Duration.ofMillis(durationMs).toSeconds()
+        );
+    }
+
     public List<MidiEventData> getMidiData() {
 
         if (this.midiData == null) {
@@ -297,4 +322,25 @@ private void validateStartableStatus() {
             throw new GeneralException(PlayingErrorStatus.INVALID_PLAYING_STATUS);
         }
     }
+
+    private static List<MidiEventData> normalizeMidiData(
+            List<MidiEventData> midiData, long savedDurationMs) {
+        long allowedTimestampMs =
+                Math.min(savedDurationMs + MIDI_TIMESTAMP_TOLERANCE_MS, MAX_DURATION_MS);
+
+        return midiData.stream()
+                .filter(event -> event.getTimestampMs() <= allowedTimestampMs)
+                .sorted(Comparator.comparingLong(MidiEventData::getTimestampMs)
+                                .thenComparingInt(MidiEventData::getSequence)
+                ).toList();
+    }
+
+    private static boolean hasInvalidEventOrder(
+            MidiEventData event
+    ) {
+        return event.getTimestampMs() == null
+                || event.getTimestampMs() < 0
+                || event.getSequence() == null
+                || event.getSequence() < 0;
+    }
 }

src/main/java/com/mr/domain/playing/exception/MidiEventErrorStatus.java

@@ -0,0 +1,30 @@
+package com.mr.domain.playing.exception;
+
+import com.mr.global.apipayload.code.BaseCode;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import org.springframework.http.HttpStatus;
+
+@Getter
+@AllArgsConstructor
+public enum MidiEventErrorStatus implements BaseCode {
+
+    INVALID_PLAYING_ID(HttpStatus.BAD_REQUEST, "MIDI_400_01", "연주 ID가 올바르지 않습니다."),
+    EMPTY_MIDI_EVENTS(HttpStatus.BAD_REQUEST,"MIDI_400_02", "MIDI 이벤트 목록은 필수입니다."),
+    INVALID_MIDI_TYPE(HttpStatus.BAD_REQUEST, "MIDI_400_03", "MIDI 이벤트 타입이 올바르지 않습니다."),
+    INVALID_PITCH_RANGE(HttpStatus.BAD_REQUEST, "MIDI_400_04", "피치 값은 0~127 사이의 값이어야 합니다."),
+    INVALID_VELOCITY_RANGE(HttpStatus.BAD_REQUEST, "MIDI_400_05", "강도는 0~127 사이의 값이어야 합니다."),
+    INVALID_TIMESTAMP(HttpStatus.BAD_REQUEST, "MIDI_400_06", "MIDI 이벤트 타임스탬프는 0 이상이어야 합니다."),
+    INVALID_MIDI_EVENT(HttpStatus.BAD_REQUEST,"MIDI_400_07", "MIDI 이벤트 목록에 유효하지 않은 값이 포함되어 있습니다."),
+    INVALID_MIDI_SEQUENCE(HttpStatus.BAD_REQUEST, "MIDI_400_08", "MIDI 이벤트 순서(sequence) 값이 유효하지 않습니다."),
+    EXCEEDED_MIDI_EVENT_COUNT(HttpStatus.BAD_REQUEST, "MIDI_400_09", "MIDI 이벤트 개수가 허용 범위를 초과했습니다."),
+    DUPLICATE_MIDI_SEQUENCE(HttpStatus.BAD_REQUEST, "MIDI_400_10", "동일한 시간에 중복된 MIDI sequence 값이 존재합니다."),
+
+    PLAYING_NOT_IN_PROGRESS(HttpStatus.CONFLICT, "MIDI_409_01", "진행 중인 연주 세션에만 MIDI 이벤트를 저장할 수 있습니다."),
+    MIDI_SAVE_REQUEST_TOO_FREQUENT(HttpStatus.TOO_MANY_REQUESTS, "MIDI_429_01", "연주 완료 요청은 1분에 한 번만 가능합니다."),
+    ;
+
+    private final HttpStatus status;
+    private final String code;
+    private final String message;
+}

src/main/java/com/mr/domain/playing/exception/PlayingErrorStatus.java

@@ -14,18 +14,12 @@ public enum PlayingErrorStatus implements BaseCode {
     MISSING_BACKING_TRACK_ID(HttpStatus.BAD_REQUEST, "PLAYING_400_03", "백킹트랙 연주 모드에서는 백킹트랙 ID가 필수입니다."),
     MISSING_PLAYING(HttpStatus.BAD_REQUEST, "PLAYING_400_04", "MIDI 이벤트를 기록할 연주 정보가 누락되었습니다."),
     MISSING_MIDI_TYPE(HttpStatus.BAD_REQUEST, "PLAYING_400_05", "MIDI Type은 필수 입력 값입니다."),
-    INVALID_PITCH_RANGE(HttpStatus.BAD_REQUEST, "PLAYING_400_06", "피치 값은 0~127 사이의 값이어야 합니다."),
-    INVALID_VELOCITY_RANGE(HttpStatus.BAD_REQUEST, "PLAYING_400_07", "강도는 0~127 사이의 값이어야 합니다."),
-    INVALID_TIMESTAMP(HttpStatus.BAD_REQUEST, "PLAYING_400_08", "MIDI 이벤트 타임스탬프는 0 이상이어야 합니다."),
-    EMPTY_MIDI_EVENTS(HttpStatus.BAD_REQUEST, "PLAYING_400_09", "저장할 MIDI 이벤트가 없습니다."),
-    INVALID_MIDI_EVENT(HttpStatus.BAD_REQUEST,"PLAYING_400_10", "MIDI 이벤트 목록에 유효하지 않은 값이 포함되어 있습니다."),
+    // 기존 PLAYING_400_06 ~ PLAYING_400_10은 MidiEventErrorStatus로 분리
     MISSING_PLAYING_MODE(HttpStatus.BAD_REQUEST, "PLAYING_400_11", "연주 모드는 필수 입력값입니다."),
     MISSING_PLAYING_STATUS(HttpStatus.BAD_REQUEST, "PLAYING_400_12", "연주 상태는 필수 입력값입니다."),
     UNSUPPORTED_PLAYING_MODE(HttpStatus.BAD_REQUEST, "PLAYING_400_13", "현재 지원하지 않는 연주 모드입니다."),
-    EXCEEDED_MIDI_EVENT_COUNT(HttpStatus.BAD_REQUEST, "PLAYING_400_14", "MIDI 이벤트 개수가 허용 범위를 초과했습니다."),
-    INVALID_MIDI_SEQUENCE(HttpStatus.BAD_REQUEST, "PLAYING_400_15", "MIDI 이벤트 순서(sequence) 값이 유효하지 않습니다."),
-    DUPLICATE_MIDI_SEQUENCE(HttpStatus.BAD_REQUEST, "PLAYING_400_16", "중복된 MIDI sequence 값이 존재합니다."),
-
+    PLAYING_ACCESS_DENIED(HttpStatus.FORBIDDEN, "PLAYING_403_01", "해당 연주에 대한 접근 권한이 없습니다."),
+    PLAYING_NOT_FOUND(HttpStatus.NOT_FOUND, "PLAYING_404_01", "연주 세션을 찾을 수 없습니다."),
     INVALID_PLAYING_STATUS(HttpStatus.CONFLICT, "PLAYING_409_01", "현재 연주 상태에서는 요청한 작업을 수행할 수 없습니다."),
     MISSING_PLAYING_START_TIME(HttpStatus.CONFLICT, "PLAYING_409_02", "연주 시작 시간이 기록되지 않았습니다."),
     INVALID_PLAYING_DURATION(HttpStatus.CONFLICT, "PLAYING_409_03", "연주 종료 시간이 시작 시간보다 이전일 수 없습니다."),