O BISPDV é a aplicação utilizada na frente de caixa para realização da venda ao consumidor e de outra funções pertinentes à venda e atendimento do cliente da loja.
Pendências, Informações e Guia sobre a implementação
O projeto anterior (bis2.pdv) está sendo descontinuado por ainda ter código com suporte a ECF e SAT, que estão em caindo em desuso. Para rever e simplificar o código um novo projeto (bis.pdv) foi criado e o código está sendo revisado e repassado para o novo projeto. Uma vez concluído o projeto bis2.pdv será descontinuado.
Alterações em andamento:
Para agilidade, foi definido que não utilizaremos o RFWDAO, mas manter a arquitetura de DAO original.
Removido código relacionados ao ECF e ao SAT, este novo projeto emitirá cupons apenas utilizando o NFCe, utilizando o código do módulo RFW.SEFAZ.
O Bundle foi rebatizado para bispdvbundle.properties, e passou a utilizar as chaves BISPDV_NNNNNN. Todas as chaves antigas foram copiadas para o arquivo e ao fechamento da versão devem ser revisadas, e as sobreviventes renomeadas.
Inicialização do Sistema
Inicialização do Sistema
A inicialização do aplicativo segue as seguintes regras:
PDVStarter
A aplicação deve ser inicializada sempre por esta classe que contém o método main();
Esta classe não faz absolutamente nada além de passar a chamada, incluindo os argumentos de linha de comando para a PDVUpdater. Sua existência tem a finalidade de permitir a incorporação de plugins, siffers, debugger e outras ferramentas na aplicação. Para isso, basta que a ferramenta implemente uma 'sósia' desta classe (mesmo nome e package), e que sua bibliotexa (.jar) seja carregada no classpath antes dos .jars da própria aplicação. Após realizar o que for necessário a ferramenta deve repassar a chamada para PDVUpdater da mesma forma, para que a aplicação se inicie em seu fluxo normal.
PDVUpdater
Esta classe que concentra as tarefas de inicialização da aplicação recebe os seguintes parâmetros:
-help - Exibe este menu de opções.
-testDarumaFW - Não inicializa a aplicacao. Tenta apenas inicializar as bibliotecas da DarumaDramework, verificando se as DLLs estão OK. Não faz comunicação com a impressora.
-watcher - Habilita uma thread que imprime o valor de algumas variáveis do sistema a cada segundo no console do sistema.
-autoSaleTest - Carrega um arquivo de vendas automáticas. Esse arquivo deve conter o que deve ser vendido, e as vendas serão feitas automaticamente no horário programado.
-noUI - Não inicializa a UI do PDVApp. Útil quando estamos utilizando o -saleFile
Valida se é a única instância tentando bloquear o arquivo .\\instance.lock no diretório da aplicação.
PDVApp
O PDVApp é o coração da aplicação. Funciona com uma série de máquinas de estado (workflows) que definem a lógica da operação da aplicação.
Workflows do Sistema
Principal: PDVState
Esse é o WORKFLOW geral da aplicação, é definida nos valores da enum PDVState:
START - Valor inicial, utilizado somente na inicialização da aplicação.
Neste passo é iniciado o workflow StartCheckStatus, enquanto esse workflow secundário é executado, o PDVState é passado para o estado STARTCHECK.
STARTCHECK - Estado enquanto a checagem inicial do sistema ocorre;
Se a checagem inicial finalizar com sucesso vai para o estado WAITINGLOGIN, em caso de erro vai para o STARTCHECK_FAIL.
STARTCHECK_FAIL - indicador de que o processo de checagem inicial terminou com erro.
Não há saída desse estado, a não ser reiniciar ou refazer a instalação do PDVApp.
WAITINGLOGIN - Sinaliza que o sistema está aguradando o login.
Fica nesse estado até que o PDVUI interaja com o usuário para executar o login.
Uma vez feita o login pelo método doLogin(), se realizado com sucesso para para o estado ADMINISTRATIVE.
ADMINISTRATIVE - Estado em que o sistema permite ser configurado, e permite acesso a outras funções administravias do checkout (como abrir e fechar o checkout).
Este já um estado de uso do sistema, deste estado o usuário pode entrar no modo de venda SALES.
SALES - Estado em que o sistema entra no modo de vendas, permite a abertura de venda, venda de produtos, recebimento, etc.
Sempre que não estiver com uma venda aberta, o usuário pode voltar para o estado ADMINISTRATIVE.
Uma vez nos estrados ADMINISTRATIVE ou SALES o usuário não pode mais voltar para os outros estados até que a aplicação seja finalizada.
Inicialização: StartCheckStatus
Esse é o WORKFLOW que cuida da checagem e inicialização inicial do sistema. Seus funcionamento é assim:
INITING - Estado inicial de começo das checkagens;
Neste estágio o sistema começa a ser inicializado, como carregamento dos bundles.
Tudo inicializado com sucesso, passa para o estado CHECKING_LOCALDB.
CHECKING_LOCALDB - Estado para verificação do banco de dados.
Verifica se o banco de dados existe, se não existir o cria;
Passa para o estado CHECKING_LOCALDB_VERSION;
CHECKING_LOCALDB_VERSION - Verifica se o banco de dados está na versão correta e faz as alterações/atualizações necessárias;
Quando atualizado passa para o CHECKING_INSTALLATION;
CHECKING_INSTALLATION- Valida se a instalação do PDV está ok (empresa configurada, dados sincronizados, etc.).
Se a instalação estiver OK vai para o estado INSTALLATION_OK, caso contrário para INSTALLATION_NEEDED.
INSTALLATION_NEEDED
Nesse estado o PDVApp não faz nada, mas serve de sinalização para o PDVUI que a instalação precisa ser realizada, e a tela é exibida. Quando a tela de instalação é finalizada, o PDVUI sinaliza para o PDVAapp que volta para o estado de CHECKING_INSTALLATION.
INSTALLATION_OK - Estado sem operação, apenas sinalizando que a Instalação está completa.
Passa automaticamente para o estado START_TERMINALAPP.
START_TERMINALAPP - Inicializa o Terminal Client (Reponsável por realizar a comunicação com o servidor).
Após inicializá-lo passa automaticamente para o estado CHECKING_SERVER_ID.
CHECKING_SERVER_ID - Valida se o ID atual configurado na estação PDV está válido e cadastrado corretamente no servidor.
Se o cadastro estiver OK passa para LOAD_CHECKOUT_DATA, caso contrário trava a aplicação em erro para garantir que seja reinstalada.
LOAD_CHECKOUT_DATA - Carrega as informações do CheckoutData, se existir, para continuar com a aplicação a partir do ponto em que estava. Se não encontrar, procura manualmente se há algum caixa em aberto no banco de dados e "cria" o CheckoutData para continuar o checkout aberto (e não perder sessões de checkouts a cada vez que se perde o CheckoutData). Em adicional, (re)carrega o CFSystem para que o sistema esteja pronto para emitir cupons fiscais.
Passa para o START_SYNCDATA.
START_SYNCDATA - Inicializa a Thread responsável por sincronizar os dados com/do servidor.
Passa para o OK.
OK - Estado em que o WORKFLOW finalizou com sucesso. Utilizado para sinalizar outras partes do sistema que a inicialização terminou com sucesso e o sistema está pronto para ser utilizado.
Sinaliza o PDVApp de que este workflou finalizou através do método app.freeStartCheck(), que dá sequência no workflow PDVState.
PDVUI
NFC-e
A emissão de NFCe é realizada pelo mesmo site da NFe. O BISPDV utilizará o módulo RFW.SEFAZ. Toda a documentação técnica estará no site do módulo. Concentrar aqui apenas as informações relacionadas ao BISPDV e à configuração/utilização do módulo.
Cadastros do Sistema
Items
A aplicação BISPDV não suporta cadastro de itens diretamente no aplicativo. A base de itens para venda é sincronizada diretamente do servidor para a aplicação.
Para a aplicação é enviada apenas apenas os campos do cadastro de itens necessários para realizar a venda do produto, um objeto PDVItemVO é montado com as informações da estrutura de ItemVO.
A conversão é feita a partir do ItemCodeVO e não de ItemVO. Isso porque cada código de item pode ser vendido por preços diferentes, quantidades diferentes, unidades de medidas diferentes entre outros. Para o BISPDV cada código funciona como um produto cadastro diferente que pode ser vendido. Já no servidor, a venda de cada código é tratada como uma venda do mesmo item (respeitando a quantidade, preços, etc.). A conversão/envio dos códigos para venda no PDV é realizada da seguinte forma:
Apenas produtos que tenham a finalidade marcada como Revenda ou Produto Acabado tem seus códigos sincronizados no PDV.
O ID aplicado no PDVItemVO é o mesmo do ItemCodeVO, utilizado como referência para sincronizar os novos códigos ou alterações do servidor.
O IDItem é atribuído em outro atibuto, e é utilizado pelo servidor para associar o item do cupom (vendas) ao ItemVO correto. Essa medida visa não perder o relacionamento entre os objetos de Item de Documentos fiscais com o cadastro de item. Isso porque o objeto ItemCodeVO pode ser excluído do sistema, já o ItemVO é só marcado como excluído no sistema e mantido para efeitos de histório, ou seja, ItemCodeVO é um objeto volátil e não pode ser utilizado para referência ou vinculação com objetos de registro ou histórico.
O servidor passar no atributo startDate a última data de alteração do ItemVO (ou seus subojetos como ItemCodeVO ou ItemPrice), para que o PDV saiba qual foi a última alteração dos objetos na sua base e, consultando a maior dessas datas entre todos os objetos, consegue utilizar essa data para requisitar os objetos alterados a partir dessadata (ao invés da data da última alteração, evitando problemas de sincronia de datas e deixar algum item dessincronizados).
Como a venda ocorre com base nas definições do ItemCodeVO, mas o sistema precisa vincular a venda com o ItemVO, os campos que definem a "transformação" entre ItemVO e ItemCodeVO são atribuídas no objeto nos seguintes atributos:
originalItemID - ID do ItemVO para associação com o item original.
originalDivider - Divisor de conversão
DOCUMENTAÇÃO A SER REVISADA!
O Conteúdo a seguir precisa ser revisado desde a "reimplementação" do PDVApp (BIS2.PDV - Projeto com código do ECF e SAT) para o novo (BIS.PDV - Projeto dedicado apenas ao código do NFCe)
O BISPDV utiliza a versão de troca de arquivos txt, que é a continuação da versão do da NTK na qual o sistema foi homologado inicialmente.
Instalação Ambiente de Testes/Homologação
Para instalação do ambiente de testes/homologação seguir as instruções do site: https://paygodev.readme.io/docs/kit-de-integra%C3%A7%C3%A3o-2.
Em 28/01/2025 solicitei cadastro para uma nova homologação e ativação do sistema e recebi um e-mail com o seguinte conteúdo:
Giovanna de Mello Doroteio comentou\: Prezado(a), Rodrigo.
Agradecemos por escolher nossos serviços. Para garantir uma experiência tranquila e bem-sucedida durante a integração, estamos fornecendo os dados de instalação e informações sobre os adquirentes disponíveis em nosso servidor de testes.
Dados de Instalação:
Id de Instalação: 344384
Senha: A70C47D1
Adquirentes disponíveis em nosso servidor de testes:
Adquirente DEMO:
Função: Simula uma sub-adquirente.
Adquirente REDE:
Função: Simula uma adquirente.
Restrição no Ambiente de Sandbox: Aceita apenas valores inteiros.
Importante: Qualquer valor com centavos resultará em uma transação negada.
Adquirente PIX C6 BANK:
Função: Simula operações com Pix e carteira digital.
Processo: Após uma transação, o QRCode para pagamento será gerado.
Aprovação Automática: A transação será aprovada automaticamente alguns segundos após a geração do QRCode.
Para acessar a documentação completa de integração, por favor, visite: Sobre esse documento
Segue o kit de integração e o passo a passo para a habilitação dos logs, respectivamente: [
Kit de integração|https://paygodev.readme.io/docs/kit-de-integra%C3%A7%C3%A3o-2][
Kit de integração- Habilitação dos Logs.|https://paygodev.readme.io/docs/kit-de-integra%C3%A7%C3%A3o-2#aten%C3%A7%C3%A3o]
ATENÇÃO: É obrigatório habilitar os logs para realizar a homologação.
Se você tiver alguma dúvida, precisar de assistência adicional ou encontrar qualquer problema durante o processo de integração, nossa equipe de suporte estará pronta para ajudar. Não hesite em entrar em contato conosco por meio deste chamado.
Agradecemos pela sua colaboração e estamos ansiosos para fornecer a melhor experiência possível durante sua fase de testes.
Atenciosamente, SETIS.
Navegação dos Arquivos do Site (Procure pelas versões mais atualizadas na sessão de download do site oficial)
Manual Orientacao SAT - arquivo geral com as orientações sobre como gerar a impressão do cupom, códigos de barras, tamanho, informações necessárias, qrcode, etc.
Guia para Geração do QRCode - arquivo com as orientações para gerar o qrcode do cupom fiscal.
Especificação de Requisitos do SAT - arquivo com as especificações para o desenvolvedor, como layout XML e outras informações técnicas.
Arquitetura
O aplicativo apresenta a arquitetura dividia conforme o diagrama abaixo:
= PDVStarter
O PDVStarter é a classe inicial da aplicação, a classe que contém o método main(). Ela faz apenas algumas verificações mínimas e necessárias para o funcionamento, como definições do ambiente java, e logo seguida inicializa o PDVUI.
PDVUI
PDVUI é a responsável pela Interface Gráfica da aplicação. A interface é montada toda com o JavaFX, por isso o método chamado no PDVUI para inicia-lo é o launch(). Ao iniciar, o JavaFX chamará o método start(Stage stage).
O PDVUI é o responsável por montar as telas e a interface gráfica para o usuário, porém como todo o controle da aplicação é feita através do PDVApp o PDVUI lê os estados do PDVApp para saber que tela montar, que controles exibir, etc. O PDVUI é atualizado através de eventos emitidos pelo PDVApp.
No PDVUI apenas as lógicas de UI são colocadas, como alguma validação de entradas do usuário, formatação e layout de tela, algumas questões de segurança para exibir ou esconder os componentes de tela, etc.
PDVScreenInterface
A classe PDVUI é a classe de controle geral da interface. Mas a cada estado do PDVState, a tela montada é "sub-controlada" pelas implementações de PDVScreenInterface. Em outras palavras, os únicos componentes que a PDVUI tem como filhas são as implementações dessa interface.
Essas implementações montam uma tela para cada fase do sistema. Por exemplo, ao iniciar a aplicação é utilizada a "StartScreen", que monta a tela para exibir as informações de inicialização e instalação, além da tela de Log-In. Após o login, o usuário é direcionado para a tela administrativa, montado pela "AdminScreen". Caso o usuário entre no modo de vendas, toda a tela de venda ao consumidor (responsável por exibir as fotos de produtos ao fundo) é gerenciada pela "SaleScreen" e assim por diante.
Em geral, a PVDUI troca essa "Screen" para estado do PDVState. Dentro de cada estado do PDVState, seus substados são verificados e controlados por cada Screen.
BISPDVFrame
Além das Screens que montam a "tela" da aplicação em cada estado, há as janelas chamadas de "Frames". Esses frames são janelas modais que são colocadas por cima da Screen para indagar o usuário para realizar alguma função.
Exemplos de Frames são as telas de configurações de Servidor ou do Sistema de Emissão do Cupom Fiscal, que aparecem por cima da AdminScreen. Ou a tela de identificação do cliente (CPF/Nota Paulista), que aparece por cima da SaleScreen ao começar uma nova venda.
PDVApp
Esta classe Singleton é responsável pela inteligência da aplicação. Através desta classe são realizadas todas as as ações de vendas, configurações, validações, segurança etc. Assim como uma camada "CRUD", esta classe faz a ligação entre as partes do sistema (CFSystem, Impressoras, TEF, Banco de Dados, etc.) e a interface do usuário (PDVUI).
Qualquer comando que o PDVUI receba do usuário, deve ser passado e tratado dentro do PDVApp, sincronizado se for o caso. O PDVApp processa e valida o comando.
Abaixo o mapa completo dos estados e "sub-estados" que o PDVApp pode assumir:
PDVState
O PDVApp pode ser considerado uma máquina de estados se analisar os passos que ele segue, e que ele guia o usuário. O controle do passo em que o PDVApp está é feito através do atributo PDVState dentro do próprio PDVApp.
Assim que aplicação é iniciada, este estado é inicializado com o valor "START", que implica que aplicação está iniciando. Em seguida ela seguirá o fluxo conforme a imagem abaixo:
PDVStateSales
Estes estatus servem como sub-status quando o PDVState está em SALES. Estes estados tem a função de definir em que passo da venda o PDVApp está no momento.
Quando o PDVState entrar no estado "SALES", o PDVStateSales deve iniciar no valor "NONE". Assim como para que o PDVState possa sair do estado "SALES", é obrigatório que o PDVStateSales tenha o valor "NONE".
Recuperação de Desligamento
Em caso de recuperação de desligamento incorreto, o sistema pode entrar no modo PDVState "SALES" e o PDVStateSales já ter um valor carregado diferente. Que tenha sido persistido e recuperado junto com o CheckoutDat
NONE - Este estado indica que embora o PDVApp esteja no estado de venda, no momento não há nenhuma venda ocorrendo. Toda vez que o PDVState entrar em Selling, o PDVStateSales inicia neste estado. Assim como, para que o PDVState saia do estado Selling, é necessário que o PDVStateSales já tenha retornado para o NONE.
Apenas no caso de recuperação de desligamento incorreto o sistema o PDVState pode entrar em Selling, e já encontrar o PDVStateSale em um estado diferente.
SALE_SELLING - Este estado indica que há uma venda ocorrendo neste momento, e que a venda está efetivamente no estado de "venda". Isto é, indica que a venda está no processo de registrar os itens que estão sendo vendidos ao consumidor.
SALE_PAYMENT - Após o término do estado anterior, quando todos os itens já estão registrados para venda, passamos para o estado de planejamento dos pagamentos. Neste passo indicamos para o sistema como os pagamentos serão realizados. Só conseguimos passar para o passo seguinte depois de informar pagamentos suficientes para quitar o total dos produtos vendidos no passo anterior.
SALE_FINALIZATION - Após informar os produtos e as formas de pagamento, o sistema entra neste passo para finalizar toda a venda. Neste passo o sistema processa toda a informação fornecida nos passos anteriores (itens e pagamentos), e executa tudo o que for necessário. Por exemplo, pagamentos com TEF, Tiquetes e outras operações que envolvam sistemas externos serão notificados e ativados no processamento deste passo.
Ao entrar neste passo o usuário não terá mais autonomia para retornar aos passos anteriores. A única condição que permitirá que o usuário volte ao passo anterior será a ocorrência de algum erro durante o processamento E QUE permita esse retrocesso ao passo anterior.
SALE_SHOW - Ao terminar o processamento de finalização da venda, o sistema para neste passo. Neste passo o cupom e as informações continuam carregadas no PDVApp mas já estão todas processadas, salvas e finalizadas. Este passo tem apenas a finalidade de permitir que informações sejam exibidas ao usuário pelo UI. Assim que o usuário as confirmar, o sistema descarrega das variáveis esta venda e volta para o passo NONE, preparando-se para outra venda ou outra operação.
PDVApp Listeners
PDVSaleEventListener
Este listener oferece notificações dos eventos relacionados a operação de venda ao consumidor. Como por exemplo, "Nova venda iniciada" (OPENCUPOM), "Última Venda Cancelada" (CALCELLASTCFX), "Venda atual cancelada" (CANCELHALFCFX), "Item Vendido/Registrado" (ITEMSOLD), e assim por diante....
PDVStateChangeListener
Este listener é acionado a cada alteração no valor do PDVState.
StartCheck
StartCheck é a rotina de inicialização que o PDVApp executa logo após a aplicação ser iniciada, antes que o usuário possa realizar qualquer interação com a aplicação. A rotina do StartCheck segue os passos conforme o Fluxograma abaixo:
INITING - é apenas o primeiro estado, o estado inicial de quando a aplicação é carregada. Não há nenhuma execução neste estado, apenas é passado para o próximo.
CHECKING_LOCALDB - Este passo é responsável por verificar o banco de dados local. Verifica sua existência e tentativa de conexão. Caso ele não exista, é criado. Caso não seja possível conectar, lança erro avisando o usuário que provavelmente há outra instância da aplicação rodando.
CHECKING_LOCALDB_VERSION - Complementar a tarefa anterior, neste passo o sistema verifica a versão do banco de dados atual. Caso a aplicação tenha sido atualizada este passo executará os comandos necessários para atualizar o banco antes que o resto da aplicação tente acessa-lo. Caso a atualização tenha algum problema a aplicação é encerrada para evitar que o uso dos dados de forma incorreta danifiquem os dados.
CHECKING_INSTALLATION - Este passo é essencial para a configuração da aplicação. Antes que o usuário possa utilizar a aplicação é necessário que alguma configurações sejam definidas, como por exemplo endereço do servidor, e periféricos pertinentes ao caixa. Caso a verificação perceba que alguma configuração inicial é necessária o StartCheck será interrompido e o sistema entrará no estado INSTALLATION_NEEDED.
Ao entrar neste estado o PDVUI detecta e exibirá o Wizard de configuração para o usuário. Uma vez que o Wizard seja finalizado ele envia ao PDVApp o comando para tentar o CHECKING_INSTALLATION novamente. E em caso de sucesso, seguirá para o próximo passo.
Note que a maior parte das configurações, principalmente as que são iguais para todos os caixas, é definida pelo servidor e sincronizada para todos os caixas. Não há como altera-las diretamente na aplicação.
INSTALLATION_OK - Neste passo não há processamento, é apenas um passo indicativo de que a instalação está OK e que pode continuar. Um estado "contrário" ao INSTALLATION_NEEDED, fazendo que o StartCheck continue sua rotina.
CHECKING_SERVER_ID - Durante a primeira inicialização/instalação da aplicação ela se registrará no servidor recebendo um ID único para identificação deste terminal deste ponto em diante. Servindo para rastrear tudo o que acontece em cada caixa/terminal de atendimento.
OK - Este é o passo final, que indica para as outras rotinas de que o StartCheck finalizou com sucesso é que o PDVApp está pronto para seguir para o próximo passo.
CFSystem
O CFSystem (Sistema de Cupom Fiscal) é o nome dado para o encapsulamento dos diferentes sistemas de emissão de cupom fiscal - SAT, ECF, NFCe, etc. - suportados atualmente ou que venham a existir no futuro. Separando o controle da emissão do cupom fiscal das rotinas do sistema permite que o mesmo app seja reaproveitado para todas as tecnologias existes com pouca ou nenhuma adaptação.
Esse encapsulamento funciona porque embora independente de como a tecnologia da emissão funcione a rotina de venda é sempre a mesma de forma geral: "Inicia a Venda - Registra Produtos - Executa Descontos e Totalizações - Recebe Pagamentos - Finaliza Venda". A cada passo da venda o PDVApp chamará os métodos da interface do CFSystem para notificar os acontecimentos da venda. Devendo o CFSystem traduzir e organizar o funcionamento para cada tecnologia.
O CFSystem é uma interface que permite as implementações das distintas tecnologias. Assim, cada implementação do CFSystem representa um equipamento e modelo de emissão diferentes. Por exemplo, a implementação para suporte do ECF Daruma é uma classe "CFSystemECFDaruma" que implementa a CFSystem.
O CFSystem também apresenta os métodos para impressão de relatórios gerenciais e outros documentos não fiscais.
CFSystemFactory
Esta classe permite que a implementação correta do CFSystem seja retornada de acordo com os parâmetros de configuração passados. Seguindo o pattern "Factory".
Cupom Fiscal / PDVCupomVO
Independente do sistema de emissão do cupom fiscal, o cupom fiscal é representado no sistema pelo PDVCupomVO. Para cada tipo de cupom fiscal (emitido por sistemas diferentes) o objeto apresentará um conjunto de atributos obrigatórios.
Ciclo de Vida do Cupom Fiscal
O cupom fiscal segue um ciclo de vida básico representado pela enumeration PDVCUPOMSTATUS, conforme o diagrama abaixo:
Estados Adicionais
Alguns sistemas de emissão, como o NFCe, apresentam mais estados por conta do controle de transmissão e emissão. Esses estados adicionais serão tratados no capítulo próprio do sistema. Vale a pena verifica se esses estados devem continuar utilizando a mesma variável ou se deve ter um conjunto de estados a parte dentro do VO, para não interferir no funcionamento do PDVApp, uma vez que o sistema de emissão é abstraído pela interface CFSystem.
