feat(purchase): add review submission for pending purchases and update related logic

app/Domains/Purchase/Controllers/PurchaseController.php

@@ -223,6 +223,19 @@ class PurchaseController extends Controller
         );
     }
 
+    public function submitForReview(
+        Request $request,
+        Tenant $tenant,
+        Purchase $compra,
+        CheckoutService $checkoutService,
+    ): PurchaseResource {
+        $compra = $this->resolveScopedPurchase($tenant, $request->user()->id, $compra);
+
+        return PurchaseResource::make(
+            $checkoutService->submitForReview($compra),
+        );
+    }
+
     public function cancel(Request $request, Tenant $tenant, Purchase $compra, CheckoutService $checkoutService): PurchaseResource
     {
         $compra = $this->resolveScopedPurchase($tenant, $request->user()->id, $compra);

app/Domains/Purchase/Models/Purchase.php

@@ -37,6 +37,8 @@ class Purchase extends Model
 
     public const STATUS_PENDING_PAYMENT = 'pending_payment';
 
+    public const STATUS_IN_REVIEW = 'in_review';
+
     public const STATUS_PAID = 'paid';
 
     public const STATUS_CANCELLED = 'cancelled';

app/Domains/Purchase/Services/CheckoutService.php

@@ -70,6 +70,7 @@ class CheckoutService
 
             if (in_array($purchase->status, [
                 Purchase::STATUS_PAID,
+                Purchase::STATUS_IN_REVIEW,
                 Purchase::STATUS_CANCELLED,
                 Purchase::STATUS_REJECTED,
                 Purchase::STATUS_EXPIRED,
@@ -86,6 +87,39 @@ class CheckoutService
         });
     }
 
+    public function submitForReview(Purchase $purchase): Purchase
+    {
+        return DB::transaction(function () use ($purchase): Purchase {
+            /** @var Purchase $purchase */
+            $purchase = Purchase::query()
+                ->lockForUpdate()
+                ->findOrFail($purchase->getKey());
+
+            if (in_array($purchase->status, [
+                Purchase::STATUS_IN_REVIEW,
+                Purchase::STATUS_PAID,
+            ], true)) {
+                return $this->loadPurchase($purchase);
+            }
+
+            if (
+                $purchase->status !== Purchase::STATUS_PENDING_PAYMENT
+                || ($purchase->expires_at !== null && $purchase->expires_at->isPast())
+            ) {
+                throw ValidationException::withMessages([
+                    'purchase' => __('api.purchase.not_available_for_review'),
+                ]);
+            }
+
+            $purchase->update([
+                'status' => Purchase::STATUS_IN_REVIEW,
+                'expires_at' => null,
+            ]);
+
+            return $this->loadPurchase($purchase);
+        });
+    }
+
     /**
      * @param  array<string, string>  $customerData
      */

app/Domains/Purchase/routes/api.php

@@ -12,5 +12,6 @@ Route::prefix('tenants/{tenant:codigo}')->middleware('auth:sanctum')->group(func
     Route::patch('compras/{compra}/customer-data', [PurchaseController::class, 'updateCustomerData']);
     Route::post('compras/{compra}/payment-intent', [PurchaseController::class, 'paymentIntent']);
     Route::post('compras/{compra}/complete', [PurchaseController::class, 'complete']);
+    Route::post('compras/{compra}/review', [PurchaseController::class, 'submitForReview']);
     Route::post('compras/{compra}/cancel', [PurchaseController::class, 'cancel']);
 });