Design - Product Catalog Module

Objetivos de Diseño

Derivados de Requirements

• R-001/US-001: Crear interfaz de catálogo público optimizada para navegación y descubrimiento de productos
• R-004/US-002: Implementar sistema de búsqueda y filtrado robusto con múltiples criterios
• R-007/US-003: Diseñar vista detallada de producto rica en información y media
• R-010/US-004: Construir panel administrativo completo para gestión de productos
• R-013/US-005: Desarrollar sistema jerárquico de categorías flexible
• R-016/US-006: Integrar control de inventario en tiempo real
• R-019/US-007: Implementar sistema de precios dinámico con promociones
• R-025/US-009: Asegurar control de acceso granular y multi-tenant

Dependencias y Límites del Módulo

Dependencias Internas

• @libs-core/ui-framework - Componentes base y design system
• @libs-core/security - Autenticación y autorización
• @libs-core/shared-models - Entities de Product, Category, Permission, Role
• @libs-core/event-system - Comunicación entre módulos
• @libs-core/log-system - Logging y observabilidad
• @gograb-space/utilities - Utilidades comunes

Dependencias Externas

• NGXS Store - State management
• Angular CDK - Componentes avanzados (drag-drop, virtual scroll)
• RxJS - Reactive programming
• API REST - Backend de productos y categorías

Límites del Módulo

• Entrada: Rutas de catálogo (/catalog, /admin/products)
• Salida: Eventos de producto (product.viewed, product.created, etc.)
• No gestiona: Pagos, envíos, reseñas, ERP externo

Arquitectura y Componentes

Contexto del Sistema

[Cliente Web] --> [Product Catalog Module] --> [Product API]
                         |                         |
                         v                         v
                  [Event System] <--> [Shared Models] <--> [Security Module]
                         |
                         v
                  [UI Framework]

Componentes Principales

1. Public Catalog (Catálogo Público)

• ProductCatalogComponent: Container principal del catálogo
• ProductGridComponent: Grid de productos con paginación
• ProductCardComponent: Card individual de producto
• ProductFiltersComponent: Panel lateral de filtros
• ProductSearchComponent: Barra de búsqueda con autocomplete

2. Product Detail (Detalle de Producto)

• ProductDetailComponent: Container de vista detallada
• ProductGalleryComponent: Galería de imágenes con zoom
• ProductInfoComponent: Información y especificaciones
• ProductActionsComponent: Botones de acción (carrito, wishlist)

3. Admin Panel (Panel Administrativo)

• ProductAdminComponent: Container administrativo
• ProductListComponent: Lista administrativa de productos
• ProductFormComponent: Formulario crear/editar producto
• ProductImageManagerComponent: Gestión de imágenes
• CategoryManagerComponent: Gestión de categorías

4. Services & State

• ProductService: HTTP operations y business logic
• CategoryService: Gestión de categorías
• ProductState (NGXS): Estado global del módulo
• ProductFacade: API simplificada para componentes

División de Responsabilidades

ProductCatalogComponent

• Coordinación de filtros y resultados
• Gestión de estado de búsqueda
• Paginación y loading states

ProductService

• HTTP requests a API de productos
• Transformación de datos
• Cache de resultados de búsqueda

ProductState (NGXS)

• Estado centralizado de productos y categorías
• Estado de filtros activos
• Cache de búsquedas recientes

Contratos y Modelos

Entidades Principales

Product Entity

interface Product {
  id: string;
  sku: string;
  name: string;
  description: string;
  shortDescription?: string;
  price: number;
  salePrice?: number;
  currency: string;
  categoryIds: string[];
  images: ProductImage[];
  stock: number;
  status: ProductStatus;
  attributes: ProductAttribute[];
  createdAt: Date;
  updatedAt: Date;
  tenantId: string;
}

Category Entity

interface Category {
  id: string;
  name: string;
  slug: string;
  description?: string;
  parentId?: string;
  level: number;
  sortOrder: number;
  isActive: boolean;
  tenantId: string;
}

ProductImage Entity

interface ProductImage {
  id: string;
  url: string;
  alt: string;
  sortOrder: number;
  isPrimary: boolean;
}

API Endpoints

Products API

• GET /api/products - Lista paginada con filtros
  • Query params: page, limit, search, categoryId, minPrice, maxPrice, status
  • Response: { data: Product[], total: number, page: number }
• GET /api/products/{id} - Detalle de producto
  • Response: Product
• POST /api/products - Crear producto (admin)
  • Body: CreateProductDto
  • Response: Product
• PUT /api/products/{id} - Actualizar producto (admin)
  • Body: UpdateProductDto
  • Response: Product
• DELETE /api/products/{id} - Eliminar producto (admin)
  • Response: { success: boolean }

Categories API

• GET /api/categories - Árbol de categorías
  • Response: Category[]
• POST /api/categories - Crear categoría (admin)
• PUT /api/categories/{id} - Actualizar categoría (admin)
• DELETE /api/categories/{id} - Eliminar categoría (admin)

Event Contracts

Product Events

• product.viewed - { productId, userId, timestamp }
• product.searched - { query, filters, resultCount, userId }
• product.created - { productId, adminId, timestamp }
• product.updated - { productId, changes, adminId }
• product.deleted - { productId, adminId, timestamp }

Decisiones de Diseño

DEC-001: NGXS para State Management

Decisión: Usar NGXS como store centralizado para estado del catálogo Alternativa: Context API + Signals Justificación: Consistencia con arquitectura global, debugging tools, efectos para side effects Impacto: Mayor complejidad inicial, mejor escalabilidad a largo plazo

DEC-002: Paginación Server-Side

Decisión: Implementar paginación en el servidor con lazy loading Alternativa: Cargar todo el catálogo client-side Justificación: Mejor performance con catálogos grandes, menor uso de memoria Impacto: Mayor complejidad en manejo de estado, mejor UX

DEC-003: Filtros Combinados

Decisión: Permitir múltiples filtros simultáneos con query parameters Alternativa: Filtros mutuamente excluyentes Justificación: Mayor flexibilidad de búsqueda, mejor UX Impacto: Lógica más compleja, estado de filtros más rico

DEC-004: Gestión de Imágenes

Decisión: Upload a CDN con optimización automática Alternativa: Almacenamiento local con transformaciones manuales Justificación: Mejor performance, escalabilidad, menor carga en servidor Impacto: Dependencia externa, costo adicional

DEC-005: Categorías Jerárquicas

Decisión: Estructura de árbol con niveles ilimitados Alternativa: Categorías planas con tags Justificación: Mejor organización, navegación familiar para usuarios Impacto: Complejidad en UI de gestión, mejor organización lógica

Riesgos y Mitigaciones

R001: Performance con Catálogos Grandes

Riesgo: Lentitud en carga con +10k productos Mitigación: Paginación server-side, lazy loading, virtual scroll, cache inteligente Impacto: Alto - afecta UX directamente

R002: Gestión de Imágenes

Riesgo: CDN no disponible o costos excesivos Mitigación: Fallback a almacenamiento local, optimización automática, compresión Impacto: Medio - funcionalidad degradada pero disponible

R003: Sincronización de Inventario

Riesgo: Stock desactualizado entre sesiones Mitigación: WebSockets para updates en tiempo real, refresh periódico Impacto: Alto - afecta ventas y experiencia

Estrategia de Pruebas y Observabilidad

Testing Strategy

• Unit Tests: Services, State, Selectors (≥90% coverage)
• Integration Tests: Component + Service interactions
• E2E Tests: Flujos completos de navegación y administración
• Performance Tests: Carga con 1000+ productos, múltiples filtros

Observabilidad

• Métricas: Tiempo de carga, conversión vista→acción, búsquedas populares
• Logging: Errores de API, filtros aplicados, productos más vistos
• Events: Todas las interacciones de producto para analytics
• Monitoring: Performance de queries, cache hit ratio

Quality Gates

• Build sin errores TypeScript
• Tests unitarios ≥90% coverage
• E2E tests críticos pasan
• Performance <2s carga inicial, <500ms filtros
• Lighthouse score ≥90 en móvil

Permisos y Control de Acceso

Permisos Definidos

• product:read - Ver catálogo público y detalles de productos
• product:write - Crear y editar productos básicos
• product:delete - Eliminar productos
• category:read - Ver categorías
• category:write - Crear y editar categorías
• category:delete - Eliminar categorías

Mapeo de Permisos por Acción

Guards Aplicados por Ruta

// Rutas públicas
{ path: 'catalog', component: ProductCatalogComponent, canActivate: [authGuard] }
{ path: 'catalog/:id', component: ProductDetailComponent, canActivate: [authGuard] }

// Rutas administrativas
{
  path: 'admin/products',
  component: ProductAdminComponent,
  canActivate: [authGuard, permissionGuard],
  data: { permission: 'product:write' }
}
{
  path: 'admin/categories',
  component: CategoryManagerComponent,
  canActivate: [authGuard, permissionGuard],
  data: { permission: 'category:read' }
}

Directivas de Seguridad en Templates

// Botones administrativos
<button *hasPermission="'product:write'" (click)="createProduct()">Crear Producto</button>
<button *hasPermission="'product:write'" (click)="editProduct()">Editar</button>
<button *hasPermission="'product:delete'" (click)="deleteProduct()">Eliminar</button>

// Gestión de categorías
<button *hasPermission="'category:write'" (click)="createCategory()">Crear Categoría</button>
<button *hasPermission="'category:delete'" (click)="deleteCategory()">Eliminar Categoría</button>

// Secciones condicionales
<div *hasPermission="'category:read'">
  <app-category-manager></app-category-manager>
</div>

Mapeo de Cobertura