SIO-Control

Sistema web para control de inventario físico, auditoría de conteos y validación multiusuario en tiempo real.

SIO-Control permite cargar el PDF diario de inventario, generar la estructura de categorías y productos, capturar conteos físicos por usuario, comparar resultados entre contadores, validar diferencias y exportar el inventario final en PDF.

Descripción General

SIO-Control es una aplicación interna orientada al conteo operativo de inventario. Su objetivo es centralizar el proceso de revisión física de productos, reducir errores de captura y conservar trazabilidad por usuario, producto y movimiento.

El sistema se usa principalmente en contextos de:

• Inventario diario o periódico.
• Auditoría de existencias.
• Conteo físico en almacén o CEDIS.
• Comparación de conteos realizados por distintos usuarios.
• Generación de un conteo final validado.

El flujo inicia con un PDF de inventario. A partir de ese documento, la aplicación detecta categorías, productos, stock registrado, cantidad no disponible y metadatos como fecha, semana y CEDIS. Después, los usuarios realizan conteos independientes y el auditor puede comparar, corregir y validar el resultado.

Funcionalidades Principales

Conteo de inventario en tiempo real

• Los usuarios autenticados pueden capturar cantidades físicas por producto.
• Cada captura se guarda como un movimiento dentro del historial del producto.
• El sistema recalcula automáticamente total contado, diferencia contra stock y avance del inventario.
• La interfaz muestra el estado del producto: pendiente, coincide, sobrante o faltante.
• El conteo puede consultarse por categoría, búsqueda global o filtros operativos.

Historial por producto

Cada producto conserva un historial de movimientos de conteo con:

• Cantidad capturada.
• Estado u observación del producto.
• Comentario opcional.
• Usuario que registró el movimiento.
• Fecha/hora de creación.
• Usuario y fecha/hora de modificación cuando aplica.

Este historial permite auditar cómo se llegó al total físico de cada producto.

Edición de conteos

El sistema permite:

• Agregar nuevos registros de conteo.
• Editar cantidades, observaciones y comentarios.
• Eliminar movimientos incorrectos.
• Recalcular totales después de cada cambio.

En el flujo de comparación, el auditor también puede corregir registros de los conteos seleccionados.

Comparación de conteos multiusuario

SIO-Control permite comparar dos conteos independientes del mismo inventario. La pantalla de comparación muestra:

• Conteo del Usuario A.
• Conteo del Usuario B.
• Diferencia entre ambos conteos.
• Productos coincidentes.
• Productos con diferencias.
• Productos pendientes.
• Productos con observaciones.
• Productos ya validados por auditoría.

La comparación exige al menos dos usuarios con conteos registrados.

Validación de inventario

El auditor puede validar producto por producto cuando existen diferencias. Antes de generar el conteo final, el sistema verifica que no existan diferencias sin revisar.

La validación deja trazabilidad mediante:

• Producto validado.
• Usuario auditor que valida.
• Fecha de actualización.
• Estado del inventario.

Exportación a PDF

El sistema genera un PDF exportable del inventario usando el conteo final validado cuando existe. Si todavía no existe conteo final, usa el conteo activo o el primer conteo guardado disponible.

El PDF incluye:

• Encabezado del inventario.
• Semana, fecha y CEDIS.
• Categorías.
• Productos.
• Stock del PDF.
• Cantidad no disponible.
• Conteo físico.
• Total contado.
• Diferencia.
• Observaciones.
• Totales por categoría.
• Total general.

Sincronización en tiempo real

La aplicación usa Firebase Firestore con suscripciones en tiempo real. Los cambios de conteo, comparación, validación e historial se reflejan automáticamente en las pantallas conectadas sin recargar el navegador.

Sistema de roles

SIO-Control maneja permisos por perfil:

• contador: usuario operativo que realiza conteos.
• auditor: usuario con permisos de validación y comparación.
• admin_auditor: usuario auditor con privilegios administrativos.

Además, existe un correo administrador configurado en el sistema que obtiene permisos de auditoría automáticamente.

Administración de usuarios

Los usuarios con permisos de auditoría pueden acceder a la administración de usuarios para:

• Consultar usuarios registrados.
• Buscar por nombre o correo.
• Filtrar por rol.
• Cambiar rol de usuario.
• Activar o desactivar acceso.

Flujo del Sistema

1. Subir PDF de inventario

   • El usuario carga el PDF diario desde la pantalla de carga.
   • El sistema lee el contenido real del archivo con pdfjs-dist.
   • Se extraen metadatos como semana, fecha, CEDIS y total general.

2. Generación de categorías y productos

   • El parser interpreta líneas del PDF.
   • Las categorías se convierten en bloques principales.
   • Los productos se asignan a su categoría correspondiente.
   • Se conserva el orden original detectado en el PDF.

3. Conteo por usuario

   • Cada usuario autenticado trabaja sobre su propio conteo individual.
   • El sistema crea o asocia un registro dentro de userCounts.
   • Las cantidades capturadas se almacenan como movimientos por producto.

4. Registro de historial por producto

   • Cada captura queda registrada en countEntries.
   • Un producto puede tener varios movimientos.
   • El total contado se calcula sumando los movimientos del producto.

5. Comparación de conteos

   • El auditor selecciona dos conteos de usuarios.
   • El sistema compara producto por producto.
   • Se muestran coincidencias, diferencias y pendientes.

6. Corrección por auditor

   • El auditor puede agregar, editar o eliminar movimientos dentro de los conteos comparados.
   • Las correcciones actualizan Firestore y recalculan los totales.
   • Los productos con diferencias pueden marcarse como validados.

7. Generación de conteo final

   • Cuando las diferencias están revisadas, el auditor genera el conteo final.
   • El sistema crea finalCount con estado validado.
   • El inventario cambia a estado validado.

8. Guardado en historial

   • Los inventarios se listan en el historial por fecha de actualización.
   • El historial muestra participantes, totales, diferencias, estado y conteo final cuando existe.

9. Exportación en PDF

   • Desde historial o detalle de inventario se exporta el documento final.
   • El archivo se genera localmente en el navegador mediante jsPDF.

Tecnologías Utilizadas

Frontend

• React: construcción de la interfaz de usuario.
• Vite: servidor de desarrollo, build y empaquetado.
• Tailwind CSS: estilos utilitarios y diseño responsive.
• React Router DOM: navegación, rutas protegidas y rutas por rol.
• Lucide React: iconografía de la interfaz.

Backend / Base de Datos

• Firebase Authentication

  • Inicio de sesión con correo y contraseña.
  • Registro de usuarios.
  • Acceso con Google.
  • Control de sesión autenticada.

• Cloud Firestore

  • Almacenamiento de inventarios.
  • Almacenamiento de usuarios y roles.
  • Sincronización en tiempo real con onSnapshot.
  • Persistencia de conteos, historial, validaciones y conteo final.

La configuración actual incluye datos del proyecto Firebase en SIO-Control-Frontend/src/firebase.js. La aplicación usa Firestore como base de datos operativa.

Otras librerías

• pdfjs-dist: lectura y extracción de texto desde archivos PDF.
• jsPDF: generación del PDF exportable de inventario.
• chart.js / react-chartjs-2: soporte para visualización de métricas.
• core-js / regenerator-runtime: compatibilidad de ejecución en navegadores.

Arquitectura del Proyecto

El repositorio está organizado en dos carpetas principales:

SIO Control/
├── README.md
├── vercel.json
├── SIO-Control-Frontend/
└── SIO-Control-Backend/

SIO-Control-Frontend

Contiene la aplicación web construida con React, Vite y Tailwind CSS.

Responsabilidades principales:

• Renderizar la interfaz de usuario.
• Gestionar rutas públicas, protegidas y por rol.
• Autenticar usuarios con Firebase Authentication.
• Leer y guardar datos en Firestore.
• Cargar y parsear PDFs de inventario.
• Capturar conteos físicos.
• Comparar conteos multiusuario.
• Administrar usuarios.
• Exportar inventarios a PDF.

Estructura relevante:

SIO-Control-Frontend/
├── public/
│   ├── manifest.webmanifest
│   └── sw.js
├── src/
│   ├── components/
│   ├── contexts/
│   ├── hooks/
│   ├── pages/
│   ├── services/
│   ├── utils/
│   ├── App.jsx
│   ├── firebase.js
│   └── main.jsx
├── package.json
└── vite.config.js

SIO-Control-Backend

Contiene reglas de negocio y utilidades reutilizables. No es un servidor HTTP independiente en el estado actual; es una capa lógica neutral que el frontend importa mediante el alias @sio-backend.

Responsabilidades principales:

• Constantes de estado de inventario.
• Opciones de observación.
• Normalización de categorías, productos y conteos.
• Cálculo de totales, diferencias y progreso.
• Filtros de producto.
• Interpretación de líneas extraídas del PDF.
• Construcción de la estructura de inventario desde texto de PDF.

Estructura relevante:

SIO-Control-Backend/
├── src/
│   ├── index.js
│   ├── inventoryCore.js
│   └── pdfInventoryBuilder.js
└── package.json

Sistema de Roles

Contador

El rol contador está orientado al trabajo operativo de inventario.

Permisos principales:

• Realizar conteo físico.
• Agregar registros de cantidad por producto.
• Editar o eliminar sus movimientos de conteo.
• Consultar su avance.
• Ver el historial asociado a los inventarios disponibles.

El contador trabaja sobre un conteo individual. Esto permite que varios usuarios capturen el mismo inventario sin sobrescribir el trabajo de otros.

Auditor

El rol auditor está orientado a revisión y control.

Permisos principales:

• Comparar conteos de dos usuarios.
• Editar movimientos en ambos conteos durante la comparación.
• Validar productos con diferencias.
• Generar conteo final.
• Acceder a detalle e historial de inventarios.
• Administrar usuarios cuando tiene permisos de auditoría.

Admin auditor

El rol admin_auditor tiene permisos de auditoría y administración. Puede gestionar roles y estado de acceso de usuarios.

Tiempo Real

SIO-Control usa Firestore para sincronización en tiempo real. Las pantallas principales se suscriben a documentos o colecciones con onSnapshot, por lo que cualquier cambio se propaga automáticamente.

Se sincronizan en tiempo real:

• Inventario actual.
• Conteos individuales.
• Movimientos por producto.
• Estado del inventario.
• Comparación entre usuarios.
• Productos validados.
• Conteo final.
• Historial de inventarios.

Esto permite trabajo multiusuario en simultáneo. Por ejemplo, un contador puede capturar productos mientras el auditor observa avances o diferencias desde otra sesión.

Exportación PDF

La exportación se realiza en el navegador con jsPDF. El servicio de exportación toma el inventario normalizado y genera un documento en formato carta.

El documento exportado contiene:

• Nombre del reporte: informe de inventario diario.
• Número de hoja y fecha/hora de generación.
• Semana, fecha y CEDIS.
• Tabla de productos por categoría.
• Columnas de cantidad, no disponible, conteo físico, total, diferencia y observación.
• Totales por categoría.
• Total general del inventario.

Prioridad de datos al exportar:

1. finalCount, si ya existe conteo final validado.
2. activeUserCount, si se exporta desde una sesión de conteo activa.
3. Primer conteo guardado disponible.
4. Categorías base del inventario.

El nombre del archivo sigue el formato:

inventario-{fecha}-{cedis}.pdf

Instalación y Uso

Requisitos

• Node.js instalado.
• npm instalado.
• Proyecto Firebase configurado.
• Firebase Authentication habilitado para correo/contraseña y, si se usa, Google.
• Cloud Firestore habilitado.
• Dominio autorizado en Firebase Authentication para ambientes de despliegue.

Instalación de dependencias

Desde la raíz del repositorio:

npm --prefix SIO-Control-Frontend install

También puede instalarse entrando directamente al frontend:

cd SIO-Control-Frontend
npm install

Ejecutar en desarrollo

Desde la raíz:

npm --prefix SIO-Control-Frontend run dev

O desde la carpeta del frontend:

cd SIO-Control-Frontend
npm run dev

Vite mostrará la URL local para abrir la aplicación en el navegador.

Generar build de producción

npm --prefix SIO-Control-Frontend run build

El resultado se genera en:

SIO-Control-Frontend/dist

Vista previa del build

npm --prefix SIO-Control-Frontend run preview

Lint

npm --prefix SIO-Control-Frontend run lint

Variables y configuración

En el estado actual, la configuración de Firebase está definida directamente en:

SIO-Control-Frontend/src/firebase.js

No existe un archivo .env obligatorio para ejecutar el proyecto localmente. Si el proyecto se prepara para producción empresarial, se recomienda mover la configuración de Firebase a variables de entorno de Vite, por ejemplo:

VITE_FIREBASE_API_KEY
VITE_FIREBASE_AUTH_DOMAIN
VITE_FIREBASE_PROJECT_ID
VITE_FIREBASE_STORAGE_BUCKET
VITE_FIREBASE_MESSAGING_SENDER_ID
VITE_FIREBASE_APP_ID
VITE_FIREBASE_MEASUREMENT_ID

Despliegue

El repositorio incluye configuración para Vercel en vercel.json.

La configuración indica:

• Framework: Vite.
• Instalación desde SIO-Control-Frontend.
• Build desde SIO-Control-Frontend.
• Carpeta de salida: SIO-Control-Frontend/dist.
• Rewrite a index.html para soportar rutas de React Router.

Estado del Proyecto

Estado actual:

• Prototipo funcional.
• En desarrollo.
• En pruebas operativas.

El sistema ya cuenta con flujo de carga de PDF, conteo, comparación, validación, historial, administración de usuarios y exportación PDF. Todavía debe considerarse como una base en evolución para uso empresarial controlado.

Notas Importantes

• SIO-Control está diseñado para uso interno empresarial.
• La información se sincroniza en tiempo real; los usuarios deben evitar trabajar con cuentas compartidas.
• Cada usuario debe ingresar con su propia cuenta para conservar trazabilidad.
• El PDF cargado debe corresponder al inventario diario esperado por el parser.
• Antes de generar conteo final, el auditor debe revisar todas las diferencias.
• El conteo final debe generarse únicamente cuando el inventario físico haya sido validado.
• Se recomienda revisar reglas de seguridad de Firestore antes de operar con datos reales.
• Se recomienda restringir los dominios autorizados en Firebase Authentication.
• Para operación en producción, se recomienda separar configuración sensible por ambiente.

Resumen Técnico del Modelo de Datos

La colección principal de inventarios se almacena en Firestore como inventory.

Campos relevantes de un inventario:

• dateKey: fecha operativa del inventario.
• fecha: fecha mostrada al usuario.
• semana: semana detectada desde el PDF.
• cedis: centro de distribución detectado.
• sourcePdfName: nombre del PDF original.
• status: estado del inventario.
• categories: estructura base de categorías y productos.
• userCounts: conteos independientes por usuario.
• verifiedProducts: productos revisados por auditoría.
• finalCount: conteo final validado.
• createdAt, createdBy: trazabilidad de creación.
• updatedAt, updatedBy: trazabilidad de actualización.

Estados principales del inventario:

• borrador
• en_proceso
• conteo_1_completo
• conteo_2_completo
• pendiente_comparacion
• validado
• guardado
• cerrado
• reabierto

La colección de usuarios se almacena como users.

Campos relevantes de usuario:

• uid
• email
• displayName
• role
• active
• lastSeenAt
• updatedAt

Rutas Principales

• /login: acceso con correo/contraseña o Google.
• /inicio: panel central del sistema.
• /inventario/resumen: resumen del inventario del día.
• /inventario/cargar: carga y previsualización del PDF.
• /inventario/conteo: conteo en proceso.
• /inventario/historial: historial de inventarios.
• /inventario/:id: detalle del inventario.
• /inventario/:id/editar: edición y captura de conteo.
• /inventario/comparar: comparación de conteos.
• /inventario/:id/comparar: comparación de un inventario específico.
• /administracion/usuarios: administración de usuarios y roles.