Mapa de atividades do Construtor

Cada item do book de aprendizado aponta para uma destas âncoras (docId). Manutenção: app/docs/AI_CONSTRUTOR.md.

intent-info

Pedido de informação

Perguntas do tipo «gere a URL», «quais variáveis», «explique». Devolver só reply (e plan se ajudar).

intent: "info"
surveyJson: null
settingsPatch: null
surveyMeta: null
createSurvey: false
changes: []

O Studio não autosava e não mostra recibo «O que mudei».

intent-mutate

Pedido de alteração

Só quando o humano pediu mudar o form ou settings. Devolver JSON completo e/ou settingsPatch com diff real. Título ecoado (igual ao atual) não é mudança.

surveyjson-form

Form (surveyJson)

Páginas, perguntas, visibleIf / enableIf / requiredIf, tipos SurveyJS. Nomes em snake_case. O texto das regras (isRequired, rowsVisibleIf, páginas objeto, não apagar sem pedido) está em app/docs/construtor-regras.json — o turno carrega esse arquivo. Esta página não repete as frases.

{
  "type": "html",
  "name": "mapa_coordenadas",
  "html": "<iframe title=\"…\" allow=\"geolocation\" data-lat-name=\"latitude_g6\" data-lng-name=\"longitude_g6\" data-addr-name=\"endereco_g6\" srcdoc='<!DOCTYPE html>…'></iframe>"
}
{ "type": "text", "name": "latitude_g6", "title": "Latitude" }
{ "type": "text", "name": "longitude_g6", "title": "Longitude" }
{ "type": "text", "name": "endereco_g6", "title": "Endereço" }

settings-filters

Filtros

settingsPatch.filters[] com expression, code, label. O Studio projeta triggers type=complete. O Construtor não edita surveyJson.triggers[].

settings-quotas

Cotas

settingsPatch.quotas[]. Nunca trigger complete para cota. Arrays substituem a lista (incluir itens que devem permanecer).

settings-automations

Automações

settingsPatch.automations[] When/Then (webhook, redirect, email, ai…). Webhook HTTPS. Arrays substituem a lista.

settings-messages

Encerramento

settingsPatch.messages.{filtered|overlimit|completed} = texto (mode: custom) ou redirect (mode: redirect, URL absoluta). Não usar path relativo. Não escrever o redirect só no reply.

create-survey

Pesquisa nova

createSurvey=true somente se o humano pediu pesquisa nova ou o form atual está vazio (0 perguntas). Se já há perguntas e o pedido é alterar, createSurvey=false e merge no JSON atual.

prefill-url

URL de prefill

Formato: https://r.gmrpesquisa.com.br/{publicName}?nome=VALOR_REAL (host público, nunca survey.gmrpesquisa.com.br/{slug} — isso devolve {"error":"not_found"}).

Query com {token} no redirect de encerramento é preenchida no complete com a resposta (data, senão customs). Host público: https://r.gmrpesquisa.com.br/{slug}?campo={campo}. Nunca survey.gmrpesquisa.com.br/{slug} ({"error":"not_found"}). Link colado no browser sem passar pelo complete não substitui as chaves.

Demo / HUB: prefill demográfico usa canônicos demo.* (sexo, demo_uf, demo_municipio, ?demo= objeto JSON). Aliases curtos uf/municipio/bairro/nome são cadastro (field.reg), não demo. Redirect de contingência HUB: {to}?hub_id={responseId} (token hub_id = id da sessão HUB). Token {demo} serializa o objeto customs.demo em JSON na query.

Registro completo (canônico → aliases → grupos do Construtor de URL): url-token-registry. Código: FIELD_CANON, FIELD_CANONICALS / customsTokenSuggestion. Dev: /docs/dev#tool-url-tokens.

url-token-registry

Registro de tokens — URL pública e redirect

Fonte de verdade para substituição no redirect de encerramento ({token} → resposta): redirect-url.js (FIELD_CANON, expandRedirectTemplate, lookupRedirectToken). Prefill / chips / Autoref: autoref.js (FIELD_CANONICALS, DEMO_TOKEN_PATHS, customsTokenSuggestion). Servidor (ESM): app/session-envelope.js — mesma tabela que alimenta start/CSV. Manter esta página alinhada ao editar o registro.

Query reservada (não usar como chave custom)

responseid, canal, _, istest, theme. theme é reservada mas editável no grupo Tema do Construtor.

Colisão cadastro vs demo

Aliases curtos uf, municipio, bairro, nome resolvem para cadastro (field.reg.*), não para demografia Meta. No Construtor, prefira reg_* no grupo Field e demo_uf / demo_municipio no grupo Demo (hints {demo.uf}, {demo.sexo}). Evite ?uf= solto em links de anúncio quando a intenção é demo.

Query reg_* vs tokens {field.reg.*}

Dois contextos diferentes, mesmo canônico customs.field.reg.*:

OndeFormatoExemplo
URL de entrada (prefill Ads / mailing)Parâmetro flat na query?reg_uf=SP&reg_municipio=São Paulo — também aceita alias curto ?uf= (cadastro, não demo)
Template de redirect de encerramentoToken entre chaves com path canônicohttps://destino/?uf={field.reg.uf}&nome={field.reg.nome} — expandido no complete via GmrRedirectUrl.expandRedirectTemplate
Construtor Studio (grupo Field)Chave reg_* + hint do tokenInput rotulado reg_uf {field.reg.uf}; chips inserem o token no valor do campo

Evite ponto na query de prefill (?field.reg.uf=) — frágil em ads managers. O start mapeia aliases flat para nested customs.field usando FIELD_CANON / consumeAliases.

Studio — accordion Field (URL_FIELD_REG)

Publicar → URL (studio-canais.js): o grupo Field lista só chaves reg_* (não uf curto). Cada linha mostra o alias de query e, ao lado, o token canônico {field.reg.*}. Acima dos inputs, chips clicáveis copiam o token para o valor (útil ao montar redirect na mesma URL de teste). Tabela fixa:

reg_uf         → {field.reg.uf}
reg_municipio  → {field.reg.municipio}
reg_bairro     → {field.reg.bairro}
reg_nome       → {field.reg.nome}
reg_cnpj       → {field.reg.cnpj}

Espelha URL_FIELD_REG + URL_HINT em studio-canais.js; paridade: node app/public/js/url-builder-studio-check.cjs.

Autoref — customsTokenSuggestion(key)

Ao digitar chaves customs / query no editor de redirect ou chips Autoref, a sugestão de token segue:

Implementação: autoref.js · smoke: node app/public/js/hub-vars-check.cjs.

Grupos — Construtor de URL (Studio)

GrupoChaves na UINotas
TemathemeReservada; tema visual
UTMutm_source, utm_medium, utm_campaign, utm_term, utm_contentBotão «macros Meta» preenche os quatro abaixo
Fieldreg_uf, reg_municipio, reg_bairro, reg_nome, reg_cnpjCadastro / registro; não confundir com demo
Demosexo, idade, demo_uf, demo_municipio, municipio_ibge, escolaridadeDemografia; UF/município via prefixo demo_
Redirectto, hub_idto = slug alvo; hub_id preenchido no complete HUB
Custom(livre)Params flat só prefill manual/mailing; alerta se chave reservada, alias duplicado ou ponto na query

Macros Meta (UTM no Ads Manager)

QueryValor Meta
utm_source{{site_source_name}}
utm_campaign{{campaign.id}}
utm_term{{adset.id}}
utm_content{{ad.id}}

utm_medium costuma ser literal (ex. paid), não macro.

Paths field.* (canônico → aliases)

Lookup redirect: extra → data → customs (nested) → aliases abaixo. Prefill na URL de entrada aceita alias flat na query quando o start mapeia para customs.field.

CanônicoAliases (recorte)Grupo URL
field.surveyorsurveyor, pesquisador, pesq, nomePesquisador, srvyr—
field.phonephone, telefone, tel—
field.client_idclientId, client_id, cliente—
field.call_idcallId, call_id—
field.audio_urlaudio_url, audioUrl, call_url, callUrl—
field.transcriptiontranscription, transcricao—
field.profile_keymeta, profile_key, profileKey, perfil—
field.reg.cnpjcnpj, reg_cnpjField
field.reg.ufuf, estado, reg_uf, reg_estadoField (reg_uf)
field.reg.municipiomunicipio, município, cidade, city, reg_municipio, reg_cidade, reg_cityField (reg_municipio)
field.reg.bairrobairro, reg_bairroField
field.reg.nomenome, reg_nomeField

Paths demo.* (público-alvo / Meta)

CanônicoQuery / hint Construtor
demo.sexosexo, demo.sexo ou token redirect {demo.sexo}. Anúncio só mulher/homem: demo.sexo=mulher|homem (+ skip.Hub.sexo)
skipHub.sexo (customs)Query literal skip.Hub.sexo=mulher|homem. visibleIf da pergunta sexo no HUB: {skipHub.sexo} empty
demo.ano_nascimento—
demo.ufdemo_uf → {demo.uf} (não usar uf curto para demo)
demo.municipiodemo_municipio → {demo.municipio}
demo.idade / escolaridadeQuery idade, escolaridade (grupo Demo no Construtor)
demo.municipio_ibgemunicipio_ibge na query
demo.faixa.ibge_5Token redirect {demo.faixa.ibge_5} (DEMO_TOKEN_PATHS)
demo.faixa.pesquisa_6Token redirect {demo.faixa.pesquisa_6}
customs.demo (objeto)?demo= JSON ou token redirect {demo}

Tokens especiais no redirect

Teste ao vivo: Studio → Publicar → URL (Construtor) → «Abrir teste» com isTest=1. Check de paridade: node app/public/js/url-builder-studio-check.cjs.

public-name

Slug / base da URL

O contexto do turno já traz publicName. Nunca peça «a URL de entrada» se o slug estiver preenchido. Monte a URL pública (PUBLIC_BASE_URL, hoje https://r.gmrpesquisa.com.br/{publicName}). Proibido survey.gmrpesquisa.com.br/{slug}.

plan-then-verify

Planejar, executar, conferir

  1. Efeitos do pedido
  2. Onde mora (schema vs settings vs API que você não chama)
  3. Ordem das alterações
  4. Lista de tarefas no plan[] — no mesmo JSON que já traz o patch. Não esperar um segundo «pode executar».
  5. Conferir se o pedido foi feito (não só JSON válido)
  6. Se travar de verdade (dado ausente no contexto): fulfillment.ok=false, blocker, orientação manual — sem patch. Revisão de cliente não é travamento.

skipversion

Autosave vs Salvar

O Construtor pode gravar draft com skipVersion: true quando houve mutate + diff. Isso não entra no ledger de aprendizado. Instrução aceita = botão Salvar (note: studio_json), que gera versão e alimenta classificador → book.