Documentación del Módulo de Inventario

Versión: 1.0
Fecha: 2026-01-12

1. Resumen Ejecutivo

El módulo de Inventario es el componente central para la gestión de productos, almacenes, ubicaciones y control de stock en la organización. Su propósito es mantener un registro preciso de las existencias, automatizar los movimientos de inventario y proporcionar trazabilidad completa de las operaciones de stock.

Valor para el Negocio:

• Control de Stock Real: Seguimiento preciso de niveles de inventario en tiempo real por almacén y ubicación.
• Trazabilidad Completa: Historial detallado de todos los movimientos de stock con origen polimórfico.
• Gestión Multi-Almacén: Soporte para múltiples almacenes con estructura jerárquica de ubicaciones.
• Transferencias Entre Almacenes: Flujo controlado de mercancías con validación de stock y estados.
• Ajustes de Inventario: Proceso de conteo físico con aprobación y generación automática de movimientos.
• Integración Contable: Vinculación con cuentas contables para valorización de inventario.

2. Arquitectura del Módulo

2.1. Componentes Principales

3. Flujos de Proceso

3.1. Flujo de Transferencia de Stock (StockTransfer)

Estados de StockTransfer:

3.2. Flujo de Ajuste de Inventario (StockAdjustment)

Estados de StockAdjustment:

3.3. Flujo de Movimiento de Stock (StockMove)

Estados de StockMove:

4. Lógica de Negocio y Reglas

4.1. Reglas de Productos

• SKU Único: Cada producto debe tener un SKU único en el sistema.
• Tipo de Producto: Define si el producto es almacenable, consumible o servicio.
• Cuenta Contable Efectiva: Si el producto no tiene cuenta asignada, hereda de su categoría.
• Stock Mínimo/Máximo: Alertas configurables por producto para gestión de reposición.
• Lote/Serie: Productos pueden requerir trazabilidad por lote o número de serie.
• Vencimiento: Productos pueden requerir control de fecha de expiración.

4.2. Reglas de Almacenes

• Eliminación Bloqueada: No se puede eliminar un almacén si tiene:
  • Movimientos de stock asociados
  • Transferencias de stock (origen o destino)
  • Ajustes de inventario
  • Ubicaciones con stock positivo
• Vinculación a Sucursal: Cada almacén pertenece a una sucursal específica.

4.3. Reglas de Ubicaciones

• Estructura Jerárquica: Las ubicaciones pueden tener ubicaciones hijas (árbol).
• Herencia de Almacén: La ubicación hija hereda automáticamente el warehouse_id del padre.
• Cálculo de Path: El path se construye automáticamente: padre.path/hijo.code.
• Profundidad Automática: depth = padre.depth + 1.
• Capacidad Física: Las ubicaciones pueden definir dimensiones y peso máximo.

4.4. Reglas de Transferencias

• Validación de Stock: Al marcar como LISTO, se valida que exista stock suficiente.
• Despacho: Genera movimientos negativos en el almacén origen.
• Recepción: Genera movimientos positivos en el almacén destino.
• Cancelación en Tránsito: Revierte los movimientos negativos ya generados.
• Edición Limitada: Solo se puede editar en estados BORRADOR y LISTO.

4.5. Reglas de Ajustes

• Diferencia Calculada: diferencia = cantidad_contada - cantidad_teórica.
• Clasificación Automática:
  • Diferencia > 0: Sobrante (genera movimiento positivo)
  • Diferencia < 0: Faltante (genera movimiento negativo)
  • Diferencia = 0: Sin cambio (no genera movimiento)
• Aprobación Requerida: Los ajustes deben ser aprobados antes de completarse.
• Registro de Aprobador: Se registra quién aprobó el ajuste.

4.6. Sincronización de Stock

El modelo StockMove sincroniza automáticamente los niveles de stock vía hooks en boot():

StockMove::boot()
    ├── created() → Si state = 'realizado' → syncStockLevel()
    └── updated() → Si cambió state/quantity/location → syncStockLevel()
                        ↓
              Recalcula StockLevel (product_id, warehouse_id, location_id)
                        ↓
              Actualiza quantity y last_movement_at

5. Modelo de Datos Detallado

5.1. Entidades de Productos

5.2. Entidades de Infraestructura

5.3. Entidades de Stock

5.4. Entidades de Operaciones

6. Casos de Uso

6.1. Gestión de Productos

• CU-01: Creación de Producto: Registro de nuevo producto con SKU, precios y configuración de stock.
• CU-02: Categorización: Asignación de productos a categorías con cuentas contables heredables.
• CU-03: Configuración de Alertas: Definición de niveles mínimos y máximos de stock.
• CU-04: Consulta de Stock: Visualización de stock por almacén y ubicación.

6.2. Gestión de Almacenes

• CU-05: Creación de Almacén: Registro de nuevo almacén vinculado a sucursal.
• CU-06: Creación de Ubicaciones: Estructura jerárquica de ubicaciones dentro del almacén.
• CU-07: Gestión de Capacidad: Definición de dimensiones y límites por ubicación.

6.3. Operaciones de Inventario

• CU-08: Transferencia Entre Almacenes: Movimiento de productos entre almacenes con validación.
• CU-09: Ajuste de Inventario: Conteo físico con registro de diferencias y aprobación.
• CU-10: Consulta de Movimientos: Historial detallado de movimientos por producto.

7. Guía de Configuración

7.1. Tipos de Producto (ProductType)

7.2. Estados de Ubicación (LocationStatus)

7.3. Configuración de Categorías

Las categorías definen cuentas contables por defecto que los productos heredan:

8. Sincronización de Stock (Model Hooks)

8.1. StockMove Boot Hooks

Siguiendo la guía de implementación del proyecto, la lógica de sincronización está en el modelo StockMove vía boot():

Método syncStockLevel:

protected static function syncStockLevel(StockMove $stockMove): void
{
    $stockLevel = StockLevel::firstOrNew([...]);
    $totalQuantity = static::where('state', StockMoveState::REALIZADO)->sum('quantity');
    $stockLevel->quantity = $totalQuantity;
    $stockLevel->last_movement_at = now();
    $stockLevel->save();
}

Nota: Esta arquitectura sigue la guía: "La lógica de negocio vive en el Modelo, NO en Observers externos."

9. Matriz de Roles y Permisos (RBAC)

10. Reportes y Exportación

10.1. Exportadores Disponibles

Acceso: Botón "Exportar" en la cabecera de las tablas correspondientes.

10.2. Indicadores Clave

11. Solución de Problemas (Troubleshooting)

Error: "No se puede eliminar el almacén porque tiene movimientos de stock asociados"

• Causa: El almacén tiene StockMoves registrados.
• Solución: Los almacenes con historial no pueden eliminarse. Considere desactivarlo (is_active = false).

Error: "No se puede eliminar el almacén porque tiene ubicaciones asociadas"

• Causa: Existen ubicaciones vinculadas al almacén.
• Solución: Elimine primero todas las ubicaciones del almacén.

Error: "No se puede eliminar el almacén porque tiene niveles de stock positivo"

• Causa: Existen productos con stock > 0 en el almacén.
• Solución: Realice transferencias para vaciar el almacén antes de eliminarlo.

Error: "Stock insuficiente para la transferencia"

• Causa: El almacén origen no tiene suficiente stock del producto.
• Solución: Verifique el stock disponible y ajuste las cantidades de la transferencia.

Error: "No se puede editar, la transferencia está EN_TRANSITO"

• Causa: La mercancía ya fue despachada.
• Solución: Complete la recepción o cancele la transferencia (revertirá los movimientos).

Error: "El ajuste debe tener al menos una línea"

• Causa: Se intenta aprobar un ajuste sin líneas de conteo.
• Solución: Agregue líneas de ajuste con productos y cantidades contadas.

12. Integraciones

12.1. Integración con Contabilidad

Los productos y categorías se vinculan con cuentas contables:

• Cuenta de Stock: Para valorización del inventario (Activo).
• Cuenta de Gasto: Para costo de ventas (Gasto).
• Cuenta de Ingreso: Para ingresos por ventas (Ingreso).

12.2. Integración con Ventas

Los movimientos de stock se generan automáticamente desde:

• Facturas de Venta: Movimientos negativos al confirmar venta.
• Facturas de Compra: Movimientos positivos al recibir mercancía.

12.3. Origen Polimórfico de Movimientos

El campo origin_type / origin_id permite rastrear el origen de cada movimiento:

13. Anexos

13.1. Enums del Módulo

13.2. Diagrama de Relaciones

Documentación generada automáticamente el 2026-01-12. Versión 1.0.