feat: add transactional approval workflow

app/Domain/Approvals/Models/ApprovalAction.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Domain\Approvals\Models;
+
+use App\Domain\Reservations\Models\Reservation;
+use App\Models\User;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class ApprovalAction extends Model
+{
+    public const UPDATED_AT = null;
+
+    protected $fillable = [
+        'reservation_id', 'actor_id', 'action', 'previous_status', 'new_status',
+        'comment', 'created_at',
+    ];
+
+    /** @return BelongsTo<Reservation, $this> */
+    public function reservation(): BelongsTo
+    {
+        return $this->belongsTo(Reservation::class);
+    }
+
+    /** @return BelongsTo<User, $this> */
+    public function actor(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'actor_id');
+    }
+}

app/Domain/Approvals/Services/ApprovalService.php

@@ -0,0 +1,133 @@
+<?php
+
+namespace App\Domain\Approvals\Services;
+
+use App\Domain\Approvals\Models\ApprovalAction;
+use App\Domain\Audit\Models\AuditLog;
+use App\Domain\Identity\Enums\RoleName;
+use App\Domain\Inventory\Models\SnipeAsset;
+use App\Domain\Reservations\Enums\ReservationItemStatus;
+use App\Domain\Reservations\Enums\ReservationStatus;
+use App\Domain\Reservations\Models\Reservation;
+use App\Domain\Reservations\Services\AvailabilityService;
+use App\Models\User;
+use Illuminate\Auth\Access\AuthorizationException;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Validation\ValidationException;
+
+class ApprovalService
+{
+    public function __construct(private readonly AvailabilityService $availability) {}
+
+    public function approve(Reservation $reservation, User $actor, ?string $comment = null): Reservation
+    {
+        $this->authorize($actor);
+
+        return DB::transaction(function () use ($reservation, $actor, $comment): Reservation {
+            $locked = $this->lockPending($reservation);
+            $items = $locked->items()->with('asset')->get();
+            SnipeAsset::query()->whereKey($items->pluck('snipe_asset_id'))->orderBy('id')->lockForUpdate()->get();
+
+            $unavailable = $items->filter(fn ($item): bool => ! $this->availability->isAvailable(
+                $item->asset,
+                $item->starts_at,
+                $item->ends_at,
+                $locked->id,
+            ));
+            if ($unavailable->isNotEmpty()) {
+                throw ValidationException::withMessages([
+                    'decision' => 'A disponibilidade mudou: '.$unavailable->pluck('asset.name')->join(', ').'.',
+                ]);
+            }
+
+            $this->transition($locked, $actor, ReservationStatus::Approved, 'approved', $comment, [
+                'approved_by' => $actor->id,
+                'approved_at' => now(),
+                'decision_reason' => $comment,
+            ]);
+            $locked->items()->where('status', ReservationItemStatus::Held)->update([
+                'status' => ReservationItemStatus::Reserved,
+            ]);
+
+            return $locked->load('requester', 'items.asset');
+        }, 3);
+    }
+
+    public function reject(Reservation $reservation, User $actor, string $reason): Reservation
+    {
+        $this->authorize($actor);
+
+        return DB::transaction(function () use ($reservation, $actor, $reason): Reservation {
+            $locked = $this->lockPending($reservation);
+            $this->transition($locked, $actor, ReservationStatus::Rejected, 'rejected', $reason, [
+                'rejected_by' => $actor->id,
+                'rejected_at' => now(),
+                'decision_reason' => $reason,
+            ]);
+            $locked->items()->whereIn('status', ReservationItemStatus::blockingValues())->update([
+                'status' => ReservationItemStatus::Cancelled,
+            ]);
+
+            return $locked->load('requester', 'items.asset');
+        }, 3);
+    }
+
+    public function requestInformation(Reservation $reservation, User $actor, string $comment): Reservation
+    {
+        $this->authorize($actor);
+
+        return DB::transaction(function () use ($reservation, $actor, $comment): Reservation {
+            $locked = $this->lockPending($reservation);
+            $this->transition($locked, $actor, ReservationStatus::AwaitingInformation, 'information_requested', $comment, [
+                'decision_reason' => $comment,
+                'approval_deadline' => now()->addHours(48),
+            ]);
+
+            return $locked->load('requester', 'items.asset');
+        }, 3);
+    }
+
+    private function authorize(User $actor): void
+    {
+        if (! $actor->active || (! $actor->hasRole(RoleName::Approver) && ! $actor->hasRole(RoleName::Administrator))) {
+            throw new AuthorizationException('Não tem permissão para decidir requisições.');
+        }
+    }
+
+    private function lockPending(Reservation $reservation): Reservation
+    {
+        $locked = Reservation::query()->whereKey($reservation->id)->lockForUpdate()->firstOrFail();
+        if ($locked->status !== ReservationStatus::PendingApproval) {
+            throw ValidationException::withMessages(['decision' => 'A requisição já não aguarda uma decisão.']);
+        }
+
+        return $locked;
+    }
+
+    /** @param array<string, mixed> $attributes */
+    private function transition(Reservation $reservation, User $actor, ReservationStatus $next, string $action, ?string $comment, array $attributes): void
+    {
+        $previous = $reservation->status;
+        if (! $previous->canTransitionTo($next)) {
+            throw ValidationException::withMessages(['decision' => 'Transição de estado inválida.']);
+        }
+
+        $reservation->update(['status' => $next, ...$attributes]);
+        ApprovalAction::create([
+            'reservation_id' => $reservation->id,
+            'actor_id' => $actor->id,
+            'action' => $action,
+            'previous_status' => $previous->value,
+            'new_status' => $next->value,
+            'comment' => $comment,
+        ]);
+        AuditLog::create([
+            'actor_id' => $actor->id,
+            'event' => "reservation.{$action}",
+            'auditable_type' => $reservation->getMorphClass(),
+            'auditable_id' => $reservation->id,
+            'before' => ['status' => $previous->value],
+            'after' => ['status' => $next->value, 'comment' => $comment],
+        ]);
+    }
+}

app/Domain/Reservations/Models/ReservationItem.php

@@ -4,9 +4,16 @@ namespace App\Domain\Reservations\Models;
 
 use App\Domain\Inventory\Models\SnipeAsset;
 use App\Domain\Reservations\Enums\ReservationItemStatus;
+use Carbon\CarbonImmutable;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 
+/**
+ * @property ReservationItemStatus $status
+ * @property CarbonImmutable $starts_at
+ * @property CarbonImmutable $ends_at
+ * @property SnipeAsset $asset
+ */
 class ReservationItem extends Model
 {
     protected $fillable = [

app/Domain/Reservations/Services/AvailabilityService.php

@@ -25,14 +25,19 @@ class AvailabilityService
                 ->where('ends_at', '>', $startsAt));
     }
 
-    public function isAvailable(SnipeAsset $asset, DateTimeInterface $startsAt, DateTimeInterface $endsAt): bool
-    {
+    public function isAvailable(
+        SnipeAsset $asset,
+        DateTimeInterface $startsAt,
+        DateTimeInterface $endsAt,
+        ?int $exceptReservationId = null,
+    ): bool {
         if (! $asset->active || ! $asset->requestable || $asset->assigned_id !== null) {
             return false;
         }
 
         $hasReservationConflict = $asset->reservationItems()
             ->whereIn('status', ReservationItemStatus::blockingValues())
+            ->when($exceptReservationId, fn (Builder $query): Builder => $query->where('reservation_id', '!=', $exceptReservationId))
             ->where('starts_at', '<', $endsAt)
             ->where('ends_at', '>', $startsAt)
             ->exists();

app/Http/Controllers/ApprovalController.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Domain\Approvals\Services\ApprovalService;
+use App\Domain\Reservations\Enums\ReservationStatus;
+use App\Domain\Reservations\Models\Reservation;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Inertia\Inertia;
+use Inertia\Response;
+
+class ApprovalController extends Controller
+{
+    public function index(Request $request): Response
+    {
+        $filters = $request->validate(['search' => ['nullable', 'string', 'max:100']]);
+
+        return Inertia::render('approvals/index', [
+            'reservations' => Reservation::query()
+                ->with(['requester:id,name,email,department', 'items.asset:id,name,asset_tag,category_name'])
+                ->whereIn('status', [ReservationStatus::PendingApproval, ReservationStatus::AwaitingInformation])
+                ->when($filters['search'] ?? null, fn ($query, string $search) => $query
+                    ->where(fn ($query) => $query
+                        ->where('reference', 'like', "%{$search}%")
+                        ->orWhereHas('requester', fn ($query) => $query->where('name', 'like', "%{$search}%"))))
+                ->oldest('starts_at')
+                ->paginate(20)
+                ->withQueryString(),
+            'filters' => $filters,
+        ]);
+    }
+
+    public function approve(Request $request, Reservation $reservation, ApprovalService $service): RedirectResponse
+    {
+        $data = $request->validate(['comment' => ['nullable', 'string', 'max:1000']]);
+        $service->approve($reservation, $request->user(), $data['comment'] ?? null);
+
+        return back()->with('success', "Requisição {$reservation->reference} aprovada.");
+    }
+
+    public function reject(Request $request, Reservation $reservation, ApprovalService $service): RedirectResponse
+    {
+        $data = $request->validate(['comment' => ['required', 'string', 'min:5', 'max:1000']]);
+        $service->reject($reservation, $request->user(), $data['comment']);
+
+        return back()->with('success', "Requisição {$reservation->reference} rejeitada.");
+    }
+
+    public function requestInformation(Request $request, Reservation $reservation, ApprovalService $service): RedirectResponse
+    {
+        $data = $request->validate(['comment' => ['required', 'string', 'min:5', 'max:1000']]);
+        $service->requestInformation($reservation, $request->user(), $data['comment']);
+
+        return back()->with('success', "Pedido de esclarecimentos enviado para {$reservation->reference}.");
+    }
+}

app/Http/Middleware/HandleInertiaRequests.php

@@ -47,6 +47,7 @@ class HandleInertiaRequests extends Middleware
             ],
             'can' => [
                 'administer' => fn (): bool => $request->user()?->can('administer') ?? false,
+                'approveReservations' => fn (): bool => $request->user()?->can('approve-reservations') ?? false,
             ],
             'sidebarOpen' => ! $request->hasCookie('sidebar_state') || $request->cookie('sidebar_state') === 'true',
         ];

app/Providers/AppServiceProvider.php

@@ -32,6 +32,11 @@ class AppServiceProvider extends ServiceProvider
             'administer',
             fn (User $user): bool => $user->active && $user->hasRole(RoleName::Administrator),
         );
+        Gate::define(
+            'approve-reservations',
+            fn (User $user): bool => $user->active
+                && ($user->hasRole(RoleName::Approver) || $user->hasRole(RoleName::Administrator)),
+        );
     }
 
     /**