commit 29614855ffbf6fd39b52984c66b065a93c1f91d2 Author: Bruno Santos Date: Fri Oct 23 22:26:47 2026 -0300 first commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..6c882a4 --- /dev/null +++ b/README.md @@ -0,0 +1,166 @@ +# Bot de Pontos v2 + +Lembretes de retorno do almoço e de fim de jornada pelo Telegram, a partir dos pontos registrados na PontoMais. + +- **Backend:** Go (API REST + worker com bot e jobs) +- **Painel:** Next.js (só administradores) +- **Banco:** PostgreSQL 17 +- **Execução:** Docker Compose numa máquina Debian, atrás do Nginx Proxy Manager da rede + +Documentação: + +- [docs/MANUAL_USUARIO.md](docs/MANUAL_USUARIO.md): manual do usuário do Telegram e do administrador do painel; +- [docs/DEPLOY.md](docs/DEPLOY.md): passo a passo de implantação no servidor; +- [docs/ARQUITETURA.md](docs/ARQUITETURA.md): arquitetura, regras de negócio e decisões. + +> **Estado:** as Sprints 0 a 6 estão implementadas, mas o código **ainda não foi compilado nem testado**. A primeira execução numa máquina com Docker deve revelar ajustes (ver "Primeira validação"). + +## Estrutura + +```text +bot-pontos-v2/ +├── backend/ # Go: um binário com api, worker, migrate e admin +│ ├── cmd/botpontos/ # ponto de entrada e comandos administrativos +│ ├── internal/ +│ │ ├── domain/ # entidades e erros (sem dependências) +│ │ ├── rules/ # cálculos puros: jornada, janela, frequência adaptativa +│ │ ├── app/ # casos de uso (Telegram, painel, CLI e jobs usam os mesmos) +│ │ ├── bot/ # comandos do Telegram +│ │ ├── httpapi/ # API REST do painel +│ │ ├── worker/ # liderança, bot e ciclos (reconciliação, despacho, manutenção) +│ │ ├── bootstrap/ # montagem dos adapters reais +│ │ ├── config/ # variáveis de ambiente e segredos +│ │ ├── httpx/ # utilitários HTTP +│ │ └── adapters/ # postgres, pontomais, telegram, feriados, crypto +│ ├── db/migrations/ # SQL (goose), embutido no binário +│ └── api/openapi.yaml # contrato da API +├── web/ # Next.js (App Router, CSS próprio) +├── postgres/init/ # cria o usuário da aplicação na 1ª subida do banco +├── scripts/backup-loop.sh # pg_dump diário com retenção de 14 dias +├── deploy/ # firewall da porta 3000 (só o NPM acessa) +├── secrets/ # Docker secrets (não versionar o conteúdo) +├── docker-compose.yml +└── .env.example +``` + +## Implantação + +> O passo a passo completo para o servidor Debian (Docker, firewall, NPM, certificado, primeiro admin, backup e problemas comuns) está em **[docs/DEPLOY.md](docs/DEPLOY.md)**. O resumo abaixo serve de referência rápida. + +Pré-requisito: Debian 12 com Docker Engine e plugin Compose (repositório oficial da Docker), NTP ativo e IP fixo. Go e Node **não** precisam estar instalados; o build acontece dentro dos containers. + +### 1. Configuração + +```bash +cp .env.example .env +``` + +Ajuste no `.env`: + +- `BP_HOST_LAN_IP`: IP fixo do servidor (o NPM aponta para ele); +- `BP_PUBLIC_URL`: endereço do painel, igual ao nome do certificado no NPM (ex.: `https://botpontos.lan`); +- `BP_NPM_IP`: IP do Nginx Proxy Manager. + +### 2. Segredos + +Siga [secrets/README.md](secrets/README.md) para criar `pg_password`, `pg_app_password`, `encryption_key`, `telegram_token` e `holiday_api_key`. + +### 3. Subir + +```bash +docker compose up -d --build +``` + +```bash +docker compose ps +``` + +`postgres`, `api`, `worker` e `web` devem ficar `healthy`; `migrate` deve terminar com `exited (0)`. + +### 4. Firewall e proxy + +- Instale `deploy/botpontos-firewall.service` (instruções no próprio arquivo) para que só o NPM alcance a porta 3000. +- No NPM, crie o Proxy Host apontando para `http://IP_DO_SERVIDOR:3000` com o certificado interno, Force SSL, HTTP/2 e HSTS (ARQUITETURA.md, 11.4). + +## Primeiro uso + +1. **Criar a conta owner do painel** (a senha é pedida no terminal, sem eco): + + ```bash + docker compose run --rm api admin create-owner --username admin + ``` + +2. **Entrar no painel** pelo endereço do NPM. + +3. **Cadastrar o primeiro admin do Telegram:** no Telegram, a pessoa envia `/cadastrar` ao bot. No painel, em **Usuários**, abra o cadastro, configure a credencial da PontoMais (ela é validada na hora), clique em **Ativar** e depois em **Tornar admin do bot**. + + Pela linha de comando, o equivalente é: + + ```bash + docker compose run --rm api admin set-credentials --user-id 1 --email pessoa@empresa.com + ``` + + ```bash + docker compose run --rm api admin bot-admin --user-id 1 --enable + ``` + +4. **Demais usuários:** cada um envia `/cadastrar`; o admin recebe o aviso pelo Telegram, configura a credencial no painel e ativa. O usuário envia `/ativarponto` para ligar os lembretes. + +## Comandos úteis + +Logs de um serviço: + +```bash +docker compose logs -f worker +``` + +Situação das migrations: + +```bash +docker compose run --rm migrate migrate status +``` + +Redefinir a senha de uma conta do painel: + +```bash +docker compose run --rm api admin reset-password --username admin +``` + +Recifrar as credenciais após trocar a chave (ver secrets/README.md): + +```bash +docker compose run --rm api admin rotate-key +``` + +## Primeira validação + +O código foi escrito sem compilação nem testes. Na primeira máquina onde isso for permitido, nesta ordem: + +1. Gerar o `go.sum` e rodar vet e testes do backend: + + ```bash + docker run --rm -v "$PWD/backend:/src" -w /src golang:1.25-alpine sh -c "go mod tidy && go vet ./... && go test ./..." + ``` + +2. Gerar o `package-lock.json` e checar os tipos do painel: + + ```bash + docker run --rm -v "$PWD/web:/app" -w /app node:22-alpine sh -c "npm install && npx tsc --noEmit" + ``` + +3. Subir com `docker compose up -d --build` e seguir "Primeiro uso". +4. Piloto com 1 a 3 usuários, medindo o atraso do `last_cached` da PontoMais (log e auditoria mostram quando cada ponto foi detectado). + +Mantenha o `go.sum` e o `package-lock.json` gerados no projeto, para builds reproduzíveis. + +## Sprints + +| Sprint | Entrega | +| --- | --- | +| 0 — Fundação | Estrutura, Compose, migrations, health, liderança do worker | +| 1 — Núcleo | Domínio e regras puras (com testes), cliente PontoMais, criptografia AES-GCM com rotação de chave | +| 2 — Bot | Comandos do Telegram com ativação unificada e avisos aos admins | +| 3 — Lembretes | Reconciliação na janela com frequência adaptativa, despacho a cada 2 min com `SKIP LOCKED`, tolerância de 10 min, 3 falhas seguidas, detecção de queda, feriados | +| 4 — API | Login com Argon2id e bloqueio, sessões, CSRF, papéis, todos os endpoints do painel | +| 5 — Painel | Dashboard, usuários (jornada, janela personalizada, credencial, consulta ao vivo), lembretes (cancelar/reenviar), auditoria, feriados, configurações com pré-visualização, contas | +| 6 — Operação | Retenção de dados, manutenção, CLI administrativa, backup, firewall, documentação |