Padrão de engenharia · uso interno

A camada de IA
da Miner.

Tudo que fala com modelo passa por uma porta só, com chave por ponta, cota diária e custo por chamada registrado. Este documento mostra o que mudou entre 6 e 13 de outubro de 2026 e, principalmente, o padrão a seguir daqui para frente.

Período do trabalho
6 a 13 de outubro de 2026
Alcance
22 pontas, 7 projetos Supabase, 10 repositórios
Fonte dos números
ia_proxy_log e painel do OpenRouter, 13/10 às 17h
Quem mantém
Gustavo Coutinho · by Miner
PORTA ÚNICA
01
O que mudou6 a 13 de outubro
Miner.
De cada um com a sua chave para uma porta só, medida e com cota

Antes, cada portal, robô e edge function falava direto com o provedor, com uma chave própria no ambiente. Funcionava, e era impossível responder três perguntas: quanto cada ponta gasta, quem ainda usa chave velha e quanto falta de crédito. Agora as três têm resposta na tela.

22
pontas com chave própria, cada uma com cota diária e rótulo por função
Fonte · ia_proxy_consumidores, 13/10
0
falando direto com provedor em código nosso, fora a voz (áudio, que a porta não faz)
Fonte · varredura dos 10 repositórios, 13/10
US$ 1,50
o mês inteiro de IA, 1.015 chamadas registradas uma a uma
Fonte · ia_proxy_log, 30 dias até 13/10
US$ 42
de saldo, uns 220 dias no ritmo de hoje
Fonte · OpenRouter, 13/10 às 17h
A

O que entrou na porta

feito
  • As 8 edges do MinerOS (radar e SAC), sem tocar em nenhuma função: só o valor da chave no cofre do projeto
  • 4 edges do MinerCRM: prls-ia, resumo de conversa, repurpose de conteúdo e análise de relatório
  • gerar-conteudo, que era o último ponto na OpenAI direto
  • Portal Porão, Blitz de Aço, Portal de Eventos, Portal Normatel, painel de saúde
  • Arquivo financeiro do Porão, a ponta mais difícil: lê PDF com o parser do OpenRouter
  • Diagnóstico do painel de gestão ACCS, que estava com a prosa morta havia semanas
B

O que a porta ganhou

novo
  • Chave por hash: a chave nasce no cofre de quem usa e só o SHA-256 fica na tabela
  • Rótulo por função (&de=): separa as 8 edges que dividem uma chave
  • Cadeia de fallback e repasse de plugins e reasoning
  • upstream_status no erro: separa sem crédito de modelo fora do ar
  • GET ?saude=1: cota e saldo sem gastar modelo
  • A chave que vazou em setembro foi revogada, e a tentativa agora registra de onde veio
02
02
Como funcionao caminho de uma chamada
Miner.
Duas portas, uma régua: ninguém fala com provedor direto
Portais de cliente Edge functions Robôs e scripts Apps internos Páginas públicas A PORTA ai-json JSON, visão e arquivo ia-chat texto corrido e busca 1. chave da ponta, por hash 2. cota do dia 3. rótulo da função 4. custo registrado 5. modelo que respondeu OpenRouter Gemini, Claude, GPT e outros uma chave só, sem limite ia_proxy_log cada chamada com ponta, função, modelo, tokens, custo e erro
Fonte · desenho das edge functions ai-json e ia-chat no projeto minercrm, versão de 13/10/2026
03
03
Padrão 1ligar uma ponta nova
Miner.
Quatro passos, sempre nesta ordem
1

A chave nasce no cofre de quem usa

Ela nunca é digitada por mim nem aparece em tela. Nasce onde vai morar e só o hash viaja.

-- edge function: dentro do Vault do próprio projeto select vault.create_secret( 'mnr_'||encode(gen_random_bytes(16),'hex'), 'ia_minha_key', 'para que serve'); # app na Vercel: valor pelo stdin, nunca em argv openssl rand -hex 16 | vercel env add IA_MINER_KEY production
-- a tabela guarda só o SHA-256 insert into ia_proxy_consumidores (nome, chave_hash, cota_dia) values ('minha-ponta', '<hash>', 500);
2

A chamada

JSON, imagem ou arquivo vai no ai-json. Texto corrido vai no ia-chat. O rótulo &de= é obrigatório quando a mesma chave serve mais de uma função.

POST /functions/v1/ai-json ?key=<chave>&de=minha-funcao { "model": "google/gemini-2.5-flash-lite", "max_tokens": 900, // sempre "system": "...", "user": "..." } // resposta { ok, data, model, usage }
  • max_tokens sempre. Sem ele o OpenRouter reserva o contexto inteiro e recusa com 402, mesmo com crédito
  • Antes de um lote, pergunte a cota e o saldo: GET ?key=...&saude=1
3

Trate o erro pelo upstream

A porta responde 502 para qualquer erro do provedor e diz em upstream_status o que foi de verdade. 402 é sem crédito e o trabalho espera na fila. 400 é definitivo, não repita. 429 é cota do dia, volta amanhã.

4

Prove e registre

Chame uma vez de verdade e confira a linha no ia_proxy_log com o nome e o rótulo certos. Sem essa conferência, a ponta pode estar caindo no caminho legado sem ninguém ver.

04
04
Padrão 2onde mora cada chave
Miner.
Uma chave vive em um lugar só, e o banco guarda apenas o hash

O lugar depende de quem usa. A regra que não muda: a chave nunca fica em código, nunca em argv (aparece no ps de quem estiver na máquina) e nunca é compartilhada entre pontas.

Quem usaOnde a chave moraComo chega láExemplos hoje
Edge function vault.create_secret no Vault do próprio projeto Nasce dentro do banco, por SQL. O valor nunca saisó o hash vai para a tabela de consumidores miner_ai_key (MinerOS) · ia_crm_key (MinerCRM) · ia_conteudo_key
App na Vercel Env IA_MINER_KEY, marcada como Secret vercel env add lendo do stdinSecret não volta: a prova vem do endpoint de saúde do produto Portal Porão · Blitz · Eventos ACCS · arquivo do Porão · painel de saúde
Script no Mac ~/.config/miner/robos.env, permissão 600 Uma linha por consumidor, lida pelo scriptnunca passada por linha de comando rotinas · command-center · deck-normatel · painel de gestão ACCS
A chave do provedor Só no ambiente das edges da porta Uma chave só na conta, sem limitelimite por chave vira ponto único de parada, com erro que parece falta de crédito miner-porta-unica, criada em 13/10
Fonte · ia_proxy_consumidores e cofres dos 7 projetos Supabase, conferidos em 13/10/2026
05
05
Padrão 3as armadilhas, todas vividas
Miner.
Oito coisas que falham caladas, e o que fazer no lugar

No pedido

evite
  • json_schema com modelo da Anthropic. Volta 404: nenhum provedor do Claude aceita. Com Claude, peça o formato na instrução e valide no código
  • Chamada sem max_tokens. O provedor reserva o contexto inteiro e recusa com 402, parecendo falta de saldo
  • Tratar todo erro como temporário. 502 da porta não é o status real: leia upstream_status antes de repetir

Na infraestrutura

evite
  • Reimplantar edge sem verify_jwt: false. O padrão liga a trava e tudo responde 401
  • Mudar assinatura de RPC sem apagar a antiga. Ficam duas e o PostgREST para de escolher: aqui o log parou por dez minutos sem avisar
  • Limite de crédito por chave. Quando estoura, todas as pontas caem juntas e o erro parece falta de saldo na conta

Na entrega

evite
  • Achar que push faz deploy. Metade dos projetos re-deploya sozinha, metade não: confira a idade do último deploy de produção
  • Migrar só quem usa a chave. Procure também quem a testa: três rotas do painel de saúde decidiam se havia IA olhando a env antiga
  • Deixar env órfã. Chave sem uso é chave esquecida: saia removendo do ambiente quando a ponta migrar
Fonte · as oito aconteceram entre 10 e 13/10/2026 e estão registradas no vault, em openrouter-gotchas-schema-e-max-tokens e rpc-duas-assinaturas-postgrest
06
06
Padrão 4como conferir, sem abrir código
Miner.
Três lugares respondem quase tudo
A

Command Center

diário

Aba LLMs · Consumo. Mostra os dois lados da conta, quem gastou por ponta e por função, o saldo e quantos dias ele dura no ritmo atual.

  • Ponta com erro aparece com selo vermelho
  • Custo por chamada separa quem chama muito e barato de quem chama pouco e caro
  • Os robôs aparecem ao lado, com atraso em vermelho
B

A própria porta

na hora

Para saber se uma ponta pode começar um lote, sem gastar modelo:

GET /ai-json?key=<chave>&saude=1 { ok, consumidor, usados, cota, saldo_openrouter }

Não entra no log e não consome a cota que está sendo consultada.

C

O log, para investigar

quando algo some
-- quem gastou, por função select * from ia_consumo_por_rotulo(30); -- quem ainda usa chave velha select * from ia_proxy_log where consumidor = 'chave-revogada';

A tentativa com chave revogada registra de onde veio: user-agent, referer e IP.

Fonte · painel em produção e funções do projeto minercrm, versão de 13/10/2026
07
07
O que faltacom data, para não esquecer
Miner.
Três exceções conscientes e quatro datas no calendário
A

Fora da porta, de propósito

decidido
  • Template multi-portal (Hidrotintas e irmãos). A credencial é por portal, guardada no banco, e a mesma linha serve vários: trocar sem trocar o código de todos derruba portal de cliente. É rollout coordenado
  • A voz do painel de saúde. É áudio, e a porta faz texto e JSON. É a única razão pela qual aquele projeto ainda guarda chave de provedor
  • Os dois boletos protegidos por senha no arquivo do Porão. Nem o modelo abre: precisam ser substituídos sem senha
B

No calendário

agendado
  • 17/10 · apagar o backup miner_ai_key_anterior_20261010 do Vault do MinerOS, depois de uma semana limpa
  • 17/10 · medir a semana cheia das duas rotinas de julgamento que continuam no Claude de propósito
  • 10/11 · tirar o caminho legado da porta, depois de um ciclo mensal inteiro sem uso. O legado morreu em 10/10, mas chamador mensal ainda não teve a chance de aparecer
  • Sem data · o primeiro --aplicar do catálogo da Normatel, que manda centenas de itens ao Meta e pede um dia acompanhado
Fonte · registro do trabalho em ~/Documents/Claude/migracao-openrouter/PADRONIZACAO-10-10.md, atualizado em 13/10/2026. Os números deste documento saíram do ia_proxy_log e do painel do OpenRouter em 13/10 às 17h e envelhecem: a aba LLMs do Command Center sempre tem o de hoje.
08