feat(validation): declarative @Valid on write DTOs (Story 29.13) (#338)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gpascucci

backend/src/main/java/ca/bc/gov/nrs/ilcr/codetable/api/CodeTableApi.java

@@ -3,6 +3,7 @@
 import ca.bc.gov.nrs.ilcr.codetable.dto.CodeTableEntry;
 import ca.bc.gov.nrs.ilcr.codetable.dto.CodeTableSaveResponse;
 import ca.bc.gov.nrs.ilcr.codetable.dto.CodeTableSummary;
+import jakarta.validation.Valid;
 import java.util.List;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
@@ -55,6 +56,6 @@ ResponseEntity<List<CodeTableEntry>> getEntries(
   @PutMapping("/{tableKey}/entries")
   ResponseEntity<CodeTableSaveResponse> saveEntry(
       @PathVariable String tableKey,
-      @RequestBody CodeTableEntry entry,
+      @Valid @RequestBody CodeTableEntry entry,
       Authentication authentication);
 }

backend/src/main/java/ca/bc/gov/nrs/ilcr/codetable/dto/CodeTableEntry.java

@@ -1,16 +1,35 @@
 package ca.bc.gov.nrs.ilcr.codetable.dto;
 
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
 import java.time.LocalDate;
 
 /**
  * One row of a lookup code table (Story 24.3 / UC-CODE-001, BR-02): a code, its description, and the
  * effective/expiry window that gates whether downstream schedules offer it for a given year (BR-07).
  *
- * @param code the code value (the table's primary key); {@code null}/blank for a Contractual add
- * @param description the human-readable label
- * @param effectiveDate first day the code is offered (inclusive); {@code null} = no lower bound
+ * <p>Declarative constraints (Story 29.13) give the {@code saveEntry} write path a uniform 400
+ * {@code ProblemDetail} for shape violations via {@code @Valid} — the same error shape as the rest of
+ * the API — WITHOUT replacing the authoritative service-layer checks. {@code CodeTableService.validate}
+ * still owns the required/length/date-order rules and their verbatim legacy message keys (FLD-001..005,
+ * BR-06); these annotations are a declarative front line, not a replacement.
+ *
+ * <p>The {@code @Size} caps are deliberately OUTER BOUNDS — the maximum across every table
+ * ({@code CodeTableRegistry}: code ≤ 20, description ≤ 500) — because a record-level annotation carries
+ * one number but the real caps are PER-TABLE ({@code table.codeMaxLength()} /
+ * {@code descriptionMaxLength()}). Keeping the annotation at the outer bound means the exact per-table
+ * length rejection still comes from {@code validate()} with its verbatim message; the annotation only
+ * catches absurd input early. Do NOT tighten these to a single table's cap.
+ *
+ * @param code the code value (the table's primary key); required + within the table's code cap on save
+ * @param description the human-readable label; required + within the table's description cap on save
+ * @param effectiveDate first day the code is offered (inclusive); required on save
  * @param expiryDate last day the code is offered (inclusive); {@code null} = never expires
  */
 public record CodeTableEntry(
-    String code, String description, LocalDate effectiveDate, LocalDate expiryDate) {
+    @NotBlank(message = "{codeRequiredErrorMsg}") @Size(max = 20) String code,
+    @NotBlank(message = "{descriptionRequiredErrorMsg}") @Size(max = 500) String description,
+    @NotNull(message = "{effectiveDateRequiredErrorMsg}") LocalDate effectiveDate,
+    LocalDate expiryDate) {
 }

backend/src/main/java/ca/bc/gov/nrs/ilcr/reporting/api/ReportApi.java

@@ -1,5 +1,6 @@
 package ca.bc.gov.nrs.ilcr.reporting.api;
 
+import jakarta.validation.Valid;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -69,10 +70,15 @@ ResponseEntity<StreamingResponseBody> getSchedule9Pdf(
    * @param authentication the caller (authorized for VIEW_SCHEDULE — print is read-only, BR-01)
    * @return 200 streaming the combined PDF ({@code application/pdf} + attachment Content-Disposition)
    */
+  // @Valid here is a forward-looking safeguard (Story 29.13): PrintRequest is today an all-Boolean
+  // record whose compact constructor defaults every omitted flag to false, so there is nothing to
+  // constrain and @Valid is a no-op. It is declared so that if a non-Boolean field is ever added to
+  // PrintRequest, adding a constraint to that field is all it takes to have it enforced — the wiring
+  // is already here. Do NOT add constraints to the Boolean flags.
   @PostMapping("/print")
   ResponseEntity<StreamingResponseBody> printSchedules(
       @RequestParam(required = false) String millId,
       @RequestParam(required = false) String year,
-      @RequestBody PrintRequest request,
+      @Valid @RequestBody PrintRequest request,
       Authentication authentication);
 }

backend/src/test/java/ca/bc/gov/nrs/ilcr/codetable/CodeTableIT.java

@@ -93,6 +93,23 @@ void invalidDateRange_is400() throws Exception {
         .andExpect(jsonPath("$[*].code", not(hasItem("IT2"))));
   }
 
+  @Test
+  @DisplayName("blank code is rejected 400 problem+json by @Valid (Story 29.13, uniform shape)")
+  void blankCode_is400FromBeanValidation() throws Exception {
+    // @NotBlank on CodeTableEntry.code fails during request-body binding — BEFORE the controller and
+    // service run — so the uniform MethodArgumentNotValid handler answers with the same ProblemDetail
+    // shape every other 400 uses (title "Validation Failed"). The service-layer codeRequiredErrorMsg
+    // check remains as the authoritative belt-and-suspenders layer for the direct-service path.
+    String body = """
+        {"code":"","description":"Blank code","effectiveDate":"2020-01-01"}""";
+    mockMvc.perform(put(UNIT_ENTRIES).with(groups("ILCR_ADMIN"))
+            .contentType(MediaType.APPLICATION_JSON).content(body))
+        .andExpect(status().isBadRequest())
+        .andExpect(content().contentTypeCompatibleWith("application/problem+json"))
+        .andExpect(jsonPath("$.title").value("Validation Failed"))
+        .andExpect(jsonPath("$.detail").value("Code: Value is required."));
+  }
+
   @Test
   @DisplayName("ILCR_SUBMITTER is denied write — 403 (S13, admin-only action)")
   void submitter_isForbidden() throws Exception {