feat(tickets): add optional integration contracts and WebUI composition

2026-08-22 12:06:04 +02:00
parent 0c1358b862
commit a090e5af20
11 changed files with 868 additions and 428 deletions
@@ -18,6 +18,7 @@ operator, and roadmap pages.
 | External references and integration maturity | `EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md` | Stable external identity and cumulative connector maturity; configured source authority is defined by the meta target architecture. |
 | Institutional context and governed references | `INSTITUTIONAL_CONTEXT_CONTRACT.md` | Shared temporal, actor/representation, institution, mandate, service, party, decision, evidence, legal-basis, information-governance, presentation, and geo DTO/provider contracts. |
 | Provider-neutral record filing | `RECORDS_FILING_CONTRACT.md` | Exact source-revision identity, current source authorization, idempotent filing, capability discovery, and ownership boundary. |
+| Ticket routing and Case escalation | `TICKET_INTEGRATION_CONTRACTS.md` | Optional fail-open routing, replay-safe Case handoff, authorization, evidence, and ownership boundaries. |
 | Temporal data read context | `TEMPORAL_DATA_CONTEXT.md` | Valid-time and recorded-time titlebar selection, HTTP/cache contract, security boundary, and module-adoption rule. |
 | Cross-module information governance adoption | `INFORMATION_GOVERNANCE_ADOPTION.md` | Manifest evidence and enforcement rules for temporal browsing, purpose-aware access, retention, and institutional context. |
 | Data-subject access and erasure requests | `DATA_SUBJECT_REQUESTS.md` | Provider-owned search and mutation, explicit coverage, governed export, retained evidence, permissions, and idempotent execution. |
@@ -0,0 +1,59 @@
+# 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.