Dominio Cart

Propósito

Gestiona el carrito activo de un tenant tanto para visitantes como para usuarios autenticados.

Modelo

Cart: pertenece a un tenant y opcionalmente a un usuario; calcula el total, permite agregar, actualizar o quitar ítems y apunta a su reserva de stock vigente mediante current_stock_reservation_id.
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.
GuestCartMergeService: incorpora el carrito invitado al usuario cuando este se autentica.

Endpoints

Bajo /tenants/{tenant:codigo}:

GET /cart.
POST /cart/items.
PATCH /cart/items/{cartItem}.
DELETE /cart/items/{cartItem}.

Contratos

AddCartItemRequest y UpdateCartItemQuantityRequest validan selección y cantidad. CartResource y CartItemResource estabilizan la respuesta pública. Cada ítem expone nombre, imagen y precio_unitario en la raíz, priorizando la variante seleccionada y usando el catálogo base como respaldo. La variante seleccionada se serializa en variant; las variantes alternativas no forman parte de la respuesta del carrito.

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.

Cada edición sincroniza una única reserva para el carrito completo. Si varios ítems o bundles consumen el mismo inventario, se persiste una sola línea con la cantidad agregada. Al editar durante checkout, la compra anterior queda superseded, su reserva se libera con el motivo correspondiente y se crea otra para el carrito actualizado.

El comando unificado php artisan reservations:expire recorre una sola vez las reservas activas cuyo expires_at haya vencido. Cuando pertenecen a un carrito, conserva la reserva y sus líneas como historial, libera el stock como conjunto y deja intactos el carrito y sus ítems.