Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JuanM84/gestor-visitas/llms.txt

Use this file to discover all available pages before exploring further.

La gestión de usuarios es una función exclusiva del rol Admin y permite administrar todo el personal que opera el sistema. Desde este módulo se crean nuevas cuentas, se asignan roles, se editan datos personales y se controla el acceso mediante activación o desactivación de cuentas. Los usuarios nunca se eliminan físicamente de la base de datos: el sistema aplica un patrón de soft-delete donde activo = false revoca el acceso sin perder el historial asociado al registro.

Crear Usuario

Alta de nuevas cuentas con nombre, correo, contraseña provisoria y asignación de rol.

Editar Datos

Modificación de nombre, correo, teléfono y rol desde el modal de edición.

Activar / Desactivar

Soft-delete para revocar o restituir el acceso sin borrar el historial.

Contraseñas y Perfil

Cada usuario gestiona su propia contraseña; el Admin puede cambiar cualquiera.

​
Roles del sistema

El sistema opera con exactamente dos roles. El rol determina qué rutas API y qué secciones de la interfaz son accesibles.
RolDescripciónPermisos principales
AdminAdministrador del sistemaAcceso total: usuarios, configuración, días inhábiles, auditoría y visitas
GuíaGuía operativo del túnelRegistro y consulta de visitas; lectura de configuración y días inhábiles
Todos los endpoints de gestión de usuarios bajo POST /api/usuarios, PUT /api/usuarios/:id, PATCH /api/usuarios/:id/desactivar y PATCH /api/usuarios/:id/reactivar requieren el middleware verificarRol(['Admin']). Un Guía que intente acceder recibirá un 403 Forbidden.

​
Estructura de la tabla USUARIO

Cada registro en la tabla USUARIO contiene los siguientes campos:
CampoTipoDescripción
idInteger (PK)Identificador único autoincremental
nombreTextNombre completo del empleado
emailText (unique)Correo electrónico — usado como nombre de usuario al iniciar sesión
telefonoText (nullable)Número de contacto opcional
password_hashTextHash bcrypt de la contraseña — nunca se almacena texto plano
rolText'Admin' o 'Guía'
activoBooleantrue = cuenta habilitada, false = acceso revocado (soft-delete)
created_atTimestampFecha y hora de creación del registro

​
Crear un nuevo usuario

Solo los Admins pueden crear cuentas. El formulario de alta se encuentra en el panel izquierdo de la página Gestión de Usuarios.
1

Completar el nombre completo

Ingrese el nombre y apellido del empleado en el campo Nombre Completo. Este campo es obligatorio y se mostrará en la tabla de personal registrado y en los registros de auditoría.
2

Ingresar el correo electrónico

Escriba la dirección de correo del empleado. El email debe ser único en el sistema; si ya existe una cuenta con esa dirección, la API devolverá un error 400. El correo se utiliza como identificador de inicio de sesión.
3

Definir una contraseña provisoria

Establezca una contraseña temporal para la cuenta. La interfaz exige mínimo 8 caracteres, incluyendo al menos una mayúscula, una minúscula y un número. El campo Repetir Contraseña debe coincidir exactamente antes de que el formulario se envíe.
4

Seleccionar el rol

Elija entre Guía Operativo (Guía) o Administrador (Admin) en el selector de rol. Por defecto, el formulario preselecciona Guía para minimizar la asignación accidental de privilegios elevados.
5

Enviar el formulario

Haga clic en Crear Usuario. Si todo es correcto, la API responde 201 Created con el objeto del nuevo usuario y el listado de personal se actualiza automáticamente. El usuario deberá cambiar su contraseña provisoria en el primer inicio de sesión.
Endpoint correspondiente: 
POST /api/usuarios
Authorization: Bearer <token_admin>
Content-Type: application/json

{
  "nombre": "María González",
  "email": "m.gonzalez@tunel.gob.ar",
  "password": "Provisoria123",
  "rol": "Guía"
}
Respuesta exitosa (201): 
{
  "mensaje": "Usuario creado exitosamente",
  "usuario": {
    "id": 12,
    "nombre": "María González",
    "email": "m.gonzalez@tunel.gob.ar",
    "rol": "Guía",
    "activo": true
  }
}

​
Listar usuarios

El listado completo del personal está restringido al rol Admin y se obtiene con: 
GET /api/usuarios
Authorization: Bearer <token_admin>
La respuesta es un array JSON con todos los usuarios (activos e inactivos). La interfaz muestra cada fila con nombre, correo, rol, estado (Activo / Inactivo) y los botones de acción correspondientes. Los registros inactivos aparecen con opacidad reducida para distinción visual.

​
Editar datos de un usuario

Un Admin puede modificar el nombre, correo, teléfono y rol de cualquier cuenta. Haga clic en el ícono de edición (lápiz) en la fila del usuario para abrir el modal de edición. 
PUT /api/usuarios/:id
Authorization: Bearer <token_admin>
Content-Type: application/json

{
  "nombre": "María A. González",
  "email": "m.gonzalez@tunel.gob.ar",
  "telefono": "+54 343 456-7890",
  "rol": "Admin"
}
La contraseña no se modifica desde el modal de edición. Para cambiarla, utilice el endpoint específico PUT /api/usuarios/:id/password descripto en la sección de contraseñas.
Respuesta exitosa (200): 
{
  "mensaje": "Usuario actualizado correctamente.",
  "usuario": {
    "id": 12,
    "nombre": "María A. González",
    "email": "m.gonzalez@tunel.gob.ar",
    "telefono": "+54 343 456-7890",
    "rol": "Admin",
    "activo": true
  }
}

​
Desactivar y reactivar usuarios

El sistema nunca borra físicamente cuentas de usuario. Cuando un empleado deja de trabajar en el túnel, su cuenta se desactiva (activo = false), lo que impide el inicio de sesión sin eliminar el historial de visitas o auditoría vinculado a ese usuario.

​
Desactivar

PATCH /api/usuarios/:id/desactivar
Authorization: Bearer <token_admin>
Protección de auto-desactivación: Un Admin no puede desactivar su propia cuenta mientras tiene la sesión activa. Si lo intenta, el servidor responde 400 con el mensaje: “No podés desactivar tu propia cuenta mientras tenés la sesión activa.”Protección del último Admin: El sistema verifica que siempre exista al menos un Admin activo. Si el usuario a desactivar es el único Admin con activo = true, la operación es rechazada con 400. Esto garantiza que el sistema nunca quede sin un administrador accesible.
Respuesta exitosa (200): 
{
  "mensaje": "Usuario \"María A. González\" desactivado correctamente",
  "usuario": { "id": 12, "activo": false, ... }
}

​
Reactivar

Para restituir el acceso de una cuenta previamente desactivada: 
PATCH /api/usuarios/:id/reactivar
Authorization: Bearer <token_admin>
Respuesta exitosa (200): 
{
  "mensaje": "Usuario \"María A. González\" reactivado correctamente",
  "usuario": { "id": 12, "activo": true, ... }
}

​
Cambiar contraseña y gestionar perfil

​
Cambiar contraseña

Este endpoint no requiere rol Admin: cualquier usuario autenticado puede cambiar su propia contraseña. Un Admin también puede cambiar la contraseña de cualquier otra cuenta (por ejemplo, para asistir a un usuario que olvidó sus credenciales). 
PUT /api/usuarios/:id/password
Authorization: Bearer <token_usuario_o_admin>
Content-Type: application/json

{
  "passwordActual": "Provisoria123",
  "nuevaPassword": "NuevaClave456"
}
Ambos campos passwordActual y nuevaPassword son obligatorios. Si alguno se omite, la API responde 400. Un usuario que intente cambiar la contraseña de otra cuenta (sin ser Admin) recibirá 403 Forbidden.
Respuesta exitosa (200): 
{ "mensaje": "Contraseña actualizada correctamente." }

​
Perfil propio

Cada usuario puede consultar y actualizar su propio perfil (correo y teléfono) sin necesidad de intervención del Admin. Un Admin puede consultar el perfil de cualquier cuenta. 
# Leer perfil
GET /api/usuarios/:id/perfil
Authorization: Bearer <token>

# Actualizar email y/o teléfono
PUT /api/usuarios/:id/perfil
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "nuevo.correo@tunel.gob.ar",
  "telefono": "+54 343 555-1234"
}
Un usuario solo puede editar su propio perfil. Intentar modificar el perfil de otra cuenta sin ser Admin resulta en 403 Forbidden con el mensaje: “Solo podés editar tu propio perfil.”

​
Resumen de endpoints

MétodoRutaRequiereDescripción
GET/api/usuariosAdminLista todos los usuarios (activos e inactivos)
POST/api/usuariosAdminCrea un nuevo usuario
PUT/api/usuarios/:idAdminActualiza nombre, email, teléfono y rol
PATCH/api/usuarios/:id/desactivarAdminSoft-delete (activo → false)
PATCH/api/usuarios/:id/reactivarAdminReactiva cuenta (activo → true)
PUT/api/usuarios/:id/passwordPropio usuario o AdminCambia contraseña con verificación de la actual
GET/api/usuarios/:id/perfilPropio usuario o AdminLee datos de perfil
PUT/api/usuarios/:id/perfilPropio usuarioActualiza email y teléfono propios

Build docs developers (and LLMs) love

Get started for freeTalk to us