# Alerts Inbox Redesign Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Collapse the Inbox / All / History alert pages into a single filterable inbox; make `read`/`ack`/`delete` global timestamp flags; add Silence-rule and Delete row/bulk actions. **Architecture:** Drop `ACKNOWLEDGED` from `AlertState` (orthogonal `acked_at` flag already exists); add `read_at` + `deleted_at` columns; drop the `alert_reads` table; rework V13 open-rule unique index predicate to `state IN ('PENDING','FIRING') AND deleted_at IS NULL`. Rewire `/read`, `/bulk-read`, `countUnread` to update `alert_instances` directly. Add `DELETE /alerts/{id}`, `POST /alerts/{id}/restore` (undo-toast backing), `POST /alerts/bulk-delete`, `POST /alerts/bulk-ack`. Rebuild `InboxPage.tsx` with a 4-filter bar; delete `AllAlertsPage` + `HistoryPage`; trim sidebar. **Tech Stack:** Java 17 / Spring Boot 3.4.3 / Flyway / PostgreSQL 16 / TypeScript / React 18 / React Router v6 / TanStack Query / `@cameleer/design-system`. **Spec:** `docs/superpowers/specs/2026-04-21-alerts-inbox-redesign-design.md` --- ## File structure **Backend (core):** - Modify: `cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertState.java` — drop `ACKNOWLEDGED` - Modify: `cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertInstance.java` — add `readAt`, `deletedAt` - Modify: `cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertInstanceRepository.java` — add `acked`/`read` filter params, `markRead`/`bulkMarkRead`/`softDelete`/`bulkSoftDelete`, `countUnread(envId, userId, groupIds, roleNames)` (replaces old single-target countUnreadBySeverityForUser) - Delete: `cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertReadRepository.java` **Backend (app):** - Create: `cameleer-server-app/src/main/resources/db/migration/V17__alerts_drop_acknowledged.sql` - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/storage/PostgresAlertInstanceRepository.java` - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/eval/AlertStateTransitions.java` — drop `ACKNOWLEDGED` case - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/controller/AlertController.java` — DELETE, bulk-delete, bulk-ack, acked/read filter params, rewire `/read` + `/bulk-read` - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/notify/InAppInboxQuery.java` — add filter params, countUnread rewire - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/dto/AlertDto.java` — add `readAt` - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/config/AlertingBeanConfig.java` — drop `alertReadRepository` bean - Delete: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/storage/PostgresAlertReadRepository.java` **UI:** - Regenerate: `ui/src/api/schema.d.ts`, `ui/src/api/openapi.json` - Modify: `ui/src/api/queries/alerts.ts` — new mutations, new filter params - Delete: `ui/src/pages/Alerts/AllAlertsPage.tsx`, `ui/src/pages/Alerts/HistoryPage.tsx` - Modify: `ui/src/router.tsx` — drop `/alerts/all`, `/alerts/history` - Modify: `ui/src/components/sidebar-utils.ts` — trim `buildAlertsTreeNodes` - Modify: `ui/src/pages/Alerts/InboxPage.tsx` — new filter bar + actions - Create: `ui/src/pages/Alerts/SilenceRuleMenu.tsx` — small duration-picker menu - Modify: `ui/src/pages/Alerts/SilencesPage.tsx` — read `?ruleId=` URL param **Tests:** - Modify: `cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/storage/PostgresAlertInstanceRepositoryIT.java` - Modify: `cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/controller/AlertControllerIT.java` - Modify: `cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/eval/AlertStateTransitionsTest.java` - Modify: `cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/AlertingFullLifecycleIT.java` - Create: `cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/storage/V17MigrationIT.java` - Create: `ui/src/pages/Alerts/InboxPage.test.tsx` **Docs/rules:** - Modify: `.claude/rules/app-classes.md`, `.claude/rules/ui.md`, `.claude/rules/core-classes.md` - Modify: `CLAUDE.md` --- ## Working rules (every task) 1. **Run migration integration tests via Testcontainers** — `mvn -pl cameleer-server-app -Dtest= test`. The suite already bootstraps Postgres via `@SpringBootTest`. 2. **Commit per task.** Commit message format: `feat(alerts): ` / `refactor(alerts): ` / `test(alerts): `. End with the Claude co-author trailer. 3. **After any backend REST change**, regenerate OpenAPI in one step: `cd ui && (curl -sS http://localhost:8081/api/v1/api-docs > src/api/openapi.json) && npx openapi-typescript src/api/openapi.json -o src/api/schema.d.ts`. This requires the backend running. 4. **Run `gitnexus_impact` before editing any symbol touched by ≥2 callers**, per project rule. Report blast radius. Run `gitnexus_detect_changes` pre-commit. 5. **Don't batch.** One task = one commit. Mark TODO items complete as you go. --- ## Task 1: V17 migration — drop ACKNOWLEDGED, add read_at + deleted_at, drop alert_reads, rework open-rule index **Files:** - Create: `cameleer-server-app/src/main/resources/db/migration/V17__alerts_drop_acknowledged.sql` - Create: `cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/storage/V17MigrationIT.java` - [ ] **Step 1: Write the migration SQL** ```sql -- V17 — Alerts: drop ACKNOWLEDGED state, add read_at/deleted_at, drop alert_reads, -- rework open-rule unique index predicate to survive ack (acked no longer "closed"). -- 1. Coerce ACKNOWLEDGED rows → FIRING (acked_at already set on these rows) UPDATE alert_instances SET state = 'FIRING' WHERE state = 'ACKNOWLEDGED'; -- 2. Swap alert_state_enum to remove ACKNOWLEDGED (Postgres can't drop enum values in place) CREATE TYPE alert_state_enum_v2 AS ENUM ('PENDING','FIRING','RESOLVED'); ALTER TABLE alert_instances ALTER COLUMN state TYPE alert_state_enum_v2 USING state::text::alert_state_enum_v2; DROP TYPE alert_state_enum; ALTER TYPE alert_state_enum_v2 RENAME TO alert_state_enum; -- 3. New orthogonal flag columns ALTER TABLE alert_instances ADD COLUMN read_at timestamptz NULL, ADD COLUMN deleted_at timestamptz NULL; CREATE INDEX alert_instances_unread_idx ON alert_instances (environment_id, read_at) WHERE read_at IS NULL AND deleted_at IS NULL; CREATE INDEX alert_instances_deleted_idx ON alert_instances (deleted_at) WHERE deleted_at IS NOT NULL; -- 4. Rework the V13/V15/V16 open-rule uniqueness index: -- - drop ACKNOWLEDGED from the predicate (ack no longer "closes") -- - add "AND deleted_at IS NULL" so a soft-deleted row frees the slot DROP INDEX IF EXISTS alert_instances_open_rule_uq; CREATE UNIQUE INDEX alert_instances_open_rule_uq ON alert_instances (rule_id, (COALESCE( context->>'_subjectFingerprint', context->'exchange'->>'id', ''))) WHERE rule_id IS NOT NULL AND state IN ('PENDING','FIRING') AND deleted_at IS NULL; -- 5. Drop the per-user reads table — read is now global on alert_instances.read_at DROP TABLE alert_reads; ``` - [ ] **Step 2: Write the failing migration IT** ```java package com.cameleer.server.app.alerting.storage; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.jdbc.core.JdbcTemplate; import org.springframework.test.context.ActiveProfiles; import static org.assertj.core.api.Assertions.assertThat; @SpringBootTest @ActiveProfiles("test") class V17MigrationIT { @Autowired JdbcTemplate jdbc; @Test void alert_state_enum_drops_acknowledged() { var values = jdbc.queryForList(""" SELECT unnest(enum_range(NULL::alert_state_enum))::text AS v """, String.class); assertThat(values).containsExactlyInAnyOrder("PENDING", "FIRING", "RESOLVED"); } @Test void read_at_and_deleted_at_columns_exist() { var cols = jdbc.queryForList(""" SELECT column_name FROM information_schema.columns WHERE table_name = 'alert_instances' AND column_name IN ('read_at','deleted_at') """, String.class); assertThat(cols).containsExactlyInAnyOrder("read_at", "deleted_at"); } @Test void alert_reads_table_is_gone() { Integer count = jdbc.queryForObject(""" SELECT COUNT(*)::int FROM information_schema.tables WHERE table_name = 'alert_reads' """, Integer.class); assertThat(count).isZero(); } @Test void open_rule_index_predicate_is_reworked() { String def = jdbc.queryForObject(""" SELECT pg_get_indexdef(indexrelid) FROM pg_index JOIN pg_class ON pg_class.oid = pg_index.indexrelid WHERE pg_class.relname = 'alert_instances_open_rule_uq' """, String.class); assertThat(def).contains("state = ANY (ARRAY['PENDING'::alert_state_enum, 'FIRING'::alert_state_enum])"); assertThat(def).contains("deleted_at IS NULL"); } } ``` - [ ] **Step 3: Run the tests — expect 4 failures** (migration not applied yet) Run: `mvn -pl cameleer-server-app -Dtest=V17MigrationIT test` Expected: 4 failures — enum still has ACKNOWLEDGED, columns don't exist, alert_reads still exists, index predicate wrong. - [ ] **Step 4: Run the full suite to verify clean up-migration** — `mvn -pl cameleer-server-app verify -DskipITs=false`. Expected: V17 test class green; many existing tests RED because they reference `ACKNOWLEDGED`. That's fine — they get fixed in subsequent tasks. - [ ] **Step 5: Commit** ```bash git add cameleer-server-app/src/main/resources/db/migration/V17__alerts_drop_acknowledged.sql \ cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/storage/V17MigrationIT.java git commit -m "feat(alerts): V17 migration — drop ACKNOWLEDGED, add read_at + deleted_at" ``` --- ## Task 2: Drop ACKNOWLEDGED from AlertState + add read_at/deleted_at to AlertInstance **Files:** - Modify: `cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertState.java` - Modify: `cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertInstance.java` - [ ] **Step 1: Update `AlertState.java`** to exactly: ```java package com.cameleer.server.core.alerting; public enum AlertState { PENDING, FIRING, RESOLVED } ``` - [ ] **Step 2: Add `readAt` + `deletedAt` to `AlertInstance`** — insert the fields after `lastNotifiedAt` (keep insertion order stable for DTOs), update compact ctor if needed, add witherr helpers `withReadAt`, `withDeletedAt`: ```java public record AlertInstance( UUID id, UUID ruleId, Map ruleSnapshot, UUID environmentId, AlertState state, AlertSeverity severity, Instant firedAt, Instant ackedAt, String ackedBy, Instant resolvedAt, Instant lastNotifiedAt, Instant readAt, // NEW — global "someone has seen this" Instant deletedAt, // NEW — soft delete boolean silenced, Double currentValue, Double threshold, Map context, String title, String message, List targetUserIds, List targetGroupIds, List targetRoleNames) { // ... existing compact ctor unchanged (list/map copies) ... public AlertInstance withReadAt(Instant i) { /* new record with readAt=i */ } public AlertInstance withDeletedAt(Instant i) { /* new record with deletedAt=i */ } // ... update every existing wither to include readAt/deletedAt in positional args ... } ``` All existing `withXxx` helpers must be updated to pass `readAt, deletedAt` positionally to the new-record construction. This is mechanical. Any call sites in the codebase that construct `AlertInstance` directly need `null, null` inserted at those positions. - [ ] **Step 3: Build the module** — `mvn -pl cameleer-server-core compile`. Fix any compile errors in callers of the constructor (seed data / tests). Expected caller: `AlertStateTransitions.newInstance` — add `null, null` for readAt/deletedAt. - [ ] **Step 4: Run the core unit tests** — `mvn -pl cameleer-server-core test`. Expected: any direct `AlertState.ACKNOWLEDGED` references in `AlertScopeTest` → drop them or replace with `FIRING`. - [ ] **Step 5: Commit** ```bash git add cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertState.java \ cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertInstance.java \ cameleer-server-core/src/test/java/com/cameleer/server/core/alerting/AlertScopeTest.java \ cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/eval/AlertStateTransitions.java git commit -m "refactor(alerts): drop ACKNOWLEDGED from AlertState, add readAt/deletedAt to AlertInstance" ``` --- ## Task 3: AlertStateTransitions — drop ACKNOWLEDGED branch **Files:** - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/eval/AlertStateTransitions.java` - Modify: `cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/eval/AlertStateTransitionsTest.java` - [ ] **Step 1: Write the failing test case** — append to `AlertStateTransitionsTest.java`: ```java @Test void firing_with_ack_stays_firing_on_next_firing_tick() { // Pre-redesign this was the "ACKNOWLEDGED stays ACK" case. Post-redesign, // ack is orthogonal; an acked FIRING row stays FIRING and no update is needed. AlertInstance current = newInstance(AlertState.FIRING) .withAck("alice", Instant.parse("2026-04-21T10:00:00Z")); Optional out = AlertStateTransitions.apply( current, new EvalResult.Firing(1.0, null, Map.of()), rule, NOW); assertThat(out).isEmpty(); } ``` (Use existing `newInstance` helper and `rule` field in the test class.) - [ ] **Step 2: Run test — expect FAIL with `NoSuchFieldError: ACKNOWLEDGED`** (switch-case references removed enum value). Run: `mvn -pl cameleer-server-app -Dtest=AlertStateTransitionsTest test`. - [ ] **Step 3: Update `AlertStateTransitions.onFiring`** — replace the switch: ```java return switch (current.state()) { case PENDING -> { Instant promoteAt = current.firedAt().plusSeconds(rule.forDurationSeconds()); if (!promoteAt.isAfter(now)) { yield Optional.of(current .withState(AlertState.FIRING) .withFiredAt(now)); } yield Optional.empty(); } case FIRING -> Optional.empty(); case RESOLVED -> Optional.empty(); }; ``` Also update `onClear` comment to remove the `/ ACKNOWLEDGED` mention. - [ ] **Step 4: Run test — expect PASS** + any existing test in this class that asserted the ACKNOWLEDGED branch needs to be dropped or converted. The old "ack stays ack" case becomes the new "ack-with-fire stays firing (no update)" case covered above. - [ ] **Step 5: Run the full alerting test suite** — `mvn -pl cameleer-server-app -Dtest='*Alert*' test`. Many still RED — fixed in later tasks. - [ ] **Step 6: Commit** ```bash git add cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/eval/AlertStateTransitions.java \ cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/eval/AlertStateTransitionsTest.java git commit -m "refactor(alerts): state machine — acked is orthogonal, no transition on ack" ``` --- ## Task 4: AlertInstanceRepository interface — filter params + new methods, drop AlertReadRepository **Files:** - Modify: `cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertInstanceRepository.java` - Delete: `cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertReadRepository.java` - [ ] **Step 1: Rewrite `AlertInstanceRepository`** to add filter params + new methods: ```java package com.cameleer.server.core.alerting; import java.time.Instant; import java.util.List; import java.util.Map; import java.util.Optional; import java.util.UUID; public interface AlertInstanceRepository { AlertInstance save(AlertInstance instance); Optional findById(UUID id); /** Open instance for a rule: state IN ('PENDING','FIRING') AND deleted_at IS NULL. */ Optional findOpenForRule(UUID ruleId); /** Unfiltered inbox listing — convenience overload. */ default List listForInbox(UUID environmentId, List userGroupIdFilter, String userId, List userRoleNames, int limit) { return listForInbox(environmentId, userGroupIdFilter, userId, userRoleNames, null, null, null, null, limit); } /** * Inbox listing with optional filters. {@code null} or empty lists mean no filter. * {@code acked} and {@code read} are tri-state: {@code null} = no filter, * {@code TRUE} = only acked/read, {@code FALSE} = only unacked/unread. * Always excludes soft-deleted rows ({@code deleted_at IS NOT NULL}). */ List listForInbox(UUID environmentId, List userGroupIdFilter, String userId, List userRoleNames, List states, List severities, Boolean acked, Boolean read, int limit); /** * Count unread alert instances visible to the user, grouped by severity. * Visibility: targets user directly, or via one of the given groups/roles. * "Unread" = {@code read_at IS NULL AND deleted_at IS NULL}. */ Map countUnreadBySeverity(UUID environmentId, String userId, List groupIds, List roleNames); void ack(UUID id, String userId, Instant when); void resolve(UUID id, Instant when); void markSilenced(UUID id, boolean silenced); void deleteResolvedBefore(Instant cutoff); /** Set {@code read_at = when} if currently null. Idempotent. */ void markRead(UUID id, Instant when); /** Bulk variant — single UPDATE. */ void bulkMarkRead(List ids, Instant when); /** Set {@code deleted_at = when} if currently null. Idempotent. */ void softDelete(UUID id, Instant when); /** Bulk variant — single UPDATE. */ void bulkSoftDelete(List ids, Instant when); /** Clear {@code deleted_at}. Undo for soft-delete. Idempotent. */ void restore(UUID id); /** Bulk ack — single UPDATE. Each row gets {@code acked_at=when, acked_by=userId} if unacked. */ void bulkAck(List ids, String userId, Instant when); List listFiringDueForReNotify(Instant now); } ``` **Breaking changes vs prior signature:** - `listForInbox` gains `acked` and `read` params (tri-state Boolean). - `countUnreadBySeverityForUser(envId, userId)` → `countUnreadBySeverity(envId, userId, groupIds, roleNames)`. Renamed + extended scope. - New: `markRead`, `bulkMarkRead`, `softDelete`, `bulkSoftDelete`, `bulkAck`. - [ ] **Step 2: Delete `AlertReadRepository.java`** — `rm cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertReadRepository.java`. Read/ack/delete all live on `AlertInstanceRepository` now. - [ ] **Step 3: Compile — expect caller breakage** — `mvn -pl cameleer-server-core compile`. Then `mvn -pl cameleer-server-app compile` will surface every broken call site. Known breakages (fixed in later tasks, do **not** patch them here): - `PostgresAlertInstanceRepository` (Task 5) - `AlertController` (Task 6) - `InAppInboxQuery` (Task 6) - `AlertingBeanConfig` (Task 5) - `PostgresAlertReadRepository` (Task 5) - [ ] **Step 4: Commit** ```bash git add cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertInstanceRepository.java git rm cameleer-server-core/src/main/java/com/cameleer/server/core/alerting/AlertReadRepository.java git commit -m "feat(alerts): core repo — filter params + markRead/softDelete/bulkAck; drop AlertReadRepository" ``` --- ## Task 5: PostgresAlertInstanceRepository — save/rowMapper, new methods, listForInbox filters, countUnread **Files:** - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/storage/PostgresAlertInstanceRepository.java` - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/config/AlertingBeanConfig.java` - Delete: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/storage/PostgresAlertReadRepository.java` - Modify: `cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/storage/PostgresAlertInstanceRepositoryIT.java` - [ ] **Step 1: Update `save` SQL** — add `read_at`, `deleted_at` to INSERT column list, values list, `ON CONFLICT DO UPDATE` list. Add `Timestamp.from(i.readAt())`, `Timestamp.from(i.deletedAt())` to the `jdbc.update(...)` args (via the existing `ts()` helper that null-safes). Follow the same pattern as `ackedAt`. - [ ] **Step 2: Update `findOpenForRule` predicate**: ```java var list = jdbc.query(""" SELECT * FROM alert_instances WHERE rule_id = ? AND state IN ('PENDING','FIRING') AND deleted_at IS NULL LIMIT 1 """, rowMapper(), ruleId); ``` - [ ] **Step 3: Update `ack` — no state change anymore**: ```java @Override public void ack(UUID id, String userId, Instant when) { jdbc.update(""" UPDATE alert_instances SET acked_at = ?, acked_by = ? WHERE id = ? AND acked_at IS NULL AND deleted_at IS NULL """, Timestamp.from(when), userId, id); } ``` - [ ] **Step 4: Implement `listForInbox` with tri-state filters** — add to existing dynamic SQL: ```java // after severity filter block: if (acked != null) { sql.append(acked ? " AND acked_at IS NOT NULL" : " AND acked_at IS NULL"); } if (read != null) { sql.append(read ? " AND read_at IS NOT NULL" : " AND read_at IS NULL"); } sql.append(" AND deleted_at IS NULL"); sql.append(" ORDER BY fired_at DESC LIMIT ?"); ``` Signature matches the interface (`Boolean acked`, `Boolean read`). - [ ] **Step 5: Rewrite `countUnreadBySeverity`** — removes the `alert_reads` join: ```java @Override public Map countUnreadBySeverity(UUID environmentId, String userId, List groupIds, List roleNames) { Array groupArray = toUuidArrayFromStrings(groupIds); Array roleArray = toTextArray(roleNames); String sql = """ SELECT severity::text AS severity, COUNT(*) AS cnt FROM alert_instances WHERE environment_id = ? AND read_at IS NULL AND deleted_at IS NULL AND ( ? = ANY(target_user_ids) OR target_group_ids && ? OR target_role_names && ? ) GROUP BY severity """; EnumMap counts = new EnumMap<>(AlertSeverity.class); for (AlertSeverity s : AlertSeverity.values()) counts.put(s, 0L); jdbc.query(sql, rs -> counts.put( AlertSeverity.valueOf(rs.getString("severity")), rs.getLong("cnt") ), environmentId, userId, groupArray, roleArray); return counts; } ``` - [ ] **Step 6: Implement new mutation methods**: ```java @Override public void markRead(UUID id, Instant when) { jdbc.update("UPDATE alert_instances SET read_at = ? WHERE id = ? AND read_at IS NULL", Timestamp.from(when), id); } @Override public void bulkMarkRead(List ids, Instant when) { if (ids == null || ids.isEmpty()) return; Array idArray = jdbc.execute((ConnectionCallback) c -> c.createArrayOf("uuid", ids.toArray())); jdbc.update(""" UPDATE alert_instances SET read_at = ? WHERE id = ANY(?) AND read_at IS NULL """, Timestamp.from(when), idArray); } @Override public void softDelete(UUID id, Instant when) { jdbc.update("UPDATE alert_instances SET deleted_at = ? WHERE id = ? AND deleted_at IS NULL", Timestamp.from(when), id); } @Override public void bulkSoftDelete(List ids, Instant when) { if (ids == null || ids.isEmpty()) return; Array idArray = jdbc.execute((ConnectionCallback) c -> c.createArrayOf("uuid", ids.toArray())); jdbc.update(""" UPDATE alert_instances SET deleted_at = ? WHERE id = ANY(?) AND deleted_at IS NULL """, Timestamp.from(when), idArray); } @Override public void restore(UUID id) { jdbc.update("UPDATE alert_instances SET deleted_at = NULL WHERE id = ?", id); } @Override public void bulkAck(List ids, String userId, Instant when) { if (ids == null || ids.isEmpty()) return; Array idArray = jdbc.execute((ConnectionCallback) c -> c.createArrayOf("uuid", ids.toArray())); jdbc.update(""" UPDATE alert_instances SET acked_at = ?, acked_by = ? WHERE id = ANY(?) AND acked_at IS NULL AND deleted_at IS NULL """, Timestamp.from(when), userId, idArray); } ``` - [ ] **Step 7: Update `rowMapper`** — read `read_at` + `deleted_at`: ```java Timestamp readAt = rs.getTimestamp("read_at"); Timestamp deletedAt = rs.getTimestamp("deleted_at"); // ... and pass: readAt == null ? null : readAt.toInstant(), deletedAt == null ? null : deletedAt.toInstant(), ``` Insert at the position matching the record's field order (after `lastNotifiedAt`, before `silenced`). - [ ] **Step 8: Delete `PostgresAlertReadRepository.java`** + remove its bean from `AlertingBeanConfig`: ```bash git rm cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/storage/PostgresAlertReadRepository.java ``` In `AlertingBeanConfig.java` remove: ```java @Bean public AlertReadRepository alertReadRepository(JdbcTemplate jdbc) { ... } ``` Remove the `AlertReadRepository` import too. - [ ] **Step 9: Update `PostgresAlertInstanceRepositoryIT`** — add tests: ```java @Test void markRead_is_idempotent_and_sets_read_at() { var inst = insertFreshFiring(); repo.markRead(inst.id(), Instant.parse("2026-04-21T10:00:00Z")); repo.markRead(inst.id(), Instant.parse("2026-04-21T11:00:00Z")); // idempotent — no-op var loaded = repo.findById(inst.id()).orElseThrow(); assertThat(loaded.readAt()).isEqualTo(Instant.parse("2026-04-21T10:00:00Z")); } @Test void softDelete_excludes_from_listForInbox() { var inst = insertFreshFiring(); repo.softDelete(inst.id(), Instant.parse("2026-04-21T10:00:00Z")); var rows = repo.listForInbox(ENV_ID, List.of(), USER_ID, List.of(), null, null, null, null, 100); assertThat(rows).extracting(AlertInstance::id).doesNotContain(inst.id()); } @Test void findOpenForRule_returns_acked_firing() { var inst = insertFreshFiring(); repo.ack(inst.id(), USER_ID, Instant.parse("2026-04-21T10:00:00Z")); var open = repo.findOpenForRule(inst.ruleId()); assertThat(open).isPresent(); // ack no longer closes the open slot } @Test void findOpenForRule_skips_soft_deleted() { var inst = insertFreshFiring(); repo.softDelete(inst.id(), Instant.now()); assertThat(repo.findOpenForRule(inst.ruleId())).isEmpty(); } @Test void bulk_ack_only_touches_unacked_rows() { var a = insertFreshFiring(); var b = insertFreshFiring(); repo.ack(a.id(), "alice", Instant.parse("2026-04-21T09:00:00Z")); repo.bulkAck(List.of(a.id(), b.id()), "bob", Instant.parse("2026-04-21T10:00:00Z")); assertThat(repo.findById(a.id()).orElseThrow().ackedBy()).isEqualTo("alice"); assertThat(repo.findById(b.id()).orElseThrow().ackedBy()).isEqualTo("bob"); } @Test void listForInbox_acked_false_hides_acked_rows() { var a = insertFreshFiring(); var b = insertFreshFiring(); repo.ack(a.id(), "alice", Instant.now()); var rows = repo.listForInbox(ENV_ID, List.of(), USER_ID, List.of(), null, null, /*acked*/ false, null, 100); assertThat(rows).extracting(AlertInstance::id).containsExactly(b.id()); } ``` (Use the test class's existing `insertFreshFiring()` helper or add a small factory. `ENV_ID` / `USER_ID` are existing fixture constants.) Also update any existing test asserting `state == ACKNOWLEDGED` after `ack()` — instead assert `ackedAt != null && state == FIRING`. - [ ] **Step 10: Run the repo IT** — `mvn -pl cameleer-server-app -Dtest=PostgresAlertInstanceRepositoryIT test`. Expected: all green. - [ ] **Step 11: Commit** ```bash git add cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/storage/PostgresAlertInstanceRepository.java \ cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/config/AlertingBeanConfig.java \ cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/storage/PostgresAlertInstanceRepositoryIT.java git rm cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/storage/PostgresAlertReadRepository.java git commit -m "feat(alerts): Postgres repo — markRead/softDelete/bulkAck, acked/read filters, countUnread via read_at" ``` --- ## Task 6: InAppInboxQuery + AlertController — new endpoints, filter params, rewire read **Files:** - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/notify/InAppInboxQuery.java` - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/controller/AlertController.java` - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/dto/AlertDto.java` - Modify: `cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/controller/AlertControllerIT.java` - [ ] **Step 1: Update `AlertDto`** — add `readAt`: ```java public record AlertDto( UUID id, UUID ruleId, UUID environmentId, AlertState state, AlertSeverity severity, String title, String message, Instant firedAt, Instant ackedAt, String ackedBy, Instant resolvedAt, Instant readAt, // NEW boolean silenced, Double currentValue, Double threshold, Map context ) { public static AlertDto from(AlertInstance i) { return new AlertDto( i.id(), i.ruleId(), i.environmentId(), i.state(), i.severity(), i.title(), i.message(), i.firedAt(), i.ackedAt(), i.ackedBy(), i.resolvedAt(), i.readAt(), i.silenced(), i.currentValue(), i.threshold(), i.context()); } } ``` `deletedAt` is intentionally absent — soft-deleted rows never reach the wire. - [ ] **Step 2: Update `InAppInboxQuery`** — new filter signature, rewired countUnread: ```java public List listInbox(UUID envId, String userId, List states, List severities, Boolean acked, Boolean read, int limit) { List groupIds = resolveGroupIds(userId); List roleNames = resolveRoleNames(userId); return instanceRepo.listForInbox(envId, groupIds, userId, roleNames, states, severities, acked, read, limit); } public UnreadCountResponse countUnread(UUID envId, String userId) { Key key = new Key(envId, userId); Instant now = Instant.now(clock); Entry cached = memo.get(key); if (cached != null && now.isBefore(cached.expiresAt())) return cached.response(); List groupIds = resolveGroupIds(userId); List roleNames = resolveRoleNames(userId); Map bySeverity = instanceRepo.countUnreadBySeverity(envId, userId, groupIds, roleNames); UnreadCountResponse response = UnreadCountResponse.from(bySeverity); memo.put(key, new Entry(response, now.plusMillis(MEMO_TTL_MS))); return response; } ``` Drop the deprecated 4-arg `listInbox` overload — the controller will use the full form. - [ ] **Step 3: Update `AlertController`** — add DELETE, bulk-delete, bulk-ack, acked/read filter params, rewire read/bulk-read: ```java @GetMapping public List list( @EnvPath Environment env, @RequestParam(defaultValue = "50") int limit, @RequestParam(required = false) List state, @RequestParam(required = false) List severity, @RequestParam(required = false) Boolean acked, @RequestParam(required = false) Boolean read) { String userId = currentUserId(); int effectiveLimit = Math.min(limit, 200); return inboxQuery.listInbox(env.id(), userId, state, severity, acked, read, effectiveLimit) .stream().map(AlertDto::from).toList(); } @PostMapping("/{id}/read") public void read(@EnvPath Environment env, @PathVariable UUID id) { requireLiveInstance(id, env.id()); instanceRepo.markRead(id, Instant.now()); } @PostMapping("/bulk-read") public void bulkRead(@EnvPath Environment env, @Valid @RequestBody BulkIdsRequest req) { List filtered = inEnvIds(req.instanceIds(), env.id()); if (!filtered.isEmpty()) instanceRepo.bulkMarkRead(filtered, Instant.now()); } @PostMapping("/bulk-ack") @PreAuthorize("hasAnyRole('VIEWER','OPERATOR','ADMIN')") public void bulkAck(@EnvPath Environment env, @Valid @RequestBody BulkIdsRequest req) { List filtered = inEnvIds(req.instanceIds(), env.id()); if (!filtered.isEmpty()) instanceRepo.bulkAck(filtered, currentUserId(), Instant.now()); } @DeleteMapping("/{id}") @PreAuthorize("hasAnyRole('OPERATOR','ADMIN')") public ResponseEntity delete(@EnvPath Environment env, @PathVariable UUID id) { requireLiveInstance(id, env.id()); instanceRepo.softDelete(id, Instant.now()); return ResponseEntity.noContent().build(); } @PostMapping("/bulk-delete") @PreAuthorize("hasAnyRole('OPERATOR','ADMIN')") public void bulkDelete(@EnvPath Environment env, @Valid @RequestBody BulkIdsRequest req) { List filtered = inEnvIds(req.instanceIds(), env.id()); if (!filtered.isEmpty()) instanceRepo.bulkSoftDelete(filtered, Instant.now()); } @PostMapping("/{id}/restore") @PreAuthorize("hasAnyRole('OPERATOR','ADMIN')") public ResponseEntity restore(@EnvPath Environment env, @PathVariable UUID id) { // Must find the row regardless of deleted_at (requireLiveInstance would 404 on a deleted row). AlertInstance inst = instanceRepo.findById(id) .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "Alert not found")); if (!inst.environmentId().equals(env.id())) throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Alert not found in env"); instanceRepo.restore(id); return ResponseEntity.noContent().build(); } // Helpers: private AlertInstance requireLiveInstance(UUID id, UUID envId) { AlertInstance i = instanceRepo.findById(id) .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "Alert not found")); if (!i.environmentId().equals(envId) || i.deletedAt() != null) throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Alert not found in env"); return i; } private List inEnvIds(List ids, UUID envId) { return ids.stream() .filter(id -> instanceRepo.findById(id) .map(i -> i.environmentId().equals(envId) && i.deletedAt() == null) .orElse(false)) .toList(); } ``` Rename `BulkReadRequest` → `BulkIdsRequest` (the body shape `{ instanceIds: [...] }` is identical for read/ack/delete; one DTO covers all three). Or keep `BulkReadRequest` and add `BulkAckRequest` + `BulkDeleteRequest` as sealed aliases — pick **rename to `BulkIdsRequest`** for DRY. Update references accordingly. Drop the `AlertReadRepository` field + constructor param. - [ ] **Step 4: Update `AlertControllerIT`** — add cases: ```java @Test void bulkDelete_softDeletes_matching_rows_in_env_only() { /* two rows in env, one out; bulk-delete both; only in-env row is deleted */ } @Test void list_respects_read_filter() { /* three rows, two unread; ?read=false returns two */ } @Test void list_respects_acked_filter() { /* similar */ } @Test void delete_non_operator_returns_403() { /* VIEWER role → 403 */ } @Test void get_returns_404_for_soft_deleted() { /* delete then GET → 404 */ } ``` Use existing test harness (`@WebMvcTest` or full `@SpringBootTest`, whichever the current IT uses). Also fix every existing IT assertion that expects `state=ACKNOWLEDGED` — switch to `ackedAt != null`. - [ ] **Step 5: Run** — `mvn -pl cameleer-server-app -Dtest=AlertControllerIT test`. Expected: green. - [ ] **Step 6: Commit** ```bash git add cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/controller/AlertController.java \ cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/notify/InAppInboxQuery.java \ cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/dto/AlertDto.java \ cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/dto/BulkIdsRequest.java \ cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/controller/AlertControllerIT.java git rm cameleer-server-app/src/main/java/com/cameleer/server/app/alerting/dto/BulkReadRequest.java git commit -m "feat(alerts): controller — DELETE + bulk-delete/bulk-ack, acked/read filters, read via instance" ``` --- ## Task 7: Fix remaining backend tests + SecurityConfig matchers **Files:** - Modify: `cameleer-server-app/src/main/java/com/cameleer/server/app/security/SecurityConfig.java` (RBAC matchers if needed) - Modify: `cameleer-server-app/src/test/java/com/cameleer/server/app/alerting/AlertingFullLifecycleIT.java` - Modify: any other test referencing `ACKNOWLEDGED` / `AlertReadRepository` - Modify: Grep-find all: `grep -rn "ACKNOWLEDGED\|AlertReadRepository\|alert_reads" cameleer-server-app/src cameleer-server-core/src` - [ ] **Step 1: List remaining ACKNOWLEDGED references** Run: `grep -rn "ACKNOWLEDGED\|AlertReadRepository\|alert_reads" cameleer-server-app/src cameleer-server-core/src` Expected: only test + doc fixture references now. Patch each assertion from `state==ACKNOWLEDGED` → `ackedAt != null`. - [ ] **Step 2: Update `SecurityConfig` matchers** — add matchers for the new endpoints: ```java // Ack/read/bulk-read/bulk-ack — VIEWER+ (matches existing) .requestMatchers(HttpMethod.POST, "/api/v1/environments/*/alerts/*/ack", "/api/v1/environments/*/alerts/*/read", "/api/v1/environments/*/alerts/bulk-read", "/api/v1/environments/*/alerts/bulk-ack") .hasAnyRole("VIEWER","OPERATOR","ADMIN") // Delete/bulk-delete — OPERATOR+ .requestMatchers(HttpMethod.DELETE, "/api/v1/environments/*/alerts/*") .hasAnyRole("OPERATOR","ADMIN") .requestMatchers(HttpMethod.POST, "/api/v1/environments/*/alerts/bulk-delete") .hasAnyRole("OPERATOR","ADMIN") ``` Verify the existing config — the `@PreAuthorize` annotations on the controller methods cover this, but add URL matchers if the existing config relies on them (inspect before copy-paste). - [ ] **Step 3: Update `AlertingFullLifecycleIT`** — any flow that did `ack → state=ACKNOWLEDGED → resolve` now skips the state change on ack. Patch asserts. - [ ] **Step 4: Run the whole alerting suite** — `mvn -pl cameleer-server-app -Dtest='*Alert*' test`. Expected: green. - [ ] **Step 5: Full build** — `mvn clean verify`. Expected: green. - [ ] **Step 6: Commit** ```bash git add -A git commit -m "test(alerts): migrate fixtures off ACKNOWLEDGED + alert_reads" ``` --- ## Task 8: Regenerate OpenAPI schema **Files:** - Regenerate: `ui/src/api/schema.d.ts`, `ui/src/api/openapi.json` - [ ] **Step 1: Start backend** — `java -jar cameleer-server-app/target/cameleer-server-app-1.0-SNAPSHOT.jar` in a separate terminal, or via Docker per your local workflow. Wait for `:8081` to accept. - [ ] **Step 2: Regenerate schema** ```bash cd ui curl -sS http://localhost:8081/api/v1/api-docs > src/api/openapi.json npx openapi-typescript src/api/openapi.json -o src/api/schema.d.ts ``` - [ ] **Step 3: Verify new endpoints appear** — `grep -E "bulk-delete|bulk-ack|\"delete\"" src/api/schema.d.ts | head -20`. Expected: DELETE on `/alerts/{id}`, POST on bulk-delete + bulk-ack. `AlertDto` includes `readAt`. `/alerts` GET has `acked`/`read` query params. - [ ] **Step 4: Surface TS breakages** — `cd ui && npx tsc --noEmit`. Expected: errors in `alerts.ts`, `InboxPage.tsx`, `AllAlertsPage.tsx`, `HistoryPage.tsx` — all fixed in subsequent tasks. Do **not** patch here. - [ ] **Step 5: Commit** ```bash git add ui/src/api/openapi.json ui/src/api/schema.d.ts git commit -m "chore(ui): regenerate OpenAPI schema for alerts inbox redesign" ``` --- ## Task 9: UI alerts.ts — new mutations + useAlerts filter params **Files:** - Modify: `ui/src/api/queries/alerts.ts` - [ ] **Step 1: Update `AlertsFilter` + `useAlerts`** — add `acked?: boolean`, `read?: boolean`: ```ts export interface AlertsFilter { state?: AlertState | AlertState[]; severity?: AlertSeverity | AlertSeverity[]; acked?: boolean; read?: boolean; ruleId?: string; limit?: number; } // in useAlerts queryFn, after severity handling: if (filter.acked !== undefined) query.acked = filter.acked; if (filter.read !== undefined) query.read = filter.read; // queryKey must include acked/read: queryKey: ['alerts', env, 'list', fetchLimit, stateKey, severityKey, filter.acked ?? null, filter.read ?? null], ``` - [ ] **Step 2: Rewire `useBulkReadAlerts` body** — body shape is identical (`{ instanceIds }`), but fix the TS reference if the generated type renamed it to `BulkIdsRequest`. - [ ] **Step 3: Add four new mutations**: ```ts export function useBulkAckAlerts() { const env = useSelectedEnv(); const qc = useQueryClient(); return useMutation({ mutationFn: async (ids: string[]) => { if (!env) throw new Error('no env'); const { error } = await apiClient.POST( '/environments/{envSlug}/alerts/bulk-ack', { params: { path: { envSlug: env } }, body: { instanceIds: ids } } as any); if (error) throw error; }, onSuccess: () => qc.invalidateQueries({ queryKey: ['alerts', env] }), }); } export function useDeleteAlert() { const env = useSelectedEnv(); const qc = useQueryClient(); return useMutation({ mutationFn: async (id: string) => { if (!env) throw new Error('no env'); const { error } = await apiClient.DELETE( '/environments/{envSlug}/alerts/{id}', { params: { path: { envSlug: env, id } } } as any); if (error) throw error; }, onSuccess: () => { qc.invalidateQueries({ queryKey: ['alerts', env] }); qc.invalidateQueries({ queryKey: ['alerts', env, 'unread-count'] }); }, }); } export function useBulkDeleteAlerts() { const env = useSelectedEnv(); const qc = useQueryClient(); return useMutation({ mutationFn: async (ids: string[]) => { if (!env) throw new Error('no env'); const { error } = await apiClient.POST( '/environments/{envSlug}/alerts/bulk-delete', { params: { path: { envSlug: env } }, body: { instanceIds: ids } } as any); if (error) throw error; }, onSuccess: () => { qc.invalidateQueries({ queryKey: ['alerts', env] }); qc.invalidateQueries({ queryKey: ['alerts', env, 'unread-count'] }); }, }); } export function useRestoreAlert() { const env = useSelectedEnv(); const qc = useQueryClient(); return useMutation({ mutationFn: async (id: string) => { if (!env) throw new Error('no env'); const { error } = await apiClient.POST( '/environments/{envSlug}/alerts/{id}/restore', { params: { path: { envSlug: env, id } } } as any); if (error) throw error; }, onSuccess: () => { qc.invalidateQueries({ queryKey: ['alerts', env] }); qc.invalidateQueries({ queryKey: ['alerts', env, 'unread-count'] }); }, }); } ``` - [ ] **Step 4: `npx tsc --noEmit`** — expected: only `AllAlertsPage.tsx`, `HistoryPage.tsx`, `InboxPage.tsx` errors remain. Those pages are rewritten/deleted in the next tasks. - [ ] **Step 5: Commit** ```bash git add ui/src/api/queries/alerts.ts git commit -m "feat(ui/alerts): hooks for bulk-ack, delete, bulk-delete; acked/read filter params" ``` --- ## Task 10: Remove AllAlertsPage, HistoryPage, router routes, sidebar trim **Files:** - Delete: `ui/src/pages/Alerts/AllAlertsPage.tsx` - Delete: `ui/src/pages/Alerts/HistoryPage.tsx` - Modify: `ui/src/router.tsx` - Modify: `ui/src/components/sidebar-utils.ts` - [ ] **Step 1: Delete the two pages** ```bash git rm ui/src/pages/Alerts/AllAlertsPage.tsx ui/src/pages/Alerts/HistoryPage.tsx ``` - [ ] **Step 2: Trim `router.tsx`** — drop lines 27, 28 (lazy imports) and the two route entries at lines 87, 88 (`/alerts/all`, `/alerts/history`). Keep the `/alerts` → `/alerts/inbox` redirect on line 85 (sidebar click lands here). - [ ] **Step 3: Trim `buildAlertsTreeNodes`** in `ui/src/components/sidebar-utils.ts`: ```ts export function buildAlertsTreeNodes(): SidebarTreeNode[] { const icon = (el: ReactNode) => el; return [ { id: 'alerts-inbox', label: 'Inbox', path: '/alerts/inbox', icon: icon(createElement(Inbox, { size: 14 })) }, { id: 'alerts-rules', label: 'Rules', path: '/alerts/rules', icon: icon(createElement(AlertTriangle, { size: 14 })) }, { id: 'alerts-silences', label: 'Silences', path: '/alerts/silences', icon: icon(createElement(BellOff, { size: 14 })) }, ]; } ``` Remove `List`, `ScrollText` from the `lucide-react` import (if no other user). - [ ] **Step 4: Check CMD-K** — `grep -n "alerts/all\|alerts/history" ui/src`. Expected: no hits. `buildAlertSearchData` in `LayoutShell.tsx` deep-links to `/alerts/inbox/{id}` regardless. - [ ] **Step 5: Run typecheck** — `cd ui && npx tsc --noEmit`. Expected: only `InboxPage.tsx` errors left (next task). - [ ] **Step 6: Commit** ```bash git add ui/src/router.tsx ui/src/components/sidebar-utils.ts git rm ui/src/pages/Alerts/AllAlertsPage.tsx ui/src/pages/Alerts/HistoryPage.tsx git commit -m "refactor(ui/alerts): single inbox — remove AllAlerts + History pages, trim sidebar" ``` --- ## Task 11: Create Silence-rule quick menu component **Files:** - Create: `ui/src/pages/Alerts/SilenceRuleMenu.tsx` - [ ] **Step 1: Write the component** — a small popover/menu with three preset buttons + a "Custom…" link: ```tsx import { useState, useRef } from 'react'; import { useNavigate } from 'react-router'; import { Button, Popover } from '@cameleer/design-system'; import { BellOff } from 'lucide-react'; import { useCreateSilence } from '../../api/queries/alertSilences'; import { useToast } from '@cameleer/design-system'; const PRESETS: Array<{ label: string; hours: number }> = [ { label: '1 hour', hours: 1 }, { label: '8 hours', hours: 8 }, { label: '24 hours', hours: 24 }, ]; interface Props { ruleId: string; ruleTitle?: string; onDone?: () => void; variant?: 'row' | 'bulk'; } export function SilenceRuleMenu({ ruleId, ruleTitle, onDone, variant = 'row' }: Props) { const [open, setOpen] = useState(false); const anchor = useRef(null); const create = useCreateSilence(); const navigate = useNavigate(); const { toast } = useToast(); const createWithDuration = async (hours: number) => { const now = new Date(); const endsAt = new Date(now.getTime() + hours * 3600_000); try { await create.mutateAsync({ matcher: { ruleId }, reason: `Silenced from inbox${ruleTitle ? ` (${ruleTitle})` : ''}`, startsAt: now.toISOString(), endsAt: endsAt.toISOString(), }); toast({ title: `Silenced for ${hours}h`, variant: 'success' }); setOpen(false); onDone?.(); } catch (e) { toast({ title: 'Silence failed', description: String(e), variant: 'error' }); } }; return ( <> setOpen(false)} anchor={anchor}>
{PRESETS.map((p) => ( ))}
); } ``` If the DS doesn't export `Popover`, fall back to the existing dropdown/menu pattern used elsewhere — search `ui/src` for "Popover\|DropdownMenu\|PopoverContent" and match an established pattern. - [ ] **Step 2: `npx tsc --noEmit`** — expected clean. - [ ] **Step 3: Commit** ```bash git add ui/src/pages/Alerts/SilenceRuleMenu.tsx git commit -m "feat(ui/alerts): silence-rule quick menu (1h/8h/24h/custom)" ``` --- ## Task 12: Rewrite InboxPage — filter bar, row actions, bulk toolbar **Files:** - Modify: `ui/src/pages/Alerts/InboxPage.tsx` - [ ] **Step 1: Rewrite `InboxPage.tsx`** — full replacement. Key shape: ```tsx // Filter state: const [severitySel, setSeveritySel] = useState>(new Set()); const [stateSel, setStateSel] = useState>(new Set(['FIRING'])); // default FIRING only const [hideAcked, setHideAcked] = useState(true); const [hideRead, setHideRead] = useState(true); const { data } = useAlerts({ severity: severitySel.size ? ([...severitySel] as AlertSeverity[]) : undefined, state: stateSel.size ? ([...stateSel] as AlertState[]) : undefined, acked: hideAcked ? false : undefined, read: hideRead ? false : undefined, limit: 200, }); ``` **Filter-bar JSX** (in the page header actions column): ```tsx
``` `STATE_ITEMS` omits `ACKNOWLEDGED`: ```tsx const STATE_ITEMS: ButtonGroupItem[] = [ { value: 'PENDING', label: 'Pending', color: 'var(--text-muted)' }, { value: 'FIRING', label: 'Firing', color: 'var(--error)' }, { value: 'RESOLVED', label: 'Resolved', color: 'var(--success)' }, ]; ``` **Row actions column** (replace the existing `ack` column): ```tsx { key: 'actions', header: '', width: '240px', render: (_, row) => (
{row.ackedAt == null && ( )} {row.readAt == null && ( )} {row.ruleId && ( )} {canDelete && ( )}
), }, ``` `canDelete` gated via `useAuthStore()` role check: `roles.includes('OPERATOR') || roles.includes('ADMIN')`. **Single delete with undo toast** (5s) — backed by `useRestoreAlert`: ```tsx const del = useDeleteAlert(); const restore = useRestoreAlert(); const onDeleteOne = async (id: string) => { try { await del.mutateAsync(id); toast({ title: 'Deleted', variant: 'success', duration: 5000, action: { label: 'Undo', onClick: () => restore.mutateAsync(id).then( () => toast({ title: 'Restored', variant: 'success' }), (e) => toast({ title: 'Undo failed', description: String(e), variant: 'error' }) ), }, }); } catch (e) { toast({ title: 'Delete failed', description: String(e), variant: 'error' }); } }; ``` If the DS `toast` API doesn't support an `action` slot, render a secondary `` inside the toast `description` ReactNode — check `@cameleer/design-system` toast signature before choosing. **Bulk toolbar** (the existing `filterBar` section): ```tsx {selectedIds.length > 0 ? ( <> {canDelete && ( )} ) : ( /* existing "Acknowledge all firing" + "Mark all read" */ )} ``` **Bulk-delete confirmation modal:** ```tsx setDeletePending(null)} onConfirm={async () => { if (!deletePending) return; await bulkDelete.mutateAsync(deletePending); toast({ title: `Deleted ${deletePending.length}`, variant: 'success' }); setDeletePending(null); setSelected(new Set()); }} title="Delete alerts?" message={`Delete ${deletePending?.length ?? 0} alerts? This affects all users.`} confirmText="Delete" variant="danger" /> ``` `SilenceRulesForSelection` is a helper that walks `rows` filtered to `selectedIds`, collects unique `ruleId`s, and renders a menu that creates one silence per ruleId with the chosen duration — composed from `SilenceRuleMenu` or a similar inline control. - [ ] **Step 2: Manual TS check + dev run** — `cd ui && npx tsc --noEmit`, expected green. Run `npm run dev`; navigate to `/alerts/inbox`, verify: - Filter toggles work (changing hides/reveals rows) - Ack button disappears after ack; row stays visible (hide-acked OFF) - Silence menu opens, "1 hour" creates a silence and shows success toast - Delete button (as OPERATOR) soft-deletes; row disappears; bell count updates - [ ] **Step 3: Commit** ```bash git add ui/src/pages/Alerts/InboxPage.tsx git commit -m "feat(ui/alerts): single inbox — filter bar, silence/delete row actions, bulk toolbar" ``` --- ## Task 13: SilencesPage — prefill `?ruleId=` from URL **Files:** - Modify: `ui/src/pages/Alerts/SilencesPage.tsx` - [ ] **Step 1: Add `useSearchParams` import + effect** ```tsx import { useSearchParams } from 'react-router'; // inside component: const [searchParams] = useSearchParams(); useEffect(() => { const r = searchParams.get('ruleId'); if (r) setMatcherRuleId(r); }, [searchParams]); ``` That's the entire change. `matcherRuleId` already feeds the create-silence form. - [ ] **Step 2: Manual test** — navigate to `/alerts/silences?ruleId=abc-123`; the Rule ID field is prefilled. - [ ] **Step 3: Commit** ```bash git add ui/src/pages/Alerts/SilencesPage.tsx git commit -m "feat(ui/alerts): SilencesPage — prefill Rule ID from ?ruleId= query param" ``` --- ## Task 14: UI InboxPage tests **Files:** - Create: `ui/src/pages/Alerts/InboxPage.test.tsx` - [ ] **Step 1: Write Vitest + RTL tests** with concrete bodies. Mocks hoisted at top so hook calls return deterministic data. ```tsx import { describe, it, expect, vi, beforeEach } from 'vitest'; import { render, screen, fireEvent, within } from '@testing-library/react'; import userEvent from '@testing-library/user-event'; import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { MemoryRouter } from 'react-router'; import InboxPage from './InboxPage'; import type { AlertDto } from '../../api/queries/alerts'; const alertsMock = vi.fn(); const deleteMock = vi.fn().mockResolvedValue(undefined); const bulkDelete = vi.fn().mockResolvedValue(undefined); const ackMock = vi.fn().mockResolvedValue(undefined); const markReadMock = vi.fn(); const authRolesMock = vi.fn<[], string[]>(); vi.mock('../../api/queries/alerts', () => ({ useAlerts: (...args: unknown[]) => ({ data: alertsMock(...args), isLoading: false, error: null }), useAckAlert: () => ({ mutateAsync: ackMock, isPending: false }), useMarkAlertRead: () => ({ mutate: markReadMock }), useBulkReadAlerts: () => ({ mutateAsync: vi.fn(), isPending: false }), useBulkAckAlerts: () => ({ mutateAsync: vi.fn(), isPending: false }), useDeleteAlert: () => ({ mutateAsync: deleteMock, isPending: false }), useBulkDeleteAlerts:() => ({ mutateAsync: bulkDelete, isPending: false }), useRestoreAlert: () => ({ mutateAsync: vi.fn() }), })); vi.mock('../../auth/auth-store', () => ({ useAuthStore: () => ({ roles: authRolesMock() }), })); function mount() { const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } }); return render( , ); } const ROW_FIRING: AlertDto = { id: '11111111-1111-1111-1111-111111111111', ruleId: 'rrrrrrrr-rrrr-rrrr-rrrr-rrrrrrrrrrrr', state: 'FIRING', severity: 'CRITICAL', title: 'Order pipeline down', message: 'msg', firedAt: '2026-04-21T10:00:00Z', ackedAt: null, ackedBy: null, resolvedAt: null, readAt: null, silenced: false, currentValue: null, threshold: null, environmentId: 'eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee', context: {}, }; const ROW_ACKED: AlertDto = { ...ROW_FIRING, id: '22222222-2222-2222-2222-222222222222', ackedAt: '2026-04-21T10:05:00Z', ackedBy: 'alice' }; beforeEach(() => { vi.clearAllMocks(); authRolesMock.mockReturnValue(['OPERATOR']); alertsMock.mockReturnValue([ROW_FIRING]); }); describe('InboxPage', () => { it('calls useAlerts with default filters: state=[FIRING], acked=false, read=false', () => { mount(); expect(alertsMock).toHaveBeenCalledWith(expect.objectContaining({ state: ['FIRING'], acked: false, read: false, })); }); it('unchecking "Hide acked" removes the acked filter', async () => { mount(); await userEvent.click(screen.getByRole('checkbox', { name: /hide acked/i })); const lastCall = alertsMock.mock.calls.at(-1)?.[0]; expect(lastCall).not.toHaveProperty('acked'); }); it('shows Acknowledge button only on rows where ackedAt is null', () => { alertsMock.mockReturnValue([ROW_FIRING, ROW_ACKED]); mount(); expect(screen.getAllByRole('button', { name: /acknowledge/i })).toHaveLength(1); }); it('opens bulk-delete confirmation with the correct count', async () => { alertsMock.mockReturnValue([ROW_FIRING, ROW_ACKED]); mount(); // Select both rows for (const cb of screen.getAllByRole('checkbox', { name: /^select/i })) { await userEvent.click(cb); } await userEvent.click(screen.getByRole('button', { name: /delete 2/i })); expect(screen.getByRole('dialog')).toHaveTextContent(/delete 2 alerts/i); }); it('hides Delete buttons when user lacks OPERATOR role', () => { authRolesMock.mockReturnValue(['VIEWER']); mount(); expect(screen.queryByRole('button', { name: /delete/i })).toBeNull(); }); it('clicking row Delete invokes useDeleteAlert and shows an Undo toast', async () => { mount(); await userEvent.click(within(screen.getAllByRole('row')[1]).getByRole('button', { name: /delete/i })); expect(deleteMock).toHaveBeenCalledWith(ROW_FIRING.id); expect(await screen.findByText(/deleted/i)).toBeInTheDocument(); expect(screen.getByRole('button', { name: /undo/i })).toBeInTheDocument(); }); }); ``` Adjust selectors if design-system renders checkboxes/buttons with different accessible names — prefer role+name queries over test-ids. - [ ] **Step 2: Run** — `cd ui && npx vitest run src/pages/Alerts/InboxPage.test.tsx`. Green. - [ ] **Step 3: Commit** ```bash git add ui/src/pages/Alerts/InboxPage.test.tsx git commit -m "test(ui/alerts): InboxPage filter + action coverage" ``` --- ## Task 15: Rules docs + CLAUDE.md **Files:** - Modify: `.claude/rules/app-classes.md` — AlertController endpoint table - Modify: `.claude/rules/core-classes.md` — AlertState enum, drop AlertReadRepository mention - Modify: `.claude/rules/ui.md` — Alerts section - Modify: `CLAUDE.md` — V17 migration entry - [ ] **Step 1: Update `.claude/rules/app-classes.md`** — find the `AlertController` bullet and replace: ``` - `AlertController` — `/api/v1/environments/{envSlug}/alerts`. GET list (inbox filtered by userId/groupIds/roleNames via `InAppInboxQuery`; query params: multi-value `state` (PENDING|FIRING|RESOLVED) + `severity`, tri-state `acked`/`read`; always `deleted_at IS NULL`) / GET `/unread-count` / GET `{id}` (404 if deleted) / POST `{id}/ack` (sets acked_at only, no state change) / POST `{id}/read` (sets read_at) / POST `/bulk-read` / POST `/bulk-ack` (VIEWER+) / DELETE `{id}` (OPERATOR+, soft-delete) / POST `/bulk-delete` (OPERATOR+). VIEWER+ for reads and ack/read. Inbox SQL: `? = ANY(target_user_ids) OR target_group_ids && ? OR target_role_names && ?` — requires at least one matching target. ``` Also drop any `AlertReadRepository` bean mention from the `config/` or `storage/` sub-bullet. - [ ] **Step 2: Update `.claude/rules/core-classes.md`** — `AlertState` enum: ``` - `AlertState` — enum: PENDING, FIRING, RESOLVED. Ack is orthogonal (`acked_at` on `alert_instances`), not a state. - `AlertInstanceRepository` — interface: save/findById/findOpenForRule (state IN ('PENDING','FIRING') AND deleted_at IS NULL); `listForInbox(env, groups, user, roles, states, severities, acked, read, limit)`; `countUnreadBySeverity(env, user, groups, roles)`; `ack`/`resolve`/`markSilenced`/`markRead`/`bulkMarkRead`/`softDelete`/`bulkSoftDelete`/`bulkAck`/`deleteResolvedBefore`/`listFiringDueForReNotify`. ``` Remove the `AlertReadRepository` bullet entirely. - [ ] **Step 3: Update `.claude/rules/ui.md`** — Alerts section: ``` - **Sidebar section** (`buildAlertsTreeNodes` in `ui/src/components/sidebar-utils.ts`) — Inbox, Rules, Silences. - **Routes** in `ui/src/router.tsx`: `/alerts` (redirect to inbox), `/alerts/inbox`, `/alerts/rules`, `/alerts/rules/new`, `/alerts/rules/:id`, `/alerts/silences`. - **Pages** under `ui/src/pages/Alerts/`: - `InboxPage.tsx` — single filterable inbox. Filters: severity (multi), state (PENDING/FIRING/RESOLVED, default FIRING), Hide acked (default on), Hide read (default on). Row actions: Acknowledge, Mark read, Silence rule… (quick menu: 1h/8h/24h/Custom), Delete (OPERATOR+, soft-delete). Bulk toolbar: Ack N · Mark N read · Silence rules · Delete N (confirmation modal). - `RulesListPage.tsx`, `RuleEditor/RuleEditorWizard.tsx` (unchanged). - `SilencesPage.tsx` — matcher-based create + end-early. Reads `?ruleId=` search param to prefill the Rule ID field (used by InboxPage "Silence rule… → Custom"). - `SilenceRuleMenu.tsx` (new) — popover duration picker used by row/bulk silence action. ``` - [ ] **Step 4: Update `CLAUDE.md`** — append to the V16 line: ``` - V17 — Alerts: drop ACKNOWLEDGED from AlertState (ack is now orthogonal via acked_at), add read_at + deleted_at (global, no per-user tracking), drop alert_reads table, rework V13/V15/V16 open-rule unique index predicate to `state IN ('PENDING','FIRING') AND deleted_at IS NULL`. ``` - [ ] **Step 5: Commit** ```bash git add .claude/rules/app-classes.md .claude/rules/core-classes.md .claude/rules/ui.md CLAUDE.md git commit -m "docs(alerts): rules + CLAUDE.md — inbox redesign, V17 migration" ``` --- ## Task 16: Final verification - [ ] **Step 1: `mvn clean verify`** — full backend build + ITs. Expected: green. - [ ] **Step 2: `cd ui && npm run build`** — TS strict + bundle. Expected: green. - [ ] **Step 3: `cd ui && npx vitest run`** — all UI tests. Expected: green. - [ ] **Step 4: Grep sanity** — `grep -rn "ACKNOWLEDGED\|AlertReadRepository\|alert_reads" cameleer-server-app cameleer-server-core ui/src`. Expected: only this plan file + spec. - [ ] **Step 5: Manual smoke**: - `/alerts/inbox` default view shows only unread-firing alerts - Toggle "Hide acked" OFF — acked rows appear - Ack a row — it stays visible while "Hide acked" is OFF; disappears when re-toggled ON - Click "Silence rule… → 1 hour" on a row — success toast, new silence visible on `/alerts/silences` - Bell badge decreases after marking rows as read - As VIEWER, Delete button is absent - As OPERATOR, Delete button works, soft-deletes, confirmation modal on bulk - [ ] **Step 6: Index refresh** — `npx gitnexus analyze --embeddings` to keep the code graph fresh for future sessions. --- ## Self-review notes Covered spec sections: - ✅ Data model changes → Task 1, 2 - ✅ V17 migration (enum swap + columns + drop alert_reads + rework index) → Task 1 - ✅ `AlertStateTransitions` ACKNOWLEDGED removal → Task 3 - ✅ `AlertInstanceRepository` interface changes → Task 4 - ✅ `PostgresAlertInstanceRepository` save/rowMapper/findOpenForRule/ack/listForInbox/countUnread/new mutations → Task 5 - ✅ Drop `AlertReadRepository` + impl + bean → Task 4, 5 - ✅ `AlertController` DELETE/bulk-delete/bulk-ack + acked/read filters + rewire read → Task 6 - ✅ `InAppInboxQuery` new signature + countUnread → Task 6 - ✅ `AlertDto.readAt` → Task 6 - ✅ Test-fixture migration off ACKNOWLEDGED → Task 7 - ✅ `SecurityConfig` matchers for new endpoints → Task 7 - ✅ OpenAPI regen → Task 8 - ✅ UI hooks: `useDeleteAlert`, `useBulkDeleteAlerts`, `useBulkAckAlerts`, `useAlerts` filter params → Task 9 - ✅ Delete `AllAlertsPage` + `HistoryPage` + router + sidebar → Task 10 - ✅ `SilenceRuleMenu` component → Task 11 - ✅ `InboxPage` rewrite → Task 12 - ✅ `SilencesPage` `?ruleId=` prefill → Task 13 - ✅ UI tests → Task 14 - ✅ Rules + `CLAUDE.md` → Task 15 - ✅ Final verification → Task 16