Merge branch 'main' into fix/home-content-followups

Author: gpascucci

.github/workflows/analysis.yml

@@ -68,7 +68,12 @@ jobs:
       checks: write
       security-events: write
     runs-on: ubuntu-24.04
-    timeout-minutes: 5
+    # Covers all four commands below — npm ci, lint, format:check AND a coverage run — not the tests
+    # alone. Raised from 5 after PR #317 was cancelled at 4m58s with zero test failures: the same job
+    # had passed at 3m22s one commit earlier, so the 5-minute budget was already two thirds spent and
+    # a growing component suite left no room for runner variance. 10 restores headroom without
+    # hiding a genuine hang.
+    timeout-minutes: 10
     steps:
       - uses: bcgov/action-test-and-analyse@8f699e3fd3fadd9a6adf6f4b1f2638ef7ecfefb9 # v2.0.0
         env:

backend/src/main/java/ca/bc/gov/nrs/ilcr/homecontent/HomeContentController.java

@@ -0,0 +1,67 @@
+package ca.bc.gov.nrs.ilcr.homecontent;
+
+import ca.bc.gov.nrs.ilcr.dto.base.Role;
+import ca.bc.gov.nrs.ilcr.homecontent.api.HomeContentApi;
+import ca.bc.gov.nrs.ilcr.homecontent.dto.HomeContentEntry;
+import ca.bc.gov.nrs.ilcr.homecontent.dto.HomeContentSaveRequest;
+import ca.bc.gov.nrs.ilcr.homecontent.dto.HomeContentSaveResponse;
+import java.util.List;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.MessageSource;
+import org.springframework.context.i18n.LocaleContextHolder;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * Content Editing endpoints (Story 24.2 / UC-CNT-001). {@code list}/{@code save} are gated on the
+ * ADMIN-only {@code EDIT_HOME_CONTENT} action (S13); {@code mine} is authenticated-only so the Home
+ * page can render the viewer's role message. Resolves the verbatim success text here (AD-8).
+ */
+@RestController
+@ConditionalOnProperty(name = "ilcr.datasource.enabled", havingValue = "true")
+public class HomeContentController implements HomeContentApi {
+
+  private static final String MSG_SAVED = "dataSavedSuccesfullyInfoMsg";
+
+  private final HomeContentService service;
+  private final MessageSource messageSource;
+
+  public HomeContentController(HomeContentService service, MessageSource messageSource) {
+    this.service = service;
+    this.messageSource = messageSource;
+  }
+
+  @Override
+  @PreAuthorize("@permissions.hasPermission(authentication, 'EDIT_HOME_CONTENT')")
+  public ResponseEntity<List<HomeContentEntry>> list(Authentication authentication) {
+    return ResponseEntity.ok(service.readAll());
+  }
+
+  @Override
+  @PreAuthorize("isAuthenticated()")
+  public ResponseEntity<HomeContentEntry> mine(Authentication authentication) {
+    return ResponseEntity.ok(service.readForRole(contentRoleOf(authentication)));
+  }
+
+  @Override
+  @PreAuthorize("@permissions.hasPermission(authentication, 'EDIT_HOME_CONTENT')")
+  public ResponseEntity<HomeContentSaveResponse> save(
+      HomeContentSaveRequest request, Authentication authentication) {
+    service.saveAll(request, authentication.getName());
+    String message =
+        messageSource.getMessage(MSG_SAVED, null, MSG_SAVED, LocaleContextHolder.getLocale());
+    return ResponseEntity.ok(new HomeContentSaveResponse(MSG_SAVED, message, service.readAll()));
+  }
+
+  /** ILCR_ADMIN → the Administrator message; everyone else (Licensee/submitter) → the Licensee one. */
+  private static String contentRoleOf(Authentication authentication) {
+    boolean admin = authentication != null && authentication.getAuthorities().stream()
+        .map(GrantedAuthority::getAuthority)
+        .map(Role::fromValue)
+        .anyMatch(role -> role == Role.ADMIN);
+    return admin ? HomeContentService.ROLE_ADMIN : HomeContentService.ROLE_LICENSEE;
+  }
+}

backend/src/main/java/ca/bc/gov/nrs/ilcr/homecontent/HomeContentException.java

@@ -0,0 +1,27 @@
+package ca.bc.gov.nrs.ilcr.homecontent;
+
+import ca.bc.gov.nrs.ilcr.exception.BusinessException;
+import org.springframework.http.HttpStatus;
+
+/**
+ * Business failures for Home content editing (Story 24.2 / UC-CNT-001): a role's message record
+ * missing at load/save (404, ERR-002) or a message exceeding the column cap (400). Carries a
+ * {@code messages.properties} key the {@code GlobalExceptionHandler} resolves (AD-8). Blank-editor
+ * rejections use {@code FieldValuesRequiredException} (all blanks reported together, FLD-001).
+ */
+public class HomeContentException extends BusinessException {
+
+  private HomeContentException(HttpStatus status, String messageKey) {
+    super(status, messageKey);
+  }
+
+  /** A role's message record does not exist (S10). */
+  public static HomeContentException contentNotFound() {
+    return new HomeContentException(HttpStatus.NOT_FOUND, "homeContentNotFoundErrorMsg");
+  }
+
+  /** A message exceeds the {@code MESSAGE_TEXT} column cap (4000). */
+  public static HomeContentException tooLong() {
+    return new HomeContentException(HttpStatus.BAD_REQUEST, "homeContentTooLongErrorMsg");
+  }
+}

backend/src/main/java/ca/bc/gov/nrs/ilcr/homecontent/HomeContentRepository.java

@@ -0,0 +1,55 @@
+package ca.bc.gov.nrs.ilcr.homecontent;
+
+import ca.bc.gov.nrs.ilcr.homecontent.dto.HomeContentEntry;
+import java.util.List;
+import java.util.Optional;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.jdbc.core.RowMapper;
+import org.springframework.jdbc.core.namedparam.MapSqlParameterSource;
+import org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate;
+import org.springframework.stereotype.Repository;
+
+/**
+ * Reads and updates the role-keyed Home messages in the legacy {@code THE.ILCR_ROLE} table (Story 24.2
+ * / UC-CNT-001): PK {@code ILCR_ROLE_NAME} ({@code LICENSEE}/{@code AUDITOR}/{@code ADMIN}), the
+ * rich-text {@code MESSAGE_TEXT VARCHAR2(4000)}, and the NOT NULL audit quartet. Every value is a bound
+ * named parameter; the acting admin + {@code SYSTIMESTAMP} are stamped on each update (AD-11).
+ */
+@Repository
+@ConditionalOnProperty(name = "ilcr.datasource.enabled", havingValue = "true")
+public class HomeContentRepository {
+
+  private static final RowMapper<HomeContentEntry> MAPPER =
+      (rs, rowNum) -> new HomeContentEntry(rs.getString("ILCR_ROLE_NAME"), rs.getString("MESSAGE_TEXT"));
+
+  private final NamedParameterJdbcTemplate jdbc;
+
+  public HomeContentRepository(NamedParameterJdbcTemplate jdbc) {
+    this.jdbc = jdbc;
+  }
+
+  /** All role messages, role-ordered (the Content Editing page loads all three). */
+  public List<HomeContentEntry> findAll() {
+    return jdbc.query(
+        "SELECT ILCR_ROLE_NAME, MESSAGE_TEXT FROM THE.ILCR_ROLE ORDER BY ILCR_ROLE_NAME", MAPPER);
+  }
+
+  /** One role's message (the Home render of the viewer's role), or empty when the row is absent. */
+  public Optional<HomeContentEntry> findByRole(String role) {
+    return jdbc.query(
+        "SELECT ILCR_ROLE_NAME, MESSAGE_TEXT FROM THE.ILCR_ROLE WHERE ILCR_ROLE_NAME = :role",
+        new MapSqlParameterSource("role", role), MAPPER).stream().findFirst();
+  }
+
+  /** Update one role's message + audit columns; returns rows affected (0 when the role is absent). */
+  public int updateMessage(String role, String messageText, String user) {
+    return jdbc.update(
+        "UPDATE THE.ILCR_ROLE SET MESSAGE_TEXT = :text, UPDATE_USERID = :user, "
+            + "UPDATE_TIMESTAMP = SYSTIMESTAMP, REVISION_COUNT = REVISION_COUNT + 1 "
+            + "WHERE ILCR_ROLE_NAME = :role",
+        new MapSqlParameterSource()
+            .addValue("text", messageText)
+            .addValue("user", user)
+            .addValue("role", role));
+  }
+}

backend/src/main/java/ca/bc/gov/nrs/ilcr/homecontent/HomeContentService.java

@@ -0,0 +1,112 @@
+package ca.bc.gov.nrs.ilcr.homecontent;
+
+import ca.bc.gov.nrs.ilcr.exception.FieldValuesRequiredException;
+import ca.bc.gov.nrs.ilcr.homecontent.dto.HomeContentEntry;
+import ca.bc.gov.nrs.ilcr.homecontent.dto.HomeContentSaveRequest;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * Content Editing service (Story 24.2 / UC-CNT-001): reads the three role messages, serves one role's
+ * message for the Home render, and saves all three ATOMICALLY (A-3 — the legacy per-role
+ * non-atomic save S09 is fixed: one transaction, all-or-nothing).
+ *
+ * <p>Each editor is required (FLD-001) — validated before any write so a rejection saves nothing, with
+ * ALL blank editors reported together. On save the legacy transform is applied (tabs/newlines/{@code
+ * &nbsp;}, D-3). Rich text is stored raw (legacy stored the WYSIWYG HTML unsanitized); the Home render
+ * sanitizes with DOMPurify (defence-in-depth), so no server-side HTML rewrite happens here.
+ */
+@Slf4j
+@Service
+@ConditionalOnProperty(name = "ilcr.datasource.enabled", havingValue = "true")
+public class HomeContentService {
+
+  static final String ROLE_LICENSEE = "LICENSEE";
+  static final String ROLE_AUDITOR = "AUDITOR";
+  static final String ROLE_ADMIN = "ADMIN";
+  private static final int MAX_MESSAGE_LENGTH = 4000;
+  // Field labels for the FLD-001 required-field messages — verbatim from legacy content.xhtml.
+  private static final String LABEL_LICENSEE = "Licensee Welcome Message";
+  private static final String LABEL_AUDITOR = "Auditor Welcome Message";
+  private static final String LABEL_ADMIN = "Administrator Welcome Message";
+
+  private final HomeContentRepository repository;
+
+  public HomeContentService(HomeContentRepository repository) {
+    this.repository = repository;
+  }
+
+  /** All three role messages for the Content Editing page. */
+  public List<HomeContentEntry> readAll() {
+    return repository.findAll();
+  }
+
+  /** The message for one role — the Home render of the viewer's role (empty text when none). */
+  public HomeContentEntry readForRole(String role) {
+    return repository.findByRole(role).orElse(new HomeContentEntry(role, null));
+  }
+
+  /**
+   * Save all three role messages in one transaction (A-3). Validate every editor first (FLD-001, all
+   * blanks together), then transform + update each; any failure rolls the whole save back.
+   *
+   * @param request the three messages
+   * @param user the acting administrator (audit)
+   */
+  @Transactional
+  public void saveAll(HomeContentSaveRequest request, String user) {
+    List<RoleMessage> messages = List.of(
+        new RoleMessage(ROLE_LICENSEE, LABEL_LICENSEE, request.licensee()),
+        new RoleMessage(ROLE_AUDITOR, LABEL_AUDITOR, request.auditor()),
+        new RoleMessage(ROLE_ADMIN, LABEL_ADMIN, request.administrator()));
+
+    List<String> blankLabels = new ArrayList<>();
+    for (RoleMessage message : messages) {
+      if (isBlankHtml(message.text())) {
+        blankLabels.add(message.label());
+      }
+    }
+    if (!blankLabels.isEmpty()) {
+      throw new FieldValuesRequiredException(blankLabels);
+    }
+
+    for (RoleMessage message : messages) {
+      String transformed = transform(message.text());
+      // Cap by BYTES: MESSAGE_TEXT is VARCHAR2(4000 BYTE), so multi-byte content (smart quotes,
+      // em dashes from paste) could pass a char-count check and then fail the insert with ORA-12899.
+      if (transformed.getBytes(StandardCharsets.UTF_8).length > MAX_MESSAGE_LENGTH) {
+        throw HomeContentException.tooLong();
+      }
+      if (repository.updateMessage(message.role(), transformed, user) == 0) {
+        throw HomeContentException.contentNotFound();
+      }
+    }
+    log.info("Home content updated (3 role messages) by {}", user);
+  }
+
+  /** Empty once tags, {@code &nbsp;} and whitespace are stripped — the required-editor check. */
+  private static boolean isBlankHtml(String html) {
+    if (html == null) {
+      return true;
+    }
+    return html.replaceAll("<[^>]*>", "").replace("&nbsp;", " ").strip().isEmpty();
+  }
+
+  /**
+   * Save-transform after {@code CoreUtil.replaceCharsForExtractFormat}: tab &rarr; two spaces, newline
+   * &rarr; one space. Legacy dropped {@code &nbsp;} entirely (CoreUtil.java:972), but the legacy
+   * PrimeFaces editor rarely emitted it; TipTap emits {@code &nbsp;} for leading/consecutive spaces,
+   * so dropping it would silently delete word breaks. We map it to a space instead (deliberate,
+   * editor-driven deviation from legacy).
+   */
+  private static String transform(String text) {
+    return text.replace("\t", "  ").replace("\n", " ").replace("&nbsp;", " ");
+  }
+
+  private record RoleMessage(String role, String label, String text) {}
+}

backend/src/main/java/ca/bc/gov/nrs/ilcr/homecontent/api/HomeContentApi.java

@@ -0,0 +1,53 @@
+package ca.bc.gov.nrs.ilcr.homecontent.api;
+
+import ca.bc.gov.nrs.ilcr.homecontent.dto.HomeContentEntry;
+import ca.bc.gov.nrs.ilcr.homecontent.dto.HomeContentSaveRequest;
+import ca.bc.gov.nrs.ilcr.homecontent.dto.HomeContentSaveResponse;
+import java.util.List;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+
+/**
+ * Content Editing API contract (Story 24.2 / UC-CNT-001; controller + api-interface split). The
+ * interface owns the request mapping; {@code HomeContentController} adds authorization. {@code list}
+ * and {@code save} are ADMIN-only ({@code EDIT_HOME_CONTENT}, 403 for a submitter, S13); {@code mine}
+ * is authenticated-only — any signed-in user reads their own role's message for the Home render.
+ */
+@RequestMapping("/api/v1/home-content")
+public interface HomeContentApi {
+
+  /**
+   * The three role messages for the Content Editing page.
+   *
+   * @param authentication the caller (must hold {@code EDIT_HOME_CONTENT})
+   * @return 200 with the role messages
+   */
+  @GetMapping
+  ResponseEntity<List<HomeContentEntry>> list(Authentication authentication);
+
+  /**
+   * The message for the CALLER's role — the Home page render (Licensee for a submitter, Administrator
+   * for an admin). Authenticated but not admin-gated.
+   *
+   * @param authentication the caller
+   * @return 200 with the caller-role message
+   */
+  @GetMapping("/mine")
+  ResponseEntity<HomeContentEntry> mine(Authentication authentication);
+
+  /**
+   * Save all three role messages atomically. Any blank editor → 400 with all blanks reported together
+   * (FLD-001) and nothing saved; a message over the column cap → 400; a missing role row → 404.
+   *
+   * @param request the three messages
+   * @param authentication the caller (must hold {@code EDIT_HOME_CONTENT}; drives the audit user)
+   * @return 200 with the verbatim success message + reloaded messages
+   */
+  @PutMapping
+  ResponseEntity<HomeContentSaveResponse> save(
+      @RequestBody HomeContentSaveRequest request, Authentication authentication);
+}

backend/src/main/java/ca/bc/gov/nrs/ilcr/homecontent/dto/HomeContentEntry.java

@@ -0,0 +1,12 @@
+package ca.bc.gov.nrs.ilcr.homecontent.dto;
+
+/**
+ * One role-keyed Home message (Story 24.2 / UC-CNT-001). {@code role} is the {@code THE.ILCR_ROLE}
+ * key ({@code LICENSEE} / {@code AUDITOR} / {@code ADMIN}); {@code messageText} is the stored rich-text
+ * (HTML) message, or {@code null} when the role has no message yet.
+ *
+ * @param role the role key
+ * @param messageText the rich-text message (HTML), may be {@code null}
+ */
+public record HomeContentEntry(String role, String messageText) {
+}

backend/src/main/java/ca/bc/gov/nrs/ilcr/homecontent/dto/HomeContentSaveRequest.java

@@ -0,0 +1,12 @@
+package ca.bc.gov.nrs.ilcr.homecontent.dto;
+
+/**
+ * The Content Editing save payload (Story 24.2 / UC-CNT-001): all three role messages, saved together
+ * atomically (A-3). Each is required rich-text (HTML); a blank editor is rejected per-field (FLD-001).
+ *
+ * @param licensee the Licensee welcome message
+ * @param auditor the Auditor-keyed welcome message
+ * @param administrator the Administrator welcome message
+ */
+public record HomeContentSaveRequest(String licensee, String auditor, String administrator) {
+}

backend/src/main/java/ca/bc/gov/nrs/ilcr/homecontent/dto/HomeContentSaveResponse.java

@@ -0,0 +1,14 @@
+package ca.bc.gov.nrs.ilcr.homecontent.dto;
+
+import java.util.List;
+
+/**
+ * The response to a Content Editing save (Story 24.2 / UC-CNT-001): the verbatim success message
+ * (AD-8) and the reloaded messages so the editors refresh in a single round-trip.
+ *
+ * @param messageKey the {@code messages.properties} key of the success message
+ * @param message the verbatim success text (SUC-001)
+ * @param entries the three role messages after the save
+ */
+public record HomeContentSaveResponse(String messageKey, String message, List<HomeContentEntry> entries) {
+}

backend/src/main/java/ca/bc/gov/nrs/ilcr/security/Action.java

@@ -20,5 +20,11 @@ public enum Action {
    * Open a new reporting year (UC-RY-001) — the Administration ▸ Open Reporting Year surface. ADMIN-only,
    * like {@link #MAINTAIN_CODE_TABLES}: a SUBMITTER hitting the open-year API is denied 403.
    */
-  OPEN_REPORTING_YEAR
+  OPEN_REPORTING_YEAR,
+  /**
+   * Edit the role-keyed Home welcome messages (Story 24.2, UC-CNT-001) — the Administration ▸ Home
+   * Content surface. ADMIN-only: a SUBMITTER hitting the save API is denied 403. The read for Home
+   * rendering is a separate, authenticated (non-admin) endpoint.
+   */
+  EDIT_HOME_CONTENT
 }