trading-platform/docs/02-definicion-modulos/OQI-003-trading-charts/historias-usuario/US-TRD-009-ver-posiciones.md

id	title	type	status	priority	epic	story_points	created_date	updated_date
US-TRD-009	Ver Panel de Posiciones Abiertas	User Story	Done	Alta	OQI-003	3	2025-12-05	2026-01-04

US-TRD-009: Ver Panel de Posiciones Abiertas

Metadata

Campo	Valor
ID	US-TRD-009
Épica	OQI-003 - Trading y Charts
Módulo	trading
Prioridad	P0
Story Points	3
Sprint	Sprint 4
Estado	Pendiente
Asignado a	Por asignar

---

Historia de Usuario

Como trader practicante, quiero ver un panel con todas mis posiciones abiertas y su P&L en tiempo real, para monitorear el rendimiento actual de mis trades y tomar decisiones informadas.

Descripción Detallada

El usuario debe tener acceso a un panel dedicado que muestre todas las posiciones abiertas con información crítica: símbolo, dirección (long/short), tamaño, precio de entrada, precio actual, P&L no realizado en dólares y porcentaje, y acciones rápidas (cerrar, modificar TP/SL).

Mockups/Wireframes

┌─────────────────────────────────────────────────────────────────────────┐
│  OPEN POSITIONS                                    Total P&L: +$345.67  │
├─────────────────────────────────────────────────────────────────────────┤
│  Symbol     Side   Size      Entry       Current      PnL       Actions │
│  ─────────────────────────────────────────────────────────────────────  │
│  BTCUSDT    LONG   0.10 BTC  $95,000.00  $97,234.50  +$223.45   [...]  │
│                                                      (+2.35%) ▲          │
│             TP: $100,000  |  SL: $93,000                                │
│  ─────────────────────────────────────────────────────────────────────  │
│  ETHUSDT    LONG   2.5 ETH   $3,800.00   $3,850.20   +$125.50   [...]  │
│                                                      (+1.32%) ▲          │
│             TP: $4,000    |  SL: $3,700                                 │
│  ─────────────────────────────────────────────────────────────────────  │
│  SOLUSDT    SHORT  10 SOL    $145.00     $142.73    +$22.70     [...]  │
│                                                      (+1.56%) ▲          │
│             TP: $140.00   |  SL: $148.00                                │
│  ─────────────────────────────────────────────────────────────────────  │
│                                                                          │
│  Summary:                                                                │
│  Total Margin Used: $7,450.00  |  Free Balance: $2,550.00              │
│  Total Equity: $10,345.67      |  Margin Level: 138.9%                 │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────┐
│ POSITION ACTIONS        │
├─────────────────────────┤
│ > Close Position        │
│ > Modify TP/SL          │
│ > Add to Position       │
│ > View on Chart         │
└─────────────────────────┘

---

Criterios de Aceptación

Escenario 1: Ver panel con múltiples posiciones

DADO que el usuario tiene 3 posiciones abiertas
CUANDO navega al panel de posiciones
ENTONCES se muestran las 3 posiciones en una tabla
Y cada fila muestra: símbolo, side, size, entry, current, P&L
Y el P&L total aparece en el header
Y los valores se actualizan cada segundo

Escenario 2: Actualización de P&L en tiempo real

DADO que el usuario tiene posición long BTCUSDT
Y el precio actual es $97,234.50
CUANDO el precio sube a $97,500.00
ENTONCES el P&L se actualiza automáticamente
Y muestra +$250.00 (+2.63%)
Y el color cambia según el valor (verde positivo, rojo negativo)

Escenario 3: Mostrar TP y SL configurados

DADO que la posición tiene TP=$100,000 y SL=$93,000
CUANDO el usuario ve la posición
ENTONCES se muestran ambos valores debajo de la fila principal
Y se indica la distancia en % al TP y SL
Ejemplo: "TP: $100,000 (+2.84%) | SL: $93,000 (-4.35%)"

Escenario 4: Panel vacío

DADO que el usuario no tiene posiciones abiertas
CUANDO accede al panel de posiciones
ENTONCES se muestra mensaje "No open positions"
Y se muestra botón "Start Trading"
Y el total P&L es $0.00

Escenario 5: Ordenar por P&L

DADO que el usuario tiene múltiples posiciones
CUANDO hace click en el header "PnL"
ENTONCES las posiciones se ordenan por P&L descendente
Y un segundo click ordena ascendente

Escenario 6: Filtrar por símbolo

DADO que el usuario tiene posiciones en BTC, ETH, SOL
CUANDO escribe "BTC" en el filtro
ENTONCES solo se muestran posiciones de BTCUSDT

Criterios Adicionales

• Resaltar posiciones con P&L > ±5% en color intenso
• Sonido de alerta cuando P&L alcanza ±10%
• Mostrar duración de la posición (ej: "2h 35m")
• Indicador visual cuando el precio se acerca al TP o SL (±2%)
• Exportar posiciones a CSV

---

Tareas Técnicas

Database:

• DB-TRD-014: Crear vista positions_with_pnl con cálculos

Backend:

• BE-TRD-044: Crear endpoint GET /trading/paper/positions
• BE-TRD-045: Implementar PositionService.listPositions()
• BE-TRD-046: Implementar cálculo de P&L no realizado
• BE-TRD-047: Implementar WebSocket para actualizaciones de P&L
• BE-TRD-048: Añadir filtros y ordenamiento

Frontend:

• FE-TRD-044: Crear componente PositionsPanel.tsx
• FE-TRD-045: Crear componente PositionRow.tsx
• FE-TRD-046: Crear componente PositionSummary.tsx
• FE-TRD-047: Crear componente PositionActions.tsx
• FE-TRD-048: Implementar hook usePositions con WebSocket
• FE-TRD-049: Implementar animación de cambios de P&L

Tests:

• TEST-TRD-022: Test unitario cálculo P&L no realizado
• TEST-TRD-023: Test integración listar posiciones
• TEST-TRD-024: Test E2E actualización en tiempo real

---

Dependencias

Depende de:

• US-TRD-006: Crear orden market - Estado: Pendiente (necesita posiciones)
• US-TRD-001: Ver chart - Estado: Pendiente (para precios)

Bloquea:

• US-TRD-008: Cerrar posición
• US-TRD-012: Configurar TP/SL

---

Notas Técnicas

Endpoints involucrados:

Método	Endpoint	Descripción
GET	/trading/paper/positions	Listar posiciones abiertas
GET	/trading/paper/positions/summary	Resumen de posiciones
WS	/trading/positions/stream	Stream de actualizaciones P&L

Entidades/Tablas:

CREATE VIEW trading.positions_with_pnl AS
SELECT
  p.*,
  t.price as current_price,
  CASE
    WHEN p.side = 'long' THEN (t.price - p.entry_price) * p.quantity
    WHEN p.side = 'short' THEN (p.entry_price - t.price) * p.quantity
  END as unrealized_pnl,
  CASE
    WHEN p.side = 'long' THEN ((t.price - p.entry_price) / p.entry_price) * 100
    WHEN p.side = 'short' THEN ((p.entry_price - t.price) / p.entry_price) * 100
  END as unrealized_pnl_percentage,
  EXTRACT(EPOCH FROM (NOW() - p.created_at)) as duration_seconds
FROM trading.paper_positions p
LEFT JOIN trading.current_prices t ON p.symbol = t.symbol
WHERE p.status = 'open';

Componentes UI:

• PositionsPanel: Panel principal
• PositionRow: Fila de posición con datos
• PositionSummary: Resumen total
• PositionActions: Menú de acciones
• PnLCell: Celda con P&L coloreado y animado

Response (List Positions):

{
  positions: [
    {
      id: "uuid-1",
      symbol: "BTCUSDT",
      side: "long",
      quantity: 0.1,
      entryPrice: 95000.00,
      currentPrice: 97234.50,
      unrealizedPnl: 223.45,
      unrealizedPnlPercentage: 2.35,
      marginUsed: 9500.00,
      takeProfit: 100000.00,
      stopLoss: 93000.00,
      durationSeconds: 8640,
      createdAt: "2025-12-05T08:00:00Z"
    },
    // ... más posiciones
  ],
  summary: {
    totalPositions: 3,
    totalMarginUsed: 7450.00,
    totalUnrealizedPnl: 345.67,
    totalUnrealizedPnlPercentage: 4.64,
    freeBalance: 2550.00,
    totalEquity: 10345.67,
    marginLevel: 138.9
  }
}

WebSocket Update:

{
  type: "position_update",
  data: {
    positionId: "uuid-1",
    currentPrice: 97500.00,
    unrealizedPnl: 250.00,
    unrealizedPnlPercentage: 2.63,
    timestamp: 1733414400
  }
}

Cálculos importantes:

// P&L no realizado (unrealized)
const unrealizedPnl = side === 'long'
  ? (currentPrice - entryPrice) * quantity
  : (entryPrice - currentPrice) * quantity;

// Equity
const equity = balance + totalUnrealizedPnl;

// Margin Level
const marginLevel = (equity / totalMarginUsed) * 100;

// Distancia a TP/SL
const distanceToTP = ((takeProfit - currentPrice) / currentPrice) * 100;
const distanceToSL = ((stopLoss - currentPrice) / currentPrice) * 100;

---

Definition of Ready (DoR)

• Historia claramente escrita
• Criterios de aceptación definidos
• Story points estimados
• Dependencias identificadas
• Sin bloqueadores
• 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
• Code review aprobado
• Documentación actualizada
• 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