shopit-back/app/Domains/Cart/documentacion

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, se desvincula y el carrito conserva la misma reserva activa con sus líneas actualizadas.

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 cambia el carrito asociado a expired sin eliminar sus ítems. Al volver a resolver ese carrito desde la API, el anterior pasa automáticamente a abandoned y se crea uno activo y vacío para la misma identidad. El cliente nunca necesita reiniciarlo explícitamente. La API también materializa este vencimiento al acceder al carrito aunque el comando programado todavía no haya corrido.