user

O submódulo User cuida do lado administrativo do gerenciamento de contas de usuário: criação, atualização de perfil, tratamento de avatar, atribuição de roles, inspeção de permissões e verificação de identificadores. Ele é intencionalmente separado do submódulo Profile, que trata das operações de autoatendimento realizadas por usuários autenticados em suas próprias contas, aplicando o princípio do menor privilégio na fronteira da API.

Administradores com a role admin ou admin-user podem criar novas contas com nome, e-mail e senha inicial. As atualizações de conta permitem alterar o nome de exibição. As redefinições de senha definem uma nova senha em nome do usuário sem exigir a senha atual, o que é útil para contas bloqueadas e fluxos de onboarding em que a credencial inicial precisa ser redefinida imediatamente. A exclusão via DELETE /user remove as contas permanentemente, sem opção de soft-delete.

Os avatares de usuário são armazenados por meio do submódulo File. POST /user/:userId/avatar aceita uma imagem multipart, a armazena e vincula o registro de File resultante ao usuário. O avatar fica então publicamente acessível em GET /user/avatar/:fileId sem autenticação, permitindo o embedding em templates de e-mail, perfis públicos e integrações de terceiros. Os donos do perfil também podem gerenciar seu próprio avatar por meio de PUT /profile/avatar no submódulo Profile.

A atribuição de roles pode ser gerenciada pelo lado do usuário: POST /user/:userId/role/:roleId atribui uma única role e DELETE /user/:userId/role/:roleId a revoga. GET /user/:userId/role lista todas as roles que um usuário possui no momento. Esses endpoints complementam a abordagem de substituição em lote do submódulo Role — ambos os caminhos gravam na mesma tabela de junção e podem ser usados de forma intercambiável.

Os endpoints de inspeção de permissões GET /user/:userId/menu e GET /user/:userId/route retornam o conjunto efetivo de entradas de menu e rotas HTTP acessíveis a um usuário específico, calculado a partir da união de todas as roles atribuídas. Eles são usados pelo painel de administração para exibir um resumo preciso do que um usuário pode fazer, sem exigir que o administrador una manualmente várias definições de role.

Os identificadores de usuário (endereços de e-mail) passam por um fluxo de verificação por padrão. POST /user/:userId/verify-identifier/:identifierId permite que administradores marquem à força um identificador como verificado, ignorando a etapa de confirmação por e-mail. Isso é útil para semear usuários de teste, migrar contas de sistemas legados ou resolver escalonamentos de suporte em que o usuário não consegue acessar o e-mail de verificação.