# US-TRD-006: Crear Orden Market

## Metadata

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

---

## Historia de Usuario

**Como** trader practicante,
**quiero** crear una orden de mercado para comprar o vender un activo,
**para** abrir una posición de paper trading inmediatamente al precio actual.

## Descripción Detallada

El usuario debe poder ejecutar órdenes de mercado (market orders) que se llenan inmediatamente al precio actual del mercado. Esto le permite practicar trading sin riesgo real, usando un balance virtual de $10,000 USD.

## Mockups/Wireframes

```
┌─────────────────────────────────────┐
│          ORDER PANEL                │
├─────────────────────────────────────┤
│  [  BUY  ] [  SELL  ]              │
├─────────────────────────────────────┤
│  Order Type:  [Market ▼]            │
│                                      │
│  Amount (BTC):                       │
│  ┌─────────────────────────────────┐│
│  │ 0.1                             ││
│  └─────────────────────────────────┘│
│                                      │
│  ≈ $9,723.45 USD                    │
│                                      │
│  Available: $10,000.00              │
│  [25%] [50%] [75%] [100%]           │
│                                      │
│  ─────────────────────────────────  │
│  Take Profit:  [Optional]           │
│  Stop Loss:    [Optional]           │
│  ─────────────────────────────────  │
│                                      │
│  Est. Fee: $0.00                    │
│  Total: $9,723.45                   │
│                                      │
│  ┌─────────────────────────────────┐│
│  │       BUY BTCUSDT               ││
│  └─────────────────────────────────┘│
└─────────────────────────────────────┘
```

---

## Criterios de Aceptación

**Escenario 1: Crear orden market de compra exitosa**
```gherkin
DADO que el usuario tiene balance de $10,000
Y el precio de BTCUSDT es $97,234.50
CUANDO selecciona BUY
Y ingresa cantidad de 0.1 BTC
Y hace click en "BUY BTCUSDT"
ENTONCES la orden se ejecuta inmediatamente
Y se muestra notificación "Order filled at $97,234.50"
Y se crea una posición long de 0.1 BTC
Y el balance se reduce aproximadamente $9,723.45
Y la posición aparece en el panel de posiciones
```

**Escenario 2: Crear orden market de venta (short)**
```gherkin
DADO que el usuario tiene balance de $10,000
Y no tiene posición en BTCUSDT
CUANDO selecciona SELL
Y ingresa cantidad de 0.05 BTC
Y hace click en "SELL BTCUSDT"
ENTONCES la orden se ejecuta inmediatamente
Y se crea una posición short de 0.05 BTC
Y el margin usado se incrementa
```

**Escenario 3: Balance insuficiente**
```gherkin
DADO que el usuario tiene balance de $500
Y el precio de BTCUSDT es $97,234.50
CUANDO intenta comprar 0.1 BTC (~$9,723)
ENTONCES el botón de submit está deshabilitado
Y se muestra mensaje "Insufficient balance"
Y se resalta el campo de amount en rojo
```

**Escenario 4: Orden con Take Profit y Stop Loss**
```gherkin
DADO que el usuario crea una orden market BUY
CUANDO configura Take Profit en $100,000
Y configura Stop Loss en $95,000
Y ejecuta la orden
ENTONCES la posición se crea con TP y SL configurados
Y el sistema monitorea estos niveles automáticamente
```

**Escenario 5: Slippage aplicado**
```gherkin
DADO que el usuario ejecuta orden market
Y el precio mostrado es $97,234.50
CUANDO la orden se ejecuta
ENTONCES el precio de fill puede variar hasta 0.1%
Y se muestra el precio real de ejecución
```

## Criterios Adicionales

- [ ] Mostrar preview del costo total antes de confirmar
- [ ] Validar cantidad mínima ($10 USD)
- [ ] Deshabilitar botón mientras procesa
- [ ] Mostrar loading spinner durante ejecución
- [ ] Sonido de notificación al ejecutar (opcional)
- [ ] Keyboard shortcut: Enter para confirmar

---

## Tareas Técnicas

**Database:**
- [ ] DB-TRD-001: Crear tabla paper_orders
- [ ] DB-TRD-002: Crear tabla paper_positions
- [ ] DB-TRD-003: Crear tabla paper_balances

**Backend:**
- [ ] BE-TRD-010: Crear endpoint POST /trading/paper/orders
- [ ] BE-TRD-011: Implementar OrderService.createMarketOrder()
- [ ] BE-TRD-012: Implementar PositionService.openPosition()
- [ ] BE-TRD-013: Implementar BalanceService con transacciones
- [ ] BE-TRD-014: Implementar validaciones de balance

**Frontend:**
- [ ] FE-TRD-010: Crear componente OrderPanel.tsx
- [ ] FE-TRD-011: Crear componente AmountInput.tsx
- [ ] FE-TRD-012: Crear componente OrderConfirmation.tsx
- [ ] FE-TRD-013: Implementar orderStore con Zustand
- [ ] FE-TRD-014: Implementar hook useCreateOrder

**Tests:**
- [ ] TEST-TRD-010: Test unitario OrderService
- [ ] TEST-TRD-011: Test integración crear orden
- [ ] TEST-TRD-012: Test E2E flujo completo de orden

---

## Dependencias

**Depende de:**
- [ ] US-TRD-001: Ver chart - Estado: Pendiente (necesita precio actual)
- [ ] US-AUTH-001: Autenticación - Estado: ✅ Completado

**Bloquea:**
- [ ] US-TRD-007: Crear orden limit
- [ ] US-TRD-008: Cerrar posición
- [ ] US-TRD-009: Ver posiciones

---

## Notas Técnicas

**Endpoints involucrados:**
| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | /trading/paper/orders | Crear orden |
| GET | /trading/paper/balance | Obtener balance |
| GET | /trading/ticker/:symbol | Precio actual |

**Entidades/Tablas:**
- `trading.paper_orders`: Registro de órdenes
- `trading.paper_positions`: Posiciones abiertas
- `trading.paper_balances`: Balance virtual

**Componentes UI:**
- `OrderPanel`: Panel principal de órdenes
- `AmountInput`: Input con cálculo USD
- `OrderTypeSelector`: Selector market/limit
- `TPSLInputs`: Inputs de Take Profit y Stop Loss

**Request Body:**
```typescript
{
  symbol: "BTCUSDT",
  side: "buy",
  type: "market",
  quantity: 0.1,
  takeProfit: 100000,  // opcional
  stopLoss: 95000      // opcional
}
```

**Response:**
```typescript
{
  order: {
    id: "uuid",
    symbol: "BTCUSDT",
    side: "buy",
    type: "market",
    status: "filled",
    quantity: 0.1,
    filledPrice: 97258.34,
    createdAt: "2025-12-05T...",
    filledAt: "2025-12-05T..."
  },
  position: {
    id: "uuid",
    symbol: "BTCUSDT",
    side: "long",
    quantity: 0.1,
    entryPrice: 97258.34,
    takeProfit: 100000,
    stopLoss: 95000
  },
  balance: {
    balance: 272.66,
    equity: 272.66,
    marginUsed: 9725.83
  }
}
```

---

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