bot-pontos/docs/MANUAL_USUARIO.md

# Manual do usuário — Bot de Pontos

O Bot de Pontos avisa pelo Telegram a hora de **voltar do almoço** e a hora de **encerrar a jornada**, com base nos pontos que você registra na PontoMais.

Este manual tem duas partes:

- **[Parte 1 — Usuário](#parte-1--usuário):** para quem recebe os lembretes pelo Telegram.
- **[Parte 2 — Administrador](#parte-2--administrador):** para quem aprova usuários e cuida do painel.

---

# Parte 1 — Usuário

## O que o bot faz

- Consulta os seus pontos do dia na PontoMais.
- Calcula a hora prevista de **voltar do almoço** e de **sair**.
- Envia um lembrete pelo Telegram **alguns minutos antes** de cada horário (5 minutos, por padrão).
- Responde na hora quando você pergunta (`/entrada2`, `/saida2`).

## O que o bot **não** faz

- **Não registra ponto.** Você continua batendo o ponto na PontoMais normalmente.
- Não substitui a conferência do seu espelho de ponto.
- Não controla hora extra (dias com mais de quatro pontos).
- Não funciona em grupos: só em conversa privada com o bot.

> O bot é uma ajuda para lembrar. A fonte oficial continua sendo a PontoMais.

## Primeiro acesso

1. **Abra o bot no Telegram.** Peça ao administrador o nome ou o link do bot e toque em **Iniciar**.
2. **Peça acesso:** envie `/cadastrar`. O administrador recebe um aviso.
3. **Credencial da PontoMais:** o administrador vai configurar o seu e-mail e senha de login da PontoMais no painel.
   - Combine com ele uma forma segura de passar a senha.
   - **Nunca envie sua senha para o bot no chat.** O bot nunca pede senha.
4. **Aguarde a aprovação.** Você recebe a mensagem *"Seu cadastro foi aprovado"*.
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.

## Os lembretes

### Como os horários são calculados

A jornada padrão tem **quatro pontos**:

| Ponto | Significado |
| --- | --- |
| 1º | Entrada |
| 2º | Saída para o almoço |
| 3º | Volta do almoço |
| 4º | Saída do dia |

- **Volta do almoço** = hora em que você saiu para o almoço + tempo de almoço (60 min, por padrão).
- **Saída** = hora em que você voltou do almoço + o que falta da jornada (8h00, por padrão).

**Exemplo:** entrada às 08:00, saída para o almoço às 12:00 e volta às 13:00.

- Lembrete de volta do almoço: **12:55** (volta prevista às 13:00).
- Você trabalhou 4 horas antes do almoço; faltam 4 horas.
- Lembrete de saída: **16:55** (saída prevista às 17:00).

Tempo de almoço, jornada e antecedência podem ser diferentes para você. Quem ajusta é o administrador.

### Como as mensagens chegam

```text
⏰ Lembrete: seu retorno do almoço está previsto para 13:00.
⏰ Lembrete: sua saída está prevista para 17:00 (jornada de 8h00).
```

Se o lembrete chegar depois do horário previsto, a frase muda para *"estava previsto para 13:00"*. Assim você sabe a hora certa mesmo com atraso.

### Quando os lembretes **não** chegam (e está tudo certo)

- **Fim de semana e feriado:** não há consultas nem lembretes.
- **Você já bateu o ponto seguinte:** se voltou do almoço antes do lembrete, ele é cancelado. O mesmo vale para a saída.
- **Lembrete muito atrasado:** se o bot só percebe o seu ponto com mais de 10 minutos de atraso em relação ao horário do aviso, o lembrete não é enviado, porque já não ajudaria. Isso pode acontecer se você sair para o almoço muito cedo, antes do horário em que o bot começa a consultar.
- **Hora extra:** com mais de quatro pontos no dia, o bot para de acompanhar.

### Horário em que o bot acompanha seus pontos

O bot consulta a PontoMais apenas numa **janela do dia**: por padrão, **das 11:30 às 19:00**.

- Antes das 11:30 o bot ainda não olha seus pontos. Isso é normal: o primeiro lembrete do dia (volta do almoço) quase sempre é depois disso.
- Se o seu horário for bem diferente (por exemplo, almoço às 10:30), peça ao administrador uma **janela personalizada**.

### Dia sem pontos

Se às **11:30** e às **11:45** o bot não encontrar nenhum ponto seu, ele entende que você pode não estar trabalhando hoje (férias, folga, atestado). Ele passa a conferir **de hora em hora até as 15:00** e, se continuar sem pontos, encerra as consultas do dia.

Você **não** recebe mensagem quando isso acontece (para não receber aviso todo dia nas férias). Se começou a trabalhar mais tarde, faça uma destas coisas e as consultas voltam:

- envie `/ativarponto`; ou
- envie `/entrada2` ou `/saida2` depois de bater o ponto.

## Comandos

| Comando | Para que serve |
| --- | --- |
| `/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) |
| `/saida2` | Perguntar agora a hora prevista de saída (precisa de pelo menos 3 pontos no dia) |
| `/ativarponto` | Ligar os lembretes automáticos (ou religar depois de uma pausa) |
| `/desativarponto` | Pausar os lembretes. Os comandos `/entrada2` e `/saida2` continuam funcionando |
| `/ajuda` | Ver a lista de comandos |

### Entendendo o `/status`

```text
Cadastro: ativo
Credencial PontoMais: validada
Lembretes: ligados
Janela de consulta: 11:30 às 19:00 (global)
Hoje: acompanhando (2 ponto(s) até a última consulta)
```

| Linha | O que significa |
| --- | --- |
| **Cadastro** | *aguardando aprovação*, *ativo* ou *desativado* |
| **Credencial PontoMais** | se o administrador já configurou e validou seu login. Se houver falhas recentes, aparece quantas |
| **Lembretes** | *ligados* ou *pausados*, com o motivo da pausa |
| **Janela de consulta** | horário em que o bot acompanha seus pontos; *personalizada* se for só sua |
| **Hoje** | o que o bot sabe do seu dia: aguardando, acompanhando, sem pontos, jornada encerrada ou dia não útil |

## Situações comuns

### "Pausei os lembretes por falha na PontoMais"

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**.

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`.

### "A PontoMais está fora do ar"

Quando a PontoMais cai para todo mundo, **ninguém é pausado**. O administrador é avisado, e os lembretes voltam ao normal quando ela responder de novo. Enquanto isso, pontos novos podem não ser percebidos a tempo.

### Esqueci de bater a entrada

O bot calcula pela **ordem** dos pontos. Se a entrada estiver faltando, ele vai confundir os horários (vai achar que a saída para o almoço é a entrada). Faça o ajuste do ponto na PontoMais. Enquanto isso, desconsidere os lembretes do dia.

### Vou sair antes / fazer hora extra

- **Saída antecipada:** se você bater o ponto de saída antes do lembrete, ele é cancelado. Se bater pouco antes do aviso, o lembrete ainda pode chegar.
- **Hora extra:** a partir do quinto ponto o bot para de acompanhar o dia.

### Férias ou afastamento longo

Envie `/desativarponto` antes de sair e `/ativarponto` na volta. Mesmo sem isso o bot para de consultar sozinho nos dias sem pontos, mas pausar evita consultas desnecessárias.

### Mudei de horário

Peça ao administrador para ajustar o tempo de almoço, a jornada, a antecedência dos avisos ou a janela de consulta.

## Privacidade e segurança

- Sua senha da PontoMais fica **cifrada** no servidor. Ninguém, nem o administrador, consegue vê-la depois de salva.
- O bot só **lê** seus pontos; ele não altera nada na PontoMais.
- O bot só responde em conversa privada.
- **Nunca** envie senhas no chat do bot. Ele nunca vai pedir.

## Perguntas frequentes

**O lembrete chegou depois da hora prevista. Por quê?**
O bot confere seus pontos de tempos em tempos (a cada 15 minutos na maior parte do dia) e envia os lembretes a cada 2 minutos. Pequenos atrasos são normais. Atrasos maiores acontecem quando a PontoMais demora a mostrar o ponto. Por isso a mensagem sempre traz o horário previsto.

**Não recebi nenhum lembrete hoje.**
Envie `/status` e confira, nesta ordem:
1. *Cadastro: ativo* e *Lembretes: ligados*.
2. Hoje é dia útil.
3. A linha *Hoje* não mostra "sem pontos".
4. Seus pontos aparecem na PontoMais na ordem certa.

Se tudo estiver certo, envie `/entrada2` para testar. Se der erro, procure o administrador.

**Posso usar o bot em um grupo?**
Não. Ele só responde em conversa privada.

---

# Parte 2 — Administrador

## Papéis

O painel tem três tipos de conta. Usuários comuns **não** acessam o painel; eles usam só o Telegram.

| Ação | Leitura | Admin | Owner |
| --- | :-: | :-: | :-: |
| Ver início, usuários, lembretes, auditoria, feriados e configurações | ✓ | ✓ | ✓ |
| Ativar/desativar usuários, ligar/pausar lembretes | | ✓ | ✓ |
| Alterar jornada, janela personalizada e credencial; testar a PontoMais | | ✓ | ✓ |
| Cancelar e reenviar lembretes | | ✓ | ✓ |
| Cadastrar feriados e alterar a janela global | | ✓ | ✓ |
| Definir o admin do bot | | ✓ | ✓ |
| Criar, desativar e excluir contas, mudar papéis e usuário ligado, redefinir senhas | | | ✓ |

### Conta de leitura ligada a um usuário

Uma conta de **leitura** pode ser ligada a um usuário do Telegram (feito pelo owner em **Contas**). Ela serve para a pessoa acompanhar e ajustar só o que é dela, sem ver nada dos outros.

| Tela | O que a conta ligada vê e faz |
| --- | --- |
| **Início** | Os avisos do sistema (PontoMais fora do ar, feriados indisponíveis) e os próprios lembretes de hoje, só para consulta (sem link). Não há contadores gerais. |
| **Usuários** | Abre direto na própria ficha. Pode salvar e testar a credencial PontoMais, alterar a jornada e a janela de consulta, e ligar ou pausar os próprios lembretes. Não ativa nem desativa o cadastro, não define admin do bot e não retoma consultas. |
| **Lembretes** | Só os próprios, somente leitura (não cancela nem reenvia). |
| **Feriados** | Somente visualização. |
| **Auditoria, Configurações e Contas** | Não aparecem no menu e a API recusa o acesso. |

Uma conta de leitura **sem** usuário ligado continua como antes: vê todas as telas, menos Contas, e não altera nada. Um usuário do Telegram só pode estar ligado a **uma** conta do painel.

Existe ainda o **admin do bot**: um usuário do Telegram que recebe os avisos operacionais e pode usar os comandos administrativos no Telegram. Ser admin do bot é independente de ter conta no painel.

## Acessar o painel

1. Abra o endereço do painel (ex.: `https://botpontos.lan`) num computador da rede.
2. Entre com seu usuário e senha.

Regras de acesso:

- A sessão dura no máximo **8 horas** e expira após **30 minutos** sem uso.
- **5 senhas erradas seguidas** bloqueiam a conta por **15 minutos**.
- Use **Sair** ao terminar, principalmente em computadores compartilhados.
- Esqueceu a senha? Peça a um owner para redefinir (em **Contas**).

## Início (dashboard)

Mostra o resumo do sistema:

- usuários **aguardando aprovação** e **ativos**;
- quantos estão com lembretes ligados;
- quantos foram **pausados por falha na PontoMais**;
- falhas de envio e lembretes expirados nos últimos 7 dias;
- quantos usuários têm **janela personalizada**;
- lembretes de hoje por situação.

Faixas de alerta aparecem no topo quando:

- **a PontoMais está fora do ar:** ninguém é pausado; aguarde;
- **os feriados do ano não foram obtidos:** segunda a sexta estão valendo como dias úteis. Cadastre os feriados manualmente se precisar.

Os números são clicáveis e levam à lista filtrada.

## Aprovar um novo usuário

Quando alguém envia `/cadastrar`, os admins do bot recebem um aviso no Telegram.

1. Em **Usuários**, filtre por *Aguardando aprovação* e abra o cadastro.
2. Em **Credencial PontoMais**, informe o e-mail e a senha de login da pessoa e clique em **Validar e salvar**.
   - A credencial é testada na PontoMais **na hora**. Se for recusada, nada é gravado.
   - Depois de salva, a senha nunca mais aparece.
3. Ajuste a **jornada**, se for diferente do padrão (ver adiante).
4. Clique em **Ativar**. A pessoa recebe a mensagem de aprovação.
5. Peça para ela enviar `/ativarponto`.

> Sem credencial validada **não é possível ativar**, nem pelo painel nem pelo Telegram.

## Tela do usuário

### Cadastro e lembretes

| Botão | O que faz |
| --- | --- |
| **Ativar** | Aprova o cadastro (exige credencial validada) |
| **Desativar** | Bloqueia o uso do bot e cancela os lembretes agendados. 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 "pausado pelo painel" |
| **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 |

A linha **Hoje** mostra a situação do dia, quantos pontos foram vistos na última consulta e quando será a próxima.

### Credencial PontoMais

Mostra o e-mail, se a credencial está validada, as **falhas seguidas** e o **último erro**. Para trocar a senha (por exemplo, depois que o usuário mudou a senha na PontoMais), preencha de novo e clique em **Validar e salvar**.

### Jornada e janela de consulta

| Campo | Padrão | Regras |
| --- | --- | --- |
| Almoço | 60 min | entre 15 e 180 |
| Jornada | 480 min (8h00) | entre 60 e 720 |
| Antecedência do retorno | 5 min | entre 0 e 60 |
| Antecedência da saída | 5 min | entre 0 e 60 |
| Fuso horário | `America/Sao_Paulo` | nome no formato IANA |

**Regra importante:** *almoço − antecedência do retorno* precisa ser **pelo menos 15 minutos**. Assim o bot tem tempo de perceber a saída para o almoço antes da hora do aviso. Exemplo: almoço de 20 min com antecedência de 5 min passa; almoço de 15 min com antecedência de 5 min é recusado.

**Janela personalizada:** desmarque **Usar padrão global** para definir uma janela só para este usuário. Os quatro horários aparecem preenchidos com os valores globais, como ponto de partida:

| Horário | Significado |
| --- | --- |
| Início da janela | primeira consulta do dia |
| Confirmação sem pontos | segunda verificação sem pontos; depois dela, o bot passa a conferir de hora em hora |
| Fim das reverificações | depois desse horário, um dia sem pontos é encerrado |
| Fim da janela | última consulta do dia |

Os horários precisam ser múltiplos de 15 minutos (:00, :15, :30, :45), estar nessa ordem e somar pelo menos 4 horas de janela. Para voltar à janela global, marque **Usar padrão global** e salve.

Mudanças valem a partir da próxima consulta. Lembretes que já foram agendados hoje não mudam.

### 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.
- **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.

| Situação | Significado |
| --- | --- |
| **agendado** | aguardando a hora do aviso |
| **enviando** | envio em andamento |
| **enviado** | entregue ao Telegram |
| **falhou** | o Telegram recusou ou não respondeu |
| **cancelado** | não será enviado (ponto seguinte já batido, pausa ou cancelamento manual) |
| **expirado** | o atraso passou de 10 min e o lembrete não foi enviado |

Ações:

- **Cancelar:** só para lembretes **agendados**.
- **Reenviar:** só para lembretes que **falharam** e são **do dia de hoje**.
  - O usuário precisa estar ativo e com os lembretes ligados.
  - Se o ponto seguinte já foi batido, o reenvio é bloqueado.
  - Atenção: se a falha foi um travamento no meio do envio, a pessoa **pode já ter recebido** a mensagem original. O painel pergunta antes de reenviar.

Lembretes **expirados** não podem ser reenviados.

## Auditoria

Registra quem fez o quê e quando: cadastros, ativações, mudanças de jornada e de credencial, envios, falhas, pausas, logins, alterações de configuração etc.

Filtre por período, origem (Telegram, painel, worker, terminal), tipo de evento e resultado. A partir da tela de um usuário, o link **Auditoria deste usuário** já abre filtrado. Use **Mais antigos →** para paginar.

Senhas e tokens nunca aparecem na auditoria.

## Feriados

O bot não consulta nem envia lembretes em fins de semana e feriados. A tela mostra os feriados de um ano por vez; use os links do ano anterior e do seguinte (ex.: **← 2025 · 2027 →**) para navegar. A coluna **Origem** indica `manual` ou a API de onde o feriado veio.

- **Sincronizar (ano) com a feriadosapi.com:** baixa os feriados do ano para a cidade configurada (nacionais e municipais; hoje Belo Horizonte). O sistema também faz isso sozinho no primeiro uso de cada ano. Só entram datas que ainda não estão na lista, então feriados manuais nunca são alterados.
- **Cadastrar feriado manual:** para pontos facultativos, recessos ou feriados que a API não trouxe (por exemplo, o Carnaval).
- **Remover:** só feriados manuais.

Se a API de feriados estiver fora do ar e o ano ainda não tiver sido sincronizado, segunda a sexta contam como dias úteis. Os admins do bot recebem um aviso por dia enquanto isso durar.

## Configurações

### Janela de consulta global

Vale para todos os usuários **sem** janela personalizada. O padrão é 11:30 às 19:00, com confirmação às 11:45 e reverificações até as 15:00.

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 têm janela personalizada e não serão afetados.
3. Clique em **Salvar**.

### 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.

## Contas do painel (owner)

- **Nova conta:** usuário (3 a 50 caracteres: letras, números, ponto, hífen ou sublinhado), senha (mínimo 12 caracteres) e papel.
- **Papel:** troque no seletor da linha.
- **Usuário do Telegram:** ao criar a conta, ou depois no seletor da linha, escolha o usuário ao qual ela fica ligada (ou "Sem usuário ligado" para remover o vínculo). Com papel de leitura, isso restringe a conta aos dados desse usuário (ver [Papéis](#papéis)). A troca vale na próxima requisição, sem precisar sair e entrar de novo.
- **Redefinir senha:** define uma nova senha e encerra as sessões abertas daquela conta.
- **Desativar / Reativar:** desativar encerra as sessões; ninguém pode desativar a própria conta.
- **Excluir:** apaga a conta de vez, com as sessões abertas. Não dá para desfazer; na auditoria, as ações antigas continuam mostrando o nome da conta. Ninguém pode excluir a própria conta. Para só bloquear o acesso, prefira **Desativar**.

Sempre precisa existir **pelo menos um owner ativo**. O sistema recusa rebaixar, desativar ou excluir o último.

## Comandos de admin no Telegram

Disponíveis para quem é **admin do bot** e está ativo:

| Comando | O que faz |
| --- | --- |
| `/usuarios` | Lista os usuários com ID, situação, credencial e lembretes |
| `/ativarusuario <id>` | Ativa (exige credencial validada, configurada no painel) |
| `/desativarusuario <id>` | Desativa e cancela os lembretes agendados |

Exemplo: `/ativarusuario 12`.

## Avisos que o admin do bot recebe

| Aviso | Quando | O que fazer |
| --- | --- | --- |
| Novo pedido de cadastro | alguém enviou `/cadastrar` | configurar a credencial e ativar |
| Usuário pausado após falhas | 3 falhas seguidas na PontoMais para aquela pessoa | testar a credencial no painel; se a senha mudou, atualizar; pedir `/ativarponto` |
| PontoMais fora do ar / voltou | todas as consultas de um ciclo falharam / alguma voltou a funcionar | aguardar; ninguém é pausado |
| Feriados não obtidos | API de feriados indisponível (no máximo 1 aviso por dia) | sincronizar depois ou cadastrar manualmente |
| Jornadas fora da regra | ao reiniciar o servidor, se alguma jornada ficou com almoço − antecedência menor que o intervalo das consultas | ajustar a jornada na tela do usuário |

Se não houver nenhum admin do bot ativo, esses avisos ficam só na auditoria. **Mantenha pelo menos um admin do bot.**

## Rotina sugerida

**Diariamente** (1 minuto, pela tela **Início**):

- alguém aguardando aprovação?
- alguém pausado por falha na PontoMais?
- falhas de envio hoje?

**Mensalmente:**

- revisar usuários desativados e contas do painel que não são mais usadas;
- conferir se os feriados do ano estão cadastrados;
- confirmar com o operador que os backups estão sendo copiados para fora do servidor.

## Problemas comuns (administrador)

| Situação | Causa provável | O que fazer |
| --- | --- | --- |
| "Configure e valide a credencial da PontoMais antes" ao ativar | credencial ausente ou nunca validada | salvar a credencial na tela do usuário |
| "A PontoMais recusou o e-mail ou a senha" | dados errados ou senha alterada | conferir com o usuário; a credencial anterior foi mantida |
| "Não foi possível validar na PontoMais agora" | PontoMais lenta ou fora do ar | tentar mais tarde |
| Usuário diz que não recebe lembretes | lembretes pausados, dia sem pontos, fora da janela ou feriado | tela do usuário (linha **Hoje**), **Lembretes** filtrado pela pessoa e **Auditoria** |
| Muitos lembretes **expirados** de um usuário | sai para o almoço antes do início da janela | dar a ele uma janela personalizada que comece mais cedo |
| Lembrete **falhou** | Telegram recusou (ex.: o usuário bloqueou o bot) ou instabilidade | pedir para o usuário desbloquear/abrir o bot; reenviar se for do dia |
| "Origem da requisição não permitida" ou "Token CSRF inválido" | painel acessado por endereço diferente do configurado, ou cookies antigos | usar sempre o endereço oficial; apagar os cookies do site e entrar de novo |
| Conta de leitura vê "Seu papel não permite esta ação" | tentou abrir tela ou ação fora do que a conta ligada permite | esperado; para ver tudo, usar uma conta sem vínculo ou admin |
| Conta bloqueada | 5 senhas erradas | aguardar 15 minutos ou pedir a um owner para redefinir a senha |