Execução e diagnóstico

Desenvolvimento local

Ordem recomendada:

1. dart run melos bootstrap na raiz;
2. npm ci em functions;
3. criar os arquivos locais de ambiente sem segredos versionados;
4. iniciar npm run emulators;
5. popular o emulador com npm run seed, quando necessário;
6. executar o app com flavor/defines explícitos.

O Emulator UI fica em http://127.0.0.1:4000. Use-o para confirmar Auth, documentos e logs locais sem inferir estado de produção.

Runbook de schedulers

1. confirme o documento settings/schedulers no ambiente correto;
2. verifique enabled, intervalMinutes e lastRunAt do job;
3. leia logs pelo prefixo do job;
4. valide os índices usados pelas queries;
5. no emulador, npm run schedulers exige FIRESTORE_EMULATOR_HOST e executa helpers locais;
6. não edite lastRunAt em produção como primeira resposta: encontre a falha do lote.

Os jobs processam limites (100/200 campanhas, 500 cupons e batches de ofertas) e podem precisar de execuções sucessivas para backlog maior.

Diagnóstico por fluxo

Sintoma	Evidência local
App inicia no projeto errado	log de flavor, applicationId, arquivo env e firebase_options.dart
Primeira callable falha	token App Check, Auth e instância regional de Functions
Garçom vê fila vazia	sessão ativa, storeIds, status waiting_checkin e Rules
Campanha não mudou de status	datas Timestamp, throttle e índice por status/data
Premium não liberou	assinatura do webhook, stripeEvents, subscriptions/{uid}, campos de users/{uid}
Oferta não aparece	origem/status, unidade ativa/localizada, filtros, limite e fallback do feed
Upload negado	owner do partner, prefixo Storage, MIME image/* e tamanho < 8 MiB

Build e release

Build Android do app principal:

cd apps/aivaleu_app
flutter build appbundle --flavor prod --dart-define=FLAVOR=prod --obfuscate --split-debug-info=build/app/outputs/symbols

Build do Super Admin:

cd apps/super_admin_web
flutter build web --release

O hosting super-admin aponta para apps/super_admin_web/build/web e usa rewrite SPA. Artefatos de símbolos devem ser guardados com a release para deobfuscation, mas não versionados.

Deploy e rollback

Os comandos abaixo alteram ambiente remoto; execute apenas após confirmar conta, projeto Firebase, testes, secrets e changelog:

firebase use
firebase deploy --only functions
firebase deploy --only hosting:super-admin
firebase deploy --only firestore:rules,firestore:indexes,storage

O repositório não contém um mecanismo automatizado de rollback. Antes do deploy, registre a revisão anterior e faça mudanças de schema backward-compatible. Para Functions/Hosting, rollback é redeploy de uma revisão conhecida; para dados, prepare script reversível e dry-run. Rules e índices devem ser coordenados com clientes já publicados.

Backfills e scripts administrativos

• backfill:coupon-usage:dry-run é a inspeção padrão.
• backfill:coupon-usage:apply grava dados.
• grant:super-admin altera custom claims.
• seed/seed2 devem apontar exclusivamente para emuladores.

Sempre verifique projeto, credencial, host de emulador e quantidade prevista antes de qualquer escrita. Não execute scripts de produção a partir de uma documentação renderizada sem revisar a fonte atual.

Limites de verificação

Build local, testes e emuladores validam o checkout. Eles não provam deploy ativo, configuração do Console Firebase, Secret Manager, Stripe, App Check enforcement, DNS ou stores móveis.