Projeto bot pontos

2026-10-23 22:31:02 -03:00
parent 29614855ff
commit b35e1a7d69
116 changed files with 14523 additions and 0 deletions
--- a/docs/ARQUITETURA.md
+++ b/docs/ARQUITETURA.md
--- a/docs/DEPLOY.md
+++ b/docs/DEPLOY.md
@@ -0,0 +1,564 @@
+# Guia de deploy — Bot de Pontos v2
+
+Passo a passo para colocar o Bot de Pontos no ar no servidor de produção:
+
+- **Servidor:** máquina física com **Debian 12**, fora do Proxmox, rodando Docker.
+- **Acesso ao painel:** pelo **Nginx Proxy Manager (NPM)** que já existe em outra máquina da rede, com **certificado interno**.
+- **Endereço do painel:** `https://botpontos.lan` (troque pelo nome que você usar).
+
+> O código **ainda não foi compilado nem testado**. A etapa 6 faz essa validação no próprio servidor antes de subir tudo. Se algo falhar, guarde a saída do comando para correção.
+
+## Visão geral
+
+```text
+Navegador ──HTTPS──► NPM (outra máquina) ──HTTP :3000──► Servidor Debian (Docker)
+                                                          ├── web       (Next.js, porta 3000)
+                                                          ├── api       (Go, só rede interna)
+                                                          ├── worker    (Go: bot + lembretes)
+                                                          ├── postgres  (só rede interna)
+                                                          └── backup    (pg_dump diário)
+```
+
+| Etapa | O quê | Onde |
+| --- | --- | --- |
+| 1 | Reunir informações e credenciais | — |
+| 2 | Preparar o Debian (IP fixo, NTP, atualizações) | servidor |
+| 3 | Instalar o Docker | servidor |
+| 4 | Copiar o projeto | Windows → servidor |
+| 5 | Criar `.env` e segredos | servidor |
+| 6 | Validar o código (testes) | servidor |
+| 7 | Subir os containers | servidor |
+| 8 | Firewall da porta 3000 | servidor |
+| 9 | DNS, certificado e Proxy Host | rede / NPM |
+| 10 | Primeiro acesso e primeiro admin | navegador / Telegram |
+| 11 | Backup fora da máquina | servidor |
+| 12 | Conferência final | — |
+
+Os comandos no servidor são executados como `root` (ou com `sudo`).
+
+---
+
+## 1. Reunir informações e credenciais
+
+Tenha em mãos antes de começar:
+
+| Item | Exemplo | Como obter |
+| --- | --- | --- |
+| IP fixo do servidor | `192.168.18.50` | reserva DHCP no roteador ou IP estático (etapa 2) |
+| IP do NPM | `192.168.18.10` | máquina onde o NPM roda |
+| Nome do painel | `botpontos.lan` | escolha um nome interno |
+| Token do bot | `123456:ABC...` | no Telegram, fale com **@BotFather** → `/newbot` |
+| Chave da feriadosapi.com | — | conta em feriadosapi.com (opcional: sem ela vale segunda a sexta) |
+| Certificado interno | `.crt` + `.key` | emitido pela CA interna da rede para `botpontos.lan` (com o nome no **SAN**) |
+| Credenciais PontoMais | e-mail e senha de cada usuário | cada usuário |
+
+No @BotFather, depois de criar o bot, é recomendado:
+
+- `/setjoingroups` → **Disable** (o bot só atende conversas privadas);
+- `/setcommands` com a lista abaixo, para aparecer o menu de comandos:
+
+```text
+status - situação do cadastro e dos lembretes
+entrada2 - retorno previsto do almoço
+saida2 - saída prevista
+ativarponto - ligar os lembretes
+desativarponto - pausar os lembretes
+cadastrar - solicitar acesso
+ajuda - lista de comandos
+```
+
+---
+
+## 2. Preparar o Debian
+
+### 2.1 Atualizar o sistema
+
+```bash
+apt update && apt full-upgrade -y
+```
+
+### 2.2 IP fixo
+
+O jeito mais simples é uma **reserva DHCP** no roteador para o MAC do servidor. Se preferir IP estático, edite `/etc/network/interfaces` (ajuste interface, IP e gateway):
+
+```text
+auto enp1s0
+iface enp1s0 inet static
+    address 192.168.18.50/24
+    gateway 192.168.18.1
+    dns-nameservers 192.168.18.1
+```
+
+Confira:
+
+```bash
+ip -4 addr show
+```
+
+### 2.3 Relógio (NTP) — obrigatório
+
+Os lembretes dependem da hora certa.
+
+```bash
+apt install -y systemd-timesyncd
+```
+
+```bash
+timedatectl set-ntp true
+```
+
+```bash
+timedatectl
+```
+
+A saída precisa mostrar `System clock synchronized: yes`. O fuso do sistema não importa (a aplicação grava em UTC e calcula no fuso de cada usuário), mas `America/Sao_Paulo` facilita a leitura dos logs:
+
+```bash
+timedatectl set-timezone America/Sao_Paulo
+```
+
+### 2.4 Ferramentas
+
+```bash
+apt install -y ca-certificates curl openssl iptables
+```
+
+---
+
+## 3. Instalar o Docker
+
+Use o repositório oficial da Docker (o pacote `docker.io` do Debian costuma estar defasado).
+
+```bash
+install -m 0755 -d /etc/apt/keyrings
+```
+
+```bash
+curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
+```
+
+```bash
+chmod a+r /etc/apt/keyrings/docker.asc
+```
+
+```bash
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" > /etc/apt/sources.list.d/docker.list
+```
+
+```bash
+apt update && apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+```
+
+Ligue o Docker na inicialização e confira:
+
+```bash
+systemctl enable --now docker
+```
+
+```bash
+docker compose version
+```
+
+---
+
+## 4. Copiar o projeto
+
+O projeto vai para `/opt/botpontos`.
+
+No servidor:
+
+```bash
+mkdir -p /opt/botpontos
+```
+
+No **Windows**, no PowerShell, dentro de `C:\Users\BrunoSantos\Documents\Codex\projeto prl3`, envie a pasta (troque usuário e IP):
+
+```powershell
+scp -r .\bot-pontos-v2 usuario@192.168.18.50:/tmp/
+```
+
+> A pasta `secrets/` deve ter só o `README.md` neste momento: os segredos são criados direto no servidor (etapa 5). Não é preciso enviar `node_modules` ou `.next`, se existirem.
+
+De volta ao servidor, mova para o lugar final:
+
+```bash
+cp -r /tmp/bot-pontos-v2/. /opt/botpontos/ && rm -rf /tmp/bot-pontos-v2
+```
+
+```bash
+cd /opt/botpontos && ls
+```
+
+Deve aparecer `backend`, `web`, `docs`, `docker-compose.yml`, `.env.example` etc.
+
+Os scripts precisam de quebra de linha Linux (LF). Confira e, se aparecer `CRLF`, converta:
+
+```bash
+file postgres/init/01-create-app-role.sh scripts/backup-loop.sh
+```
+
+```bash
+sed -i 's/\r$//' postgres/init/01-create-app-role.sh scripts/backup-loop.sh
+```
+
+---
+
+## 5. Criar `.env` e segredos
+
+Todos os comandos desta etapa rodam em `/opt/botpontos`.
+
+### 5.1 `.env`
+
+```bash
+cp .env.example .env && nano .env
+```
+
+Ajuste:
+
+```env
+BP_HOST_LAN_IP=192.168.18.50          # IP fixo do servidor
+BP_PUBLIC_URL=https://botpontos.lan   # exatamente o endereço que o navegador usa
+BP_NPM_IP=192.168.18.10               # IP do Nginx Proxy Manager
+BP_COOKIE_SECURE=true
+BP_LOG_LEVEL=info
+```
+
+### 5.2 Segredos
+
+```bash
+mkdir -p secrets
+```
+
+```bash
+openssl rand -base64 32 | tr -d '\n' > secrets/pg_password
+```
+
+```bash
+openssl rand -base64 32 | tr -d '\n' > secrets/pg_app_password
+```
+
+```bash
+openssl rand -base64 48 | tr -d '\n' > secrets/encryption_key
+```
+
+Token do bot (cole o seu entre as aspas simples):
+
+```bash
+printf '%s' 'COLE_O_TOKEN_DO_BOTFATHER' > secrets/telegram_token
+```
+
+Chave da feriadosapi.com, ou arquivo vazio se não tiver:
+
+```bash
+printf '%s' 'COLE_A_CHAVE' > secrets/holiday_api_key
+```
+
+```bash
+: > secrets/holiday_api_key
+```
+
+Permissões (a pasta protege; os arquivos precisam ser legíveis pelos containers):
+
+```bash
+chmod 700 secrets && chmod 644 secrets/*
+```
+
+### 5.3 Guardar a chave de criptografia fora do servidor
+
+**Sem a `encryption_key`, as senhas da PontoMais gravadas não podem ser recuperadas.** Copie o conteúdo para o seu cofre de senhas agora:
+
+```bash
+cat secrets/encryption_key
+```
+
+---
+
+## 6. Validar o código (testes)
+
+O código nunca foi compilado. Rode a validação no servidor antes de subir. Esses comandos usam containers temporários e não instalam Go nem Node na máquina.
+
+Backend — gera o `go.sum`, roda `go vet` e os testes:
+
+```bash
+docker run --rm -v "$PWD/backend:/src" -w /src golang:1.25-alpine sh -c "go mod tidy && go vet ./... && go test ./..."
+```
+
+Painel — gera o `package-lock.json` e checa os tipos:
+
+```bash
+docker run --rm -v "$PWD/web:/app" -w /app node:22-alpine sh -c "npm install && npx tsc --noEmit"
+```
+
+- Tudo passou: siga para a etapa 7.
+- Algo falhou: **pare aqui**, salve a saída completa e traga para correção.
+
+> Os arquivos `go.sum` e `package-lock.json` gerados ficam no projeto e tornam os próximos builds reproduzíveis. Copie-os de volta para a pasta do Windows também.
+
+---
+
+## 7. Subir os containers
+
+```bash
+docker compose up -d --build
+```
+
+O primeiro build leva alguns minutos. Depois confira:
+
+```bash
+docker compose ps -a
+```
+
+Resultado esperado:
+
+| Serviço | Estado |
+| --- | --- |
+| `postgres` | `running (healthy)` |
+| `migrate` | `exited (0)` |
+| `api` | `running (healthy)` |
+| `worker` | `running (healthy)` |
+| `web` | `running (healthy)` |
+| `backup` | `running` |
+
+Logs, se algo não ficar saudável:
+
+```bash
+docker compose logs --tail=100 migrate api worker
+```
+
+O worker deve registrar `liderança obtida; worker ativo` e `bot do Telegram iniciado`.
+
+Teste local da porta (no próprio servidor):
+
+```bash
+curl -s http://192.168.18.50:3000/healthz
+```
+
+Deve responder `{"status":"ok"}`.
+
+---
+
+## 8. Firewall da porta 3000
+
+Portas publicadas pelo Docker **ignoram** regras comuns de `ufw`/`iptables INPUT`. A regra vai na cadeia `DOCKER-USER`, aplicada por um serviço do systemd.
+
+Coloque o IP do NPM no arquivo:
+
+```bash
+sed -i 's/IP_DO_NPM/192.168.18.10/' deploy/botpontos-firewall.service
+```
+
+Instale e ative:
+
+```bash
+cp deploy/botpontos-firewall.service /etc/systemd/system/
+```
+
+```bash
+systemctl daemon-reload && systemctl enable --now botpontos-firewall
+```
+
+Confira a regra:
+
+```bash
+iptables -S DOCKER-USER
+```
+
+Deve aparecer uma linha com `--ctorigdstport 3000` e `! -s 192.168.18.10/32 -j DROP`.
+
+**Teste de aceite:** de um computador da rede que **não** seja o NPM, o acesso direto precisa falhar (timeout):
+
+```bash
+curl -m 5 http://192.168.18.50:3000/healthz
+```
+
+---
+
+## 9. DNS, certificado e Proxy Host
+
+### 9.1 DNS interno
+
+No DNS da rede (roteador, Pi-hole, AdGuard etc.), crie:
+
+```text
+botpontos.lan  →  192.168.18.10   (IP do NPM, não do servidor Docker)
+```
+
+### 9.2 Certificado no NPM
+
+No NPM: **SSL Certificates → Add SSL Certificate → Custom**. Envie o `.crt` (com a cadeia, se houver) e a `.key` emitidos pela CA interna para `botpontos.lan`.
+
+O certificado raiz da CA interna precisa estar instalado nos computadores que acessam o painel.
+
+### 9.3 Proxy Host
+
+**Hosts → Proxy Hosts → Add Proxy Host:**
+
+| Aba | Campo | Valor |
+| --- | --- | --- |
+| Details | Domain Names | `botpontos.lan` |
+| Details | Scheme | `http` |
+| Details | Forward Hostname / IP | `192.168.18.50` |
+| Details | Forward Port | `3000` |
+| Details | Block Common Exploits | ligado |
+| Details | Websockets Support | desligado |
+| Details | Access List | uma lista que permita só a rede local (ex.: `192.168.18.0/24`) |
+| SSL | SSL Certificate | o certificado da etapa 9.2 |
+| SSL | Force SSL / HTTP/2 / HSTS | ligados |
+
+Abra `https://botpontos.lan` num computador da rede: deve aparecer a tela de login, sem alerta de certificado.
+
+> Anote a data de validade do certificado interno. Com HSTS ligado, um certificado vencido **bloqueia** o acesso em vez de só mostrar aviso.
+
+---
+
+## 10. Primeiro acesso e primeiro admin
+
+### 10.1 Conta owner do painel
+
+No servidor (a senha, de no mínimo 12 caracteres, é pedida sem eco):
+
+```bash
+docker compose run --rm api admin create-owner --username admin
+```
+
+Entre em `https://botpontos.lan` com essa conta.
+
+### 10.2 Primeiro admin do Telegram
+
+1. A pessoa que será admin envia `/cadastrar` ao bot no Telegram.
+2. No painel, **Usuários** → abra o cadastro.
+3. Em **Credencial PontoMais**, informe e-mail e senha → **Validar e salvar**. A credencial é testada na hora; se a PontoMais recusar, nada é gravado.
+4. Clique em **Ativar**.
+5. Clique em **Tornar admin do bot**.
+6. A pessoa envia `/ativarponto` e confere com `/status`.
+
+A partir daí, novos pedidos de cadastro chegam como aviso no Telegram desse admin.
+
+### 10.3 Demais usuários
+
+Para cada usuário: `/cadastrar` no Telegram → credencial no painel → **Ativar** → o usuário envia `/ativarponto`.
+
+Recomendação: comece com 1 a 3 usuários (piloto) por alguns dias antes de liberar para todos.
+
+### 10.4 Conta de leitura para um usuário (opcional)
+
+Para que uma pessoa acompanhe só os próprios dados no painel:
+
+1. O usuário já deve estar cadastrado e ativo (item 10.2 ou 10.3).
+2. Entre com o owner → **Contas** → **Nova conta**: defina usuário e senha, papel **leitura** e escolha o **Usuário do Telegram**.
+3. Entregue a senha à pessoa. Ela verá apenas Início, Usuários, Lembretes e Feriados, e só os próprios dados.
+
+Não há migration nem variável de ambiente nova para isso: o vínculo usa a coluna `web_accounts.user_id`, que já existe. O backend e o painel precisam ser atualizados juntos.
+
+### 10.5 Feriados
+
+Em **Feriados**, clique em **Sincronizar** para o ano atual (se houver chave da feriadosapi.com) e cadastre feriados manuais que faltarem.
+
+---
+
+## 11. Backup fora da máquina
+
+O container `backup` faz um `pg_dump` por dia em `/opt/botpontos/backups`, guardando 14 dias. **Um backup no mesmo disco não protege contra falha do disco.** Copie para outra máquina ou NAS.
+
+Exemplo com um compartilhamento montado em `/mnt/nas` e cron diário às 04:00:
+
+```bash
+mkdir -p /mnt/nas/botpontos
+```
+
+```bash
+echo '0 4 * * * root cp -n /opt/botpontos/backups/*.dump /mnt/nas/botpontos/ 2>/dev/null' > /etc/cron.d/botpontos-backup
+```
+
+Guarde também, fora do servidor:
+
+- a `encryption_key` (etapa 5.3);
+- o arquivo `.env`;
+- uma cópia da pasta `secrets/` (num local seguro).
+
+### Restaurar um backup
+
+Pare os serviços que escrevem no banco:
+
+```bash
+docker compose stop api worker web
+```
+
+Restaure (troque o nome do arquivo):
+
+```bash
+docker compose exec -T postgres pg_restore -U botpontos -d botpontos --clean --if-exists --no-owner < backups/botpontos-AAAAMMDD-HHMMSS.dump
+```
+
+Suba de novo:
+
+```bash
+docker compose up -d
+```
+
+A `encryption_key` usada no restore precisa ser a mesma da época do backup.
+
+---
+
+## 12. Conferência final
+
+- [ ] `docker compose ps -a` com todos saudáveis e `migrate` em `exited (0)`.
+- [ ] `timedatectl` mostra o relógio sincronizado.
+- [ ] Acesso direto à porta 3000 bloqueado para quem não é o NPM.
+- [ ] `https://botpontos.lan` abre sem alerta de certificado.
+- [ ] Login no painel funciona; conta owner criada.
+- [ ] Admin do Telegram recebe aviso ao surgir um novo `/cadastrar`.
+- [ ] Um usuário piloto recebeu o lembrete de retorno do almoço.
+- [ ] Feriados do ano sincronizados ou cadastrados.
+- [ ] Backup do dia existe em `backups/` e foi copiado para fora.
+- [ ] `encryption_key` guardada no cofre de senhas.
+
+---
+
+## Atualizar a aplicação
+
+1. Gere um backup manual antes:
+
+   ```bash
+   docker compose exec backup sh -c 'PGPASSWORD=$(cat /run/secrets/pg_password) pg_dump -h postgres -U botpontos -d botpontos -Fc -f /backups/antes-da-atualizacao.dump'
+   ```
+
+2. Copie a nova versão do código para `/opt/botpontos` (como na etapa 4), **sem** sobrescrever `.env`, `secrets/` e `backups/`.
+3. Reconstrua e suba (as migrations rodam sozinhas no serviço `migrate`):
+
+   ```bash
+   docker compose up -d --build
+   ```
+
+4. Confira com `docker compose ps -a` e os logs.
+
+Atualize também o sistema e as imagens base de tempos em tempos:
+
+```bash
+apt update && apt full-upgrade -y
+```
+
+```bash
+docker compose pull postgres backup && docker compose up -d --build
+```
+
+---
+
+## Problemas comuns
+
+| Sintoma | Causa provável | O que fazer |
+| --- | --- | --- |
+| `docker compose up` reclama de `BP_HOST_LAN_IP` | `.env` ausente ou sem a variável | etapa 5.1 |
+| `secret ... file not found` | algum arquivo de `secrets/` não existe | etapa 5.2 (o `holiday_api_key` pode ser vazio, mas precisa existir) |
+| `migrate` termina com erro de senha | senhas do banco trocadas depois da primeira subida | as senhas só valem na 1ª inicialização do volume; veja `secrets/README.md` |
+| `api`/`worker` saem com `BP_ENCRYPTION_KEY ... obrigatório` | chave ausente ou com menos de 32 caracteres | refaça `secrets/encryption_key` |
+| `worker` sai com `BP_TELEGRAM_TOKEN ... obrigatório` | token ausente | etapa 5.2 |
+| Worker com `falha no getUpdates` repetido | token errado ou servidor sem internet | confira o token e a saída para a internet |
+| Painel abre, mas o login diz "Origem da requisição não permitida" | `BP_PUBLIC_URL` diferente do endereço usado no navegador | ajuste o `.env` (com `https://`, sem barra no fim) e rode `docker compose up -d` |
+| Login funciona, mas toda ação diz "Token CSRF inválido" | cookies de outra origem ou cache | apague os cookies do site e entre de novo; use sempre o mesmo endereço |
+| Após login, volta para a tela de login | `BP_COOKIE_SECURE=true` acessando por `http://` | acesse pelo NPM com `https://` |
+| Navegador alerta sobre o certificado | CA interna não instalada no computador, ou nome fora do SAN | etapa 9.2 |
+| Lembretes não chegam | usuário sem `/ativarponto`, dia não útil, fora da janela, ou dia sem pontos | `/status` no Telegram; tela do usuário e **Auditoria** no painel |
+| Lembrete aparece como **expirado** | ponto detectado com mais de 10 min de atraso | normal em almoço muito cedo ou atraso da PontoMais; ver ARQUITETURA.md 9.3 |
+| Usuário pausado "após falhas na PontoMais" | 3 falhas seguidas de consulta | teste a credencial no painel e religue os lembretes |
+| Alerta de "PontoMais fora do ar" | todas as consultas do ciclo falharam | aguarde; ninguém é pausado; o admin recebe aviso quando voltar |
--- a/docs/MANUAL_USUARIO.md
+++ b/docs/MANUAL_USUARIO.md
@@ -0,0 +1,427 @@
+# 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 | | ✓ | ✓ |
+| Criar contas, mudar papéis, 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.
+
+- **Sincronizar com a feriadosapi.com:** baixa os feriados do ano para a cidade configurada. O sistema também faz isso sozinho no primeiro uso de cada ano.
+- **Cadastrar feriado manual:** para pontos facultativos, recessos ou feriados que a API não trouxe.
+- **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.
+
+Sempre precisa existir **pelo menos um owner ativo**. O sistema recusa rebaixar ou desativar 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 |