refactor(backend): reorganize domains into Core, Commerce, Ticketing and Shared

app/Domains/Commerce/Catalog/documentacion/README.md

@@ -0,0 +1,36 @@
+# Dominio Catalog
+
+## Propósito
+
+Modela y publica la oferta comercial del tenant: productos, variantes, categorías, marcas, atributos, inventario, bundles y grupos destacados.
+
+## Modelo
+
+- `CatalogItem` es la raíz del producto y se relaciona con tenant, categoría, marca, inventario, variantes, atributos, adjuntos y grupos destacados.
+- `Variant`, `ItemAttribute`, `Attribute`, `AttributeOption` y `VariantDefinition` describen opciones comercializables.
+- `Inventory` administra stock disponible, reservado y comprado.
+- `StockReservation` representa la reserva completa de un carrito o checkout, con estados `active`, `committed`, `released` y `expired`. Su `expires_at` es el único reloj del bloqueo. Al expirar, también pasan a `expired` la compra pagable y el carrito asociados dentro de la misma transacción. Sus estados terminales nunca se reactivan ni se reemplazan implícitamente. Sus `StockReservationLine` agregan la cantidad requerida por inventario, incluso cuando varios ítems o bundles consumen el mismo stock.
+- `Category` soporta jerarquía y categorías globales o propias del tenant.
+- `FeaturedGroup` y `FeaturedItem` organizan secciones destacadas.
+- `BundleComponent` representa los componentes de un paquete.
+
+## Servicios
+
+- `CatalogService`: alta, búsqueda, detalle, listado por categoría y eliminación.
+- `CatalogInventoryService`: consulta, reserva, libera y confirma inventario.
+- `StockReservationService`: sincroniza el carrito como conjunto, bloquea todos sus inventarios en orden estable y mantiene el ledger agregado consistente con `Inventory.reserved_stock`.
+- `ExpireStockReservationsService`: detecta en un único recorrido reservas vencidas de compras, carritos y huérfanas, y delega los efectos comerciales sin mezclar esas reglas con la liberación física del inventario.
+- `FeaturedGroupService`: pagina los ítems destacados para la tienda.
+- `OnTicketFeaturedGroupService`: administra grupos destacados del panel para sitios de tickets.
+
+## Endpoints de tienda
+
+Bajo `/tenants/{tenant:codigo}` se publican catálogo, búsqueda, categoría, detalle, alta de ítems y paginación de grupos destacados.
+
+## Endpoints administrativos
+
+Bajo `/v1/adminapp/tenant/featured-groups`, con `auth:sanctum` y `adminapp.tenant`, se listan, crean y actualizan grupos destacados.
+
+## Dependencias y reglas
+
+Usa `Attachable` para imágenes/archivos, `Tenant` para aislamiento y `Ticket`/`Event` para vigencia y fechas. `Cart` y `Purchase` consumen sus precios, variantes e inventario. Los cambios de stock deben pasar por `CatalogInventoryService` para conservar reservas y disponibilidad.