7. Plataforma — Event Bus, Outbox, State Machines & Plugins
Camada de arquitetura que transforma o sistema de "aplicativo" em plataforma (aplicada a partir da auditoria de 27 pontos).
7.1 Event Bus interno + Transactional Outbox (#5/#26)
Tudo relevante vira evento. Publicar um evento grava uma linha na tabela outbox_eventos na MESMA transação do negócio (o "pedido salvo" e o "evento salvo" acontecem juntos ou nenhum). Um worker (no scheduler, a cada tick) lê o outbox e entrega a cada assinante registrado, com retry exponencial e idempotência (idempotency_key única). Módulo novo só faz event_bus.subscribe('pedido_entregue', handler) — não altera o resto. Código: services/event_bus.py; observabilidade em /admin/api/eventos. Eventos emitidos hoje: pedido_em_preparo|pronto|saiu_entrega|entregue.
7.2 Máquinas de estado separadas (#8)
O pedido tem eixos paralelos, cada um com sua máquina: payment_status (pending→authorized→paid→refunded), production_status (queued→preparing→ready→handed_off), delivery_status (unassigned→on_route→delivered), fiscal_status (not_required→processing→authorized). Sincronizados no motor de transição. Permite "pago, parcialmente pronto, nota autorizada, aguardando motoboy".
7.3 Plugin System (#27)
Cada integração vira um plugin em plugins/<nome>/ com uma função register(registry) que registra rotas (blueprint), assinantes de evento, itens de menu, webhooks e tarefas. Carregado no boot (services/plugins.py), à prova de falha (um plugin quebrado não derruba o app). Assim Stone/iFood/PowerBI/OpenAI viram pacotes plugáveis. Exemplo em plugins/exemplo_analytics.py.
7.4 Abstrações de provider (#21/#22)
- WhatsApp (
services/whatsapp_provider.py): interfaceProviderWhatsApp(send_text/send_media/mark_read) comBaileysProvider(atual) eMetaCloudApiProvider(esqueleto). Migrar para a API oficial não muda nenhuma regra de IA/CRM. - Fiscal (
services/fiscal_provider.py):FiscalProvider(ENotasProvider hoje; FocusNFe/SEFAZ depois) +TaxEngine(RegimeNormal/CST e SimplesNacional/CSOSN), escolhidos por casa. Desacopla UF/regime/provedor.
7.5 Migração formal (#1/#2/#3)
Tabela schema_migrations (histórico versionado — ponte para Alembic). O modelo alvo é o monólito modular por domínio (orders/catalog/pdv/kitchen/…); o Event Bus já é o mecanismo de desacoplamento entre eles.
Versão para IA/crawler: /manual.md (Markdown cru) · /manual/completo (página única) · /sitemap.xml