Implement persistence layer with binary serializer and state management

backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/application/AudioAnalysisUseCase.java

@@ -1,7 +1,10 @@
 package com.smartjam.smartjamanalyzer.application;
 
 import java.nio.file.Path;
+import java.util.UUID;
 
+import com.smartjam.common.model.AudioProcessingStatus;
+import com.smartjam.smartjamanalyzer.domain.model.AnalysisResult;
 import com.smartjam.smartjamanalyzer.domain.model.FeatureSequence;
 import com.smartjam.smartjamanalyzer.domain.port.*;
 import lombok.RequiredArgsConstructor;
@@ -19,12 +22,21 @@ public class AudioAnalysisUseCase {
     private final WorkspaceFactory workspaceFactory;
     private final FeatureExtractor featureExtractor;
 
+    private final PerformanceEvaluator performanceEvaluator;
+    private final ReferenceRepository referenceRepository;
+    private final ResultRepository resultRepository;
+    private final DebugVisualizer debugVisualizer;
+
     public void execute(String bucket, String fileKey) {
-        try (Workspace workspace = workspaceFactory.create()) {
+        UUID entityId = extractUuid(fileKey);
+
+        // TODO: Добавить обработку(проверку типа) входящего файла
+
+        // TODO: Добавить нормальный сбор метрик
 
-            // TODO: Добавить обработку(проверку типа) входящего файла
+        try (Workspace workspace = workspaceFactory.create()) {
+            updateStatus(bucket, entityId, AudioProcessingStatus.ANALYZING, null);
 
-            // TODO: Добавить нормальный сбор метрик
             StopWatch watch = new StopWatch(fileKey);
 
             log.info("=== Начало обработки файла: {} из бакета {} ===", fileKey, bucket);
@@ -37,24 +49,84 @@ public void execute(String bucket, String fileKey) {
             Path cleanWavFile = audioConverter.convertToStandardWav(localFile, workspace);
             watch.stop();
 
-            watch.start("Business Logic (Math)");
-
+            watch.start("Feature Extraction");
             FeatureSequence features = featureExtractor.extract(cleanWavFile);
+            watch.stop();
 
             log.info("Extracted {} feature frames", features.frames().size());
 
+            watch.start("Evaluation & Persistence");
             if ("references".equals(bucket)) {
-                log.info("Действие: Обработка ЭТАЛОНА учителя...");
+                handleTeacherReference(entityId, features);
             } else if ("submissions".equals(bucket)) {
-                log.info("Действие: Обработка ПОПЫТКИ ученика...");
+                handleStudentSubmission(entityId, features);
             }
             watch.stop();
 
             log.info("Результаты обработки {}: \n{}", fileKey, watch.prettyPrint());
 
         } catch (Exception e) {
-            log.error("Ошибка в UseCase для файла {}: {}", fileKey, e.getMessage());
+
+            String errorMsg =
+                    e.getMessage() != null ? e.getMessage() : e.getClass().getSimpleName();
+
+            log.error("Ошибка в UseCase для файла {}: {}", fileKey, errorMsg, e);
+            updateStatus(bucket, entityId, AudioProcessingStatus.FAILED, errorMsg);
+
             throw new RuntimeException("Business logic failed", e);
         }
     }
+
+    private void updateStatus(String bucket, UUID id, AudioProcessingStatus status, String error) {
+        try {
+            if ("references".equals(bucket)) {
+                referenceRepository.updateStatus(id, status, error);
+            } else {
+                resultRepository.updateStatus(id, status, error);
+            }
+        } catch (Exception ex) {
+            log.error("Failed to update status in DB for {}: {}", id, ex.getMessage());
+        }
+    }
+
+    private void handleTeacherReference(UUID assignmentId, FeatureSequence teacherFeatures) {
+        log.info("Saving teacher reference features for assignment: {}", assignmentId);
+        referenceRepository.save(assignmentId, teacherFeatures);
+    }
+
+    private void handleStudentSubmission(UUID submissionId, FeatureSequence studentFeatures) {
+        log.info("Evaluating student submission: {}", submissionId);
+
+        UUID assignmentId = resultRepository
+                .findAssignmentIdBySubmissionId(submissionId)
+                .orElseThrow(() ->
+                        new IllegalStateException("Submission " + submissionId + " is not linked to any assignment"));
+
+        FeatureSequence teacherFeatures = referenceRepository
+                .findFeaturesById(assignmentId)
+                .orElseThrow(() -> new IllegalStateException(
+                        "Teacher reference features not found for assignment: " + assignmentId));
+
+        AnalysisResult result = performanceEvaluator.evaluate(teacherFeatures, studentFeatures);
+
+        resultRepository.save(submissionId, result);
+
+        try {
+            debugVisualizer.generateHeatmap(result, "debug_" + submissionId + ".png");
+        } catch (Exception e) {
+            log.error("Не удалось сгенерировать тепловую карту {}: {}", submissionId, e.getMessage());
+        }
+
+        log.info("Submission {} evaluation completed.", submissionId);
+    }
+
+    private UUID extractUuid(String fileKey) {
+        try {
+            String rawUuid = fileKey.contains(".") ? fileKey.substring(0, fileKey.lastIndexOf(".")) : fileKey;
+
+            return UUID.fromString(rawUuid);
+        } catch (Exception e) {
+            throw new IllegalArgumentException("Invalid S3 file key. Expected UUID, got: " + fileKey);
+        }
+    }
 }

backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/domain/port/ReferenceRepository.java

@@ -1,11 +1,36 @@
 package com.smartjam.smartjamanalyzer.domain.port;
 
+import java.util.Optional;
 import java.util.UUID;
 
+import com.smartjam.common.model.AudioProcessingStatus;
 import com.smartjam.smartjamanalyzer.domain.model.FeatureSequence;
 
+/** Domain port for managing teacher reference features. */
 public interface ReferenceRepository {
-    void save(UUID targetId, FeatureSequence features);
 
-    FeatureSequence findById(UUID targetId);
+    /**
+     * Saves the spectral features of a teacher's reference track.
+     *
+     * @param assignmentId Unique identifier of the assignment.
+     * @param features Extracted features to persist.
+     */
+    void save(UUID assignmentId, FeatureSequence features);
+
+    /**
+     * Retrieves reference features for comparison.
+     *
+     * @param assignmentId Unique identifier of the assignment.
+     * @return The feature sequence if presented.
+     */
+    Optional<FeatureSequence> findFeaturesById(UUID assignmentId);
+
+    /**
+     * Performs an optimized status update for an assignment, optionally recording an error message.
+     *
+     * @param assignmentId unique identifier of the submission.
+     * @param status the new processing state.
+     * @param errorMessage description of the failure, if applicable.
+     */
+    void updateStatus(UUID assignmentId, AudioProcessingStatus status, String errorMessage);
 }

backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/domain/port/ResultRepository.java

@@ -1,9 +1,40 @@
 package com.smartjam.smartjamanalyzer.domain.port;
 
+import java.util.Optional;
 import java.util.UUID;
 
+import com.smartjam.common.model.AudioProcessingStatus;
 import com.smartjam.smartjamanalyzer.domain.model.AnalysisResult;
 
+/**
+ * Port for managing student submissions and their analysis results. Handles the persistence of evaluation scores and
+ * detailed feedback events.
+ */
 public interface ResultRepository {
+
+    /**
+     * Persists the final analysis result for a specific submission.
+     *
+     * @param submissionId unique identifier of the student submission.
+     * @param result calculated scores and feedback events.
+     */
     void save(UUID submissionId, AnalysisResult result);
+
+    /**
+     * Resolves the teacher's assignment ID associated with a given student submission.
+     *
+     * @param submissionId unique identifier of the submission.
+     * @return the UUID of the parent assignment.
+     * @throws RuntimeException if no linked assignment ID found.
+     */
+    Optional<UUID> findAssignmentIdBySubmissionId(UUID submissionId);
+
+    /**
+     * Update status for a submission, optionally recording an error message.
+     *
+     * @param submissionId unique identifier of the submission.
+     * @param status the new processing state.
+     * @param errorMessage description of the failure, if applicable.
+     */
+    void updateStatus(UUID submissionId, AudioProcessingStatus status, String errorMessage);
 }

backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/persistence/adapter/AssignmentPersistenceAdapter.java

@@ -0,0 +1,64 @@
+package com.smartjam.smartjamanalyzer.infrastructure.persistence.adapter;
+
+import java.util.Optional;
+import java.util.UUID;
+
+import com.smartjam.common.model.AudioProcessingStatus;
+import com.smartjam.smartjamanalyzer.domain.model.FeatureSequence;
+import com.smartjam.smartjamanalyzer.domain.port.ReferenceRepository;
+import com.smartjam.smartjamanalyzer.infrastructure.persistence.entity.AssignmentEntity;
+import com.smartjam.smartjamanalyzer.infrastructure.persistence.repository.JpaAssignmentRepository;
+import com.smartjam.smartjamanalyzer.infrastructure.utils.FeatureBinarySerializer;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * JPA implementation of {@link ReferenceRepository}. Bridges the domain logic with the database using binary
+ * serialization for spectral data.
+ */
+@Component
+@RequiredArgsConstructor
+public class AssignmentPersistenceAdapter implements ReferenceRepository {
+    private final JpaAssignmentRepository repository;
+
+    /**
+     * Packs spectral features into a binary format and saves them to the assignment record. Transition the status to
+     * {@link AudioProcessingStatus#COMPLETED}.
+     */
+    @Override
+    @Transactional
+    public void save(UUID assignmentId, FeatureSequence features) {
+        byte[] bytes = FeatureBinarySerializer.serialize(features);
+
+        AssignmentEntity entity = repository
+                .findById(assignmentId)
+                .orElseThrow(() -> new IllegalStateException("Assignment metadata missing for ID: " + assignmentId
+                        + ". It might have " + "been deleted or not created yet."));
+
+        entity.setReferenceSpectreCache(bytes);
+        entity.setStatus(AudioProcessingStatus.COMPLETED);
+        entity.setErrorMessage(null);
+
+        repository.save(entity);
+    }
+
+    /**
+     * Retrieves and unpacks binary features from the database.
+     *
+     * @return an Optional containing the FeatureSequence, or empty if not found.
+     */
+    @Override
+    @Transactional(readOnly = true)
+    public Optional<FeatureSequence> findFeaturesById(UUID assignmentId) {
+        return repository
+                .findById(assignmentId)
+                .map(e -> FeatureBinarySerializer.deserialize(e.getReferenceSpectreCache()));
+    }
+
+    @Override
+    @Transactional
+    public void updateStatus(UUID id, AudioProcessingStatus status, String errorMessage) {
+        repository.updateStatus(id, status, errorMessage);
+    }
+}

backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/persistence/adapter/SubmissionPersistenceAdapter.java

@@ -0,0 +1,56 @@
+package com.smartjam.smartjamanalyzer.infrastructure.persistence.adapter;
+
+import java.util.Optional;
+import java.util.UUID;
+
+import com.smartjam.common.model.AudioProcessingStatus;
+import com.smartjam.smartjamanalyzer.domain.model.AnalysisResult;
+import com.smartjam.smartjamanalyzer.domain.port.ResultRepository;
+import com.smartjam.smartjamanalyzer.infrastructure.persistence.entity.SubmissionEntity;
+import com.smartjam.smartjamanalyzer.infrastructure.persistence.repository.JpaSubmissionRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * JPA implementation of {@link ResultRepository}. Manages storage of evaluation results and coordinates mapping between
+ * domain results and JSONB database columns.
+ */
+@Component
+@RequiredArgsConstructor
+public class SubmissionPersistenceAdapter implements ResultRepository {
+    private final JpaSubmissionRepository repository;
+
+    /**
+     * Updates the submission record with scores and feedback. Transition the status to
+     * {@link AudioProcessingStatus#COMPLETED}.
+     */
+    @Override
+    @Transactional
+    public void save(UUID submissionId, AnalysisResult result) {
+        SubmissionEntity entity = repository
+                .findById(submissionId)
+                .orElseThrow(() -> new IllegalStateException("Submission record missing for ID: " + submissionId));
+
+        entity.setTotalScore(result.totalScore());
+        entity.setPitchScore(result.pitchScore());
+        entity.setRhythmScore(result.rhythmScore());
+        entity.setAnalysisFeedback(result.feedback());
+        entity.setStatus(AudioProcessingStatus.COMPLETED);
+        entity.setErrorMessage(null);
+
+        repository.save(entity);
+    }
+
+    @Override
+    @Transactional(readOnly = true)
+    public Optional<UUID> findAssignmentIdBySubmissionId(UUID submissionId) {
+        return repository.findById(submissionId).map(SubmissionEntity::getAssignmentId);
+    }
+
+    @Override
+    @Transactional
+    public void updateStatus(UUID submissionId, AudioProcessingStatus status, String errorMessage) {
+        repository.updateStatus(submissionId, status, errorMessage);
+    }
+}

backend/smartjam-analyzer/src/main/java/com/smartjam/smartjamanalyzer/infrastructure/persistence/entity/AssignmentEntity.java

@@ -0,0 +1,30 @@
+package com.smartjam.smartjamanalyzer.infrastructure.persistence.entity;
+
+import java.util.UUID;
+
+import jakarta.persistence.*;
+
+import com.smartjam.common.model.AudioProcessingStatus;
+import lombok.*;
+
+/** Database model for teacher assignments. Stores heavy spectral data as raw bytes (BYTEA) to optimize performance. */
+@Entity
+@Table(name = "assignments")
+@Getter
+@Setter
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class AssignmentEntity {
+    @Id
+    private UUID id;
+
+    @Enumerated(EnumType.STRING)
+    private AudioProcessingStatus status;
+
+    @Column(name = "reference_spectre_cache")
+    private byte[] referenceSpectreCache;
+
+    @Column(name = "error_message", columnDefinition = "TEXT")
+    private String errorMessage;
+}