> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolutionfoundation.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# v1.0.0-rc5 — Hardening de instalação fresh + Expansão EvoFlow

> **Data de publicação:** 27 de maio de 2026
> **Tipo:** Release Candidate
> **Foco:** Confiabilidade de instalações fresh (correção da race condition no banco compartilhado) + expansão da superfície EvoFlow

A `v1.0.0-rc5` chega **dois dias após a `v1.0.0-rc4`** e concentra dois temas: **eliminar a race condition de primeira inicialização** que travava autenticação em instalações novas (quando todos os serviços subiam em paralelo contra o mesmo Postgres) e **expandir a superfície de EvoFlow** ponta a ponta — worker de backfill de eventos de contato, mirror do schema de eventos em Ruby com validador, cinco novos tipos de nó de fluxo e um `EventSelector` compartilhado no frontend que consome o manifest de eventos.

***

## Destaques

### 🛠️ Confiabilidade de instalação fresh

A imagem da `rc4`, quando subia contra um Postgres vazio com todos os serviços iniciando em paralelo, caía em uma race condition: o `evo-ai-processor-community` (Python/SQLAlchemy) criava um stub `users(id integer)` para suas foreign keys **antes** do `evo-auth-service-community` (Rails) rodar sua migração `InitSchema`. O Rails então pulava silenciosamente seu próprio `create_table :users` (via `if_not_exists: true`), e o schema canônico (PK `uuid`, `mfa_method`, `encrypted_password`, `oauth_access_tokens`) nunca era materializado. Todo login terminava em `PG::UndefinedTable: relation "oauth_access_tokens" does not exist`, cascateando para 503 no CRM.

A correção atua nos dois lados:

* **Processor** — `Base.metadata.create_all()` agora exclui tabelas que pertencem a outros serviços. O processor só materializa as tabelas que ele mesmo possui; o stub `users` simplesmente não é mais emitido.
* **Auth-service** — antes de rodar `InitSchema`, a migração detecta a presença de um `users(id integer)` sem colunas de autenticação (heurística do stub) e dropa a tabela. O schema canônico é então recriado intacto. A operação é idempotente — não faz nada em instalações cuja tabela `users` já está no formato correto.

O incidente que disparou a correção (multimport, 2026-05-27) está documentado em runbook interno; instalações novas em ambientes de serviços compartilhados agora sobem limpas, sem intervenção manual.

### 🔓 Licensing nunca bloqueia uma requisição

O middleware `Licensing::SetupGate` no auth-service foi rebaixado de **gate de enforcement** para **hook puro de observabilidade**. Antes da `rc5`, qualquer indisponibilidade do servidor de licensing (timeout, DNS, 5xx) virava `503 SETUP_REQUIRED` em toda rota fora da bypass list — derrubando o CRM inteiro mesmo após as correções de auth.

A nova implementação:

* Tenta reidratar o contexto de licença se ele estiver inativo.
* Emite o sinal de observabilidade independentemente do resultado.
* **Sempre encaminha a requisição.** O estado da licença vira telemetria; nenhuma requisição é bloqueada por ele.

Complementarmente, a queue `licensing` foi adicionada ao `config/sidekiq.yml`. Antes ela estava ausente, então `SetupJob` e `HeartbeatJob` ficavam silenciosamente enfileirados e nunca executados — resultado: `api_key` não era persistido após o setup e o heartbeat de licenciamento nunca rodava.

### 🌊 Expansão EvoFlow

A `rc5` traz três avanços coordenados na superfície EvoFlow:

* **Mirror Ruby do schema de eventos + `SchemaValidator`** (EVO-1261) — o `EVENT_SCHEMA` canônico do EvoFlow é espelhado no CRM e congelado profundamente. O validador exige UUID estrito, rejeita strings vazias, faz checagem eager de schema e levanta exceção em nomes de evento não registrados. Inclui cast de `inbox_id` / `assigned_by_id` para `:uuid` no fork de leitura.
* **Cinco novos tipos de nó de fluxo** (EVO-1262) — `ActionService` foi consolidado sobre handlers compartilhados de pipeline e mensagem, e cinco novos node types passam por esses handlers. Acompanha harness de paridade, cobertura de specs e README descrevendo o contrato dos handlers compartilhados.
* **`BackfillContactEventsWorker`** — worker Sidekiq que portar eventos históricos de `Message` e `ReportingEvent` para o dataset `contact_events` via `/events/batch` do EvoFlow. Roda em **dry-run por padrão**, na queue `:integrations` com `retry: 2`. Não é disparado automaticamente — operador invoca via `bundle exec rake evo_flow:backfill[<contact_id>]`.

No frontend, o `EventSelector` + `EventPropertiesForm` compartilhados consomem o manifest de eventos em runtime — adicionar ou remover eventos no backend não exige mais editar o código dos nós do flow editor.

***

## Outras mudanças notáveis

### CRM

* **EVO-1243 — Endpoint proxy `/contacts/:id/events` com enrich** — expõe o stream de eventos do contato vindo do EvoFlow através do CRM, enriquecendo cada evento com o contexto que a UI precisa. Inclui guard de STI adicionado durante o hardening de revisão.
* **Evolution Hub — vincular inbox a canal existente** (EVO-1455) — operadores agora podem anexar uma inbox do CRM a um canal preexistente no Evolution Hub, em vez de sempre provisionar um canal novo via o proxy. Inclui nova migração `AddEvolutionHubMetaToChannels`.
* **Evolution Hub — gate legado `EVOLUTION_HUB_URL` removido** — instalações não precisam mais setar a variável de ambiente legada para ativar os fluxos do Hub; a configuração é lida da fonte canônica (UI Admin).
* **Notificações — payload enriquecido** — nome do remetente, avatar, preview da mensagem e `last_activity_at` passam a viajar no payload, permitindo render rich na lista sem round-trip extra.
* **EVO-1419 — Escopo de notificações apertado** — fan-out de inbox saiu do escopo da EVO-1419; o enriquecimento de payload acima é o entregável remanescente. Tipos `pipeline_task_*` declarados explicitamente fora do escopo desta iteração.
* **WhatsApp Cloud — erros de envio passam por `StatusUpdateService`** — erros em tempo de envio no provider Cloud agora seguem o mesmo funil de status-update dos demais providers, mantendo o pipeline de status de mensagem consistente.
* **EvoFlow — entradas faltantes para 5 eventos de conversation** — gap no schema de eventos espelhado, que travava o boot da branch `develop` da rc4, foi fechado. Sem ação de upgrade necessária.
* **Notificações — sender nil em assignment + lookup defensivo de `avatar_url`** — notificações de atribuição não quebram mais quando o usuário que atribuiu é nil; `avatar_url` é buscado defensivamente.

### Frontend

* **Evolution Hub — vincular inbox a canal existente** — fluxo de conexão agora permite anexar inbox a um canal Hub preexistente, não apenas criar um novo a cada vez.
* **Notificações — `NotificationItem` redesenhado** — linha de notificação passa a mostrar nome do remetente, avatar, preview da mensagem e timestamp relativo, substituindo o layout mínimo anterior.
* **Notificações — tempo relativo locale-aware** — `NotificationItem` migrado para helpers de tempo relativo do `date-fns` (com suporte a locale).
* **Notificações — guard no merge de update via WebSocket + testes de reducer** — caminho de merge de updates concorrentes protegido contra estado inconsistente; testes cobrindo o comportamento de remoção ao marcar como lida.
* **Notificações — usar `notification.sender` para nome e avatar** — campo estava sendo lido da fonte errada, causando avatares ausentes ou incorretos.
* **EVO-1421 — Remoção do wrapper inert de floating-panel + aposentadoria do `BaseFlowPanel`** — wrapper era renderizado mas inert (nenhum click ou teclado chegava ao painel); removido junto com o componente legado, agora que os consumidores migraram.
* **EVO-1454 — Contraste WCAG AA no hint de empty-state do `ConditionalNode`** — tonalidade subiu para `text-yellow-700` para atingir contraste AA contra o fundo do nó.
* **i18n — acento espanhol em `channel_message` + limpeza de double blank line** — corrigida tradução espanhola e removida linha em branco dupla no mesmo arquivo de locale.

### Auth Service

* **AuthBridge 1.1.0 — `find_user_by_email` + `sign_in_request`** — dois novos extension points estritos expostos pelo `AuthBridge`. `find_user_by_email` permite que uma implementação Enterprise resolva o usuário a partir de um identity store alternativo (ex.: diretório SSO) antes do lookup local; `sign_in_request` permite injetar lógica custom no sign-in em tempo de request (auditoria, elevação de MFA, provisionamento JIT). Ambos seguem o contrato duck-typed existente com erro explícito em retornos com shape inválido. Documentado em `EXTENSION_POINTS.md`.
* **`add_fk_if_missing` type-aware** (#36) — helper de FK agora inspeciona o tipo da PK referenciada e casa o tipo da coluna, evitando erros de type-mismatch em instalações que migram de uma `users` histórica com PK integer.
* **Downgrade da versão da migração ActiveRecord para 7.1** (#37) — alinha com a versão do Rails efetivamente em uso, evitando erros de boot em `db:migrate` contra ambientes em 7.1.

### Processor

* **Renomeação org `EvolutionAPI` → `evolution-foundation` na documentação** — URLs do GitHub e referências atualizadas. Sem impacto em código.

### Core Service

* **Sem mudanças funcionais** — tag emitida para manter a família CRM Community alinhada em uma única versão de release-candidate.

### Bot Runtime

* **Release de catch-up** — o serviço pulou a `v1.0.0-rc4` (não havia mudança funcional que justificasse tag na época). A `v1.0.0-rc5` realinha a imagem do bot-runtime com o restante da família. O binário Go é **idêntico ao da `v1.0.0-rc3`** — só a tag é nova. Faça pull de `evoapicloud/evo-bot-runtime:1.0.0-rc5` para manter o `docker-compose` consistente.

***

## Notas de atualização

* ✅ **Instalações fresh** — a race condition do `users` table stub está resolvida. Sem intervenção manual em deploys novos: o processor não cria mais o stub, e o auth-service dropa qualquer stub preexistente antes de recriar o schema canônico.
* ⚠️ **Upgrade de instalação quebrada pela race condition da rc4** — se sua instalação caiu no sintoma típico (`relation "oauth_access_tokens" does not exist` em todo login; tabela `users` existe mas com PK `integer` e sem as colunas de auth), execute `DROP TABLE users CASCADE` no Postgres compartilhado **antes** de fazer pull da `rc5` e redeploy. Faça backup antes. O auto-detect da migração cobre o shape comum, mas se seu stub divergir pode ser necessário dropar explicitamente.
* ⚠️ **Licensing não bloqueia mais nenhum endpoint** — se seus runbooks operacionais dependiam do auth-service retornar `503 SETUP_REQUIRED` enquanto o licensing estava inacessível, atualize-os. O sinal agora é um evento de observabilidade, não uma resposta que bloqueia requisições. O estado da licença continua aparecendo em logs e métricas para monitoramento.
* ⚠️ **Sidekiq — queue `licensing` ativa** — a queue `licensing` foi adicionada ao `config/sidekiq.yml`. Se seu deploy usa um `sidekiq.yml` customizado (montado via volume), inclua `- licensing` na lista de queues, senão `SetupJob` e `HeartbeatJob` continuarão silenciosos.
* ⚠️ **CRM — `db:migrate` na atualização** — a migração `AddEvolutionHubMetaToChannels` adiciona colunas Meta do Evolution Hub na tabela `channels`. Idempotente.
* ✅ **EvoFlow — backfill de contact events** — o `BackfillContactEventsWorker` é seguro de rodar em instalações existentes (idempotente). Operadores fazendo upgrade da rc4 devem deixá-lo concluir antes de depender do novo endpoint `/contacts/:id/events`. **Roda em dry-run por padrão**; só executa quando invocado via `bundle exec rake evo_flow:backfill[<contact_id>]`.
* ✅ **EvoFlow — schema sanity** — entradas faltantes para 5 eventos de conversation foram registradas. Sem ação de upgrade.
* 📝 **Bot Runtime — pulou rc4** — a tag salta de `v1.0.0-rc3` direto para `v1.0.0-rc5`. Conteúdo da imagem é o mesmo da `rc3`. Faça pull da tag nova só para manter o compose alinhado.
* 📝 **`EVOLUTION_HUB_URL` não é mais consultada** — se ainda estiver setada no seu `.env`, pode remover. A configuração do Hub é lida da UI Admin.
* 📝 **AuthBridge 1.1.0** — extensão opt-in para Enterprise; consumidores 1.0.x continuam funcionando.

***

## Compatibilidade

* Compatível com deploys da `v1.0.0-rc4` — caminho de upgrade direto (com as ressalvas acima sobre limpeza manual do stub em instalações quebradas).
* Compatível com deploys da `v1.0.0-rc3` — upgrade direto.
* Nenhuma breaking change na API pública.
* Imagens Docker publicadas sob a org `evoapicloud` no Docker Hub. A tag Docker remove o `v` inicial (git `v1.0.0-rc5` → Docker `1.0.0-rc5`).

***

## Referência técnica

* [CHANGELOG — evo-crm-community (umbrella)](https://github.com/evolution-foundation/evo-crm-community/blob/main/CHANGELOG.md)
* [CHANGELOG — evo-ai-crm-community](https://github.com/evolution-foundation/evo-ai-crm-community/blob/main/CHANGELOG.md)
* [CHANGELOG — evo-ai-frontend-community](https://github.com/evolution-foundation/evo-ai-frontend-community/blob/main/CHANGELOG.md)
* [CHANGELOG — evo-auth-service-community](https://github.com/evolution-foundation/evo-auth-service-community/blob/main/CHANGELOG.md)
* [CHANGELOG — evo-ai-processor-community](https://github.com/evolution-foundation/evo-ai-processor-community/blob/main/CHANGELOG.md)
* [CHANGELOG — evo-ai-core-service-community](https://github.com/evolution-foundation/evo-ai-core-service-community/blob/main/CHANGELOG.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.