# US-INV-007: Ver Historial de Transacciones

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | US-INV-007 |
| **Épica** | OQI-004 - Cuentas de Inversión |
| **Módulo** | investment |
| **Prioridad** | P1 |
| **Story Points** | 3 |
| **Sprint** | Sprint 6 |
| **Estado** | Pendiente |
| **Asignado a** | Por asignar |

---

## Historia de Usuario

**Como** inversor,
**quiero** ver el historial completo de transacciones de mi cuenta,
**para** auditar movimientos, reconciliar mi balance y tener trazabilidad completa.

## Descripción Detallada

El usuario debe poder acceder a un historial completo de todas las transacciones de su cuenta: depósitos, retiros, ganancias/pérdidas de trades, distribuciones de utilidades, y comisiones. Debe poder filtrar por tipo, fecha, y exportar los datos.

## Mockups/Wireframes

```
┌─────────────────────────────────────────────────────────────────┐
│                    HISTORIAL DE TRANSACCIONES                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Filtros:                                                        │
│  Tipo: [Todas ▼] Período: [Último mes ▼] [Buscar]              │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ Fecha       │ Tipo              │ Descripción  │ Monto    │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │ 2025-12-05  │ 💰 Depósito       │ Stripe       │ +$1,000  │  │
│  │ 10:30 AM    │                   │              │          │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │ 2025-12-04  │ 📈 Ganancia Trade │ BTC/USDT     │ +$45.20  │  │
│  │ 03:15 PM    │                   │ Long         │          │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │ 2025-12-04  │ 📉 Pérdida Trade  │ ETH/USDT     │ -$12.30  │  │
│  │ 11:20 AM    │                   │ Long         │          │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │ 2025-12-03  │ 📊 Distribución   │ Utilidades   │ +$32.10  │  │
│  │ 12:00 PM    │                   │ Mensual      │          │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │ 2025-12-02  │ 💸 Retiro         │ Stripe       │ -$500.00 │  │
│  │ 09:00 AM    │                   │ Completado   │          │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │ 2025-12-01  │ 💰 Depósito       │ Stripe       │ +$200.00 │  │
│  │ 02:45 PM    │                   │              │          │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  Mostrando 6 de 156 transacciones                               │
│  [← Anterior]  Página 1 de 26  [Siguiente →]                    │
│                                                                  │
│  [Exportar CSV] [Exportar PDF]                                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Ver historial completo**
```gherkin
DADO que el usuario tiene cuenta con 156 transacciones
CUANDO navega a /investment/transactions/:accountId
ENTONCES se muestra lista paginada (10 por página)
Y cada transacción muestra: fecha, hora, tipo, descripción, monto
Y las transacciones están ordenadas por fecha desc (más recientes primero)
Y se muestra navegación de paginación
```

**Escenario 2: Filtrar por tipo de transacción**
```gherkin
DADO que el usuario está viendo el historial
CUANDO selecciona filtro "Tipo: Depósitos"
ENTONCES se muestran solo transacciones de tipo "deposit"
Y se actualiza contador "Mostrando X de Y"
Y se resetea paginación a página 1
```

**Escenario 3: Filtrar por período**
```gherkin
DADO que el usuario está viendo el historial
CUANDO selecciona "Período: Último mes"
ENTONCES se muestran solo transacciones de últimos 30 días
Y se actualiza la lista
```

**Escenario 4: Ver detalle de transacción**
```gherkin
DADO que el usuario está viendo el historial
CUANDO hace click en una transacción
ENTONCES se abre modal/drawer con detalle completo
Y muestra: ID transacción, timestamp exacto, monto bruto, comisiones, monto neto
Y para trades: par, dirección, precio entrada, precio salida, P&L
Y para Stripe: payment intent ID, método de pago
```

**Escenario 5: Exportar historial**
```gherkin
DADO que el usuario tiene filtros activos
CUANDO hace click en "Exportar CSV"
ENTONCES se descarga CSV con transacciones filtradas
Y incluye todas las columnas relevantes
Y nombre archivo: "transactions_atlas_2025-12-05.csv"
```

**Escenario 6: Cuenta sin transacciones**
```gherkin
DADO que el usuario tiene cuenta recién creada
Y no hay transacciones
CUANDO accede al historial
ENTONCES se muestra mensaje "Aún no hay transacciones"
Y se muestra CTA "Realizar primer depósito"
```

## Criterios Adicionales

- [ ] Mostrar balance acumulado después de cada transacción
- [ ] Indicadores visuales por tipo (colores, iconos)
- [ ] Búsqueda por texto libre (descripción, monto)
- [ ] Infinite scroll como alternativa a paginación
- [ ] Cache de consultas frecuentes

---

## Tareas Técnicas

**Database:**
- [ ] DB-INV-001: Índice compuesto en (account_id, created_at DESC)
- [ ] DB-INV-002: Índice en (account_id, transaction_type)
- [ ] DB-INV-003: Vista para unir transacciones con metadata

**Backend:**
- [ ] BE-INV-001: Endpoint GET /investment/accounts/:id/transactions
- [ ] BE-INV-002: Implementar TransactionService.getHistory()
- [ ] BE-INV-003: Query builder para filtros dinámicos
- [ ] BE-INV-004: Paginación cursor-based o offset
- [ ] BE-INV-005: Endpoint GET /investment/transactions/:id (detalle)
- [ ] BE-INV-006: Endpoint GET /investment/accounts/:id/transactions/export

**Frontend:**
- [ ] FE-INV-001: Crear página TransactionsPage.tsx
- [ ] FE-INV-002: Crear componente TransactionList.tsx
- [ ] FE-INV-003: Crear componente TransactionRow.tsx
- [ ] FE-INV-004: Crear componente TransactionFilters.tsx
- [ ] FE-INV-005: Crear componente TransactionDetailModal.tsx
- [ ] FE-INV-006: Crear componente Pagination.tsx
- [ ] FE-INV-007: Implementar transactionsStore
- [ ] FE-INV-008: Implementar exportación CSV

**Tests:**
- [ ] TEST-INV-001: Test queries con filtros
- [ ] TEST-INV-002: Test paginación
- [ ] TEST-INV-003: Test exportación
- [ ] TEST-INV-004: Test E2E historial completo

---

## Dependencias

**Depende de:**
- [ ] US-INV-003: Realizar depósito - Estado: Pendiente
- [ ] US-INV-006: Solicitar retiro - Estado: Pendiente

**Bloquea:**
- [ ] US-INV-011: Exportar reporte PDF

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | /investment/accounts/:id/transactions | Lista paginada |
| GET | /investment/transactions/:id | Detalle |
| GET | /investment/accounts/:id/transactions/export | CSV export |

**Entidades/Tablas:**
- `investment.transactions`: Transacciones principales
- `investment.trade_details`: Metadata de trades
- `payments.stripe_transactions`: Metadata de Stripe

**Query Parameters:**
```typescript
{
  page: 1,
  limit: 10,
  type?: "deposit" | "withdrawal" | "trade_profit" | "trade_loss" | "distribution" | "fee",
  startDate?: "2025-11-01",
  endDate?: "2025-12-05",
  search?: "BTC",
  sortBy?: "created_at",
  sortOrder?: "DESC"
}
```

**Response GET /transactions:**
```typescript
{
  transactions: [
    {
      id: "uuid",
      accountId: "uuid",
      type: "deposit",
      amount: 1000,
      description: "Stripe deposit",
      createdAt: "2025-12-05T10:30:00Z",
      metadata: {
        stripePaymentIntentId: "pi_xxx",
        paymentMethod: "card_****4242"
      }
    },
    {
      id: "uuid",
      accountId: "uuid",
      type: "trade_profit",
      amount: 45.20,
      description: "BTC/USDT Long",
      createdAt: "2025-12-04T15:15:00Z",
      metadata: {
        symbol: "BTC/USDT",
        side: "long",
        entryPrice: 45000,
        exitPrice: 46000,
        size: 0.05,
        pnl: 45.20
      }
    }
  ],
  pagination: {
    page: 1,
    limit: 10,
    total: 156,
    totalPages: 16,
    hasNext: true,
    hasPrev: false
  },
  summary: {
    totalDeposits: 5000,
    totalWithdrawals: 1000,
    totalProfits: 1245.50,
    totalLosses: 255.30
  }
}
```

**Tipos de Transacción:**
- `deposit`: Depósito vía Stripe
- `withdrawal`: Retiro vía Stripe
- `trade_profit`: Ganancia de trade del agente
- `trade_loss`: Pérdida de trade del agente
- `distribution`: Distribución mensual de utilidades
- `fee`: Comisiones (Stripe, plataforma)

**CSV Export Format:**
```csv
Date,Time,Type,Description,Amount,Balance,Transaction ID
2025-12-05,10:30:00,Deposit,Stripe,+1000.00,1000.00,uuid
2025-12-04,15:15:00,Trade Profit,BTC/USDT Long,+45.20,1045.20,uuid
```

---

## Definition of Ready (DoR)

- [x] Historia claramente escrita
- [x] Criterios de aceptación definidos
- [x] Story points estimados
- [x] Dependencias identificadas
- [ ] Diseño/mockup disponible
- [x] API spec disponible

## Definition of Done (DoD)

- [ ] Código implementado según criterios
- [ ] Tests unitarios escritos y pasando
- [ ] Tests de integración pasando
- [ ] Paginación funcionando correctamente
- [ ] Filtros funcionando
- [ ] Exportación CSV funcionando
- [ ] Code review aprobado
- [ ] Documentación actualizada
- [ ] Performance optimizada (queries < 500ms)
- [ ] QA aprobado
- [ ] Desplegado en ambiente de pruebas

---

## Historial de Cambios

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-05 | Creación | Requirements-Analyst |

---

**Creada por:** Requirements-Analyst
**Fecha:** 2025-12-05
**Última actualización:** 2025-12-05