🖥️ Kiosk / POS
Análise técnica aprofundadaTechnical deep dive

Kiosk, POS e self-serviceKiosk, POS, and self-service

Como a aplicação WPF DigiSchool.POS combina interface de utilizador, chamadas a DSCore e integração com hardware local como leitores, dinheiro, impressoras, scanner e webcam. How the DigiSchool.POS WPF application combines user interface, DSCore service calls, and local hardware integration such as readers, cash devices, printers, scanner, and webcam.

Principais pontosKey takeaways

A visão essencial para onboarding técnico no módulo kiosk/POS.The essential view for technical onboarding on the kiosk/POS module.

ConfirmadoConfirmed

POS é UI e runtime de hardwarePOS is UI and hardware runtime

A aplicação WPF não é apenas ecrãs: também abre portas COM, controla dinheiro, imprime e recebe tokens.The WPF app is not only screens: it also opens COM ports, controls cash devices, prints, and receives tokens.

Self-service depende de timers e estadoSelf-service depends on timers and state

Os aceitadores de moedas/notas podem ser ativados/desativados por fluxo de pagamento e timers de inatividade.Coin/bill acceptors can be enabled/disabled by the payment flow and inactivity timers.

DSCore continua a decidir negócioDSCore still decides business

O POS recolhe eventos locais, mas vendas, validações e regras passam por serviços DSCore.POS collects local events, but sales, validations, and rules go through DSCore services.

1. O que a interface kiosk/POS faz1. What the kiosk/POS interface does

DigiSchool.POS pode assumir vários papéis conforme o tipo de host configurado.DigiSchool.POS can take several roles depending on the configured host type.

ConfirmadoConfirmed

Modos principaisMain modes

  • POS de operador para vendas e operações de conta.Operator POS for sales and account operations.
  • Kiosk self-service para carregamento/top-up.Self-service kiosk for recharge/top-up.
  • Monitor de portões e cantina, através de janelas dedicadas.Gate and canteen monitor through dedicated windows.
  • Login e seleção/configuração de host.Login and host selection/configuration.

Responsabilidade técnicaTechnical responsibility

O POS gere UI, estado de carrinho/top-up, chamadas WCF para DSCore, integração de hardware local e preferências como porta COM, impressora e fullscreen.POS manages UI, cart/top-up state, WCF calls to DSCore, local hardware integration, and preferences such as COM port, printer, and fullscreen mode.

2. Janelas, views e ViewModels2. Windows, views, and ViewModels

A arquitetura é parcialmente MVVM, mas o código mostra acoplamento entre UI, ViewModels e hardware.The architecture is partially MVVM, but the code shows coupling between UI, ViewModels, and hardware.

ConfirmadoConfirmed
ElementoElement PapelRole NotasNotes
LoginWindow Entrada inicial da aplicação.Initial application entry point. Define o caminho até ao host/módulo ativo.Leads to the active host/module.
POSWindow, POSSelfServiceWindow, POSSelServiceWindow Experiência POS e self-service.POS and self-service experience. Inclui captura de teclado/barcode e timers de inatividade.Includes keyboard/barcode capture and inactivity timers.
HostViewModel Seleciona janela/módulo conforme host type.Selects window/module based on host type. Também cria gestores de comunicação local para leitores COM.Also creates local communication managers for COM readers.
PosViewModel Carrinho, vendas, top-up e dinheiro.Cart, sales, top-up, and cash devices. Liga callbacks de BillMachine/CoinMachine e imprime recibos.Wires BillMachine/CoinMachine callbacks and prints receipts.
SettingsControlViewModel Configuração de portas COM, impressoras e fullscreen.COM port, printer, and fullscreen configuration. Enumera portas via SerialPort.GetPortNames().Enumerates ports through SerialPort.GetPortNames().

3. Integração de hardware local3. Local hardware integration

Dispositivos ligados à máquina kiosk/POS são controlados diretamente pelo processo WPF.Devices connected to the kiosk/POS machine are controlled directly by the WPF process.

ConfirmadoConfirmed
Arquitetura runtime do kioskKiosk runtime architecture
flowchart TB
    POS["DigiSchool.POS WPF"]
    HostVM["HostViewModel"]
    PosVM["PosViewModel"]
    Settings["SettingsControlViewModel"]
    DSCore["DSCore WCF"]
    Local["Hardware local"]
    Bill["BillMachine"]
    Coin["CoinMachine"]
    Cashlogy["CashlogyMachine"]
    RFID["COMCommunicationManager"]
    Printer["Windows PrintQueue"]
    Scanner["Barcode via teclado"]
    Webcam["WebcamPlayer"]

    POS --> HostVM
    HostVM --> PosVM
    HostVM --> Settings
    POS --> DSCore
    PosVM --> Bill
    PosVM --> Coin
    PosVM --> Cashlogy
    HostVM --> RFID
    PosVM --> Printer
    POS --> Scanner
    POS --> Webcam
    Bill --> Local
    Coin --> Local
    Cashlogy --> Local
    RFID --> Local
          
flowchart TB
    POS["DigiSchool.POS WPF"]
    HostVM["HostViewModel"]
    PosVM["PosViewModel"]
    Settings["SettingsControlViewModel"]
    DSCore["DSCore WCF"]
    Local["Local hardware"]
    Bill["BillMachine"]
    Coin["CoinMachine"]
    Cashlogy["CashlogyMachine"]
    RFID["COMCommunicationManager"]
    Printer["Windows PrintQueue"]
    Scanner["Barcode via keyboard"]
    Webcam["WebcamPlayer"]

    POS --> HostVM
    HostVM --> PosVM
    HostVM --> Settings
    POS --> DSCore
    PosVM --> Bill
    PosVM --> Coin
    PosVM --> Cashlogy
    HostVM --> RFID
    PosVM --> Printer
    POS --> Scanner
    POS --> Webcam
    Bill --> Local
    Coin --> Local
    Cashlogy --> Local
    RFID --> Local

Bill validatorBill validator

Serial 9600, paridade Even, protocolo binário com CRC, escrow, ACK e stack.Serial 9600, Even parity, binary protocol with CRC, escrow, ACK, and stack.

Coin acceptorCoin acceptor

Serial 38400, mensagens ASCII como #ACON*, #ACOFF* e #AC-OK*.Serial 38400, ASCII messages such as #ACON*, #ACOFF*, and #AC-OK*.

CashlogyCashlogy

Classe TCP existe; integração parece opcional ou dependente de configuração.TCP class exists; integration appears optional or configuration-dependent.

ImpressoraPrinter

Usa filas Windows PrintQueue/XPS, não comandos ESC/POS raw confirmados.Uses Windows PrintQueue/XPS; raw ESC/POS commands are not confirmed.

Barcode scannerBarcode scanner

Provavelmente keyboard wedge: o POS interpreta eventos de teclado.Likely keyboard wedge: POS interprets keyboard events.

RFID localLocal RFID

Leitor COM 9600 N 8 1; tokens normalizados em formatos como #TOKEN*.COM reader 9600 N 8 1; tokens normalized into formats such as #TOKEN*.

4. Fluxos principais4. Main flows

Estes fluxos ajudam a diagnosticar falhas do POS/self-service fim a fim.These flows help diagnose POS/self-service failures end to end.

SequênciasSequences
Sequência de inserção de dinheiroMoney insertion sequence
sequenceDiagram
    autonumber
    participant User as Utilizador
    participant Device as Moeda/Nota
    participant Driver as CoinMachine/BillMachine
    participant POS as PosViewModel
    participant Sales as DSCore SalesService
    participant DB as Base de dados
    participant Printer as Impressora

    User->>Device: Insere dinheiro
    Device->>Driver: Mensagem serial
    Driver->>Driver: Valida código, estado ou CRC
    Driver->>POS: onDataInbound(valor/código)
    POS->>POS: Atualiza top-up/carrinho
    POS->>Sales: Regista venda ou carregamento
    Sales->>DB: Persiste transação
    POS->>Printer: Imprime recibo se configurado
          
sequenceDiagram
    autonumber
    participant User
    participant Device as Coin/Bill device
    participant Driver as CoinMachine/BillMachine
    participant POS as PosViewModel
    participant Sales as DSCore SalesService
    participant DB as Database
    participant Printer

    User->>Device: Inserts money
    Device->>Driver: Serial message
    Driver->>Driver: Validate code, status, or CRC
    Driver->>POS: onDataInbound(amount/code)
    POS->>POS: Update top-up/cart
    POS->>Sales: Register sale or recharge
    Sales->>DB: Persist transaction
    POS->>Printer: Print receipt if configured
Comunicação com hardware localLocal hardware communication
flowchart LR
    POS["DigiSchool.POS"]
    RFID["Leitor RFID COM"]
    Bill["Validador notas COM"]
    Coin["Moedeiro COM"]
    Cashlogy["Cashlogy TCP"]
    Printer["Impressora Windows"]
    Barcode["Scanner teclado"]
    Webcam["Webcam"]

    RFID --> POS
    Bill --> POS
    Coin --> POS
    Cashlogy --> POS
    POS --> Printer
    Barcode --> POS
    Webcam --> POS
          
flowchart LR
    POS["DigiSchool.POS"]
    RFID["RFID COM reader"]
    Bill["Bill validator COM"]
    Coin["Coin acceptor COM"]
    Cashlogy["Cashlogy TCP"]
    Printer["Windows printer"]
    Barcode["Keyboard scanner"]
    Webcam["Webcam"]

    RFID --> POS
    Bill --> POS
    Coin --> POS
    Cashlogy --> POS
    POS --> Printer
    Barcode --> POS
    Webcam --> POS
Fluxo POS para serviços DSCorePOS to DSCore service flow
sequenceDiagram
    autonumber
    participant POS as POS WPF
    participant VM as ViewModel
    participant Proxy as Cliente WCF
    participant DSCore as DSCore
    participant Store as DataStore
    participant DB as Base de dados

    POS->>VM: Ação do operador ou evento hardware
    VM->>Proxy: Chamada serviço local
    Proxy->>DSCore: WCF net.tcp
    DSCore->>Store: Regra de negócio
    Store->>DB: Leitura/escrita
    DB-->>Store: Resultado
    DSCore-->>VM: Resposta
    VM-->>POS: Atualiza UI
          
sequenceDiagram
    autonumber
    participant POS as POS WPF
    participant VM as ViewModel
    participant Proxy as WCF client
    participant DSCore
    participant Store as DataStore
    participant DB as Database

    POS->>VM: Operator action or hardware event
    VM->>Proxy: Local service call
    Proxy->>DSCore: WCF net.tcp
    DSCore->>Store: Business rule
    Store->>DB: Read/write
    DB-->>Store: Result
    DSCore-->>VM: Response
    VM-->>POS: Update UI

5. Configuração e startup5. Configuration and startup

A execução correta depende de configuração local, serviços e drivers.Correct execution depends on local configuration, services, and drivers.

DependênciasDependencies

Dependências típicasTypical dependencies

  • HostId e tipo de host configurado.Configured HostId and host type.
  • Portas COM para leitores e dinheiro.COM ports for readers and cash devices.
  • Nome da impressora Windows.Windows printer name.
  • Serviços DSCore ativos e endpoints WCF acessíveis.DSCore services running and WCF endpoints reachable.
  • Drivers USB/serial, printer e webcam instalados.USB/serial, printer, and webcam drivers installed.

Startup simplificadoSimplified startup

  1. Windows inicia e serviços de backend devem estar disponíveis.Windows starts and backend services should be available.
  2. DigiSchool.POS abre em LoginWindow.DigiSchool.POS opens at LoginWindow.
  3. HostViewModel escolhe o módulo conforme host type.HostViewModel selects the module based on host type.
  4. Gestores locais abrem portas/dispositivos configurados.Local managers open configured ports/devices.
  5. ViewModels começam a chamar serviços DSCore.ViewModels start calling DSCore services.

6. Pontos prováveis de falha6. Likely failure points

Kiosks falham muitas vezes por configuração ou hardware local, não apenas por código.Kiosks often fail because of local configuration or hardware, not only code.

Risco operacionalOperational risk

Porta COM erradaWrong COM port

O dispositivo pode estar ligado mas invisível para a aplicação.The device may be connected but invisible to the application.

Dispositivo ocupadoDevice already open

Outra aplicação pode ter bloqueado a porta serial ou impressora.Another application may have locked the serial port or printer.

DSCore indisponívelDSCore unavailable

UI abre, mas vendas/validações podem falhar.UI opens, but sales/validations may fail.

Timers de inatividadeInactivity timers

Self-service pode desativar aceitadores antes da conclusão do fluxo.Self-service may disable acceptors before the flow completes.

Printer driver/filaPrinter driver/queue

A aplicação usa a fila Windows; problemas da fila afetam recibos.The app uses the Windows queue; queue issues affect receipts.

Parsing de mensagensMessage parsing

Mensagens parciais de hardware podem não produzir eventos esperados.Partial hardware messages may not produce expected events.

7. Checklist de diagnóstico7. Debugging checklist

Comece pelo físico, confirme configuração, depois siga o evento até DSCore.Start with the physical layer, confirm configuration, then follow the event to DSCore.

SuporteSupport

Hardware localLocal hardware

  • Confirmar energia, cabos e drivers.Confirm power, cables, and drivers.
  • Confirmar porta COM em Device Manager.Confirm COM port in Device Manager.
  • Confirmar que a porta/impressora não está ocupada.Confirm the port/printer is not already in use.
  • Verificar definições guardadas no POS.Check settings stored in POS.

Fluxo de negócioBusiness flow

  • Confirmar que DSCore está ativo.Confirm DSCore is running.
  • Reproduzir evento e anotar hora exata.Reproduce event and record exact timestamp.
  • Verificar logs do POS e DSCore nessa janela.Check POS and DSCore logs in that window.
  • Confirmar transação/histórico na base de dados, se aplicável.Confirm transaction/history in database if applicable.

8. Ficheiros e classes importantes8. Important files and classes

Pontos de entrada para onboarding e investigação.Entry points for onboarding and investigation.

Mapa de códigoCode map
Ficheiro/classeFile/class MotivoReason
DigiSchool.POS/App.xaml, LoginWindow.xamlStartup e entrada da aplicação.Application startup and entry.
POSWindow.xaml, POSSelfServiceWindow.xaml, POSSelServiceWindow.xamlUI principal POS/self-service.Main POS/self-service UI.
HostViewModel.cs, PosViewModel.csSeleção de módulo, carrinho, vendas e hardware.Module selection, cart, sales, and hardware.
CommunicationManager.csLeitor RFID local via COM.Local RFID reader over COM.
BillMachine.cs, CoinMachine.cs, CashlogyMachine.csDispositivos de dinheiro.Cash devices.
Crc16CcittKermit.csCRC usado pelo validador de notas.CRC used by the bill validator.
Code/WebcamPlayerIntegração de webcam.Webcam integration.

9. Oportunidades de modernização9. Modernization opportunities

Modernizar kiosk com segurança exige separar UI, hardware e serviços gradualmente.Modernizing kiosk safely requires gradually separating UI, hardware, and services.

RoadmapRoadmap
Arquitetura futura do kioskFuture kiosk architecture
flowchart LR
    UI["UI WPF atual ou futura web/Electron"]
    API["API local do kiosk"]
    Devices["Serviço/adapters de hardware"]
    CoreAPI["Facade para DSCore"]
    DSCore["DSCore existente"]
    Health["Health dashboard"]

    UI --> API
    API --> Devices
    API --> CoreAPI
    CoreAPI --> DSCore
    Devices --> Health
    CoreAPI --> Health
          
flowchart LR
    UI["Current WPF or future web/Electron UI"]
    API["Local kiosk API"]
    Devices["Hardware service/adapters"]
    CoreAPI["DSCore facade"]
    DSCore["Existing DSCore"]
    Health["Health dashboard"]

    UI --> API
    API --> Devices
    API --> CoreAPI
    CoreAPI --> DSCore
    Devices --> Health
    CoreAPI --> Health

PreservarPreserve

Regras DSCore, configurações de host e protocolos existentes até haver testes e diagnóstico.DSCore rules, host configuration, and existing protocols until tests and diagnostics exist.

RefatorarRefactor

Introduzir interfaces para leitores, dinheiro, impressora e health reporting antes de trocar UI.Introduce interfaces for readers, cash devices, printer, and health reporting before replacing UI.

10. Questões ainda a validar10. Questions still to validate

Estas perguntas exigem ambiente real, documentação de hardware ou confirmação operacional.These questions require a real environment, hardware documentation, or operational confirmation.

AssunçõesAssumptions
  • Quais modelos físicos exatos de bill validator, coin acceptor e leitores RFID estão em produção?Which exact physical bill validator, coin acceptor, and RFID reader models are in production?
  • Cashlogy está ativo em clientes atuais ou apenas suportado pelo código?Is Cashlogy active in current customers or only supported by code?
  • Quais logs são recolhidos em produção e por quanto tempo?Which logs are collected in production and for how long?
  • Há procedimentos de campo para troca de COM ports, impressoras e drivers?Are there field procedures for changing COM ports, printers, and drivers?