feat(tickets): deliver canonical operational lifecycle

src/govoplan_tickets/backend/schemas.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TicketCreateRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    record: dict[str, Any]
+    idempotency_key: str = Field(min_length=1, max_length=255)
+
+
+class TicketMutationRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    expected_revision: int = Field(ge=1)
+    recorded_at: datetime
+    change_reason: str = Field(min_length=1, max_length=1_000)
+    idempotency_key: str = Field(min_length=1, max_length=255)
+
+
+class TicketTriageRequest(TicketMutationRequest):
+    changes: dict[str, Any]
+
+
+class TicketAssignmentRequest(TicketMutationRequest):
+    assignee: dict[str, Any] | None = None
+
+
+class TicketResolutionRequest(TicketMutationRequest):
+    target_status: str = Field(min_length=1, max_length=40)
+    resolution_summary: str | None = Field(default=None, max_length=20_000)
+
+
+class TicketParticipantsRequest(TicketMutationRequest):
+    participants: list[dict[str, Any]] = Field(max_length=100)
+
+
+class TicketLinkRequest(TicketMutationRequest):
+    link: dict[str, Any]
+
+
+class TicketCommentRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    expected_revision: int = Field(ge=1)
+    comment_id: str = Field(min_length=1, max_length=255)
+    body: str = Field(min_length=1, max_length=20_000)
+    visibility: str = Field(default="internal", max_length=40)
+    recorded_at: datetime
+    idempotency_key: str = Field(min_length=1, max_length=255)
+
+
+class TicketEscalationRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    expected_revision: int = Field(ge=1)
+    case_type_key: str = Field(min_length=1, max_length=120)
+    occurred_at: datetime
+    handoff_note: str | None = Field(default=None, max_length=10_000)
+    idempotency_key: str = Field(min_length=1, max_length=255)
+
+
+class TicketDeleteRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    expected_revision: int = Field(ge=1)
+    occurred_at: datetime
+    reason: str = Field(min_length=1, max_length=1_000)
+    idempotency_key: str = Field(min_length=1, max_length=255)
+
+
+class TicketListResponse(BaseModel):
+    tickets: list[dict[str, Any]]
+    total: int
+    offset: int
+    limit: int
+
+
+class TicketCommentsResponse(BaseModel):
+    comments: list[dict[str, Any]]
+
+
+class TicketHistoryResponse(BaseModel):
+    history: list[dict[str, Any]]
+
+
+class TicketCommentMutationResponse(BaseModel):
+    ticket: dict[str, Any]
+    comment: dict[str, Any]
+
+
+class TicketEscalationResponse(BaseModel):
+    ticket: dict[str, Any]
+    escalation: dict[str, Any]
+
+
+__all__ = [
+    "TicketAssignmentRequest",
+    "TicketCommentMutationResponse",
+    "TicketCommentRequest",
+    "TicketCommentsResponse",
+    "TicketCreateRequest",
+    "TicketDeleteRequest",
+    "TicketEscalationRequest",
+    "TicketEscalationResponse",
+    "TicketHistoryResponse",
+    "TicketLinkRequest",
+    "TicketListResponse",
+    "TicketParticipantsRequest",
+    "TicketResolutionRequest",
+    "TicketTriageRequest",
+]