shopit-back/app/Domains/Administrator/documentacion

Administradores de AdminApp

CRUD de usuarios con rol adminapp, limitado al tenant del usuario autenticado. Todos los administradores del tenant pueden gestionar esta sección.

Endpoints

Base: /api/v1/adminapp/tenant/administrators. Requieren auth:sanctum y adminapp.tenant.

• GET /: listado ordenado por nombre; acepta search por nombre, DNI o email.
• POST /: alta; responde 201 con data.
• PUT /{administrator}: actualización de los tres campos; responde 200 con data.
• DELETE /{administrator}: baja lógica; responde 204.

Alta y actualización reciben:

{
  "nombre_apellido": "Ada Lovelace",
  "dni": "12345678",
  "email": "ada@example.test"
}

Nombre (hasta 255 caracteres), DNI (hasta 50) y email (hasta 255) son obligatorios. El email se normaliza a minúsculas antes de validar y debe ser único entre usuarios activos, sin importar su tenant o rol. Se permite reutilizar el email de un usuario eliminado. Rol y tenant no son editables desde esta API.

Las respuestas incluyen id, nombre_apellido, dni, email, rol_codigo y role (codigo, nombre). Nunca incluyen contraseña ni datos de escaneo.

Alta y acceso

Se genera una contraseña aleatoria y un intento de establecimiento de contraseña con motivo administrator_created, reutilizando createForAdminAppEmail. El evento usa el canal adminapp; el listener existente envía el email después del commit mediante la cola emails. Requiere la configuración de correo, dominio AdminApp y worker existentes. No se envían contraseñas en texto plano.

Eliminación y aislamiento

Las consultas de usuarios se limitan por tenant y rol adminapp. IDs ajenos, usuarios eliminados y usuarios de otros roles devuelven 404. La validación de campos devuelve 422; falta de autenticación, 401, y rol no autorizado, 403.

No se permite eliminar al propio usuario ni dejar al tenant sin administradores (422, error administrator). La eliminación bloquea la fila del tenant dentro de una transacción para serializar bajas concurrentes. También verifica que el actor siga activo, revoca tokens y aplica el borrado lógico existente en users.

No agrega tablas ni migraciones. No modifica el CRUD de escáneres ni el frontend.

Verificación

php artisan test tests/Feature/Administrator/AdministratorControllerTest.php

Las pruebas cubren CRUD, normalización y unicidad del email, establecimiento de contraseña, restricciones de rol y tenant, baja lógica, tokens y protecciones de eliminación. El caso de petición autenticada antes de la baja del actor se simula; no es una prueba con conexiones concurrentes reales.