Saltar a contenido

0027. CRUD de usuarios

Estado: Aceptado Fecha: 2026-09-30 Autor: Duval Alcivar Módulo(s) afectado(s): app/domains/usuarios/, tests/unit/usuarios/

Contexto

mae_usuarios es la cuenta de acceso a la plataforma: una entidad (persona natural o jurídica) detrás de la cuenta (ADR 0025) y un rol del catálogo global de tipos de usuario (ADR 0026). El usuario es global: no lleva empresa_id ni RLS (ADR 0012 transversal); sus empresas se declaran aparte en rel_usuario_empresa. La tabla ya existe (ADR 0004) con username único, password (hash) y password_temp.

Decisión

Se implementa el CRUD de mae_usuarios bajo /api/v1/usuarios, con el patrón del servicio (router -> service -> repository, ADR 0001 transversal):

  • GET /usuarios lista los activos ordenados por username; GET /usuarios/{usuario_id} devuelve uno por UUID; DELETE es borrado lógico (204). El usuario inexistente o inactivo responde 404 «Usuario no encontrado».
  • La contraseña se guarda SIEMPRE hasheada con Argon2id (hash_password de app.core.security, ADR 0007): el service la hashea antes de persistir, en el POST y en el PUT si el payload la trae. Ningún contrato de lectura la expone.
  • El Read expone nombre_mostrar resuelto por el service según el tipo de la entidad asociada (ADR 0022 transversal): persona natural → nombres + apellidos, persona jurídica → la razón social. Si la entidad no existe, devuelve una cadena vacía. Por eso el service de usuarios devuelve MaeUsuariosRead —no el ORM—: el campo es calculado, no una columna.
  • Validaciones del POST y del PUT (sólo cuando el campo cambia): username duplicado entre activos → 409 «Ya existe un usuario con ese username»; entidad_id debe apuntar a una entidad activa → 404 «Entidad no encontrada»; tipo_usuario_id debe apuntar a un rol activo → 404 «Tipo de usuario no encontrado». El email no se valida como único: la columna no tiene constraint de unicidad.
  • UsuariosRepository hereda las lecturas de EntidadesRepository (para resolver nombre_mostrar) y de TiposUsuarioRepository (para validar tipo_usuario_id): el service coordina las reglas y el repository sólo lee las referencias que valida.

Alternativas descartadas

  • Exponer el hash en un Read — rompería el ADR 0007 y permitiría ataques de fuerza bruta fuera de línea; password sólo existe en los contratos de entrada y se descarta al proyectar.
  • Persistir la contraseña en claro o sin hash — descartado por construcción: el service llama hash_password incondicionalmente.
  • Resolver nombre_mostrar en el repository con un JOIN — el repository no conoce reglas de dominio (ADR 0001 transversal) y la resolución depende del tipo_entidad de la raíz polimórfica; el service la coordina reutilizando las lecturas existentes del slice de entidades.

Consecuencias

  • Desbloquea el login JWT (verificación de username + password contra el hash Argon2id) y la asignación de empresas y permisos del usuario (rel_usuario_empresa, rel_usuario_accion).
  • OpenAPI del servicio suma 5 endpoints bajo /api/v1/usuarios.
  • El repository y el service del dominio usuarios suman una clase por capa (UsuariosRepository, UsuariosService); MaeUsuariosRead agrega el campo calculado nombre_mostrar.