support_backend/specs/012-admin-list-views/spec.md

# Feature Specification: Admin List Views

**Feature Branch**: `012-admin-list-views`

**Created**: 2026-09-07

**Status**: Draft

**Input**: User description: "Add missing read-only list endpoints supporthub-web's admin
monitoring and catalog screens need: SLA runs across tickets, recent escalation events across
tickets, and products with their integration status, none of which exist as a single query
today."

## User Scenarios & Testing *(mandatory)*

### User Story 1 - An agent or admin sees SLA status across every ticket at a glance (Priority: P1)

Rather than checking one ticket's SLA state at a time, an agent or admin retrieves a list of
every ticket's current SLA run, filterable by status (running/paused/warning/breached), each
entry carrying enough to identify and link to its ticket.

**Why this priority**: This is the entire reason this feature exists — supporthub-web's own
001-agent-admin-ui, User Story 6, has no data source for its SLA monitor view without it, and
no endpoint in the SLA module answers "every ticket's SLA state," only one ticket's own.

**Independent Test**: With SLA runs in different states across several tickets, call this
endpoint unfiltered and confirm every run appears; call it filtered by `status=breached` and
confirm only breached runs appear.

**Acceptance Scenarios**:

1. **Given** tickets with SLA runs in running, paused, and breached states, **When** the
   endpoint is called with no filter, **Then** every run is returned, each including its
   ticket's id and code, status, and due/breached timestamps.
2. **Given** the same tickets, **When** the endpoint is called with `status=breached`, **Then**
   only the breached runs are returned.

---

### User Story 2 - An agent or admin sees recent escalation events across every ticket (Priority: P1)

An agent or admin retrieves a list of recent escalation events across all tickets — each
showing the triggering reason, the rule that fired it (if automatic) or the actor who triggered
it (if manual), and the resulting target hierarchy node.

**Why this priority**: The same 001-agent-admin-ui User Story 6 has no data source for its
escalation matrix view without it — today the only way to see an escalation event at all is
`EscalationEventRepository.findAllForTicket`, which requires already knowing which ticket to
ask about.

**Independent Test**: With escalation events (both automatic and manual) recorded across
several tickets, call this endpoint and confirm every event appears, most recent first, each
identifying its ticket, reason, rule-or-actor, and target node.

**Acceptance Scenarios**:

1. **Given** three tickets each with one escalation event, **When** the endpoint is called,
   **Then** all three appear, ordered most-recent-first, each including its ticket id/code,
   reason, `ruleId` (or null for manual), `triggeredBy`, and `toNodeId`.

---

### User Story 3 - An admin views the product catalog with integration status (Priority: P2)

An admin retrieves the product catalog with each product's integration status
(active/suspended) visible directly in the list, rather than needing a second lookup per
product.

**Why this priority**: Lower than User Stories 1-2 (matches 001-agent-admin-ui's own User Story
7 being P3) — the product catalog changes far less often than SLA/escalation state, but its own
consuming frontend story still has no single query to build a list screen against: the existing
public `GET /products` doesn't include `ProductIntegration`, and integration status is only
otherwise reachable per-integration-id, not per-product.

**Independent Test**: With two products, one with an active integration and one with a
suspended integration, call this endpoint and confirm each product's own integration status is
present without a further request.

**Acceptance Scenarios**:

1. **Given** a product with an active integration and one with a suspended integration, **When**
   an admin calls this endpoint, **Then** both appear with their correct integration status;
   a product with no integration at all shows a clearly-absent (not misleadingly "active")
   status.

---

### Edge Cases

- What happens to a ticket whose SLA run was already marked `completed` (ticket resolved)? It
  still appears in the unfiltered SLA-run list (this is a monitoring view of everything that
  exists, not just "currently at risk") but is excluded by a `status=breached`/`running`/etc.
  filter unless it matches.
- What happens for a ticket with no SLA run at all (no matching policy, or the run hasn't been
  created yet)? It simply doesn't appear in this list — this endpoint lists existing `SLARun`
  rows, it does not synthesize one for every ticket.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: The system MUST provide an endpoint listing every `SLARun`, each including its
  owning ticket's id and code, optionally filtered by `status`.
- **FR-002**: The system MUST provide an endpoint listing recent `EscalationEvent` rows across
  all tickets, most-recent-first, each including its owning ticket's id and code.
- **FR-003**: The system MUST provide an endpoint listing the product catalog with each
  product's integration status included, distinguishing "has an active integration," "has a
  suspended integration," and "has no integration at all."
- **FR-004**: All three endpoints are read-only (no new write capability) and reuse existing
  `SLARun`/`EscalationEvent`/`Product`/`ProductIntegration` data — no new persisted entity.

### Key Entities

- **SLA Run List Item**: An `SLARun` projected with its ticket's `id`/`code` alongside its own
  existing fields.
- **Escalation Event List Item**: An `EscalationEvent` projected with its ticket's `id`/`code`
  alongside its own existing fields.
- **Product Catalog List Item**: A `Product` projected with its integration's `status`, or an
  explicit absence marker if it has none.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: Every ticket's SLA state is retrievable in a single request, filterable by status,
  with zero additional per-ticket requests needed.
- **SC-002**: Recent escalation events across every ticket are retrievable in a single request.
- **SC-003**: The product catalog with integration status is retrievable in a single request,
  with 0% of products showing a misleading status when they have no integration at all.

## Assumptions

- **No pagination on the SLA-run or product-catalog lists** — matches 011-agent-ticket-queue's
  own precedent (bounded, realistic data volumes for this stage); the escalation-event list
  DOES cap at a default/maximum `limit` (most-recent-first), since that list only ever grows
  and has no other natural bound.
- **These are read-only monitoring/catalog views, not a general search/filter API** — the SLA
  list's only filter is `status`; no additional filters (date range, product, priority) are
  added speculatively beyond what 001-agent-admin-ui's own User Story 6 spec asks for.
- **Auth**: SLA-run and escalation-event lists are agent-usable (`fastify.authenticate` only,
  matching the existing single-ticket `GET /tickets/:id/sla-run`'s own agent-facing nature and
  001-agent-admin-ui's "agents and admins" wording for User Story 6); the product-catalog list
  is admin-only (`requireRole('ADMIN')`), matching every other admin-configuration read in this
  codebase.