# US-PAY-010: Ver Historial de Pagos y Transacciones

**Version:** 1.0.0
**Fecha:** 2025-12-05
**Estado:** ✅ Implementado
**Story Points:** 2
**Prioridad:** P1 (Alta)
**Épica:** [OQI-005](../_MAP.md)

---

## Historia de Usuario

**Como** usuario de OrbiQuant con actividad de pagos
**Quiero** ver un historial completo de mis transacciones
**Para** rastrear mis gastos, recargas de wallet y compras realizadas

---

## Criterios de Aceptación

### AC-001: Acceder a Historial de Pagos

**Dado** que soy usuario logueado
**Cuando** navego a "Configuración → Historial de Pagos"
**Entonces** debería ver:
- Lista de todas mis transacciones ordenadas por fecha (más reciente primero)
- Para cada transacción:
  - Fecha y hora
  - Tipo (Suscripción, Curso, Recarga de Wallet, Reembolso)
  - Descripción detallada
  - Monto con signo (+ para créditos, - para débitos)
  - Estado (Exitoso, Fallido, Pendiente, Reembolsado)
  - Método de pago usado
  - Link a factura (si aplica)
- Paginación si tengo > 20 transacciones

### AC-002: Ver Sin Transacciones

**Dado** que soy usuario nuevo sin actividad de pagos
**Cuando** navego al historial de pagos
**Entonces** debería ver:
- Mensaje: "No tienes transacciones todavía"
- Ilustración o ícono de historial vacío
- Botón "Explorar Cursos" o "Ver Planes"

### AC-003: Tipos de Transacciones Mostradas

**Dado** que estoy viendo mi historial
**Cuando** reviso las transacciones
**Entonces** debería ver claramente diferenciados:

**Suscripciones:**
- ícono 🔄
- "Pago de suscripción Pro - Diciembre 2025"
- Monto: -$49.00
- Estado: Exitoso

**Cursos:**
- ícono 📚
- "Compra de curso: Trading Básico 101"
- Monto: -$29.00
- Estado: Exitoso

**Recarga de Wallet:**
- ícono 💰
- "Recarga de wallet"
- Monto: +$50.00
- Estado: Exitoso

**Reembolsos:**
- ícono ↩️
- "Reembolso: Curso Trading Avanzado"
- Monto: +$49.00
- Estado: Reembolsado

**Débitos de Wallet:**
- ícono 📤
- "Pago con wallet: Curso React Avanzado"
- Monto: -$29.00
- Estado: Exitoso

### AC-004: Filtrar por Tipo

**Dado** que tengo múltiples tipos de transacciones
**Cuando** aplico filtro de tipo
**Entonces** debería poder filtrar por:
- Todos (por defecto)
- Suscripciones
- Cursos
- Wallet (recargas y débitos)
- Reembolsos
- Solo exitosos
- Solo fallidos

### AC-005: Filtrar por Fecha

**Dado** que quiero ver transacciones de un período específico
**Cuando** selecciono rango de fechas
**Entonces** debería:
- Ver selector de fecha (desde - hasta)
- Opciones rápidas: "Último mes", "Últimos 3 meses", "Este año", "Todo"
- Actualizar lista con transacciones del rango seleccionado

### AC-006: Ver Detalles de Transacción

**Dado** que quiero ver más información de una transacción
**Cuando** hago click en una transacción
**Entonces** debería ver modal/expandir con:
- Todos los detalles de la transacción
- ID de transacción (Stripe Payment Intent ID)
- Método de pago (Visa •••• 4242, Wallet, etc.)
- Fecha y hora exacta
- Estado detallado
- Link a factura (si existe)
- Link a recurso comprado (curso, suscripción)
- Botón "Solicitar Reembolso" (si es elegible)

### AC-007: Transacciones Fallidas

**Dado** que tengo transacciones fallidas
**Cuando** las veo en el historial
**Entonces** debería:
- Ver badge rojo "Fallido"
- Ver motivo del fallo: "Tarjeta rechazada", "Fondos insuficientes", etc.
- Ver botón "Reintentar" (si aplica)
- NO ver factura ni acceso a recurso

### AC-008: Exportar Historial

**Dado** que quiero guardar mi historial para registros
**Cuando** hago click en "Exportar"
**Entonces** debería:
- Ver opciones: CSV, PDF
- Seleccionar rango de fechas
- Descargar archivo con formato:
  - CSV: Fecha, Tipo, Descripción, Monto, Estado, Método
  - PDF: Documento formateado con logo y tabla

### AC-009: Balance Actual de Wallet

**Dado** que tengo wallet con saldo
**Cuando** veo el historial de pagos
**Entonces** debería ver:
- Card destacado en la parte superior:
  - "Balance de Wallet: $50.00"
  - Botón "Recargar"
  - Link "Ver transacciones de wallet"
- Historial de transacciones de wallet integrado en lista general

### AC-010: Buscar Transacción

**Dado** que estoy buscando una transacción específica
**Cuando** uso el buscador
**Entonces** debería poder buscar por:
- Descripción (nombre de curso, tipo de pago)
- Monto (ej: "49" muestra todos de $49)
- ID de transacción
- Resultados se filtran en tiempo real

### AC-011: Solicitar Reembolso desde Historial

**Dado** que veo una compra elegible para reembolso
**Cuando** hago click en "Solicitar Reembolso"
**Entonces** debería:
- Ver formulario de solicitud con:
  - Motivo (lista predefinida)
  - Comentarios adicionales (opcional)
- Enviar solicitud
- Ver confirmación: "Solicitud de reembolso enviada"
- Ver estado actualizado: "Reembolso Pendiente"

---

## Mockup

```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│                  Historial de Pagos                         │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  💰 Balance de Wallet: $50.00                       │   │
│  │  [Recargar]  [Ver transacciones de wallet]         │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Filtros:  [Todos ▼]  [Último mes ▼]  [Buscar...]          │
│                                                [Exportar]   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 🔄  Pago de suscripción Pro - Diciembre 2025        │   │
│  │     05/12/2025 14:30                    [Exitoso]   │   │
│  │     Visa •••• 4242                                  │   │
│  │                                          -$49.00    │   │
│  │     [Ver Factura]  [Ver Detalles]                  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 💰  Recarga de wallet                               │   │
│  │     01/12/2025 10:15                    [Exitoso]   │   │
│  │     Visa •••• 4242                                  │   │
│  │                                          +$50.00    │   │
│  │     [Ver Factura]  [Ver Detalles]                  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 📚  Compra de curso: Trading Básico 101             │   │
│  │     28/11/2025 16:45                    [Exitoso]   │   │
│  │     Wallet                                          │   │
│  │                                          -$29.00    │   │
│  │     [Ver Factura]  [Ir al Curso]  [Solicitar       │   │
│  │                                    Reembolso]       │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ ❌  Pago de suscripción Pro - Noviembre 2025        │   │
│  │     05/11/2025 14:30                    [Fallido]   │   │
│  │     Visa •••• 5555                                  │   │
│  │     Motivo: Tarjeta rechazada           -$49.00    │   │
│  │     [Reintentar]  [Actualizar Tarjeta]             │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ ↩️  Reembolso: Curso Trading Avanzado               │   │
│  │     15/10/2025 09:20                 [Reembolsado]  │   │
│  │     Visa •••• 4242                                  │   │
│  │                                          +$49.00    │   │
│  │     [Ver Nota de Crédito]                          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Mostrando 1-10 de 47 transacciones                         │
│  [← Anterior]  [1] [2] [3] [4] [5]  [Siguiente →]          │
│                                                             │
└─────────────────────────────────────────────────────────────┘


───────────── Modal: Detalles de Transacción ─────────────

┌─────────────────────────────────────────────────────────────┐
│                                                      [X]    │
│              Detalles de Transacción                        │
│                                                             │
│  Tipo: Compra de Curso                                      │
│  Descripción: Trading Básico 101                            │
│  Fecha: 28/11/2025 16:45:23                                 │
│                                                             │
│  ───────────────────────────────────────────────────        │
│                                                             │
│  Monto: $29.00 USD                                          │
│  Método de pago: Wallet                                     │
│  Estado: Exitoso ✅                                         │
│                                                             │
│  ───────────────────────────────────────────────────        │
│                                                             │
│  ID de transacción:                                         │
│  wt_3Abc123def456ghi789                                     │
│                                                             │
│  ───────────────────────────────────────────────────        │
│                                                             │
│  [Ver Factura]  [Ir al Curso]  [Solicitar Reembolso]      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Flujo de Usuario (Gherkin)

```gherkin
Feature: Ver Historial de Pagos

  Scenario: Ver historial completo
    Given que soy usuario logueado "juan@example.com"
    And he realizado 5 transacciones en el último mes
    When navego a "Configuración → Historial de Pagos"
    Then debería ver 5 transacciones listadas
    And deberían estar ordenadas por fecha descendente
    And debería ver mi balance de wallet en la parte superior

  Scenario: Filtrar por tipo de transacción
    Given que estoy viendo mi historial de pagos
    And tengo transacciones de suscripciones y cursos
    When selecciono filtro "Cursos"
    Then debería ver solo transacciones de compra de cursos
    And NO debería ver transacciones de suscripciones

  Scenario: Ver detalles de transacción exitosa
    Given que estoy viendo mi historial
    When hago click en transacción "Curso Trading Básico 101"
    Then debería ver modal con detalles completos
    And debería ver ID de transacción
    And debería ver método de pago usado
    And debería ver botón "Ver Factura"
    And debería ver botón "Ir al Curso"

  Scenario: Solicitar reembolso desde historial
    Given que compré curso hace 3 días con 0% de progreso
    When veo esa transacción en el historial
    And hago click en "Solicitar Reembolso"
    Then debería ver formulario de solicitud
    When selecciono motivo "No es lo que esperaba"
    And confirmo solicitud
    Then debería ver "Solicitud de reembolso enviada"
    And estado debería cambiar a "Reembolso Pendiente"

  Scenario: Exportar historial a CSV
    Given que tengo 20 transacciones
    When hago click en "Exportar"
    And selecciono "CSV"
    And selecciono "Últimos 3 meses"
    Then debería descargar archivo "OrbiQuant_Historial_2025.csv"
    And archivo debería contener todas las transacciones del período

  Scenario: Usuario sin transacciones
    Given que soy usuario nuevo sin actividad
    When navego a "Historial de Pagos"
    Then debería ver "No tienes transacciones todavía"
    And debería ver botón "Explorar Cursos"
```

---

## Notas Técnicas

### Frontend

- Componente: `apps/frontend/src/pages/Settings/PaymentHistory.tsx`
- Modal: `TransactionDetailsModal.tsx`
- Fetch: `GET /api/v1/payments/history`
- Integrar con wallet balance: `GET /api/v1/wallet/balance`

### Backend

**Endpoint Principal:**

`GET /api/v1/payments/history`

Query params:
- `?type=subscription|course|wallet|refund`
- `?status=succeeded|failed|refunded`
- `?from=2025-01-01&to=2025-12-31`
- `?search=trading`
- `?page=1&limit=20`

Response:
```json
{
  "transactions": [
    {
      "id": "uuid",
      "type": "subscription",
      "description": "Pago de suscripción Pro - Diciembre 2025",
      "amount": -49.00,
      "currency": "USD",
      "status": "succeeded",
      "paymentMethod": {
        "type": "card",
        "brand": "visa",
        "last4": "4242"
      },
      "invoiceId": "uuid-factura",
      "resourceId": "uuid-subscription",
      "resourceType": "subscription",
      "refundable": false,
      "createdAt": "2025-12-05T14:30:00Z"
    }
  ],
  "walletBalance": 50.00,
  "total": 47,
  "page": 1,
  "perPage": 20
}
```

**Endpoint de Exportación:**

`GET /api/v1/payments/history/export`

Query params:
- `?format=csv|pdf`
- `?from=2025-01-01&to=2025-12-31`

Response: Stream archivo CSV/PDF

### Database

**Query combina múltiples tablas:**
```sql
SELECT
  'payment' as source,
  p.id,
  p.type,
  p.description,
  p.amount * -1 as amount, -- Débito
  p.status,
  p.created_at
FROM billing.payments p
WHERE p.user_id = :userId

UNION ALL

SELECT
  'wallet_transaction' as source,
  wt.id,
  wt.type,
  wt.description,
  wt.amount, -- Puede ser + o -
  'succeeded' as status,
  wt.created_at
FROM billing.wallet_transactions wt
WHERE wt.wallet_id = (SELECT id FROM billing.wallets WHERE user_id = :userId)

UNION ALL

SELECT
  'refund' as source,
  r.id,
  'refund' as type,
  'Reembolso: ' || p.description,
  r.amount as amount, -- Positivo
  r.status,
  r.created_at
FROM billing.refunds r
JOIN billing.payments p ON r.payment_id = p.id
WHERE r.user_id = :userId

ORDER BY created_at DESC
```

### Exportación CSV

```csv
Fecha,Tipo,Descripción,Monto,Estado,Método
2025-12-05 14:30,Suscripción,Pago de suscripción Pro - Diciembre 2025,-$49.00,Exitoso,Visa 4242
2025-12-01 10:15,Recarga Wallet,Recarga de wallet,+$50.00,Exitoso,Visa 4242
2025-11-28 16:45,Curso,Compra: Trading Básico 101,-$29.00,Exitoso,Wallet
```

---

## Dependencias

- [RF-PAY-003: Sistema de Wallet](../requerimientos/RF-PAY-003-wallet.md)
- [RF-PAY-006: Sistema de Reembolsos](../requerimientos/RF-PAY-006-reembolsos.md)

---

## Requerimientos Relacionados

- [RF-PAY-003: Sistema de Wallet Interno](../requerimientos/RF-PAY-003-wallet.md)
- [RF-PAY-004: Sistema de Facturación](../requerimientos/RF-PAY-004-facturacion.md)
- [RF-PAY-006: Sistema de Reembolsos](../requerimientos/RF-PAY-006-reembolsos.md)

---

## Tareas Técnicas

### Frontend
- [ ] Página `PaymentHistory.tsx`
- [ ] Modal `TransactionDetailsModal.tsx`
- [ ] Wallet balance card
- [ ] Filtros (tipo, fecha, búsqueda)
- [ ] Exportación (CSV/PDF)
- [ ] Paginación
- [ ] Indicador de reembolsabilidad

### Backend
- [ ] Endpoint `GET /payments/history`
- [ ] Combinar datos de payments + wallet_transactions + refunds
- [ ] Implementar filtros y búsqueda
- [ ] Endpoint `GET /payments/history/export`
- [ ] Generar CSV/PDF
- [ ] Optimizar query para performance

### Testing
- [ ] Test: Usuario ve todas sus transacciones
- [ ] Test: Filtros funcionan correctamente
- [ ] Test: Búsqueda encuentra transacciones
- [ ] Test: Exportación CSV genera archivo correcto
- [ ] Test: Paginación funciona
- [ ] Test: Balance de wallet se muestra correctamente
- [ ] Test: No puede ver transacciones de otros usuarios
