Estrutura e extensão¶

Árvore de trabalho¶

apps/
  aivaleu_app/       cliente + parceiro
  waiter_desktop/    operação de check-in
  super_admin_web/   curadoria
packages/
  aivaleu_domain/    entidades, portas e casos de uso
  aivaleu_data/      modelos e adapters Firebase
  aivaleu_core/      serviços comuns
  aivaleu_ui/        design system
functions/
  index.js           exports Firebase
  src/               handlers e regras server-side
  tests/             Jest e emulator tests
context/             decisões e planejamento mantidos pela equipe

O diretório context/ ajuda a explicar intenção, mas o comportamento atual deve ser confirmado no código, testes, Rules e configurações executáveis.

Adicionar uma feature vertical¶

Defina ou reutilize entidade e contrato em aivaleu_domain.
Implemente o adapter/model em aivaleu_data.
Se houver mutação privilegiada, implemente uma Function com autorização explícita.
Atualize Rules e índices para leituras diretas necessárias.
Registre a composição no arquivo DI de cada app consumidor.
Implemente Cubit/BLoC e UI feature-first.
Cubra domínio, adapter, backend/Rules e estados de UI.
Atualize documentação e contexto quando a regra ou decisão mudar.

Adicionar um campo Firestore¶

Mapeie todos os escritores, não apenas o app:

flowchart LR
    Entity[Entidade] --> Model[Model from/to Firestore]
    Model --> Repo[Repository]
    CF[Cloud Functions] --> Doc[(Documento)]
    Repo --> Doc
    Rules[Rules] --> Doc
    Index[Index] --> Doc
    Test[Tests] --> Entity
    Test --> CF
    Test --> Rules

Campos server-owned precisam ser bloqueados nas Rules e omitidos dos patches de partner/client. Para dados legados, forneça default/leitura compatível antes de exigir o campo.

Adicionar um estado¶

Estados de oferta, cupom, campanha e participação aparecem em Dart, strings Firestore, Functions, Rules, queries, widgets e testes. Atualize a matriz completa. Um enum novo apenas no app não habilita a transição no backend.

Alterar uma callable¶

Prefira payload mínimo e derivação server-side. Preserve compatibilidade quando já há apps publicados:

aceite campo antigo durante a janela de migração;
retorne campos aditivos;
não renomeie código HttpsError sem atualizar consumidores;
versione algoritmo/metadados quando a ordem observável muda;
evite trusts em IDs de ownership enviados pelo cliente.

Convenções de segurança¶

Nunca importe firebase-admin no cliente.
Nunca use campo de documento como substituto de custom claim para Super Admin.
Nunca confie em Rules para proteger operações Admin SDK.
Não registre secrets, PIN em claro ou payload Stripe completo.
Use transaction para read-check-write concorrente.
Use serverTimestamp para eventos autoritativos.
Faça dry-run antes de backfill e mantenha execução idempotente.

Manutenção desta documentação¶

O Markdown em technical-docs/docs é a fonte. Ao mudar arquitetura, contrato, coleção, configuração, teste ou runbook:

atualize a página do componente, sem criar diário de implementação;
valide paths, símbolos e exemplos contra o checkout;
rode o build estrito;
inspecione desktop, viewport estreito, busca e ambos os temas;
não versione technical-docs/site, .venv ou dist.

.\technical-docs\.venv\Scripts\python.exe -m mkdocs build --strict -f technical-docs\mkdocs.yml