trading-platform/docs/02-definicion-modulos/OQI-003-trading-charts/historias-usuario/US-TRD-007-crear-orden-limit.md

id	title	type	status	priority	epic	story_points	created_date	updated_date
US-TRD-007	Crear Orden Limit	User Story	Done	Alta	OQI-003	5	2025-12-05	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

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

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

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

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

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:

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:

{
  symbol: "BTCUSDT",
  side: "buy",
  type: "limit",
  quantity: 0.1,
  limitPrice: 95000.00,
  timeInForce: "GTC"
}

Response:

{
  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:

// 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)

• 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