trading-platform/docs/02-definicion-modulos/OQI-007-llm-agent/historias-usuario/US-LLM-011-ejecutar-trade-desde-chat.md

id	title	type	status	priority	epic	project	story_points	created_date	updated_date
US-LLM-011	Ejecutar Trade desde Chat	User Story	Pending	Alta	OQI-007	trading-platform	5	2026-01-25	2026-01-25

US-LLM-011: Ejecutar Trade desde Chat

Épica: OQI-007 - LLM Strategy Agent Sprint: TBD Story Points: 5 Prioridad: P0 - Alta

---

Historia de Usuario

Como usuario Pro o Premium con capacidad de trading real Quiero ejecutar trades directamente desde el chat con el asistente AI mediante comandos naturales Para operar en los mercados rápidamente sin cambiar de interfaz

---

Criterios de Aceptación

AC-1: Interpretar comandos de trading

Given soy usuario Pro/Premium
And tengo acceso a trading real
When digo frases como "Vende 50 acciones de AAPL" o "Compra Bitcoin a $43,000"
Then el agente interpreta correctamente:
  - Acción (compra/venta)
  - Símbolo del activo
  - Cantidad
  - Tipo de orden (mercado/límite)
  - Precio (si es límite)
And valida que la orden sea válida

AC-2: Mostrar preview de la orden

Given el agente interpreta un comando de trading
When prepara la orden
Then muestra un resumen detallado:
  - Símbolo y nombre del activo
  - Acción (BUY/SELL)
  - Cantidad de unidades
  - Tipo de orden (market/limit)
  - Precio unitario estimado
  - Costo/ingresos totales
  - Comisiones estimadas
  - Impacto en el portafolio
And NO ejecuta la orden automáticamente

AC-3: Requerir confirmación explícita

Given el agente muestra el preview de la orden
When el usuario revisa los detalles
Then el agente pide confirmación explícita:
  - "¿Confirmas esta orden?" o similar
  - Botones/acciones claras (Confirmar/Cancelar)
And SOLO ejecuta si el usuario confirma
And permite cancelar en cualquier momento

AC-4: Validar límites de riesgo

Given quiero ejecutar una orden
When el agente prepara la orden
Then valida:
  - Saldo disponible suficiente
  - Límite de exposición por activo
  - Límite de pérdida diaria
  - Límite de apalancamiento
And si hay violación:
  - Informa qué límite se excede
  - Muestra valores actuales vs permitidos
  - NO permite ejecutar

AC-5: Ejecutar y retornar feedback

Given el usuario confirma la orden
When se ejecuta correctamente
Then muestra confirmación con:
  - ID de la orden
  - Status (filled/pending)
  - Símbolo y precio ejecutado
  - Cantidad y costo final
  - Timestamp exacto
  - Posición actualizada en el activo
And registra en el historial del chat

AC-6: Manejo de errores

Given intento ejecutar una orden
When ocurre error (conexión, mercado cerrado, etc.)
Then el agente:
  - Informa el tipo de error
  - Explica por qué no se ejecutó
  - Sugiere alternativas (ej: orden pendiente)
  - NO procesa parcialmente la orden

AC-7: Restricción por plan

Given soy usuario Free o con trading deshabilitado
When intento ejecutar una orden
Then el agente:
  - Rechaza la orden
  - Explica que requiere plan Pro/Premium
  - Muestra opción de upgrade
  - NO ejecuta ninguna orden

---

Flujo de Confirmación

## Confirmar Orden 📊

**Acción:** VENTA
**Símbolo:** AAPL - Apple Inc.
**Cantidad:** 50 acciones
**Tipo:** Market Order
**Precio actual:** $185.32
**Costo total:** ~$9,266.00
**Comisión:** ~$9.27
**Neto:** ~$9,256.73

**Tu portafolio:**
- Posición actual: 100 acciones @ $184.50
- Posición después: 50 acciones

---

⚠️ Esta es una orden REAL de trading

¿Confirmas esta orden?

[✅ Confirmar] [❌ Cancelar]

---

Respuesta Post-Ejecución

## Orden Ejecutada ✅

**ID:** ORD-20260125-001234
**Status:** Filled (Completada)
**Símbolo:** AAPL
**Acción:** VENTA
**Cantidad:** 50 acciones
**Precio:** $185.31
**Total:** $9,265.50
**Comisión:** $9.27
**Neto:** $9,256.23
**Timestamp:** 15:45:32 ET

**Posición Actualizada:**
- AAPL: 50 acciones @ $185.31 (promedio)
- Valor: $9,265.50
- Variación: +2.5% hoy

Registro guardado en tu historial.

---

Respuesta con Error

## Error al Ejecutar ❌

**Razón:** Mercado cerrado (Cierre: 16:00 ET)

La orden no pudo ejecutarse porque el mercado de NYSE está cerrado.

**Alternativas:**
- Crear orden pendiente para la apertura mañana
- Intentar en mercados abiertos (premarket a las 04:00 ET)
- Esperar a mañana a las 09:30 ET

¿Qué prefieres?

[Orden Pendiente] [Otra acción] [Cancelar]

---

API Endpoint

POST /api/llm/execute-trade

Headers:

Authorization: Bearer {token}
Content-Type: application/json

Request Body:

{
  "sessionId": "chat-session-12345",
  "interpretation": {
    "action": "BUY|SELL",
    "symbol": "AAPL",
    "quantity": 50,
    "orderType": "market|limit",
    "limitPrice": null,
    "timeInForce": "DAY|GTC"
  },
  "userId": "user-uuid",
  "confirmedAt": "2026-01-25T15:45:32Z"
}

Response (Success):

{
  "success": true,
  "order": {
    "orderId": "ORD-20260125-001234",
    "status": "filled",
    "symbol": "AAPL",
    "action": "SELL",
    "quantity": 50,
    "executedPrice": 185.31,
    "totalValue": 9265.50,
    "commission": 9.27,
    "netValue": 9256.23,
    "executedAt": "2026-01-25T15:45:32Z"
  },
  "message": "Orden ejecutada exitosamente"
}

Response (Error):

{
  "success": false,
  "error": {
    "code": "MARKET_CLOSED",
    "message": "El mercado está cerrado",
    "details": "NYSE cierra a las 16:00 ET"
  },
  "alternatives": [
    {
      "type": "pending_order",
      "description": "Crear orden pendiente para apertura"
    }
  ]
}

---

Notas Técnicas

• Tool: execute_trade (en el LLM Agent)
• Servicio: Trading API Backend (puerto 3080)
• Confirmación: OBLIGATORIA antes de ejecutar
• Validación: Límites de riesgo, saldo, mercado abierto
• Logging: Todas las órdenes registradas con timestamp
• Rate limit: 20 órdenes/minuto por usuario
• Timeout: 30 segundos para confirmación
• Rollback: Si falla ejecución, reversión de cambios

---

Flujo Técnico

graph TD
    A["Usuario: 'Vende 50 AAPL'"] -->|Chat Input| B["LLM Agent"]
    B -->|NLU| C["Interpretar Comando"]
    C -->|Validar Sintaxis| D{¿Válido?}
    D -->|No| E["Error: Comando inválido"]
    D -->|Sí| F["Preparar Preview"]
    F -->|GET /api/market/price| G["Obtener precio actual"]
    G -->|GET /api/portfolio/position| H["Obtener posición actual"]
    H -->|Calcular| I["Preparar detalles orden"]
    I -->|Mostrar| J["Preview en chat"]
    J -->|Usuario revisa| K{¿Confirma?}
    K -->|Cancela| L["Cancelado"]
    K -->|Confirma| M["POST /api/llm/execute-trade"]
    M -->|Validar riesgos| N{¿Límites OK?}
    N -->|No| O["Error: Límite excedido"]
    N -->|Sí| P["Ejecutar orden"]
    P -->|Trading System| Q["Orden procesada"]
    Q -->|Response| R["Mostrar confirmación"]
    R -->|Actualizar portafolio| S["Feedback final"]

---

Criterios de Aceptación Técnica

• Interpretar al menos 10 variantes de comandos
• Validar todos los campos obligatorios
• Conectar con Trading API backend
• Mostrar preview antes de ejecutar
• Requerir confirmación explícita
• Validar límites de riesgo
• Ejecutar orden correctamente
• Mostrar confirmación con detalles
• Registrar en historial
• Manejo robusto de errores
• Tests unitarios (80%+ coverage)
• Tests E2E del flujo completo
• QA aprobado

---

Dependencias

• RF-LLM-005: Herramienta Trading Execution
• RF-LLM-006: Interpretación NLU avanzada
• ET-LLM-005: Arquitectura Tools
• OQI-001: Autenticación y autorización
• OQI-003: Paper Trading System
• REC-BACKEND-001: Trading API

---

Definición de Done

• Endpoint /api/llm/execute-trade implementado
• LLM Agent puede interpretar comandos
• Preview de orden funcionando
• Confirmación obligatoria
• Validación de límites de riesgo
• Ejecución de orden
• Feedback post-ejecución
• Manejo de errores
• Restricción por plan
• Tests unitarios
• Tests E2E
• QA aprobado
• Documentación actualizada

---

Historia de usuario - Sistema NEXUS Trading Platform