rckrdmrd/erp-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
f95b8d4577
erp-core/docs/05-user-stories/mgn-005/US-MGN-005-004-001-visualizar-stock-quants.md

6.4 KiB
Raw Blame History

US-MGN-005-004-001: Visualizar Stock por Ubicación (Quants)

RF Asociado: RF-MGN-005-003 Módulo: MGN-005 - Inventario Básico Epic: Stock Quants Prioridad: P0 Story Points: 4 Sprint: Sprint 10 Estado: Ready for Development Fecha: 2025-11-24

User Story

Como usuario de inventario, Quiero visualizar el stock disponible por producto y ubicación (quants), Para conocer dónde está almacenado cada producto y sus cantidades.

Descripción Detallada

Los stock quants (inventory.stock_quants) representan cantidades físicas de producto en ubicaciones específicas. Cada quant tiene:

  • product_id: Producto
  • location_id: Ubicación
  • quantity: Cantidad disponible
  • reserved_quantity: Cantidad reservada para pedidos

Esta US permite visualizar quants con filtros por producto, ubicación, almacén y estado (disponible, reservado).

Criterios de Aceptación

Escenario 1: Listar quants de un producto (Camino Feliz)

Dado que consulto quants del producto_id=1, Cuando obtengo la lista, Entonces el sistema retorna todos los quants con location, quantity, available_quantity.

Escenario 2: Filtrar quants por ubicación

Dado que consulto quants con location_id=10, Cuando obtengo la lista, Entonces el sistema retorna solo quants de esa ubicación.

Escenario 3: Calcular stock disponible (available = quantity - reserved)

Dado que quant tiene quantity=10 y reserved_quantity=3, Cuando consulto el quant, Entonces el sistema muestra available_quantity=7.

Escenario 4: Visualizar stock agregado por producto

Dado que consulto stock total de product_id=1, Cuando obtengo el agregado, Entonces el sistema suma quantities de todos los quants del producto.

Reglas de Negocio

  • RN-1: Quants muestran stock por ubicación específica.
  • RN-2: available_quantity = quantity - reserved_quantity.
  • RN-3: Quants con quantity=0 pueden ocultarse en la vista.
  • RN-4: RLS filtra quants por empresa.

Tareas Técnicas

Backend

  • Endpoint: GET /api/v1/inventory/stock-quants
  • Endpoint: GET /api/v1/inventory/stock-quants/by-product/:productId
  • Endpoint: GET /api/v1/inventory/stock-quants/by-location/:locationId
  • Service: QuantService.findAll(filters)
  • Service: QuantService.getStockByProduct(productId)
  • DTO: QueryQuantsDto (product_id, location_id, warehouse_id, include_zero)
  • Calcular available_quantity
  • Agregación por producto/ubicación
  • Unit tests
  • Integration tests
  • Swagger docs

Frontend

  • Componente: StockQuantsTable.tsx
  • Página: StockQuantsPage.tsx (/inventory/stock-quants)
  • Filtros: producto, ubicación, almacén
  • API client: quantApi.getAll(filters)
  • State management: useQuantStore
  • Component tests
  • E2E test: "should view stock quants"

Database

  • Tabla: inventory.stock_quants
  • Índices: idx_stock_quants_product_location
  • View: vw_stock_available (con available_quantity calculado)
  • RLS policy: company_isolation_quants

Mockups / Wireframes

Lista Stock Quants:

┌─────────────────────────────────────────────────────┐
│ Stock por Ubicación                                │
├─────────────────────────────────────────────────────┤
│ Filtros:                                           │
│ Producto: [Select ▼] Ubicación: [Select ▼]       │
│ [ Ocultar stock cero ]                            │
├─────────────────────────────────────────────────────┤
│ Producto      │Ubicación │Cantidad│Reservado│Disp.│
│───────────────┼──────────┼────────┼─────────┼─────│
│ Laptop HP     │Zona A-P1 │  10    │   3     │  7  │
│ Laptop HP     │Zona B-P2 │   5    │   0     │  5  │
│ Mouse Óptico  │Zona A-P1 │  50    │  10     │ 40  │
│───────────────┼──────────┼────────┼─────────┼─────│
│ TOTAL:                   │  65    │  13     │ 52  │
└─────────────────────────────────────────────────────┘

Casos de Prueba

Funcionales

  1. TC-001: Listar quants por producto
  2. TC-002: Filtrar quants por ubicación
  3. TC-003: Calcular available_quantity correctamente
  4. TC-004: Agregado de stock por producto
  5. TC-005: RLS filtra por empresa

No Funcionales

  1. Performance: < 300ms para listar quants
  2. Seguridad: JWT + permiso inventory_user

Dependencias

  • US bloqueantes: US-MGN-005-003-002 (Validar Movimiento - crea quants)
  • Módulos requeridos: MGN-001, MGN-002
  • Datos maestros: Ninguno

Notas de Implementación

  • Considerar crear vista materializada para consultas frecuentes
  • Frontend: Actualizar en tiempo real con polling o WebSocket
  • Agregar indicador visual para stock bajo (threshold)

Estimación Detallada

Tarea Horas
Backend 2
Frontend 2.5
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
  • RLS aplicado
  • QA validado
  • PO aprobado

Referencias