Backend e dados¶

Firebase¶

firebase.json centraliza Firestore, Functions, Storage, Hosting e Emulator Suite. O backend JavaScript roda em Node.js 22.

flowchart TB
  APP[Apps Flutter] --> AUTH[Firebase Auth]
  APP --> FS[(Cloud Firestore)]
  APP --> ST[(Storage)]
  APP --> CF[Cloud Functions]
  CF --> FS
  CF --> AUTH
  CF --> STRIPE[Stripe]
  TRIGGERS[Firestore/Scheduler triggers] --> CF
  RC[Remote Config] --> APP

Coleções centrais¶

Coleção	Responsabilidade
`users`	Perfil, estado de Premium e metadados de referral.
`partners`	Organização/parceiro; `owner_uid` define propriedade.
`stores`	Unidades vinculadas por `partner_id`.
`offers`	Oferta comercial, autoria, curadoria e quota de cupons.
`coupon_redemptions`	Instâncias de cupom e estado do check-in.
`campaigns`	Campanhas e janelas de submissão/execução.
`campaign_participations`	Participação de parceiros em campanhas.
`waiters`	Garçons e vínculo com unidade.
`waiter_sessions`	Sessão backend-only emitida após login por PIN.
`referral_rewards`	Benefícios de indicação disponíveis/consumidos.
`subscriptions`	Espelho server-side do estado de assinatura Stripe.
`stripeEvents`	Idempotência/auditoria operacional de webhooks Stripe.
`settings/schedulers`	Frequência lógica e enable/disable de schedulers.

Convenções de vínculo¶

Há convenções históricas de nomes diferentes:

offers.restaurantId aponta para um documento em stores;
stores.partner_id aponta para partners;
offers.partnerId usa camelCase;
waiters.store_id aparece no modelo persistido.

Ao criar query nova, confirme o nome persistido, não apenas o nome da propriedade Dart.

Índices¶

firestore.indexes.json versiona índices compostos para consultas de cupons, ofertas e campanhas. Exemplos:

cupom por usuário + status;
cupom por restaurante/partner + status + updatedAt;
cooldown por usuário + oferta + status + usedAt;
ofertas por source/status;
campanhas por status e datas.

Quando uma nova query Firestore exigir índice, adicione-o ao arquivo versionado em vez de depender apenas de criação manual no console.

Storage¶

Uploads de imagens ficam separados por partner/campanha e são limitados pelas storage.rules a imagens menores que 8 MiB. Leitura de imagens nesses caminhos é pública; escrita exige partner dono ou Super Admin, conforme o prefixo.