# US-MGN-007-005-002: Validar Devolución y Ajustar Stock

**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:** Devoluciones de Ventas
**Prioridad:** P1
**Story Points:** 2
**Sprint:** Sprint 17
**Estado:** Ready for Development
**Fecha:** 2025-11-24

---

## User Story

**Como** usuario de almacén,
**Quiero** validar devoluciones recibidas físicamente,
**Para** incrementar el stock y registrar el ingreso de productos devueltos.

---

## Descripción Detallada

Validar una return significa:
- Cambiar estado draft → done
- Crear stock_moves: ubicación_cliente → almacén
- Actualizar stock_quants sumando al almacén
- Registrar date_done
- Crear mensaje en chatter
- Opcional: Notificar a ventas para gestionar reemplazo/reembolso

---

## Criterios de Aceptación

### Escenario 1: Validar return exitosamente (Camino Feliz)
**Dado que** return id=1 en draft con product_id=1, qty=10,
**Cuando** valido return,
**Entonces** estado=done, crea stock_move (cliente → almacén), suma +10 en quants, registra date_done.

### Escenario 2: Validar que return está en draft
**Dado que** return ya está en done,
**Cuando** intento validar,
**Entonces** sistema retorna error 400 "La devolución ya está validada".

### Escenario 3: Actualizar qty_returned en delivery origen
**Dado que** return proviene de delivery id=1,
**Cuando** valido return de 10 unidades,
**Entonces** delivery.qty_returned += 10.

### Escenario 4: Registrar fecha de validación
**Dado que** valido return exitosamente,
**Cuando** se completa,
**Entonces** date_done registra timestamp actual.

---

## Reglas de Negocio

- **RN-1:** Solo returns en draft pueden validarse.
- **RN-2:** Crea stock_moves (location_from=cliente → location_to=almacén).
- **RN-3:** Actualiza stock_quants sumando cantidades.
- **RN-4:** Si tiene delivery origen, actualiza delivery.qty_returned.
- **RN-5:** date_done registra timestamp de validación.
- **RN-6:** Permisos: stock_user.

---

## Tareas Técnicas

### Backend
- [ ] Endpoint: `POST /api/v1/sales/returns/:id/validate`
- [ ] Service: `ReturnService.validate(id)`
- [ ] Validar estado draft
- [ ] Crear stock_moves (cliente → almacén)
- [ ] Actualizar stock_quants (+qty)
- [ ] Actualizar delivery.qty_returned si aplica
- [ ] Actualizar state=done, date_done=now()
- [ ] Crear mensaje en chatter
- [ ] Unit tests (>80%)
- [ ] Integration tests
- [ ] Swagger docs

### Frontend
- [ ] Botón: "Validate" en vista de return draft
- [ ] Confirmación modal antes de validar
- [ ] API client: `returnApi.validate(id)`
- [ ] Notificación toast de éxito
- [ ] Component tests
- [ ] E2E test: "should validate return and adjust stock"

### Database
- [ ] Columna: `sales.returns.date_done` (timestamp)
- [ ] Columna: `inventory.deliveries.qty_returned` (numeric)

---

## Mockups / Wireframes

**Vista Return con validación:**
```
┌─────────────────────────────────────────────┐
│ Return RET/2024/0001        [draft]         │
├─────────────────────────────────────────────┤
│ Cliente: ABC Corp                           │
│ Motivo: Producto defectuoso                 │
│                                             │
│ Productos:                                  │
│ • Laptop HP: 10 unidades                    │
│                                             │
│ [Validate Return] [Cancel]                  │
└─────────────────────────────────────────────┘
```

---

## Casos de Prueba

### Funcionales
1. **TC-001:** Validar return exitosamente
2. **TC-002:** Error si return ya validado
3. **TC-003:** Stock_moves creados correctamente
4. **TC-004:** Stock_quants actualizado (+qty)
5. **TC-005:** delivery.qty_returned actualizado
6. **TC-006:** date_done registrado correctamente

### No Funcionales
1. **Performance:** < 500ms para validar return
2. **Seguridad:** JWT + permiso stock_user

---

## Dependencias

- **US bloqueantes:**
  - US-MGN-007-005-001 (Crear Devolución)
  - US-MGN-005-003-002 (Validar Movimiento Stock)

---

## Notas de Implementación

- Usar transacción para atomicidad (stock_moves + quants + delivery)
- Considerar inspección de calidad antes de validar (estado intermedio: received)
- Frontend: Permitir agregar notas de inspección

---

## Estimación Detallada

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

---

## Definition of Done

- [ ] Código implementado según ET
- [ ] Tests pasando (>80%)
- [ ] Code review aprobado
- [ ] Validación funciona correctamente
- [ ] Stock actualizado correctamente
- [ ] delivery.qty_returned actualizado
- [ ] date_done registrado
- [ ] 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)
- [Traceability](../../02-modelado/trazabilidad/TRACEABILITY-MGN-007.yaml)
- [Schema](../../02-modelado/database-design/schemas/sales-schema-ddl.sql)