Feature Flags

O Feature Flags separa duas decisões que quase todo time trata como uma só: subir o código e ligar a funcionalidade. O código sobe desligado; ligar vira uma chamada de API, e desligar também.

Na prática, uma financeira que muda a política de análise de proposta não precisa mais escolher entre "vai para os 120 correspondentes de uma vez" e "não vai". Ela liga a política nova para três correspondentes, olha a taxa de aprovação por uma semana, e sobe para 100%. Se der errado às três da tarde de uma sexta, o caminho de volta é POST /disable — não é um rollback de deploy.

Está em produção desde novembro de 2025, roda tenant-scoped sobre o token do IAM e usa o Decision Engine quando a regra de segmentação é complexa demais para uma lista de condições.

O cenário. Um time entrega software para várias empresas clientes na mesma plataforma. Cada cliente tem um apetite de risco diferente, um contrato diferente e um calendário diferente. Toda mudança relevante precisa de uma resposta para "e se quebrar para o cliente grande?".

Sem um interruptor, só existe um caminho — e ele leva a funcionalidade para todo mundo ao mesmo tempo:

flowchart LR
  A["código pronto"] --> B["deploy"]
  B --> C["ligado para 100%<br/>dos clientes"]
  C --> D{"quebrou?"}
  D -->|não| E["ok"]
  D -->|sim| F["rollback de deploy:<br/>pipeline + aprovação + janela"]
  F --> B

O que trava hoje.

• Deploy e release são a mesma decisão. Subir o código significa ligar para todo mundo. Então a barra para subir fica alta, o lote fica grande, e lote grande é exatamente o que aumenta a chance de quebrar.
• A branch de longa duração apodrece. Enquanto a funcionalidade não está "pronta o suficiente", ela vive fora da main. Quando finalmente entra, entra com três semanas de divergência e um merge que ninguém quer revisar.
• O rollback é caro e lento. Reverter um deploy exige pipeline, aprovação e janela. Nesse tempo o cliente está com a funcionalidade quebrada.
• A liberação por cliente vira if no código. Alguém escreve if (organizationId === '...'), o próximo escreve em outro lugar, e seis meses depois ninguém sabe quais clientes têm o quê. Descobrir exige grep.
• As plataformas do mercado cobram pela dimensão errada. Preço por assento penaliza time grande; preço por usuário ativo mensal penaliza o cliente que cresce. Nenhuma das duas dimensões tem relação com o valor que a flag entrega.

O custo de não resolver. Pete Hodgson descreve o mecanismo com precisão na referência clássica sobre o assunto: os release toggles existem para implementar um princípio de entrega contínua.

Sem isso, o custo aparece como lote grande, janela de deploy noturna e rollback caro — e cada um desses é uma escolha que o time faz porque não tem o interruptor, não porque queira.

O interruptor é de operação, não de deploy. Ligar e desligar exige a permissão FEATURE_FLAGS_TOGGLE, separada de FEATURE_FLAGS_UPDATE. Quem opera pode desligar em incidente sem poder alterar a definição da flag.

O mesmo usuário sempre vê o mesmo lado. O rollout percentual usa hash consistente de userId:flagKey (murmurhash v3). Um usuário em 10% continua em 10% quando você sobe para 20% — a experiência não pisca a cada requisição.

flowchart LR
  A["userId + flagKey"] --> B["murmurhash v3"]
  B --> C["balde de 0 a 99"]
  C --> D{"balde < rolloutPercentage?"}
  D -->|sim| E["recebe a variação da regra"]
  D -->|não| F["segue para a próxima regra"]

A regra de segmentação pode ser a sua regra de negócio. Um segmento pode ser uma lista de condições sobre atributos (renda > 5000 AND uf in [SP, RJ]) ou uma tabela DMN completa, executada pelo Decision Engine. Quem escreve a política de crédito consegue escrever quem vê a funcionalidade nova, sem passar por um deploy.

Flag não é booleano. Uma variação carrega qualquer JSON — booleano, string, número, objeto ou lista. Dá para usar a mesma flag para ligar a funcionalidade e para carregar o parâmetro dela (o limite, o texto, a lista de bancos habilitados).

O custo não sobe com o seu cliente. A cobrança é por avaliação e por flag ativa, não por assento nem por usuário ativo mensal.

Panorama

O mercado de feature management se organizou em torno de duas perguntas: por qual dimensão cobrar e onde a flag é avaliada. LaunchDarkly cobra por consumo (conexões de serviço e MAU client-side) e avalia no SDK com streaming. Unleash e GrowthBook cobram por assento e são open source, com avaliação local. Flagsmith e ConfigCat cobram por requisição ou por download de configuração. Todas resolvem bem o caso "SaaS B2C com muitos usuários finais".

Nenhuma delas conhece o seu domínio. Quando a regra de "quem vê" depende de política de crédito, de tipo de contrato ou de uma matriz de decisão do time de risco, todas te devolvem o mesmo primitivo: uma lista de condições sobre atributos que você preenche. O Feature Flags da Catalisa aceita esse mesmo primitivo — e aceita também uma tabela DMN, avaliada pelo Decision Engine que já roda ao lado.

Preços de tabela pública consultados em 2026-08-16: LaunchDarkly, GrowthBook, Flagsmith, Unleash, ConfigCat. Tabelas mudam; confira na data da sua análise.

Nossos diferenciais

1. A segmentação pode ser uma tabela de decisão. Um Segment do tipo DMN carrega XML de DMN e é avaliado pelo Decision Engine via facade. Isso é difícil de copiar não pela técnica, mas porque exige ter um motor DMN operado ao lado — o que um fornecedor de feature flags puro não tem motivo para construir.
2. O tenant não é convenção. O organizationId vem do JWT assinado pelo IAM, e todos os 25 endpoints aplicam requireOrganization. Uma flag de um cliente não é visível para outro porque a consulta ao banco nunca recebe o tenant do corpo da requisição.
3. A cobrança não pune crescimento. Assento penaliza time grande; MAU penaliza cliente que cresce. Avaliação e flag ativa são as duas dimensões que de fato acompanham o valor entregue.

Quando escolher o concorrente

Três situações em que a resposta honesta é "não use o nosso":

Se você precisa de experimentação A/B de verdade — significância estatística, CUPED, teste sequencial, análise sobre o data warehouse — o GrowthBook faz isso hoje e nós não fazemos (§15).

Se o seu produto é B2C com milhões de usuários finais e você precisa de avaliação sem chamada de rede, com SDK que mantém as flags em memória e recebe atualização por streaming, o LaunchDarkly e o Unleash resolvem isso e nós ainda exigimos uma chamada HTTP por avaliação (mitigada por cache de 5 minutos).

Se você quer ambientes separados (dev/homologação/produção) com promoção de flag entre eles, todos os cinco concorrentes têm e nós não temos.

O Feature Flags ganha quando o problema é liberação controlada por cliente empresarial dentro de uma plataforma multi-tenant, especialmente quando a regra de "quem vê" é regra de negócio de verdade — não quando o problema é otimizar conversão de um funil B2C.

Unidade de cobrança

Precificação em definição. Os drivers estão definidos e são estes:

O que dispara custo, na prática

Uma avaliação com cache quente custa uma leitura no Redis. Uma avaliação de segmento SIMPLE custa a mesma leitura mais aritmética em memória. Uma avaliação de segmento DMN custa uma chamada ao Decision Engine — por isso a associação (organização, segmento, usuário) é cacheada por 15 minutos.

flowchart TD
  EV["avaliação chega"] --> C{"flag no cache Redis?"}
  C -->|"sim, 300s de TTL"| BARATO["custo: 1 leitura no Redis"]
  C -->|não| DB["custo: 1 leitura no Redis + 1 consulta ao Postgres"]
  BARATO --> S{"a regra usa segmento?"}
  DB --> S
  S -->|não| PCT["rollout percentual:<br/>só aritmética em memória"]
  S -->|SIMPLE| MEM["condições avaliadas em memória"]
  S -->|DMN| M{"associação no cache?"}
  M -->|"sim, 900s de TTL"| MEM2["custo: 1 leitura no Redis"]
  M -->|não| DE["custo: 1 chamada de rede<br/>ao Decision Engine"]

Comparação de custo

Cenário nomeado: plataforma B2B com 12 pessoas mexendo em flags, 80 empresas clientes, cerca de 40 mil usuários finais ativos por mês e 6 serviços consultando flags.

Estimativa a partir das tabelas públicas consultadas em 2026-08-16, aplicando a conta direta do plano de entrada. Não é proposta comercial: descontos anuais, negociação e mudança de tabela alteram o resultado. A coluna Catalisa está em definição e não deve ser apresentada com número.

ROI

O retorno não está na linha de licença — GrowthBook self-hosted tem custo de licença zero. Está em dois lugares:

• O incidente que não acontece. Cada release que sobe para 5% antes de 100% é uma chance de descobrir o problema com 5% do impacto. Numa operação de crédito, a diferença entre "propostas de 120 correspondentes com política errada" e "propostas de 3 correspondentes" é a diferença entre um incidente e um ajuste.
• O if que não é escrito. Cada liberação por cliente que vira segmento em vez de condicional no código é uma linha que não precisa de deploy para mudar, e um lugar a menos para procurar quando alguém pergunta quem tem o quê.

Camadas e caminho da requisição

flowchart TD
  HTTP["HTTP"] --> APP

  subgraph APP["Hono app — basePath /feature-flags"]
    R1["/api/v1/flags — flagsRouter (7)"]
    R2["/api/v1/flags/:flagId/targeting-rules — targetingRulesRouter (6)"]
    R3["/api/v1/flags/:flagId/overrides — overridesRouter (4)"]
    R4["/api/v1/segments — segmentsRouter (5)"]
    R5["/api/v1/evaluate — evaluateRouter (3)"]
    R6["/health"]
  end

  APP -->|"authMiddleware → requirePermission → requireOrganization<br/>Zod parse → ResultAsync&lt;T, AppError&gt;"| SVC

  subgraph SVC["services/"]
    S1["FlagService — CRUD, enable/disable, valida variações"]
    S2["SegmentService — CRUD de segmentos"]
    S3["EvaluationService — precedência, cache, log amostrado"]
    S4["SegmentMembershipService — SIMPLE em memória · DMN via facade"]
  end

  SVC --> REPO["repositories/<br/>Prisma<br/>schema flags"]
  SVC --> REDIS["Redis<br/>ff:flag:{org}:{key} — TTL 300s<br/>ff:membership:{org}:{seg}:{user} — TTL 900s"]
  SVC --> DEF["DecisionEngineFacade<br/>local = TypeDI<br/>remote = HTTP"]

Precedência de avaliação

A ordem importa e é fixa. Ela vale para evaluateFlag, evaluateBatch e evaluateAll — as três passam pelo mesmo evaluateFlagInternal.

flowchart TD
  IN["POST /feature-flags/api/v1/evaluate/:flagKey<br/>context: userId, attributes"] --> C0["busca a flag: cache ff:flag:{org}:{key}, senão Postgres"]
  C0 --> Q1{"1 · a flag existe nesta organização?"}
  Q1 -->|não| E404["404 NOT_FOUND"]
  Q1 -->|sim| Q2{"2 · a defaultVariation existe na lista de variações?"}
  Q2 -->|não| E500["500 INTERNAL — dado inconsistente"]
  Q2 -->|sim| Q3{"3 · status igual a DISABLED?"}
  Q3 -->|sim| RDIS["variação padrão · reason DISABLED"]
  Q3 -->|não| Q4{"4 · há userId no contexto e override para ele?"}
  Q4 -->|sim| ROVR["variação do override · reason OVERRIDE"]
  Q4 -->|não| Q5{"5 · a flag tem alguma regra de targeting?"}
  Q5 -->|não| RDEF1["variação padrão · reason DEFAULT"]
  Q5 -->|sim| LOOP["6 · percorre as regras por priority ASC<br/>menor priority primeiro"]
  LOOP --> Q6{"6a · todos os segmentos da regra casam?<br/>lógica AND · regra sem segmento casa com todos"}
  Q6 -->|não| NEXT["próxima regra"]
  Q6 -->|sim| Q7{"6b · rolloutPercentage cobre este usuário?<br/>sem userId, regra com rollout menor que 100 é pulada"}
  Q7 -->|não| NEXT
  Q7 -->|sim| RMATCH["variação da regra · reason RULE_MATCH<br/>com matchedRuleId e matchedSegmentIds"]
  NEXT --> Q8{"acabaram as regras?"}
  Q8 -->|não| LOOP
  Q8 -->|sim| RDEF2["7 · nenhuma regra casou<br/>variação padrão · reason DEFAULT"]

Decisões não óbvias

Flag nasce DISABLED. FlagService.createFlag força status: 'DISABLED' mesmo que o corpo peça outra coisa. Criar não pode ser o mesmo ato de ligar — senão o primeiro POST de um script de setup vira um release não intencional.

Cache de 300s na flag, 900s na associação de segmento. A flag muda com frequência (é o ponto dela), então 5 minutos é o teto tolerado entre desligar e o efeito aparecer, e toda mutação invalida a chave explicitamente. A associação de um usuário a um segmento muda pouco e custa caro quando é DMN (chamada de rede ao Decision Engine), então 15 minutos compensa.

Bucketing por murmurhash.v3(userId:flagKey) % 100. Hash não criptográfico, rápido e uniforme o suficiente para 100 baldes. O flagKey entra no hash de propósito: sem ele, o mesmo usuário cairia sempre no mesmo balde em todas as flags, e um usuário azarado ficaria fora de todo rollout de 10% da plataforma para sempre.

Sem userId no contexto, regra com rollout < 100% é pulada. Não há como fazer bucketing consistente sem identificador. A alternativa — sortear — daria resposta diferente a cada requisição para o mesmo usuário, que é o pior comportamento possível numa flag. Pular é conservador e previsível.

flowchart LR
  U{"há userId no contexto?"}
  U -->|sim| H["murmurhash.v3 de userId e flagKey<br/>módulo 100, dá um balde de 0 a 99"]
  H --> C{"balde menor que rolloutPercentage?"}
  C -->|sim| IN["a regra casa"]
  C -->|não| OUT["a regra é pulada"]
  U -->|não| SK["regra com rollout abaixo de 100% é pulada<br/>sortear daria resposta diferente a cada requisição"]

Log de avaliação com amostragem de 10%, fire-and-forget. Registrar 100% transformaria uma leitura de cache num INSERT. A amostragem preserva a distribuição por variação e por motivo, que é o que importa para diagnóstico, sem transformar o caminho quente em escrita.

evaluate-batch e evaluate-all não usam o cache de flag. Elas buscam direto no banco (findManyByKeys, findAllEnabled), porque o cache é indexado por chave individual. São endpoints de bootstrap, chamados uma vez por sessão — não são o caminho quente.

Segmentos de uma regra são combinados com AND. Uma regra com dois segmentos exige pertencer aos dois. Para OR, crie duas regras com a mesma variação, ou use operator: "OR" dentro das condições de um único segmento SIMPLE.

Monolito vs. standalone

Em monolito, o SegmentMembershipService alcança o Decision Engine por chamada direta no container TypeDI. Em standalone — o modo usado em produção — a mesma interface IDecisionEngineFacade faz HTTP para MODULE_DECISION_ENGINE_URL. O serviço de feature flags não sabe a diferença.

flowchart LR
  SMS["SegmentMembershipService"] --> IF["IDecisionEngineFacade"]
  IF -->|"DEPLOYMENT_MODE=monolith"| LOCAL["chamada direta no container TypeDI"]
  IF -->|"DEPLOYMENT_MODE=standalone"| REMOTE["HTTP para MODULE_DECISION_ENGINE_URL"]

Nos dois modos o BB expõe apenas HTTP: não há consumidor de fila nem job agendado no main.ts.

Glossário

Modelo de dados

Schema flags no PostgreSQL.

erDiagram
  FeatureFlag ||--o{ FlagTargetingRule : "tem regras"
  FeatureFlag ||--o{ FlagOverride : "tem fixações"
  FeatureFlag ||--o{ FlagEvaluationLog : "gera avaliações amostradas"
  FlagTargetingRule ||--o{ TargetingRuleSegment : "aponta para"
  Segment ||--o{ TargetingRuleSegment : "é usado por"
  FeatureFlag {
    uuid id
    uuid organizationId
    string key "único por organização"
    enum status "ENABLED ou DISABLED"
    jsonb variations
    string defaultVariation
    datetime deletedAt "exclusão lógica"
  }
  Segment {
    uuid id
    uuid organizationId
    string key "único por organização"
    enum ruleType "SIMPLE ou DMN"
    text ruleContent
    string decisionId
    datetime deletedAt "exclusão lógica"
  }
  FlagTargetingRule {
    uuid id
    uuid flagId
    int priority "menor avalia primeiro"
    string variationKey
    int rolloutPercentage
    text inlineDmnRule "aceito, não avaliado"
  }
  TargetingRuleSegment {
    uuid ruleId "chave composta"
    uuid segmentId "chave composta"
  }
  FlagOverride {
    uuid id
    uuid flagId
    string userId "único junto com flagId"
    string variationKey
  }
  FlagEvaluationLog {
    uuid id
    string flagKey
    string variationKey
    string reason
    jsonb context
    int evaluationTimeMs
  }

Enumerações

Ciclo de vida da flag

stateDiagram-v2
  [*] --> DISABLED : "POST /flags — nasce aqui sempre"
  DISABLED --> ENABLED : "POST /:flagId/enable"
  ENABLED --> DISABLED : "POST /:flagId/disable"
  DISABLED --> Excluida : "DELETE /:flagId"
  ENABLED --> Excluida : "DELETE /:flagId"
  Excluida --> [*]
  state "deletedAt diferente de null" as Excluida
  note right of Excluida
    Exclusão lógica: a linha fica no banco,
    a flag some das consultas e do cache.
  end note

Só existem dois estados. Não há rascunho, agendamento nem arquivamento.

Operadores de condição em segmento SIMPLE

O ruleContent de um segmento SIMPLE é um JSON { operator: "AND" | "OR", conditions: [...] }. Cada condição é { attribute, operator, value }:

O atributo userId é especial: quando condition.attribute === "userId", o valor comparado é o context.userId, não context.attributes.userId.

Prefixo real: /feature-flags. Em staging, a base é https://flags.bb.stg.catalisa.app.

Todos os 25 endpoints exigem authMiddleware (Bearer JWT do IAM) e requireOrganization — token sem organizationId recebe 403 antes de chegar na regra de negócio.

flowchart LR
  BASE["/feature-flags/api/v1"] --> F["/flags — 7 endpoints"]
  BASE --> S["/segments — 5 endpoints"]
  BASE --> EV["/evaluate — 3 endpoints"]
  F --> TR["/flags/:flagId/targeting-rules — 6 endpoints"]
  F --> OV["/flags/:flagId/overrides — 4 endpoints"]
  TR -.->|"segmentIds"| S
  EV -.->|"lê flag, regras e overrides"| F

Flags — /feature-flags/api/v1/flags

Segmentos — /feature-flags/api/v1/segments

Regras de targeting — /feature-flags/api/v1/flags/:flagId/targeting-rules

Overrides — /feature-flags/api/v1/flags/:flagId/overrides

Avaliação — /feature-flags/api/v1/evaluate

⚠️ -batch e -all estão registradas com um caminho que não é alcançável na prática. Os handlers são declarados como '-batch' e '-all' sem barra inicial, o que o Hono resolve para /feature-flags/api/v1/evaluate/-batch e /-all. Como POST /:flagKey é registrada antes, ela captura essas duas rotas primeiro e trata -batch como se fosse a key de uma flag — o resultado é 404 Feature flag not found. Use POST /feature-flags/api/v1/evaluate/:flagKey uma vez por flag até isso ser corrigido. Ver §15.

Saúde

POST /feature-flags/api/v1/flags

Cria uma flag. Aceita corpo plano ou envelope JSON:API ({ "data": { "attributes": { ... } } }).

Request

{
  "key": "politica-aceite-v2",
  "name": "Política de aceite v2",
  "description": "Novo corte de score na esteira de consignado",
  "variations": [
    { "key": "v1", "value": false },
    { "key": "v2", "value": true }
  ],
  "defaultVariation": "v1"
}

{
  "key": "politica-aceite-v2",
  "name": "Política de aceite v2",
  "description": "Novo corte de score na esteira de consignado",
  "variations": [
    { "key": "v1", "value": false },
    { "key": "v2", "value": true }
  ],
  "defaultVariation": "v1"
}

Resposta 201

{
  "data": {
    "type": "feature-flags",
    "id": "8f2c1f6e-1c2b-4a0f-9d1a-3b7c5e9a0011",
    "links": { "self": "/api/v1/flags/8f2c1f6e-1c2b-4a0f-9d1a-3b7c5e9a0011" },
    "attributes": {
      "key": "politica-aceite-v2",
      "name": "Política de aceite v2",
      "status": "DISABLED",
      "variations": [{ "key": "v1", "value": false }, { "key": "v2", "value": true }],
      "defaultVariation": "v1"
    }
  }
}

{
  "data": {
    "type": "feature-flags",
    "id": "8f2c1f6e-1c2b-4a0f-9d1a-3b7c5e9a0011",
    "links": { "self": "/api/v1/flags/8f2c1f6e-1c2b-4a0f-9d1a-3b7c5e9a0011" },
    "attributes": {
      "key": "politica-aceite-v2",
      "name": "Política de aceite v2",
      "status": "DISABLED",
      "variations": [{ "key": "v1", "value": false }, { "key": "v2", "value": true }],
      "defaultVariation": "v1"
    }
  }
}

O status volta DISABLED mesmo se você mandar outra coisa — é intencional (§7). O links.self omite o prefixo /feature-flags; trate-o como caminho relativo ao módulo, não como URL montável (§15).

Erros

POST /feature-flags/api/v1/evaluate/:flagKey

O endpoint quente. O :flagKey é a key da flag, não o UUID.

Request — corpo opcional; sem corpo, o contexto é vazio.

{
  "context": {
    "userId": "cli-88213",
    "attributes": {
      "correspondenteId": "corr-014",
      "renda": 7200,
      "uf": "SP"
    }
  }
}

{
  "context": {
    "userId": "cli-88213",
    "attributes": {
      "correspondenteId": "corr-014",
      "renda": 7200,
      "uf": "SP"
    }
  }
}

Resposta 200

{
  "data": {
    "flagKey": "politica-aceite-v2",
    "value": true,
    "variationKey": "v2",
    "reason": "RULE_MATCH",
    "matchedRuleId": "b1c2d3e4-0000-4000-8000-000000000001",
    "matchedSegmentIds": ["a9f0e1d2-0000-4000-8000-000000000002"]
  }
}

{
  "data": {
    "flagKey": "politica-aceite-v2",
    "value": true,
    "variationKey": "v2",
    "reason": "RULE_MATCH",
    "matchedRuleId": "b1c2d3e4-0000-4000-8000-000000000001",
    "matchedSegmentIds": ["a9f0e1d2-0000-4000-8000-000000000002"]
  }
}

matchedRuleId e matchedSegmentIds só aparecem quando reason é RULE_MATCH. Use reason para diagnóstico: DEFAULT quando nenhuma regra casou, DISABLED quando a flag está desligada, OVERRIDE quando há fixação para o userId.

Erros

POST /feature-flags/api/v1/flags/:flagId/targeting-rules

Request

{
  "name": "Piloto com 3 correspondentes",
  "priority": 0,
  "variationKey": "v2",
  "rolloutPercentage": 100,
  "segmentIds": ["a9f0e1d2-0000-4000-8000-000000000002"]
}

{
  "name": "Piloto com 3 correspondentes",
  "priority": 0,
  "variationKey": "v2",
  "rolloutPercentage": 100,
  "segmentIds": ["a9f0e1d2-0000-4000-8000-000000000002"]
}

Regra sem segmentIds e com rolloutPercentage: 10 é o padrão de rollout percentual puro: casa com todo mundo e depois filtra 10% por hash.

Erros

POST /feature-flags/api/v1/flags/:flagId/overrides

{ "userId": "cli-88213", "variationKey": "v2" }

{ "userId": "cli-88213", "variationKey": "v2" }

Override vence tudo, inclusive rollout percentual. Um userId só pode ter um override por flag — o segundo devolve 409.

Do zero à primeira flag ligada para 10% dos usuários. Credenciais de staging conforme AMBIENTES.md.

O caminho tem sete passos e termina com a flag desligada de novo — de propósito, para você ver os dois lados do interruptor:

flowchart LR
  P1["1 · autenticar"] --> P2["2 · criar a flag"]
  P2 --> P3["3 · avaliar: nasce DISABLED"]
  P3 --> P4["4 · criar a regra de 10%"]
  P4 --> P5["5 · ligar a flag"]
  P5 --> P6["6 · ver o rollout acontecendo"]
  P6 --> P7["7 · desligar"]

1. Autenticar no IAM

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

export FF=https://flags.bb.stg.catalisa.app/feature-flags/api/v1

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

export FF=https://flags.bb.stg.catalisa.app/feature-flags/api/v1

Resposta esperada: $TOKEN preenchido com um JWT que carrega organizationId e as permissões FEATURE_FLAGS_*. Se vier vazio, a autenticação falhou e todos os passos seguintes respondem 401.

2. Criar a flag

FLAG_ID=$(curl -s -X POST $FF/flags \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "key": "checkout-novo",
    "name": "Checkout novo",
    "variations": [{"key":"off","value":false},{"key":"on","value":true}],
    "defaultVariation": "off"
  }' | jq -r '.data.id')

echo "$FLAG_ID"

FLAG_ID=$(curl -s -X POST $FF/flags \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "key": "checkout-novo",
    "name": "Checkout novo",
    "variations": [{"key":"off","value":false},{"key":"on","value":true}],
    "defaultVariation": "off"
  }' | jq -r '.data.id')

echo "$FLAG_ID"

8f2c1f6e-1c2b-4a0f-9d1a-3b7c5e9a0011

8f2c1f6e-1c2b-4a0f-9d1a-3b7c5e9a0011

3. Confirmar que ela nasce desligada

curl -s -X POST $FF/evaluate/checkout-novo \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"context":{"userId":"user-1"}}' | jq

curl -s -X POST $FF/evaluate/checkout-novo \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"context":{"userId":"user-1"}}' | jq

{ "data": { "flagKey": "checkout-novo", "value": false,
            "variationKey": "off", "reason": "DISABLED" } }

{ "data": { "flagKey": "checkout-novo", "value": false,
            "variationKey": "off", "reason": "DISABLED" } }

4. Criar a regra de rollout de 10%

curl -s -X POST $FF/flags/$FLAG_ID/targeting-rules \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Rollout 10%","priority":0,"variationKey":"on","rolloutPercentage":10}' | jq

curl -s -X POST $FF/flags/$FLAG_ID/targeting-rules \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Rollout 10%","priority":0,"variationKey":"on","rolloutPercentage":10}' | jq

{
  "data": {
    "type": "targeting-rules",
    "id": "b1c2d3e4-0000-4000-8000-000000000001",
    "attributes": {
      "name": "Rollout 10%",
      "priority": 0,
      "variationKey": "on",
      "rolloutPercentage": 10,
      "segmentIds": []
    }
  }
}

{
  "data": {
    "type": "targeting-rules",
    "id": "b1c2d3e4-0000-4000-8000-000000000001",
    "attributes": {
      "name": "Rollout 10%",
      "priority": 0,
      "variationKey": "on",
      "rolloutPercentage": 10,
      "segmentIds": []
    }
  }
}

Sem segmentIds, a regra casa com todo mundo e o filtro fica todo por conta do percentual.

5. Ligar a flag

curl -s -X POST $FF/flags/$FLAG_ID/enable \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes.status'

curl -s -X POST $FF/flags/$FLAG_ID/enable \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes.status'

"ENABLED"

"ENABLED"

6. Ver o rollout acontecendo

for i in $(seq 1 30); do
  curl -s -X POST $FF/evaluate/checkout-novo \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "{\"context\":{\"userId\":\"user-$i\"}}" | jq -r '.data.variationKey'
done | sort | uniq -c

for i in $(seq 1 30); do
  curl -s -X POST $FF/evaluate/checkout-novo \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "{\"context\":{\"userId\":\"user-$i\"}}" | jq -r '.data.variationKey'
done | sort | uniq -c

     27 off
      3 on

     27 off
      3 on

Espere algo perto de 3 respostas on e 27 off. Rode de novo: os mesmos usuários caem do mesmo lado, porque o balde vem de murmurhash(userId:flagKey).

7. Desligar

curl -s -X POST $FF/flags/$FLAG_ID/disable \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes.status'

curl -s -X POST $FF/flags/$FLAG_ID/disable \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes.status'

O efeito é imediato para quem consulta depois da invalidação de cache, que acontece na mesma chamada.

Subir um rollout de 5% para 100% com segurança

Objetivo. Aumentar a exposição em degraus sem trocar quem já está dentro.

Cada degrau só acrescenta usuários — quem já estava dentro continua dentro, porque o balde não muda:

flowchart LR
  A["5%"] --> B["10%"]
  B --> C["25%"]
  C --> D["50%"]
  D --> E["100%"]
  A -.->|"o conjunto só cresce"| E
  F["reduzir o percentual"] -.->|"remove quem já viu a novidade"| G["prefira desligar a flag"]

1. Descobrir o id da regra

RULE_ID=$(curl -s $FF/flags/$FLAG_ID/targeting-rules \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data[0].id')

echo "$RULE_ID"

RULE_ID=$(curl -s $FF/flags/$FLAG_ID/targeting-rules \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data[0].id')

echo "$RULE_ID"

b1c2d3e4-0000-4000-8000-000000000001

b1c2d3e4-0000-4000-8000-000000000001

2. Subir de degrau em degrau, observando métricas entre eles

for pct in 5 10 25 50 100; do
  curl -s -X PATCH $FF/flags/$FLAG_ID/targeting-rules/$RULE_ID \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "{\"rolloutPercentage\": $pct}" | jq -r '.data.attributes.rolloutPercentage'
  # observe métricas antes do próximo degrau
done

for pct in 5 10 25 50 100; do
  curl -s -X PATCH $FF/flags/$FLAG_ID/targeting-rules/$RULE_ID \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "{\"rolloutPercentage\": $pct}" | jq -r '.data.attributes.rolloutPercentage'
  # observe métricas antes do próximo degrau
done

5
10
25
50
100

5
10
25
50
100

Armadilhas.

• Não mude a key da flag no meio do rollout. O balde é hash(userId:flagKey); trocar a key reembaralha todo mundo e usuários que estavam dentro saem.
• Aumentar o percentual é seguro (o conjunto só cresce); diminuir remove usuários que já viram a funcionalidade nova. Se isso for inaceitável, desligue a flag em vez de reduzir o percentual.
• Quem chama sem context.userId nunca entra num rollout parcial e sempre recebe a variação padrão. Confira que o seu chamador manda o identificador.

Segmentar por atributo com regra SIMPLE

Objetivo. Liberar só para clientes de SP com renda acima de 5 mil.

São três peças, montadas nesta ordem:

flowchart LR
  RC["ruleContent<br/>string com JSON dentro"] --> SEG["segmento SIMPLE<br/>sp-renda-alta"]
  SEG --> RULE["regra de targeting<br/>segmentIds: [sp-renda-alta]"]
  RULE --> FLAG["flag"]
  CTX["context.attributes<br/>uf, renda"] -.->|"comparados na avaliação"| RC

1. Montar o ruleContent

# O ruleContent é uma STRING com JSON dentro. Monte com jq para não errar o escape.
REGRA=$(jq -nc '{
  operator: "AND",
  conditions: [
    { attribute: "uf",    operator: "eq", value: "SP"  },
    { attribute: "renda", operator: "gt", value: 5000  }
  ]
}')

echo "$REGRA"

# O ruleContent é uma STRING com JSON dentro. Monte com jq para não errar o escape.
REGRA=$(jq -nc '{
  operator: "AND",
  conditions: [
    { attribute: "uf",    operator: "eq", value: "SP"  },
    { attribute: "renda", operator: "gt", value: 5000  }
  ]
}')

echo "$REGRA"

{"operator":"AND","conditions":[{"attribute":"uf","operator":"eq","value":"SP"},{"attribute":"renda","operator":"gt","value":5000}]}

{"operator":"AND","conditions":[{"attribute":"uf","operator":"eq","value":"SP"},{"attribute":"renda","operator":"gt","value":5000}]}

2. Criar o segmento

SEG_ID=$(jq -nc --arg rc "$REGRA" '{
    key: "sp-renda-alta",
    name: "SP com renda acima de 5k",
    ruleType: "SIMPLE",
    ruleContent: $rc
  }' \
  | curl -s -X POST $FF/segments \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d @- | jq -r '.data.id')

echo "$SEG_ID"

SEG_ID=$(jq -nc --arg rc "$REGRA" '{
    key: "sp-renda-alta",
    name: "SP com renda acima de 5k",
    ruleType: "SIMPLE",
    ruleContent: $rc
  }' \
  | curl -s -X POST $FF/segments \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
      -d @- | jq -r '.data.id')

echo "$SEG_ID"

a9f0e1d2-0000-4000-8000-000000000002

a9f0e1d2-0000-4000-8000-000000000002

3. Apontar uma regra da flag para o segmento

jq -nc --arg seg "$SEG_ID" '{
    name: "SP renda alta", priority: 0,
    variationKey: "on", segmentIds: [$seg]
  }' \
| curl -s -X POST $FF/flags/$FLAG_ID/targeting-rules \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d @-

jq -nc --arg seg "$SEG_ID" '{
    name: "SP renda alta", priority: 0,
    variationKey: "on", segmentIds: [$seg]
  }' \
| curl -s -X POST $FF/flags/$FLAG_ID/targeting-rules \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d @-

A resposta é a mesma da criação de regra em §9: 201 com data.attributes.segmentIds já preenchido com o SEG_ID.

Armadilhas.

• ruleContent é uma string com JSON dentro, não um objeto. Errar isso gera 500 na avaliação, não 400 na criação — a validação do conteúdo acontece na hora de avaliar.
• Comparadores numéricos (gt, gte, lt, lte) devolvem false quando qualquer lado não é número. "renda": "7200" (string) nunca passa em gt: 5000.
• O ruleType não pode ser alterado depois: o schema de PATCH de segmento não aceita o campo. Para mudar de SIMPLE para DMN, crie outro segmento.
• Mudar ruleContent invalida o cache de associação daquele segmento, mas a propagação pode levar até 15 minutos para usuários já avaliados.

Segmentar com uma tabela DMN

Objetivo. Usar uma matriz de decisão do time de risco como critério de quem vê a funcionalidade.

sequenceDiagram
  participant App as Aplicação
  participant FF as Feature Flags
  participant R as Redis
  participant DE as Decision Engine
  App->>FF: "POST /evaluate/:flagKey com context"
  FF->>R: "GET ff:membership:{org}:{seg}:{user}"
  alt "associação em cache"
    R-->>FF: "true ou false"
  else "cache frio"
    FF->>DE: "execute(dmnXml, { userId, ...attributes })"
    DE-->>FF: "{ isMember: true }"
    FF->>R: "SETEX por 900s"
  end
  FF-->>App: "variação e reason"

1. Criar o segmento DMN

curl -s -X POST $FF/segments \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "key": "elegivel-piloto",
    "name": "Elegível ao piloto (DMN)",
    "ruleType": "DMN",
    "ruleContent": "<?xml version=\"1.0\"?><definitions ...>...</definitions>"
  }'

curl -s -X POST $FF/segments \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "key": "elegivel-piloto",
    "name": "Elegível ao piloto (DMN)",
    "ruleType": "DMN",
    "ruleContent": "<?xml version=\"1.0\"?><definitions ...>...</definitions>"
  }'

2. Nomear a saída da tabela para que o BB a entenda

O SegmentMembershipService manda { userId, ...attributes } como entrada da decisão e interpreta a saída nesta ordem:

Armadilhas.

• Nomeie a saída da sua tabela DMN como isMember. É o primeiro nome procurado e o único que deixa a intenção explícita para quem ler a tabela depois.
• Segmento DMN sem ruleContent sempre casa (devolve true). Um segmento DMN vazio libera para todos — é o oposto do que se espera de uma regra restritiva.
• Cada avaliação DMN não cacheada é uma chamada de rede ao Decision Engine. Os segmentos de uma flag são avaliados em sequência, não em paralelo, de propósito: em paralelo, uma flag com cinco segmentos DMN viraria cinco chamadas simultâneas por requisição.
• Se o Decision Engine estiver fora do ar, a avaliação da flag falha com 500 em vez de cair na variação padrão. Para caminho crítico, prefira segmento SIMPLE.

Descobrir por que um usuário está vendo a variação errada

Objetivo. Diagnóstico em quatro consultas.

O campo reason da resposta já diz por onde começar — ele é o passo da precedência em que a avaliação parou:

flowchart TD
  R{"reason da resposta"}
  R -->|DISABLED| D["a flag está desligada<br/>POST /:flagId/enable"]
  R -->|OVERRIDE| O["existe fixação para o userId<br/>apague o override"]
  R -->|DEFAULT| DF["nenhuma regra casou<br/>confira os atributos enviados<br/>contra as condições do segmento"]
  R -->|"RULE_MATCH com a variação errada"| RM["confira priority: menor número ganha<br/>e a primeira que casa encerra a avaliação"]
  DF --> U{"você mandou context.userId?"}
  U -->|não| SEMID["regra com rollout menor que 100 é pulada"]
  U -->|sim| ATR["compare atributo por atributo, com atenção ao tipo"]

1. Ver o que a avaliação responde e, principalmente, por quê

curl -s -X POST $FF/evaluate/checkout-novo \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"context":{"userId":"cli-88213","attributes":{"uf":"SP","renda":7200}}}' | jq

curl -s -X POST $FF/evaluate/checkout-novo \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"context":{"userId":"cli-88213","attributes":{"uf":"SP","renda":7200}}}' | jq

{ "data": { "flagKey": "checkout-novo", "value": false,
            "variationKey": "off", "reason": "DEFAULT" } }

{ "data": { "flagKey": "checkout-novo", "value": false,
            "variationKey": "off", "reason": "DEFAULT" } }

2. Conferir se a flag está ligada

curl -s $FF/flags/$FLAG_ID -H "Authorization: Bearer $TOKEN" | jq '.data.attributes.status'

curl -s $FF/flags/$FLAG_ID -H "Authorization: Bearer $TOKEN" | jq '.data.attributes.status'

"ENABLED"

"ENABLED"

3. Conferir se existe override para este usuário

curl -s "$FF/flags/$FLAG_ID/overrides" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | select(.attributes.userId=="cli-88213")'

curl -s "$FF/flags/$FLAG_ID/overrides" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | select(.attributes.userId=="cli-88213")'

Saída vazia significa que não há override — se reason veio OVERRIDE, é aqui que a explicação aparece.

4. Conferir em que ordem as regras são avaliadas

curl -s $FF/flags/$FLAG_ID/targeting-rules -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {priority: .attributes.priority, variationKey: .attributes.variationKey,
                   rollout: .attributes.rolloutPercentage, segs: .attributes.segmentIds}'

curl -s $FF/flags/$FLAG_ID/targeting-rules -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {priority: .attributes.priority, variationKey: .attributes.variationKey,
                   rollout: .attributes.rolloutPercentage, segs: .attributes.segmentIds}'

{ "priority": 0, "variationKey": "on", "rollout": 10, "segs": [] }

{ "priority": 0, "variationKey": "on", "rollout": 10, "segs": [] }

Ordem de diagnóstico, na mesma sequência da precedência: reason = DISABLED → a flag está desligada. OVERRIDE → apague o override. DEFAULT → nenhuma regra casou; confira os atributos que você mandou contra as condições do segmento. RULE_MATCH com a variação errada → confira priority: menor número ganha, e a primeira que casa encerra a avaliação.

Fixar uma variação para um cliente que abriu chamado

Objetivo. Tirar um usuário específico da funcionalidade nova sem mexer no rollout de todos os outros.

curl -s -X POST $FF/flags/$FLAG_ID/overrides \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"userId":"cli-88213","variationKey":"off"}'

curl -s -X POST $FF/flags/$FLAG_ID/overrides \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"userId":"cli-88213","variationKey":"off"}'

A partir da próxima avaliação, esse userId recebe reason: "OVERRIDE" — o override vence regra, segmento e rollout.

Armadilhas. Override não expira. Não há campo de validade nem limpeza automática — vira dívida silenciosa. Trate a lista de overrides como fila de suporte e revise periodicamente com GET /flags/:flagId/overrides.

flowchart TD
  IAM["IAM"] -->|"Bearer JWT — organizationId + permissões"| FF["Feature Flags<br/>avaliação · precedência · cache"]
  FF -->|"segmento ruleType=DMN<br/>execute(dmnXml, { userId, ...attrs })"| DE["Decision Engine"]
  DE -->|"{ isMember: true }"| FF
  FF -->|"eventos feature-flags.*"| WH["Webhooks Engine<br/>entrega ao cliente final"]
  FF -->|"eventos feature-flags.*"| AT["Audit Trail<br/>trilha de compliance"]
  WH -->|"HTTP assinado"| CLI["sistema do cliente"]

Este diagrama é o argumento comercial em uma imagem. Uma plataforma de feature flags avulsa para na primeira seta: ela não sabe quem é a organização sem você reimplementar o mapeamento, não tem um motor DMN ao lado para executar a sua regra de risco, e não tem para onde publicar o evento "a flag X foi desligada às 14h32 pelo usuário Y" além do próprio log dela.

Eventos publicados. Todos vão para o barramento e podem virar webhook para o cliente final:

Para receber esses eventos no seu sistema, assine feature-flags.* no Webhooks Engine.

Variáveis de ambiente

O Feature Flags não define variável própria. Ele usa as compartilhadas:

Dependências de infraestrutura

Limites e quotas

Catálogo de erros

Observabilidade

• GET /feature-flags/health responde com nome e versão do build. É a sonda de vida do orquestrador. Não verifica banco nem Redis — um 200 aqui não garante que a avaliação funciona.
• FlagEvaluationLog guarda 10% das avaliações com variationKey, reason, context, matchedRuleId, matchedSegmentIds e evaluationTimeMs. É a fonte para responder "qual a distribuição real do meu rollout de 10%?" e "quanto tempo custa avaliar esta flag?". Hoje só dá para consultar por SQL — não há endpoint (§15).
• O evento feature-flags.flag.evaluated acompanha cada avaliação amostrada e pode ser consumido pelo Audit Trail ou entregue por webhook.
• Chaves de cache para inspeção direta: ff:flag:{organizationId}:{flagKey} e ff:membership:{organizationId}:{segmentId}:{userId}.

Isolamento entre tenants

Os 25 endpoints aplicam, nesta ordem, authMiddleware → requirePermission(...) → requireOrganization. O organizationId sai do claim assinado do JWT e é passado explicitamente para cada método de repositório; nenhuma rota lê organizationId do corpo ou da query.

flowchart LR
  REQ["requisição com Bearer JWT"] --> A["authMiddleware<br/>valida assinatura HS256"]
  A --> P["requirePermission<br/>FEATURE_FLAGS_* ou SEGMENTS_*"]
  P --> O["requireOrganization<br/>403 se o token não tem organizationId"]
  O --> ORG["organizationId sai do claim assinado"]
  ORG --> DB["toda consulta ao Postgres recebe o organizationId"]
  ORG --> RD["toda chave de Redis leva o organizationId no prefixo"]

As duas chaves únicas do banco são compostas com a organização ((organizationId, key) em FeatureFlag e em Segment), então duas empresas podem ter uma flag checkout-novo sem colidir e sem enxergar uma a outra. As chaves do Redis também carregam o organizationId no prefixo, o que impede que o cache vaze entre tenants.

Recursos de outra organização respondem 404, não 403 — deliberadamente, para não confirmar a existência do recurso.

Separação de privilégio para operação

FEATURE_FLAGS_TOGGLE é uma permissão distinta de FEATURE_FLAGS_UPDATE. Quem está de plantão pode receber só a de toggle: consegue desligar em incidente, não consegue alterar variação, criar flag nem mexer em segmento. É a diferença entre um kill switch operacional e uma porta aberta.

Dados sensíveis no contexto de avaliação

Este é o ponto de atenção do BB para LGPD. O context.attributes que você manda em cada avaliação é persistido inteiro no campo context (JSONB) de FlagEvaluationLog nas avaliações amostradas, e o context.userId é gravado em texto. O BB não filtra, não mascara e não classifica esse conteúdo.

flowchart LR
  CTX["context.attributes<br/>e context.userId"] --> AV["avaliação"]
  AV --> S{"sorteio de 10%"}
  S -->|"90% das vezes"| NADA["nada é gravado"]
  S -->|"10% das vezes"| LOG["flags.flag_evaluation_logs<br/>context inteiro em JSONB<br/>userId em texto"]
  LOG --> SEM["sem mascaramento<br/>e sem expurgo automático"]

A consequência prática: se o seu chamador mandar CPF, e-mail ou renda em attributes, esses valores ficam no banco. Recomendações:

• Mande identificadores opacos, não dados pessoais. perfilRenda: "faixa-3" em vez de renda: 7200; um userId pseudonimizado em vez do CPF.
• Mande só os atributos que as suas condições de fato usam. Atributo que não é lido por nenhuma condição só gera passivo.
• Se dado pessoal precisar entrar no contexto, trate flags.flag_evaluation_logs como tabela com dado pessoal no seu inventário de LGPD, e considere que não há expurgo automático hoje (§15).

Segmentos DMN

O ruleContent de um segmento DMN é XML fornecido pelo cliente e executado pelo Decision Engine. A superfície de execução e as garantias de isolamento são as do Decision Engine, não deste BB. Trate quem tem SEGMENTS_CREATE como quem tem permissão de submeter lógica para execução no motor de decisão.

Exclusão lógica

Flags e segmentos usam deletedAt. A linha permanece para auditoria e para que um flagId histórico em log continue resolvível. Consultas de avaliação e listagem filtram deletedAt: null, então o recurso excluído é invisível pela API e sai do cache na mesma operação.

Rastreabilidade das mudanças

Toda criação, alteração, ligamento, desligamento e exclusão grava createdBy/updatedBy com o userId do token e publica evento no barramento com userId e organizationId nos metadados. "Quem desligou o checkout às 14h32" é uma consulta, não uma investigação.

Quanto tempo leva entre eu desligar a flag e o efeito aparecer?

Imediato para quem consultar depois do POST /disable, porque a própria chamada invalida a chave ff:flag:{org}:{key} no Redis. O teto teórico é o TTL de 300 segundos, que só entra em jogo se a invalidação falhar ou se alguém mudar o status direto no banco em vez de usar a API.

O mesmo usuário sempre recebe a mesma variação?

Sim, enquanto a key da flag e o percentual não mudarem. O balde vem de murmurhash.v3("userId:flagKey") % 100, que é determinístico e não guarda estado. Aumentar o percentual só acrescenta usuários; diminuir remove. Trocar a key da flag reembaralha todo mundo — não faça isso durante um rollout.

Preciso mandar userId em toda avaliação?

Não é obrigatório, mas sem ele você perde duas coisas: overrides não são aplicados e qualquer regra com rolloutPercentage abaixo de 100 é pulada. Uma flag com rollout de 10% chamada sem userId devolve a variação padrão, sempre. Se a sua resposta parece "presa" no padrão, essa é a primeira coisa a conferir.

Dá para usar isso como plataforma de teste A/B?

Para o roteamento, sim: variações múltiplas, distribuição consistente e o registro de qual usuário viu o quê (amostrado em 10%). Para a análise, não — o BB não calcula significância, não conhece as suas métricas de negócio e nem sequer expõe os logs por API hoje (§15). Se a sua pergunta é "a variação B converte mais?", use GrowthBook ou o seu data warehouse. Se a pergunta é "quero liberar para 10% e poder desligar", é exatamente para isso que este BB existe.

Qual a diferença entre segmento SIMPLE e DMN?

SIMPLE é uma lista de condições sobre atributos, avaliada em memória, sem chamada de rede: rápido e sem dependência externa. DMN é uma tabela de decisão executada pelo Decision Engine: expressa regra de negócio de verdade, permite que o time de risco escreva o critério sem passar por deploy, e custa uma chamada de rede (cacheada por 15 minutos). Regra de ouro: se cabe em condições sobre atributos, use SIMPLE. Se a regra já existe como matriz de decisão do negócio, use DMN.

Uma flag da minha empresa pode ser vista por outro cliente da plataforma?

Não. O organizationId vem do JWT assinado e é aplicado em toda consulta ao banco e em todo prefixo de cache. A unicidade da key é por organização, então nem a colisão de nome existe. Recurso de outro tenant responde 404, não 403 — de propósito, para não confirmar que ele existe.

Posso avaliar várias flags de uma vez para carregar a tela?

Hoje não pela API. Os endpoints evaluate-batch e evaluate-all existem no código, mas estão registrados num caminho que a rota POST /:flagKey captura antes, então respondem 404 (§15). Até a correção, faça uma chamada por flag no bootstrap — o cache de 300 segundos do lado do servidor absorve boa parte do custo.

O que acontece com o dado que eu mando em context.attributes?

Ele é usado na avaliação e, em 10% das vezes, persistido inteiro em flags.flag_evaluation_logs, junto com o userId. Não há mascaramento nem expurgo automático. Mande identificador opaco e faixa em vez de dado pessoal bruto — ver §14.

Como faço para saber quais flags posso apagar?

GET /feature-flags/api/v1/flags?filter[status]=ENABLED devolve as ligadas; cruze com o SELECT em flag_evaluation_logs para ver quais ainda são consultadas. O BB não faz essa limpeza sozinho — flag ligada em 100% há seis meses é dívida técnica, e o material de referência do assunto trata as flags no código como estoque com custo de manutenção (Martin Fowler — *Feature Toggles*).

Preciso do Decision Engine para usar o Feature Flags?

Só se você usar segmento do tipo DMN. Flags com rollout percentual, overrides e segmentos SIMPLE funcionam sem nenhuma dependência além de PostgreSQL, Redis e IAM.

_{Padrão: PADRAO-DOCUMENTACAO.md · Índice: INDEX.md}