Add application API and OpenAPI docs

2026-04-20 13:22:56 +02:00
parent 70d760e3a6
commit 8b25421e7c
80 changed files with 6908 additions and 1277 deletions
@@ -0,0 +1,183 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Actions\Permissions\PermissionService;
+use App\Actions\Projects\BuildProjectTicketDetailPayload;
+use App\Actions\Projects\BuildProjectTicketOptionsPayload;
+use App\Actions\Projects\BuildProjectTicketStatusTargetsPayload;
+use App\Actions\Tickets\CreateProjectTicket;
+use App\Actions\Tickets\MoveProjectTicket;
+use App\Actions\Tickets\UpdateProjectTicket;
+use App\Enums\Permission;
+use App\Http\Requests\Api\MoveProjectTicketRequest;
+use App\Http\Requests\StoreProjectTicketRequest;
+use App\Http\Requests\UpdateProjectTicketRequest;
+use App\Http\Resources\TicketResource;
+use App\Models\Project;
+use App\Models\Ticket;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+use Illuminate\Support\Arr;
+
+class ProjectTicketController extends ApiController
+{
+    public function __construct(
+        private readonly BuildProjectTicketDetailPayload $buildProjectTicketDetailPayload,
+        private readonly BuildProjectTicketOptionsPayload $buildProjectTicketOptionsPayload,
+        private readonly BuildProjectTicketStatusTargetsPayload $buildProjectTicketStatusTargetsPayload,
+        private readonly CreateProjectTicket $createProjectTicket,
+        private readonly MoveProjectTicket $moveProjectTicket,
+        private readonly PermissionService $permissionService,
+        private readonly UpdateProjectTicket $updateProjectTicket,
+    ) {}
+
+    public function index(Request $request, Project $project): AnonymousResourceCollection
+    {
+        $user = $this->authenticatedUser($request);
+
+        abort_unless(
+            $this->permissionService->allows($user, Permission::ProjectRead, $project),
+            403,
+        );
+
+        return TicketResource::collection(
+            $project->tickets()
+                ->with([
+                    'ticketPriority',
+                    'ticketStatus.allowedTargetStatuses.boardColumn',
+                    'ticketStatus.boardColumn',
+                    'ticketType',
+                ])
+                ->get(),
+        );
+    }
+
+    public function options(Request $request, Project $project): JsonResponse
+    {
+        $user = $this->authenticatedUser($request);
+
+        abort_unless(
+            $this->permissionService->allows($user, Permission::ProjectWrite, $project),
+            403,
+        );
+
+        return response()->json([
+            'data' => $this->buildProjectTicketOptionsPayload->handle(
+                $project,
+                Arr::get($request->query(), 'source') === 'board' ? 'board' : 'backlog',
+            ),
+        ]);
+    }
+
+    public function store(StoreProjectTicketRequest $request, Project $project): JsonResponse
+    {
+        $user = $this->authenticatedUser($request);
+
+        abort_unless(
+            $this->permissionService->allows($user, Permission::ProjectWrite, $project),
+            403,
+        );
+
+        $ticket = $this->createProjectTicket->handle($project, $request->validated(), $user);
+
+        return TicketResource::make($ticket->load(['ticketPriority', 'ticketStatus.boardColumn', 'ticketType']))
+            ->additional([
+                'meta' => [
+                    'message' => "{$ticket->ticket_key} was created.",
+                ],
+            ])
+            ->response()
+            ->setStatusCode(201);
+    }
+
+    public function show(Request $request, Project $project, Ticket $ticket): JsonResponse
+    {
+        $user = $this->authenticatedUser($request);
+
+        abort_unless(
+            $this->permissionService->allows($user, Permission::ProjectRead, $project),
+            403,
+        );
+
+        return response()->json([
+            'data' => $this->buildProjectTicketDetailPayload->handle($project, $ticket, $user),
+        ]);
+    }
+
+    public function update(
+        UpdateProjectTicketRequest $request,
+        Project $project,
+        Ticket $ticket,
+    ): JsonResponse {
+        $user = $this->authenticatedUser($request);
+
+        abort_unless(
+            $this->permissionService->allows($user, Permission::ProjectWrite, $project),
+            403,
+        );
+
+        $wasUpdated = $this->updateProjectTicket->handle($ticket, $user, $request->validated());
+        $statusMessage = $wasUpdated
+            ? "{$ticket->ticket_key} was updated."
+            : 'No ticket changes were detected.';
+
+        return TicketResource::make($ticket->fresh()->load([
+            'assignee',
+            'author',
+            'fieldValues.ticketFieldDefinition',
+            'fieldValues.userValue',
+            'ticketPriority',
+            'ticketStatus.boardColumn',
+            'ticketType',
+            'worklogEntries.actor',
+        ]))
+            ->additional([
+                'meta' => [
+                    'message' => $statusMessage,
+                ],
+            ])
+            ->response();
+    }
+
+    public function statusTargets(Request $request, Project $project, Ticket $ticket): JsonResponse
+    {
+        $user = $this->authenticatedUser($request);
+
+        abort_unless(
+            $this->permissionService->allows($user, Permission::ProjectRead, $project),
+            403,
+        );
+
+        return response()->json([
+            'data' => $this->buildProjectTicketStatusTargetsPayload->handle($ticket),
+        ]);
+    }
+
+    public function move(
+        MoveProjectTicketRequest $request,
+        Project $project,
+        Ticket $ticket,
+    ): JsonResponse {
+        $user = $this->authenticatedUser($request);
+
+        abort_unless(
+            $this->permissionService->allows($user, Permission::ProjectWrite, $project),
+            403,
+        );
+
+        $result = $this->moveProjectTicket->handle($project, $ticket, $user, $request->validated());
+        $message = $result['moved']
+            ? "{$ticket->ticket_key} moved to {$result['destination_label']}."
+            : "{$ticket->ticket_key} already belongs to {$result['destination_label']}.";
+
+        return TicketResource::make($ticket->fresh()->load(['ticketPriority', 'ticketStatus.boardColumn', 'ticketType']))
+            ->additional([
+                'meta' => [
+                    'message' => $message,
+                ],
+            ])
+            ->response();
+    }
+}