Agendador de Relatórios

descrição Geral

A funcionalidade de Agendamento de Relatórios é uma ferramenta projetada para automatizar a geração e distribuição periódica de relatórios dentro de um sistema de gerenciamento de frota. Esta funcionalidade permite aos usuários configurar a geração automática de relatórios específicos, como o Histórico de Cidades, determinando sua periodicidade (diária, semanal ou mensal) e configurando os destinatários que receberão estes relatórios por e-mail. Para acessar a opção utilize o menu CONFIGURAÇÕES e a opção AGENDAMENTO DE RELATÓRIOS.

O sistema é composto por duas telas principais:

• Tela de cadastro/edição de agendamento
• Tela de listagem de agendamentos configurados

Elementos da Interface

Tela de Cadastro/Edição de Agendamento

Seção de Cabeçalho

• Título: "Agendador de Relatório"
• Subtítulo: "Relatório: Histórico de Cidades" (O nome do relatório selecionado)

Seção de Configuração Básica

• Nome: Campo de texto para identificação do agendamento
  • Exemplo: "Agenda Histórico de Cidades Mensal"
  • Obrigatório
  • Sem limite específico de caracteres
• Enviar às (hh:mm): Campo de texto com máscara para horário
  • Formato 24h (00:00 a 23:59)
  • Exemplo: "07:12"
  • Obrigatório
  • Determina o horário que o relatório será gerado e enviado

Seção de Periodicidade

• Periodicização a cada: Conjunto de campos para definir a frequência
  • Campo numérico para quantidade (valor mínimo 1)
  • Dropdown para seleção da unidade de tempo
    • Opções: "Dias", "Semanas", "Mês/Meses"
  • Obrigatório

Seção de Dias da Semana (visível apenas quando "Semanas" está selecionado)

• E repetir: Conjunto de checkboxes para os dias da semana
  • Opções: Segunda, Terça, Quarta, Quinta, Sexta, Sábado, Domingo
  • Pelo menos um dia deve ser selecionado quando periodicidade é semanal
  • No exemplo, Sexta e Sábado estão selecionados

Seção de Data Limite

• Até o dia: Campo de data
  • Formato: DD/MM/AAAA
  • Opcional
  • Define até quando o agendamento estará ativo

Seção de Destinatários

• Destinatários: Conjunto de 6 campos para e-mails
  • Formato: e-mail válido (texto@domínio.com)
  • Apenas o primeiro é obrigatório
  • Nos demais campos aparecem placeholders: "Destinatário 2", "Destinatário 3", etc.
  • Exemplo do primeiro campo preenchido: "moisesf@gmail.com"

Seção Formato

• Indica o formato que o relatório será enviado por email. Os formatos póssíveis são PDF, XLS, TXT e RTF. Não permite alteração. Caso queria alterar o formato deve-se excluir o agendamento e criar um novo com o formato desejado.

Botões de Ação

• Gravar: Botão verde para salvar as configurações
• Excluir: Botão vermelho para remover o agendamento
• Voltar: Botão cinza para retornar à tela de listagem

Tela de Listagem de Agendamentos

Seção de Cabeçalho

• Título: "Agendador de Relatórios"

Seção de Filtros

• Filtros: Seção expansível
  • Nome: Campo de texto para filtrar pelo nome do agendamento
  • Periodicidade: Dropdown com opções de periodicidade
  • Botões de ação à direita (busca, exportação e adição)

Tabela de Agendamentos

• Colunas:
  • Nome: Nome do agendamento cadastrado
  • Relatório: Tipo de relatório configurado
  • Horário: Horário programado para execução
  • Periodicidade: Frequência configurada (exibida em formato textual)
  • Repetir Até: Data limite para o agendamento (quando definida)
  • Última Execução: Data e hora da última vez que o relatório foi executado
  • N.: Número sequencial ou contador (nã
  • Formato: Formato que o visívelrelatório completamente)será enviado. Opções: PDF, XLS, TXT e RTF.

Dados Exibidos (exemplo)

• Um agendamento com nome "Agenda Histórico de Cidades Mensal"
• Relatório do tipo "Histórico de Cidades"
• Horário de execução às "07:12:00"
• Periodicidade "Toda semana [ Sexta, Sábado ]"
• Última execução em "2025-03-14 07:19:38.0"
• Valor "0" na coluna N.

Propósito e Fluxo de Trabalho

O propósito principal deste sistema é automatizar a geração e distribuição de relatórios, economizando tempo e garantindo que relatórios importantes sejam gerados de forma consistente e enviados aos interessados.

Fluxo de trabalho básico:

1. O usuário acessa a tela de listagem de agendamentos
2. Para criar um novo agendamento, o usuário clica no botão de adicionar (ícone verde à direita)
3. Na tela de cadastro, o usuário:
   • Seleciona o tipo de relatório (pré-configurado na tela)
   • Fornece um nome para identificar o agendamento
   • Define o horário para execução
   • Configura a periodicidade (diária, semanal ou mensal)
   • Se semanal, seleciona os dias da semana
   • Se mensal, define o dia do mês
   • Opcionalmente, define uma data limite para o agendamento
   • Insere pelo menos um e-mail de destinatário
4. O usuário clica em "Gravar" para salvar o agendamento
5. O sistema retorna à tela de listagem onde o novo agendamento aparece
6. O sistema, nos bastidores, executará o relatório conforme a programação e enviará aos destinatários

Para editar um agendamento existente, o usuário seleciona o registro na tabela de listagem. Para remover, utiliza o botão "Excluir" na tela de edição.

Instruções Passo-a-Passo

Como criar um novo agendamento de relatório:

1. Acesse a tela de listagem de agendamentos
2. Clique no botão verde à direita (ícone de adição)
3. Na tela de cadastro:
   • Digite um nome descritivo para o agendamento
   • Defina o horário de envio no formato HH:MM
   • Configure a periodicidade:
     • Digite o número no campo "Periodicização a cada"
     • Selecione a unidade de tempo (Dias, Semanas, Mês/Meses)
   • Se escolher periodicidade semanal:
     • Marque as caixas correspondentes aos dias da semana desejados
   • Se escolher periodicidade mensal:
     • Digite o dia do mês (1-31)
   • Opcionalmente, defina uma data limite no campo "Até o dia"
   • Preencha pelo menos o primeiro campo de e-mail destinatário
   • Adicione destinatários adicionais nos campos restantes, se necessário
4. Clique no botão "Gravar" para salvar o agendamento
5. O sistema retornará automaticamente à tela de listagem

Como editar um agendamento existente:

1. Na tela de listagem, clique na linha do agendamento que deseja editar
2. Faça as alterações necessárias nos campos disponíveis
3. Clique no botão "Gravar" para salvar as modificações

Como excluir um agendamento:

1. Na tela de listagem, clique na linha do agendamento que deseja excluir
2. Na tela de edição, clique no botão "Excluir" (vermelho)
3. Confirme a operação quando solicitado

Como filtrar agendamentos na listagem:

1. Na seção de filtros, digite um termo no campo "Nome" para filtrar por nome do agendamento
2. Selecione uma opção no dropdown "Periodicidade" para filtrar por tipo de periodicidade
3. Clique no botão de busca (ícone de lupa) para aplicar os filtros

Regras de Negócio e Validações

Com base na análise do sistema, podemos identificar as seguintes regras de negócio e validações:

1. Validações de campos obrigatórios:

   • O nome do agendamento deve ser preenchido
   • O horário de envio deve ser preenchido e válido
   • A periodicidade deve ser configurada
   • Se periodicidade for semanal, ao menos um dia da semana deve ser selecionado
   • Se periodicidade for mensal, o dia do mês deve ser válido (1-31)
   • Pelo menos um destinatário de e-mail deve ser fornecido

2. Validações de formato:

   • Horário deve estar no formato HH:MM (24h)
   • E-mails devem estar em formato válido
   • Data limite deve estar no formato DD/MM/AAAA e ser uma data futura

3. Funcionalidade de repetição:

   • Dependendo da periodicidade selecionada, os campos de configuração exibidos variam
   • Com periodicidade semanal, os checkboxes de dias da semana são mostrados
   • Com periodicidade mensal, um campo para o dia do mês é mostrado

4. Automação:

   • O sistema executa automaticamente os relatórios nos horários configurados
   • Os relatórios são enviados para os e-mails cadastrados
   • O sistema registra a data e hora da última execução

Perguntas Frequentes (FAQ)

1. Como configuro um relatório para ser enviado diariamente?

Para configurar um relatório diário, selecione "Dias" no dropdown de periodicidade e coloque "1" no campo numérico. Defina o horário desejado e adicione os e-mails dos destinatários.

2. Posso configurar um relatório para ser enviado apenas em dias específicos da semana?

Sim. Selecione "Semanas" no dropdown de periodicidade e marque apenas os dias da semana desejados na seção "E repetir".

3. Como faço para que o relatório seja enviado uma vez por mês, sempre no mesmo dia?

Selecione "Mês/Meses" no dropdown de periodicidade, coloque "1" no campo numérico e especifique o dia do mês desejado.

4. O que acontece se eu configurar o dia 31 para um relatório mensal?

Para meses que não possuem o dia 31, o sistema executará o relatório no último dia do mês.

5. Posso limitar por quanto tempo um agendamento ficará ativo?

Sim. Utilize o campo "Até o dia" para definir uma data limite. Após essa data, o agendamento não será mais executado.

6. Quantos destinatários posso adicionar para receber o relatório?

O sistema permite até 6 endereços de e-mail diferentes como destinatários.

7. Como sei se o agendamento está funcionando corretamente?

Na tela de listagem, você pode verificar a coluna "Última Execução" que mostra a data e hora da última vez que o relatório foi executado com sucesso.

8. Posso pausar temporariamente um agendamento sem excluí-lo?

Não há uma função específica de pausa, mas você pode editar o agendamento e definir uma data no passado no campo "Até o dia" para desativá-lo, e depois alterar para uma data futura quando quiser reativá-lo.

9. O que acontece se eu não preencher o campo "Até o dia"?

Se não for definida uma data limite, o agendamento continuará ativo indefinidamente até que seja excluído manualmente.

10. Posso visualizar o conteúdo dos relatórios antes de agendar?

O sistema de agendamento não possui visualização prévia. Recomenda-se gerar o relatório manualmente primeiro para verificar seu conteúdo antes de configurar o agendamento.

Com base no arquivo SenderAgendarRelatoriosFachada.java, vou complementar a documentação anterior com detalhes importantes sobre o funcionamento interno do sistema de agendamento de relatórios, especialmente quanto aos mecanismos de execução e regras de processamento.

Complemento

Mecanismo de Execução Automática

O sistema utiliza um mecanismo automatizado (robô) para execução dos relatórios agendados. Este processo verifica periodicamente quais relatórios devem ser executados com base em suas configurações. Vamos detalhar seu funcionamento:

Processo de Verificação e Envio

1. O sistema recupera a lista de relatórios agendados pendentes de envio via método recuperarListaParaEnviar().

2. Para cada agendamento, realiza validações específicas de acordo com a periodicidade:

   • Verifica se o horário atual é igual ou posterior ao configurado
   • Confirma se o dia atual corresponde ao programado
   • Confirma se o relatório ainda não foi executado hoje
   • Verifica regras específicas para periodicidade semanal ou mensal

3. Quando um agendamento atende aos critérios, o sistema:

   • Autentica-se com as credenciais do cliente
   • Gera o relatório solicitado, convertendo os parâmetros conforme necessário
   • Envia o relatório por e-mail aos destinatários configurados
   • Registra a execução no histórico do agendamento

Regras de Execução Detalhadas

Para Relatórios Mensais:

• Na primeira execução: verifica se o dia atual coincide com o dia programado e se o horário é válido
• Nas execuções seguintes: verifica se o mês atual corresponde ao próximo mês esperado após a última execução (considerando o passo de repetição configurado)
• Ajusta automaticamente para o último dia do mês quando o dia configurado não existe no mês atual (ex: dia 31 em fevereiro)

Para Relatórios Semanais:

• Na primeira execução: verifica se o dia atual da semana está entre os selecionados e se o horário é válido
• Nas execuções seguintes: verifica se a semana atual corresponde à próxima semana esperada após a última execução (considerando o passo de repetição configurado em semanas)
• Executa apenas nos dias da semana que foram marcados na configuração

Ajuste Automático de Datas

O sistema possui um mecanismo inteligente para ajustar automaticamente as datas de início e fim dos relatórios:

1. Quando um relatório é agendado com um período específico (ex: últimos 30 dias), o sistema calcula a diferença entre a data do agendamento e a data atual.

2. Aplica essa diferença às datas de início e fim do período do relatório, mantendo a mesma amplitude relativa, mas atualizando-as para o momento atual.

3. Isso garante que relatórios periódicos sempre apresentem dados atualizados em relação ao momento de sua execução, não ficando presos ao período original do agendamento.

Comunicação e Processamento

O sistema realiza as seguintes operações de comunicação na geração de relatórios:

1. Autenticação: Realiza autenticação segura usando um hash gerado a partir do ID do cliente e da empresa.

2. Requisição de Relatório: Constrói uma requisição HTTP com todos os parâmetros necessários para a geração do relatório.

3. Processamento de Resposta: Recebe e processa a resposta (geralmente um arquivo PDF), salvando-o temporariamente.

4. Preparação de E-mail: Utiliza um template personalizado contendo:

   • Nome do agendamento
   • Nome do cliente
   • Data e hora de geração
   • Nome descritivo do relatório
   • Período abrangido (data/hora início e fim)
   • Dados da empresa (nome fantasia e site)

5. Envio: Distribui o e-mail com o relatório anexado para todos os destinatários configurados.

Tratamento de Erros e Situações Especiais

O sistema implementa as seguintes estratégias para lidar com situações excepcionais:

1. Falhas de Autenticação: Se a autenticação falhar, o sistema registra o erro e interrompe o processamento daquele relatório.

2. Validação de E-mails: Antes de enviar, valida cada endereço de e-mail configurado, utilizando apenas os que possuem formato válido.

3. Datas Inexistentes: Para relatórios mensais programados para dias que não existem em todos os meses (como dia 31), o sistema ajusta automaticamente para o último dia do mês.

4. Parâmetros Dinâmicos: Os parâmetros de data são recalculados dinamicamente a cada execução, garantindo que os relatórios sempre apresentem dados atualizados.

5. Limite de Execução: Respeita a configuração de data limite ("Até o dia"), não executando relatórios após essa data.

Considerações Técnicas Adicionais

1. O sistema utiliza templates Velocity para a geração padronizada do corpo do e-mail.

2. Os arquivos de relatório são gerados como PDFs e anexados ao e-mail.

3. O registro de execução permite rastrear todas as gerações de relatórios, controlando a frequência e evitando duplicações.

4. A validação de horário usa a comparação com o horário do sistema, permitindo a execução mesmo se o momento exato for perdido (desde que o horário atual seja posterior ao programado).

5. O sistema mantém registro detalhado de logs para fins de auditoria e resolução de problemas.

6. Há um mecanismo de conversão entre diferentes formatos de data para garantir a compatibilidade entre os diversos componentes do sistema.

Esta complementação esclarece o funcionamento interno do sistema de agendamento, fornecendo uma visão mais completa de como os relatórios são processados, ajustados e enviados automaticamente conforme as configurações definidas pelo usuário.