# Fluxo PDV API — Roadmap de Execução > Documento canônico de execução do backend do Fluxo PDV. > Criado em: 2026-09-30. > Repositório coordenado: paulodias-dev/fluxo-pdv-app. > Escopo inicial: panificadoras, delicatessens e varejo de balcão com balanças, comandas, PDV, operação offline e NFC-e. ## 1. Objetivo Evoluir a base Laravel existente para um PDV corporativo multi-tenant, mantendo arquitetura de monólito modular, isolamento rigoroso por tenant, WMS como fonte única de verdade e fronteiras explícitas entre Venda de Balcão, Pedido Administrativo e Comanda. Este roadmap é o guia de implementação e deve ser atualizado a cada PR. Nenhuma issue concluída fora da branch principal conta como evolução real do projeto. ## 2. Diretrizes arquiteturais imutáveis 1. Manter monólito modular; não criar bifurcações por segmento como tenant_type = panificadora. 2. PosSale, Order e Tab são agregados distintos. 3. WMS permanece a fonte única de verdade de estoque. 4. Reservas de estoque devem evoluir para uma abstração genérica, não exclusiva de Service Order. 5. Pagamento instantâneo do PDV não deve ser confundido com Contas a Receber. 6. Cliente deve ser opcional em venda de balcão. 7. Cada venda deve preservar snapshots imutáveis de produto, preço, custo relevante e tributação. 8. Dinheiro e tributos não podem depender de float para regras críticas. 9. Toda operação originada no PDV deve aceitar ULID/UUID e chave de idempotência. 10. Emissão fiscal deve ser assíncrona e desacoplada do commit da venda. 11. Transactional Outbox é obrigatória na fronteira venda → fiscal. 12. Fila fiscal deve ser independente das filas não críticas. 13. Toda entidade operacional deve ser tenant-owned e fail-closed. 14. Toda mutação financeira, fiscal ou de estoque deve possuir teste de idempotência/concor­rência quando aplicável. 15. Todos os endpoints novos ou alterados devem possuir L5 Swagger/OpenAPI. ## 3. Regra de progresso O progresso canônico deste roadmap é calculado somente pelas issues/checkpoints marcados como concluídos neste arquivo e já integrados à main. **Progresso real em `main`:** 105/108 checkpoints concluídos = 97,2% **Progresso representado por `feat/pdv-weight-reading-read-model`:** 108/108 checkpoints concluídos = 100,0% - PR aberto não aumenta o percentual. - Cada alteração de escopo exige recontagem do numerador e denominador. - O PR deve informar percentual anterior, percentual representado pela branch e próxima entrega. - O App possui percentual próprio, mas a homologação final exige o par API + App compatível. ## 4. Sequência de entrega Ordem obrigatória de dependência: Fundação de domínio → WMS/reservas → Caixa/Pagamentos → PDV Online → Balanças/Device Bridge → Comandas/Realtime → Fiscal/Outbox → Offline Sync → Observabilidade/Hardening. Quando houver entrega coordenada, a API deve ficar merge-ready antes do App. --- # PILAR 1 — Engenharia de Domínio e Banco de Dados ## EPIC API-01 — Kernel transacional do PDV Objetivo: criar o agregado PosSale sem reutilizar Order como venda de balcão. Issues sugeridas: ### API-01.1 — Modelo PosSale e identidade idempotente - [x] Criar pos_sales com tenant_id, ULID/UUID externo, idempotency_key, terminal, operador, cash_session, cliente opcional, status, business_date e timestamps operacionais. - [x] Criar constraints e índices tenant-first para external_id, idempotency_key, terminal, status e data operacional. - [x] Definir máquina de estados da venda e impedir transições inválidas. Critérios de aceite: - retry da mesma requisição retorna a mesma venda; - tenant A nunca resolve venda do tenant B; - identidade técnica não depende de sequência visual. ### API-01.2 — Itens e snapshots imutáveis - [x] Criar pos_sale_items com snapshot de produto, SKU/EAN, descrição, unidade, quantidade, preço, desconto, total, custo e dados fiscais necessários. - [x] Impedir reconstrução histórica a partir do cadastro atual de Product. - [x] Registrar origem do peso/barcode/dispositivo quando aplicável. ### API-01.3 — Precisão decimal - [x] Definir Value Objects/serviços de Money, Quantity e Rate sem float para invariantes críticas. - [x] Definir política única de arredondamento e precisão por quantidade, preço unitário, desconto, tributo e total. - [x] Cobrir produtos por peso e divisão de pagamento com testes de arredondamento. ## EPIC API-02 — WMS e reservas genéricas Objetivo: manter estoque único e remover o acoplamento conceitual de reservas a Service Order. ### API-02.1 — inventory_reservations - [x] Modelar reserva genérica com source_type/source_id/source_item_id, produto, local, quantidade, status, reserved_at, consumed_at e released_at. - [x] Criar serviço transacional com lock determinístico para reservar, consumir e liberar. - [x] Preservar compatibilidade com reservas existentes durante migração. ### API-02.2 — Origem semântica das movimentações - [x] Evoluir referência de stock_movements para identificar venda PDV, estorno, comanda, OS, recebimento e ajuste sem ambiguidade. - [x] Garantir que cancelamentos/devoluções gerem movimentos compensatórios, nunca deleção de histórico. ### API-02.3 — Finalização atômica de estoque - [x] Consumir estoque no fechamento da venda com concorrência segura. - [x] Testar dois terminais disputando o último saldo disponível. - [x] Definir política explícita para estoque negativo e modo offline. ## EPIC API-03 — Caixa e pagamentos instantâneos ### API-03.1 — Terminais - [x] Criar pos_terminals com código, nome, estoque/local padrão, status e configurações operacionais. - [x] Garantir unicidade por tenant e revogação operacional. ### API-03.2 — Sessão de caixa - [x] Criar cash_sessions com abertura, saldo inicial, fechamento, esperado, declarado e diferença. - [x] Impedir duas sessões abertas incompatíveis conforme regra de terminal/operador. - [x] Criar cash_movements append-only para abertura, venda em dinheiro, suprimento, sangria, estorno e ajuste. ### API-03.3 — Pagamentos da venda - [x] Criar pos_payments com método, valor, provider, referência, autorização/NSU quando aplicável e status. - [x] Suportar múltiplos meios na mesma venda, troco e pagamento parcial durante finalização. - [x] Não criar Receivable para venda instantânea liquidada; usar Financeiro tradicional apenas quando houver dívida real. ### API-03.4 — Cancelamento e devolução - [x] Criar fluxo auditável de cancelamento pós-finalização. - [x] Criar devolução total/parcial com reversão financeira e de estoque. - [x] Exigir permissão/override de supervisor conforme política. ## EPIC API-04 — Produto e perfil fiscal ### API-04.1 — Produto vendável por peso - [x] Acrescentar configuração comercial para produto por peso, precisão e código interno de balança sem degradar o cadastro horizontal. - [x] Manter kg/un/lt e permitir futuras unidades de forma extensível. ### API-04.2 — Perfil fiscal do produto - [x] Criar product_fiscal_profiles desacoplado de products. - [x] Preparar versionamento/snapshot para mudanças tributárias sem reescrever venda histórica. --- # PILAR 2 — Resiliência do PDV e Hardware ## EPIC API-05 — Contratos para operação offline ### API-05.1 — Sync incremental de catálogo - [x] Criar contrato delta/cursor para produtos, preços, códigos, métodos de pagamento e configurações mínimas do terminal. - [x] Garantir paginação/cursor estável e tenant-safe. - [x] Definir tombstones/revisões para itens removidos ou desativados. ### API-05.2 — Ingestão idempotente de operações offline - [x] Criar endpoint de sincronização em lote com operation_id, idempotency_key, terminal_id e timestamp de origem. - [x] Retornar ack individual por operação e erros classificáveis em retryable/conflict/terminal. - [x] Preservar venda efetivamente cobrada por snapshot e gerar ocorrência de reconciliação quando catálogo/estoque divergirem. ### API-05.3 — Registro e segurança do dispositivo - [x] Criar device_registrations com credencial própria, revogável e vinculada a tenant/terminal. - [x] Não reutilizar JWT de funcionário no Device Bridge. - [x] Criar heartbeat/status mínimo sem transformar telemetria de alta frequência em gargalo do banco principal. ## EPIC API-06 — Balanças e códigos de barras ### API-06.1 — Perfis de código da balança - [x] Criar scale_profiles configuráveis por tenant com prefixo, tamanho, máscara, produto, peso/preço e validação. - [x] Implementar parser determinístico com testes para diferentes layouts. - [x] Persistir trilha de auditoria suficiente para investigar divergências. ### API-06.2 — Contrato Device Bridge - [x] Definir protocolo/versionamento entre App e Bridge para leitura de peso e status de dispositivo. - [x] Permitir peso manual somente com permissão e marca de auditoria. - [x] Projetar capacidade extensível para impressora térmica, gaveta e display sem acoplar o domínio fiscal ao hardware. ### API-06.3 — Read model de peso para o App - [x] Expor leitura de peso tenant-safe e escopada ao terminal com RBAC pos.access + devices.view. - [x] Retornar somente eventos estáveis de dispositivo ativo/capability scale.read. - [x] Adicionar cursor after_event_id para impedir reutilização silenciosa de leitura já consumida. ## EPIC API-07 — Comandas e realtime ### API-07.1 — Mesas e áreas - [x] Criar dining_areas e dining_tables tenant-owned. - [x] Definir status operacionais sem usar tabela como fonte financeira. ### API-07.2 — Agregado Tab - [x] Criar tabs com identificador público, mesa/cliente opcionais, status, lock_version, responsável, totais e datas. - [x] Criar tab_items com snapshots e estados de cancelamento. - [x] Criar tab_events append-only. ### API-07.3 — Concorrência de comandas - [x] Implementar optimistic locking por lock_version. - [x] Exigir operation_id idempotente nas mutações críticas. - [x] Cobrir duas alterações concorrentes sem lost update. ### API-07.4 — Operações de salão - [x] Transferir mesa. - [x] Transferir itens entre comandas. - [x] Mesclar comandas. - [x] Dividir conta por item/quantidade/valor. - [x] Permitir pagamentos parciais conforme regra aprovada. ### API-07.5 — Realtime - [x] Publicar eventos pós-commit em canais privados tenant/comanda. - [x] Preparar backend WebSocket/broadcast escalável e autorizado. - [x] Proibir polling agressivo como mecanismo principal de sincronização. --- # PILAR 3 — Ecossistema Fiscal ## EPIC API-08 — Bounded Context Fiscal ### API-08.1 — Configuração fiscal - [x] Criar fiscal_settings por tenant/estabelecimento. - [x] Armazenar certificados/segredos cifrados e nunca expor credenciais em payload/log. - [x] Separar ambiente de homologação e produção. ### API-08.2 — FiscalDocument e snapshots - [x] Criar fiscal_documents, fiscal_document_items e fiscal_events. - [x] Manter chave, modelo, série, número, protocolo, XML, QR Code, status e timestamps. - [x] Garantir unicidade de chave e sequência conforme regra fiscal. ### API-08.3 — Adapter Fiscal - [x] Definir contrato FiscalProviderAdapter desacoplado do PDV. - [x] Implementar primeiro provider sem espalhar SDK/HTTP do fornecedor pelo domínio. - [x] Normalizar rejeições, timeouts e estados externos. ## EPIC API-09 — Assincronia, Outbox e filas ### API-09.1 — Transactional Outbox - [x] Gravar fiscal_outbox na mesma transação que finaliza a PosSale. - [x] Publicar/processar somente após commit. - [x] Garantir reprocessamento sem duplicidade fiscal. ### API-09.2 — Fila fiscal dedicada - [x] Criar filas separadas para emissão, eventos/cancelamento e reconciliação. - [x] Configurar retry/backoff/dead-letter/failures conforme criticidade. - [x] Evitar que e-mail, notificações ou tarefas administrativas atrasem emissão fiscal. ### API-09.3 — Tentativas e reconciliação - [x] Criar fiscal_emission_attempts com correlation ID, duração, erro normalizado e próxima tentativa. - [x] Criar reconciliador para casos em que houve timeout sem certeza do resultado no provedor/SEFAZ. - [x] Nunca emitir um segundo documento apenas porque a resposta anterior se perdeu. ### API-09.4 — Cancelamento, contingência e DANFE - [x] Implementar cancelamento como evento fiscal separado. - [x] Modelar contingência desde o início, com estados próprios. - [x] Disponibilizar contrato para DANFE/reimpressão sem bloquear o commit da venda. --- # PILAR 4 — Governança Operacional ## EPIC API-10 — Observabilidade e auditoria ### API-10.1 — Correlation ID ponta a ponta - [x] Propagar correlation_id por venda, estoque, pagamento, outbox, job e documento fiscal. - [x] Padronizar logs estruturados sem PII/segredos desnecessários. ### API-10.2 — Saúde operacional - [x] Expor saúde de filas fiscais, backlog, idade do job mais antigo, falhas e workers. - [x] Expor última sincronização/heartbeat de terminal e dispositivo em nível operacional. - [x] Integrar com a infraestrutura de Queue Health já existente sem misturar escopo platform/tenant. ### API-10.3 — Auditoria sensível - [x] Auditar desconto, cancelamento, devolução, sangria, suprimento, peso manual, fechamento, retry fiscal e cancelamento fiscal. - [x] Registrar ator, terminal, tenant, correlação e motivo. ## EPIC API-11 — Performance e read models ### API-11.1 — Índices e consulta - [x] Validar todos os índices críticos com tenant_id como primeiro componente onde aplicável. - [x] Proibir históricos operacionais sem paginação. - [x] Criar read models/snapshots para dashboards em vez de SUM repetitivo sobre milhões de itens. ### API-11.2 — SLO e carga - [x] Definir orçamento de latência para finalização interna, busca e realtime. - [x] Criar testes de carga para venda concorrente, comandas e ingestão offline. - [x] Medir P50/P95/P99 e documentar baseline. ## EPIC API-12 — Release corporativa ### API-12.1 — Segurança e multi-tenancy - [x] Testar IDOR e isolamento cross-tenant para todos os novos agregados. - [x] Testar revogação de terminal/device e permissões RBAC. ### API-12.2 — Matriz de falhas - [x] Testar perda de conexão antes/durante/depois do commit. - [x] Testar timeout fiscal, worker parado, fila acumulada e retry. - [x] Testar concorrência no último estoque e fechamento duplicado. ### API-12.3 — Documentação e gates - [x] Documentar todos os endpoints em L5 Swagger. - [x] Incluir suites do PDV no gate de release. - [x] Documentar ordem segura de deploy API → App e rollback. --- ## 5. Permissões mínimas previstas PDV: - pos.access - pos.sell - pos.discount - pos.cancel - pos.refund - pos.supervisor.override - pos.suspended.manage - pos.cash.open - pos.cash.close - pos.cash.supply - pos.cash.withdraw Comandas: - tabs.view - tabs.create - tabs.manage - tabs.transfer - tabs.merge - tabs.split - tabs.pay - tabs.close - tabs.reopen Fiscal: - fiscal.view - fiscal.emit - fiscal.retry - fiscal.cancel - fiscal.settings.manage Dispositivos: - devices.view - devices.manage ## 6. Critérios de Definition of Done da API Uma issue de backend somente pode ser marcada como concluída quando: 1. regra de negócio está em Service/Action/domínio, não em controller gordo; 2. isolamento multi-tenant está testado; 3. autorização/RBAC está aplicada; 4. migration é aditiva/reversível e segura para MySQL; 5. Swagger foi atualizado; 6. testes happy path + validação + autorização foram adicionados; 7. invariantes de dinheiro/estoque possuem teste transacional; 8. idempotência/concor­rência foi testada quando aplicável; 9. logs não expõem credenciais ou dados fiscais sensíveis; 10. ordem de deploy foi documentada quando houver dependência do App. ## 7. Política de branches e PRs Branches: - feat/pdv- - feat/tabs- - feat/fiscal- - feat/devices- - fix/- - docs/pdv- Todo PR deve ser não-draft quando entregue e informar: - objetivo; - issue/épico; - regras de negócio; - migrations; - permissões; - Swagger; - testes realmente executados; - impacto multi-tenant; - dependência do App; - percentual total do roadmap; - próxima implementação resumida. ## 8. Próxima entrega recomendada A expansão coordenada para **APP-05.3 — Leitura direta de peso** acrescentou o contrato **API-06.3** ao backend. Nesta branch, o backend volta a **108/108 checkpoints concluídos = 100,0%**, disponibilizando ao App a leitura estável tenant-safe com cursor de consumo. Próxima implementação recomendada: consumir no App `GET /api/v1/pos/device-bridge/weight-readings/latest`, capturar somente leitura estável posterior ao cursor e concluir a **APP-05.3** com fallback manual autorizado e origem `device_bridge`.