Rosa Mexicano — Manual Técnico Completo do Sistema

Plataforma tudo-em-um para restaurante (multi-tenant): pedido, PDV, cozinha, delivery, fiscal (NFC-e), financeiro/ERP, IA no WhatsApp e site.

Este documento descreve cada aba, o que ela faz, as automações invisíveis, os endpoints/rotas, os modelos de dados e os trâmites de cada fluxo.

Escala: 38 abas · 8 seções · ~497 rotas · 76 tabelas · 31 migrações automáticas · 5 serviços Docker.

Índice (menu do painel, na ordem real)

Visão geral: Dashboard · Financeiro/Métricas · BI · Despesas/Contas a pagar · Contas a receber · Conciliação financeira · TEF/Maquininha

Operacional: Caixa & Salão (PDV) · Pedidos · KDS/Cozinha · Reservas · Vale-Presente · Rastreamento · Roteirização

Delivery & Cardápio: Cardápio/Delivery · Produtos da Casa · Estoque · Insumos & Fornecedores · Ficha Técnica & CMV · Compras · Inventário · Motoboys · Config. de entregas

Atendimento & Clientes: Suporte Whats (Estufa) · Suporte · Clientes · Avaliações

Conteúdo & Marketing: Editor de Site · Marketing · CRM · Mensagens do Bot

Rosa Bot (IA): Rosa Bot · Aprovações do Bot · (El Bigodón no WhatsApp)

Configurações: Checkout & Pagamentos · API de Mapas · Empresa/Fiscal · Config. Fiscal · Notas Fiscais · Cadastro Fiscal · Impressoras · Operadores · Auditoria/Logs

Conta: Webmail · Administrador · Sair

1. Visão geral & arquitetura

Monólito Flask servido atrás de proxy, com serviços auxiliares em contêineres. Stack Docker autocontido em /home/andrew/rede-restaurantes.

Blueprints: app (raiz, 213 rotas) · admin_bp (/admin, 196) · estufa_bp (/admin/estufa, 20) · rastreio_bp (31) · garcom_bp (/garcom, 13) · agent_public_bp (4) · agent_internal_bp (ferramentas da IA) · mobile_api (/api/mobile, 20).

2. Infra, deploy & multi-tenant

• Deploy sem rebuild: código bind-mount; sudo docker restart rede-restaurantes-app (~7s). Armadilha: o compose bind-monta arquivos individuais — todo módulo novo precisa entrar no volumes: do docker-compose.yml (ex.: garcom_routes.py).
• Multi-tenant: cada restaurante é uma linha em casas (slug único). casa_atual() resolve por sessão em /admin e /garcom, e por host no site público. Quase toda tabela tem casa_id. Config por casa em casas.empresa_config (JSON).
• Migrações automáticas: no boot, db.create_all() + 31 funções _ensure_* que fazem ALTER TABLE idempotente (ex.: _ensure_operador_papel_column, _ensure_kds_columns, _ensure_pedido_producao_columns).

3. Permissões por operador (RBAC)

Cada operador tem um papel: admin, caixa, garcom, cozinha, motoboy, marketing, fiscal. O papel entra na sessão no login (master = admin).

Automação: @admin_bp.before_request chama _papel_pode(path) contra _ROTAS_RESTRITAS → 403 real no backend (não só menu escondido). Menu some via pode_area() (context processor global, funciona fora do admin_bp).

Além do papel (RBAC granular, §8): cada operador também tem permissoes (JSON com chaves finas — pedido.cancelar, caixa.reabrir, estoque.ver_custo…), limite_desconto e unidades (escopo por filial). Helpers _pode_permissao() / _limite_desconto_operador(). O papel é o default; a permissão fina refina.

4. Automações invisíveis — o motor do sistema

4.1 Scheduler em background (thread fn-scheduler, tick 60s)

• _carrinho_job_abandonar (15 min): marca carrinhos parados como abandonados.
• _carrinho_job_regua (30 min): régua de recuperação de carrinho.
• _reservas_job_liberar_vencidas (5 min): libera mesas de reservas sem check-in dentro da tolerância.
• event_bus.processar_outbox (cada tick): worker do Event Bus — entrega os eventos pendentes do outbox_eventos aos assinantes com retry exponencial (ver §7.1).
• _push_job_agendados (1 min): envia push agendados via Firebase.

Nota de arquitetura: este scheduler in-process é o worker atual. A fundação (outbox + idempotência + retry) já está pronta para extrair um serviço/worker dedicado (Celery/Dramatiq/RQ) sem reescrever a lógica — ver §7.5 e o roadmap (§10).

4.2 Agente local de impressão (polling)

Agente no balcão faz polling em /api/agente/fila-impressao (header X-Agente-Token). Backend devolve em ESC/POS base64 por estação. Salão: itens de comanda não impressos. Delivery: pedidos aceitos (idempotente via producao_impressa). Piggyback fiscal: a cada poll resolve NFC-e pendentes (_atualizar_notas_processando, throttle 90s) → nota vira autorizada+XML sem abrir tela.

4.3 Motor único de produção + fluxo de status

_aplicar_transicao_status(pedido, status): carimba o horário de cada etapa (aceito_em/pronto_em/saiu_em/entregue_em), dispara o WhatsApp transacional por etapa (idempotente por flag = anti-ban) e publica o evento no Event Bus (pedido_em_preparo|pronto|saiu_entrega|entregue, ver §7.1). Acionado no Caixa/Pedidos, modal e app do motoboy. Textos editáveis em Mensagens do Bot.

Importante (arquitetura atual): o "status" não é mais um único campo linear. O pedido tem máquinas de estado SEPARADAS — payment_status, production_status, delivery_status, fiscal_status — sincronizadas neste motor (ver §7.2). Isso permite estados como "pago, parcialmente pronto, nota autorizada, aguardando motoboy".

4.4 Fechamento amarrado

Pedido aceito ou comanda fechada dispara em cadeia (idempotente): baixa de estoque → emissão NFC-e (gated) → impressão de produção → alimenta financeiro/relatórios.

4.5 Webhooks assíncronos

• /webhooks/mercadopago: confirma pagamento do site (PIX/cartão) → aprova pedido, credita fidelidade, e-mail.
• /webhooks/infinitepay: confirma cartão do app Android.
• /webhooks/asaas: gateway de teste (parado; não remover).
• /admin/estufa/api/webhook/whatsapp: mensagem recebida → Estufa → dispara El Bigodón (se ligado).
• Resend: eventos de e-mail.

4.6 Fidelidade, carteira & cashback

Pedido entregue/pago → _creditar_fidelidade_pedido (pontos+cashback, idempotente). Cancelado → _carteira_estornar_pedido. Carteira abate no checkout.

4.7 Editor de site ao vivo (after_request)

@app.after_request injeta o overlay do Editor quando admin acessa com ?editor=1 e aplica overrides salvos no site vivo. Outro after_request aplica cache longo a estáticos versionados.

5. Pipeline fiscal — NFC-e (modelo 65)

Emissão para Santa Catarina (NFC-e; SAT não se aplica). Empresa Regime Normal (CRT 3) → CST (não CSOSN). Provedor: eNotas (assíncrono).

Desacoplado (§7.4): o núcleo fiscal fala com abstrações — FiscalProvider (eNotas hoje; FocusNFe/SEFAZ direto depois) e TaxEngine (RegimeNormal/CST e SimplesNacional/CSOSN), escolhidos por casa. UF/regime/provedor deixam de ser fixos. Código em services/fiscal_provider.py.

Estratégia série 2: a NFC-e do sistema sai em série 2; o Hubzy fica na série 1 (mesmo CNPJ/cert/CSC, sem colisão). Roda em paralelo sem afetar o Hubzy.

Trâmite: (1) venda consumada chama _emitir_nfce_*; (2) gate: só emite se config pronta (_fiscal_config_casa) e canal habilitado; (3) monta payload com dados fiscais por produto → cria NotaFiscal 'processando'; (4) _atualizar_nota_fiscal consulta eNotas → autorizada (grava chave/protocolo/DANFE/XML) ou rejeitada; (5) falha vira 'erro' → reenviar; contabilidade baixa ZIP por período separado por status.

Segredos: chave da API, senha do certificado e CSC são criptografados (Fernet, derivado do SECRET_KEY) — nunca em texto puro. Certificado A1 (.pfx) validado por pkcs12.

6. Stack tecnológico completo — linguagens & bancos

5 contêineres: postgres:15-alpine (SQL) · python:3.11-slim/app (Flask 2.3 + SQLAlchemy 2.0 + Socket.IO) · node:20-alpine/whatsapp (Express + Baileys) · python:3.11-slim/agent (FastAPI + uvicorn) · caddy:2-alpine (proxy HTTPS).

6.1 Linguagens — das menos às mais usadas

1. glTF/GLB — modelo 3D do pin oficial (MapaCore).

2. Caddyfile (DSL) — proxy HTTPS.

3. Áudio (WAV/MP3) / vídeo (MP4) — sons de alerta, mídias.

4. TOML/INI/.properties — config de build Android + envs.

5. Gradle Kotlin DSL (.kts)/Gradle — build dos apps Android.

6. Shell (bash .sh) — scripts de deploy/manutenção.

7. YAML — docker-compose.yml.

8. Dockerfile — 3 imagens (app, agent, whatsapp).

9. SQL puro — seeds/patches (seed/flora_seed.sql, apps/*/backend-patch/migrations.sql) + ALTER TABLE das migrações.

10. XML — recursos e manifests dos apps Android.

11. Java — Maps Gateway (Quarkus native) + partes Android.

12. Kotlin — apps nativos Android (dashboard-mobile/admin, motoboy, MapaCore) — 254 arquivos .kt.

13. CSS3 — estilos de todas as telas, responsivo, tema claro/escuro.

14. Jinja2 — templating do Flask (~109 páginas HTML).

15. JSON — APIs, empresa_config, colunas JSON no Postgres, config server-driven.

16. SQL via SQLAlchemy (ORM) — toda a persistência: 76 modelos, dialeto PostgreSQL.

17. JavaScript — front (vanilla + Alpine.js), PWA/service workers, tempo real (Socket.IO), mapas (MapLibre/Leaflet) e o serviço Node (Baileys).

18. HTML5 — estrutura de todas as telas.

19. Python 3.11 — a mais usada: núcleo Flask (app.py ~15k + admin ~7k + blueprints) + agente FastAPI. Toda a lógica de negócio, fiscal, ERP, IA e automações.

Libs Python: Flask, Flask-SQLAlchemy, Flask-SocketIO, Flask-CORS, Flask-Limiter, SQLAlchemy 2.0, Werkzeug, cryptography (Fernet), Pillow (webp), fpdf2 (PDF), psycopg2, httpx/requests, mercadopago, resend, firebase-admin, PyJWT, svix, twilio. Agente: FastAPI/uvicorn/pydantic. Node: Baileys/Express/axios/pino.

Libs front: Alpine.js, Socket.IO client, MapLibre GL, Leaflet, Chart.js.

6.2 Bancos & armazenamento — dos menos aos mais usados

1. Firebase (FCM) — push notifications (guarda tokens de dispositivo).

2. Sessão (cookie assinado) — login, casa, papel (via SECRET_KEY).

3. Volumes em disco — mídia da Estufa, uploads, certificados A1, sessões Baileys, dados Caddy.

4. RedisJSON — cache L2 do Maps Gateway (stack separado, via URL+token).

5. PostgreSQL 15 — o banco principal: as 76 tabelas (multi-tenant por casa_id), colunas JSON.

Camada de mapas (stack próprio): Maps Gateway em Quarkus (Java native) + RedisJSON, servindo OSRM (rotas) e Photon/Nominatim (geocode) com token/quota por casa. Alimenta rastreio, roteirização e app do motoboy.

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): interface ProviderWhatsApp (send_text/send_media/mark_read) com BaileysProvider (atual) e MetaCloudApiProvider (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.

8. Segurança & confiabilidade

• #20 IA nunca define senha: a ferramenta de senha do Rosa Bot foi reescrita para disparar o fluxo seguro de redefinição (token + e-mail); a IA não acessa hash nem define senha arbitrária.
• #19 Auditoria imutável: admin_audit_log tem cadeia de hash (hash_atual = SHA256(hash_anterior + evento)). Editar/apagar qualquer linha quebra a cadeia das seguintes. Verificação em /admin/api/auditoria/verificar (aponta a 1ª linha adulterada).
• #6 RBAC granular (APLICADO — corrigido pós-auditoria): além do papel, o operador tem permissoes (JSON: pedido.cancelar, caixa.reabrir, estoque.ver_custo, comanda.desconto_sem_limite, fiscal.cancelar_nfce…), limite_desconto e unidades. O modelo Operador mapeia essas colunas e os gates são efetivamente consultados (call-sites reais): cancelar pedido exige pedido.cancelar (403 sem); custo de insumo/CMV some para quem não tem estoque.ver_custo (padrão negar); desconto acima do limite_desconto do operador é barrado (salvo comanda.desconto_sem_limite). Configurável na tela Operadores (checkboxes + limite). Ações têm padrão PERMITIR (o papel governa; só nega quem estiver marcado False); visualização de custo tem padrão NEGAR. Provado por harness E2E (Persona 7: PASS).
• #7 Isolamento multi-tenant: guarda defensiva _tenant_guard() + auditoria de superfície /admin/api/tenant/auditoria (quais tabelas têm/não têm casa_id) + script RLS pronto (services/rls_tenant.sql) para rollout por tabela.
• #25 Confiabilidade: health check em /health e /healthz (app + banco + backlog do outbox). Observabilidade do Event Bus em /admin/api/eventos.

9. Financeiro & operação — aprofundamentos

• #13 DRE completo em camadas (/admin/api/financeiro/dre): receita bruta → (−) cancelamentos/descontos/impostos → receita líquida → (−) CMV → lucro bruto → (−) taxas de adquirente/entrega → margem de contribuição → (−) pessoal/ocupação/operacionais → EBITDA → resultado líquido.
• #12 CMV/margem real por canal (_cmv_produto(produto, canal_custos)): além dos ingredientes, desconta embalagem + taxa do adquirente/canal + imposto + comissão → margem de contribuição verdadeira por canal.
• #18 CRM RFM (/admin/api/crm/rfm): score R/F/M 1-5 + segmentos de comportamento (Campeões, Leais em risco, Novos, Não posso perder, Em risco/Perdidos).
• #11 Estoque inteligente: insumos têm tipo (insumo/semiacabado/acabado) + lote/validade/local (base para FEFO e produção de semiacabados).
• #16 Reservas — ocupação: no_show, duracao_prevista_min, waitlist, ocasiao (base para lista de espera, score de no-show e otimização de ocupação).

10. Roadmap de arquitetura — status dos 27 pontos da auditoria

Legenda: ✅ aplicado · ◷ faseado (fundação no lugar).

AS 38 ABAS, UMA A UMA

Visão geral

◆ Dashboard — /admin

Painel de abertura com KPIs + "Painel rápido" (chips com pedidos pendentes, e-mails não lidos, chats abertos) no topo de todas as abas. Métricas úteis (30d): ticket médio, pedidos válidos, cancelamentos, canais (delivery/retirada/salão), tempo médio de preparo (aceito→pronto) e de entrega (saiu→entregue), pico e mais vendidos.

$ Financeiro / Métricas — /admin/financeiro

Receita, formas de pagamento, ticket, série temporal, conciliação de caixa, exportações (CSV/PDF/e-mail/WhatsApp). DRE em camadas (/admin/api/financeiro/dre, §9/§13): receita bruta → (−) cancelamentos/descontos/impostos → receita líquida → (−) CMV → lucro bruto → (−) taxas de adquirente/entrega → margem de contribuição → (−) pessoal/ocupação/operacionais → EBITDA → resultado líquido. Não é mais "receita − despesa".

📈 BI · Inteligência — /admin/bi *(novo)*

_bi_analytics calcula: curva ABC (A até 80% acumulado, B até 95%, C resto; o item que cruza 80% ainda é A); margem/lucro por produto (via CMV); previsão de estoque (consumo = ficha × qtd vendida → dias até acabar); queda de venda (última semana < 60% da média); campeão sem lucro (classe A/B margem <15%); pico por categoria.

🧾 Despesas / Contas a pagar — /admin/financeiro/despesas

CRUD de despesas (criar/pagar/excluir) com categorias, fornecedor, vencimento, recorrência. Tiles: pago no mês/a pagar/vencidas. Modelo Despesa. Alimenta lucro líquido e DRE.

💵 Contas a receber — /admin/contas-receber *(novo)*

Recebíveis por cliente/forma com bruto, taxa%, líquido, data de liquidação, status e baixa (individual/lote). Atraso por vencimento. Modelo Recebivel.

🏦 Conciliação financeira — /admin/conciliacao *(novo)*

Vendido × taxa × líquido × recebido × a receber, por forma/adquirente + editor de taxas/prazos. Automação: "Gerar recebíveis" (_gerar_recebiveis_pedidos) varre pedidos pagos e cria Recebivel aplicando taxa/prazo por forma (config fin_taxas). Ex.: R$100 crédito 3,2% → líquido R$96,80, liquidação +30d.

💳 TEF / Maquininha — /admin/tef *(novo)*

Registra transação da maquininha (valor, forma, parcelas, bandeira, adquirente, NSU, autorização) — modo manual ou negada. Automação: aprovada vira Recebivel conciliável (_tef_para_recebivel); cancelar zera transação + recebível. Modelo TefTransacao. Pronto para agente pinpad/SmartPOS.

Operacional

🧾 Caixa & Salão (PDV) — /admin/caixa

PDV completo do salão: planta visual em 3 setores (mesas em %), abrir/gerir comandas, juntar/transferir mesas, agrupar itens, conta dividida em vias por %, cashback individual/global. Sessão de caixa (CaixaSessao), sangria/suprimento (CaixaMovimento), fechamento cego, gate de caixa aberto, auditoria (CaixaAuditLog). Fechar comanda dispara o fechamento amarrado (estoque + NFC-e presencial + impressão).

▣ Pedidos — /admin/pedidos

Pedidos delivery/retirada em tempo real (alarme sonoro). Aceitar, mudar status, reativar, lixeira (soft-delete 30d). Ao aceitar: status em_preparo, carimba aceito_em, WhatsApp ao cliente, baixa estoque, emite NFC-e (gated). Entregue → credita fidelidade. Cancelar → estorna carteira.

🍳 KDS · Cozinha — /admin/kds *(novo)*

Painel vivo (auto-refresh 8s) com colunas Em produção/Prontos, abas por estação. Cada ticket: itens, obs, tempo decorrido, vermelho quando atrasa (>25 min). Fontes: delivery (pedidos em_preparo/pronto, item→estação via Arranjo.estacao) e salão (ComandaItem.kds_status: novo/preparo/pronto/entregue). Ações: Pronto (delivery → motor de status → WhatsApp; salão marca itens), Entregue (sai da tela), Reimprimir.

🍽️ Reservas — /admin/reservas

Mapa visual (%), seleção de mesas, janela de chegada e tolerância. Crédito de Reserva (ex.: R$25/adulto) por PIX/cartão/carteira que vira consumação; sem dinheiro não bloqueia a mesa. Liberação automática pelo scheduler (5 min) para mesas sem check-in. Reserva confirmada → WhatsApp. Modelos: Reserva, ReservaMesa, Area, MesaVizinho, ReservaLog.

🎁 Vale-Presente — /admin/vale

Emissão/gestão: recibo, operador/baixa, compra anônima, recuperar/excluir, travas. Ao pagar, o presenteado recebe por e-mail (Resend) e WhatsApp com código. Modelo ValePresente.

📍 Rastreamento de entregas — rastreio_bp

Central de rastreio em tempo real + app do motoboy. Fila FIFO liga pedido↔motoboy (_casar_fila), oferta/aceite, GPS ao vivo, rota (OSRM), botão "Cheguei" (avisa cliente no WhatsApp), chat cliente↔motoboy, avisos operador→motoboy com confirmação. A posição do motoboy vive na API de mapas (token da casa). Modelos: Motoboy, RastreioSessao, MotoboyMensagem, EntregaMensagem.

🗺️ Roteirização inteligente — /admin/roteirizacao *(novo)*

Entregas pendentes agrupadas por proximidade em rotas otimizadas: nº paradas, distância, ETA, prioridade (por espera) + seletor de motoboy. Automação (_roteirizacao_plano): ordena por vizinho-mais-próximo da loja, quebra em grupos (máx 4 paradas ou salto >2,5 km), calcula distância/ETA (22 km/h + 6 min/parada). Despachar cria sessões de rastreio, muda pedido para saiu_entrega e avisa o cliente.

Delivery & Cardápio

🌮 Cardápio / Delivery — /admin/produtos

Produtos do delivery/site (Arranjo): nome, preço, categoria, foto (webp thumb+full), estação, complementos/adicionais. Cada produto carrega campos fiscais (NCM/CFOP/CEST/origem/CST/alíquotas) e de estoque.

🍽️ Produtos da Casa — /admin/produtos-casa

Itens do salão/PDV (ProdutoCasa): nome, preço, categoria, estação (cozinha/bar). É o cardápio que o garçom lança na comanda.

📦 Estoque — /admin/estoque *(novo)*

Controle por produto (opt-in): entrada/baixa/ajuste, mínimo, indicadores (ok/baixo/zerado). Automação: a venda baixa o estoque (idempotente). Diferente do estoque de insumos.

🧺 Insumos & Fornecedores — /admin/insumos *(novo)*

Cadastro de insumos (unidade, custo médio, estoque, mínimo, fornecedor) e fornecedores (CNPJ, contato). Base do CMV, compras e inventário. Modelos: Insumo, Fornecedor.

📐 Ficha Técnica & CMV — /admin/ficha-tecnica *(novo)*

Lista de produtos com custo (CMV), CMV%, margem R$ e margem%; editor de ficha (insumo + quantidade + % perda) com recálculo ao vivo. Motor (_cmv_produto): custo = Σ insumo.custo_médio × quantidade × (1 + perda/100). Ex.: 40×0,15×1,1 + 30×0,05 = R$8,10. Alimenta BI e previsão de estoque. Modelo FichaTecnicaItem. Margem REAL por canal (§9/§12): passando canal_custos, o motor desconta também embalagem + taxa do adquirente/canal + imposto + comissão e devolve a margem de contribuição verdadeira por canal.

🛒 Compras — /admin/compras *(novo)*

Pedidos de compra (fornecedor + itens + custo unitário), sugestão automática (insumos abaixo do mínimo, por fornecedor), recebimento. Entrada de mercadoria (_receber_compra): soma ao estoque + recalcula custo médio ponderado (ex.: (10×40+10×46)/20 = R$43) + grava histórico de preço. Idempotente. Modelos: CompraPedido, CompraItem, PrecoFornecedorHist.

📋 Inventário — /admin/inventario *(novo)*

Abrir contagem (snapshot do estoque), digitar contado (divergência ao vivo), fechar. Fechamento (_fechar_inventario): aplica contado ao estoque + valoriza a divergência (quebra/perda R$ = Σ (contado−sistema)×custo). Ex.: −2 kg × R$43 = −R$86. Auditado, sem desfazer. Modelos: InventarioContagem, InventarioItem.

🛵 Motoboys — /admin/motoboys

Cadastro de entregadores (nome, telefone, token do app, disponibilidade). Cada instalação gera um uuid. Alimenta fila de rastreio e roteirização. Modelo Motoboy.

📦 Configurações de entregas — /admin/entregas

Regras de taxa de entrega (grátis/por bairro/por km), raio, tempos. Alimenta o frete no checkout.

Atendimento & Clientes

🟢 Suporte Whats Rosa (Estufa) — /admin/estufa

Central omnichannel de WhatsApp (inbox): conversas, mídia, status/stories, envio, tempo real via Socket.IO. Node Baileys conecta o número do Rosa. Botão 🤖 El Bigodón liga/desliga a IA. Modelos: EstufaContato/Conversa/Mensagem/Status/Sessao. O envio passa pela abstração ProviderWhatsApp (§7.4) — Baileys é só a implementação atual; migrar para a API oficial da Meta não muda nenhuma regra de IA/CRM.

💬 Suporte (chat do site) — /admin/suporte

Chat de suporte do site (transbordo humano do El Bigodón). Sessões abertas/atendidas/encerradas. Modelos: ChatSessao, ChatMensagem.

◎ Clientes — /admin/clientes

Base de clientes (Usuario): dados, pedidos, pontos, cashback, nível, endereços, indicações, preferências. Fonte do CRM.

★ Avaliações — /admin/avaliacoes

Avaliações (nota + comentário) por pedido, para moderação/resposta. Modelo Avaliacao.

Conteúdo & Marketing

🎨 Editor de Site — /admin/editor-site

Editor visual ao vivo por página — clica no elemento e edita texto/imagem, override guardado (SiteConteudo: dados + dados_anterior para desfazer). Config global em SiteConfig. Injeção via after_request (§4.7). Modelos: SiteConfig, SiteConteudo, CmsPage.

↗ Marketing — /admin/marketing

Cupons (percentual/fixo, pedido mínimo, validade, 1-uso ou genérico), banner/pop-up (páginas e frequência), promoções. Cupons genéricos ou por cliente. Modelo Cupom.

👥 CRM · Clientes — /admin/crm *(novo)*

Três segmentos automáticos: Sumidos (>45 dias), VIP (≥5 pedidos ou ≥R$500), Aniversariantes do mês — com contagem/lista + medição de retorno (cupons auto gerados × usados). Campanha por perfil (_crm_segmentos + /campanha): gera cupom automático individual por cliente (ex.: VOLTA15-…, origem 'auto', validade), que aparece na conta do cliente. Anti-ban: sem disparo em massa por WhatsApp. Segmentação RFM (§9/§18, /admin/api/crm/rfm): score Recência/Frequência/Valor 1-5 + rótulos (Campeões, Leais em risco, Novos, Não posso perder, Em risco/Perdidos).

💬 Mensagens do Bot — /admin/mensagens-bot

Edição de todos os textos transacionais de WhatsApp (pedido aguardando/aceito/pronto/saiu/entregue, motoboy chegou, reserva confirmada, vale-presente) com tags. Padrões em _BOT_MSGS_DEFAULT, override por casa. Inclui controle de áudio das páginas.

Rosa Bot (IA)

🤖 Rosa Bot (IA admin) — /admin/rosa-bot

Chat administrativo com o agente Gemini. Consulta e altera dados (produtos/clientes/pedidos/senhas) via ferramentas internas com permissão. Escopo 'admin'. O flora-agent faz function-calling em /api/internal/agent/tools/* (auditadas em AgentAuditLog, rate-limit em AgentRateLimit).

✅ Aprovações do Bot (HITL) — /admin/aprovacoes

Human-in-the-loop: ações sensíveis que a IA propõe ficam pendentes de aprovação humana (badge de contagem). Modelo AgentHitlRequest.

🌮 El Bigodón — IA no WhatsApp *(novo)*

Persona El Bigodón atendendo clientes no WhatsApp, reativo (só responde quando o cliente escreve; nunca inicia/dispara em massa = anti-ban). Fluxo: mensagem no webhook da Estufa → se master ligado, dispara thread com request context → _chamar_agente('suporte', …) com ferramentas de dados reais (cardápio, horário, status do pedido, reserva) → envia pelo node e salva na Estufa. Travas: master desligado por padrão (botão na Estufa); pausa quando humano assume; chama atendente em pagamento/reclamação/cancelamento/desconto; oferece humano após muitas trocas; nunca confirma pagamento nem altera reserva. Tom ajustado para WhatsApp.

Configurações

💳 Checkout & Pagamentos — /admin/pagina-checkout

Config do checkout e credenciais por casa. Regra: site = Mercado Pago (PIX+cartão); app Android = InfinitePay no cartão. Asaas = gateway de teste. Cartão/pagar na entrega/PIX mantidos.

🗺️ API de Mapas — /admin/maps-api

Gestão do Maps Gateway próprio (Quarkus native + RedisJSON): tokens por casa, quota, dogfood. OSRM (rota), Photon/Nominatim (geocode) como API central, fora do código do cliente.

🏢 Empresa / Fiscal — /admin/empresa

Dados cadastrais (razão social, CNPJ, IE, endereço, CNAE, telefone) + flags. Guardado em casas.empresa_config (JSON).

🧾 Config. Fiscal · NFC-e — /admin/fiscal-config *(novo)*

Tudo para emitir: CNPJ/IE/CSC/série/ambiente + upload do certificado A1 (.pfx, validado) + chave da API eNotas + enotas_empresa_id. Banner pronto/faltando. Plug-and-play: replicar para outro restaurante = preencher + subir cert + salvar. Segredos criptografados (Fernet).

📑 Notas Fiscais · Contabilidade — /admin/notas-fiscais *(novo)*

Lista + filtro por status/período, download XML/DANFE, ZIP por período separado por status (autorizadas/canceladas/negadas/inutilizadas) para o contador, cancelamento (justificativa), inutilização de faixa (histórico), reenviar (recuperação). Poll das processando ao abrir.

🧾 Cadastro Fiscal (por produto) — /admin/fiscal-produtos *(novo)*

Campos fiscais de cada produto (delivery e salão): NCM, CFOP, CEST, origem, CST + alíquotas ICMS/PIS/COFINS. Atalhos "padrão comida" e "monofásico (bebidas 04/0%)". Entram no payload da NFC-e.

🖨️ Impressoras — /admin/impressoras

Impressoras por estação (cozinha/bar/caixa) com largura (58/80mm). O agente local usa esse mapa. Base do KDS e da impressão automática. Modelo Impressora.

👥 Operadores — /admin/operadores

Usuários do painel: criar (com papel), trocar papel inline, redefinir senha, ativar/desativar, excluir. Só admin. Alterações vão à Auditoria. Modelo Operador.

📝 Auditoria / Logs — /admin/auditoria *(novo)*

Histórico de quem alterou o quê — config fiscal, despesas, estoque, notas, insumos, compras, inventário, recebíveis, TEF, roteirização, CRM, papéis — com operador, IP, alvo, ação, detalhe (JSON), filtrável. Registro à prova de falha (_audit_admin). Modelo AdminAuditLog.

Conta

✉ Webmail — /admin/webmail

Caixa de e-mail integrada (entrada/enviados), templates transacionais, eventos de entrega. Infra Resend no domínio @cheffzy.com.br (mantida até verificar o domínio do Rosa). Envia comprovantes, boas-vindas, vale-presente, recuperação de senha. Modelos: EmailMensagem, EmailAnexo, EmailEvento, EmailTemplate, TokenEmail.

Apêndice A — PWA do Garçom (garcom_bp, /garcom)

App web mobile instalável (manifest + service worker) para o salão, fora do chrome do admin. Requer operador logado. Opera nos mesmos modelos do Caixa.

Ecossistema de apps (status real): PWA do Garçom — produção; App Android do Garçom — beta/conclusão; App Android do Motoboy — produção (rastreio_bp + GPS ao Maps Gateway); App Android do Cliente — produção (mobile_api + Firebase); Painel Android Administrativo (dashboard-mobile, Kotlin) — produção/beta. O app nativo de delivery é a fase seguinte. Todos consomem as mesmas APIs Python deste manual.

Apêndice B — Modelo de dados (76 tabelas)

• Casa & operação: casas, operadores, mesas, comandas, comanda_itens, comanda_pagamentos, caixa_sessoes, caixa_movimentos, caixa_audit_log, impressoras.
• Reservas: reservas, reserva_areas, reserva_mesas, mesa_vizinhos, reserva_logs.
• Clientes & fidelidade: usuarios, favoritos, cliente_atividades, indicacoes, enderecos, preferencias_clientes, vale_presentes, carteira_transacoes, cartoes_salvos, cupons, carrinhos_abandonados, push_notificacoes, avaliacoes.
• Cardápio: arranjos, categorias, complemento_grupos, produtos_casa.
• Pedidos & entrega: pedidos, motoboys, rastreio_sessoes, motoboy_mensagens, entrega_mensagens.
• Financeiro & fiscal: despesas, notas_fiscais, recebiveis, tef_transacoes, admin_audit_log (com hash_anterior/hash_atual = cadeia imutável, §8).
• Plataforma (novo, §7): outbox_eventos (Event Bus/Transactional Outbox — tipo, payload, idempotency_key, status, tentativas, proxima_em/backoff) · schema_migrations (histórico de versão do schema). Arquivos: services/event_bus.py, services/plugins.py + plugins/*, services/fiscal_provider.py, services/whatsapp_provider.py, services/rls_tenant.sql. Colunas novas: pedidos.payment_status/production_status/delivery_status/fiscal_status (§8); operadores.permissoes/limite_desconto/unidades (§6); insumos.tipo/lote/validade/local (§11); reservas.no_show/duracao_prevista_min/waitlist/ocasiao (§16).
• ERP (suprimentos): fornecedores, insumos, ficha_tecnica_itens, compra_pedidos, compra_itens, preco_fornecedor_hist, inventario_contagens, inventario_itens.
• E-mail/conteúdo/IA: email_mensagens, email_anexos, email_eventos, email_templates, tokens_email, site_config, site_conteudo, cms_pages, agent_audit_log, agent_hitl_requests, agent_rate_limit.
• WhatsApp (Estufa) & chat: estufa_contatos, estufa_conversas, estufa_mensagens, estufa_status, estufa_sessoes, contato_whatsapp, chat_sessoes, chat_mensagens, feed_assinantes, dispositivos_fcm_admin.

Apêndice C — Apps cliente & APIs externas

• Site público — loja, cardápio, carrinho, checkout, reservas, rastreio, galeria; multi-tenant por host.
• App Android do cliente — via mobile_api (20 rotas) + Firebase (push); cartão por InfinitePay.
• App do motoboy — via rastreio_bp; GPS direto ao Maps Gateway.
• PWA do garçom — Apêndice A.
• Integrações: eNotas (NFC-e), Mercado Pago/InfinitePay/Asaas (pagamento), Resend (e-mail), Google Gemini (IA), Baileys (WhatsApp), OSRM/Photon/Nominatim (mapas), Firebase (push).

*Manual gerado a partir do código em produção. 38 abas · ~497 rotas · 76 tabelas · 5 serviços Docker. Funcionalidades marcadas "novo" foram construídas e testadas ponta a ponta. Próxima fase (separada): apps nativos de delivery e garçom.*

Referências exaustivas (auto-geradas do código): todas as rotas · tabelas & colunas · funções · arquivos. Índice: /manual.

Versão para IA/crawler: /manual.md (Markdown cru) · /manual/completo (página única) · /sitemap.xml