📦 Inventarios

---

1. 🧩 Descripción General

El módulo de Inventarios tiene como objetivo registrar, controlar y analizar los movimientos físicos y virtuales de los productos en stock, incluyendo su entrada, salida, ubicación, reservas y ajustes. Es un módulo central que se conecta directamente con Compras, Ventas, Producción, Finanzas y Facturación.

---

2. 🧱 Modelos del Módulo

a. Product

• id: integer (PK)
• name: string
• sku: string (único)
• category_id: FK → ProductCategory
• unit: string (pieza, litro, etc.)
• description: text
• track_batches: boolean
• track_lots: boolean
• is_active: boolean

b. Warehouse

• id: integer (PK)
• name: string
• location: string (texto libre)
• is_main: boolean

c. Stock

• id: integer (PK)
• product_id: FK → Product
• warehouse_id: FK → Warehouse
• quantity: decimal
• reserved: decimal
• minimum: decimal
• maximum: decimal

d. ProductBatch

• id: integer (PK)
• product_id: FK → Product
• batch_number: string
• expiry_date: date
• stock_id: FK → Stock

e. StockMovement

• id: integer (PK)
• stock_id: FK → Stock
• type: enum (entrada, salida, ajuste, traslado)
• quantity: decimal
• description: string
• source: string (compra, venta, devolución, etc.)
• user_id: FK → User

---

3. 🔁 Funciones del Controlador

• index(): Lista de productos con su stock actual y ubicación.
• store(): Alta de productos o inicialización de stock.
• show($id): Consulta detallada del inventario de un producto.
• update($id): Edición de producto o ajuste de stock.
• destroy($id): Desactivación lógica del producto.
• moveStock(): Movimiento entre almacenes.
• registerBatch(): Alta de lotes con fecha de caducidad.
• report(): Consulta de reportes de inventario (Kardex, mínimos, etc.)

---

4. 🌐 Endpoints detallados y justificados

Método	Ruta	Descripción	Justificación de negocio
GET	/api/products	Listado general de productos	Permite al usuario ver existencias por almacén
POST	/api/products	Crear un nuevo producto	Registro de nuevos SKUs
GET	/api/products/{id}	Detalle del producto con inventario por almacén	Información detallada de stock y lotes
PUT	/api/products/{id}	Editar producto o existencias mínimas	Ajustes administrativos
DELETE	/api/products/{id}	Desactivar un producto	Control de catálogo sin eliminar histórico
POST	/api/stock/move	Mover stock entre almacenes	Soporte a logística
POST	/api/batch/register	Registrar lote de producto	Trazabilidad de productos por fecha/lote
GET	/api/stock/report	Consulta de reportes	Decisiones logísticas y operativas

---

5. 🖥️ Diseño UX sugerido (flujo de usuario)

Pantalla principal: "Control de Inventarios"

• Tabla con productos y stock por almacén
• Botones:
  • Ver detalle
  • Editar
  • Mover stock
  • Agregar lote

Pantalla secundaria: "Detalle del Producto"

• Información del producto
• Lista de almacenes con stock
• Acciones:
  • Ajustar existencia
  • Ver movimientos
  • Ver lotes

Pantalla: "Movimientos"

• Tabla con entradas, salidas, ajustes
• Filtros por tipo, fecha, producto

---

6. 📄 Vistas sugeridas (tipo wireframe)

Vista	Campos sugeridos	Acciones
Inventario general	SKU, nombre, cantidad, almacén, mínimo, máximo	Ver, Mover, Editar
Formulario producto	Nombre, SKU, unidad, categoría, ¿lleva lote?	Guardar
Movimiento de stock	Producto, origen, destino, cantidad	Ejecutar
Lotes por producto	Lote, cantidad, caducidad, almacén	Ver

---

7. 🔗 Conexión Frontend ↔ API JSON:API

Acción en Frontend	Método/API	Función esperada
Cargar productos al iniciar	GET /api/products	Mostrar tabla
Crear nuevo producto	POST /api/products	Enviar formulario
Ver detalles de un producto	GET /api/products/{id}	Mostrar almacenes y lotes
Mover producto	POST /api/stock/move	Enviar origen, destino y cantidad
Registrar lote	POST /api/batch/register	Enviar datos de lote
Ver reportes	GET /api/stock/report	Obtener Kardex, mínimos, etc.

---

🧩 Este documento sirve como guía para desarrolladores backend y frontend. Contiene la lógica de negocio, el diseño UX básico y la conexión entre ambos para mantener coherencia funcional en el desarrollo del módulo de Inventarios.