6.6 KiB
US-MGN-005-004-002: Reservar Stock para Pedidos
RF Asociado: RF-MGN-005-003 Módulo: MGN-005 - Inventario Básico Epic: Stock Quants Prioridad: P1 Story Points: 4 Sprint: Sprint 10 Estado: Ready for Development Fecha: 2025-11-24
User Story
Como sistema de ventas, Quiero reservar stock en ubicaciones para pedidos confirmados, Para garantizar disponibilidad y evitar sobreventa.
Descripción Detallada
La reserva de stock incrementa reserved_quantity en stock_quants sin mover físicamente el producto. Esto asegura que el stock esté comprometido para un pedido específico.
Cuando se valida una entrega, la reserva se libera y el stock se mueve físicamente (quantity se decrementa).
Criterios de Aceptación
Escenario 1: Reservar stock disponible (Camino Feliz)
Dado que ubicación Zona A tiene product=1, quantity=10, reserved=0, Cuando reservo 5 unidades, Entonces el sistema actualiza reserved_quantity=5, available=5.
Escenario 2: Error al reservar más del disponible
Dado que ubicación tiene quantity=10, reserved=3 (available=7), Cuando intento reservar 8 unidades, Entonces el sistema retorna error 400 "Stock disponible insuficiente (disponible: 7, solicitado: 8)".
Escenario 3: Liberar reserva
Dado que ubicación tiene quantity=10, reserved=5, Cuando libero 5 unidades de reserva, Entonces el sistema actualiza reserved_quantity=0, available=10.
Escenario 4: Reservar en múltiples ubicaciones
Dado que necesito reservar 15 unidades de product=1, Cuando hay 10 en Zona A y 8 en Zona B, Entonces el sistema reserva 10 de Zona A y 5 de Zona B.
Reglas de Negocio
- RN-1: reserved_quantity no puede exceder quantity.
- RN-2: available_quantity = quantity - reserved_quantity.
- RN-3: Reservas se vinculan a pedidos de venta (sale_order_line_id).
- RN-4: Liberar reserva restaura available_quantity.
- RN-5: Reservas pueden distribuirse en múltiples ubicaciones.
Tareas Técnicas
Backend
- Endpoint: POST /api/v1/inventory/stock-quants/reserve
- Endpoint: POST /api/v1/inventory/stock-quants/unreserve
- Service: QuantService.reserve(productId, quantity, orderId)
- Service: QuantService.unreserve(productId, quantity, orderId)
- Service: QuantService.findAvailableLocations(productId, quantity)
- DTO: ReserveStockDto (product_id, quantity, order_id)
- Validar stock disponible
- Actualizar reserved_quantity
- Manejar reservas en múltiples ubicaciones
- Transaction para atomicidad
- Unit tests
- Integration tests
- Swagger docs
Frontend
- Componente: ReserveStockButton.tsx
- Modal de confirmación
- API client: quantApi.reserve(data)
- Component tests
- E2E test: "should reserve stock"
Database
- Tabla: inventory.stock_reservations (opcional - tracking de reservas)
- Transaction isolation level: READ COMMITTED
- Lock: SELECT FOR UPDATE en quants
Mockups / Wireframes
Modal Reservar Stock:
┌─────────────────────────────────────────────┐
│ Reservar Stock │
├─────────────────────────────────────────────┤
│ Pedido: SO-00123 │
│ Producto: Laptop HP │
│ Cantidad a Reservar: 15 unidades │
│ │
│ Distribución Propuesta: │
│ ┌───────────────────────────────────────┐ │
│ │Ubicación │Disponible│Reservar │ │
│ ├──────────┼──────────┼────────────────┤ │
│ │Zona A-P1 │ 10 │ 10 [✓] │ │
│ │Zona B-P2 │ 8 │ 5 [✓] │ │
│ └───────────────────────────────────────┘ │
│ │
│ Total Reservado: 15 / 15 ✓ │
├─────────────────────────────────────────────┤
│ [Confirmar Reserva] [Cancelar] │
└─────────────────────────────────────────────┘
Casos de Prueba
Funcionales
- TC-001: Reservar stock disponible exitosamente
- TC-002: Error por stock insuficiente
- TC-003: Liberar reserva exitosamente
- TC-004: Reservar en múltiples ubicaciones
- TC-005: Transaction rollback en caso de error
- TC-006: RLS filtra por empresa
No Funcionales
- Performance: < 400ms para reservar stock
- Seguridad: JWT + permiso inventory_user
Dependencias
- US bloqueantes: US-MGN-005-004-001 (Visualizar Quants)
- Módulos requeridos: MGN-007 (Ventas - opcional)
- Datos maestros: Ninguno
Notas de Implementación
- Usar SELECT FOR UPDATE para evitar condiciones de carrera
- Algoritmo de selección de ubicaciones: FIFO (primeras ubicaciones con stock)
- Considerar tabla stock_reservations para trazabilidad detallada
- Frontend: Mostrar preview de distribución antes de confirmar
Estimación Detallada
| Tarea | Horas |
|---|---|
| Backend | 2.5 |
| Frontend | 2 |
| Testing | 1.5 |
| Code Review | 0.5 |
| TOTAL | 6.5 horas = 4 SP |
Definition of Done
- Código implementado según ET
- Tests pasando (>80%)
- Code review aprobado
- Documentación actualizada
- Swagger docs completo
- Transaction correctamente implementada
- RLS aplicado
- QA validado
- PO aprobado