Ingestão de Dados

O GamiBot sincroniza atividades Ficheiro (resource) e Pasta de uma disciplina Moodle que tenha o seu próprio bloco GamiBot. Ao adicionar o bloco a uma disciplina existente, os conteúdos já presentes e elegíveis entram na fila. Novos carregamentos, edições, alterações de visibilidade e remoções entram na mesma fila persistente, partilhada por todo o site. Um botão flutuante global ou bloco de categoria não ativa, por si só, a disciplina.

O Moodle envia notificações ao endpoint de ingestão configurado; o serviço recetor trata da obtenção e indexação dos ficheiros. No serviço atual, Docling processa os ficheiros, Ollama serve o modelo de embeddings nomic-text e Qdrant guarda o índice. O plugin Moodle não extrai texto, não gera embeddings nem garante formatos de ficheiro específicos. Os limites de envio regulam os pedidos ao recetor, não o processamento interno deste.

Conteúdos elegíveis

O índice partilhado da disciplina recebe conteúdos apenas de uma disciplina, secção e atividade visíveis, apresentados na página da disciplina e não pendentes de eliminação. Atividades ocultas da página da disciplina são excluídas. Os conteúdos de uma subsecção herdam a visibilidade e as restrições dos elementos superiores.

O plugin avalia regras de disponibilidade baseadas apenas em datas, incluindo abertura e fecho. Qualquer árvore de regras com condições específicas do aluno ou outras condições não baseadas em datas — como grupo, nota, conclusão ou perfil — é excluída por inteiro. Antes de cada envio, o processo verifica novamente a elegibilidade. O acesso pessoal de um docente não altera estas regras do índice partilhado. O webhook não substitui uma verificação de autorização por aluno no momento da pesquisa.

Fila global e limites de envio

As ações de edição no Moodle colocam trabalho em fila sem esperar pelos pedidos de rede. A tarefa agendada Synchronise GamiBot resource availability deteta alterações de elegibilidade e envia o trabalho em fila, por defeito a cada minuto. Existe apenas um processo de envio de cada vez, mesmo com vários processos de cron. Para todas as disciplinas e edições simultâneas, os valores predefinidos são:

Definição básica	Valor predefinido	Efeito
Pedidos de ingestão por execução do cron	5	No máximo cinco passos de envio; cada passo envia no máximo um pedido. Intervalo 1–100.
Intervalo mínimo entre pedidos de ingestão	5 segundos	Intervalo mínimo entre inícios de pedidos, comum a todas as disciplinas e processos. Intervalo 1–3600.

Uma execução deixa de iniciar trabalho após 30 segundos; intervalos longos e pastas grandes continuam em execuções seguintes. Os pedidos falhados permanecem na fila, fazem a tarefa agendada falhar de forma visível e são repetidos com espera exponencial entre um minuto e uma hora. A fila guarda a posição dentro de pastas grandes para evitar recomeçar em cada execução. Aumente o intervalo ou reduza o lote se o serviço de ingestão ficar sobrecarregado.

Quando um Ficheiro ou Pasta muda, o Moodle envia a eliminação do módulo antes dos carregamentos de substituição. Remover o último bloco GamiBot da disciplina ou eliminar a disciplina coloca a limpeza na fila. A remoção é assíncrona: o material já indexado pode continuar no serviço recetor até que a eliminação seja processada. Verifique as remoções pendentes quando for necessário retirar o acesso a material.

Contrato do webhook

Os carregamentos são pedidos POST JSON com event: "file_uploaded", o secret configurado, moodle_url, course_id, section_id, section_name, module_id, module_name, file_url, filename, mimetype e filesize. O file_url é um URL de ficheiro dos serviços web do Moodle; o recetor precisa de acesso adequado ao Moodle para obter o conteúdo.

As eliminações usam event: "file_deleted", secret, moodle_url, course_id e module_id. O segredo é um valor no corpo JSON; o Moodle não acrescenta uma assinatura HMAC. O recetor deve autenticar o segredo, usar TLS e tratar como idempotente a eliminação de todos os vetores desse site Moodle, disciplina e módulo. Se tiver uma fila interna, deve aplicar a eliminação de um módulo antes dos carregamentos posteriores desse módulo.

O Moodle só considera um pedido recebido após uma resposta HTTP 2xx. Essa resposta confirma a receção, não a conclusão da indexação ou eliminação no recetor. Por isso, uma fila Moodle vazia não prova que o índice remoto esteja atualizado.

Reconciliar e consultar o estado

Execute o cron do Moodle pelo menos uma vez por minuto. A partir da raiz do Moodle, um administrador pode colocar uma disciplina ou todas as disciplinas ativas na fila e consultar o trabalho pendente:

php local/gamibot_manager/cli/sync_resources.php --courseid=42
php local/gamibot_manager/cli/sync_resources.php --all
php local/gamibot_manager/cli/sync_resources.php --status
php local/gamibot_manager/cli/sync_resources.php --status --courseid=42

Estes comandos colocam trabalho em fila ou mostram o estado; é o cron que o envia à velocidade configurada. O estado inclui módulos pendentes, remoções, novas tentativas e trabalho retido para outro endpoint. Ao mudar o endpoint, o trabalho pendente para o destino antigo fica retido, em vez de ser enviado ao novo. Organize a limpeza no serviço antigo ou reponha o endpoint anterior para processar esse trabalho.

Ao atualizar uma instalação antiga cujo recetor já contém vetores, organize a limpeza do índice histórico deste site Moodle no recetor e depois use --all para colocar os ficheiros elegíveis atuais na fila. A fila não consegue descobrir vetores de módulos já eliminados do Moodle. Alterações de disponibilidade, acumulação de trabalho, tentativas e processamento remoto impedem garantir um momento exato de sincronização.

Consulte Configuração do Moodle e teste o GamiBot.