Referência de engenharia · baseline master 1e981687

AiValeu

Documentação técnica do monorepo que sustenta o aplicativo cliente/parceiro, o painel Super Admin, o monitor de check-in, os packages compartilhados e o backend Firebase.

Flutter · Dart · BLoC/Cubit · GetIt · Firebase · Cloud Functions · Firestore · Stripe · Melos

Começar pelo ambiente Ver arquitetura

Fonte de verdade

Esta referência descreve a implementação observada na branch master, commit 1e981687f1dcd8553c2198b4b9faa8f1d4b31e43. Quando documentação histórica diverge do código, prevalecem implementação, testes e configuração executável.

Escolha seu ponto de entrada

• Começando

  Prepare Flutter, Melos, Node 22 e Firebase Emulator Suite sem depender de dados de produção.

• Arquitetura

  Entenda a separação entre apps, domínio puro, implementações Firebase e componentes compartilhados.

• Domínio

  Siga os fluxos de ofertas, ranking, cupons, check-in, campanhas, Premium e auditoria.

• Referência

  Consulte Functions, coleções, regras de segurança, Storage e Remote Config.

• Testes

  Execute as suítes Dart/Flutter, Jest e testes com emuladores.

• Operação

  Build, deploy, schedulers, Stripe, backfills e pontos conhecidos de diagnóstico.

Arquitetura em alto nível

flowchart LR
    C[App AiValeu\ncliente + parceiro] --> D[Domain\nentities + use cases]
    SA[Super Admin Web] --> D
    W[Waiter Desktop] --> D
    D --> R[Repository contracts]
    R --> DATA[Data\nFirestore + Functions]
    DATA --> FS[(Cloud Firestore)]
    DATA --> CF[Cloud Functions\nNode.js 22]
    CF --> FS
    CF --> ST[Stripe]
    C --> RC[Remote Config\nvisual + versionamento]
    C --> UI[AiValeu UI\ndesign system]
    SA --> UI
    W --> UI

Princípios que aparecem no código

• O package aivaleu_domain não depende de Flutter nem Firebase.
• Regras críticas e mutações privilegiadas ficam em Cloud Functions, Firestore Rules ou use cases, não apenas na interface.
• O feed principal é offer-first; o mapa permanece store-first.
• coupon_redemptions é a fonte atual do ciclo de cupons; o fluxo legado generateCoupon está bloqueado.
• Remote Config controla apresentação, versões e flags não críticas; autorização e estado financeiro continuam no backend.
• Auditoria de ofertas preserva autoria real, inclusive quando um Super Admin age em nome de um parceiro.