cdec253b02
- Add 5 frontend specification documents (ET-*-frontend.md): - ET-AUTH-006: Authentication module frontend spec - ET-ML-008: ML Signals module frontend spec - ET-LLM-007: LLM Agent module frontend spec - ET-PFM-008: Portfolio Manager frontend spec (design) - ET-MKT-003: Marketplace frontend spec (design) - Add 8 new user stories: - US-AUTH-013: Global logout - US-AUTH-014: Device management - US-ML-008: Ensemble signal view - US-ML-009: ICT analysis view - US-ML-010: Multi-symbol scan - US-LLM-011: Execute trade from chat - US-PFM-013: Rebalance alerts - US-PFM-014: PDF report generation - Update task index with completed analysis Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
358 lines
8.1 KiB
Markdown
358 lines
8.1 KiB
Markdown
---
|
|
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*
|