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.*:
| Onde | Formato | Exemplo |
|---|---|---|
| URL de entrada (prefill Ads / mailing) | Parâmetro flat na query | ?reg_uf=SP®_municipio=São Paulo — também aceita alias curto ?uf= (cadastro, não demo) |
| Template de redirect de encerramento | Token entre chaves com path canônico | https://destino/?uf={field.reg.uf}&nome={field.reg.nome} — expandido no complete via GmrRedirectUrl.expandRedirectTemplate |
| Construtor Studio (grupo Field) | Chave reg_* + hint do token | Input 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:
- Alias em
FIELD_CANONICALS(excetoconsumeAliasessó-start) →{field…}canônico — ex.pesquisador→{field.surveyor},reg_uf→{field.reg.uf} demo_uf→{demo.uf}(caso especial; não passa pelo mapa field)- Chave desconhecida →
{customs.chave}(bag flat legado)
Implementação: autoref.js · smoke: node app/public/js/hub-vars-check.cjs.
Grupos — Construtor de URL (Studio)
| Grupo | Chaves na UI | Notas |
|---|---|---|
| Tema | theme | Reservada; tema visual |
| UTM | utm_source, utm_medium, utm_campaign, utm_term, utm_content | Botão «macros Meta» preenche os quatro abaixo |
| Field | reg_uf, reg_municipio, reg_bairro, reg_nome, reg_cnpj | Cadastro / registro; não confundir com demo |
| Demo | sexo, idade, demo_uf, demo_municipio, municipio_ibge, escolaridade | Demografia; UF/município via prefixo demo_ |
| Redirect | to, hub_id | to = 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)
| Query | Valor 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ônico | Aliases (recorte) | Grupo URL |
|---|---|---|
field.surveyor | surveyor, pesquisador, pesq, nomePesquisador, srvyr | — |
field.phone | phone, telefone, tel | — |
field.client_id | clientId, client_id, cliente | — |
field.call_id | callId, call_id | — |
field.audio_url | audio_url, audioUrl, call_url, callUrl | — |
field.transcription | transcription, transcricao | — |
field.profile_key | meta, profile_key, profileKey, perfil | — |
field.reg.cnpj | cnpj, reg_cnpj | Field |
field.reg.uf | uf, estado, reg_uf, reg_estado | Field (reg_uf) |
field.reg.municipio | municipio, município, cidade, city, reg_municipio, reg_cidade, reg_city | Field (reg_municipio) |
field.reg.bairro | bairro, reg_bairro | Field |
field.reg.nome | nome, reg_nome | Field |
Paths demo.* (público-alvo / Meta)
| Canônico | Query / hint Construtor |
|---|---|
demo.sexo | sexo, 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.uf | demo_uf → {demo.uf} (não usar uf curto para demo) |
demo.municipio | demo_municipio → {demo.municipio} |
demo.idade / escolaridade | Query idade, escolaridade (grupo Demo no Construtor) |
demo.municipio_ibge | municipio_ibge na query |
demo.faixa.ibge_5 | Token redirect {demo.faixa.ibge_5} (DEMO_TOKEN_PATHS) |
demo.faixa.pesquisa_6 | Token redirect {demo.faixa.pesquisa_6} |
customs.demo (objeto) | ?demo= JSON ou token redirect {demo} |
Tokens especiais no redirect
{hub_id}— no complete, valor =responseIdda sessão (contingência HUB). Lookup emredirect-url.js: tokenhub_idlêextra.responseIdantes dedata/customs. No Construtor, grupo Redirect expõe chavehub_idpara prefill de teste; em produção costuma ser só no template ({to}?hub_id={hub_id}).{demo}— serializacustoms.democomo JSON URL-encoded na query de destino.- Paths com ponto (
field.reg.uf,demo.uf,demo.faixa.ibge_5) — só entre chaves no redirect; na query de prefill use alias flat ou prefixoreg_/demo_conforme grupo.
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
- Efeitos do pedido
- Onde mora (schema vs settings vs API que você não chama)
- Ordem das alterações
- Lista de tarefas no
plan[]— no mesmo JSON que já traz o patch. Não esperar um segundo «pode executar». - Conferir se o pedido foi feito (não só JSON válido)
- 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.
legal-exclusao
Exclusão de dados
Titular pede para sair da lista / apagar dados com WhatsApp, e-mail ou CPF. Gravamos o pedido; não apagamos sessão nesta leva.
- Política: https://survey.gmrpesquisa.com.br/privacidade
- Formulário: https://survey.gmrpesquisa.com.br/exclusao
- Callback Meta:
POST https://survey.gmrpesquisa.com.br/v1/public/meta/data-deletion(signed_request)