Módulos NestJS

Arquitetura

O backend é organizado em módulos autocontidos, cada um com sua própria responsabilidade.

Módulos

Auth

Responsabilidade: Autenticação JWT e registro de usuários.

Rotas:

• POST /api/auth/register - Registro global (primeiro usuário → superadmin)
• POST /api/auth/login - Login
• GET /api/auth/me - Dados do usuário atual

Rotas por tenant:

• POST /t/:slug/auth/register - Registro no tenant (primeiro → admin)
• POST /t/:slug/auth/login - Login no tenant

Users

Responsabilidade: Gerenciamento de usuários.

Rotas:

• GET /t/:slug/users - Listar usuários
• POST /t/:slug/users - Criar usuário
• PUT /t/:slug/users/:id - Atualizar usuário
• DELETE /t/:slug/users/:id - Deletar usuário

Tenants

Responsabilidade: Gerenciamento de tenants (superadmin).

Rotas:

• GET /api/superadmin/tenants - Listar todos
• POST /api/superadmin/tenants - Criar
• PUT /api/superadmin/tenants/:id - Atualizar
• PUT /api/superadmin/tenants/:id/toggle - Ativar/desativar

Menu

Responsabilidade: Cardápio (categorias e itens) e preços agendados.

Rotas:

• GET /t/:slug/menu/categories - Categorias
• POST /t/:slug/menu/categories - Criar categoria
• GET /t/:slug/menu/items - Itens (público)
• POST /t/:slug/menu/items - Criar item (admin)
• POST /t/:slug/menu/price-schedules - Criar agendamento de preço
• GET /t/:slug/menu/price-schedules - Listar agendamentos
• PUT /t/:slug/menu/price-schedules/:id/cancel - Cancelar agendamento

Orders

Responsabilidade: Pedidos, comandas de mesa e fechamento de conta.

Rotas:

• GET /t/:slug/orders - Listar pedidos (BranchScopeGuard)
• POST /t/:slug/orders - Criar pedido (público)
• GET /t/:slug/orders/open-tab/:tableId - Buscar comanda aberta de uma mesa
• PATCH /t/:slug/orders/:id/add-items - Adicionar itens à comanda
• POST /t/:slug/orders/:id/close-tab - Fechar comanda (status → delivered). Calcula netAmount e taxSummary com base no TaxEngine.
• PUT /t/:slug/orders/:id/status - Atualizar status

Reservations

Responsabilidade: Reservas de mesas.

Rotas:

• GET /t/:slug/reservations - Listar
• POST /t/:slug/reservations - Criar (público)
• PUT /t/:slug/reservations/:id - Atualizar
• DELETE /t/:slug/reservations/:id - Cancelar

Tables

Responsabilidade: Mesas do restaurante.

Rotas:

• GET /t/:slug/tables - Listar
• POST /t/:slug/tables - Criar
• PUT /t/:slug/tables/:id - Atualizar
• DELETE /t/:slug/tables/:id - Deletar

Filial (Pdvs)

Responsabilidade: Filiais e terminais PDV. Inclui autenticação por PIN, endereço da filial, usuários atribuídos e modos de serviço.

Rotas:

• GET /t/:slug/pdvs - Listar
• POST /t/:slug/pdvs - Criar
• PUT /t/:slug/pdvs/:id - Atualizar
• DELETE /t/:slug/pdvs/:id - Deletar
• GET /t/:slug/pdvs/my - Filiais do usuário atual
• POST /t/:slug/pdvs/auth - Autenticação por PIN

Kitchen (WebSocket)

Responsabilidade: Display de cozinha em tempo real.

Namespace: /kitchen

Eventos:

• newOrder - Novo pedido
• orderStatusUpdate - Status atualizado
• paymentUpdate - Resultado de pagamento Stone (server → PDV Terminal)
• fiscalStatusUpdate - NF-e autorizada ou rejeitada (notifica admin UI)

Stone

Localização: backend/src/stone/

Responsabilidade: Integração com gateway de pagamento Stone — autenticação OAuth2, criação de payment intents, recebimento de webhooks e emissão de resultado via WebSocket.

Componentes:

Componente	Descrição
StoneService	Cache de token OAuth2 + createPaymentIntent() + getPaymentStatus() + cancelIntent() + verifySignature()
StoneController	POST /api/stone/webhook — rota global sem guard de tenant; valida assinatura HMAC-SHA256 e emite paymentUpdate via KitchenGateway

Dependência circular: StoneModule ↔ OrdersModule resolvida via forwardRef() nos dois módulos.

Rotas:

• POST /api/stone/webhook — global (sem prefixo /t/:slug), sem JwtAuthGuard

TaxEngine

Localização: backend/src/tax-engine/

Responsabilidade: Motor de cálculo tributário com suporte ao sistema legado (ICMS/PIS/COFINS) e ao novo IBS/CBS (Reforma Tributária). Calcula impostos por item com taxas de transição faseadas.

Componentes:

Componente	Descrição
TaxEngineService	Calcula impostos por item considerando grupo fiscal, regime tributário e fase da reforma

FiscalQueue (BullMQ)

Localização: backend/src/fiscal-queue/

Responsabilidade: Fila assíncrona para emissão de NF-e/NFC-e via BullMQ com retry exponential backoff. O processor emite notificações WebSocket (fiscalStatusUpdate) ao concluir.

Componentes:

Componente	Descrição
FiscalQueueModule	Registra a fila BullMQ e o processor
FiscalQueueProcessor	Processa jobs de emissão e emite eventos WebSocket

Rotas:

• GET /t/:slug/fiscal/queue/stats — Métricas da fila (waiting, active, completed, failed)

NCM Lookup

Localização: backend/src/ncm-lookup/

Responsabilidade: Busca fuzzy de códigos NCM via similaridade por trigram (coeficiente de Jaccard). Contém 60+ códigos comuns para foodservice.

Rotas:

• GET /t/:slug/ncm/search?q=&category=&limit= — Busca NCM por código ou descrição

Certificates

Localização: backend/src/certificates/

Responsabilidade: Upload, armazenamento (S3) e monitoramento de expiração de certificados digitais A1 (.pfx).

Componentes:

Componente	Descrição
CertificateScheduler	Cron diário às 9h — verifica certificados com expiração dentro de 30 dias e registra avisos nos limiares de 30/15/7/3/1 dias

InboundNfe

Localização: backend/src/inbound-nfe/

Responsabilidade: Consulta e manifestação de NF-es emitidas contra o CNPJ do tenant (Manifestação do Destinatário), com processamento automático de estoque e contas a pagar.

Componentes:

Componente	Descrição
InboundNfeService	syncFromProvider(), manifest(), confirmAndProcess()
SefazInboundProvider	Consulta nfeDistDFe (SEFAZ direto) + envio de eventos via RecepcaoEvento4

Rotas:

• GET /t/:slug/inbound-nfe — listar com paginação/filtros
• POST /t/:slug/inbound-nfe/sync — sincronizar com provider
• GET /t/:slug/inbound-nfe/:id — detalhe
• POST /t/:slug/inbound-nfe/:id/manifest — manifestar (ciencia/confirmacao/desconhecimento/nao_realizada)
• DELETE /t/:slug/inbound-nfe/:id — remover
• GET /t/:slug/inbound-nfe/accounts-payable — listar Contas a Pagar
• POST /t/:slug/inbound-nfe/accounts-payable — criar AP manual
• PUT /t/:slug/inbound-nfe/accounts-payable/:id/pay — registrar pagamento
• DELETE /t/:slug/inbound-nfe/accounts-payable/:id — cancelar AP

Schemas: InboundNfe, AccountsPayable

Dependências: BomModule (via forwardRef()), CertificatesModule, UploadModule

---

DRE

Localização: backend/src/dre/

Responsabilidade: Cálculo dinâmico do P&L por regime de competência. Sem schema de DRE — agrega de Order, InventoryMovement, AccountsPayable e OperatingExpense via MongoDB aggregation pipeline.

Componentes:

Componente	Descrição
DreService	computeDre() (11 etapas de agregação), CRUD de OperatingExpense, ExpenseCategory, CostCenter
DreModule	Seed de categorias defaults no onModuleInit

Rotas:

• GET /t/:slug/dre — calcular DRE (query: year, month, costCenterId?)
• GET/POST /t/:slug/dre/expenses — CRUD de Despesas Operacionais
• PUT/DELETE /t/:slug/dre/expenses/:id
• GET/POST /t/:slug/dre/categories — Plano de Contas
• DELETE /t/:slug/dre/categories/:id
• GET/POST /t/:slug/dre/cost-centers — Centros de Custo
• DELETE /t/:slug/dre/cost-centers/:id

Schemas: OperatingExpense, ExpenseCategory (com tenant: null para defaults), CostCenter

---

BOM (Fichas Técnicas)

Localização: backend/src/bom/

Responsabilidade: Cálculo de custo de produção por item do cardápio, com custos indiretos e histórico append-only de snapshots. Recálculo automático disparado por NF-e entrada ou atualização de costPrice no estoque.

Componentes:

Componente	Descrição
BomService	calculateCost(), recalculateAllForIngredients(), getSnapshotHistory()

Rotas:

• GET /t/:slug/bom — listar com custo atual
• GET /t/:slug/bom/:menuItemId — detalhe completo
• POST /t/:slug/bom/:menuItemId/calculate — calcular (body: { targetMargin? })
• GET /t/:slug/bom/:menuItemId/history — histórico de snapshots
• POST/PUT/DELETE /t/:slug/bom/indirect-costs — CRUD de custos indiretos

Schemas: BomIndirectCost, BomCostSnapshot (append-only)

Dependências: InventoryModule (via forwardRef() para trigger de recálculo)

---

Notifications

Localização: backend/src/notifications/

Responsabilidade: Serviço de envio de email via Nodemailer (SMTP).

Templates:

Template	Descrição
Confirmação de pedido	Enviado ao cliente após criação do pedido
Pedido pronto	Notifica o cliente quando o pedido está pronto
Reserva	Confirmação de reserva
Resposta de suporte	Resposta a ticket de suporte
Alerta de certificado	Aviso de expiração de certificado digital
Convite de contador	Convite para acessar o portal do contador