✨ add ticket management and statistics (closed beta) (#4590)

Author: MrKrisKrisu

API_CHANGELOG.md

@@ -35,6 +35,17 @@ Check back here regularly to stay ahead of removals.
 
 ---
 
+# 2026-03-15 (Ticket management – closed beta)
+
+Added new `GET|POST|PUT|DELETE /api/v1/tickets` endpoints for managing transit tickets.
+Only available to users with the `closed-beta` role.
+
+Added `ticket` field to `StatusResource`: only present when the authenticated user is the status owner and a ticket is assigned.
+
+Added `PUT /api/v1/statuses/{id}/tickets` endpoint for assigning or removing a ticket from a status (`ticketId`: UUID or `null`).
+
+---
+
 # 2026-03-14 (Freight train category)
 
 Added new transport category `freightTrain` to `HafasTravelType`. Users can now create manual trips with the freight train type.

app/Dto/TicketStatisticsDto.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Dto;
+
+/**
+ * @phpstan-type PurposeBreakdown array{reason: string|null, count: int, distance: int}
+ * @phpstan-type CategoryBreakdown array{name: string|null, count: int, distance: int}
+ * @phpstan-type OperatorBreakdown array{name: string|null, count: int, distance: int}
+ */
+readonly class TicketStatisticsDto
+{
+    /**
+     * @param  array<PurposeBreakdown>  $purposes
+     * @param  array<CategoryBreakdown>  $categories
+     * @param  array<OperatorBreakdown>  $operators
+     */
+    public function __construct(
+        public int $tripCount,
+        public int $distance,
+        public int $duration,
+        public ?string $firstUsed,
+        public ?string $lastUsed,
+        public ?float $costPerTrip,
+        public ?float $costPerKm,
+        public ?float $costPerHour,
+        public array $purposes,
+        public array $categories,
+        public array $operators,
+    ) {}
+}

app/Http/Controllers/API/v1/StatusController.php

@@ -16,6 +16,7 @@
 use App\Http\Resources\StopoverResource;
 use App\Models\Status;
 use App\Models\Stopover;
+use App\Models\Ticket;
 use App\Models\Trip;
 use Illuminate\Auth\Access\AuthorizationException;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
@@ -47,6 +48,14 @@
         new OA\Property(property: 'destinationArrivalPlanned', description: 'Destination arrival time', type: 'string', format: 'date', example: '2020-01-01 13:00:00', nullable: true),
     ],
 )]
+#[OA\Schema(
+    schema: 'StatusAssignTicketBody',
+    title: 'StatusAssignTicketBody',
+    description: 'Assign or remove a ticket from a status',
+    properties: [
+        new OA\Property(property: 'ticketId', description: 'UUID of the ticket to assign, or null to remove the assignment', type: 'string', format: 'uuid', example: '00000000-0000-0000-0000-000000000000', nullable: true),
+    ],
+)]
 #[OA\Schema(
     schema: 'Polyline',
     title: 'Polyline',
@@ -564,6 +573,7 @@ public function update(Request $request, int $statusId): JsonResponse
             if (array_key_exists('eventId', $validated)) { // don't use isset here as it would return false if eventId is null
                 $updatePayload['event_id'] = $validated['eventId'];
             }
+
             $status->update($updatePayload);
 
             if (array_key_exists('manualDeparture', $validated)) {
@@ -616,6 +626,67 @@ public function update(Request $request, int $statusId): JsonResponse
         }
     }
 
+    #[OA\Put(
+        path: '/statuses/{id}/tickets',
+        operationId: 'assignTicketToStatus',
+        description: 'Assign or remove a ticket from a status. Only the status owner can perform this action.',
+        summary: 'Assign or remove a ticket from a status',
+        security: [['passport' => ['write-statuses']], ['token' => []]],
+        requestBody: new OA\RequestBody(
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/StatusAssignTicketBody'),
+        ),
+        tags: ['Tickets'],
+        parameters: [
+            new OA\Parameter(
+                name: 'id',
+                description: 'Status-ID',
+                in: 'path',
+                schema: new OA\Schema(type: 'integer'),
+                example: 1337,
+            ),
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'successful operation',
+                content: new OA\JsonContent(
+                    properties: [new OA\Property(property: 'data', ref: '#/components/schemas/StatusResource')],
+                ),
+            ),
+            new OA\Response(response: 404, description: 'Status or ticket not found'),
+        ],
+    )]
+    public function assignTicket(Request $request, int $id): JsonResponse
+    {
+        $status = Status::find($id);
+        if ($status === null || $status->user_id !== auth()->id()) {
+            return $this->sendError('Status not found.', 404);
+        }
+
+        $validated = Validator::make($request->all(), [
+            'ticketId' => ['present', 'nullable', 'uuid'],
+        ])->validate();
+
+        if ($validated['ticketId'] !== null) {
+            $ticket = Ticket::where('id', $validated['ticketId'])
+                ->where('user_id', auth()->id())
+                ->first();
+
+            if ($ticket === null) {
+                return $this->sendError('Ticket not found.', 404);
+            }
+
+            $status->ticket_id = $ticket->id;
+        } else {
+            $status->ticket_id = null;
+        }
+
+        $status->save();
+
+        return $this->sendResponse(new StatusResource($status->fresh()));
+    }
+
     /**
      * @todo extract this to backend
      * @todo does this conform to the private checkin-shit?