Gates / Entries Technical Deep Dive

Principais pontosKey takeaways

O fluxo de acesso cruza UI, WCF, base de dados e hardware físico.The access flow crosses UI, WCF, database, and physical hardware.

ConfirmadoConfirmed

DSCore decideDSCore decides

A autorização de acesso passa por AccessControlDataStore e regras associadas a token, host e direção.Access authorization goes through AccessControlDataStore and rules tied to token, host, and direction.

DSComm traduzDSComm translates

Leitores de rede, portas e controladores UDP são geridos por DSCommServer.Network readers, doors, and UDP controllers are managed by DSCommServer.

POS observa e pode comandarPOS observes and can command

GateWindow/GatesViewModel mostram eventos e podem iniciar abertura manual.GateWindow/GatesViewModel show events and can initiate manual opening.

1. Papéis dos componentes1. Component roles

Estes nomes aparecem frequentemente no código e nos logs.These names appear frequently in code and logs.

MapaMap

ComponenteComponent	PapelRole
`DSCore`	Cérebro de negócio: valida acesso, cria autorizações e envia comandos.Business brain: validates access, creates authorizations, and sends commands.
`GatesService`	Serviço DSCore para validação de gate e abertura manual.DSCore service for gate validation and manual opening.
`GateEntriesService`	Serviço WCF duplex para comandos e notificações de entradas.Duplex WCF service for commands and entry notifications.
`GateEntriesManager`	Cliente DSComm para chamar GateEntries em DSCore.DSComm client for calling GateEntries in DSCore.
`UDPManager`	Gestor de hardware em DSComm: TCP listener e ciclo de canais UDP.Hardware manager in DSComm: TCP listener and UDP channel loop.
`UDPChannel`	Canal para controlador de porta/gate/vending; envia open/deny/keep-alive.Channel to door/gate/vending controller; sends open/deny/keep-alive.
`GatesViewModel`	ViewModel da UI de gate, valida leitor local e atualiza monitor.Gate UI ViewModel, validates local reader and updates monitor.

2. Arquitetura de portões2. Gates architecture

Há dois caminhos principais: leitores de rede via DSComm e leitores locais via POS.There are two main paths: network readers through DSComm and local readers through POS.

ConfirmadoConfirmed

Arquitetura de gatesGates architecture

flowchart TB
    Card["Cartão RFID"]
    NetReader["Leitor rede TCP"]
    LocalReader["Leitor local COM"]
    POS["DigiSchool.POS GateWindow"]
    GatesVM["GatesViewModel"]
    DSComm["DSCommServer"]
    UDPManager["UDPManager"]
    UDPChannel["UDPChannel"]
    Controller["Controlador porta/gate"]
    DSCore["DSCore"]
    GatesService["GatesService"]
    GateEntries["GateEntriesService"]
    Access["AccessControlDataStore"]
    DB[("Base de dados")]

    Card --> NetReader --> UDPManager
    Card --> LocalReader --> POS --> GatesVM --> GatesService
    DSComm --> UDPManager --> UDPChannel --> Controller
    UDPManager --> GateEntries
    GatesService --> Access --> DB
    GateEntries --> Access
    GateEntries --> POS
    DSCore --> GatesService
    DSCore --> GateEntries

flowchart TB
    Card["RFID card"]
    NetReader["TCP network reader"]
    LocalReader["Local COM reader"]
    POS["DigiSchool.POS GateWindow"]
    GatesVM["GatesViewModel"]
    DSComm["DSCommServer"]
    UDPManager["UDPManager"]
    UDPChannel["UDPChannel"]
    Controller["Door/gate controller"]
    DSCore["DSCore"]
    GatesService["GatesService"]
    GateEntries["GateEntriesService"]
    Access["AccessControlDataStore"]
    DB[("Database")]

    Card --> NetReader --> UDPManager
    Card --> LocalReader --> POS --> GatesVM --> GatesService
    DSComm --> UDPManager --> UDPChannel --> Controller
    UDPManager --> GateEntries
    GatesService --> Access --> DB
    GateEntries --> Access
    GateEntries --> POS
    DSCore --> GatesService
    DSCore --> GateEntries

3. Fluxos RFID de rede e local3. Network and local RFID flows

Use estes diagramas para seguir o evento desde o cartão até à resposta ao leitor.Use these diagrams to follow the event from card to reader response.

SequênciasSequences

Sequência de leitor RFID de redeNetwork RFID reader sequence

sequenceDiagram
    autonumber
    participant Card as Cartão
    participant Reader as Leitor TCP
    participant UDPManager as UDPManager
    participant GEManager as GateEntriesManager
    participant GateEntries as GateEntriesService
    participant Access as AccessControlDataStore
    participant DB as Base de dados
    participant POS as Monitor gate

    Card->>Reader: Cartão apresentado
    Reader->>UDPManager: Mensagem TCP com token e device number
    UDPManager->>UDPManager: Resolve host e direção
    UDPManager->>GEManager: RequestAutorization
    GEManager->>GateEntries: Chamada WCF
    GateEntries->>Access: Valida regras
    Access->>DB: Lê/escreve histórico
    Access-->>GateEntries: Resultado
    GateEntries-->>GEManager: Autorizado ou negado
    GEManager-->>UDPManager: Resultado
    UDPManager-->>Reader: code 0000 ou 1111
    GateEntries-->>POS: Callback de atividade

sequenceDiagram
    autonumber
    participant Card
    participant Reader as TCP reader
    participant UDPManager
    participant GEManager as GateEntriesManager
    participant GateEntries as GateEntriesService
    participant Access as AccessControlDataStore
    participant DB as Database
    participant POS as Gate monitor

    Card->>Reader: Card presented
    Reader->>UDPManager: TCP message with token and device number
    UDPManager->>UDPManager: Resolve host and direction
    UDPManager->>GEManager: RequestAutorization
    GEManager->>GateEntries: WCF call
    GateEntries->>Access: Validate rules
    Access->>DB: Read/write history
    Access-->>GateEntries: Result
    GateEntries-->>GEManager: Authorized or denied
    GEManager-->>UDPManager: Result
    UDPManager-->>Reader: code 0000 or 1111
    GateEntries-->>POS: Activity callback

Sequência de leitor local COMLocal COM reader sequence

sequenceDiagram
    autonumber
    participant Card as Cartão
    participant Reader as Leitor COM
    participant Comm as COMCommunicationManager
    participant POS as DigiSchool.POS
    participant GatesVM as GatesViewModel
    participant GatesService as GatesService
    participant Access as AccessControlDataStore

    Card->>Reader: Cartão apresentado
    Reader->>Comm: Texto serial como #TOKEN*
    Comm->>POS: NotifyNewToken
    POS->>GatesVM: Encaminha token
    GatesVM->>GatesService: ValidateUserEntryExit
    GatesService->>Access: Valida autorização
    Access-->>GatesService: Resultado
    GatesService-->>GatesVM: Resultado
    GatesVM->>Comm: SendOk ou SendNotOk
    GatesVM->>POS: Atualiza monitor

sequenceDiagram
    autonumber
    participant Card
    participant Reader as COM reader
    participant Comm as COMCommunicationManager
    participant POS as DigiSchool.POS
    participant GatesVM as GatesViewModel
    participant GatesService
    participant Access as AccessControlDataStore

    Card->>Reader: Card presented
    Reader->>Comm: Serial text such as #TOKEN*
    Comm->>POS: NotifyNewToken
    POS->>GatesVM: Route token
    GatesVM->>GatesService: ValidateUserEntryExit
    GatesService->>Access: Validate authorization
    Access-->>GatesService: Result
    GatesService-->>GatesVM: Result
    GatesVM->>Comm: SendOk or SendNotOk
    GatesVM->>POS: Update monitor

4. Abertura manual de porta/gate4. Manual door/gate opening

A UI pode iniciar uma abertura manual, mas o comando ainda passa por DSCore e DSComm.The UI can initiate manual opening, but the command still goes through DSCore and DSComm.

ConfirmadoConfirmed

Sequência de abertura manualManual open-door sequence

sequenceDiagram
    autonumber
    participant Operator as Operador
    participant POS as Gate UI
    participant GatesService as GatesService
    participant Access as AccessControlDataStore
    participant GateEntries as GateEntriesService
    participant DSComm as DSComm callback
    participant UDPManager as UDPManager
    participant Channel as UDPChannel
    participant Controller as Controlador

    Operator->>POS: Clica abrir
    POS->>GatesService: SetOpenDoorCommand
    GatesService->>Access: Cria autorização manual
    GatesService->>GateEntries: SendCommand open-door
    GateEntries-->>DSComm: Execute command
    DSComm->>UDPManager: Execute open-door
    UDPManager->>Channel: OpenDoor
    Channel->>Controller: Comando UDP de abertura

sequenceDiagram
    autonumber
    participant Operator
    participant POS as Gate UI
    participant GatesService
    participant Access as AccessControlDataStore
    participant GateEntries as GateEntriesService
    participant DSComm as DSComm callback
    participant UDPManager
    participant Channel as UDPChannel
    participant Controller

    Operator->>POS: Clicks open
    POS->>GatesService: SetOpenDoorCommand
    GatesService->>Access: Create manual authorization
    GatesService->>GateEntries: SendCommand open-door
    GateEntries-->>DSComm: Execute command
    DSComm->>UDPManager: Execute open-door
    UDPManager->>Channel: OpenDoor
    Channel->>Controller: UDP open command

5. Notificações e callbacks5. Notifications and callbacks

GateEntriesService é o ponto de coordenação para comandos e eventos em tempo real.GateEntriesService is the coordination point for commands and real-time events.

WCF duplexWCF duplex

Relação DSCore / DSComm / POS callbacksDSCore / DSComm / POS callback relationship

flowchart LR
    GateEntries["GateEntriesService"]
    POS["POS Gate UI: consumidor atividade"]
    DSComm["DSComm: processador comandos"]
    GatesService["GatesService"]
    UDPManager["UDPManager"]
    Access["AccessControlDataStore"]

    POS -->|"Subscribe"| GateEntries
    DSComm -->|"Subscribe"| GateEntries
    GatesService -->|"SendCommand"| GateEntries
    GateEntries -->|"Execute"| DSComm
    DSComm --> UDPManager
    UDPManager -->|"NotifyActivity"| GateEntries
    GateEntries -->|"NotifyNewACL"| POS
    GateEntries --> Access

flowchart LR
    GateEntries["GateEntriesService"]
    POS["POS Gate UI: activity consumer"]
    DSComm["DSComm: command processor"]
    GatesService["GatesService"]
    UDPManager["UDPManager"]
    Access["AccessControlDataStore"]

    POS -->|"Subscribe"| GateEntries
    DSComm -->|"Subscribe"| GateEntries
    GatesService -->|"SendCommand"| GateEntries
    GateEntries -->|"Execute"| DSComm
    DSComm --> UDPManager
    UDPManager -->|"NotifyActivity"| GateEntries
    GateEntries -->|"NotifyNewACL"| POS
    GateEntries --> Access

6. Direção de entrada/saída6. Entry/exit direction

A direção é parte da autorização: o mesmo cartão pode ter regras diferentes para entrada, saída ou origem desconhecida.Direction is part of authorization: the same card may have different rules for entry, exit, or unknown source.

Regra de acessoAccess rule

Onde apareceWhere it appears

Leitores de rede mapeiam host/direção antes de pedir autorização.Network readers map host/direction before requesting authorization.
Leitores locais usam configuração VirtualCardReader com direção.Local readers use VirtualCardReader configuration with direction.
Abertura manual pode receber door id e direção.Manual opening can receive door id and direction.

RiscoRisk

Direção errada pode causar autorização errada, histórico incorreto ou abertura de lado errado do controlador.Wrong direction can cause incorrect authorization, incorrect history, or opening the wrong controller side.

7. Pontos prováveis de falha7. Likely failure points

Falhas de gates podem estar em hardware, DSComm, DSCore, callbacks, regras ou configuração.Gate failures can be in hardware, DSComm, DSCore, callbacks, rules, or configuration.

OperaçãoOperations

Leitor não chega ao DSCommReader does not reach DSComm

Verificar IP, porta TCP, firewall, heartbeat e device number.Check IP, TCP port, firewall, heartbeat, and device number.

Canal UDP offlineUDP channel offline

Verificar host configurado, porta 1501/configurada, keep-alive e rede.Check configured host, port 1501/configured port, keep-alive, and network.

Callback perdidoLost callback

DSComm ou POS pode ter perdido subscrição WCF duplex.DSComm or POS may have lost WCF duplex subscription.

Regra nega acessoRule denies access

Negação pode ser correta por horário, permissão, cartão ou host.Denial may be correct due to schedule, permission, card, or host.

Direção erradaWrong direction

Entrada/saída invertida pode gerar histórico e decisão incorretos.Inverted entry/exit can create incorrect history and decisions.

Serviço paradoService stopped

DSCore ou DSCommServer parado interrompe validação ou comandos.Stopped DSCore or DSCommServer interrupts validation or commands.

8. Checklist de diagnóstico8. Debugging checklist

Siga o fluxo de leitura ou comando, sem saltar diretamente para o controlador físico.Follow the read or command flow, without jumping directly to the physical controller.

SuporteSupport

Leitura de cartãoCard read

Identificar leitor local COM ou rede TCP.Identify local COM reader or TCP network reader.
Confirmar token recebido no POS ou DSComm.Confirm token received in POS or DSComm.
Confirmar host/direção resolvidos corretamente.Confirm host/direction are resolved correctly.
Confirmar RequestAutorization em DSCore.Confirm RequestAutorization in DSCore.
Confirmar histórico/resultado na base de dados.Confirm history/result in database.

Abertura manualManual opening

Confirmar botão/UI chama GatesService.Confirm button/UI calls GatesService.
Confirmar comando open-door emitido por GateEntries.Confirm open-door command emitted by GateEntries.
Confirmar DSComm recebeu callback Execute.Confirm DSComm received Execute callback.
Confirmar UDPChannel associado ao host.Confirm UDPChannel associated with the host.
Confirmar comando no controlador físico.Confirm command at physical controller.

9. Ficheiros e classes importantes9. Important files and classes

Comece por estes ficheiros para entender o fluxo de gates.Start with these files to understand the gates flow.

CódigoCode

Ficheiro/classeFile/class	MotivoReason
`DigiSchool.POS/GateWindow.xaml`, `GateWindowHorizontal.xaml`	UI de monitorização de gate.Gate monitor UI.
`DigiSchool.POS/ViewModels/GatesViewModel.cs`	Validação local, UI e comandos de gate.Local validation, UI, and gate commands.
`DigiSchool.POS/Code/CommunicationManager.cs`	Leitores locais COM.Local COM readers.
`DigiSchool.DSCore/Services/Gates/GatesService.cs`	Validação e abertura manual.Validation and manual opening.
`DigiSchool.DSCore/Services/GateEntries/GateEntriesService.cs`	Callbacks, comandos e notificações.Callbacks, commands, and notifications.
`DigiSchool.DSCommServer/Client/GateEntriesService/GateEntriesManager.cs`	Cliente DSComm para GateEntries.DSComm client for GateEntries.
`DigiSchool.DSCommServer/Server/UDPManager.cs`	TCP listener e gestor de canais.TCP listener and channel manager.
`DigiSchool.DSCommServer/Server/UDPChannel.cs`	Protocolo UDP de controladores.UDP controller protocol.
`DigiSchool.Data/DataStores/AccessControlDataStore.cs`	Regras de autorização e histórico.Authorization rules and history.

10. Oportunidades de modernização10. Modernization opportunities

Preservar a separação DSCore/DSComm, mas melhorar diagnóstico, adapters e observabilidade.Preserve the DSCore/DSComm split, but improve diagnostics, adapters, and observability.

FuturoFuture

Arquitetura futura para gatesFuture gates architecture

flowchart LR
    UI["Gate UI atual/futura"]
    API["API local/HTTP"]
    CoreFacade["Facade acesso"]
    DSCore["DSCore existente"]
    DeviceSvc["Serviço/adapters hardware"]
    Controller["Controladores gates"]
    Health["Health dashboard"]

    UI --> API
    API --> CoreFacade
    CoreFacade --> DSCore
    API --> DeviceSvc
    DeviceSvc --> Controller
    CoreFacade --> Health
    DeviceSvc --> Health

flowchart LR
    UI["Current/future Gate UI"]
    API["Local/HTTP API"]
    CoreFacade["Access facade"]
    DSCore["Existing DSCore"]
    DeviceSvc["Hardware service/adapters"]
    Controller["Gate controllers"]
    Health["Health dashboard"]

    UI --> API
    API --> CoreFacade
    CoreFacade --> DSCore
    API --> DeviceSvc
    DeviceSvc --> Controller
    CoreFacade --> Health
    DeviceSvc --> Health

Diagnóstico essencialEssential diagnostics

Estado de DSComm, subscrição GateEntries, último token, último host/direção, resultado de autorização e estado UDPChannel.DSComm state, GateEntries subscription, last token, last host/direction, authorization result, and UDPChannel state.

Interfaces úteisUseful interfaces

ICardReader, IDoorController, IAccessAuthorizer e IDeviceHealthReporter.ICardReader, IDoorController, IAccessAuthorizer, and IDeviceHealthReporter.

11. Questões ainda a validar11. Questions still to validate

Estas perguntas devem ser fechadas com documentação de instalação e ambiente real.These questions should be closed with installation documentation and a real environment.

AssunçõesAssumptions

Quais modelos físicos de leitores e controladores estão em produção?Which physical reader and controller models are in production?
Quais portas/IPs são padrão por instalação?Which ports/IPs are standard per installation?
Como suporte distingue negação correta de falha técnica no terreno?How does support distinguish a correct denial from a technical field failure?
Há métricas atuais para callbacks perdidos, channels offline e retries?Are there current metrics for lost callbacks, offline channels, and retries?