Sistema de Gestión de Almacén (WMS) con Escáner Móvil Offline y Trazabilidad Total

// 01_EL RETO

El reto

La planta operaba con un ERP corporativo que gestionaba el inventario únicamente a nivel de almacén (grandes áreas), sin precisión sobre la ubicación física exacta de los materiales. Cada mañana, una persona recorría el almacén contando manualmente en hojas de papel lo que había disponible por lote y tipo de producto, pero para saber dónde estaba ubicado un material específico había que preguntar a los operadores, ya que no existía un control que evitara dejar lotes dispersos en múltiples ubicaciones. Las etiquetas para todo lo que no era producto terminado (materias primas, insumos, refacciones) se generaban manualmente en Excel, sin códigos de barras ni QR, lo que dificultaba la identificación. Los vales de salida eran físicos (papel) y con frecuencia se extraviaban, obligando a buscar en archivos muertos para reconstruir movimientos antiguos. Esta dinámica generaba errores de inventario, retrasos en la localización de materiales, y pérdida de trazabilidad.

// 02_ROLE

Mi rol y tecnologías

Diseño de la arquitectura hexagonal del WMS como subsistema semi-autónomo, implementación del backend (dominio, servicios de aplicación, repositorios, API REST), desarrollo del frontend React (gestión de ubicaciones, materiales, movimientos, escáner móvil, etiquetas), integración con el módulo de seguridad de Kairos (JWT, permisos), y lógica de ciclos de inventario físico con resolución de discrepancias.

• Modelado de entidades: Location (jerárquica), Material, Stock, Movement, InventoryCycle, InventoryCount, AuditLog, con herencia de tipos y restricciones de profundidad, permitiendo ubicar materiales a nivel de bin individual.
• Implementación de la jerarquía de ubicaciones con validación de tipos permitidos (ALLOWED_CHILDREN) y generación automática de códigos, para estandarizar la nomenclatura de almacenes, zonas, racks, niveles y bins.
• Máquina de estados de movimientos (Borrador → Pendiente → Aprobado → Completado / Cancelado) con lógica de mutación de stock solo al completar, y verificación de disponibilidad y capacidad, reemplazando los vales en papel.
• Captura de firma digital en canvas con exportación a Base64 PNG y almacenamiento en la tabla de movimientos, digitalizando la validación de salidas.
• Servicio de generación de etiquetas SVG para ubicaciones, materiales y unidades de stock, con codificación QR (JSON comprimido) y código de barras Code128, eliminando las etiquetas de Excel y permitiendo impresión en impresoras térmicas estándar.
• Módulo de ciclos de inventario físico: planificación con selector de árbol de ubicaciones, toma de snapshot de stock al iniciar (in_progress), escaneo móvil con jsQR y almacenamiento local (localStorage) para operación en áreas sin cobertura, eliminando los conteos manuales en papel.
• Resolución de discrepancias con tres estrategias (ajustado, aceptado, rechazado) y auditoría completa de cambios en ubicaciones, materiales, stock, movimientos y ciclos, con almacenamiento de old_values y new_values en JSONB, permitiendo reconstruir cualquier movimiento histórico sin recurrir a archivos muertos.
• Integración con el módulo de seguridad de Kairos: validación de JWT y verificación de permisos (wms:action:resource) mediante WMSPermissionChecker, y registro automático de rutas protegidas en el backend central, manteniendo coherencia con el sistema ERP existente a nivel de almacenes.

// 03_SOLUTION

Solución e impacto

El WMS se desplegó como un subsistema semi-autónomo con arquitectura hexagonal, con su propia base de datos PostgreSQL y API FastAPI, integrado al ecosistema Kairos mediante Nginx (proxy) y el módulo de seguridad central, y complementando al ERP existente añadiendo la granularidad de ubicaciones que este no proporcionaba. La jerarquía de ubicaciones permite organizar el almacén hasta 5 niveles (almacén → zona → rack → nivel → bin) con validación de tipos, de modo que cualquier material se asigna a un bin específico y se controla que no quede disperso en múltiples ubicaciones. Los movimientos de inventario reemplazan los vales de papel: se crean digitalmente con una máquina de estados, permiten captura de firma en canvas y, al completarse, actualizan el stock en tiempo real. El sistema genera etiquetas SVG con QR y código de barras para todos los elementos (no solo producto terminado), lo que permite escaneo rápido con la aplicación móvil. La aplicación móvil, basada en jsQR, funciona offline almacenando los escaneos en localStorage y sincronizando automáticamente al recuperar cobertura, eliminando la dependencia de una persona haciendo conteos manuales cada mañana. Los ciclos de inventario físico se planifican desde el frontend, se toma un snapshot del stock esperado, y los operadores escanean ubicaciones con el móvil; las discrepancias se resuelven con tres estrategias documentadas en la auditoría. Cada cambio queda registrado en la tabla de auditoría con diffs en JSONB, proporcionando trazabilidad total y permitiendo consultar movimientos históricos sin buscar en archivos físicos.

// 04_RESULTS

Resultados