From 779ffaab552a698b3ffb3c219a3a70998a020c73 Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Sat, 25 Apr 2026 14:27:46 +0200
Subject: [PATCH] feat(bulk-edit): scaffold DTOs and BULK_EDIT_TOO_MANY_IDS
 error code

Adds the request/response shapes for the upcoming PATCH /api/documents/bulk,
POST /api/documents/batch-metadata, and the new error code for the 500-ID cap.

Refs #225

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../dto/BatchMetadataRequest.java             |  9 ++++++++
 .../familienarchiv/dto/BulkEditError.java     |  9 ++++++++
 .../familienarchiv/dto/BulkEditResult.java    |  9 ++++++++
 .../dto/DocumentBatchSummary.java             | 10 +++++++++
 .../dto/DocumentBulkEditDTO.java              | 21 +++++++++++++++++++
 .../familienarchiv/exception/ErrorCode.java   |  2 ++
 6 files changed, 60 insertions(+)
 create mode 100644 backend/src/main/java/org/raddatz/familienarchiv/dto/BatchMetadataRequest.java
 create mode 100644 backend/src/main/java/org/raddatz/familienarchiv/dto/BulkEditError.java
 create mode 100644 backend/src/main/java/org/raddatz/familienarchiv/dto/BulkEditResult.java
 create mode 100644 backend/src/main/java/org/raddatz/familienarchiv/dto/DocumentBatchSummary.java
 create mode 100644 backend/src/main/java/org/raddatz/familienarchiv/dto/DocumentBulkEditDTO.java

diff --git a/backend/src/main/java/org/raddatz/familienarchiv/dto/BatchMetadataRequest.java b/backend/src/main/java/org/raddatz/familienarchiv/dto/BatchMetadataRequest.java
new file mode 100644
index 00000000..47bc489b
--- /dev/null
+++ b/backend/src/main/java/org/raddatz/familienarchiv/dto/BatchMetadataRequest.java
@@ -0,0 +1,9 @@
+package org.raddatz.familienarchiv.dto;
+
+import java.util.List;
+import java.util.UUID;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+public record BatchMetadataRequest(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) List<UUID> ids) {}
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/dto/BulkEditError.java b/backend/src/main/java/org/raddatz/familienarchiv/dto/BulkEditError.java
new file mode 100644
index 00000000..2bde3fdd
--- /dev/null
+++ b/backend/src/main/java/org/raddatz/familienarchiv/dto/BulkEditError.java
@@ -0,0 +1,9 @@
+package org.raddatz.familienarchiv.dto;
+
+import java.util.UUID;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+public record BulkEditError(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String message) {}
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/dto/BulkEditResult.java b/backend/src/main/java/org/raddatz/familienarchiv/dto/BulkEditResult.java
new file mode 100644
index 00000000..af8608b1
--- /dev/null
+++ b/backend/src/main/java/org/raddatz/familienarchiv/dto/BulkEditResult.java
@@ -0,0 +1,9 @@
+package org.raddatz.familienarchiv.dto;
+
+import java.util.List;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+public record BulkEditResult(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) int updated,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) List<BulkEditError> errors) {}
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/dto/DocumentBatchSummary.java b/backend/src/main/java/org/raddatz/familienarchiv/dto/DocumentBatchSummary.java
new file mode 100644
index 00000000..aaea14a0
--- /dev/null
+++ b/backend/src/main/java/org/raddatz/familienarchiv/dto/DocumentBatchSummary.java
@@ -0,0 +1,10 @@
+package org.raddatz.familienarchiv.dto;
+
+import java.util.UUID;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+public record DocumentBatchSummary(
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) UUID id,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String title,
+        @Schema(requiredMode = Schema.RequiredMode.REQUIRED) String pdfUrl) {}
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/dto/DocumentBulkEditDTO.java b/backend/src/main/java/org/raddatz/familienarchiv/dto/DocumentBulkEditDTO.java
new file mode 100644
index 00000000..ad6d246e
--- /dev/null
+++ b/backend/src/main/java/org/raddatz/familienarchiv/dto/DocumentBulkEditDTO.java
@@ -0,0 +1,21 @@
+package org.raddatz.familienarchiv.dto;
+
+import java.util.List;
+import java.util.UUID;
+
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import lombok.AllArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class DocumentBulkEditDTO {
+    private List<UUID> documentIds;
+    private List<String> tagNames;
+    private UUID senderId;
+    private List<UUID> receiverIds;
+    private String documentLocation;
+    private String archiveBox;
+    private String archiveFolder;
+}
diff --git a/backend/src/main/java/org/raddatz/familienarchiv/exception/ErrorCode.java b/backend/src/main/java/org/raddatz/familienarchiv/exception/ErrorCode.java
index 686c8627..187b793d 100644
--- a/backend/src/main/java/org/raddatz/familienarchiv/exception/ErrorCode.java
+++ b/backend/src/main/java/org/raddatz/familienarchiv/exception/ErrorCode.java
@@ -111,6 +111,8 @@ public enum ErrorCode {
     VALIDATION_ERROR,
     /** Batch upload exceeds the maximum allowed file count per request. 400 */
     BATCH_TOO_LARGE,
+    /** Bulk edit request exceeds the per-request document ID cap. 400 */
+    BULK_EDIT_TOO_MANY_IDS,
     /** An unexpected server-side error occurred. 500 */
     INTERNAL_ERROR,
 }