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 /usuarioslista los activos ordenados porusername;GET /usuarios/{usuario_id}devuelve uno por UUID;DELETEes borrado lógico (204). El usuario inexistente o inactivo responde404«Usuario no encontrado».- La contraseña se guarda SIEMPRE hasheada con Argon2id
(
hash_passworddeapp.core.security, ADR 0007): el service la hashea antes de persistir, en elPOSTy en elPUTsi el payload la trae. Ningún contrato de lectura la expone. - El Read expone
nombre_mostrarresuelto 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 devuelveMaeUsuariosRead—no el ORM—: el campo es calculado, no una columna. - Validaciones del
POSTy delPUT(sólo cuando el campo cambia):usernameduplicado entre activos →409«Ya existe un usuario con ese username»;entidad_iddebe apuntar a una entidad activa →404«Entidad no encontrada»;tipo_usuario_iddebe apuntar a un rol activo →404«Tipo de usuario no encontrado». Elemailno se valida como único: la columna no tiene constraint de unicidad. UsuariosRepositoryhereda las lecturas deEntidadesRepository(para resolvernombre_mostrar) y deTiposUsuarioRepository(para validartipo_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;
passwordsó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_passwordincondicionalmente. - Resolver
nombre_mostraren el repository con unJOIN— el repository no conoce reglas de dominio (ADR 0001 transversal) y la resolución depende deltipo_entidadde 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+passwordcontra 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
usuariossuman una clase por capa (UsuariosRepository,UsuariosService);MaeUsuariosReadagrega el campo calculadonombre_mostrar.