BISPDV

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.

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 checkout, se tiver persistido, ou se encontrar no banco de dados algum checkout aberto.

  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.

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)

PayGo

O PayGo é o sistema integrado de TEF do sistma.

Observações Importantes:

• Site de suporte e manual do desenvolvedor: https://paygodev.readme.io/docs/vis%C3%A3o-geral
• Download do Kit de Integração: https://paygodev.readme.io/docs/kit-de-integra%C3%A7%C3%A3o-2
• 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.

SAT

Informações

• Site Oficial: https://portal.fazenda.sp.gov.br/servicos/sat

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.