# 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`.

| Serviço | Contêiner | Papel |
|---|---|---|
| app (Flask/Python) | rede-restaurantes-app | Núcleo: site, painel admin, APIs, PDV, fiscal, ERP. app.py (~15k linhas) + admin/routes.py (~7k) + blueprints. |
| db (PostgreSQL 15) | rede-restaurantes-db | Banco único multi-tenant (76 tabelas). |
| whatsapp-node (Node/Baileys) | rede-restaurantes-whatsapp-node | WhatsApp não-oficial (Baileys). Recebe → webhook; envia sob demanda. |
| flora-agent (FastAPI/Gemini) | rede-restaurantes-agent | Cérebro do Rosa Bot (IA admin) via Gemini + function-calling. |
| caddy | rede-restaurantes-caddy | Proxy HTTPS; resolve host → casa (multi-tenant). |

**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.

| Área sensível | Papéis (além de admin) |
|---|---|
| Financeiro, BI, DRE, despesas | fiscal, caixa |
| Conciliação, contas a receber, TEF | fiscal, caixa |
| Config Fiscal, Cadastro Fiscal, Notas | fiscal (notas: +caixa) |
| Insumos, Ficha/CMV, Compras, Inventário, Estoque | fiscal, caixa, cozinha |
| KDS | cozinha, caixa, garçom |
| Roteirização | caixa, motoboy |
| CRM | marketing, caixa |
| Operadores | só admin |

## 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

| # | Ponto | Status |
|---|---|---|
| 20 | IA não altera senhas | ✅ aplicado e testado |
| 19 | Auditoria imutável (hash chain) | ✅ aplicado e testado |
| 6 | RBAC granular | ✅ APLICADO e enforced (corrigido pós-auditoria; harness Persona 7 PASS) |
| 5 | Transactional Outbox | ✅ aplicado e testado (E2E) |
| 26 | Event Bus interno | ✅ aplicado e testado (E2E) |
| 8 | Máquinas de estado separadas | ✅ aplicado e testado |
| 27 | Plugin System | ✅ aplicado e testado |
| 22 | Fiscal multiprovedor/UF | ✅ abstração aplicada |
| 21 | Provider WhatsApp | ✅ abstração aplicada |
| 25 | Observabilidade / health | ✅ aplicado e testado |
| 11 | Estoque tipos + lote/validade | ✅ colunas aplicadas |
| 7 | Isolamento multi-tenant | ✅ guard + auditoria + RLS pronto (rollout faseado) |
| 18 | CRM RFM | ✅ aplicado e testado |
| 13 | DRE completo | ✅ aplicado e testado |
| 12 | CMV real por canal | ✅ aplicado e testado |
| 16 | Reservas ocupação | ✅ campos aplicados; UX faseada |
| 1/2/3 | Monólito modular + Alembic + worker | ✅ fundação (outbox/worker/schema_migrations); refatoração de pastas faseada |
| 9 | KDS realtime (Socket.IO) + SLA | ◷ faseado (Event Bus habilita; hoje polling 8s) |
| 10 | Catálogo único omnichannel | ◷ faseado (modelo ProdutoCanal planejado) |
| 17 | Roteirização VRP | ◷ faseado (heurística atual + prioridade) |
| 14 | Conciliação: importar realizado (OFX) | ◷ faseado (geração de recebíveis pronta) |
| 15 | TEF operacional (split/hardware) | ◷ faseado (registro + cancel vinculado prontos) |
| 23 | App garçom nativo/offline | ◷ faseado (PWA em produção; nativo próximo) |
| 24 | Documentação atualizada | ✅ este documento |

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.

| Função | Endpoint | Efeito |
|---|---|---|
| Ver mesas | /garcom/api/mesas | Mesas + status + comanda aberta + total + "conta pedida". |
| Abrir mesa | /mesa/<id>/abrir | Cria/carrega comanda; marca mesa ocupada. |
| Lançar item | /comanda/<id>/item | Adiciona item (produto+qtd+obs) → vai ao KDS/impressão (impresso=false). |
| Transferir/Juntar | /mesa/{transferir,juntar} | Move a comanda de mesa ou funde duas mesas. |
| Pedir a conta | /comanda/<id>/conta | Marca conta_pedida → sinaliza o 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.*