60 lines
2.6 KiB
Markdown
60 lines
2.6 KiB
Markdown
# Ticket Integration Capability Contracts
|
|
|
|
Core owns two narrow, optional contracts that let the Tickets module compose
|
|
with policy and formal-procedure modules without importing either one. Tickets
|
|
remains the authority for operational ticket identity, lifecycle, assignment,
|
|
comments, links, and immutable history.
|
|
|
|
## Capability Names
|
|
|
|
- `tickets.routing` optionally supplies a `TicketRoutingProvider`.
|
|
- `tickets.case_escalation` optionally supplies a
|
|
`TicketCaseEscalationProvider`.
|
|
|
|
Both contracts are version 1 and are defined in
|
|
`govoplan_core.core.tickets`. Registry helpers return `None` when a capability
|
|
is absent or has the wrong shape, so optional-module absence is normal runtime
|
|
state rather than a startup failure.
|
|
|
|
## Routing
|
|
|
|
Tickets sends a bounded, tenant-scoped `TicketRoutingRequest` containing the
|
|
ticket reference, type, priority, title, receive time, optional queue hint, and
|
|
non-secret attributes. The provider returns its identity and may return a queue
|
|
reference, timezone-aware service target, human-readable explanation, and
|
|
bounded metadata.
|
|
|
|
The provider is advisory. Tickets snapshots any returned queue and target into
|
|
its own record and history. An absent provider, a no-match plan, or an absent
|
|
queue must not prevent ticket intake; authorized staff can route manually.
|
|
Providers must not persist a second ticket lifecycle.
|
|
|
|
## Case Escalation
|
|
|
|
Tickets sends a `TicketCaseEscalationCommand` with stable tenant, ticket, and
|
|
display references, the requested Case type, actor-visible handoff note,
|
|
timezone-aware occurrence time, and an idempotency key. The provider returns a
|
|
stable Case identifier, number, bounded application-relative URL, replay flag,
|
|
and bounded metadata.
|
|
|
|
Providers must:
|
|
|
|
- recheck tenant and Case-creation authorization;
|
|
- reject an absent or inactive requested Case type;
|
|
- make identical retries resolve the same Case;
|
|
- preserve the Ticket reference in governed Case context; and
|
|
- return only an application-relative path, never an untrusted external URL.
|
|
|
|
Tickets records the result and its own escalation evidence. Cases remains the
|
|
authority for the formal procedure; Tickets remains the authority for the
|
|
operational request. Creating a Case does not merge or silently close either
|
|
lifecycle.
|
|
|
|
## Failure And Transaction Semantics
|
|
|
|
Capability calls receive the caller's active persistence session so a concrete
|
|
provider can participate in the same unit of work. Authorization and validation
|
|
errors fail the requested routing/escalation mutation explicitly. The caller
|
|
must still apply its own permission checks, tenant boundary, replay protection,
|
|
and immutable evidence rules.
|