b.santos/bot-pontos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

manual do usuario atualizado

Browse Source
This commit is contained in:
Bruno Santos
2026-11-06 15:15:51 -03:00
parent 14f1ea240f
commit 4d8c1e1838
1 changed files with 56 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/MANUAL_USUARIO.md
View File

@@ -38,7 +38,7 @@ Este manual tem duas partes:
5. **Ligue os lembretes:** envie `/ativarponto`.
6. **Confira:** envie `/status`. Deve aparecer *Cadastro: ativo* e *Lembretes: ligados*.
Pronto. A partir do próximo dia útil você passa a receber os lembretes.
Pronto. Se você ligar os lembretes num dia útil, antes do fim do horário de acompanhamento (19:00, por padrão), o bot já começa a acompanhar seus pontos no mesmo dia. Senão, começa no próximo dia útil.
## Os lembretes
@@ -100,6 +100,7 @@ Você **não** recebe mensagem quando isso acontece (para não receber aviso tod
| Comando | Para que serve |
| --- | --- |
| `/start` ou `/iniciar` | Mensagem inicial: orienta a se cadastrar ou mostra a lista de comandos |
| `/cadastrar` | Pedir acesso ao bot (só na primeira vez) |
| `/status` | Ver a situação do seu cadastro, da credencial, dos lembretes e do dia |
| `/entrada2` | Perguntar agora a hora prevista de voltar do almoço (precisa de pelo menos 2 pontos no dia) |
@@ -108,6 +109,29 @@ Você **não** recebe mensagem quando isso acontece (para não receber aviso tod
| `/desativarponto` | Pausar os lembretes. Os comandos `/entrada2` e `/saida2` continuam funcionando |
| `/ajuda` | Ver a lista de comandos |
Enquanto o cadastro aguarda aprovação, só `/status` e `/ajuda` funcionam; os demais respondem que o cadastro ainda não foi aprovado.
### Respostas de `/entrada2` e `/saida2`
Os dois comandos consultam a PontoMais na hora, a qualquer horário do dia:
```text
Retorno previsto do almoço: 13:00 (almoço de 1h00).
Saída prevista: 17:00. Para completar 8h00.
```
Outras respostas possíveis:
| Resposta | O que significa |
| --- | --- |
| *Encontrei 1 ponto(s) hoje. O retorno do almoço é calculado a partir do segundo ponto.* | Você ainda não bateu a saída para o almoço |
| *Encontrei 2 ponto(s) hoje. A saída é calculada a partir do terceiro ponto.* | Você ainda não voltou do almoço |
| *Os pontos de hoje estão repetidos ou fora de ordem.* | Confira e ajuste o ponto na PontoMais |
| *Há mais de quatro pontos hoje (hora extra)...* | O bot não acompanha dias com hora extra |
| *Não foi possível calcular a saída...* | O tempo antes do almoço já completa a jornada |
| *Não consegui consultar a PontoMais agora.* | A PontoMais não respondeu; tente de novo em alguns minutos |
| *...As consultas automáticas de hoje foram retomadas.* | O dia estava "sem pontos" e o bot voltou a acompanhar |
### Entendendo o `/status`
```text
@@ -128,9 +152,9 @@ Hoje: acompanhando (2 ponto(s) até a última consulta)
## Situações comuns
### "Pausei os lembretes por falha na PontoMais"
### "Não consegui consultar a PontoMais 3 vezes seguidas, então pausei seus lembretes"
O bot tentou consultar seus pontos **3 vezes seguidas** (cerca de 30 minutos) e não conseguiu, então pausou seus lembretes e avisou você e o administrador. O motivo mais comum é **senha da PontoMais alterada**.
O bot tentou consultar seus pontos **3 vezes seguidas** (cerca de 30 minutos) e não conseguiu, então pausou seus lembretes e avisou você e o administrador. O `/status` passa a mostrar *Lembretes: pausados (3 falhas seguidas na PontoMais...)*. O motivo mais comum é **senha da PontoMais alterada**.
1. Se você trocou a senha da PontoMais, informe a nova ao administrador (de forma segura, fora do bot).
2. Depois que ele atualizar, envie `/ativarponto`.
@@ -258,20 +282,32 @@ Quando alguém envia `/cadastrar`, os admins do bot recebem um aviso no Telegram
> Sem credencial validada **não é possível ativar**, nem pelo painel nem pelo Telegram.
## Usuários
A lista mostra ID, nome, status, credencial, lembretes e janela de cada usuário. Filtros: busca por **nome ou chat ID**, **status** (aguardando aprovação, ativos, desativados) e **janela** (personalizada ou global). Clique no nome para abrir a tela do usuário.
## Tela do usuário
O topo mostra o nome, o status, o ID, o chat do Telegram e a data do cadastro. No rodapé, os links **Lembretes deste usuário** e **Auditoria deste usuário** abrem as listas já filtradas.
### Cadastro e lembretes
O quadro mostra:
- **Lembretes:** *ligados* ou o motivo da pausa (*pausado pelo usuário*, *pausado após falhas na PontoMais*, *pausado pelo painel* ou *usuário desativado*);
- **Admin do bot:** sim ou não;
- **Hoje:** a situação do dia (*aguardando primeira consulta*, *acompanhando*, *sem pontos (reverificando)*, *sem pontos (encerrado)* ou *jornada encerrada*), quantos pontos foram vistos na última consulta e quando será a próxima.
| Botão | O que faz |
| --- | --- |
| **Ativar** | Aprova o cadastro (exige credencial validada) |
| **Desativar** | Bloqueia o uso do bot e cancela os lembretes agendados. A pessoa recebe no Telegram o aviso de que o acesso foi desativado. Não apaga o histórico |
| **Ligar lembretes** | Liga os lembretes, zera o contador de falhas e retoma o dia, se ele estava "sem pontos" |
| **Pausar lembretes** | Desliga os lembretes e cancela os agendados. O `/status` do usuário mostra "pausados (por um administrador)" |
| **Pausar lembretes** | Desliga os lembretes e cancela os agendados. O painel mostra "pausado pelo painel" e o `/status` do usuário, "pausados (por um administrador)" |
| **Tornar admin do bot** / **Remover admin do bot** | Define quem recebe os avisos operacionais no Telegram |
| **Retomar consultas de hoje** | Aparece quando o dia está "sem pontos". Volta a consultar até o fim da janela |
| **Retomar consultas de hoje** | Aparece quando o dia está "sem pontos" (reverificando ou encerrado). Volta a consultar até o fim da janela |
A linha **Hoje** mostra a situação do dia, quantos pontos foram vistos na última consulta e quando será a próxima.
**Ligar** e **Pausar lembretes** só aparecem para usuários ativos.
### Credencial PontoMais
@@ -304,12 +340,12 @@ Mudanças valem a partir da próxima consulta. Lembretes que já foram agendados
### Pontos de hoje
- **Consultar PontoMais agora:** mostra os pontos do dia e os horários previstos. Não é automático, para não gastar consultas à toa.
- **Consultar PontoMais agora:** mostra os pontos do dia, o retorno e a saída previstos e a situação do dia. Avisa também se os pontos estão repetidos ou fora de ordem, ou se há hora extra. Não é automático, para não gastar consultas à toa.
- **Testar credencial:** igual, mas também marca a credencial como validada se der certo.
## Lembretes
Lista os lembretes com filtros por dia, situação, tipo e usuário.
Lista os lembretes com dia, usuário, tipo (*retorno do almoço* ou *saída*), horário do aviso, horário previsto, situação e detalhe (erro ou hora do envio). Os filtros da tela são **dia**, **situação** e **tipo**; **Limpar** remove todos. Para ver só os lembretes de uma pessoa, use o link **Lembretes deste usuário** na tela dela.
| Situação | Significado |
| --- | --- |
@@ -357,13 +393,13 @@ Vale para todos os usuários **sem** janela personalizada. O padrão é 11:30 à
1. Ajuste os horários.
2. Clique em **Pré-visualizar efeito** para ver:
- quantas consultas por usuário a janela gera (máximo, dia típico e dia de folga);
- quantos usuários teriam tido lembretes atrasados nos últimos 30 dias;
- quantos usuários e quantos dias, nos últimos 30 dias, teriam tido o aviso de retorno antes do início da nova janela (lembretes que sairiam atrasados);
- quantos usuários têm janela personalizada e não serão afetados.
3. Clique em **Salvar**.
3. Clique em **Salvar** e confirme. A mudança vale a partir da próxima consulta.
### Parâmetros do servidor
Só leitura: intervalo das consultas, do envio, tolerância de atraso e limite de falhas. Alterá-los exige mudar a configuração do servidor.
Só leitura: intervalo da reconciliação, das consultas lentas e do despacho, tolerância de atraso e número de falhas até a pausa. Eles vêm das variáveis de ambiente do servidor; alterá-los exige mudar o `.env`/Compose e reiniciar os containers.
## Contas do painel (owner)
@@ -388,6 +424,15 @@ Disponíveis para quem é **admin do bot** e está ativo:
Exemplo: `/ativarusuario 12`.
O `/usuarios` responde uma linha por usuário, assim:
```text
12 — Maria Silva — ativo, credencial ok, lembretes on
13 — João Souza — aguardando aprovação, sem credencial, lembretes off
```
Para ativar, a credencial precisa estar como *credencial ok*. Se não estiver, o bot responde que ela deve ser configurada pelo painel antes. Ao ser ativada, a pessoa recebe a mensagem de aprovação; ao ser desativada, recebe o aviso de que o acesso foi desativado.
## Avisos que o admin do bot recebe
| Aviso | Quando | O que fazer |