Site público: HTML/JavaScript. Backstage: HTML com Supabase JS v2 e autenticação Supabase Auth. Backend do Testa-te: Worker Cloudflare em https://api.themappp.com, que comunica com Supabase REST usando credenciais apenas no servidor. Evitar alterações às rotas e tabelas existentes. Não assumir que todos os minijogos usam o Worker.

Backstage: countrySelect; país obtido por currentCountry()?.iso2, convertido para maiúsculas (PT, DE, etc.). Funções RPC recebem p_pais. Worker /testa-ronda aceita pais, com PT como valor por defeito. IMPORTANTE: verificar sempre que o HTML público envia o país correto e que todas as consultas/rankings são filtrados por pais. Não confundir 'Portugal' com 'PT'.

Fonte principal: public.povoacoes. Worker consulta Supabase REST com filtro pais=eq.<ISO2> e ativa=eq.true e campos id,nome,desambig,lon,lat,regiao. Função places(env,pais) mantém cache de 10 minutos. O endpoint POST /testa-ronda seleciona a localidade e devolve nome e token de ronda. O HTML público contém também LOC_PLACES como lista local usada em modos/fallbacks; não a tratar como base de dados oficial.

Fluxo confirmado: POST /testa-ronda com dispositivo, sessao opcional, pais e ilhas; devolve token e nome. POST /testa envia token e coordenadas do clique, permitindo calcular distância e pontuação no Worker. Token da ronda expira ao fim de 15 minutos. Não enviar coordenadas verdadeiras no payload público da ronda. Verificar nomes exatos dos campos no código antes de alterar.

No Worker: pontos = Math.round(100 * Math.exp(-km/60)). Um erro de 1 km vale aproximadamente 98 pontos. A tolerância de 1 km para validação das coordenadas é uma política de qualidade dos dados, NÃO um raio de pontuação máxima. Não alterar fórmula sem pedido explícito.

No Worker analisado: 3 jogadas gratuitas por dispositivo, 20/dia para utilizadores autenticados, limite adicional por IP de 12/24 h; sessão validada pelo backend. Há hashes de dispositivo/IP e token de ronda. Não retirar limites nem confiar exclusivamente em validações feitas no navegador.

Tabela public.testa_jogadas: guarda identificadores de jogador/concelho/localidade, coordenadas do palpite, distância, pontos e metadados antiabuso/nonce conforme implementação do Worker. A fonte persistente é Supabase, não localStorage do browser. Alterar coordenadas de uma localidade não recalcula automaticamente jogadas antigas.

Novo Backstage consulta RPC testa_estatisticas_publicas(p_pais). Rankings de localidades: mínimo de 20 jogadas; acerto definido como distância até 10 km no módulo implementado. O jogo existente tem GET /testa-ranking para ranking de concelhos, cuja consulta original a testa_media_concelho não inclui filtro de país explícito: verificar isolamento antes de usar em múltiplos países. As estatísticas públicas não devem expor identificadores pessoais.

Worker consulta view testa_celulas por povoacao_id e agrega coordenadas em células. A implementação analisada usa limiar de 10 palpites para apresentar esta funcionalidade. Preservar anonimização/agregação; não publicar coordenadas associadas a utilizadores individuais.

O HTML do Backstage usa Supabase Auth e RPCs backstage_testa_listar(p_pais), backstage_testa_importar e funções de edição definidas no SQL de instalação. O carregamento atualiza de 30 em 30 segundos quando a página está aberta. Só Owner vê o separador. A segurança efetiva depende das permissões/RLS e das funções SECURITY DEFINER no Supabase, não de esconder botões.

Formato preferido: CSV delimitado por ponto e vírgula, com cabeçalho nome;desambig;lon;lat;regiao;ativa. Também aceita TSV/JSON no Backstage preparado. País vem do cabeçalho, não do bloco. Coordenadas WGS84 decimais, longitude antes da latitude, ponto decimal. Até 200 registos por bloco. Pré-visualização, validação e identificação de possíveis duplicados antes de gravar. Nunca substituir localidades existentes automaticamente.

Preferência operacional: OSM ou GeoNames; confirmar município pela CAOP quando disponível. 1 km é a tolerância de validação aceite pelo projeto, não uma garantia de precisão da fonte. Sedes de concelho não devem ser confundidas com centroides dos polígonos. Confirmar país, município e longitude/latitude antes de ativar.

Worker filtra regiao, incluindo 'continente' ou 'principal', e ilhas indicadas em POST /testa-ronda. No HTML PT há seleção de 'acores' e 'madeira'. Preservar os valores de regiao esperados pela implementação; não criar etiquetas incompatíveis sem atualizar Worker e dados.

Worker 'comunidade' gere autenticação/sessões e rotas do Testa-te. O HTML público envia sessao quando o jogador está autenticado. Algumas rotas antigas da comunidade e do ranking têm valores PT fixos; não presumir isolamento multi-país total. Antes de adaptar para DE, NL ou IE, auditar todos os filtros por pais.

Supabase Auth via createClient(SUPABASE_URL,SUPABASE_PUBLISHABLE_KEY), signInWithPassword e sessão persistente. A chave publishable é pública; a service role NÃO deve ser embutida no HTML. O separador Testa-te e este separador Mecânica são Owner-only na interface. Restrições reais de escrita devem ser impostas no Supabase.

Páginas presentes no HTML: dashboard, requests, territories, editions, businesses, categories, revenue, traffic, empires, users, community, audit. O Backstage usa state e funções de renderização próprias por módulo. Tráfego indica explicitamente dados de demonstração e integração futura com analytics; não afirmar que é telemetria real. Consultar os nomes das tabelas e funções existentes antes de alterar módulos não relacionados.

No Backstage há páginas requests e territories, estados pending/approved/rejected para pedidos e available/reserved/occupied para territórios. Edições incluem códigos e personalizações. Estas estruturas são independentes das localidades de public.povoacoes. Não reutilizar IDs de territórios como IDs de povoações.

A página Receitas distingue pagamentos/donativos e movimentos confirmados. A página Tráfego atual declara dados locais de demonstração e futura fonte Cloudflare. Não apresentar números simulados como reais nem modificar dados financeiros ao alterar o jogo.

Backstage Testa-te: consulta a cada 30 s quando aberto; módulo público de rankings preparado para atualização periódica. Worker: cache de localidades de até 10 min. Uma localidade recém-ativada pode demorar até expirar a cache a entrar nas rondas. Não chamar 'tempo real' absoluto a dados sujeitos a cache.

Instruções de segurança para a IA: trabalhar sobre o ficheiro atual completo; não reconstruir o site; preservar CSS, seletores, endpoints, autenticação e dados existentes; indicar ficheiros alterados, migrações SQL e passos de deploy; nunca inserir service_role ou segredos no browser; distinguir código existente de proposta; testar sintaxe e regressões; fazer alterações reversíveis.