5.4 KiB
US-MGN-007-005-002: Validar Devolución y Ajustar Stock
RF Asociado: RF-MGN-007-004 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
- TC-001: Validar return exitosamente
- TC-002: Error si return ya validado
- TC-003: Stock_moves creados correctamente
- TC-004: Stock_quants actualizado (+qty)
- TC-005: delivery.qty_returned actualizado
- TC-006: date_done registrado correctamente
No Funcionales
- Performance: < 500ms para validar return
- 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