Add application API and OpenAPI docs

app/Actions/ProjectBoard/DeleteBoardColumn.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Actions\ProjectBoard;
+
+use App\Models\BoardColumn;
+use App\Models\Project;
+use App\Models\TicketStatus;
+use Illuminate\Support\Facades\DB;
+
+class DeleteBoardColumn
+{
+    use ManagesTicketStatusPositions;
+    use ReordersBoardColumns;
+
+    public function handle(Project $project, BoardColumn $boardColumn): string
+    {
+        $deletedName = $boardColumn->name;
+
+        DB::transaction(function () use ($boardColumn, $project): void {
+            $boardColumn->ticketStatuses()
+                ->get()
+                ->each(function (TicketStatus $ticketStatus) use ($project): void {
+                    $ticketStatus->update([
+                        'board_column_id' => null,
+                        'position' => $this->nextStatusPosition($project, null),
+                    ]);
+                });
+
+            $boardColumn->delete();
+
+            $this->normalizeColumnPositions($project);
+        });
+
+        return $deletedName;
+    }
+}

app/Actions/ProjectBoard/DeleteTicketStatus.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace App\Actions\ProjectBoard;
+
+use App\Models\Project;
+use App\Models\TicketStatus;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Validation\ValidationException;
+
+class DeleteTicketStatus
+{
+    use ManagesTicketStatusPositions;
+
+    /**
+     * @return array{context_label: string, deleted_name: string}
+     */
+    public function handle(Project $project, TicketStatus $ticketStatus): array
+    {
+        $ticketStatus->load('boardColumn');
+        $boardColumnId = $ticketStatus->board_column_id;
+
+        if ($this->statusContextQuery($project, $boardColumnId)->count() <= 1) {
+            throw ValidationException::withMessages([
+                'ticket_status_id' => "{$this->statusContextLabel($ticketStatus)} needs at least one ticket status.",
+            ]);
+        }
+
+        $deletedName = $ticketStatus->name;
+        $contextLabel = $this->statusContextLabel($ticketStatus);
+
+        DB::transaction(function () use ($boardColumnId, $project, $ticketStatus): void {
+            $replacementStatus = $this->statusContextQuery($project, $boardColumnId)
+                ->whereKeyNot($ticketStatus->id)
+                ->firstOrFail();
+
+            $ticketStatus->tickets()->update([
+                'ticket_status_id' => $replacementStatus->id,
+            ]);
+
+            $ticketStatus->delete();
+
+            $this->normalizeStatusPositions($project, $boardColumnId);
+        });
+
+        return [
+            'context_label' => $contextLabel,
+            'deleted_name' => $deletedName,
+        ];
+    }
+}

app/Actions/ProjectBoard/ManagesTicketStatusPositions.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace App\Actions\ProjectBoard;
+
+use App\Models\Project;
+use App\Models\TicketStatus;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+trait ManagesTicketStatusPositions
+{
+    private function nextStatusPosition(Project $project, ?int $boardColumnId): int
+    {
+        return $this->statusContextQuery($project, $boardColumnId)->count() + 1;
+    }
+
+    private function normalizeStatusPositions(Project $project, ?int $boardColumnId): void
+    {
+        $this->statusContextQuery($project, $boardColumnId)
+            ->get()
+            ->values()
+            ->each(function (TicketStatus $ticketStatus, int $index): void {
+                $ticketStatus->forceFill([
+                    'position' => $index + 1,
+                ])->saveQuietly();
+            });
+    }
+
+    private function statusContextLabel(TicketStatus $ticketStatus): string
+    {
+        return $ticketStatus->boardColumn?->name ?? 'Backlog';
+    }
+
+    private function statusContextQuery(Project $project, ?int $boardColumnId): HasMany
+    {
+        return $project->ticketStatuses()
+            ->when(
+                $boardColumnId === null,
+                fn ($query) => $query->whereNull('board_column_id'),
+                fn ($query) => $query->where('board_column_id', $boardColumnId),
+            );
+    }
+}

app/Actions/ProjectBoard/ReordersBoardColumns.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace App\Actions\ProjectBoard;
+
+use App\Models\BoardColumn;
+use App\Models\Project;
+use Illuminate\Support\Collection;
+
+trait ReordersBoardColumns
+{
+    private function normalizeColumnPositions(Project $project): void
+    {
+        $this->persistOrderedColumns(
+            $project->boardColumns()
+                ->get()
+                ->values(),
+        );
+    }
+
+    private function reorderColumns(Project $project, BoardColumn $movingColumn, int $desiredPosition): void
+    {
+        /** @var Collection<int, BoardColumn> $columns */
+        $columns = $project->boardColumns()
+            ->whereKeyNot($movingColumn->id)
+            ->get()
+            ->values();
+
+        $insertAt = max(0, min($desiredPosition - 1, $columns->count()));
+
+        $columns->splice($insertAt, 0, [$movingColumn]);
+
+        $this->persistOrderedColumns($columns->values());
+    }
+
+    /**
+     * @param  Collection<int, BoardColumn>  $columns
+     */
+    private function persistOrderedColumns(Collection $columns): void
+    {
+        $temporaryOffset = ((int) $columns->max('position')) + $columns->count() + 1;
+
+        $columns->each(function (BoardColumn $column, int $index) use ($temporaryOffset): void {
+            $column->forceFill([
+                'position' => $temporaryOffset + $index,
+            ])->saveQuietly();
+        });
+
+        $columns->each(function (BoardColumn $column, int $index): void {
+            $column->forceFill([
+                'position' => $index + 1,
+            ])->saveQuietly();
+        });
+    }
+}

app/Actions/ProjectBoard/StoreBoardColumn.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Actions\ProjectBoard;
+
+use App\Models\BoardColumn;
+use App\Models\Project;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\DB;
+
+class StoreBoardColumn
+{
+    use ReordersBoardColumns;
+
+    /**
+     * @param  array{name: string, position?: int|null}  $validated
+     */
+    public function handle(Project $project, array $validated): BoardColumn
+    {
+        $desiredPosition = Arr::get($validated, 'position') ?? $project->boardColumns()->count() + 1;
+
+        return DB::transaction(function () use ($project, $validated, $desiredPosition): BoardColumn {
+            $boardColumn = $project->boardColumns()->create([
+                'name' => Arr::get($validated, 'name'),
+                'position' => $project->boardColumns()->count() + 1,
+            ]);
+            $boardColumn->ticketStatuses()->create([
+                'name' => Arr::get($validated, 'name'),
+                'position' => 1,
+                'project_id' => $project->id,
+            ]);
+
+            $this->reorderColumns($project, $boardColumn, $desiredPosition);
+
+            return $boardColumn;
+        });
+    }
+}

app/Actions/ProjectBoard/StoreTicketStatus.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Actions\ProjectBoard;
+
+use App\Models\Project;
+use App\Models\TicketStatus;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\DB;
+
+class StoreTicketStatus
+{
+    use ManagesTicketStatusPositions;
+
+    /**
+     * @param  array{board_column_id?: int|null, name: string}  $validated
+     */
+    public function handle(Project $project, array $validated): TicketStatus
+    {
+        $boardColumnId = Arr::get($validated, 'board_column_id');
+        $boardColumnId = $boardColumnId === null ? null : (int) $boardColumnId;
+
+        $ticketStatus = DB::transaction(function () use ($boardColumnId, $project, $validated): TicketStatus {
+            return $project->ticketStatuses()->create([
+                'board_column_id' => $boardColumnId,
+                'name' => Arr::get($validated, 'name'),
+                'position' => $this->nextStatusPosition($project, $boardColumnId),
+            ]);
+        });
+
+        return $ticketStatus->load('boardColumn');
+    }
+}

app/Actions/ProjectBoard/UpdateBoardColumn.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Actions\ProjectBoard;
+
+use App\Models\BoardColumn;
+use App\Models\Project;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\DB;
+
+class UpdateBoardColumn
+{
+    use ReordersBoardColumns;
+
+    /**
+     * @param  array{name: string, position: int}  $validated
+     */
+    public function handle(Project $project, BoardColumn $boardColumn, array $validated): BoardColumn
+    {
+        DB::transaction(function () use ($boardColumn, $project, $validated): void {
+            $boardColumn->update([
+                'name' => Arr::get($validated, 'name'),
+            ]);
+
+            $this->reorderColumns($project, $boardColumn, Arr::get($validated, 'position'));
+        });
+
+        return $boardColumn->fresh();
+    }
+}

app/Actions/ProjectBoard/UpdateTicketStatus.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Actions\ProjectBoard;
+
+use App\Models\TicketStatus;
+use Illuminate\Support\Arr;
+
+class UpdateTicketStatus
+{
+    /**
+     * @param  array{name: string}  $validated
+     */
+    public function handle(TicketStatus $ticketStatus, array $validated): TicketStatus
+    {
+        $ticketStatus->update([
+            'name' => Arr::get($validated, 'name'),
+        ]);
+
+        return $ticketStatus->fresh();
+    }
+}

app/Actions/ProjectBoard/UpdateTicketStatusTransitions.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Actions\ProjectBoard;
+
+use App\Models\TicketStatus;
+use Illuminate\Support\Arr;
+
+class UpdateTicketStatusTransitions
+{
+    /**
+     * @param  array{allowed_ticket_status_ids?: array<int, int|string>|null}  $validated
+     */
+    public function handle(TicketStatus $ticketStatus, array $validated): TicketStatus
+    {
+        $allowedTicketStatusIds = collect(Arr::get($validated, 'allowed_ticket_status_ids', []))
+            ->map(fn (int|string $ticketStatusId): int => (int) $ticketStatusId)
+            ->unique()
+            ->values()
+            ->all();
+
+        $ticketStatus->allowedTargetStatuses()->sync($allowedTicketStatusIds);
+
+        return $ticketStatus->fresh();
+    }
+}