Cómo vincular un empleado con un usuario

En este artículo

Antes de empezar

• Trabajar con una organización y ubicación activas; en el demo ES: Grupo Marea Demo y Marea Gran Via.
• Tener `staff:manage` para crear o guardar empleados. `staff:view` permite abrir detalles existentes, pero no sustituye la capacidad de guardar.
• Tener un rol de personal disponible en la ubicación; la ficha no se guarda sin `staff_role_id`.
• Para seleccionar un usuario existente, tener `users:view` o `users:manage` y un usuario aceptado en la ubicación, sin ficha `staff` previa y que no sea interno de tipo `device`.
• Para usar `Crear usuario interno`, tener `users:manage` y un `AccessNamespace` interno configurado en la ubicación.

Instrucciones

1. 1.

   Abrir la ficha de empleado

   Entra en `location/staff/create` para registrar un empleado o en `location/staff/detail/:staffId` para editar una ficha existente. En la ficha, la sección `Usuario asociado` aparece cuando el operador puede ver o gestionar usuarios de la ubicación.

2. 2.

   Completar el rol y la identidad base

   Selecciona un rol de personal antes de guardar. Si no vas a asociar ningún usuario, introduce nombre y apellido manuales; si eliges un usuario, la identidad mínima puede venir del usuario vinculado.

3. 3.

   Seleccionar el usuario asociado

   En `Usuario asociado`, elige un usuario aceptado de la ubicación o deja `Sin usuario asociado` para mantener la ficha sin relación. El selector carga usuarios aceptados con `without_staff=true`, por lo que no muestra usuarios que ya tengan ficha de personal en esa ubicación.

4. 4.

   Decidir si heredar datos del usuario

   Activa `Utilizar los datos del usuario` para copiar nombre, email, teléfono e imagen del usuario seleccionado y bloquear la edición manual de esos campos. Déjalo desactivado si quieres conservar datos manuales aunque exista `user_id`.

5. 5.

   Guardar la ficha completa

   Pulsa `Registrar` en alta o `Guardar cambios` en edición. La asociación se persiste al guardar la ficha completa mediante `POST /api/app/{orgId}/{locationId}/staff` o `PUT /api/app/{orgId}/{locationId}/staff/{staffId}` con `user_id` y `use_user_data`.

6. 6.

   Crear usuario interno si no existe

   Si el empleado todavía no tiene usuario, pulsa `Crear usuario interno`. La pantalla se abre como `Crear usuario para empleado`, con tipo `employee` fijo y botón `Crear y asociar`; al volver, la ficha queda con el usuario seleccionado y `Utilizar los datos del usuario` activo.

7. 7.

   Desvincular o mantener datos manuales

   Para quitar la relación, selecciona `Sin usuario asociado` y guarda. Para mantener el vínculo sin heredar identidad, conserva el usuario seleccionado, desactiva `Utilizar los datos del usuario` y guarda la ficha.

Validaciones y límites

• La pantalla bloquea o muestra error si falta el rol de personal; backend devuelve error cuando `staff_role_id` está vacío.
• Cuando no hay usuario vinculado, nombre y apellido son obligatorios en la ficha.
• La sección `Usuario asociado` requiere `users:view` o `users:manage`; el botón `Crear usuario interno` requiere `users:manage`.
• El selector excluye usuarios que ya tengan cualquier ficha `staff` en la ubicación, incluso si esa ficha está archivada.
• Los usuarios internos de tipo `device` no aparecen como candidatos; sí pueden aparecer usuarios externos y usuarios internos de tipo `employee`.
• Un mismo usuario no puede quedar asociado a dos fichas de personal de la misma ubicación por la restricción única de `staff`.
• El formulario de usuario interno exige nombre, `User ID` y contraseña; en alta la contraseña debe tener al menos 6 caracteres.
• No existe un endpoint independiente `staff.link-user`; la acción se realiza guardando la ficha completa de personal.

Resultado esperado

La ficha de personal queda guardada con o sin `user_id` según la selección. Si `use_user_data` está activo, Antylogic usa los datos del usuario para nombre, email, teléfono e imagen, y el listado de personal refleja el usuario como asociado.