support_backend/specs/008-sla-escalation/data-model.md

Data Model: SLA and Escalation

Field shapes below match docs/06-database-schema.md "Domain: SLA" / "Domain: Escalation" exactly, with two additive refinements called out explicitly (both purely additive — nothing in doc 06's shape is removed or narrowed).

SLAPolicy

Field	Type	Notes
id	String @id @default(cuid())
name	String
productId	String?	wildcard when null — FK to Product.id
categoryId	String?	wildcard when null — FK to Category.id
problemTypeId	String?	wildcard when null — free-text reference, no ProblemType table exists in this codebase (problem taxonomy lives on Problem directly, per 004/005); stored and matched as opaque text
priority	String?	wildcard when null — free-text, matches Ticket.priority
firstResponseMinutes	Int	required — every policy must define a first-response target
investigationMinutes	Int?	stored per doc 06; not read by any calculation in this feature (spec.md Assumptions)
resolutionMinutes	Int	required
customerResponseMinutes	Int?	stored per doc 06; not read by any calculation in this feature (spec.md Assumptions)
businessCalendarId	String?	FK to BusinessCalendar.id; null means "24/7, no exclusions" (an explicit policy choice, not a missing-calendar error)
active	Boolean @default(true)	inactive policies are excluded from resolution
createdAt / updatedAt	DateTime	updatedAt used as the resolution tie-break (research.md)

Validation (Zod, at the schema layer): firstResponseMinutes > 0, resolutionMinutes > 0, investigationMinutes/customerResponseMinutes positive when present; productId/categoryId/ businessCalendarId must reference an existing row when provided (repository-level existence check, same convention as every prior feature's FK-shaped free-form input).

Resolution (findApplicablePolicy(ticket)): among active policies where each set scope field equals the ticket's corresponding value and each unset field is a wildcard, return the one with the fewest wildcards; tie-break by latest updatedAt. No match → no SLARun is created (FR-005).

SLARun

Field	Type	Notes
id	String @id @default(cuid())
ticketId	String @unique	one run per ticket — no reopen-cycle support (spec.md Assumptions)
policyId	String	FK to SLAPolicy.id, the policy resolved at creation time
firstResponseDueAt	DateTime?	computed via the calendar walk from assignedAt; null when the policy has no firstResponseMinutes... (always present per policy validation, so effectively always set)
resolutionDueAt	DateTime?	computed the same way from resolutionMinutes
status	String	running | paused | warning | breached | completed — matches doc 06 exactly
pausedAt	DateTime?	set when status transitions to paused; cleared on resume
resumedAt	DateTime?	last resume timestamp, informational (audit convenience, mirrors AssignmentHistory's always-append style)
breachedAt	DateTime?	set once, the first time resolutionDueAt is detected passed while running
completedAt	DateTime?	set when the ticket reaches a resolved/closed status; a completed run is never later marked breached (FR-011)
firstResponseBreachedAt	DateTime?	additive refinement, not in doc 06's literal listing — records the first-response breach separately from status/breachedAt, which this feature reserves for the resolution timer; doubles as the idempotency guard for the breach-detection job (research.md)

Status transitions (enforced in the service layer, not a DB constraint — same convention as Ticket.status's 12-state machine in 003): running → paused (on ticket entering WAITING_FOR_CUSTOMER) → running (on leaving it, due dates shifted forward by the pause duration) → breached (resolution due date passed while running) → completed (ticket resolved/ closed, from any of running/paused/breached). warning is reserved by doc 06's enum for a future near-breach signal; no code path in this feature sets it (documented, not implemented — same discipline as the 8 inert EscalationRule.triggerType values).

BusinessCalendar

Field	Type	Notes
id	String @id @default(cuid())
name	String
timezone	String	IANA zone name (e.g. "America/New_York"), validated against Intl.supportedValuesOf('timeZone') at the schema layer
workingHours	Json	shape: { mon?: {start: "HH:mm", end: "HH:mm"}, tue?: ..., wed?: ..., thu?: ..., fri?: ..., sat?: ..., sun?: ... } — a missing key means zero working hours that weekday (research.md)
holidays	Holiday[]

Holiday

Field	Type	Notes
id	String @id @default(cuid())
calendarId	String	FK to BusinessCalendar.id
date	DateTime	compared by calendar date only (year/month/day in the calendar's own timezone), not by exact instant
description	String?

EscalationPolicy

Field	Type	Notes
id	String @id @default(cuid())
name	String
productId	String?	wildcard (global) when null
active	Boolean @default(true)
rules	EscalationRule[]

EscalationRule

Field	Type	Notes
id	String @id @default(cuid())
policyId	String	FK to EscalationPolicy.id
triggerType	String	one of doc 05 §6's 10 values; schema accepts all 10, only resolution_breach/first_response_breach are ever evaluated (research.md)
condition	Json	stored, not evaluated, by this feature (research.md)
targetNodeId	String	FK to HierarchyNode.id, validated to exist at creation time (FR-017's rejection rule applies identically here)
notify	Json	who/how to notify — stored and returned only; no delivery mechanism exists (spec.md Assumptions, platform/notifications untouched)
active	Boolean @default(true)

EscalationEvent

Field	Type	Notes
id	String @id @default(cuid())
ticketId	String	FK to Ticket.id
ruleId	String?	null for a manual escalation or a breach with no matching rule
fromNodeId	String?	the node the ticket was assigned to immediately before this event, if any
toNodeId	String?	the rule's targetNodeId (or the manually-specified node); null when no rule matched
reason	String	free text — for a rule firing, a generated description (e.g. "resolution SLA breached"); for manual escalation, the caller-supplied reason
triggeredBy	String	system | <agentId> | <adminId> — never a bare "customer" literal in this feature's own write paths (doc 06 lists it as a valid value for a future customer-initiated trigger type, not one this feature fires)
createdAt	DateTime @default(now())

Relations added to existing models

• Ticket.slaRun SLARun? (inverse of SLARun.ticketId @unique)
• Ticket.escalationEvents EscalationEvent[]
• Product.slaPolicies SLAPolicy[], Product.escalationPolicies EscalationPolicy[]
• Category.slaPolicies SLAPolicy[]
• HierarchyNode.escalationRules EscalationRule[] (inverse of targetNodeId)

Out of scope for this data model (per spec.md Assumptions)

• No investigationDueAt/customerResponseDueAt fields — doc 06's SLARun doesn't define them, and nothing in spec.md's acceptance scenarios exercises them; investigationMinutes/ customerResponseMinutes remain stored-but-unused on SLAPolicy, same as doc 06 itself defines.
• No FK tightening of HierarchyNode.slaPolicyId/escalationPolicyId (still free-text, per 006) — SLA policy resolution in this feature is scope-based (product/category/problemType/priority), not looked up through those two fields; they remain unvalidated free text, unchanged from 006.