Squashed commit of the following:

commit 1dc4e29c69 Author: ncoronel <ncoronel@quo.ar> Date: Wed Aug 19 13:58:03 2026 -0300 refactor(reservations): unify expiration command commit 093e894cc3 Author: ncoronel <ncoronel@quo.ar> Date: Wed Aug 19 13:48:09 2026 -0300 feat(cart): expire abandoned stock reservations commit fdf0f3328f Author: ncoronel <ncoronel@quo.ar> Date: Wed Aug 19 12:53:12 2026 -0300 refactor(stock): implement expiration for stock reservations and add configuration commit 8d6bcdcc43 Author: ncoronel <ncoronel@quo.ar> Date: Wed Aug 19 12:38:21 2026 -0300 refactor(cart): invalidate payment on actual changes commit 3206e293eb Author: ncoronel <ncoronel@quo.ar> Date: Wed Aug 19 12:24:48 2026 -0300 refactor(cart): own checkout item editing commit aed99bd05e Author: ncoronel <ncoronel@quo.ar> Date: Wed Aug 19 12:14:57 2026 -0300 refactor(checkout): remove legacy purchase item reservations commit f1649e0e4b Author: ncoronel <ncoronel@quo.ar> Date: Wed Aug 19 12:06:29 2026 -0300 refactor(checkout): materialize purchase items on confirmation commit e6c4b40a37 Author: ncoronel <ncoronel@quo.ar> Date: Wed Aug 19 12:06:19 2026 -0300 feat(inventory): add traceable cart stock reservations
2026-08-19 13:59:38 -03:00
parent 15878cd9ba
commit 172e14ae9b
45 changed files with 1391 additions and 544 deletions
--- a/app/Domains/Cart/Controllers/CartController.php
+++ b/app/Domains/Cart/Controllers/CartController.php
@@ -2,6 +2,7 @@

 namespace App\Domains\Cart\Controllers;

+use App\Domains\Cart\Models\Cart;
 use App\Domains\Cart\Models\CartItem;
 use App\Domains\Cart\Requests\AddCartItemRequest;
 use App\Domains\Cart\Requests\UpdateCartItemQuantityRequest;
@@ -77,6 +78,36 @@ class CartController extends Controller
        ]);
    }

+    public function updateCheckoutItem(
+        UpdateCartItemQuantityRequest $request,
+        Tenant $tenant,
+        Cart $cart,
+        CartItem $cartItem,
+    ): CartResource {
+        $updatesVariant = $request->exists('variant_id');
+
+        return CartResource::make(
+            $this->cartService->updateCheckoutItem(
+                $tenant,
+                $request,
+                $cart,
+                $cartItem->getKey(),
+                (int) $request->validated('cantidad'),
+                $updatesVariant
+                    ? ($request->validated('variant_id') !== null
+                        ? (int) $request->validated('variant_id')
+                        : null)
+                    : $cartItem->variant_id,
+                $updatesVariant,
+            ),
+        )->additional([
+            'code' => $updatesVariant ? 'cart.item_updated' : 'cart.quantity_updated',
+            'message' => $updatesVariant
+                ? __('api.cart.item_updated')
+                : __('api.cart.quantity_updated'),
+        ]);
+    }
+
    public function removeItem(Request $request, Tenant $tenant, CartItem $cartItem): CartResource
    {
        return CartResource::make(
--- a/app/Domains/Cart/Models/Cart.php
+++ b/app/Domains/Cart/Models/Cart.php
@@ -7,6 +7,8 @@ use App\Domains\Catalog\Models\CatalogItem;
 use App\Domains\Catalog\Models\Inventory;
 use App\Domains\Catalog\Models\Variant;
 use App\Domains\Catalog\Services\CatalogInventoryService;
+use App\Domains\Catalog\Services\StockReservationService;
+use App\Domains\Purchase\Models\Purchase;
 use App\Domains\Purchase\Services\UserPurchaseLimitService;
 use App\Domains\Tenant\Models\Tenant;
 use Illuminate\Database\Eloquent\Attributes\Fillable;
@@ -24,6 +26,7 @@ use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
    'user_id',
    'guest_token',
    'status',
+    'origin',
 ])]
 class Cart extends Model
 {
@@ -32,6 +35,10 @@ class Cart extends Model

    protected $table = 'carritos';

+    public const ORIGIN_USER = 'user';
+
+    public const ORIGIN_DIRECT_CHECKOUT = 'direct_checkout';
+
    protected function casts(): array
    {
        return [
@@ -63,6 +70,12 @@ class Cart extends Model
        return $this->hasMany(CartItem::class, 'cart_id');
    }

+    /** @return HasMany<Purchase, $this> */
+    public function purchases(): HasMany
+    {
+        return $this->hasMany(Purchase::class, 'cart_id');
+    }
+
    public function getTotalAmount(): float
    {
        $items = $this->relationLoaded('items')
@@ -114,11 +127,12 @@ class Cart extends Model
                    'cantidad' => $quantity,
                ]);
            } else {
+                app(StockReservationService::class)->ensure($item, $selectedItem);
                $item->cantidad += $quantity;
                $item->save();
            }

-            $inventoryService->reserve($selectedItem, $quantity);
+            app(StockReservationService::class)->reserve($item, $selectedItem, $quantity);

            return $item->fresh();
        });
@@ -129,6 +143,7 @@ class Cart extends Model
        int $quantity,
        ?int $variantId = null,
        bool $updateVariant = false,
+        ?int $excludedPurchaseId = null,
    ): CartItem {
        if ($quantity <= 0) {
            throw ValidationException::withMessages([
@@ -141,6 +156,7 @@ class Cart extends Model
            $quantity,
            $variantId,
            $updateVariant,
+            $excludedPurchaseId,
        ): CartItem {
            /** @var CartItem $item */
            $item = $this->items()
@@ -168,9 +184,10 @@ class Cart extends Model
                $this->assertUserPurchaseLimit(
                    $nextSelection,
                    $otherVariantsQuantity + $quantity,
+                    $excludedPurchaseId,
                );

-                $inventoryService->release($currentSelection, $item->cantidad);
+                app(StockReservationService::class)->release($item, $currentSelection, $item->cantidad);
                $availableQuantity = $inventoryService->availableQuantity($nextSelection);

                if ($availableQuantity !== null && $availableQuantity < $quantity) {
@@ -186,11 +203,11 @@ class Cart extends Model
                    ->lockForUpdate()
                    ->first();

-                $inventoryService->reserve($nextSelection, $quantity);
-
                if ($targetItem !== null) {
+                    app(StockReservationService::class)->ensure($targetItem, $nextSelection);
                    $targetItem->cantidad += $quantity;
                    $targetItem->save();
+                    app(StockReservationService::class)->reserve($targetItem, $nextSelection, $quantity);
                    $item->delete();

                    return $targetItem->fresh();
@@ -199,6 +216,7 @@ class Cart extends Model
                $item->variant_id = $variantId;
                $item->cantidad = $quantity;
                $item->save();
+                app(StockReservationService::class)->reserve($item, $nextSelection, $quantity);

                return $item->fresh();
            }
@@ -213,6 +231,7 @@ class Cart extends Model
                $this->assertUserPurchaseLimit(
                    $currentSelection,
                    $otherVariantsQuantity + $quantity,
+                    $excludedPurchaseId,
                );
            }

@@ -225,17 +244,17 @@ class Cart extends Model
                ]);
            }

-            $item->cantidad = $quantity;
-            $item->save();
-
            if ($delta > 0) {
-                $inventoryService->reserve($currentSelection, $delta);
+                app(StockReservationService::class)->reserve($item, $currentSelection, $delta);
            }

            if ($delta < 0) {
-                $inventoryService->release($currentSelection, abs($delta));
+                app(StockReservationService::class)->release($item, $currentSelection, abs($delta));
            }

+            $item->cantidad = $quantity;
+            $item->save();
+
            return $item->fresh();
        });
    }
@@ -254,7 +273,8 @@ class Cart extends Model
                $item->variant_id,
                true,
            );
-            app(CatalogInventoryService::class)->release(
+            app(StockReservationService::class)->release(
+                $item,
                $selectedItem,
                $item->cantidad,
            );
@@ -334,6 +354,7 @@ class Cart extends Model
    private function assertUserPurchaseLimit(
        CatalogItem|Variant $selectedItem,
        int $cartQuantity,
+        ?int $excludedPurchaseId = null,
    ): void {
        if ($this->user_id === null) {
            return;
@@ -347,6 +368,7 @@ class Cart extends Model
            $catalogItem,
            $this->user_id,
            $cartQuantity,
+            $excludedPurchaseId,
            field: 'cantidad',
        );
    }
--- a/app/Domains/Cart/Models/CartItem.php
+++ b/app/Domains/Cart/Models/CartItem.php
@@ -3,11 +3,13 @@
 namespace App\Domains\Cart\Models;

 use App\Domains\Catalog\Models\CatalogItem;
+use App\Domains\Catalog\Models\StockReservation;
 use App\Domains\Catalog\Models\Variant;
 use Illuminate\Database\Eloquent\Attributes\Fillable;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;

 #[Fillable([
    'cart_id',
@@ -55,4 +57,10 @@ class CartItem extends Model
    {
        return $this->variant ?? $this->catalogItem;
    }
+
+    /** @return HasMany<StockReservation, $this> */
+    public function stockReservations(): HasMany
+    {
+        return $this->hasMany(StockReservation::class);
+    }
 }
--- a/app/Domains/Cart/Services/CartService.php
+++ b/app/Domains/Cart/Services/CartService.php
@@ -4,15 +4,24 @@ namespace App\Domains\Cart\Services;

 use App\Domains\Auth\Models\User;
 use App\Domains\Cart\Models\Cart;
+use App\Domains\Cart\Models\CartItem;
+use App\Domains\Catalog\Services\StockReservationService;
+use App\Domains\Purchase\Models\Purchase;
 use App\Domains\Tenant\Models\Tenant;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Str;
+use Illuminate\Validation\ValidationException;
 use Symfony\Component\HttpFoundation\Cookie;
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

 class CartService
 {
+    public function __construct(
+        private readonly StockReservationService $reservations,
+    ) {}
+
    public function show(Tenant $tenant, Request $request): Cart
    {
        $resolvedIdentity = $this->resolveIdentity($request);
@@ -66,6 +75,107 @@ class CartService
        return $this->loadCart($cart);
    }

+    public function updateCheckoutItem(
+        Tenant $tenant,
+        Request $request,
+        Cart $cart,
+        int $cartItemId,
+        int $quantity,
+        ?int $variantId,
+        bool $updateVariant,
+    ): Cart {
+        $user = $request->user() ?? Auth::guard('sanctum')->user();
+
+        if (! $user instanceof User) {
+            throw new NotFoundHttpException('Checkout cart not found.');
+        }
+
+        return DB::transaction(function () use (
+            $tenant,
+            $user,
+            $cart,
+            $cartItemId,
+            $quantity,
+            $variantId,
+            $updateVariant,
+        ): Cart {
+            /** @var Purchase|null $purchase */
+            $purchase = Purchase::query()
+                ->where('cart_id', $cart->getKey())
+                ->where('tenant_codigo', $tenant->codigo)
+                ->where('user_id', $user->getKey())
+                ->whereIn('status', [
+                    Purchase::STATUS_CREATED,
+                    Purchase::STATUS_PENDING_PAYMENT,
+                ])
+                ->whereDoesntHave('items')
+                ->lockForUpdate()
+                ->first();
+
+            if ($purchase === null) {
+                throw new NotFoundHttpException('Checkout cart not found.');
+            }
+
+            if ($purchase->expires_at !== null && $purchase->expires_at->isPast()) {
+                throw ValidationException::withMessages([
+                    'cart' => __('api.purchase.not_editable'),
+                ]);
+            }
+
+            /** @var Cart|null $checkoutCart */
+            $checkoutCart = Cart::query()
+                ->whereKey($cart->getKey())
+                ->where('tenant_codigo', $tenant->codigo)
+                ->where('user_id', $user->getKey())
+                ->where('status', 'checkout')
+                ->lockForUpdate()
+                ->first();
+
+            if ($checkoutCart === null) {
+                throw new NotFoundHttpException('Checkout cart not found.');
+            }
+
+            /** @var CartItem|null $cartItem */
+            $cartItem = $checkoutCart->items()
+                ->whereKey($cartItemId)
+                ->lockForUpdate()
+                ->first();
+
+            if ($cartItem === null) {
+                throw new NotFoundHttpException('Checkout item not found.');
+            }
+
+            $hasChanges = (int) $cartItem->cantidad !== $quantity
+                || ($updateVariant && $cartItem->variant_id !== $variantId);
+
+            if (! $hasChanges) {
+                return $this->loadCart($checkoutCart);
+            }
+
+            $checkoutCart->updateItem(
+                $cartItemId,
+                $quantity,
+                $variantId,
+                $updateVariant,
+                $purchase->getKey(),
+            );
+
+            $purchase->telepagosQr()->delete();
+            $purchase->update([
+                'status' => Purchase::STATUS_CREATED,
+                'payment_method' => null,
+                'transfer_payer_dni' => null,
+                'total' => $checkoutCart->getTotalAmount(),
+                'expires_at' => now()->addMinutes(
+                    max(1, (int) config('purchase.checkout_expiration_minutes', 30)),
+                ),
+            ]);
+            $this->reservations->syncPurchaseExpiration($purchase);
+
+            return $this->loadCart($checkoutCart);
+        });
+    }
+
    public function removeItem(Tenant $tenant, Request $request, int $cartItemId): Cart
    {
        $identity = $this->requireIdentity($request);
--- a/app/Domains/Cart/Services/ExpireCartReservationsService.php
+++ b/app/Domains/Cart/Services/ExpireCartReservationsService.php
@@ -0,0 +1,123 @@
+<?php
+
+namespace App\Domains\Cart\Services;
+
+use App\Domains\Cart\Models\Cart;
+use App\Domains\Cart\Models\CartItem;
+use App\Domains\Catalog\Models\Inventory;
+use App\Domains\Catalog\Models\StockReservation;
+use Illuminate\Support\Facades\DB;
+
+class ExpireCartReservationsService
+{
+    public function expireOverdue(): int
+    {
+        $expiredItems = 0;
+        $lastCartItemId = 0;
+
+        do {
+            $cartItemIds = StockReservation::query()
+                ->where('status', StockReservation::STATUS_ACTIVE)
+                ->whereNull('purchase_id')
+                ->whereNotNull('cart_item_id')
+                ->whereNotNull('expires_at')
+                ->where('expires_at', '<=', now())
+                ->where('cart_item_id', '>', $lastCartItemId)
+                ->whereHas('cartItem.cart', fn ($query) => $query->where('status', 'active'))
+                ->select('cart_item_id')
+                ->distinct()
+                ->orderBy('cart_item_id')
+                ->limit(500)
+                ->pluck('cart_item_id');
+
+            foreach ($cartItemIds as $cartItemId) {
+                $lastCartItemId = (int) $cartItemId;
+
+                if ($this->expireCartItem($lastCartItemId)) {
+                    $expiredItems++;
+                }
+            }
+        } while ($cartItemIds->count() === 500);
+
+        return $expiredItems;
+    }
+
+    private function expireCartItem(int $cartItemId): bool
+    {
+        /** @var CartItem|null $candidate */
+        $candidate = CartItem::query()->select(['id', 'cart_id'])->find($cartItemId);
+        if ($candidate === null) {
+            return false;
+        }
+
+        return DB::transaction(function () use ($candidate, $cartItemId): bool {
+            /** @var Cart|null $cart */
+            $cart = Cart::query()
+                ->whereKey($candidate->cart_id)
+                ->where('status', 'active')
+                ->lockForUpdate()
+                ->first();
+
+            if ($cart === null) {
+                return false;
+            }
+
+            /** @var CartItem|null $cartItem */
+            $cartItem = $cart->items()
+                ->whereKey($cartItemId)
+                ->lockForUpdate()
+                ->first();
+
+            if ($cartItem === null) {
+                return false;
+            }
+
+            $reservations = StockReservation::query()
+                ->where('cart_item_id', $cartItem->getKey())
+                ->where('status', StockReservation::STATUS_ACTIVE)
+                ->orderBy('inventory_id')
+                ->lockForUpdate()
+                ->get();
+
+            if (
+                $reservations->isEmpty()
+                || $reservations->contains(
+                    fn (StockReservation $reservation): bool => $reservation->purchase_id !== null
+                        || $reservation->expires_at === null
+                        || $reservation->expires_at->isFuture(),
+                )
+            ) {
+                return false;
+            }
+
+            $inventories = Inventory::query()
+                ->whereKey($reservations->pluck('inventory_id'))
+                ->orderBy('id')
+                ->lockForUpdate()
+                ->get()
+                ->keyBy('id');
+
+            foreach ($reservations as $reservation) {
+                $inventory = $inventories->get($reservation->inventory_id)
+                    ?? throw new \InvalidArgumentException('No se encontro el inventario reservado.');
+
+                $inventory->release((int) $reservation->quantity);
+                $reservation->update([
+                    'quantity' => 0,
+                    'status' => StockReservation::STATUS_EXPIRED,
+                    'expires_at' => null,
+                    'released_at' => now(),
+                ]);
+            }
+
+            $cartItem->delete();
+
+            if (! $cart->items()->exists()) {
+                $cart->update(['status' => 'expired']);
+                $cart->delete();
+            }
+
+            return true;
+        });
+    }
+}
--- a/app/Domains/Cart/Services/GuestCartMergeService.php
+++ b/app/Domains/Cart/Services/GuestCartMergeService.php
@@ -34,6 +34,10 @@ class GuestCartMergeService
                ->first();

            if ($userCart !== null) {
+                $userCart->items()
+                    ->orderBy('id')
+                    ->pluck('id')
+                    ->each(fn (int $itemId) => $userCart->removeItem($itemId));
                $userCart->update([
                    'status' => 'converted',
                ]);
--- a/app/Domains/Cart/documentacion/README.md
+++ b/app/Domains/Cart/documentacion/README.md
@@ -7,11 +7,12 @@ Gestiona el carrito activo de un tenant tanto para visitantes como para usuarios
 ## Modelo

 - `Cart`: pertenece a un tenant y opcionalmente a un usuario; calcula el total y permite agregar, actualizar o quitar ítems.
- `CartItem`: referencia un `CatalogItem` y, opcionalmente, una `Variant`; expone la selección efectiva.
+- `CartItem`: referencia un `CatalogItem` y, opcionalmente, una `Variant`; sólo persiste la selección y cantidad, y expone siempre los datos vigentes del catálogo.

 ## Servicios

 - `CartService`: obtiene el carrito, modifica ítems y administra la cookie del token invitado.
+- `ExpireCartReservationsService`: libera las reservas vencidas de carritos activos y elimina los carritos que quedan vacíos.
 - `GuestCartMergeService`: incorpora el carrito invitado al usuario cuando este se autentica.

 ## Endpoints
@@ -30,3 +31,7 @@ Bajo `/tenants/{tenant:codigo}`:
 ## Dependencias y reglas

 Depende de `Catalog` para productos y variantes, de `Tenant` para aislar datos y de `Auth` cuando existe usuario. Toda operación debe comprobar que carrito e ítem pertenecen al tenant actual.
+
+Un carrito puede pasar a `checkout`. Las compras directas usan un carrito técnico con `origin=direct_checkout`; los carritos normales conservan `origin=user` y pueden restaurarse al cancelar o vencer la compra.
+
+El comando unificado `php artisan reservations:expire` procesa primero las compras vencidas y luego las reservas activas sin compra cuyo `expires_at` haya vencido. Se ejecuta cada minuto mediante el scheduler, conserva la fila de reserva con estado `expired`, elimina el ítem abandonado y elimina lógicamente el carrito cuando queda vacío.
--- a/app/Domains/Cart/routes/api.php
+++ b/app/Domains/Cart/routes/api.php
@@ -10,3 +10,9 @@ Route::prefix('tenants/{tenant:codigo}')
        Route::patch('cart/items/{cartItem}', [CartController::class, 'updateItemQuantity']);
        Route::delete('cart/items/{cartItem}', [CartController::class, 'removeItem']);
    });
+
+Route::prefix('tenants/{tenant:codigo}')
+    ->middleware('auth:sanctum')
+    ->group(function (): void {
+        Route::patch('checkout-carts/{cart}/items/{cartItem}', [CartController::class, 'updateCheckoutItem']);
+    });