Usuarios y Licencias AY-014

Conceptos básicos

En FactuPOS existen dos conceptos que se confunden con frecuencia y que conviene separar desde el principio:

¿Qué es una licencia?

Una licencia en FactuPOS es lo mismo que una estación. Cada licencia permite que una persona a la vez esté trabajando en esa estación. El número de licencias que tenga una empresa define cuántas personas pueden estar usando el sistema al mismo tiempo.

Las licencias se administran en el módulo Configuración → Estaciones (CF-006). Cada licencia tiene un nombre identificable, por ejemplo:

• Caja 1 — Terminal de cobro frente al cliente
• Caja 2 — Segunda terminal de cobro
• Administración — PC del encargado para reportes y configuración
• Bodega — Terminal para recibir mercadería

¿Qué es un usuario?

Un usuario es una persona que tiene credenciales para entrar al sistema. No es lo mismo que una licencia: usted puede crear todos los usuarios que quiera, sin importar cuántas licencias tenga.

Cada usuario tiene:

• Código único de hasta 5 caracteres (ej: 00025)
• Nombre (hasta 50 caracteres), email, teléfono, cédula, dirección
• Grupo: Usuario, Agente o Referido/Empleado (campo obligatorio)
• Departamento (hasta 3 caracteres, opcional)
• Estación predeterminada: la licencia que usará normalmente al entrar
• Horario de acceso: franja de días/horas permitida (por defecto "Completo" = 24/7)
• Comisión (0–100 %) para agentes de venta
• Contraseña personal (hasta 25 caracteres)
• Un juego de permisos (qué módulos y acciones puede realizar)

El módulo para administrarlos es Seguridad → Usuarios (SE-001).

Relación usuario–licencia

Esta es la parte clave. La regla se enuncia en tres puntos:

Diagrama

Reglas de la sesión

• Un usuario = una sesión. Si inicia sesión en otra parte, la anterior se cierra.
• Una licencia = un usuario a la vez. Solo puede haber una persona logueada en cada estación.
• Cuando alguien entra a una licencia ya ocupada, el sistema muestra un aviso: "Estación ocupada por [usuario]". Puede cancelar o continuar (lo que cierra la sesión del otro).
• Cuando alguien entra con un usuario que ya tiene sesión abierta en otra parte, el sistema muestra: "Sesión activa en otro lugar". Puede cancelar o continuar (cierra la otra sesión).
• El sistema verifica periódicamente si la sesión sigue activa. Si otra persona tomó su licencia o su usuario, usted ve un aviso en rojo y vuelve al login.

Login y autenticación

El proceso de acceso al sistema usa un wizard de 4 pasos: servidor, empresa, usuario y contraseña. Una vez completado, el sistema crea una sesión segura en el subdominio de la empresa.

Flujo de verificación de contraseña

FactuPOS nunca almacena la contraseña en texto legible para comparar. El proceso real es:

1. El usuario escribe su contraseña en el paso 4 del wizard.
2. El PHP llama al procedimiento almacenado SP_VerificaPasswordUsuario en SQL Server.
3. El SP carga el salt (UNIQUEIDENTIFIER) y el hash almacenado (VARBINARY(64)) del usuario.
4. Recalcula: HASHBYTES('SHA2_256', CONCAT(TRIM(clave_ingresada), CAST(salt AS VARCHAR(36)))) con collation binaria.
5. Si los hashes coinciden, devuelve la fila del usuario y se crea la sesión.

Trigger de hashing automático

Cuando se guarda o cambia una contraseña (desde SE-001 o la API), el trigger TRG_Usuarios_HashClave se dispara automáticamente:

• Genera un nuevo salt con NEWID().
• Calcula SHA2_256(CONCAT(TRIM(Password), CAST(NuevoSalt))).
• Guarda el salt y el hash en Empleados.salt y Empleados.clavesegura.
• La columna Password queda en texto para la función "Olvidé mi contraseña".

Token "Recordarme" (fp_token)

Si el usuario marca la opción de acceso rápido, el sistema crea una cookie fp_token:

Función "Olvidé mi contraseña"

• Disponible en el paso 4 del wizard de login.
• Envía la contraseña actual al email registrado del usuario.
• Rate limiting: máximo 5 solicitudes por usuario+empresa en 10 minutos.
• El email muestra la dirección ofuscada: j***@gmail.com.

Contraseñas

Longitud máxima

La columna Empleados.Password acepta hasta 25 caracteres. El frontend aplica este límite con maxlength="25".

Cambio de contraseña

1. En SE-001, seleccionar el usuario y abrir el modal de edición.
2. Escribir la nueva contraseña en el campo "Contraseña".
3. Guardar. El trigger de SQL Server genera automáticamente el nuevo salt y hash.
4. Si el usuario tiene email registrado, recibe la nueva clave por correo.

Usuarios protegidos

Los códigos 09029 y 59999 no aparecen en la lista de usuarios de SE-001 y no se pueden editar desde la interfaz web. Son cuentas de sistema reservadas para administración.

Sesiones multi-subdominio

Cada empresa en FactuPOS opera en su propio subdominio (ej: mitienda.factupos.com). Las cookies de sesión están aisladas por subdominio, por lo que el sistema usa un mecanismo especial para transferir la sesión del dominio principal al subdominio de la empresa.

Flujo de transferencia

1. El usuario completa el wizard en factupos.com (dominio principal).
2. El servidor genera un token aleatorio de 64 caracteres hex usando bin2hex(random_bytes(32)).
3. El token se guarda en /tmp/factupos_transfers/{token}.json con los datos de sesión y un timestamp.
4. El sistema redirige al usuario al subdominio con el token en la URL:
   https://empresa.factupos.com/auth.php?transfer={token}
5. El auth.php del subdominio lee el archivo, valida que tenga menos de 30 segundos, crea la sesión local y elimina el archivo inmediatamente.

Estaciones en el login

Al autenticarse, el sistema debe saber en qué estación (licencia) trabaja el usuario. La estación se determina así:

1. El wizard de login carga la lista de estaciones disponibles desde la BD.
2. Si el usuario tiene una estación predeterminada configurada (Empleados.EstacionId), esa se preselecciona automáticamente.
3. Si no tiene predeterminada, se usa la primera estación de la lista.
4. Si no hay estaciones, el campo queda vacío y el login es bloqueado con el mensaje "Debes seleccionar una estación".

Consulta de estaciones (con fallback)

La lista de estaciones del modal de usuarios (SE-001) se carga con fallback:

Horarios de acceso

Cada usuario puede tener asignado un horario de acceso que restringe en qué días y horas puede entrar al sistema. Si intenta acceder fuera de su horario, el menú principal le muestra una pantalla de bloqueo con reloj en vivo.

Los horarios se administran en Seguridad → Horarios de Acceso (permiso 900). Cada horario define 7 días (Dom–Sáb) con hora de inicio, hora de fin y si ese día está activo.

Contrato de servicio y batería

En el encabezado del sistema aparece una batería estilo celular de 8 segmentos que representa el estado del contrato de servicio con el proveedor (SoporteReal). Funciona consultando la cuenta por cobrar (CxC) del cliente en la base de datos del proveedor.

Significado de la batería

Bloqueo total (día 8 en adelante)

• Las tarjetas del menú quedan grises e inactivas (pointer-events: none).
• Se abre automáticamente el modal "Reportar Pago".
• No se puede navegar por el sistema hasta que el proveedor registre el pago.

Parámetros del contrato

Ejemplos prácticos

Ejemplo 1: Restaurante con 2 cajas

El restaurante tiene 2 licencias (Caja 1 y Caja 2) pero 5 empleados que se turnan:

• Los 5 usuarios se crean en Seguridad → Usuarios.
• A cada empleado se le asigna una estación predeterminada según su turno.
• Solo pueden trabajar 2 personas a la vez (una por caja).
• Si un tercero necesita entrar, tiene que esperar o desplazar a uno.

Ejemplo 2: Tienda con 1 caja y 1 admin

La tienda tiene 2 licencias (Caja y Administración):

• La cajera usa siempre la licencia "Caja".
• El dueño usa siempre la licencia "Administración" para ver reportes.
• Ambos pueden estar conectados al mismo tiempo porque son licencias distintas.

Ejemplo 3: Necesito más gente trabajando al mismo tiempo

Si su empresa crece y ahora necesita 3 personas facturando en paralelo, debe:

1. Contactar a Soporte Real para contratar una licencia adicional.
2. Una vez activada, crear la nueva estación en Configuración → Estaciones.
3. Asignar la nueva estación como predeterminada a los usuarios que la vayan a usar.

Grupos de usuario

Cada usuario pertenece a un grupo. El grupo cambia el comportamiento del usuario en reportes, comisiones y módulos. Es un campo obligatorio al crear o editar un usuario.

El grupo se almacena en Empleados.Grupo (columna CHAR(1), puede ser NULL en registros legacy).

Crear un usuario

1. Entrar a Seguridad → Usuarios (SE-001).
2. Hacer clic en el botón Nuevo en la parte superior del panel de usuarios (requiere permiso 901).
3. Completar los campos del modal. Los marcados con asterisco son obligatorios: Nombre, Grupo y Contraseña.
4. Seleccionar la Estación (licencia) donde trabajará normalmente. Junto al nombre de cada estación se muestra su detalle (información del último ingreso: quién, cuándo y desde dónde), y al elegirla el detalle completo aparece debajo del campo — útil para identificar la estación correcta antes de asignarla.
5. Seleccionar el Horario de acceso (por defecto "Completo" = 24/7).
6. Si es agente, poner el % de comisión (0–100).
7. Guardar. Si puso email, el sistema le envía la contraseña por correo automáticamente.
8. Después de crearlo, asignarle permisos en el panel derecho de la misma pantalla.

Validaciones y límites de campos

El sistema aplica validaciones tanto en el frontend (atributos maxlength) como en el backend antes de ejecutar el INSERT o UPDATE en la tabla Empleados.

Estados de usuario

La eliminación es lógica (se marca como eliminado, no se borra físicamente), para conservar la trazabilidad de facturas, recibos y movimientos históricos.

Permisos del módulo

El módulo de Seguridad tiene sus propios permisos. Se asignan desde el panel de permisos de SE-001 o desde Seguridad → Permisos del Sistema (SE-002).

Asignar permisos: pantalla de 3 columnas

Al hacer clic en un usuario de la lista, la asignación de permisos se muestra en tres columnas de izquierda a derecha:

1. Usuarios — la lista donde elegís a quién configurar.
2. Módulos — la lista de áreas (Facturación, Inventarios, Contabilidad, Planilla…). Cada módulo muestra un contador asignados / total. Arriba está «Todos» para ver el total.
3. Permisos — la lista de permisos del módulo elegido. Cada uno tiene una casilla para marcar (asignar) o desmarcar (quitar).

Al hacer clic en un módulo, la tercera columna se filtra a los permisos de ese módulo; «Todos» muestra la lista completa. Marcar requiere el permiso 906 y desmarcar el 907; si no los tenés, la casilla aparece deshabilitada.

Ver quién más tiene un permiso (y quitárselo)

Debajo de la lista de permisos hay un panel. Al hacer clic sobre un permiso, ese panel muestra qué otros usuarios activos también lo tienen, en forma de etiquetas con su código y nombre.

Parámetros de empresa

Los parámetros relacionados con seguridad y sesiones se configuran desde Configuración → Parámetros (CF-004).

Tablas de base de datos

Referencia de las tablas y vistas principales que usa el módulo de Seguridad.

Procedimientos almacenados clave

Preguntas frecuentes

¿Cuántos usuarios puedo crear?

Todos los que quiera. Los usuarios no se cobran: lo que se cobra son las licencias (sesiones simultáneas).

¿Puedo usar el mismo usuario en dos computadoras al mismo tiempo?

No. Cada usuario tiene una sola sesión activa. Si inicia sesión en otra parte, la anterior se cierra automáticamente.

¿Pueden dos usuarios usar la misma licencia al mismo tiempo?

No. Cada licencia permite un usuario a la vez. Si María entra a Caja 1 y Juan estaba usándola, Juan queda desconectado.

¿Cómo sé cuántas licencias tengo?

En Configuración → Estaciones puede ver la lista completa. Cada estación activa es una licencia.

¿Qué pasa si quiero eliminar un usuario?

Se puede Inactivar (queda en amarillo, no puede entrar pero se conservan sus registros) o Eliminar (se marca como eliminado en rojo). No se borra físicamente para mantener la trazabilidad de facturas, recibos, etc.

¿Cómo cambio la contraseña de un usuario?

Seleccionar el usuario, abrir el modal de edición (requiere permiso 902) y escribir la nueva contraseña. El sistema hashea automáticamente. Si el usuario tiene email, recibe la nueva clave por correo.

¿Los usuarios del sistema (09029, 59999) se pueden editar?

No. Son usuarios protegidos del sistema. No aparecen en la lista ni se pueden modificar ni eliminar desde la interfaz web.

¿Qué tan segura es la contraseña almacenada?

Las contraseñas se verifican con SHA-256 con salt aleatorio (UNIQUEIDENTIFIER único por usuario). El hash se recalcula con cada cambio de clave. Sin embargo, la clave en texto también se guarda en la columna Password para permitir la función "Olvidé mi contraseña".

La batería del contrato aparece en cero. ¿Qué hago?

Significa que hay 8 o más días de atraso en el pago del servicio. Use el modal "Reportar Pago" (se abre automáticamente) para notificar a Soporte Real que realizó un pago. El sistema se desbloqueará cuando el proveedor confirme el pago en su sistema.

Un usuario dice que su estación no aparece en el dropdown del login

Si la lista de estaciones queda vacía, usualmente es porque la vista vista_estaciones no está disponible en esa empresa. El sistema intenta un fallback automático a la tabla Estaciones directa. Si tampoco funciona, contacte a soporte técnico para verificar la migración de vistas.