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

**RF Asociado:** [RF-MGN-005-003](../../02-modelado/requerimientos-funcionales/mgn-005/RF-MGN-005-003-movimientos-de-stock.md)
**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

- [RF-MGN-005-003](../../02-modelado/requerimientos-funcionales/mgn-005/RF-MGN-005-003-movimientos-de-stock.md)
- [ET Backend](../../02-modelado/especificaciones-tecnicas/backend/mgn-005/ET-BACKEND-MGN-005-003-movimientos-de-stock.md)
- [ET Frontend](../../02-modelado/especificaciones-tecnicas/frontend/mgn-005/ET-FRONTEND-MGN-005-003-movimientos-de-stock.md)
- [Traceability](../../02-modelado/trazabilidad/TRACEABILITY-MGN-005.yaml)
- [Schema](../../02-modelado/database-design/schemas/inventory-schema-ddl.sql)