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,67 @@
+<?php
+
+namespace App\Actions\Projects;
+
+use App\Actions\Permissions\PermissionService;
+use App\Enums\Permission;
+use App\Http\Resources\ProjectResource;
+use App\Http\Resources\TicketPriorityResource;
+use App\Http\Resources\TicketResource;
+use App\Http\Resources\TicketStatusResource;
+use App\Http\Resources\TicketTypeResource;
+use App\Http\Resources\UserResource;
+use App\Models\Project;
+use App\Models\Ticket;
+use App\Models\User;
+
+class BuildProjectBacklogPayload
+{
+    public function __construct(
+        private readonly PermissionService $permissionService,
+    ) {}
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function handle(Project $project, User $user, mixed $status = null): array
+    {
+        $canManageTickets = $this->permissionService->allows($user, Permission::ProjectWrite, $project);
+
+        return [
+            'backlogTicketStatuses' => TicketStatusResource::collection(
+                $project->ticketStatuses()
+                    ->whereNull('board_column_id')
+                    ->get(),
+            )->resolve(),
+            'canCreateTickets' => $canManageTickets,
+            'canEditTickets' => $canManageTickets,
+            'project' => ProjectResource::make($project)->resolve(),
+            'status' => $status,
+            'ticketStatusOptions' => TicketStatusResource::collection(
+                $project->ticketStatuses()
+                    ->with('boardColumn')
+                    ->get(),
+            )->resolve(),
+            'ticketPriorities' => TicketPriorityResource::collection($project->ticketPriorities()->get())->resolve(),
+            'ticketTypes' => TicketTypeResource::collection($project->ticketTypes()->get())->resolve(),
+            'tickets' => TicketResource::collection(
+                Ticket::query()
+                    ->with([
+                        'ticketPriority',
+                        'ticketStatus.allowedTargetStatuses.boardColumn',
+                        'ticketStatus.boardColumn',
+                        'ticketType',
+                    ])
+                    ->where('project_id', $project->id)
+                    ->whereHas('ticketStatus', fn ($query) => $query->whereNull('board_column_id'))
+                    ->orderByDesc('sequence_number')
+                    ->get(),
+            )->resolve(),
+            'users' => UserResource::collection(
+                User::query()
+                    ->orderBy('name')
+                    ->get(),
+            )->resolve(),
+        ];
+    }
+}
@@ -0,0 +1,46 @@
+<?php
+
+namespace App\Actions\Projects;
+
+use App\Actions\Permissions\PermissionService;
+use App\Enums\Permission;
+use App\Http\Resources\BoardColumnResource;
+use App\Http\Resources\ProjectResource;
+use App\Models\Project;
+use App\Models\User;
+
+class BuildProjectBoardPayload
+{
+    public function __construct(
+        private readonly PermissionService $permissionService,
+    ) {}
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function handle(Project $project, User $user, mixed $status = null): array
+    {
+        $canManageTickets = $this->permissionService->allows($user, Permission::ProjectWrite, $project);
+
+        return [
+            'boardColumns' => BoardColumnResource::collection(
+                $project->boardColumns()
+                    ->with([
+                        'ticketStatuses',
+                        'tickets' => fn ($query) => $query
+                            ->with([
+                                'ticketPriority',
+                                'ticketStatus.allowedTargetStatuses.boardColumn',
+                                'ticketStatus.boardColumn',
+                                'ticketType',
+                            ]),
+                    ])
+                    ->get(),
+            )->resolve(),
+            'canCreateTickets' => $canManageTickets,
+            'canEditTickets' => $canManageTickets,
+            'project' => ProjectResource::make($project)->resolve(),
+            'status' => $status,
+        ];
+    }
+}
@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Actions\Projects;
+
+use App\Http\Resources\BoardColumnResource;
+use App\Http\Resources\ProjectResource;
+use App\Http\Resources\TicketStatusResource;
+use App\Models\Project;
+
+class BuildProjectBoardSettingsPayload
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function handle(Project $project, mixed $status = null): array
+    {
+        return [
+            'backlogTicketStatuses' => TicketStatusResource::collection(
+                $project->ticketStatuses()
+                    ->whereNull('board_column_id')
+                    ->get(),
+            )->resolve(),
+            'boardColumns' => BoardColumnResource::collection(
+                $project->boardColumns()
+                    ->with('ticketStatuses')
+                    ->get(),
+            )->resolve(),
+            'project' => ProjectResource::make($project)->resolve(),
+            'status' => $status,
+            'ticketStatuses' => TicketStatusResource::collection(
+                $project->ticketStatuses()
+                    ->with(['allowedTargetStatuses.boardColumn', 'boardColumn'])
+                    ->get(),
+            )->resolve(),
+        ];
+    }
+}
@@ -0,0 +1,124 @@
+<?php
+
+namespace App\Actions\Projects;
+
+use App\Actions\Git\BuildSuggestedTicketBranchName;
+use App\Actions\Git\ResolveTicketBranchMatches;
+use App\Actions\Git\ResolveTicketPullRequestMatches;
+use App\Actions\Permissions\PermissionService;
+use App\Enums\Permission;
+use App\Http\Resources\ProjectResource;
+use App\Http\Resources\TicketFieldDefinitionResource;
+use App\Http\Resources\TicketLinkResource;
+use App\Http\Resources\TicketLinkTypeResource;
+use App\Http\Resources\TicketPriorityResource;
+use App\Http\Resources\TicketReferenceResource;
+use App\Http\Resources\TicketRepositoryBranchResource;
+use App\Http\Resources\TicketRepositoryPullRequestResource;
+use App\Http\Resources\TicketResource;
+use App\Http\Resources\TicketTreeNodeResource;
+use App\Http\Resources\TicketTypeResource;
+use App\Http\Resources\UserResource;
+use App\Models\Project;
+use App\Models\Ticket;
+use App\Models\TicketLink;
+use App\Models\User;
+
+class BuildProjectTicketDetailPayload
+{
+    public function __construct(
+        private readonly BuildSuggestedTicketBranchName $buildSuggestedTicketBranchName,
+        private readonly PermissionService $permissionService,
+        private readonly ResolveTicketBranchMatches $resolveTicketBranchMatches,
+        private readonly ResolveTicketPullRequestMatches $resolveTicketPullRequestMatches,
+    ) {}
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function handle(Project $project, Ticket $ticket, User $user, mixed $status = null): array
+    {
+        $canEditTicket = $this->permissionService->allows($user, Permission::ProjectWrite, $project);
+        $canManageProject = $this->permissionService->allows($user, Permission::ProjectAdmin, $project);
+        $displayTicket = $ticket->load([
+            'assignee',
+            'author',
+            'fieldValues.ticketFieldDefinition',
+            'fieldValues.userValue',
+            'parentTicket',
+            'ticketPriority',
+            'ticketStatus.boardColumn',
+            'ticketType',
+            'worklogEntries.actor',
+        ]);
+
+        if (! $project->show_author && ! $canManageProject) {
+            $displayTicket->setRelation('author', null);
+            $displayTicket->author_user_id = null;
+        }
+
+        return [
+            'canEditTicket' => $canEditTicket,
+            'canManageProject' => $canManageProject,
+            'childTicketTree' => TicketTreeNodeResource::collection(
+                $ticket->childTickets()
+                    ->with('ticketType')
+                    ->get(),
+            )->resolve(),
+            'linkedTickets' => TicketLinkResource::collection(
+                TicketLink::query()
+                    ->with(['sourceTicket', 'targetTicket', 'ticketLinkType'])
+                    ->where(function ($query) use ($ticket): void {
+                        $query
+                            ->where('source_ticket_id', $ticket->id)
+                            ->orWhere('target_ticket_id', $ticket->id);
+                    })
+                    ->orderBy('id')
+                    ->get()
+                    ->each(fn (TicketLink $ticketLink) => $ticketLink->setAttribute('current_ticket_id', $ticket->id)),
+            )->resolve(),
+            'parentTicketOptions' => TicketReferenceResource::collection(
+                Ticket::query()
+                    ->where('project_id', $project->id)
+                    ->whereKeyNot($ticket->id)
+                    ->whereHas('ticketType', fn ($query) => $query->where('is_parent', true))
+                    ->orderByDesc('sequence_number')
+                    ->get(),
+            )->resolve(),
+            'project' => ProjectResource::make($project)->resolve(),
+            'repositoryBranches' => TicketRepositoryBranchResource::collection(
+                $this->resolveTicketBranchMatches->handle(
+                    $user,
+                    $project,
+                    $ticket,
+                ),
+            )->resolve(),
+            'repositoryPullRequests' => TicketRepositoryPullRequestResource::collection(
+                $this->resolveTicketPullRequestMatches->handle(
+                    $user,
+                    $project,
+                    $ticket,
+                ),
+            )->resolve(),
+            'status' => $status,
+            'suggestedBranchName' => $this->buildSuggestedTicketBranchName->handle($ticket),
+            'ticket' => TicketResource::make($displayTicket)->resolve(),
+            'ticketFieldDefinitions' => TicketFieldDefinitionResource::collection($project->ticketFieldDefinitions()->get())->resolve(),
+            'ticketLinkOptions' => TicketReferenceResource::collection(
+                Ticket::query()
+                    ->where('project_id', $project->id)
+                    ->whereKeyNot($ticket->id)
+                    ->orderByDesc('sequence_number')
+                    ->get(),
+            )->resolve(),
+            'ticketLinkTypes' => TicketLinkTypeResource::collection($project->ticketLinkTypes()->get())->resolve(),
+            'ticketPriorities' => TicketPriorityResource::collection($project->ticketPriorities()->get())->resolve(),
+            'ticketTypes' => TicketTypeResource::collection($project->ticketTypes()->get())->resolve(),
+            'users' => UserResource::collection(
+                User::query()
+                    ->orderBy('name')
+                    ->get(),
+            )->resolve(),
+        ];
+    }
+}
@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Actions\Projects;
+
+use App\Http\Resources\FieldTypeOptionResource;
+use App\Http\Resources\ProjectResource;
+use App\Http\Resources\TicketFieldDefinitionResource;
+use App\Http\Resources\TicketLinkTypeResource;
+use App\Http\Resources\TicketPriorityResource;
+use App\Http\Resources\TicketTypeResource;
+use App\Models\Project;
+use App\Models\TicketFieldDefinition;
+
+class BuildProjectTicketMetadataSettingsPayload
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function handle(Project $project, mixed $status = null, mixed $error = null): array
+    {
+        return [
+            'fieldTypeOptions' => FieldTypeOptionResource::collection(collect(TicketFieldDefinition::FIELD_TYPES))->resolve(),
+            'project' => ProjectResource::make($project)->resolve(),
+            'error' => $error,
+            'status' => $status,
+            'ticketFieldDefinitions' => TicketFieldDefinitionResource::collection($project->ticketFieldDefinitions()->get())->resolve(),
+            'ticketLinkTypes' => TicketLinkTypeResource::collection($project->ticketLinkTypes()->get())->resolve(),
+            'ticketPriorities' => TicketPriorityResource::collection($project->ticketPriorities()->get())->resolve(),
+            'ticketTypes' => TicketTypeResource::collection($project->ticketTypes()->withCount('tickets')->get())->resolve(),
+        ];
+    }
+}
@@ -0,0 +1,46 @@
+<?php
+
+namespace App\Actions\Projects;
+
+use App\Http\Resources\ProjectResource;
+use App\Http\Resources\TicketPriorityResource;
+use App\Http\Resources\TicketStatusResource;
+use App\Http\Resources\TicketTypeResource;
+use App\Http\Resources\UserResource;
+use App\Models\Project;
+use App\Models\User;
+
+class BuildProjectTicketOptionsPayload
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function handle(Project $project, string $source = 'backlog', mixed $status = null): array
+    {
+        $source = $source === 'board' ? 'board' : 'backlog';
+        $defaultTicketStatus = $source === 'board'
+            ? $project->ticketStatuses()->whereNotNull('board_column_id')->first()
+            : $project->ticketStatuses()->whereNull('board_column_id')->first();
+
+        $defaultTicketStatus ??= $project->ticketStatuses()->first();
+
+        return [
+            'defaultTicketStatusId' => $defaultTicketStatus?->id,
+            'project' => ProjectResource::make($project)->resolve(),
+            'source' => $source,
+            'status' => $status,
+            'ticketPriorities' => TicketPriorityResource::collection($project->ticketPriorities()->get())->resolve(),
+            'ticketStatusOptions' => TicketStatusResource::collection(
+                $project->ticketStatuses()
+                    ->with('boardColumn')
+                    ->get(),
+            )->resolve(),
+            'ticketTypes' => TicketTypeResource::collection($project->ticketTypes()->get())->resolve(),
+            'users' => UserResource::collection(
+                User::query()
+                    ->orderBy('name')
+                    ->get(),
+            )->resolve(),
+        ];
+    }
+}
@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Actions\Projects;
+
+use App\Http\Resources\TicketStatusResource;
+use App\Models\Ticket;
+
+class BuildProjectTicketStatusTargetsPayload
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function handle(Ticket $ticket): array
+    {
+        $ticket->loadMissing('ticketStatus.allowedTargetStatuses.boardColumn');
+
+        return [
+            'current_status' => $ticket->ticketStatus === null
+                ? null
+                : TicketStatusResource::make($ticket->ticketStatus->loadMissing('boardColumn'))->resolve(),
+            'target_statuses' => TicketStatusResource::collection(
+                $ticket->ticketStatus?->allowedTargetStatuses ?? collect(),
+            )->resolve(),
+        ];
+    }
+}
@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Actions\Projects;
+
+use App\Actions\Permissions\PermissionService;
+use App\Actions\ProjectTicketMetadata\InitializeProjectTicketMetadata;
+use App\Enums\Permission;
+use App\Models\Project;
+use App\Models\User;
+
+class CreateProject
+{
+    public function __construct(
+        private readonly InitializeProjectTicketMetadata $initializeProjectTicketMetadata,
+        private readonly PermissionService $permissionService,
+    ) {}
+
+    /**
+     * @param  array{key: string, name: string}  $attributes
+     */
+    public function handle(array $attributes, User $actor): Project
+    {
+        $project = Project::query()->create($attributes);
+
+        $this->initializeProjectTicketMetadata->handle($project);
+        $this->permissionService->grant($actor, Permission::ProjectAdmin, $project);
+
+        return $project;
+    }
+}
@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Actions\Projects;
+
+use App\Models\Project;
+
+class DeleteProject
+{
+    public function handle(Project $project): string
+    {
+        $projectName = $project->name;
+
+        $project->delete();
+
+        return $projectName;
+    }
+}
@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Actions\Projects;
+
+use App\Actions\Permissions\PermissionService;
+use App\Enums\Permission;
+use App\Models\Project;
+use App\Models\User;
+use Illuminate\Database\Eloquent\Collection;
+
+class ListVisibleProjects
+{
+    public function __construct(
+        private readonly PermissionService $permissionService,
+    ) {}
+
+    /**
+     * @return Collection<int, Project>
+     */
+    public function handle(User $user): Collection
+    {
+        $projectQuery = Project::query()
+            ->orderByDesc('id');
+
+        if ($this->permissionService->allows($user, Permission::GlobalAdmin)) {
+            return $projectQuery->get();
+        }
+
+        $viewableProjectIds = $this->permissionService->viewableProjectIds($user);
+
+        if ($viewableProjectIds === []) {
+            return new Collection;
+        }
+
+        return $projectQuery
+            ->whereIn('id', $viewableProjectIds)
+            ->get();
+    }
+}