trading-platform/docs/02-definicion-modulos/OQI-009-marketplace/especificaciones/ET-MKT-003-frontend.md

ET-MKT-003: Especificación Frontend - Módulo Marketplace

Documento: ET-MKT-003-frontend.md Proyecto: Trading Platform - OQI-009-Marketplace Versión: 1.0.0 Estado: A IMPLEMENTAR Última Actualización: 2026-01-25

---

1. Descripción General

Este documento define la especificación de la capa frontend para el módulo Marketplace (OQI-009) del sistema Trading Platform. El módulo permite a usuarios explorar, comparar y adquirir productos financieros digitales (Signal Packs, sesiones de asesoramiento y complementos de visualización).

Nota Importante

Esta especificación describe un diseño a implementar. No existe código frontend actual para este módulo. Las páginas y componentes listados representan la propuesta de arquitectura que será desarrollada en futuras iteraciones.

Productos Soportados

• Signal Packs: Paquetes de señales de trading pre-configuradas
• Advisory Sessions: Sesiones de asesoramiento con expertos
• Visualization Addons: Complementos avanzados de visualización de mercados

---

2. Arquitectura Frontend

2.1 Stack Tecnológico

Framework:       React 18.x
Lenguaje:        TypeScript 5.x
Estilos:         Tailwind CSS + CSS Modules
Gestión Estado:  Redux Toolkit
HTTP Client:     Axios
Componentes UI:  Headless UI / Radix UI
Testing:         Jest + React Testing Library

2.2 Patrones Arquitectónicos

• Componentes Funcionales: Todos los componentes deben ser funcionales con hooks
• Estructura por Features: Organización en carpetas por feature (pages, components)
• Custom Hooks: Lógica reutilizable extraída en hooks personalizados
• Context API: Para estados compartidos entre componentes distantes
• Lazy Loading: Carga diferida de componentes con React.lazy()

---

3. Estructura de Directorios

src/
├── features/
│   └── marketplace/
│       ├── pages/
│       │   ├── MarketplacePage/
│       │   ├── ProductDetailPage/
│       │   ├── SignalPacksPage/
│       │   └── AdvisoryPage/
│       ├── components/
│       │   ├── ProductCard/
│       │   ├── SignalPackCard/
│       │   ├── AdvisorCard/
│       │   ├── BookingModal/
│       │   ├── FilterBar/
│       │   ├── ProductGallery/
│       │   └── ReviewSection/
│       ├── hooks/
│       │   ├── useMarketplaceFilters.ts
│       │   ├── useProductCart.ts
│       │   └── useAdvisorBooking.ts
│       ├── services/
│       │   ├── marketplaceApi.ts
│       │   ├── productApi.ts
│       │   └── advisoryApi.ts
│       ├── types/
│       │   └── marketplace.types.ts
│       ├── store/
│       │   └── marketplaceSlice.ts
│       └── styles/
│           └── marketplace.module.css

---

4. Páginas Propuestas

4.1 MarketplacePage

Ruta: /marketplace Responsabilidad: Landing principal del marketplace con vista general de todos los productos

Características:

• Hero section con introducción al marketplace
• Buscador global de productos
• Filtros por categoría (Signal Packs, Advisory, Addons)
• Grid de productos destacados
• Testimonios de usuarios
• Llamadas a la acción (CTA)

Responsive Design:

• Desktop: Grid 4 columnas
• Tablet: Grid 2 columnas
• Mobile: Grid 1 columna

---

4.2 ProductDetailPage

Ruta: /marketplace/product/:productId Responsabilidad: Vista detallada de un producto individual

Contenido Esperado:

• Galería de imágenes/screenshots
• Nombre, descripción y precio
• Especificaciones técnicas
• Comparativa con productos similares
• Sección de reviews y ratings
• Botón de compra/carrito
• Información del vendedor
• FAQ relacionadas

Datos a Cargar:

• Detalles del producto (API GET /api/products/:id)
• Reviews (API GET /api/products/:id/reviews)
• Productos relacionados (API GET /api/products/:id/related)

---

4.3 SignalPacksPage

Ruta: /marketplace/signal-packs Responsabilidad: Página especializada para Signal Packs con funcionalidades específicas

Características:

• Filtros avanzados (tipo de señal, precisión, timeframe)
• Comparador de paquetes
• Gráfico de performance histórico
• Tabla de estadísticas en tiempo real
• Demos interactivos
• Botón "Probar Gratis" y "Comprar Ahora"

Componentes Específicos:

• SignalPackCard (extendido)
• PerformanceChart
• ComparisonTable
• LiveStatisticsWidget

---

4.4 AdvisoryPage

Ruta: /marketplace/advisory Responsabilidad: Página para sesiones de asesoramiento con expertos

Características:

• Directorio de asesores con filtros
• Calendarios de disponibilidad
• Precios por tipo de sesión
• Credenciales y especialidades de asesores
• Sistema de booking integrado
• Historial de sesiones del usuario
• Funcionalidad de reseñas post-sesión

Integración Modal:

• Modal de booking (BookingModal) se dispara desde tarjetas de asesores
• Confirmación y pago dentro del modal

---

5. Componentes Propuestos

5.1 ProductCard

Ubicación: components/ProductCard/

interface ProductCardProps {
  product: Product;
  onViewDetails: (productId: string) => void;
  onAddToCart?: (product: Product) => void;
  variant?: 'default' | 'compact' | 'featured';
}

Elementos:

• Imagen de portada
• Nombre del producto
• Rating (estrellas + número de reviews)
• Precio y descuento (si aplica)
• Descripción breve (2-3 líneas)
• Etiquetas (categoría, trending)
• Botones de acción (Ver detalles, Agregar al carrito)

Estados:

• Default: Producto disponible
• Loading: Cargando datos
• Disabled: Producto no disponible
• Favorited: Producto agregado a favoritos

---

5.2 SignalPackCard

Ubicación: components/SignalPackCard/ Extends: ProductCard (con extensiones específicas)

interface SignalPackCardProps extends ProductCardProps {
  winRate: number;
  totalSignals: number;
  avgReturnPerSignal: number;
  lastSignalDate: Date;
  difficultyLevel: 'beginner' | 'intermediate' | 'advanced';
}

Elementos Adicionales:

• Badge de dificultad
• Win rate en porcentaje
• Total de señales generadas
• Retorno promedio por señal
• Fecha de última señal
• Gráfico mini de performance (sparkline)

---

5.3 AdvisorCard

Ubicación: components/AdvisorCard/

interface AdvisorCardProps {
  advisor: Advisor;
  onBookSession: (advisorId: string) => void;
}

Elementos:

• Foto de perfil
• Nombre y especialidad
• Rating y número de sesiones completadas
• Descripción breve
• Certificaciones y credenciales (badges)
• Precio por hora/sesión
• Disponibilidad (horarios)
• Botón "Reservar Ahora"
• Link a perfil completo

---

5.4 BookingModal

Ubicación: components/BookingModal/

interface BookingModalProps {
  advisor: Advisor;
  isOpen: boolean;
  onClose: () => void;
  onConfirm: (booking: BookingRequest) => Promise<void>;
}

Flujo:

1. Selección de Sesión: Tipo y duración
2. Calendario: Seleccionar fecha/hora disponible
3. Detalles Personales: Confirmar información del usuario
4. Resumen de Pago: Mostrar total y método de pago
5. Confirmación: Enviar reserva y mostrar confirmación

Validaciones:

• Fecha/hora no pueden ser pasadas
• Usuario debe estar autenticado
• Validar disponibilidad en tiempo real
• Procesar pago antes de confirmar

---

5.5 Componentes Auxiliares

FilterBar

Ubicación: components/FilterBar/ Responsabilidad: Filtros dinámicos reutilizables

interface FilterBarProps {
  filters: FilterDefinition[];
  onApply: (appliedFilters: Record<string, any>) => void;
  onReset: () => void;
}

ProductGallery

Ubicación: components/ProductGallery/ Responsabilidad: Galería de imágenes con zoom y thumbnails

ReviewSection

Ubicación: components/ReviewSection/ Responsabilidad: Mostrar y permitir crear nuevas reseñas

---

6. Flujos de Usuario Principales

6.1 Flujo: Explorar y Comprar Signal Pack

MarketplacePage
  → (filtrar/buscar)
  → SignalPacksPage
  → ProductDetailPage (Signal Pack)
  → Carrito
  → Checkout

6.2 Flujo: Reservar Sesión de Asesoramiento

MarketplacePage
  → AdvisoryPage
  → (filtrar asesores)
  → AdvisorCard
  → BookingModal (se abre)
  → Confirmación y Pago
  → Página de confirmación

6.3 Flujo: Ver Detalles de Complemento

MarketplacePage
  → ProductDetailPage (Addon)
  → Comparar con similares
  → Agregar al carrito
  → Checkout

---

7. Integración con API

7.1 Endpoints Consumidos

GET    /api/marketplace/products           # Listar productos con filtros
GET    /api/marketplace/products/:id       # Detalle de producto
GET    /api/marketplace/products/:id/reviews
POST   /api/marketplace/cart               # Agregar al carrito
GET    /api/marketplace/advisors           # Listar asesores
POST   /api/marketplace/bookings           # Crear booking
GET    /api/user/orders                    # Historial de compras

7.2 Servicios API (Custom Hooks)

// marketplaceApi.ts
export const marketplaceApi = {
  getProducts: (filters?: ProductFilters) => Promise<Product[]>,
  getProductDetail: (id: string) => Promise<Product>,
  getAdvisors: (filters?: AdvisorFilters) => Promise<Advisor[]>,
  createBooking: (booking: BookingRequest) => Promise<BookingResponse>,
  getReviews: (productId: string) => Promise<Review[]>,
  submitReview: (review: ReviewSubmission) => Promise<Review>,
}

---

8. Estado Global (Redux)

8.1 Slices del Store

// marketplaceSlice.ts
{
  marketplace: {
    products: Product[],
    selectedProduct: Product | null,
    advisors: Advisor[],
    cart: CartItem[],
    filters: {
      category: string[],
      priceRange: [number, number],
      rating: number,
      // ... más filtros
    },
    loading: boolean,
    error: string | null,
  }
}

8.2 Actions Principales

• setProducts(products)
• setSelectedProduct(product)
• addToCart(product)
• removeFromCart(productId)
• updateFilters(filters)
• setLoading(boolean)

---

9. Validaciones Frontend

9.1 Búsqueda y Filtros

• Campo de búsqueda: mínimo 3 caracteres
• Filtros deben reflejar datos del backend
• Debounce en búsqueda (300ms)

9.2 Booking de Sesiones

• Fecha no puede ser en el pasado
• Hora debe coincidir con disponibilidad del asesor
• Usuario debe estar autenticado
• Validar saldo/método de pago

9.3 Carrito

• Validar cantidad disponible
• Evitar agregar mismo producto dos veces (aumentar cantidad)
• Mostrar total actualizado

9.4 Formularios

• Validación en tiempo real
• Mensajes de error claros
• Estados loading en botones de envío

---

10. Performance y Optimización

10.1 Técnicas

• Code Splitting: Lazy loading de páginas con React.lazy()
• Memoization: React.memo() para componentes puros
• Image Optimization: Optimizar imágenes, WebP, lazy loading
• Virtualization: Virtualizaciónlist para listas largas (si aplica)
• Bundle Analysis: Usar webpack-bundle-analyzer

10.2 Métricas Objetivo

• LCP (Largest Contentful Paint): < 2.5s
• FID (First Input Delay): < 100ms
• CLS (Cumulative Layout Shift): < 0.1

---

11. Accesibilidad (A11y)

11.1 Estándares

• WCAG 2.1 Nivel AA
• Navegación por teclado
• Contraste mínimo 4.5:1
• Labels explícitos en formularios
• ARIA labels donde sea necesario

11.2 Implementación

// Ejemplo: Botón accesible
<button
  aria-label="Agregar producto al carrito"
  className="btn-primary"
  onClick={handleAddToCart}
>
  Agregar al Carrito
</button>

---

12. Testing

12.1 Cobertura Objetivo

• Unit Tests: 80% de componentes
• Integration Tests: Flujos principales
• E2E Tests: Casos de compra y booking

12.2 Ejemplos de Pruebas

// ProductCard.test.tsx
describe('ProductCard', () => {
  it('should render product information', () => {
    const product = mockProduct();
    render(<ProductCard product={product} onViewDetails={jest.fn()} />);
    expect(screen.getByText(product.name)).toBeInTheDocument();
  });

  it('should call onViewDetails when clicked', () => {
    const onViewDetails = jest.fn();
    const product = mockProduct();
    render(<ProductCard product={product} onViewDetails={onViewDetails} />);
    fireEvent.click(screen.getByRole('button', { name: /ver detalles/i }));
    expect(onViewDetails).toHaveBeenCalledWith(product.id);
  });
});

---

13. Tipo de Datos Principales

13.1 Interfaces TypeScript

// marketplace.types.ts

interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  discount?: number;
  category: 'signal_pack' | 'advisory' | 'addon';
  rating: number;
  reviewCount: number;
  image: string;
  images?: string[];
  createdAt: Date;
  updatedAt: Date;
}

interface SignalPack extends Product {
  winRate: number;
  totalSignals: number;
  avgReturnPerSignal: number;
  difficultyLevel: 'beginner' | 'intermediate' | 'advanced';
  lastSignalDate: Date;
}

interface Advisor {
  id: string;
  name: string;
  email: string;
  photo: string;
  specialty: string;
  bio: string;
  rating: number;
  completedSessions: number;
  pricePerHour: number;
  certifications: Certification[];
  availability: TimeSlot[];
}

interface BookingRequest {
  advisorId: string;
  userId: string;
  sessionType: 'consultation' | 'strategy_review';
  duration: 30 | 60 | 90; // minutos
  scheduledDate: Date;
  notes?: string;
}

interface Review {
  id: string;
  productId: string;
  userId: string;
  rating: number;
  title: string;
  comment: string;
  createdAt: Date;
}

---

14. Responsive Design Breakpoints

/* Tailwind / CSS */
Mobile:    < 640px   (sm)
Tablet:    640px+    (md)
Desktop:   1024px+   (lg)
Wide:      1280px+   (xl)
UltraWide: 1536px+   (2xl)

---

15. Roadmap de Implementación

Fase 1: Estructura Base (Sprint 1-2)

• Setup proyecto React + TypeScript
• Crear estructura de directorios
• Implementar routing y layout base
• Configurar Redux store

Fase 2: Componentes (Sprint 3-4)

• ProductCard, SignalPackCard, AdvisorCard
• FilterBar, ProductGallery
• BookingModal

Fase 3: Páginas (Sprint 5-6)

• MarketplacePage
• ProductDetailPage
• SignalPacksPage
• AdvisoryPage

Fase 4: Integraciones y Polish (Sprint 7-8)

• Consumir APIs
• Testing
• Optimización
• Despliegue

---

16. Referencias y Documentos Relacionados

• ET-MKT-001-database.md: Esquema de base de datos
• ET-MKT-002-api.md: Especificación de API REST
• Guía de Componentes: (a crear en futuro)
• Guía de Testing: (a crear en futuro)

---

17. Notas de Desarrollo

Prácticas Recomendadas

1. Mantener componentes pequeños y enfocados
2. Usar TypeScript para toda la capa frontend
3. Escribir tests mientras se desarrolla
4. Revisar código antes de merge
5. Documentar componentes complejos

Dependencias NPM Esperadas

{
  "react": "^18.2.0",
  "react-dom": "^18.2.0",
  "@reduxjs/toolkit": "^1.9.x",
  "react-redux": "^8.1.x",
  "axios": "^1.4.x",
  "tailwindcss": "^3.3.x",
  "typescript": "^5.1.x"
}

---

18. Cambios Pendientes

Este documento será actualizado cuando:

• Se inicie implementación de componentes
• Se definan cambios en UX/UI
• Se agreguen nuevas funcionalidades
• Se identifiquen patrones de optimización

---

Documento Generado: 2026-01-25 Próxima Revisión: Tras completar Fase 1 de implementación Estado: BORRADOR - A IMPLEMENTAR