# GovOPlaN Tickets

<!-- govoplan-repository-type:start -->
**Repository type:** module (domain).
<!-- govoplan-repository-type:end -->

`govoplan-tickets` is the generic GovOPlaN work-intake and service-ticket
module. It covers public and internal reports, requests, incidents, problems,
queues, triage, routing, assignment, service-level state, and auditable
resolution.

Its runtime module ID is `tickets`.

The module now provides the first canonical vertical slice: tenant-safe ticket
persistence, guarded lifecycle actions, distinct report/triage/assignment/
resolution permissions, participants, typed links and attachment references,
comments, immutable revision history, Search contributions, soft deletion, and
optional Helpdesk-routing and Case-escalation capability boundaries.

## Initial Ownership

- ticket identity, type, priority, state, and queue
- public and internal intake profiles
- reporter/requester and affected-object references
- triage, routing, assignment, and service-level facts
- resolution evidence and escalation links

## Boundaries

Tickets are operational work items. They may be resolved entirely within a
queue or linked to a task, project, asset, facility, or formal case.

Cases are different: `govoplan-cases` owns the authoritative procedural record
for an administrative matter, including parties, evidence, decisions,
procedural deadlines, and retention. Escalating a ticket creates a stable link;
it does not rewrite the ticket as a case.

Detailed boundary notes are in
[docs/TICKETS_DOMAIN_BOUNDARY.md](docs/TICKETS_DOMAIN_BOUNDARY.md).

## Integrations

Expected optional integrations:

- cases
- projects
- wiki
- assets
- facilities
- forms_runtime
- portal
- files
- workflow
- tasks
- mail
- notifications
- search

Optional providers are discovered through Core contracts. Tickets remains
usable when they are absent: queue and service-target selection becomes manual,
Case escalation is disabled, file attachments remain typed references, and
global Search indexing is unavailable. The API and WebUI expose these
consequences rather than silently hiding actions.

## Runtime Surface

- `/api/v1/tickets` for reporting, listing, and tenant-safe discovery
- guarded triage, assignment, participant, link, comment, resolution, and
  Case-escalation actions
- immutable `/history` evidence and optimistic revision checks
- `/availability` diagnostics for optional integrations
- `/tickets` queue/detail WebUI using shared workspace and dialog primitives
- `tickets.registry` and `privacy.dsar.tickets` provider capabilities
- `tickets.tickets` Search source with backfill, authorization rechecks, and
  idempotent event changes

## Development Install

From the core checkout:

```bash
cd /mnt/DATA/git/govoplan-core
./.venv/bin/python -m pip install -e ../govoplan-tickets
```

Focused verification:

```bash
cd /mnt/DATA/git/govoplan-tickets
PYTHONPATH=src:/mnt/DATA/git/govoplan-core/src /mnt/DATA/git/govoplan/.venv/bin/python -m unittest discover -s tests
cd webui && node scripts/test-interface-pattern.mjs
```

## Gitea Workflow

Issue templates are installed under `.gitea/`, and the shared label taxonomy is
copied to `docs/gitea-labels.json` with the module label `module/tickets`.

From the core checkout, labels can be synced once a local `GITEA_TOKEN` is available:

```bash
cd /mnt/DATA/git/govoplan-core
/mnt/DATA/git/govoplan/tools/gitea/gitea-sync-labels.py --root /mnt/DATA/git/govoplan-tickets --apply
```