# US-MGN-006-004-001: Crear Devolución a Proveedor

**RF Asociado:** [RF-MGN-006-004](../../02-modelado/requerimientos-funcionales/mgn-006/RF-MGN-006-004-recepciones-de-compras.md)
**Módulo:** MGN-006 - Compras Básico
**Epic:** Devoluciones a Proveedores
**Prioridad:** P1
**Story Points:** 3
**Sprint:** Sprint 15
**Estado:** Ready for Development
**Fecha:** 2025-11-24

---

## User Story
**Como** usuario de compras,
**Quiero** crear devoluciones de productos a proveedores,
**Para** retornar mercancía defectuosa o incorrecta.

---

## Descripción Detallada
Una devolución (return) crea un picking de tipo outgoing (inverso a recepción). Incluye:
- Referencia a PO y recepción original
- Productos y cantidades a devolver
- Motivo de devolución
- Se puede crear crédito nota automático

---

## Criterios de Aceptación

### Escenario 1: Crear devolución desde recepción (Camino Feliz)
**Dado que** tengo recepción validada con producto A qty=10,
**Cuando** creo devolución de 3 unidades con motivo="Producto defectuoso",
**Entonces** sistema crea picking return con línea producto A qty=3, motivo guardado.

### Escenario 2: Validar cantidad a devolver
**Dado que** producto recibido fue 10 unidades, ya devolví 2,
**Cuando** intento devolver 9 unidades,
**Entonces** sistema retorna error "Cantidad excede lo recibido (disponible para devolución: 8)".

### Escenario 3: Crear nota de crédito automática
**Dado que** valido devolución,
**Cuando** marco opción "Crear nota de crédito",
**Entonces** sistema genera credit note (vendor refund) con valores de líneas devueltas.

---

## Reglas de Negocio
- **RN-1:** Solo se pueden devolver productos recibidos.
- **RN-2:** Cantidad devuelta ≤ cantidad recibida - devoluciones previas.
- **RN-3:** Devolución genera picking outgoing.
- **RN-4:** Opcionalmente genera nota de crédito.

---

## Tareas Técnicas

### Backend
- [ ] Endpoint: POST /api/v1/purchase/returns
- [ ] Service: PurchaseReturnService.create(dto)
- [ ] Service: validateReturnQuantity(poLineId, qty)
- [ ] DTO: CreateReturnDto, ReturnLineDto
- [ ] Validar cantidades
- [ ] Unit tests
- [ ] Integration tests
- [ ] Swagger docs

### Frontend
- [ ] Componente: CreateReturnForm.tsx
- [ ] Selector de recepción origen
- [ ] Tabla con cantidades disponibles para devolver
- [ ] Campo motivo requerido
- [ ] API client: purchaseReturnApi.create()
- [ ] Component tests
- [ ] E2E test

### Database
- [ ] Tabla: purchase.purchase_returns
- [ ] Tabla: purchase.purchase_return_lines
- [ ] Índices: idx_returns_po_id

---

## Estimación Detallada
| Tarea | Horas |
|-------|-------|
| Backend | 2 |
| Frontend | 2 |
| Testing | 1 |
| Code Review | 0.5 |
| **TOTAL** | **5.5 horas = 3 SP** |

---

## Definition of Done
- [ ] Código implementado según ET
- [ ] Tests pasando (>80%)
- [ ] Code review aprobado
- [ ] Validaciones correctas
- [ ] QA validado
- [ ] PO aprobado

---

## Referencias
- [RF-MGN-006-004](../../02-modelado/requerimientos-funcionales/mgn-006/RF-MGN-006-004-recepciones-de-compras.md)
- [Traceability](../../02-modelado/trazabilidad/TRACEABILITY-MGN-006.yaml)