Especificação de Requisitos: Login sem Senha por E-mail e Auxílio de Configuração OAuth (req-032)

Esta especificação define o lote de trabalho req-032 (BATCH-032) para o Engenheiro Executor. O escopo abrange a expansão dos métodos de login do gestor com uma quarta opção (Login sem Senha via Código por E-mail) e a adição de links de auxílio ("How-To") e instruções de configuração para os provedores de login social (Google e Meta) na interface do painel administrativo.

1. Configurações Globais no Módulo admin-environment

Na aba Configurações de Usuário (data-tab="usuario"), adicionar os seguintes elementos na interface:

1.1 Quarto Método de Login (Login sem Senha via E-mail)

• Variável: AUTH_METHOD_EMAIL_ACTIVE (Checkbox, default false, salvo no .env como AUTH_METHOD_EMAIL_ACTIVE).

• Rótulo: "Habilitar login sem senha via Código por E-mail".

• Comportamento: Permite que usuários se autentiquem no sistema apenas informando o e-mail cadastrado, recebendo um código de acesso de 6 dígitos sem a necessidade de fornecer sua senha pessoal.

1.2 Links e Auxílio de Configuração ("How-To") para Google/Meta OAuth

Exibir instruções e links diretos para auxiliar o administrador a configurar as credenciais de login social.

• Para o Google:

  • Exibir texto descritivo: "Para configurar: Acesse o Google Cloud Console, crie um projeto, vá em 'Tela de consentimento OAuth', depois em 'Credenciais' -> 'Criar credenciais' -> 'ID do cliente OAuth' (Aplicativo Web). Adicione a URI de redirecionamento abaixo em 'URIs de redirecionamento autorizadas'."

  • Link direto: [REDACTED] (abrir em nova aba).

• Para o Facebook/Meta:

  • Exibir texto descritivo: "Para configurar: Acesse o portal Meta for Developers, crie um aplicativo do tipo 'Consumidor', adicione o produto 'Login do Facebook', vá em 'Configurações do Login do Facebook' e insira a URI de redirecionamento abaixo em 'URIs de redirecionamento do OAuth válidas'."

  • Link direto: [REDACTED] (abrir em nova aba).

• As mensagens devem estar devidamente internacionalizadas nos manifests e arquivos JSON/HTML correspondentes (pt-br e en).

2. Fluxo de Login sem Senha no Módulo perfil-usuario

O formulário de login (acessar-sistema) e seu controlador backend devem ser adaptados para suportar o novo método de autenticação:

2.1 Interface do Login (acessar-sistema.html)

• Se AUTH_METHOD_EMAIL_ACTIVE for true:

  • Se AUTH_METHOD_PASSWORD_ACTIVE também for true:

  • Apresentar abas ou botões alternadores (toggles) permitindo ao usuário alternar entre "Entrar com Senha" e "Entrar com Código por E-mail".

  • Ao selecionar "Código por E-mail", o campo de senha (senha) e eventuais campos extras não pertinentes são ocultados, deixando apenas o campo de identificação (e-mail/usuário) e o botão de ação.

  • Se AUTH_METHOD_PASSWORD_ACTIVE for false (desabilitado):

  • Ocultar completamente o campo de senha. A tela de login exibirá apenas o campo de entrada do e-mail e o botão "Enviar Código de Acesso".

• Os botões de login social (Google/Meta) continuam sendo renderizados normalmente conforme suas respectivas configurações globais.

2.2 Fluxo Backend do Login por Código (perfil-usuario.php)

Ao submeter o e-mail no modo "Entrar com Código por E-mail":

1. O backend verifica se AUTH_METHOD_EMAIL_ACTIVE está ativado.

2. Busca o usuário na tabela usuarios utilizando o e-mail ou nome de usuário fornecido.

3. Valida se o usuário existe e se o status dele é ativo (status = 'A').

4. Em caso positivo (e-mail/usuário válido):

   • Gera um código de 6 dígitos de uso único.

   • Grava o código e expiração (5 minutos) na tabela usuarios utilizando as colunas existentes two_factor_email_code e two_factor_email_expire.

   • Dispara o e-mail de notificação com o código de verificação reutilizando a biblioteca 2fa.php -> two_factor_email_send_code().

   • Registra o fluxo de login temporário nas variáveis de sessão do sistema:

     • pending_2fa_user = ID do usuário.

     • pending_2fa_mode = 'verify'.

     • pending_2fa_type = 'email'.

   • Redireciona o usuário para a página signin-2fa/.

5. Se o e-mail/usuário não for encontrado, exibe uma mensagem de erro genérica padrão (evitando exposição de existência de e-mail por motivos de segurança).

6. A página signin-2fa/ já possui a lógica de validação do código de e-mail e finalização automática de login (perfil_usuario_finalizar_login()), que deve ser mantida.

3. Atualização do Arquivo de Template (.env)

• Adicionar no arquivo de template global gestor/autenticacoes.exemplo/dominio/.env a nova seção contendo as variáveis criadas no BATCH-030 e BATCH-032 com seus valores default:

  • AUTH_METHOD_PASSWORD_ACTIVE=true

  • AUTH_METHOD_GOOGLE_ACTIVE=false

  • OAUTH_GOOGLE_CLIENT_ID=

  • OAUTH_GOOGLE_CLIENT_SECRET=SECRET

  • AUTH_METHOD_META_ACTIVE=false

  • OAUTH_META_APP_ID=

  • OAUTH_META_APP_SECRET=SECRET

  • AUTH_2FA_REQUIRED=false

  • AUTH_2FA_METHOD_APP=true

  • AUTH_2FA_METHOD_EMAIL=true

  • AUTH_JWT_ROTATION_DAYS=30

  • AUTH_JWT_GRACE_HOURS=24

  • AUTH_METHOD_EMAIL_ACTIVE=false

4. Critérios de Aceitação e Validação

• Validação de Interface: Habilitar/desabilitar os toggles no painel administrativo e conferir a reatividade da tela de login (ocultação/exibição da senha e botões alternadores).

• Envio de Código: Testar o fluxo de login sem senha inserindo um e-mail válido, verificando se o código é enviado à caixa de entrada e gravado nas tabelas com prazo de expiração correto.

• Validação e Acesso: Digitar o código recebido no e-mail na tela de 2FA e comprovar que o usuário acessa o painel normalmente sem digitar senha em nenhum momento.

• Validação de Linting: Garantir que as alterações passem por php -l e node --check.