# 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/`

```typescript
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)

```typescript
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/`

```typescript
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/`

```typescript
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

```typescript
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)
```typescript
// 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
```typescript
// 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
```typescript
// 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
```typescript
// 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

```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

```css
/* 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
```json
{
  "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