Docs › Para clientes › Guia do administrador

Guia do administrador

Configuração do Chat com tutor (local_tutorchat): configurações, papéis e permissões, onde o chat funciona, cartões de atividade, licença, diagnóstico, tarefas agendadas e solução de problemas. A instalação e a atualização estão em Requisitos e instalação. Quem usa o chat tem guias próprios: tutor, aluno e supervisor. Dúvidas frequentes: perguntas frequentes.

4. Configurações

Em Administração do site → Plugins → Plugins locais → Chat com tutor. Os campos aparecem nesta ordem; os quatro últimos formam o bloco Onde o chat funciona. Os campos numéricos aceitam só números inteiros; um valor menor que 1 (ou vazio) faz o plugin usar o padrão (exceto Dias depois do término, em que 0 é um valor válido).

Observações:

• Intervalos de atualização. Em sites grandes, aumentar os intervalos reduz a carga no servidor, ao custo de mensagens que demoram mais a aparecer. O aluno que não está em um atendimento aberto e está com a janela do chat fechada não faz nenhuma consulta periódica. Com uma conversa na tela, o intervalo começa no valor do chat aberto e, depois de 1 minuto sem mensagens, cresce até o maior intervalo com a conversa em silêncio. Se o servidor demora a responder, o navegador espera mais entre as consultas.
• Cores. Use valores hexadecimais (por exemplo #357a32). A cor do texto sobre elas é escolhida automaticamente para manter o contraste. As demais cores do chat vêm do tema do site; as cores dos rótulos de papel (seção 5) são uma paleta fixa de seis e não são configuráveis.
• Campos no painel. Um campo escolhido só é mostrado ao tutor que pode vê-lo no Moodle, e só quando tem valor.
• Avaliação. Os tutores nunca veem as avaliações; elas aparecem apenas na supervisão.

5. Papéis e permissões

Tutores

1. Crie um papel para os tutores ou use um existente (por exemplo, "Professor"). Para criar: Administração do site → Usuários → Permissões → Definir papéis → Adicionar um novo papel, sem arquétipo, permitindo atribuí-lo no nível de Curso.
2. Em Chat com tutor → Papéis de tutor, marque o papel e salve. Isso concede local/tutorchat:tutor ("Atender alunos como tutor") ao papel, no nível do site.
3. Em cada curso, inscreva os tutores com esse papel (Participantes). Só tutores com inscrição ativa no curso são listados aos alunos.

Cada tutor passa a ver o link Área do tutor no menu principal.

Se você desmarcar um papel em Papéis de tutor, a capability é removida dele no nível do site. Alterações feitas em um curso (substituições de permissão) não são desfeitas.

Alunos

local/tutorchat:chat ("Conversar com os tutores de um curso") vem permitida por padrão ao papel Estudante. Quem a tem em um curso vê o botão do chat nas páginas dele, desde que o curso tenha ao menos um tutor que o aluno possa contatar.

Desligar o chat em um curso

Há dois caminhos. Para ligar o chat só onde você quer (por exemplo, ao colocá-lo em produção aos poucos), use Onde o chat funciona, descrito na seção 5-A: o curso fora da lista fica congelado e o histórico continua legível. Para tirar um curso do alcance das pessoas sem nenhuma tela, proíba local/tutorchat:chat (alunos) ou local/tutorchat:tutor (tutores) nas permissões desse curso; a proibição não deixa uma tela somente leitura com o histórico.

Tutores por grupo

Em cursos com grupos separados, o aluno só vê os tutores que pertencem a algum grupo dele; um aluno sem grupo não vê nenhum. Quem tem moodle/site:accessallgroups vê todos.

Supervisão

Duas capabilities, verificadas no contexto do sistema. Nenhuma delas é concedida a papel algum por padrão, nem a gerentes. Os administradores do site já têm ambas.

Para conceder:

1. Administração do site → Usuários → Permissões → Definir papéis → Adicionar um novo papel (arquétipo: nenhum).
2. Permita viewreports (e, se quiser que o papel leia conversas, viewconversations) e marque o papel como atribuível no nível Sistema.
3. Atribua o papel em Administração do site → Usuários → Permissões → Atribuir papéis do sistema.

A página também está em Administração do site → Relatórios → Supervisão do chat. Conceder essas permissões em um curso ou categoria não tem efeito.

O uso da página está descrito no guia do supervisor.

Ler conversas é um acesso a dados pessoais: cada abertura fica registrada no log do site (evento "Conversa lida pela supervisão"), e cada exportação também ("Relatório da supervisão exportado"). Veja privacidade.

5-A. Onde o chat funciona

Por padrão o chat funciona em todos os cursos do site. O bloco Onde o chat funciona, na página de configurações do plugin, deixa você ligá-lo só em algumas categorias e cursos (e ampliar aos poucos) e esconder o chat dos cursos terminados.

As quatro configurações

• As duas listas vazias significam o site inteiro, como antes. Basta escolher uma categoria ou um curso para o chat deixar de funcionar nos demais.
• Uma categoria escolhida vale para a árvore toda: as subcategorias e os cursos delas entram.
• Ao salvar, ids de cursos ou categorias que não existem mais são descartados. Se uma categoria ou um curso escolhido for excluído depois, nada quebra: ele simplesmente não corresponde a nenhum curso.
• A página inicial do site continua sem chat, como sempre.
• Qualquer mudança nestas quatro configurações limpa o cache tutoranywhere.
• Com tudo no padrão (nada escolhido e a opção desligada) os caminhos de leitura não fazem nenhuma consulta nova ao banco. A exceção são os caminhos de escrita: enviar uma mensagem ou encerrar um atendimento passa a conferir a matrícula ativa de quem escreve (is_enrolled), o que o Moodle normalmente responde com os dados da sessão do usuário.

Os três estados de um curso

Cada curso está sempre em um destes estados, avaliados nesta ordem:

1. Terminado: Esconder o chat em cursos terminados ligada, o curso tem data de término e essa data mais os dias de tolerância já passou. Um curso sem data de término nunca é terminado.
2. Ativo: nenhuma categoria e nenhum curso escolhidos, ou o curso está em Cursos, ou está em uma categoria de Categorias (ou em uma subcategoria dela).
3. Inativo: qualquer outro caso, isto é, há uma lista escolhida e o curso não consta dela.

Congelamento (curso inativo)

• As conversas abertas ficam somente leitura para o aluno e para o tutor: o campo de mensagem e os botões de encerrar somem, o histórico continua visível e ninguém abre uma conversa nova.
• O bloqueio vale na hora: a recusa de abrir conversa e de enviar mensagem não depende da tarefa agendada. Quem estava com a tela aberta e tenta enviar recebe o aviso e a conversa passa a somente leitura sem recarregar.
• Uma conversa congelada continua sujeita ao Encerramento automático: como ninguém pode escrever, ela é encerrada pela tarefa de atendimentos inativos quando completa esse prazo sem mensagem nova.
• O widget somente leitura não consulta o servidor periodicamente: nada pode mudar nele. Se o curso voltar a ficar ativo, o aluno vê a mudança depois de recarregar a página.
• Reativar o curso (incluí-lo nas listas) não reabre as conversas já encerradas; o aluno abre uma nova.

Cursos terminados

• Só valem com Esconder o chat em cursos terminados ligada. Desligada, a data de término é ignorada, como antes.
• Passada a data (mais os dias de tolerância) o chat some do curso para o aluno e o curso deixa de contar para o link Área do tutor.
• A tarefa agendada Encerrar atendimentos inativos do chat com tutor (seção 7) fecha as conversas abertas de cursos terminados, deixando "encerrado por" em branco (como no encerramento automático). Os atendimentos fechados continuam legíveis para quem participou e para a supervisão. Até a tarefa rodar (no máximo cerca de uma hora, porque ela roda de hora em hora) a conversa já está bloqueada para escrita, mas ainda consta como aberta.
• Para estender um curso, aumente os Dias depois do término ou a data de término do curso. Conversas que a tarefa já fechou não são reabertas automaticamente.

Inscrição ativa para escrever

Enviar mensagem e encerrar uma conversa passam a exigir inscrição ativa de quem escreve:

• Um aluno com inscrição suspensa ou encerrada, mesmo com o papel ainda atribuído, não consegue mais escrever em uma conversa aberta (antes isso era possível chamando o serviço diretamente).
• O tutor com inscrição suspensa também não escreve.
• Só a inscrição de quem escreve é conferida: o tutor com inscrição ativa continua podendo responder na conversa aberta de um aluno que foi suspenso depois.

O link "Área do tutor" e o atraso de até 10 minutos

• O link Área do tutor no menu principal só aparece para quem é tutor de pelo menos um curso ativo.
• A página continua abrindo pelo endereço direto (/local/tutorchat/index.php) para qualquer tutor e lista todas as conversas dele, com a marca nas de cursos que não estão ativos. Um tutor só de cursos inativos ou terminados não vê o link, mas consegue ler o histórico pelo endereço.
• A informação "este usuário é tutor de algum curso ativo" fica no cache tutoranywhere (600 s). Quando um curso muda de categoria ou de data de término, o link pode levar até 10 minutos para aparecer ou sumir. O bloqueio das conversas não usa esse cache e vale na hora. Mudar uma das quatro configurações acima limpa o cache.

5-B. Cartões de atividade e formatos de curso

O tutor pode enviar ao aluno um cartão de uma atividade, de um recurso ou de uma seção do curso, e o aluno pode anexar a página em que está (veja o guia do tutor e o guia do aluno). Não há configuração nova: o recurso vale onde o chat vale, e usa as permissões que o Moodle já aplica.

• Quem vê o quê. O cartão é mostrado pela visão de quem lê, com as regras de visibilidade e de restrição de acesso do próprio Moodle. O tutor só pode enviar o que o aluno pode saber que existe (item oculto é recusado) e um item restrito é enviado com o motivo. O servidor confere tudo de novo no envio: um cartão forjado ou de outro curso é recusado.
• Painel do tutor. Os blocos Atrasadas e Próximos prazos vêm do calendário do Moodle e só listam as atividades que o papel do tutor pode ver. Um papel de tutor personalizado precisa das permissões de ver as atividades (por exemplo mod/assign:view) para que elas apareçam.
• Formatos de curso. O cartão e o botão Abrir funcionam em qualquer formato. O destaque do item na página (Ver no curso) foi verificado em: Tópicos, Semanal, Atividade única (não há Ver no curso: só há uma página) e Tiles (format_tiles, versão 5.0.0.24 verificada; o bloco da seção abre pelo parâmetro expand). Em outros formatos (Grid, Onetopic, Flexible sections...) o plugin tenta as marcas padrão da página do curso; se o formato não as tem, o aluno vê "Procure por: nome do item" no botão do chat, e o cartão e Abrir continuam funcionando. O plugin não depende de nenhum formato de terceiros.
• Custo. O seletor do tutor e o bloco de prazos são calculados só quando o tutor os pede, nunca na verificação periódica. Em um curso com cerca de 300 atividades, o seletor leva alguns segundos para abrir pela primeira vez (medido: perto de 1,4 s). Detalhes técnicos na parte interna da documentação (desempenho).
• Privacidade. O cartão guarda só a referência do item (cardtype e cardid), nunca o nome; veja privacidade.

6. Rótulos de papel

Os alunos veem, ao lado de cada tutor (na lista e no cabeçalho da conversa), um rótulo com o nome do papel dele. O papel mostrado é o que concede a capability de tutor e vem primeiro na ordem de papéis do site; o nome respeita renomeações feitas no curso. A cor vem de uma paleta fixa de seis cores, igual em todos os cursos.

7. Tarefas agendadas

Em Administração do site → Servidor → Tarefas → Tarefas agendadas. O cron do Moodle precisa rodar com frequência (de preferência a cada minuto).

Sem o cron, os atendimentos inativos não são encerrados e o resumo só é atualizado pelo botão Atualizar agora da supervisão (que se recusa a rodar se os dados têm menos de 5 minutos). A aba Agora da supervisão não depende do resumo.

7-A. Licença

O TutorChat precisa de uma chave de licença, enviada pelo fornecedor. Sem chave, o plugin funciona em teste por 30 dias, contados a partir da instalação do plugin ou da atualização para esta versão.

Onde colar a chave: Administração do site → Plugins → Plugins locais → TutorChat → Licença. Cole a chave inteira (pode ter quebras de linha) e salve. A página mostra o cliente, o número da licença, o endereço do site, a validade e os dias de carência. A chave só vale para o endereço do site para o qual foi emitida. Antes de mudar o endereço do site (domínio ou caminho), peça uma chave nova; trocar http por https ou www. não exige chave nova.

Quando está bloqueada: o botão do chat some para os alunos, o link "Área do tutor" some do menu, a supervisão (menu Relatórios) mostra a mensagem de que o chat não está disponível e nenhuma mensagem nova é enviada. Nada é apagado: as conversas ficam guardadas e as tarefas agendadas continuam rodando. Tudo volta a funcionar assim que o administrador colar uma chave válida. A página de licença continua acessível mesmo bloqueada.

Pela linha de comando (na pasta do Moodle):

• php local/tutorchat/cli/license.php --status mostra o estado da licença.
• php local/tutorchat/cli/license.php --set=<chave> confere e salva a chave (termina com erro e o motivo se for inválida).

Relógio do servidor: o plugin guarda a maior data já vista para não deixar ninguém "voltar o relógio" e prolongar a licença. Se o relógio do servidor andou para a frente por engano e a licença passou a aparecer como vencida, corrija o relógio e rode php admin/cli/cfg.php --component=local_tutorchat --name=licensemaxseen --unset.

Importante: a conferência da chave é feita só no seu servidor. O único contato com o fornecedor é o envio opcional de dados de diagnóstico, descrito na seção 7-B.

7-B. Diagnóstico (telemetria)

Por padrão o plugin envia ao fornecedor, uma vez por dia, contagens de uso, tempos de resposta, versões técnicas e erros. O plugin não foi feito para enviar dado de pessoa (nem mensagens, nomes, e-mails ou números de usuário, curso ou conversa), mas o texto livre de erros de fora do Moodle não dá para limpar com certeza. Para desligar, desmarque Enviar dados de diagnóstico ao fornecedor na página Licença; para ver o pacote exato, clique em Ver o que será enviado. Detalhes, a lista do que vai e do que nunca vai, e o limite da limpeza das mensagens de erro: dados de diagnóstico.

8. Dados e privacidade

O plugin guarda atendimentos, mensagens, avaliações, a disponibilidade dos tutores e um resumo estatístico. Os atendimentos nunca são apagados automaticamente: eles só saem pelas ferramentas de privacidade do Moodle ou quando o curso é excluído. O texto das mensagens só é apagado por conta própria se você ativar Meses para guardar as mensagens (seção 9). Veja privacidade e a lista do que informar a alunos e tutores.

9. Sites grandes

O custo do chat no servidor depende de quantos usuários têm uma conversa aberta, e não do tamanho do histórico. Para sites com muitos alunos e tutores:

Configurações que importam

Caches de aplicação

O plugin guarda em cache de aplicação do Moodle a lista de tutores de cada curso (coursetutors) e a informação "este usuário é tutor em algum curso" (tutoranywhere), por 10 minutos, e limpa o que for afetado quando papéis, inscrições, usuários ou permissões mudam, e também quando você salva a configuração Papéis de tutor. Em um site com mais de um servidor web, associe esses dois caches a um armazenamento compartilhado, como o Redis (Administração do site → Plugins → Armazenamento em cache → Configuração: adicione uma instância do Redis e, em Definições de mapeamento, mapeie as definições local_tutorchat / coursetutors e local_tutorchat / tutoranywhere a ela). Com o armazenamento padrão em arquivos, cada servidor monta e limpa a sua própria cópia, e uma mudança de papel pode demorar até 10 minutos para valer nos outros servidores.

Sessões somente leitura

Ative $CFG->enable_read_only_sessions = true; no config.php. As duas consultas periódicas do chat (local_tutorchat_sync e local_tutorchat_get_widget_state) são declaradas como somente leitura, então liberam a sessão do usuário logo no início e não atrasam as outras requisições dele (por exemplo, a página que ele está abrindo). Antes de ativar, o Moodle exige que todas as definições de cache de modo sessão sejam mapeadas para um armazenamento diferente do de sessão (Administração do site → Plugins → Armazenamento em cache → Configuração); sem isso ele recusa a sessão e mostra um erro que cita as definições, por exemplo core/coursecat. No teste do desenvolvimento, com a opção ativa, as consultas periódicas de um aluno e de um tutor, feitas de 66 a 77 segundos depois da última requisição que gravou a sessão, não gravaram o último acesso do usuário (user.lastaccess e user_lastaccess).

Retenção das mensagens antigas

Com Meses para guardar as mensagens maior que 0, a tarefa agendada Remover mensagens antigas do chat com tutor (todo dia às 03:30) apaga, em definitivo, o texto das mensagens dos atendimentos encerrados há mais tempo que o prazo (meses de 30 dias, contados a partir da última atividade do atendimento). Ela trabalha em lotes de 500 atendimentos, no máximo 20 lotes por execução, e continua de onde parou na execução seguinte; a primeira ativação em um site com muitos atendimentos antigos pode precisar de várias execuções (dias) para zerar o atraso. O que permanece: o atendimento (curso, aluno, tutor, datas), a avaliação e o resumo de estatísticas. Quem abre um atendimento apagado vê o aviso "As mensagens deste atendimento foram removidas pelo prazo de retenção." Atendimentos em andamento nunca são tocados. Não há como recuperar as mensagens apagadas, a não ser por backup. Veja privacidade.

Medir no seu servidor

O plugin traz um roteiro que mede as operações periódicas e só lê o banco (se alguma operação gravar, ele para com erro). A partir da pasta do Moodle:

php local/tutorchat/cli/benchmark.php --runs=50

Opções: --tutor=ID, --student=ID, --course=ID (sem elas, usa o tutor com mais atendimentos e o aluno e o curso do atendimento mais recente dele) e --runs=N. Para cada operação (sync_student, sync_tutor, visible_tutors, tutor_anywhere, nav_unread, widget_state e, desde a entrega B2, course_items e context_pending, que medem o seletor de atividades e o bloco de prazos e dependem do tamanho do curso) ele mostra as leituras e as gravações no banco de uma chamada e o tempo em milissegundos: a primeira chamada (cold, que enche os caches) e a mediana e o percentil 95 das seguintes (warm). Compare principalmente as leituras. As medições do desenvolvimento estão em parte interna da documentação (desempenho).

10. Solução de problemas