docs(012-admin-list-views): spec for SLA-run, escalation-event, and product-catalog list endpoints
Discovered while planning supporthub-web's 001-agent-admin-ui User Stories 6-7: no endpoint lists SLA runs or escalation events across multiple tickets (only per-ticket), and no endpoint returns the product catalog with integration status joined in. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
saqib mir
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
fb9606b6aa
commit
49db40d7c1
@@ -0,0 +1,42 @@
|
||||
# Specification Quality Checklist: Admin List Views
|
||||
|
||||
**Purpose**: Validate specification completeness and quality before proceeding to planning
|
||||
**Created**: 2026-09-07
|
||||
**Feature**: [spec.md](../spec.md)
|
||||
|
||||
## Content Quality
|
||||
|
||||
- [x] No implementation details (languages, frameworks, APIs)
|
||||
- [x] Focused on user value and business needs
|
||||
- [x] Written for non-technical stakeholders
|
||||
- [x] All mandatory sections completed
|
||||
|
||||
## Requirement Completeness
|
||||
|
||||
- [x] No [NEEDS CLARIFICATION] markers remain
|
||||
- [x] Requirements are testable and unambiguous
|
||||
- [x] Success criteria are measurable
|
||||
- [x] Success criteria are technology-agnostic (no implementation details)
|
||||
- [x] All acceptance scenarios are defined
|
||||
- [x] Edge cases are identified
|
||||
- [x] Scope is clearly bounded
|
||||
- [x] Dependencies and assumptions identified
|
||||
|
||||
## Feature Readiness
|
||||
|
||||
- [x] All functional requirements have clear acceptance criteria
|
||||
- [x] User scenarios cover primary flows
|
||||
- [x] Feature meets measurable outcomes defined in Success Criteria
|
||||
- [x] No implementation details leak into specification
|
||||
|
||||
## Notes
|
||||
|
||||
- Discovered the same way 011-agent-ticket-queue was: while building supporthub-web's
|
||||
001-agent-admin-ui (User Stories 6 and 7 this time), a research pass over supporthub-api's
|
||||
actual endpoints found no cross-ticket SLA-run or escalation-event listing at all, and no
|
||||
products-with-integration-status endpoint — three separate but same-shaped gaps (an existing
|
||||
domain's data, never exposed as a list/join query), bundled into one feature rather than three
|
||||
separate ones since none is large enough to justify its own spec.
|
||||
- Deliberately narrow: read-only, no new persisted entity, no general search/filter API beyond
|
||||
the one filter (`status`) and one cap (`limit`) each list actually needs, per Assumptions.
|
||||
- All items pass; no revision iterations were needed.
|
||||
@@ -0,0 +1,144 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user