Manual del
Administrador

Manual del Administrador

Sección 1

1.1 Visión General

El sistema de Control de Stock de ACyEDE utiliza una arquitectura cliente-servidor de tres capas. El frontend es una aplicación de página única (SPA) construida con React que se ejecuta en el navegador del usuario. El backend es una API REST construida con Node.js y Express que gestiona la lógica de negocio y la autenticación. La base de datos es un archivo SQLite gestionado con la librería better-sqlite3.

Esta arquitectura permite que el sistema funcione en un único servidor, sin necesidad de instalar un motor de base de datos externo. Toda la información se almacena en un solo archivo .db, lo que simplifica enormemente el backup y la portabilidad.

1.2 Diagrama de Arquitectura

1.3 Estructura del Proyecto

1.4 Stack Tecnológico

Manual del Administrador

Sección 2

2.1 Requisitos Previos

2.2 Instalación Paso a Paso

1. Obtener el código del proyecto

   Cloná el repositorio o copiá la carpeta del proyecto al servidor:

   Terminal

   # Opción A: Clonar desde repositorio
   git clone https://github.com/tu-org/acyede-stock.git
   cd acyede-stock
   
   # Opción B: Copiar carpeta manualmente
   # Copiar la carpeta completa al servidor y navegar a ella

2. Instalar todas las dependencias

   Ejecutá el comando de instalación unificado desde la raíz del proyecto:

   Terminal

   npm run install:all
   
   # Este comando instala las dependencias de:
   #   - Raíz del proyecto (scripts de gestión)
   #   - server/ (API backend + SQLite)
   #   - client/ (React frontend)

3. Configurar variables de entorno

   Creá o editá el archivo server/.env con la configuración necesaria:

   server/.env

   # Puerto del servidor
   PORT=3001
   
   # Clave secreta para firmar tokens JWT
   # ¡CAMBIÁ ESTO EN PRODUCCIÓN!
   JWT_SECRET=tu_clave_secreta_super_segura_aqui
   
   # Ruta al archivo de base de datos
   DB_PATH=./db/stock.db

4. Iniciar en modo desarrollo

   Para desarrollo local con hot-reload:

   Terminal

   npm run dev
   
   # Esto inicia simultáneamente:
   #   - Backend en http://localhost:3001
   #   - Frontend en http://localhost:5173 (con proxy al backend)

5. Compilar y ejecutar en producción

   Para despliegue en producción, compilá el frontend y luego iniciá el servidor:

   Terminal

   # Compilar el frontend para producción
   npm run build
   
   # Iniciar el servidor (sirve el frontend compilado + API)
   npm start
   
   # El sistema completo queda disponible en:
   #   http://localhost:3001

2.3 Variables de Entorno

2.4 Verificar la Instalación

Después de iniciar el sistema, verificá que todo funcione correctamente:

# Verificar que el servidor responde
curl http://localhost:3001/api/auth/me

# Respuesta esperada (sin token): {"error":"Token no proporcionado"}
# Esto confirma que la API está funcionando correctamente

# Probar login
curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# Respuesta esperada: {"token":"eyJ...", "user":{...}}

Manual del Administrador

Sección 3

3.1 Usuarios Predeterminados

Al ejecutar el sistema por primera vez, se crean automáticamente tres usuarios con roles distintos. Estos usuarios permiten el acceso inicial al sistema y deben ser modificados inmediatamente después del primer inicio de sesión.

3.2 Crear un Nuevo Usuario

Solo los usuarios con rol Administrador pueden crear nuevas cuentas.

1. Acceder a la gestión de usuarios

   Navegá a la sección Usuarios desde el menú lateral (escritorio) o desde la navegación inferior (móvil).

2. Iniciar la creación

   Hacé clic en el botón "Nuevo Usuario" ubicado en la parte superior de la página.

3. Completar el formulario

   Ingresá los datos del nuevo usuario:

   • Nombre de usuario: Identificador único para el login (sin espacios)
   • Nombre completo: Nombre y apellido del usuario
   • Contraseña: Mínimo 6 caracteres
   • Rol: Seleccioná entre Administrador, Operador o Solo lectura
4. Guardar

   Hacé clic en "Guardar". El usuario podrá iniciar sesión de inmediato con las credenciales asignadas.

3.3 Editar un Usuario

Desde la lista de usuarios, hacé clic en el botón de edición (ícono de lápiz) junto al usuario que querés modificar. Podés cambiar:

• Nombre completo: Actualizar el nombre del usuario
• Rol: Cambiar el nivel de acceso (los cambios aplican en el próximo login)
• Contraseña: Resetear la contraseña del usuario

3.4 Desactivar un Usuario

Los usuarios no se eliminan del sistema, sino que se desactivan (soft-disable). Un usuario desactivado no puede iniciar sesión, pero su historial de movimientos se conserva para auditoría. Los usuarios desactivados pueden ser reactivados en cualquier momento por un administrador.

3.5 Matriz de Permisos por Rol

Manual del Administrador

Sección 4

4.1 Ubicación del Archivo

La base de datos es un archivo SQLite ubicado en:

server/db/stock.db

Este archivo contiene toda la información del sistema: usuarios, productos, categorías, proveedores y movimientos de stock. Al ser un único archivo, es extremadamente fácil de respaldar, migrar o clonar.

4.2 Esquema de Tablas

La base de datos consta de 5 tablas principales:

4.3 Relaciones entre Entidades

4.4 Auto-Seeding (Datos Iniciales)

La primera vez que se inicia el servidor, el sistema detecta que la base de datos está vacía y ejecuta automáticamente el proceso de seeding:

• Crea las tablas con toda la estructura definida en el esquema
• Inserta los 3 usuarios predeterminados (admin, operador, consulta) con contraseñas hasheadas con bcrypt
• Crea categorías de ejemplo para facilitar el inicio
• Crea proveedores de ejemplo como referencia

4.5 Notas Importantes sobre SQLite

Manual del Administrador

Sección 5

5.1 Backup Manual

El backup del sistema consiste en respaldar dos elementos: la base de datos y las fotos de productos.

1. Detener el servidor

   Asegurate de que el servidor no esté en ejecución para evitar inconsistencias. Si usás PM2: pm2 stop acyede-stock. Si ejecutás directamente: presioná Ctrl+C en la terminal.

2. Copiar el archivo de base de datos

   Copiá el archivo server/db/stock.db a una ubicación segura:

   Windows — CMD / PowerShell

   copy server\db\stock.db D:\backups\stock_2026-07-07.db

3. Copiar la carpeta de fotos

   Las fotos de productos se almacenan en server/uploads/. Respaldá esta carpeta completa:

   Windows — CMD / PowerShell

   xcopy server\uploads D:\backups\uploads_2026-07-07\ /E /I

4. Reiniciar el servidor

   Una vez completado el backup, reiniciá el servidor normalmente: npm start o pm2 start acyede-stock.

5.2 Backup Automatizado

Usá el siguiente script de Windows (.bat) para automatizar el backup diario. Programalo en el Programador de Tareas de Windows para que se ejecute automáticamente.

@echo off
REM ============================================
REM   ACyEDE Stock - Script de Backup Automático
REM   Programar en el Programador de Tareas
REM ============================================

REM Configuración - AJUSTAR ESTAS RUTAS
SET PROJECT_DIR=C:\acyede-stock
SET BACKUP_DIR=D:\backups\acyede
SET MAX_BACKUPS=30

REM Generar marca de tiempo
SET TIMESTAMP=%date:~6,4%-%date:~3,2%-%date:~0,2%_%time:~0,2%-%time:~3,2%
SET TIMESTAMP=%TIMESTAMP: =0%

REM Crear directorio de backup si no existe
IF NOT EXIST "%BACKUP_DIR%" MKDIR "%BACKUP_DIR%"

REM Copiar base de datos
echo [%TIMESTAMP%] Iniciando backup...
copy "%PROJECT_DIR%\server\db\stock.db" "%BACKUP_DIR%\stock_%TIMESTAMP%.db"

REM Copiar carpeta de uploads
xcopy "%PROJECT_DIR%\server\uploads" "%BACKUP_DIR%\uploads_%TIMESTAMP%\" /E /I /Q

REM Registrar en log
echo [%TIMESTAMP%] Backup completado exitosamente >> "%BACKUP_DIR%\backup_log.txt"

echo Backup completado: %BACKUP_DIR%\stock_%TIMESTAMP%.db

5.3 Restaurar desde Backup

1. Detener el servidor

   Detenés el servidor para liberar el archivo de base de datos.

2. Reemplazar la base de datos

   Reemplazá el archivo actual con la copia de backup:

   Terminal

   # Renombrar el archivo actual (por seguridad)
   rename server\db\stock.db stock_corrupted.db
   
   # Copiar el backup
   copy D:\backups\acyede\stock_2026-07-05.db server\db\stock.db

3. Restaurar fotos (si es necesario)

   Si también necesitás restaurar las fotos de productos:

   Terminal

   xcopy D:\backups\acyede\uploads_2026-07-05\ server\uploads\ /E /I /Y

4. Reiniciar el servidor

   Iniciá el servidor normalmente. Verificá que los datos se hayan restaurado correctamente ingresando al sistema y revisando la información.

Manual del Administrador

Sección 6

6.1 Opción A: Servidor Local (Red Interna)

La opción más simple es ejecutar el sistema en una PC o servidor dedicado dentro de la red local de la organización. Los demás dispositivos acceden al sistema a través de la dirección IP del servidor.

1. Preparar el servidor

   Instalá Node.js en la PC/servidor que va a alojar el sistema. Asegurate de que tenga una IP fija en la red local (o configurá una IP estática en la red).

2. Instalar y compilar

   Terminal

   npm run install:all
   npm run build
   npm start

3. Acceder desde otros dispositivos

   Los usuarios de la red acceden abriendo un navegador y visitando:

   URL de acceso

   http://IP_DEL_SERVIDOR:3001
   
   # Ejemplo: http://192.168.1.100:3001

Gestión de procesos con PM2

Para que el servidor se mantenga ejecutando en segundo plano y se reinicie automáticamente ante errores o reinicios del sistema, usá PM2:

# Instalar PM2 globalmente
npm install -g pm2

# Iniciar el servidor con PM2
pm2 start server/index.js --name "acyede-stock"

# Configurar inicio automático con Windows
pm2 save
pm2-startup install

# Comandos útiles de PM2
pm2 status            # Ver estado del proceso
pm2 logs acyede-stock  # Ver logs en tiempo real
pm2 restart acyede-stock # Reiniciar
pm2 stop acyede-stock    # Detener

6.2 Opción B: Hosting en la Nube

Para acceso desde internet (fuera de la red local), podés desplegar en un servicio de hosting en la nube.

Pasos generales para hosting en la nube:

1. Subir el código

   Subí el proyecto a un repositorio Git o usá el CLI del servicio elegido para deployar directamente.

2. Configurar variables de entorno

   Definí PORT, JWT_SECRET y DB_PATH en el panel de configuración del servicio.

3. Configurar el build y start

   Build command: npm run install:all && npm run build
   Start command: npm start

4. Configurar dominio (opcional)

   Configurá un dominio personalizado y un certificado SSL en el panel del servicio de hosting.

6.3 Checklist de Seguridad para Producción

Antes de poner el sistema en producción, verificá cada punto de esta lista:

• Cambiar JWT_SECRET — Usar una clave aleatoria de al menos 64 caracteres. Nunca usar el valor por defecto.
• Cambiar contraseñas predeterminadas — Cambiar las contraseñas de admin, operador y consulta inmediatamente.
• Habilitar HTTPS — Configurar un certificado SSL. En servidor local, podés usar un proxy reverso con Nginx/Caddy. En hosting, generalmente ya está incluido.
• Configurar backups automáticos — Programar el script de backup diario (ver Sección 5.2) y verificar que se ejecute correctamente.
• Restringir acceso al servidor — Configurar el firewall para permitir solo el tráfico necesario (puerto 3001 o el configurado).
• Mantener Node.js actualizado — Instalar actualizaciones de seguridad regularmente. Verificar con node --version.

Manual del Administrador

Sección 7

7.1 Problemas Frecuentes y Soluciones

7.2 Comandos de Diagnóstico

# Verificar versión de Node.js (requiere 18+)
node --version

# Verificar versión de npm
npm --version

# Verificar si el puerto 3001 está en uso (Windows)
netstat -ano | findstr :3001

# Ver procesos de Node.js en ejecución (Windows)
tasklist | findstr node

# Verificar tamaño de la base de datos (PowerShell)
Get-Item server\db\stock.db | Select-Object Name, Length

# Verificar contenido de la carpeta uploads
dir server\uploads | Measure-Object

# Ver logs de PM2 (si usás PM2)
pm2 logs acyede-stock --lines 50

# Verificar que la API responde
curl http://localhost:3001/api/auth/me

7.3 Reinicio Completo del Sistema

Si nada funciona, podés hacer un reinicio completo reinstalando las dependencias:

# 1. Detener cualquier proceso en ejecución
pm2 stop all  # o Ctrl+C si ejecutás directamente

# 2. Eliminar dependencias
rmdir /s /q node_modules
rmdir /s /q server\node_modules
rmdir /s /q client\node_modules

# 3. Reinstalar todo
npm run install:all

# 4. Recompilar
npm run build

# 5. Reiniciar
npm start

Manual del Administrador

Sección 8

Todos los endpoints devuelven respuestas en formato JSON. La autenticación se realiza mediante un token JWT que debe incluirse en el header Authorization: Bearer <token> de cada solicitud (excepto el login).

8.1 Autenticación

8.2 Productos

8.3 Movimientos de Stock

8.4 Categorías

8.5 Proveedores

8.6 Usuarios

8.7 Reportes

8.8 Ejemplo de Uso de la API

# Paso 1: Obtener token de autenticación
curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# Respuesta: {"token":"eyJhbGciOiJIUzI1NiIs..."}

# Paso 2: Usar el token para consultar productos
curl http://localhost:3001/api/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Paso 3: Crear un nuevo producto
curl -X POST http://localhost:3001/api/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Cable UTP Cat6","sku":"CAB-006","categoryId":1,"stock":100,"minStock":20,"price":850}'