# US-MGN-007-003-001: Crear Entrega desde Sales Order

**RF Asociado:** [RF-MGN-007-004](../../02-modelado/requerimientos-funcionales/mgn-007/RF-MGN-007-004-entregas-de-ventas.md)
**Módulo:** MGN-007 - Ventas Básico
**Epic:** Entregas de Ventas
**Prioridad:** P0
**Story Points:** 5
**Sprint:** Sprint 17
**Estado:** Ready for Development
**Fecha:** 2025-11-24

---

## User Story

**Como** usuario de almacén,
**Quiero** crear entregas (delivery orders) desde órdenes de venta confirmadas,
**Para** preparar el picking y despacho de productos al cliente.

---

## Descripción Detallada

Una Entrega (Delivery / Picking) es el documento que autoriza la salida física de productos. Se crea desde una SO confirmada copiando las líneas pendientes de entregar.

Flujo:
1. SO confirmada genera botón "Create Delivery"
2. Sistema crea delivery en draft con líneas pendientes
3. Ubicación origen: almacén configurado en SO
4. Ubicación destino: ubicación del cliente
5. Referencia: SO/2024/NNNN
6. Estado inicial: draft (editable)

Delivery tiene estados: draft, assigned (reservado), done (validado), cancelled.

---

## Criterios de Aceptación

### Escenario 1: Crear delivery desde SO confirmada (Camino Feliz)
**Dado que** SO id=1 está confirmed con 3 líneas,
**Cuando** ejecuto action "Create Delivery",
**Entonces** sistema crea delivery en draft con las 3 líneas, número DO/2024/0001, origen=Almacén Principal.

### Escenario 2: Validar que SO está confirmada
**Dado que** SO está en draft,
**Cuando** intento crear delivery,
**Entonces** sistema retorna error 400 "Solo pueden crearse entregas de órdenes confirmadas".

### Escenario 3: Crear delivery parcial si hay entregas previas
**Dado que** SO tiene qty_total=100, qty_delivered=60,
**Cuando** creo delivery,
**Entonces** sistema crea delivery solo con qty_pending=40.

### Escenario 4: No crear delivery si ya está todo entregado
**Dado que** SO tiene qty_delivered = qty_total (100%),
**Cuando** intento crear delivery,
**Entonces** sistema retorna error 400 "No hay productos pendientes de entregar".

### Escenario 5: Vincular delivery a SO
**Dado que** se crea delivery desde SO id=1,
**Cuando** se completa creación,
**Entonces** delivery.order_id=1 y SO muestra delivery en lista de entregas.

### Escenario 6: Generar número secuencial de delivery
**Dado que** última delivery fue DO/2024/0005,
**Cuando** creo nueva delivery,
**Entonces** sistema genera número DO/2024/0006.

---

## Reglas de Negocio

- **RN-1:** Solo SO en estado confirmed o superior pueden generar deliveries.
- **RN-2:** Delivery se crea con líneas pendientes (qty_to_deliver = qty_ordered - qty_delivered).
- **RN-3:** Número secuencial: DO/{year}/{seq:04d}.
- **RN-4:** Estado inicial: draft.
- **RN-5:** Ubicación origen: almacén de la SO (warehouse_id).
- **RN-6:** Ubicación destino: ubicación del cliente (partner location).
- **RN-7:** Se puede crear delivery parcial si hay cantidades pendientes.
- **RN-8:** Permisos: stock_user.

---

## Tareas Técnicas

### Backend
- [ ] Endpoint: `POST /api/v1/sales/orders/:id/create-delivery`
- [ ] Service: `SalesOrderService.createDelivery(orderId)`
- [ ] Service: `DeliveryService.createFromOrder(order, lines)`
- [ ] Validar SO está confirmed
- [ ] Calcular qty_pending por línea (ordered - delivered)
- [ ] Validar que hay cantidades pendientes
- [ ] Copiar líneas con qty_pending > 0
- [ ] Generar número secuencial DO
- [ ] Vincular delivery.order_id
- [ ] Crear mensaje en chatter
- [ ] Unit tests (>80%)
- [ ] Integration tests
- [ ] Swagger docs

### Frontend
- [ ] Botón: "Create Delivery" en vista de SO confirmed
- [ ] Badge: Mostrar qty delivered / qty total en SO
- [ ] Tabla: Lista de deliveries asociadas a SO
- [ ] API client: `salesOrderApi.createDelivery(id)`
- [ ] Navegación automática a delivery creada
- [ ] Notificación toast de éxito
- [ ] Component tests
- [ ] E2E test: "should create delivery from sales order"

### Database
- [ ] Tabla: `inventory.deliveries` (id, order_id, number, state, date, location_from_id, location_to_id)
- [ ] Tabla: `inventory.delivery_lines` (id, delivery_id, product_id, qty_ordered, qty_done)
- [ ] FK: `inventory.deliveries.order_id → sales.orders.id`
- [ ] Índices: idx_deliveries_order_id, idx_deliveries_state
- [ ] RLS policy: company_isolation_deliveries

---

## Mockups / Wireframes

**Vista SO con botón Create Delivery:**
```
┌─────────────────────────────────────────────┐
│ Sales Order SO/2024/0001    [confirmed]     │
├─────────────────────────────────────────────┤
│ Cliente: ABC Corp                           │
│ Entregado: 60 / 100 unidades (60%)          │
│                                             │
│ Líneas:                                     │
│ • Producto A: 50/50 entregado ✓             │
│ • Producto B: 10/50 entregado ⚠             │
│                                             │
│ Entregas:                                   │
│ • DO/2024/0001 [done] - 60 unidades         │
│                                             │
│ [Create Delivery] [Create Invoice]          │
└─────────────────────────────────────────────┘
```

---

## Casos de Prueba

### Funcionales
1. **TC-001:** Crear delivery desde SO confirmed exitosamente
2. **TC-002:** Error si SO no está confirmed
3. **TC-003:** Error si no hay cantidades pendientes
4. **TC-004:** Delivery se crea solo con líneas pendientes
5. **TC-005:** Número secuencial generado correctamente
6. **TC-006:** delivery.order_id vinculado correctamente
7. **TC-007:** Mensaje creado en chatter
8. **TC-008:** Ubicaciones origen/destino correctas

### No Funcionales
1. **Performance:** < 500ms para crear delivery con 20 líneas
2. **Seguridad:** JWT + permiso stock_user

---

## Dependencias

- **US bloqueantes:**
  - US-MGN-007-002-002 (Confirmar SO)
  - US-MGN-005-002-001 (Gestionar Ubicaciones)
- **Módulos requeridos:** MGN-005 (Inventario)

---

## Notas de Implementación

- Calcular qty_pending por línea: `qty_ordered - SUM(deliveries.qty_done)`
- Frontend: Mostrar progress bar de entregas en SO
- Considerar permitir creación automática de delivery al confirmar SO
- Validar que warehouse_id esté configurado en SO

---

## Estimación Detallada

| Tarea | Horas |
|-------|-------|
| Backend | 2.5 |
| Frontend | 2 |
| Testing | 2 |
| Code Review | 0.5 |
| **TOTAL** | **7 horas = 5 SP** |

---

## Definition of Done

- [ ] Código implementado según ET
- [ ] Tests pasando (>80%)
- [ ] Code review aprobado
- [ ] Delivery se crea correctamente
- [ ] Solo líneas pendientes incluidas
- [ ] Número secuencial generado
- [ ] Vinculación a SO correcta
- [ ] Mensaje en chatter creado
- [ ] Swagger docs actualizado
- [ ] QA validado
- [ ] PO aprobado

---

## Referencias

- [RF-MGN-007-004](../../02-modelado/requerimientos-funcionales/mgn-007/RF-MGN-007-004-entregas-de-ventas.md)
- [ET Backend](../../02-modelado/especificaciones-tecnicas/backend/mgn-007/ET-BACKEND-MGN-007-004-entregas.md)
- [ET Frontend](../../02-modelado/especificaciones-tecnicas/frontend/mgn-007/ET-FRONTEND-MGN-007-004-entregas.md)
- [Traceability](../../02-modelado/trazabilidad/TRACEABILITY-MGN-007.yaml)
- [Schema](../../02-modelado/database-design/schemas/inventory-schema-ddl.sql)
