# OQI-005: Análisis de Componentes - Frontend Pagos

**Módulo:** OQI-005 (pagos-stripe)
**Fecha:** 2026-01-25
**Cobertura:** 14 componentes + 4 páginas + 1 servicio + types

---

## Tabla de Componentes (14 total)

| # | Componente | Ruta | Tipo | Estado | Funcionalidad Principal |
|---|-----------|------|------|--------|------------------------|
| 1 | **PricingCard** | `/components/payments/PricingCard.tsx` | Presentación | ✅ Activo | Visualiza plan individual con características y CTA |
| 2 | **SubscriptionCard** | `/components/payments/SubscriptionCard.tsx` | Estado/Gestión | ✅ Activo | Muestra suscripción actual con acciones (cambiar/cancelar) |
| 3 | **SubscriptionUpgradeFlow** | `/components/payments/SubscriptionUpgradeFlow.tsx` | Modal/Flujo | ✅ Activo | Flujo 3-pasos: seleccionar → previsualizar → confirmar cambio plan |
| 4 | **PaymentMethodForm** | `/components/payments/PaymentMethodForm.tsx` | Formulario | ✅ Activo | Agregar tarjeta de crédito (manual, sin Stripe.js) |
| 5 | **PaymentMethodsList** | `/components/payments/PaymentMethodsList.tsx` | Lista/Gestión | ✅ Activo | Listar, seleccionar, eliminar métodos de pago |
| 6 | **WalletCard** | `/components/payments/WalletCard.tsx` | Presentación | ✅ Activo | Saldo disponible, depósitos/retiros, transacciones recientes (top 5) |
| 7 | **WalletDepositModal** | `/components/payments/WalletDepositModal.tsx` | Modal | ✅ Activo | Depositar dinero: monto preestablecido + método de pago |
| 8 | **WalletWithdrawModal** | `/components/payments/WalletWithdrawModal.tsx` | Modal | ✅ Activo | Retirar dinero: validación saldo, comisión 1%, cuenta bancaria |
| 9 | **InvoiceList** | `/components/payments/InvoiceList.tsx` | Tabla/Paginación | ✅ Activo | Historial facturas: busca, filtra, descarga, paginado |
| 10 | **TransactionHistory** | `/components/payments/TransactionHistory.tsx` | Tabla/Paginación | ✅ Activo | Historial transacciones wallet: filtro tipo, exporta CSV |
| 11 | **BillingInfoForm** | `/components/payments/BillingInfoForm.tsx` | Formulario | ✅ Activo | Editar información facturación: dirección, impuestos |
| 12 | **CouponForm** | `/components/payments/CouponForm.tsx` | Formulario | ✅ Activo | Validar y aplicar códigos de descuento |
| 13 | **InvoiceDetail** | `/components/payments/InvoiceDetail.tsx` | Modal | ✅ Activo | Detalle factura: items, totales, impuestos, descarga PDF |
| 14 | **UsageProgress** | `/components/payments/UsageProgress.tsx` | Barra de Progreso | ✅ Activo | Mostrar límites de plan: API calls, paper trades, cursos, watchlist |

---

## Tabla de Páginas (4 total)

| # | Página | Ruta | Funcionalidad |
|---|--------|------|--------------|
| 1 | **Pricing** | `/modules/payments/pages/Pricing.tsx` | Grid planes con toggle mensual/anual, tabla comparativa, FAQ |
| 2 | **Billing** | `/modules/payments/pages/Billing.tsx` | Dashboard con 4 tabs: resumen, métodos pago, facturas, wallet |
| 3 | **CheckoutSuccess** | `/modules/payments/pages/CheckoutSuccess.tsx` | Confirmación pago exitoso con detalles suscripción |
| 4 | **CheckoutCancel** | `/modules/payments/pages/CheckoutCancel.tsx` | Cancelación checkout con motivos y opciones alternativas |

---

## Servicios (1)

| Servicio | Métodos | Descripción |
|----------|---------|-------------|
| **payment.service.ts** | 26+ métodos | API client para todos los endpoints de pagos |

---

## Estructura de Carpetas

```
apps/frontend/src/
├── components/payments/               (12 componentes)
│   ├── PricingCard.tsx
│   ├── SubscriptionCard.tsx
│   ├── SubscriptionUpgradeFlow.tsx
│   ├── PaymentMethodForm.tsx
│   ├── PaymentMethodsList.tsx
│   ├── WalletCard.tsx
│   ├── WalletDepositModal.tsx
│   ├── WalletWithdrawModal.tsx
│   ├── InvoiceList.tsx
│   ├── TransactionHistory.tsx
│   ├── BillingInfoForm.tsx
│   ├── CouponForm.tsx
│   ├── InvoiceDetail.tsx
│   ├── UsageProgress.tsx
│   └── index.ts                      (exports)
├── modules/payments/pages/            (4 páginas)
│   ├── Pricing.tsx
│   ├── Billing.tsx
│   ├── CheckoutSuccess.tsx
│   └── CheckoutCancel.tsx
├── modules/payments/
│   └── index.ts
├── services/
│   └── payment.service.ts
├── stores/
│   └── paymentStore.ts               (Zustand state)
└── types/
    └── payment.types.ts              (30+ tipos)
```

---

## Matriz de Dependencias

```
Pricing Page
  ├── usePaymentStore (fetchPlans, fetchCurrentSubscription, createCheckoutSession)
  └── PricingCard (12x)
       └── payment.service (indirecto)

Billing Page
  ├── usePaymentStore (11 métodos)
  ├── SubscriptionCard
  ├── UsageProgress
  ├── WalletCard
  ├── WalletDepositModal
  └── WalletWithdrawModal

PricingCard / SubscriptionCard / UsageProgress
  └── payment.types (interfaces)

SubscriptionUpgradeFlow
  └── payment.service (previewSubscriptionChange, changeSubscriptionPlan)

PaymentMethodForm / PaymentMethodsList
  └── payment.service (add, remove, setDefault)

WalletCard / WalletDepositModal / WalletWithdrawModal
  └── payment.service (depositToWallet, withdrawFromWallet, getWallet)

InvoiceList / InvoiceDetail
  └── payment.service (getInvoices, getInvoiceById, downloadInvoice)

TransactionHistory
  └── payment.service (getWalletTransactions)

BillingInfoForm
  └── payment.service (getBillingInfo, updateBillingInfo)

CouponForm
  └── payment.service (validateCoupon)
```

---

## Clasificación por Funcionalidad

### Planes & Suscripción (5 componentes)
- `PricingCard` - Visualización plan
- `SubscriptionCard` - Estado suscripción
- `SubscriptionUpgradeFlow` - Cambio de plan
- `UsageProgress` - Límites de plan
- `Pricing` (página) - Grid planes

### Pagos & Métodos (3 componentes)
- `PaymentMethodForm` - Agregar tarjeta
- `PaymentMethodsList` - Gestionar tarjetas
- `BillingInfoForm` - Información facturación

### Wallet (3 componentes)
- `WalletCard` - Saldo y transacciones recientes
- `WalletDepositModal` - Depositar fondos
- `WalletWithdrawModal` - Retirar fondos

### Facturas & Historial (3 componentes)
- `InvoiceList` - Tabla facturas
- `InvoiceDetail` - Detalle factura modal
- `TransactionHistory` - Historial transacciones

### Descuentos (1 componente)
- `CouponForm` - Validar cupones

### Dashboard & Flujos (2 páginas)
- `Billing` (página) - Dashboard general
- `CheckoutSuccess` / `CheckoutCancel` (páginas) - Estados checkout

---

## Resumen Estadísticas

- **Componentes presentación:** 8 (PricingCard, SubscriptionCard, WalletCard, UsageProgress, InvoiceDetail, TransactionHistory)
- **Componentes formularios:** 4 (PaymentMethodForm, BillingInfoForm, CouponForm, + SubscriptionUpgradeFlow)
- **Componentes modales:** 3 (SubscriptionUpgradeFlow, WalletDepositModal, WalletWithdrawModal, InvoiceDetail)
- **Componentes listas:** 3 (PaymentMethodsList, InvoiceList, TransactionHistory)
- **Páginas:** 4 (Pricing, Billing, CheckoutSuccess, CheckoutCancel)
- **Métodos de servicio:** 26+ en payment.service.ts

---

## Notas Técnicas

### Tecnologías Usadas
- **UI:** Tailwind CSS (dark mode)
- **Iconos:** lucide-react
- **Estado:** Zustand (paymentStore)
- **API Client:** axios
- **Router:** react-router-dom
- **Tablas:** HTML nativa (InvoiceList, TransactionHistory)
- **Paginación:** Manual con state (currentPage)
- **Formularios:** HTML nativo (sin react-hook-form)

### Características
- Validación de formularios en cliente
- Manejo de estados de carga (loading, error, success)
- Modales superpuestos con z-50
- Exportación a CSV (TransactionHistory)
- Descarga PDF (InvoiceDetail, InvoiceList)
- Responsive design (grid responsivo)
- Internacionalización: español/inglés mezclado

### Patrones
- Props drilling en Billing page (11 props pasadas)
- Hooks: useState, useEffect, useMemo
- Callbacks onSuccess/onError
- Conditional rendering (step-based flows)
- Maps para listas (plans, methods, invoices)

