@seedgrid/ai-toolkit 0.3.2 → 0.3.4

package/seedgridKB/SeedGrid/Produtos/Pulse/Servidor/Configuracao.md

@@ -0,0 +1,128 @@
+---
+tags: [seedgrid, produto, pulse, servidor, configuracao, variaveis]
+fonte: seedgrid-products/seedgrid-pulse/backend (src/config.rs, env.md)
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse (servidor) — variáveis de ambiente
+
+Todas as variáveis do **servidor**. As da UI estão em [[SeedGrid/Produtos/Pulse/UI/Configuracao|Configuração da UI]]. Arquitetura atual: **login-tenancy, banco único** — a separação entre clientes é lógica, por `company_id`. Sem `POSTGRES_URL` o servidor sobe em modo memória/dev com a plataforma desabilitada.
+
+Convenção: 🔒 = segredo (nunca em repositório/log); valores de exemplo são placeholders, **não** padrões.
+
+## Runtime (HTTP, WebSocket, CORS)
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `HTTP_HOST` | `127.0.0.1` | IP de bind. Em container use `0.0.0.0`. |
+| `HTTP_PORT` | `8080` | Porta HTTP. |
+| `WS_PATH` | `/ws` | Path do WebSocket legado (o endpoint do protocolo é `/api/v1/connect`). |
+| `CORS_ALLOWED_ORIGINS` | vazio | Lista separada por vírgula. Vazio = nenhuma origem liberada. |
+| `WS_HEARTBEAT_INTERVAL_SECONDS` | `30` | Heartbeat do WebSocket. |
+| `WS_IDLE_TIMEOUT_SECONDS` | `90` | Fecha conexão ociosa. |
+
+## Credenciais do Pulse 🔒
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `SEEDGRID_PULSE_SERVER_KEY` | — | Chave **administrativa** (contas/chaves, métricas) em `x-api-key`. **Não publica** (403). Só em ENV; fica só com a operação do Pulse. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_SECRET` | — | Segredo HMAC-SHA256 que assina o token curto de conexão. Sem ele, `POST /api/v1/connect-tokens` responde 503. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_PREVIOUS_SECRET` | — | Segredo anterior, aceito só na verificação (rotação sem derrubar tokens válidos). |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_TTL_SECS` | `300` | Validade do token quando o pedido não informa `ttlSeconds`. É a janela para **conectar**. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_MAX_TTL_SECS` | `900` | Teto: pedido acima → 422. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_RATE_PER_KEY` | `600` | Emissões/min por chave `project`; `0` desliga. Por instância. |
+| `SEEDGRID_PULSE_CONNECT_TOKEN_RATE_PER_SUBJECT` | `30` | Emissões/min por `subject` na mesma chave; `0` desliga. Por instância. |
+| `SEEDGRID_PULSE_PUBLIC_WS_URL` | — | Endereço **público** do WebSocket devolvido em `connectUrl`. Ausente = campo omitido. |
+
+Quem usa cada credencial: [[SeedGrid/Produtos/Pulse/Autenticacao-e-chaves|Autenticação e chaves]].
+
+## Persistência e mensageria
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `POSTGRES_URL` | — | **Interruptor da plataforma.** Sem ela, security/login-tenancy/audit/apikeys ficam desligados. 🔒 |
+| `POSTGRES_RUN_MIGRATIONS` | `true` | Roda migrations na subida. |
+| `DELIVERY_STORE_BACKEND` | `memory` | `memory` \| `postgres`. Em produção, `postgres`. |
+| `BROKER_PROVIDER` | `memory` | `memory` \| `redis` \| `nats` \| `rabbitmq` (fallback `EVENT_BUS_BACKEND`). Valor desconhecido cai em `memory`. Detalhes e variáveis por provider: [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers]]. |
+| `PRESENCE_BACKEND` | `memory` | `memory` \| `redis`. Multi-réplica ⇒ `redis`. |
+| `BROKER_REDIS_URL` | — | URL Redis-compatível (fallback `REDIS_URL`). 🔒 |
+| `BROKER_REDIS_CHANNEL` | `seedgrid:pulse:events` | Canal pub/sub (fallback `REDIS_PUBSUB_CHANNEL`). |
+| `BROKER_NATS_URL` | — | URL do NATS (`nats://host:4222`; fallback `NATS_URL`). Obrigatória com `nats`. 🔒 |
+| `BROKER_NATS_SUBJECT` | `seedgrid.pulse.events` | Subject do pub/sub. |
+| `BROKER_RABBITMQ_URL` | — | URL AMQP (fallbacks `RABBITMQ_URL`, `AMQP_URL`). Obrigatória com `rabbitmq`. 🔒 |
+| `BROKER_RABBITMQ_EXCHANGE` | `seedgrid.pulse.events` | Exchange fanout. |
+
+As URLs Redis-compatíveis servem para Valkey e Dragonfly sem mudar mais nada; ver [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers]].
+
+## Entrega (retry, TTL, limpeza)
+
+Os pares `*_CAP` são o **teto** que uma configuração por mensagem pode pedir; omitidos, assumem o valor base. Todos (exceto o intervalo de limpeza) são editáveis em runtime em **Configurações**.
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `DELIVERY_RETRY_STRATEGY` | `exponential` | `exponential` (qualquer outro valor = `fixed`: atraso constante de `DELIVERY_RETRY_BASE_MS`). |
+| `DELIVERY_RETRY_BASE_MS` | `300` | Backoff base. |
+| `DELIVERY_RETRY_MAX_MS` | `5000` | Backoff máximo. |
+| `DELIVERY_MAX_ATTEMPTS` | `20` | Tentativas de execução por mensagem (modo `processed`). |
+| `DELIVERY_TTL_SECONDS` | `86400` | TTL da mensagem (1 dia). |
+| `DELIVERY_RESULT_TIMEOUT_SECONDS` | `0` (sem prazo) | **Prazo de execução** padrão (modo `processed`): segundos entre o `ack` e o `result`. `0` desliga. Estourado, vale como `retryable` com motivo `result_timeout`. Editável em Configurações, sem reinício. |
+| `DELIVERY_RESULT_TIMEOUT_SECONDS_CAP` | `86400` (ou o padrão, se maior) | Teto do prazo que o publisher pode pedir; `0` **proíbe** o prazo de execução. |
+| `DELIVERY_RETRY_BASE_MS_CAP` / `DELIVERY_RETRY_MAX_MS_CAP` / `DELIVERY_MAX_ATTEMPTS_CAP` / `DELIVERY_TTL_SECONDS_CAP` | = valor base | Tetos para o override por mensagem. |
+| `DELIVERY_CLEANUP_INTERVAL_SECONDS` | `60` | Intervalo da varredura de retenção (`DELIVERY_CLEANUP_RETENTION_DAYS`) e da limpeza automática da lixeira. **Não** controla a expiração por TTL, que tem verificador próprio (a cada `ceil(DELIVERY_RETRY_BASE_MS/1000)` s, mínimo 1 s). Exige reinício. |
+| `DELIVERY_CLEANUP_RETENTION_DAYS` | `0` (nunca apaga) | **Dias** que uma mensagem em estado final (`completed`/`dead_letter`/`expired`) é mantida. `0` desliga a varredura: o histórico é prova. Obsoleta: `DELIVERY_CLEANUP_RETENTION_SECONDS` (lida só se a de dias não existir). |
+| `DELIVERY_TRASH_AUTO_CLEAN_DAYS` | `0` (só manual) | Dias na lixeira antes da limpeza automática. Cada limpeza vai ao audit como `system:pulse`. |
+
+Detalhes e as regras de lixeira: [[SeedGrid/Produtos/Pulse/Servidor/Operacao|Operação]].
+
+## Security (login, JWT, RBAC)
+
+Habilitado com `POSTGRES_URL` **e** as chaves RSA. Nomes alinhados à extension Java `security` ([[SeedGrid/Extensions/security/Configuracao|Configuração do security]]).
+
+| Variável | Descrição |
+|---|---|
+| `SECURITY_PRIVATE_KEY_LOCATION` / `SECURITY_PUBLIC_KEY_LOCATION` | Caminhos do par RSA (primários). 🔒 |
+| `SECURITY_JWT_PRIVATE_KEY_PEM` / `SECURITY_JWT_PUBLIC_KEY_PEM` | PEM inline (secundário). 🔒 |
+| `SECURITY_JWT_ISSUER` / `SECURITY_JWT_KID` | Issuer e `kid` do JWT. |
+| `SECURITY_JWT_TTL` | Validade do access token, ISO-8601 (`PT8H`). |
+| `SECURITY_REFRESH_TOKEN_TTL` | Validade do refresh token (`P30D`). |
+| `SECURITY_PASSWORD_MIN_SIZE` / `_EXPIRATION_DAYS` / `_MAX_HISTORY` | Política de senha. |
+| `SECURITY_ENCRYPTION_KEY` | AES-256 (base64) da cripto de campo; obrigatória se usar TOTP. 🔒 |
+| `SECURITY_FRONTEND_BASE_URL` | Base da UI nos links de e-mail. |
+| `SEEDGRID_SECURITY_FIRST_ADMIN_USER_EMAIL` / `_NAME` / `_INITIAL_PASSWORD` | Bootstrap do primeiro admin. 🔒 |
+| `SEEDGRID_SECURITY_DEFAULT_COMPANY_CNPJ` / `_CORPORATE_NAME` / `_TRADE_NAME` | Company da plataforma (razão social e fantasia são obrigatórias no bootstrap). |
+
+### 2FA
+
+Desligado por padrão. `SEEDGRID_SECURITY_2F_ENABLED=true` liga; `_ALLOWED_METHODS` (`EMAIL,TOTP`), `_DEFAULT_METHOD` (`TOTP`), `_EMAIL_CODE_TTL`, `_SESSION_TTL`, `_VERIFY_MAX_ATTEMPTS` (5), `_TOTP_ISSUER` (`SeedGrid`; vale trocar para `SeedGrid Pulse`), `_TOTP_DIGITS` (6), `_TOTP_PERIOD` (30), `_TOTP_WINDOW` (1), `_BACKUP_CODES_COUNT` (10). WhatsApp: `SEEDGRID_SECURITY_2F_WHATSAPP_CHANNEL_ID` mais um provider em `SEEDGRID_WHATSAPP_API` (`evolution`/`cloud`) com credenciais ([[SeedGrid/Extensions/whatsapp/Configuracao|whatsapp]]).
+
+### E-mail (SMTP)
+
+`SECURITY_MAILER_USERNAME` e `_PASSWORD` ligam o SMTP real (🔒); `_HOST` (`smtp.gmail.com`), `_PORT` (587), `_START_TLS` (`REQUIRED`), `_FROM`. **Sem usuário e senha o e-mail só vai para o log** — confirmação, reset de senha e 2FA por e-mail não chegam.
+
+## Login-tenancy
+
+`SEEDGRID_LOGIN_TENANCY_APP_CODE` (`seedgrid-app`; use `seedgrid-pulse`), `_APP_NAME`, `_DATABASE_MIGRATE_AT_START` (`true`), `_DATABASE_BASELINE_ON_MIGRATE` (`true`), `_FOUNDATION_STATUS_ENABLED`, `_FOUNDATION_HEALTH_ENABLED`, `_BOOTSTRAP_ENABLED`, `_BOOTSTRAP_ADMIN_ENABLED`. Não existe flag "enabled": a dependência ativa o baseline. `SEEDGRID_SHOW_DEV_MESSAGE` (`false`) inclui detalhe interno nos erros — **nunca em produção**. Ver [[SeedGrid/Extensions/login-tenancy/Configuracao|login-tenancy]].
+
+## Audit
+
+`SEEDGRID_AUDIT_ENABLED` (`true`), `AUDIT_STRATEGY` (`JPA` = Postgres \| `MONGODB`), `SEEDGRID_AUDIT_DB_*` só para banco de auditoria separado, `SEEDGRID_AUDIT_MONGODB_URI`/`_DATABASE`. No deploy padrão as migrations de audit rodam no mesmo banco. A leitura é escopada por `company_id` via headers internos sobrescritos pelo JWT — não os repasse de proxy. Ver [[SeedGrid/Extensions/audit/Configuracao|audit]].
+
+## API keys
+
+`SEEDGRID_APIKEYS_PREFIX_LENGTH` (`8`), `SEEDGRID_APIKEYS_KEY_BYTES` (`32`). Ver [[SeedGrid/Extensions/apikeys/Configuracao|apikeys]].
+
+## Observabilidade
+
+`RUST_LOG` (ex.: `info`). Métricas: `GET /metrics` (JSON) e `GET /metrics/prometheus`; Prometheus e Grafana vêm no compose.
+
+## Variáveis removidas (não configure)
+
+As de multitenancy por subdomínio (`DOMAIN_SUFFIX`, `SEEDGRID_MULTITENANCY_*`, `PRODUCT_PREFIX`, `MULTITENANCY_MAILER_*`) foram eliminadas e são ignoradas. Backup (`BACKUP_*`) e billing (`SEEDGRID_BILLING_*`) não se aplicam ao Pulse hoje.
+
+## Pegadinhas
+
+- A chave de servidor nunca vai para produto nenhum nem para o serviço da UI.
+- Variável definida no EasyPanel **vence** o padrão de código: ao mudar um padrão, confira o ambiente.
+- `0` em retenção/limpeza significa **desligado** (não "apagar tudo").

package/seedgridKB/SeedGrid/Produtos/Pulse/Servidor/Instalacao.md

@@ -0,0 +1,105 @@
+---
+tags: [seedgrid, produto, pulse, servidor, instalacao, deploy]
+fonte: seedgrid-products/seedgrid-pulse/backend
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse (servidor) — instalação e execução
+
+O **servidor Pulse** é o backend Rust (Axum): API REST, WebSocket, entrega, retry, DLQ, presença e módulos de plataforma. A UI é outro componente: [[SeedGrid/Produtos/Pulse/UI/Visao-geral|Pulse UI]].
+
+Voltar: [[SeedGrid/Produtos/Pulse/Visao-geral|Visão geral]] · variáveis: [[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração do servidor]] · brokers: [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers (Redis, Valkey, Dragonfly, NATS, RabbitMQ)]]
+
+## Modos de execução
+
+| Modo | Quando | Persistência |
+|---|---|---|
+| **Memória** (sem `POSTGRES_URL`) | desenvolvimento rápido, testes | nenhuma; plataforma (login, audit, apikeys) **desabilitada** — só o núcleo realtime |
+| **Postgres** | produção de instância única | mensagens, contas, usuários, audit |
+| **Distribuído** | várias réplicas | Postgres + broker pub/sub + presença em Redis |
+
+Exemplos de `env` (Confirmado — `backend/README.md`):
+
+```env
+# simples
+BROKER_PROVIDER=memory
+PRESENCE_BACKEND=memory
+DELIVERY_STORE_BACKEND=memory
+
+# com Postgres
+DELIVERY_STORE_BACKEND=postgres
+POSTGRES_URL=postgres://<user>:<senha>@<host>:5432/<db>
+
+# distribuído
+BROKER_PROVIDER=redis
+PRESENCE_BACKEND=redis
+DELIVERY_STORE_BACKEND=postgres
+BROKER_REDIS_URL=redis://<host>:6379/0
+```
+
+## Subir com Docker/Podman Compose
+
+Em `backend/`:
+
+```bash
+docker compose up -d --build
+```
+
+Sobe `postgres`, `redis`, `seedgrid-pulse`, `prometheus`, `grafana` e `seedgrid-pulse-ui`. Portas locais (Confirmado — `docker-compose.yml`): API `18080`, Prometheus `19090`, Grafana `13001`, UI `13000`.
+
+O compose de desenvolvimento traz valores de exemplo (chave de servidor, segredo do token, admin inicial). **Troque todos** em qualquer ambiente real. 🔒
+
+## Rodar a partir do fonte
+
+Pré-requisitos: Rust estável recente (edition 2024) e o repositório de crates da plataforma clonado ao lado (path dependencies).
+
+```text
+<raiz>/
+├─ seedgrid-platform/rust/              # crates seedgrid-rust-crate-*
+└─ seedgrid-products/seedgrid-pulse/    # este repo
+```
+
+O prefixo `../../../seedgrid-platform/rust/` está em `backend/Cargo.toml`; ajuste-o se o layout for outro.
+
+```bash
+cd backend
+docker compose up -d postgres redis
+cargo run
+```
+
+O build não precisa de banco (não há `sqlx::query!` verificada em compilação).
+
+## Primeiro acesso
+
+Com `POSTGRES_URL` e o par RSA do JWT, o boot roda as migrations e cria a company da plataforma e o **primeiro admin** a partir de `SEEDGRID_SECURITY_FIRST_ADMIN_USER_*` e `SEEDGRID_SECURITY_DEFAULT_COMPANY_*` ([[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração]]). Entre na UI com esse admin, crie a **conta** do seu produto e as **chaves** (Contas → conta → Chaves → Nova chave). O segredo da chave aparece **uma única vez**.
+
+Par RSA do JWT (exemplo):
+
+```bash
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private.pem
+openssl rsa -pubout -in private.pem -out public.pem
+```
+
+Aponte `SECURITY_PRIVATE_KEY_LOCATION` / `SECURITY_PUBLIC_KEY_LOCATION` (ou use PEM inline).
+
+## Imagem e deploy
+
+- Imagem no GHCR: `ghcr.io/seedgrid/seedgrid-pulse-backend` (Confirmado — `.github/workflows/deploy.yml`).
+- `push` em `main` dispara o workflow, que detecta o que mudou, publica a imagem e chama o webhook do EasyPanel (secret `EASYPANEL_DEPLOY_URL_PULSE_BACKEND`). Commit só de documentação **não** redeploya.
+- O container escuta `8080`; use `HTTP_HOST=0.0.0.0` em container.
+- Probes: liveness `GET /health`, readiness `GET /ready` (200/503 com o estado de store, broker e presença).
+- Migrations rodam no boot (`POSTGRES_RUN_MIGRATIONS`, padrão `true`).
+
+## Checklist de produção
+
+- [ ] `POSTGRES_URL` + `DELIVERY_STORE_BACKEND=postgres`.
+- [ ] Mais de uma réplica ⇒ broker pub/sub (`redis`, ou `nats`/`rabbitmq` — ver [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers]]) **e** `PRESENCE_BACKEND=redis`.
+- [ ] `SEEDGRID_PULSE_SERVER_KEY` e `SEEDGRID_PULSE_CONNECT_TOKEN_SECRET` longos e aleatórios, só em ENV. 🔒
+- [ ] `SEEDGRID_PULSE_PUBLIC_WS_URL` com o endereço público do WebSocket (`wss://…`), se há clientes de navegador.
+- [ ] `CORS_ALLOWED_ORIGINS` com a origem da UI.
+- [ ] Par RSA do JWT próprio; admin inicial trocado.
+- [ ] `SEEDGRID_SHOW_DEV_MESSAGE` desligado (padrão).
+- [ ] Proxy reverso **não** repassa `x-seedgrid-company-id` / `x-seedgrid-all-companies` vindos do cliente.
+- [ ] Retenção do histórico decidida (padrão: nunca apagar) — [[SeedGrid/Produtos/Pulse/Servidor/Operacao|Operação]].

package/seedgridKB/SeedGrid/Produtos/Pulse/Servidor/Operacao.md

@@ -0,0 +1,86 @@
+---
+tags: [seedgrid, produto, pulse, servidor, operacao, lixeira, retencao]
+fonte: seedgrid-products/seedgrid-pulse/backend (docs/LIXEIRA-mensagens-e-contas.md, README.md)
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse (servidor) — operação
+
+Lixeira, retenção, auditoria, observabilidade e escala. Voltar: [[SeedGrid/Produtos/Pulse/Visao-geral|Visão geral]] · variáveis: [[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração]].
+
+## Princípios
+
+- O **histórico de entregas é prova**: por padrão **nunca é apagado sozinho**.
+- Apagar é **sempre ação humana**, com permission própria, confirmação na UI e **audit** (quem, o quê, quantos).
+- A chave de servidor **não apaga nada** (401): toda exclusão tem um autor.
+
+## Lixeira de mensagens
+
+- **Só mensagens `pending`** podem ir para a lixeira (mensagens entregues/processadas são histórico; só saem com a exclusão da conta).
+- Na UI: **Mensagens**, filtro de status **"Na lixeira"**. Mover (`PULSE_MESSAGE_DELETE`), restaurar (volta a `pending`) e limpar de vez (`PULSE_MESSAGE_PURGE`, apaga também as entregas por destinatário).
+- API: `POST /api/v1/messages/trash` · `/trash/restore` · `/trash/purge`, lote de até **1000** ids (`400 BATCH_TOO_LARGE`), resposta `{requested, affected, skipped}`.
+- Mensagem na lixeira não é entregue, não expira por TTL e some das listas padrão.
+- **Descartar** (tela Pendências, `PULSE_BACKLOG_DISCARD`) e **Lixeira** coexistem como ações distintas; só a lixeira tem restaurar e limpar de vez.
+- Tarefas `delivered` sem `result` e sem prazo de execução (as anteriores ao Pulse 0.3.0, ou quando `resultTimeoutSeconds` não foi usado) só saem por **descarte**; veja [[SeedGrid/Produtos/Pulse/Protocolo-e-API#Prazo de execução (resultTimeoutSeconds)|Prazo de execução]].
+
+## Lixeira de contas
+
+- A lixeirinha da lista de contas pede confirmação e leva a conta para `pending_delete` (`PULSE_ACCOUNT_DELETE`). A conta **deixa de autenticar** e suas conexões são derrubadas.
+- **Lixeira de contas** (menu): restaurar (volta ao status anterior) ou **apagar definitivamente** (`PULSE_ACCOUNT_PURGE`), que remove a conta, suas chaves e **todas as suas mensagens** em cascata. O diálogo mostra antes quantas chaves e mensagens saem (`GET /accounts/{id}/deletion-summary`).
+- O apagar definitivo **não é uma transação única**: mensagens primeiro, conta por último. Se falhar no meio, a conta continua na lixeira e dá para repetir.
+
+## Retenção e limpeza automática
+
+| Variável | Padrão | Efeito |
+|---|---|---|
+| `DELIVERY_CLEANUP_RETENTION_DAYS` | `0` | Dias que uma mensagem **final** (`completed`/`dead_letter`/`expired`) é mantida. `0` = **nunca apaga**. |
+| `DELIVERY_TRASH_AUTO_CLEAN_DAYS` | `0` | Dias na lixeira antes de apagar sozinho. `0` = só manual. Cada limpeza vai ao audit como `system:pulse`. |
+
+As duas **não se sobrepõem**: a primeira atua no histórico (estados finais), a segunda na lixeira (`trashed`). Mensagens `pending` e `delivered` nunca são limpas pela retenção. A obsoleta `DELIVERY_CLEANUP_RETENTION_SECONDS` só vale se a de dias não existir. Ambas são editáveis em **Configurações**, sem redeploy.
+
+> **Mudança de comportamento (2026-10-15):** o padrão era 7 dias e `0` apagava tudo. Ambientes que definem a variável explicitamente (EasyPanel) mantêm o valor definido.
+
+Sem consumidor, uma `pending` não fica para sempre: o TTL (`DELIVERY_TTL_SECONDS`, 1 dia) a expira.
+
+## Ordem das listas e paginação
+
+As telas listam **da mais recente para a mais antiga** (quem acabou de publicar vê a sua primeira): contas por `created_at`, mensagens por `published_at` e entregas por destinatário por `delivered_at`, todas **com desempate por id**. A paginação é 1-based (`page`, `pageSize`; a Auditoria usa `page`/`size` e o backend dela é base 0, convertido pela UI). Até o Pulse 0.2.1 a lista de contas ordenava sem desempate, e contas criadas no mesmo segundo repetiam ou sumiam entre páginas (corrigido no 0.2.2). O **replay** e as pendências devidas continuam em ordem cronológica (do mais antigo ao mais novo), porque entregar na ordem de publicação é o comportamento certo (Confirmado em `delivery/repo.rs`).
+
+## Auditoria
+
+Toda operação destrutiva (mover para lixeira, restaurar, limpar; contas e mensagens) grava em `audit_log` o autor (claim `sub` do JWT, e-mail na descrição), a ação e as contagens, **somente se algo mudou**. Visível em **Segurança → Auditoria** (escopo por `company_id`).
+
+## Observabilidade
+
+| O quê | Onde |
+|---|---|
+| Liveness / readiness | `GET /health` · `GET /ready` (200 `READY` / 503 `NOT_READY`, com store, broker e presença) |
+| Métricas | `GET /metrics` (JSON) · `GET /metrics/prometheus` |
+| Dashboards | Prometheus + Grafana no compose (`SeedGrid Pulse Overview`) |
+| Telas | dashboard, conexões, backlog, DLQ, mensagens, entregas por destinatário |
+
+Métricas úteis: `publish_requests_total`, `delivery_attempts_total`, `delivery_success_total`, `delivery_dead_letter_total`, `delivery_expired_total`, `delivery_result_timeout_total` (prazo de execução estourado), `ack_total`, `ws_connections_opened_total`/`_closed_total`, latências `publish_to_deliver_*` e `deliver_to_ack_*`.
+
+## Escala (várias réplicas)
+
+- Estado durável no **Postgres** (`DELIVERY_STORE_BACKEND=postgres`).
+- Entrega entre instâncias via **broker pub/sub** (`BROKER_PROVIDER`) e presença em Redis (`PRESENCE_BACKEND=redis`): ver [[SeedGrid/Produtos/Pulse/Servidor/Providers|Providers]].
+- Revogação de credencial atravessa o broker (tópico `pulse.revocations`) e derruba as conexões em **todas** as instâncias.
+- Limites de emissão de token são **por instância**: com N réplicas o efetivo é até N vezes.
+
+## Diagnóstico rápido
+
+| Sintoma | Verifique |
+|---|---|
+| Publicou e ninguém recebeu | `accountId`/conta ativa; `channel` e `event` batem com o `subscribe`; `user` do destino = `subject` da conexão; entrega fica `pending` até alguém conectar |
+| 403 ao publicar | está usando chave `client` ou a chave de servidor; use a `project` |
+| WebSocket 401 | credencial ausente/revogada; token `pct_` vencido antes de conectar |
+| Conexão fecha com `4403` | chave/conta revogada: não reconecte com a mesma credencial |
+| `connect-tokens` 503 | falta `SEEDGRID_PULSE_CONNECT_TOKEN_SECRET` |
+| E-mail/2FA por e-mail não chega | `SECURITY_MAILER_USERNAME`/`_PASSWORD` ausentes (só loga) |
+| Histórico "sumiu" | retenção definida no ambiente (`DELIVERY_CLEANUP_RETENTION_*`) |
+| Réplica B não recebe o que A publicou | broker `memory` em produção multi-réplica |
+
+Testes e CI: `cargo test` (unitários e e2e); com Docker/Podman, `cargo test redis_ -- --ignored`, `postgres_ -- --ignored` e `--test trash_integration -- --ignored --test-threads=1` sobem Postgres/Redis via testcontainers.

package/seedgridKB/SeedGrid/Produtos/Pulse/Servidor/Providers.md

@@ -0,0 +1,121 @@
+---
+tags: [seedgrid, produto, pulse, servidor, broker, redis, valkey, dragonfly, nats, rabbitmq, postgres]
+fonte: seedgrid-products/seedgrid-pulse/backend (src/config.rs, src/broker.rs, tests/) + seedgrid-platform/rust/seedgrid-rust-crate-broker
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse (servidor) — providers: broker, presença e store
+
+O Pulse separa três responsabilidades, cada uma com seu provider. Voltar: [[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração do servidor]] · [[SeedGrid/Produtos/Pulse/Servidor/Instalacao|Instalação]].
+
+| Responsabilidade | Variável | Opções | Para quê |
+|---|---|---|---|
+| **Broker** (pub/sub entre instâncias) | `BROKER_PROVIDER` | `memory`, `redis`, `nats`, `rabbitmq` | levar uma publicação a **todas** as instâncias, para a que tem o WebSocket entregar; e propagar revogação de credencial |
+| **Presença** (quem está conectado em quê) | `PRESENCE_BACKEND` | `memory`, `redis` | presença por canal/grupo compartilhada entre instâncias |
+| **Store de entregas** (mensagens, estados, DLQ) | `DELIVERY_STORE_BACKEND` | `memory`, `postgres` | durabilidade, replay, histórico |
+
+## Quando precisa de quê
+
+| Cenário | Broker | Presença | Store |
+|---|---|---|---|
+| Desenvolvimento / uma instância sem persistência | `memory` | `memory` | `memory` |
+| **Uma instância em produção** | `memory` | `memory` | `postgres` |
+| **Várias réplicas (escala)** | `redis` \| `nats` \| `rabbitmq` | **`redis`** | `postgres` |
+
+- Sem broker compartilhado, uma réplica não entrega o que outra publicou (ver [[SeedGrid/Produtos/Pulse/Servidor/Operacao|Operação — diagnóstico]]).
+- **A presença só tem `memory` e `redis`.** Com NATS ou RabbitMQ como broker em várias réplicas, ainda é preciso um servidor Redis-compatível para `PRESENCE_BACKEND=redis` (Confirmado — `config.rs`).
+- O estado de entrega vive no **Postgres**; o broker é só o barramento. Por isso um broker sem persistência (NATS core) não perde mensagem do Pulse: o replay a recupera do banco.
+
+## Redis e compatíveis (Valkey, Dragonfly, KeyDB…)
+
+Usa pub/sub do protocolo Redis. Variáveis:
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `BROKER_PROVIDER=redis` | | |
+| `BROKER_REDIS_URL` (fallback `REDIS_URL`) | — | `redis://host:6379/0`; use `rediss://` para TLS. 🔒 |
+| `BROKER_REDIS_CHANNEL` (fallback `REDIS_PUBSUB_CHANNEL`) | `seedgrid:pulse:events` | canal pub/sub |
+| `PRESENCE_BACKEND=redis` | | usa a mesma `BROKER_REDIS_URL` |
+
+Como o Pulse só fala o protocolo Redis (cliente `redis` 0.32), qualquer servidor compatível serve — **basta apontar a URL**. Verificado em 2026-10-16 rodando a suíte `redis_integration` (broker pub/sub, presença com expiração/heartbeat e revogação entre instâncias) contra:
+
+| Servidor | Imagem testada | Resultado |
+|---|---|---|
+| Redis | `redis:7.2.4` | 5/5 ✅ |
+| Valkey | `valkey/valkey:8` | 5/5 ✅ |
+| Dragonfly | `docker.dragonflydb.io/dragonflydb/dragonfly:latest` | 5/5 ✅ |
+
+KeyDB e serviços gerenciados (ElastiCache, Memorystore, Upstash…) **não foram testados** aqui; devem funcionar por falarem o mesmo protocolo (Inferência) — rode a suíte antes de adotar.
+
+Para validar outro servidor:
+
+```bash
+SG_PULSE_TEST_REDIS_IMAGE=<imagem>:<tag> \
+DOCKER_HOST='npipe:////./pipe/podman-machine-default' TESTCONTAINERS_RYUK_DISABLED=true \
+cargo test --test redis_integration -- --ignored --test-threads=1
+```
+
+Exemplo de troca (compose): no serviço `redis`, use a imagem `valkey/valkey:8` (ou Dragonfly) e mantenha `BROKER_REDIS_URL=redis://redis:6379/0`; nenhuma outra variável muda.
+
+## NATS
+
+Pub/sub **core** do NATS em um `subject`; cada instância assina o mesmo subject e recebe tudo (fan-out).
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `BROKER_PROVIDER=nats` | | |
+| `BROKER_NATS_URL` (fallback `NATS_URL`) | — | `nats://host:4222`. **Obrigatória.** 🔒 |
+| `BROKER_NATS_SUBJECT` | `seedgrid.pulse.events` | sem espaços nem curingas `*`/`>` |
+| `PRESENCE_BACKEND` | `memory` | `redis` em multi-réplica |
+
+- Entrega **at-most-once**, sem persistência (NATS core). Aceitável porque o estado de entrega está no Postgres e volta pelo replay.
+- Sem reconexão automática do stream do broker (igual ao Redis): se a conexão cair, o stream termina com `warn`. Mantenha supervisão/restart do serviço.
+
+Exemplo:
+
+```env
+BROKER_PROVIDER=nats
+BROKER_NATS_URL=nats://nats:4222
+PRESENCE_BACKEND=redis
+BROKER_REDIS_URL=redis://redis:6379/0
+DELIVERY_STORE_BACKEND=postgres
+POSTGRES_URL=postgres://<user>:<senha>@<host>:5432/<db>
+```
+
+## RabbitMQ
+
+Exchange **fanout** durável declarada no boot; cada instância cria a **própria fila exclusiva e auto-delete**, ligada ao exchange (fan-out entre instâncias).
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `BROKER_PROVIDER=rabbitmq` | | |
+| `BROKER_RABBITMQ_URL` (fallbacks `RABBITMQ_URL`, `AMQP_URL`) | — | `amqp://user:senha@host:5672/%2f` (vhost codificado). **Obrigatória.** 🔒 |
+| `BROKER_RABBITMQ_EXCHANGE` | `seedgrid.pulse.events` | nome do exchange fanout |
+| `PRESENCE_BACKEND` | `memory` | `redis` em multi-réplica |
+
+- `amqps://` (TLS) está habilitado na crate mas **não foi testado**.
+- Sem reconexão automática do broker; filas exclusivas somem quando a instância cai (comportamento desejado no fan-out).
+
+## Memória
+
+`BROKER_PROVIDER=memory` (padrão; valor desconhecido também cai nele): barramento em processo. Só serve para **uma instância**.
+
+## Readiness
+
+`GET /ready` testa store, broker e presença e responde 200 `READY` ou 503 `NOT_READY` com o detalhe por componente. Para NATS e RabbitMQ a sonda é um `ping` com timeout de 5 s.
+
+## Postgres (store de entregas e plataforma)
+
+`POSTGRES_URL` é o interruptor da plataforma (login, audit, apikeys) e `DELIVERY_STORE_BACKEND=postgres` liga a persistência de entregas. As migrations rodam no boot (`POSTGRES_RUN_MIGRATIONS=true`); cada módulo usa a própria tabela de histórico (`_sqlx_migrations_*`). Qualquer Postgres gerenciado serve. Banco único, separação lógica por `company_id`.
+
+## Como foi verificado
+
+| Item | Evidência |
+|---|---|
+| Redis / Valkey / Dragonfly | `tests/redis_integration.rs`, 5/5 por servidor (Podman, testcontainers) |
+| NATS e RabbitMQ | testes de container nas crates `seedgrid-broker-nats`/`-rabbitmq` (fan-out para 3 subscribers em 2 instâncias, payload malformado sem derrubar o stream, `ping`) e `tests/broker_providers_integration.rs` no Pulse (`build_broker` entrega a todos; `/ready` UP) |
+| Postgres | `tests/postgres_integration.rs` |
+
+Código-fonte dos brokers: `seedgrid-platform/rust/seedgrid-rust-crate-broker` (crates `-spi`, `-memory`, `-redis`, `-nats`, `-rabbitmq`); README da crate descreve o contrato `Broker` (`publish`/`subscribe`).

package/seedgridKB/SeedGrid/Produtos/Pulse/UI/Configuracao.md

@@ -0,0 +1,61 @@
+---
+tags: [seedgrid, produto, pulse, ui, configuracao, variaveis]
+fonte: seedgrid-products/seedgrid-pulse/frontend/seedgrid-pulse-ui (.env.example, src/app/layout.tsx)
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse UI — variáveis de ambiente
+
+Variáveis da **UI**. As do servidor estão em [[SeedGrid/Produtos/Pulse/Servidor/Configuracao|Configuração do servidor]]. Lidas em **runtime** (layout `force-dynamic`): no EasyPanel são env do container, sem rebuild. Visão geral: [[SeedGrid/Produtos/Pulse/UI/Visao-geral|Pulse UI]].
+
+## Conexão com o Pulse
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `SEEDGRID_PULSE_SERVER_BASE_URL` | `http://127.0.0.1:18080` (exemplo do `.env.example`) | Base URL da API Pulse **alcançável pelo navegador**. Única informação de conexão entregue ao client. Fallback legado: `NEXT_PUBLIC_PULSE_BASE_URL`. |
+| `SEEDGRID_PULSE_INTERNAL_BASE_URL` | = a anterior | Base URL usada pelo **servidor da UI** nos proxies (`/api/security/*`, `/api/pulse/messages`). Só precisa quando difere (containers na mesma rede, ex.: `http://seedgrid-pulse:8080`). |
+
+Não existe credencial aqui: nem usuário/senha nem chave. As telas autenticam com o JWT do operador logado.
+
+## Aparência e idioma
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `SEEDGRID_PULSE_DEFAULT_THEME_SEED` | `#16803D` | Cor semente do tema. Legado: `NEXT_PUBLIC_DEFAULT_THEME_SEED`. |
+| `SEEDGRID_PULSE_DEFAULT_THEME_MODE` | `light` | `light` ou `dark`. Legado: `NEXT_PUBLIC_DEFAULT_THEME_MODE`. |
+| `SEEDGRID_PULSE_UI_DEFAULT_LOCALE` | `pt-BR` | Idioma padrão: `en`, `pt-BR`, `pt-PT`, `fr`, `es`. Legado: `NEXT_PUBLIC_PULSE_UI_DEFAULT_LOCALE`. |
+
+Os nomes `NEXT_PUBLIC_*` antigos seguem aceitos como fallback para imagens antigas; prefira os `SEEDGRID_PULSE_*`.
+
+## Auto-refresh (polling, em segundos)
+
+Padrão de todos: **30**.
+
+| Variável | Tela |
+|---|---|
+| `NEXT_PUBLIC_DASHBOARD_REFRESH_SECONDS` | dashboard |
+| `NEXT_PUBLIC_CONNECTIONS_REFRESH_SECONDS` | conexões |
+| `NEXT_PUBLIC_MESSAGES_REFRESH_SECONDS` | mensagens |
+| `NEXT_PUBLIC_BACKLOG_REFRESH_SECONDS` | backlog |
+| `NEXT_PUBLIC_DELIVERIES_REFRESH_SECONDS` | entregas |
+| `NEXT_PUBLIC_DLQ_REFRESH_SECONDS` | DLQ |
+
+> **Não confirmado se mudar estes valores tem efeito.** A UI lê cada uma com `process.env[nome]` dinâmico (`src/lib/ui-refresh.ts`); em componente client o Next só substitui acessos estáticos (`process.env.NEXT_PUBLIC_X`) no build. Se o intervalo não mudar após definir a variável, o padrão de 30 s está valendo. Tratar como pendência a verificar antes de contar com este ajuste.
+
+## Exemplo mínimo de produção
+
+```env
+SEEDGRID_PULSE_SERVER_BASE_URL=https://pulse.<seu-dominio>
+SEEDGRID_PULSE_INTERNAL_BASE_URL=http://seedgrid-pulse:8080
+SEEDGRID_PULSE_UI_DEFAULT_LOCALE=pt-BR
+```
+
+No servidor correspondente: `CORS_ALLOWED_ORIGINS=https://pulse-ui.<seu-dominio>`.
+
+## O que NÃO colocar na UI
+
+- `SEEDGRID_PULSE_SERVER_KEY` (chave de servidor) — a UI não a usa e ela não publica.
+- Qualquer chave `project` ou `client`.
+- Usuário/senha de operador em ENV (removido; o login é pela tela).

package/seedgridKB/SeedGrid/Produtos/Pulse/UI/Visao-geral.md

@@ -0,0 +1,74 @@
+---
+tags: [seedgrid, produto, pulse, ui, nextjs]
+fonte: seedgrid-products/seedgrid-pulse/frontend/seedgrid-pulse-ui
+branch: main
+commit: 9dcbdad
+analisado-em: 2026-10-16
+---
+
+# Pulse UI — visão geral, instalação e execução
+
+Painel web **operacional/administrativo** do Pulse (Next.js + React + `@seedgrid/fe-components`). É um componente separado do servidor: tem imagem, deploy e variáveis próprios. Variáveis: [[SeedGrid/Produtos/Pulse/UI/Configuracao|Configuração da UI]]. Servidor: [[SeedGrid/Produtos/Pulse/Servidor/Instalacao|Pulse (servidor)]].
+
+Voltar: [[SeedGrid/Produtos/Pulse/Visao-geral|Visão geral do Pulse]]
+
+## O que a UI faz
+
+| Área | Telas |
+|---|---|
+| Visão operacional | dashboard, conexões ativas, métricas e agregados |
+| Mensagens | listagem (mais recente primeiro), detalhe (entregas por destinatário e tentativas, com o motivo `result_timeout` traduzido), publicação manual (inclui o campo opcional "Prazo de execução (s)"), **lixeira** (filtro "Na lixeira") |
+| Pendências | backlog, descarte |
+| Falhas | DLQ (reprocessar, limpar), lixeira da DLQ |
+| Entregas | entregas por destinatário |
+| Contas | contas, chaves (criar, rotacionar, revogar), **lixeira de contas** |
+| Segurança | usuários, perfis/permissions, auditoria |
+| Configurações | ajustes de entrega em runtime (retry, TTL, retenção, lixeira) |
+
+Idiomas: en, pt-BR, pt-PT, fr, es.
+
+## Como ela autentica
+
+A UI **não guarda credencial de conexão**. As telas usam o **JWT do operador logado** (login do `security`) e cada ação exige a **permission** correspondente (RBAC) — ver [[SeedGrid/Produtos/Pulse/Autenticacao-e-chaves|Autenticação e chaves]]. Antes existiam `NEXT_PUBLIC_PULSE_BASIC_USER/_PASSWORD`; foram removidas porque o Next as embutia no bundle e elas ficavam legíveis no HTML. A tela de publicação publica **como o operador** (`PULSE_MESSAGE_PUBLISH`), não com a chave de servidor.
+
+## Instalação e execução
+
+Requisitos: Node 22 (a imagem usa `node:22-bookworm-slim`; Next 16, React 19).
+
+```bash
+cd frontend/seedgrid-pulse-ui
+npm install
+npm run dev          # http://127.0.0.1:3000
+```
+
+Variáveis em `.env` (copie de `.env.example`). Com o `podman-compose`/`docker compose` da pasta, a UI sobe em `http://127.0.0.1:13000` junto de Pulse, Postgres e Redis.
+
+Qualidade e testes:
+
+```bash
+npm run lint
+npm run build
+npm test                  # unitários (vitest)
+npm run test:integration  # sobe um mock do Pulse com testcontainers
+```
+
+## Imagem e deploy
+
+- Imagem no GHCR: `ghcr.io/seedgrid/seedgrid-pulse-ui` (Confirmado — `.github/workflows/deploy.yml`).
+- `push` em `main` com mudança em `frontend/**` publica a imagem e chama o webhook do EasyPanel (secret `EASYPANEL_DEPLOY_URL_PULSE_UI`).
+- As variáveis são lidas em **runtime** pelo layout (`force-dynamic`): troca-se de ambiente mudando o env do container, **sem rebuild**.
+
+## Rede: dois endereços do mesmo servidor
+
+| Quem acessa | Variável | Exemplo |
+|---|---|---|
+| **Navegador** do operador | `SEEDGRID_PULSE_SERVER_BASE_URL` | `https://pulse.exemplo.com` |
+| **Servidor da UI** (proxies `/api/security/*`, `/api/pulse/messages`) | `SEEDGRID_PULSE_INTERNAL_BASE_URL` | `http://seedgrid-pulse:8080` (mesma rede de containers) |
+
+Se a UI e o servidor estão em containers na mesma rede, defina os dois; o interno é opcional e, ausente, usa o primeiro.
+
+## Atenção
+
+- A UI não deve receber `SEEDGRID_PULSE_SERVER_KEY`: a chave de servidor não publica e não pertence ao serviço da UI.
+- O servidor precisa de `CORS_ALLOWED_ORIGINS` com a origem da UI.
+- Papel `ADMIN` herda as permissions de lixeira (`PULSE_MESSAGE_DELETE/PURGE`, `PULSE_ACCOUNT_DELETE/PURGE`); outros perfis precisam recebê-las para ver os botões.