Feature Flags

Feature Flags são interruptores que controlam o que está ativo na plataforma. Você usa quando quer liberar uma novidade só para um grupo, segurar uma feature instável, aumentar um limite para um time específico, ou desligar um módulo inteiro que sua empresa não usa.

Três escopos no canto superior direito

No alto da tela, o seletor Escopo escolhe pra quem você está editando: Organização (vale para todo mundo), Time (vale só para o time selecionado) ou Usuário (vale só para o usuário). A regra é simples — o escopo mais específico ganha. Se a org diz que algo está ligado, mas o time desliga, o time desliga. Se o time deixa ligado, mas o usuário desliga, fica desligado para aquela pessoa.

Seletor de escopo — Organização, Time ou Usuário

Como o valor final é decidido

Cada flag tem um valor padrão (vem do catálogo da plataforma + plano contratado). Em cima desse padrão, a sua organização pode sobrescrever; em cima da org, o time; em cima do time, o usuário. O sistema busca do mais específico para o mais geral — o primeiro que tem override define o valor.

Usuário → Time → Organização → Plano → Padrão da plataforma

Aba Módulos — liga e desliga áreas inteiras

Cada módulo é uma área grande do produto: Chat, Agentes, Estúdio Criativo, Analytics, Compliance, etc. Quando você desativa um módulo, ele some do menu lateral para quem está naquele escopo. Alguns módulos têm uma contagem ("Analytics — 2 features") indicando que dentro dele há features granulares ajustáveis na próxima aba.

Aba Módulos — toggles para áreas inteiras

Aba Features — recursos específicos dentro dos módulos

Aqui você ajusta funcionalidades pontuais sem desligar o módulo inteiro. Por exemplo: manter o módulo Chat ativo, mas desligar a entrada por voz (chat.voice-input) para um time que ainda não treinou nisso. Cada feature tem um identificador (chat.multi-model, analytics.export, knowledge.ocr) e uma descrição curta.

Aba Features — toggles granulares por funcionalidade

Aba Limites — quotas e rate limits

Em vez de liga/desliga, são valores numéricos. Quantos agentes a organização pode ter, quantos membros, quantas conexões, quantas requisições por minuto na API de auth (proteção contra brute force). Útil para diferenciar planos: a Free fica em 3 agentes, a Pro em 50, a Enterprise sem limite.

Aba Limites — valores numéricos de quotas

Alguns exemplos comuns: limit.maxAgents (quantos agentes a org pode criar), limit.maxKnowledgeBases, limit.maxMembers, limit.rateLimit.auth (requisições por minuto em /v1/auth/* para evitar brute force).

Toda alteração entra em vigor imediatamente — não precisa reiniciar nada. A próxima requisição já vê o novo valor.

Quem pode editar: ADMIN ou SUPERADMIN da organização. Os outros papéis veem o estado mas não conseguem mudar.

Para quem é útil

Admin que gerência rollout — libera nova feature para um time piloto antes da org toda.
Compliance / segurança — desliga módulos que sua empresa não pode usar (ex: voz para certas áreas reguladas).
Suporte / customer success — aumenta um limite específico para um cliente sem mexer no plano dele inteiro.

As Feature Flags são gerenciadas pelo authz-service via /v1/flags/*. O catálogo é estático (vive em libs/shared/domain/src/catalog/feature-flags.catalog.ts no monorepo) e os overrides ficam em 3 níveis: org, team e user.

Tipos de flag

MODULE — boolean, controla se uma área inteira está ativa (ex: module.chat).
FEATURE — boolean granular dentro de módulo (ex: chat.voice-input, analytics.export).
LIMIT — número (ex: limit.maxAgents, limit.rateLimit.auth).
EXPERIMENT — reservado no enum, ainda não usado em produção.

Resolver valor efetivo

Use /v1/flags/definitions para o catálogo (com defaults) e /v1/flags/org para os overrides org-wide. Para o valor efetivo de uma flag para um usuário (já resolvendo a cascata), o backend devolve via JWT na sessão e nos endpoints internos consumidos pelos services.

curl

# Listar todas as definicoes do catalogo (modules + features + limits)
curl https://api.adalink.ai/v1/flags/definitions \
  -H "Authorization: Bearer SEU_TOKEN"

# Ver overrides ativos da organizacao
curl https://api.adalink.ai/v1/flags/org \
  -H "Authorization: Bearer SEU_TOKEN"

Aplicar overrides

Cada nível tem seu endpoint PUT. Para flags booleanas, o body é { "value": true }; para LIMIT, valor numérico. Para limpar um override e voltar ao default da camada de baixo, use DELETE no mesmo path.

curl

# Override da organizacao
curl -X PUT https://api.adalink.ai/v1/flags/org/chat.voice-input \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": false }'

# Override de um time
curl -X PUT https://api.adalink.ai/v1/flags/teams/TEAM_ID/chat.voice-input \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": true }'

# Override de um usuario
curl -X PUT https://api.adalink.ai/v1/flags/users/USER_ID/chat.voice-input \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": false }'

# Limite numerico (LIMIT type)
curl -X PUT https://api.adalink.ai/v1/flags/org/limit.maxAgents \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": 50 }'

# Remover override (volta ao default do plano/catalogo)
curl -X DELETE https://api.adalink.ai/v1/flags/org/chat.voice-input \
  -H "Authorization: Bearer SEU_TOKEN"

Apenas usuários com papel ADMIN ou SUPERADMIN podem criar overrides. Outros papéis recebem 403. Mudanças entram em vigor imediatamente — não há cache TTL no caminho de leitura.