Cloud Functions¶

Runtime e convenções¶

O backend usa Functions v2, firebase-admin e Node.js 22. functions/index.js é o único entrypoint e exporta módulos de functions/src. A região é southamerica-east1 em todas as exports atuais.

Callables devem receber autenticação Firebase; CORS ou invoker: public tornam o endpoint alcançável, mas não substituem a verificação de request.auth. Mutações críticas usam transações/batches e FieldValue.serverTimestamp().

Catálogo de callables¶

Export	Consumidor/finalidade	Autorização server-side
`createCouponRedemption`	gera cupom por `offerId`	usuário autenticado; elegibilidade derivada
`activateCoupon`	move o cupom para espera	dono autenticado do cupom
`cancelCheckin`	volta para `active`	dono autenticado do cupom
`cancelCoupon`	cancela e libera vaga	dono autenticado do cupom
`markCouponAsUsed`	uso pelo painel parceiro	owner do partner do cupom
`generateCoupon`	endpoint antigo	sempre falha pedindo atualização do app
`validateGeofence`	fluxo geográfico legado	autenticado; usa coleção legada `coupons`
`loginWaiter`	autentica e cria sessão por 24h	usuário Firebase autenticado; app usa auth anônimo
`confirmCheckin`	confirma na unidade	sessão de garçom ativa e autorizada
`getOfferFeed`	ranking offer-first	usuário autenticado
`getDashboardStats`	métricas do parceiro	apenas autenticação; recebe `partnerId` do cliente
`curateOffer`	aprovar/rejeitar/ajustar/tier	custom claim `super_admin`
`createOfferAsAdmin`	cria oferta com autoria administrativa	custom claim `super_admin`
`deleteOffer`	deleção auditada	Super Admin ou criador da oferta, com vínculo ao partner
`createCampaign`	cria draft	custom claim `super_admin`
`updateCampaign`	edita draft/scheduled	custom claim `super_admin`
`changeCampaignStatus`	aplica matriz de estados	custom claim `super_admin`
`joinCampaign`	registra interesse	usuário autenticado que é owner de partner
`withdrawCampaignParticipation`	desiste	owner do partner, salvo participação aprovada
`submitCampaignOffer`	cria oferta por unidade	owner do partner + ownership das unidades
`getSchedulerSettings`	lê/inicializa defaults	custom claim `super_admin`
`updateSchedulerSettings`	habilita e muda intervalo	custom claim `super_admin`
`submitReferralCode`	associa indicação	dono autenticado da conta
`createStripeCheckoutSession`	cria checkout	usuário autenticado
`createStripePortalSession`	abre portal do customer	usuário autenticado
`deleteUserAccount`	exclusão/redação	usuário autenticado da própria sessão

Autorização do dashboard

getDashboardStats valida autenticação, mas o código atual não demonstra que o partnerId informado pertence ao UID chamador. Como Admin SDK ignora Firestore Rules, trate esse endpoint como uma superfície a endurecer antes de expor métricas sensíveis.

HTTP, triggers e schedulers¶

Export	Tipo	Fonte/efeito
`stripeWebhook`	`onRequest`	valida assinatura Stripe e sincroniza assinatura/entitlement
`referralEngine`	`onDocumentUpdated users/{userId}`	aplica recompensa após validação do telefone
`onUserCreatedWithPhoneVerified`	`onDocumentCreated users/{userId}`	cobre criação já verificada
`onOfferWritten`	Firestore com auth context	registra criação, atualização e deleção em audit log
`expireCoupons`	schedule a cada minuto + throttle	expira cupons e libera reservas
`resetTrendingProducts`	cron `5 0 * * *`	zera contagem/flag trending de todas as ofertas
`closeExpiredCampaigns`	schedule a cada minuto + throttle	encerra campanhas e expira ofertas
`autoTransitionCampaigns`	schedule a cada minuto + throttle	promove campanhas pelas datas

Contrato de erros¶

Código	Interpretação típica
`unauthenticated`	não há contexto Firebase Auth
`permission-denied`	role, ownership, sessão ou unidade incompatível
`invalid-argument`	campo ausente, formato ou enum inválido
`not-found`	documento relacionado não existe
`already-exists`	conflito de código/slug ou recurso único
`resource-exhausted`	limite de cupom atingido
`failed-precondition`	estado, janela, cooldown ou entitlement não permite ação
`internal`	falha inesperada após normalização/log seguro

Não dependa de texto de erro para lógica. Os adapters devem decidir pelo código e apresentar mensagem localizada.

Como adicionar uma Function¶

implemente o handler em functions/src e valide autenticação/role antes de ler dados sensíveis;
derive IDs e ownership do token sempre que possível;
use transação para invariantes concorrentes e batch para mudanças independentes;
exporte pelo functions/index.js;
adicione teste Jest e, se a regra depender do Firestore real, teste de emulador;
atualize Rules/índices e o adapter Dart em conjunto;
valide localmente sem chamar produção.