---
id: "US-LLM-011"
title: "Ejecutar Trade desde Chat"
type: "User Story"
status: "Pending"
priority: "Alta"
epic: "OQI-007"
project: "trading-platform"
story_points: 5
created_date: "2026-01-25"
updated_date: "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
```gherkin
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
```gherkin
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
```gherkin
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
```gherkin
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
```gherkin
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
```gherkin
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
```gherkin
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

```markdown
## 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

```markdown
## 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

```markdown
## 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:**
```json
{
  "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):**
```json
{
  "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):**
```json
{
  "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

```mermaid
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*