trading-platform/docs/02-definicion-modulos/OQI-004-investment-accounts/historias-usuario/US-INV-007-ver-transacciones.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-INV-007	Ver Historial de Transacciones	User Story	Done	Media	OQI-004	trading-platform	3	2025-12-05	2026-01-04

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

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

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

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

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

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

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:

{
  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:

{
  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:

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)

• Historia claramente escrita
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• Diseño/mockup disponible
• 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