---
id: "US-TRD-007"
title: "Crear Orden Limit"
type: "User Story"
status: "Done"
priority: "Alta"
epic: "OQI-003"
story_points: 5
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# US-TRD-007: Crear Orden Limit

## Metadata

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

---

## Historia de Usuario

**Como** trader practicante,
**quiero** crear órdenes limit con un precio específico,
**para** ejecutar trades cuando el precio alcance mi nivel objetivo sin tener que monitorear constantemente.

## Descripción Detallada

El usuario debe poder crear órdenes limit que se ejecutarán automáticamente cuando el precio del mercado alcance el precio especificado. A diferencia de las órdenes market, las limit permiten control preciso del precio de entrada.

## Mockups/Wireframes

```
┌─────────────────────────────────────┐
│          ORDER PANEL                │
├─────────────────────────────────────┤
│  [  BUY  ] [  SELL  ]              │
├─────────────────────────────────────┤
│  Order Type:  [Limit ▼]             │
│                                      │
│  Limit Price (USD):                  │
│  ┌─────────────────────────────────┐│
│  │ 95,000.00                       ││
│  └─────────────────────────────────┘│
│  Current: $97,234.50 (-2.30%)       │
│                                      │
│  Amount (BTC):                       │
│  ┌─────────────────────────────────┐│
│  │ 0.1                             ││
│  └─────────────────────────────────┘│
│                                      │
│  ≈ $9,500.00 USD                    │
│                                      │
│  Available: $10,000.00              │
│  [25%] [50%] [75%] [100%]           │
│                                      │
│  ─────────────────────────────────  │
│  Time in Force: [GTC ▼]             │
│  (Good Till Cancelled)               │
│  ─────────────────────────────────  │
│                                      │
│  Est. Fee: $0.00                    │
│  Total: $9,500.00                   │
│                                      │
│  ┌─────────────────────────────────┐│
│  │   PLACE LIMIT BUY ORDER         ││
│  └─────────────────────────────────┘│
└─────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Crear orden limit buy exitosa**
```gherkin
DADO que el usuario tiene balance de $10,000
Y el precio actual de BTCUSDT es $97,234.50
CUANDO selecciona BUY
Y selecciona tipo "Limit"
Y ingresa precio limit de $95,000
Y ingresa cantidad de 0.1 BTC
Y hace click en "PLACE LIMIT BUY ORDER"
ENTONCES la orden se crea con estado "pending"
Y aparece en el panel de "Open Orders"
Y el balance reservado es $9,500.00
Y la orden se ejecutará cuando el precio baje a $95,000
```

**Escenario 2: Crear orden limit sell**
```gherkin
DADO que el usuario tiene una posición long de 0.1 BTC
Y el precio actual es $97,234.50
CUANDO selecciona SELL
Y selecciona tipo "Limit"
Y ingresa precio limit de $100,000
Y ingresa cantidad de 0.1 BTC
Y confirma la orden
ENTONCES se crea orden limit sell pendiente
Y la posición queda reservada
Y se ejecutará cuando el precio suba a $100,000
```

**Escenario 3: Precio limit inválido para buy**
```gherkin
DADO que el precio actual es $97,234.50
CUANDO el usuario crea orden limit BUY
Y ingresa precio $100,000 (mayor al actual)
ENTONCES se muestra warning "Limit buy price should be below current price"
Y permite continuar (puede ser intencional)
```

**Escenario 4: Ejecución automática de orden limit**
```gherkin
DADO que existe orden limit BUY a $95,000
CUANDO el precio de mercado baja a $95,000
ENTONCES la orden se ejecuta automáticamente
Y se crea una posición long de 0.1 BTC
Y la orden pasa de "pending" a "filled"
Y se envía notificación "Limit order filled at $95,000"
```

**Escenario 5: Cancelar orden limit pendiente**
```gherkin
DADO que el usuario tiene orden limit pendiente
CUANDO hace click en "Cancel" en Open Orders
ENTONCES la orden cambia a estado "cancelled"
Y el balance reservado se libera
Y desaparece del panel de Open Orders
```

## Criterios Adicionales

- [ ] Validar precio mínimo ($10 USD)
- [ ] Time in Force: GTC (Good Till Cancelled), IOC (Immediate or Cancel)
- [ ] Mostrar línea horizontal en chart con precio limit
- [ ] Preview del precio en relación al precio actual
- [ ] Notificación push cuando se ejecuta

---

## Tareas Técnicas

**Database:**
- [ ] DB-TRD-010: Añadir tipo "limit" a paper_orders
- [ ] DB-TRD-011: Añadir campos limit_price, time_in_force

**Backend:**
- [ ] BE-TRD-032: Actualizar endpoint POST /trading/paper/orders para limit
- [ ] BE-TRD-033: Implementar OrderService.createLimitOrder()
- [ ] BE-TRD-034: Implementar OrderMatchingService para monitorear precios
- [ ] BE-TRD-035: Crear job que verifica órdenes limit cada segundo
- [ ] BE-TRD-036: Implementar lógica de ejecución automática
- [ ] BE-TRD-037: Crear endpoint DELETE /trading/paper/orders/:id (cancelar)

**Frontend:**
- [ ] FE-TRD-032: Actualizar OrderPanel con tipo limit
- [ ] FE-TRD-033: Crear componente LimitPriceInput.tsx
- [ ] FE-TRD-034: Crear componente TimeInForceSelector.tsx
- [ ] FE-TRD-035: Crear componente OpenOrdersPanel.tsx
- [ ] FE-TRD-036: Añadir línea horizontal en chart para órdenes limit
- [ ] FE-TRD-037: Implementar hook useCancelOrder

**Tests:**
- [ ] TEST-TRD-016: Test unitario OrderMatchingService
- [ ] TEST-TRD-017: Test integración crear/ejecutar orden limit
- [ ] TEST-TRD-018: Test E2E flujo completo limit order

---

## Dependencias

**Depende de:**
- [ ] US-TRD-006: Crear orden market - Estado: Pendiente
- [ ] US-TRD-001: Ver chart - Estado: Pendiente

**Bloquea:**
- Ninguna

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | /trading/paper/orders | Crear orden limit |
| GET | /trading/paper/orders | Listar órdenes pendientes |
| DELETE | /trading/paper/orders/:id | Cancelar orden |
| PATCH | /trading/paper/orders/:id | Modificar orden |

**Entidades/Tablas:**
```sql
ALTER TABLE trading.paper_orders ADD COLUMN limit_price DECIMAL(20, 8);
ALTER TABLE trading.paper_orders ADD COLUMN time_in_force VARCHAR(10) DEFAULT 'GTC';
```

**Estados de orden:**
- `pending`: Esperando ejecución
- `filled`: Ejecutada completamente
- `partially_filled`: Ejecutada parcialmente
- `cancelled`: Cancelada por usuario
- `expired`: Expiró (para IOC, FOK)

**Componentes UI:**
- `LimitPriceInput`: Input con validación de precio
- `TimeInForceSelector`: Dropdown de TIF
- `OpenOrdersPanel`: Panel de órdenes pendientes
- `OrderLine`: Línea horizontal en chart

**Request Body:**
```typescript
{
  symbol: "BTCUSDT",
  side: "buy",
  type: "limit",
  quantity: 0.1,
  limitPrice: 95000.00,
  timeInForce: "GTC"
}
```

**Response:**
```typescript
{
  order: {
    id: "uuid",
    symbol: "BTCUSDT",
    side: "buy",
    type: "limit",
    status: "pending",
    quantity: 0.1,
    limitPrice: 95000.00,
    timeInForce: "GTC",
    createdAt: "2025-12-05T...",
    expiresAt: null
  },
  balance: {
    balance: 500.00,
    reserved: 9500.00,
    equity: 10000.00
  }
}
```

**Order Matching Logic:**
```typescript
// Para órdenes BUY limit
if (currentPrice <= order.limitPrice) {
  executeOrder(order, currentPrice);
}

// Para órdenes SELL limit
if (currentPrice >= order.limitPrice) {
  executeOrder(order, currentPrice);
}
```

**Time in Force opciones:**
- **GTC** (Good Till Cancelled): Permanece activa hasta ejecutarse o cancelarse
- **IOC** (Immediate or Cancel): Se ejecuta inmediatamente o se cancela
- **FOK** (Fill or Kill): Se ejecuta completamente o se cancela

---

## Definition of Ready (DoR)

- [x] Historia claramente escrita
- [x] Criterios de aceptación definidos
- [x] Story points estimados
- [x] Dependencias identificadas
- [x] 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