Canteen Technical Deep Dive

Principais pontosKey takeaways

Resumo para developers que estão a entrar no módulo de cantina.Summary for developers onboarding into the canteen module.

MistoMixed

Fluxo confirmadoConfirmed flow

Existem CanteenWindow, CanteenEntriesViewModel, CanteenReader e chamadas a MealsDataStore para validação.CanteenWindow, CanteenEntriesViewModel, CanteenReader, and MealsDataStore validation calls exist.

Leitor pode ser local ou redeReader can be local or network

A documentação confirma ambos os padrões gerais; o caminho exato depende do tipo de host/configuração.The documentation confirms both general patterns; the exact path depends on host type/configuration.

UI recebe eventosUI receives events

GateEntries também notifica entradas de cantina para consumidores inscritos.GateEntries also notifies canteen entries to subscribed consumers.

1. O que a interface de cantina faz1. What the canteen interface does

A cantina valida se um cartão/utilizador pode efetuar entrada ou consumo de refeição e atualiza UI/histórico.The canteen validates whether a card/user can enter or consume a meal and updates UI/history.

ConfirmadoConfirmed

Responsabilidades funcionaisFunctional responsibilities

Ler token/cartão de utilizador.Read user token/card.
Validar entrada/refeição contra regras de negócio.Validate entry/meal against business rules.
Mostrar resultado numa janela de monitorização.Show result in a monitoring window.
Registar histórico de entrada/refeição.Record entry/meal history.

Assunção importanteImportant assumption

A documentação confirma classes e chamadas principais, mas alguns detalhes de UI e regras de refeições exigem validação em código/ambiente real.The documentation confirms key classes and calls, but some UI details and meal-rule details require validation in code/a real environment.

2. Arquitetura runtime da cantina2. Canteen runtime architecture

A cantina pode receber tokens por leitor local no POS ou por leitores de rede geridos pelo DSCommServer.Canteen can receive tokens through a local POS reader or through network readers managed by DSCommServer.

Confirmado + inferidoConfirmed + inferred

Arquitetura runtime da cantinaCanteen runtime architecture

flowchart LR
    Card["Cartão/RFID"]
    LocalReader["Leitor local COM"]
    NetReader["CanteenReader de rede"]
    POS["DigiSchool.POS"]
    CanteenVM["CanteenEntriesViewModel"]
    DSComm["DSCommServer"]
    DSCore["DSCore"]
    Meals["MealsDataStore"]
    DB[("Base de dados")]

    Card --> LocalReader --> POS --> CanteenVM --> DSCore
    Card --> NetReader --> DSComm --> DSCore
    DSCore --> Meals --> DB
    DSComm -->|"NotifyCanteen"| DSCore
    DSCore -->|"callback"| POS

flowchart LR
    Card["Card/RFID"]
    LocalReader["Local COM reader"]
    NetReader["Network CanteenReader"]
    POS["DigiSchool.POS"]
    CanteenVM["CanteenEntriesViewModel"]
    DSComm["DSCommServer"]
    DSCore["DSCore"]
    Meals["MealsDataStore"]
    DB[("Database")]

    Card --> LocalReader --> POS --> CanteenVM --> DSCore
    Card --> NetReader --> DSComm --> DSCore
    DSCore --> Meals --> DB
    DSComm -->|"NotifyCanteen"| DSCore
    DSCore -->|"callback"| POS

3. Validação de cartões e entradas3. Card and entry validation

A validação usa identidade do cartão, host/direção quando aplicável, regras de refeições e histórico.Validation uses card identity, host/direction when applicable, meal rules, and history.

FluxoFlow

Fluxo de validação de cartãoCard validation flow

sequenceDiagram
    autonumber
    participant User as Utilizador
    participant Reader as Leitor
    participant Runtime as POS ou DSComm
    participant Core as DSCore
    participant Meals as MealsDataStore
    participant DB as Base de dados
    participant UI as UI cantina

    User->>Reader: Apresenta cartão
    Reader->>Runtime: Envia token
    Runtime->>Core: Pede validação de cantina
    Core->>Meals: Valida regras/refeição
    Meals->>DB: Lê utilizador, marcações, histórico
    DB-->>Meals: Dados
    Meals-->>Core: Resultado
    Core-->>Runtime: Aceite ou recusado
    Core-->>UI: Notificação de entrada

sequenceDiagram
    autonumber
    participant User
    participant Reader
    participant Runtime as POS or DSComm
    participant Core as DSCore
    participant Meals as MealsDataStore
    participant DB as Database
    participant UI as Canteen UI

    User->>Reader: Presents card
    Reader->>Runtime: Sends token
    Runtime->>Core: Requests canteen validation
    Core->>Meals: Validates meal rules
    Meals->>DB: Reads user, bookings, history
    DB-->>Meals: Data
    Meals-->>Core: Result
    Core-->>Runtime: Accepted or denied
    Core-->>UI: Entry notification

Processamento de entrada de cantinaCanteen entry processing flow

flowchart TB
    Token["Token/cartão"]
    User["Resolver utilizador"]
    Rules["Validar refeição/regra"]
    History["Registar entrada"]
    Feedback["Responder leitor/UI"]
    Notify["Notificar consumidores"]

    Token --> User --> Rules
    Rules --> History
    Rules --> Feedback
    History --> Notify

flowchart TB
    Token["Token/card"]
    User["Resolve user"]
    Rules["Validate meal/rule"]
    History["Record entry"]
    Feedback["Respond to reader/UI"]
    Notify["Notify consumers"]

    Token --> User --> Rules
    Rules --> History
    Rules --> Feedback
    History --> Notify

4. Relação UI, serviços e dados4. UI, service, and data relationship

A UI é uma janela WPF, mas as decisões e persistência vivem em DSCore/data stores.The UI is a WPF window, but decisions and persistence live in DSCore/data stores.

ComponentesComponents

Relação UI / serviço / dadosUI / service / data relationship

flowchart LR
    Window["CanteenWindow"]
    VM["CanteenEntriesViewModel"]
    GateEntries["GateEntriesService callbacks"]
    Core["DSCore"]
    Meals["MealsDataStore"]
    DB[("Base de dados")]
    Reader["Leitor local ou rede"]

    Reader --> VM
    Window --> VM
    VM --> Core
    Core --> Meals --> DB
    GateEntries --> VM

flowchart LR
    Window["CanteenWindow"]
    VM["CanteenEntriesViewModel"]
    GateEntries["GateEntriesService callbacks"]
    Core["DSCore"]
    Meals["MealsDataStore"]
    DB[("Database")]
    Reader["Local or network reader"]

    Reader --> VM
    Window --> VM
    VM --> Core
    Core --> Meals --> DB
    GateEntries --> VM

ComponenteComponent	Papel provável/confirmadoLikely/confirmed role
`CanteenWindow.xaml`	Janela WPF do monitor de cantina.WPF canteen monitor window.
`CanteenEntriesViewModel`	ViewModel associada a entradas/validações de cantina.ViewModel associated with canteen entries/validations.
`MealsDataStore`	Regras e persistência ligadas a refeições/cantina.Rules and persistence related to meals/canteen.
`GateEntriesManager.NotifyCanteen`	Caminho de notificação de entradas de cantina a partir de DSComm.Notification path for canteen entries from DSComm.

5. Pontos prováveis de falha5. Likely failure points

Falhas de cantina podem estar na leitura do cartão, regra de refeição, UI ou callback.Canteen failures can be in card reading, meal rules, UI, or callbacks.

RiscosRisks

Leitor sem tokenReader has no token

Problema em COM, rede, IP, driver, cabo ou configuração de host.Issue in COM, network, IP, driver, cable, or host configuration.

Regra nega refeiçãoRule denies meal

Pode ser correto por marcações, horários, saldo, permissões ou histórico.May be correct due to bookings, schedules, balance, permissions, or history.

UI não atualizaUI does not update

Callback GateEntries ou subscrição POS pode estar desconectada.GateEntries callback or POS subscription may be disconnected.

6. Checklist de diagnóstico6. Debugging checklist

Siga o evento desde o cartão até à persistência/notificação.Follow the event from card to persistence/notification.

SuporteSupport

Leitura e validaçãoReading and validation

Identificar se o leitor é local COM ou rede via DSComm.Identify whether the reader is local COM or network via DSComm.
Confirmar que o token é recebido.Confirm the token is received.
Confirmar que DSCore/MealsDataStore recebe validação.Confirm DSCore/MealsDataStore receives validation.
Verificar resultado esperado contra regras de refeição.Check expected result against meal rules.

UI e históricoUI and history

Verificar se entrada/histórico foi criado na base de dados.Check whether entry/history was created in the database.
Confirmar que POS está subscrito a notificações.Confirm POS is subscribed to notifications.
Comparar timestamp nos logs POS, DSCore e DSComm.Compare timestamp in POS, DSCore, and DSComm logs.
Testar com cartão conhecido e regras simples.Test with a known card and simple rules.

7. Ficheiros e classes importantes7. Important files and classes

Entradas úteis para investigar cantina e refeições.Useful entry points to investigate canteen and meal behavior.

MapaMap

Ficheiro/classeFile/class	MotivoReason
`DigiSchool.POS/CanteenWindow.xaml`	Janela WPF de cantina.Canteen WPF window.
`CanteenEntriesViewModel`	ViewModel de entradas/validações de cantina.ViewModel for canteen entries/validations.
`DigiSchool.POS/Code/CommunicationManager.cs`	Caminho de leitor local COM.Local COM reader path.
`DigiSchool.DSCommServer/Server/UDPManager.cs`	Caminho de leitor de rede CanteenReader.Network CanteenReader path.
`DigiSchool.DSCore/Services/GateEntries/GateEntriesService.cs`	Callbacks/notificações de entradas.Entry callbacks/notifications.
`DigiSchool.Data/DataStores/MealsDataStore.cs`	Regras/persistência de refeições.Meal rules/persistence.

8. Oportunidades de modernização8. Modernization opportunities

A cantina beneficiaria de um modelo explícito de validação, observabilidade e testes de regras.Canteen would benefit from an explicit validation model, observability, and rule tests.

FuturoFuture

Arquitetura futura da cantinaFuture canteen architecture

flowchart LR
    UI["UI cantina atual/futura"]
    API["API local/serviço"]
    Reader["Adapter leitor cartão"]
    CanteenAPI["Facade validação cantina"]
    DSCore["DSCore existente"]
    Health["Health e auditoria"]

    UI --> API
    API --> Reader
    API --> CanteenAPI
    CanteenAPI --> DSCore
    Reader --> Health
    CanteenAPI --> Health

flowchart LR
    UI["Current/future canteen UI"]
    API["Local API/service"]
    Reader["Card reader adapter"]
    CanteenAPI["Canteen validation facade"]
    DSCore["Existing DSCore"]
    Health["Health and audit"]

    UI --> API
    API --> Reader
    API --> CanteenAPI
    CanteenAPI --> DSCore
    Reader --> Health
    CanteenAPI --> Health

TestesTests

Criar fixtures para cartões, marcações, horários e resultados esperados.Create fixtures for cards, bookings, schedules, and expected results.

ObservabilidadeObservability

Expor último token, última validação, razão de negação e estado de callback.Expose last token, last validation, denial reason, and callback state.

9. Questões ainda a validar9. Questions still to validate

Alguns detalhes devem ser confirmados com código específico e ambiente operacional.Some details should be confirmed with specific code and operational environment.

AssunçõesAssumptions

Qual é o caminho dominante em produção: leitor local COM ou leitor de rede CanteenReader?What is the dominant production path: local COM reader or network CanteenReader?
Que regras exatas decidem consumo de refeição, repetição e horários?Which exact rules decide meal consumption, duplicates, and schedules?
Que dados são apresentados na UI em caso de negação?Which data is shown in the UI when denied?
Há emuladores/testes específicos de cantina?Are there canteen-specific emulators/tests?