Softic.Badge — Architecture | Softic.Badge

Softic.Badge est le produit SOFTIC de contrôle d'accès et de pointage physique. Il remplace ZKAccess 3.5 : il parle directement aux appareils ZKTeco, garde ses données dans une base SQL Server propre et alimente Softic.Intranet.

Vue d'ensemble

                 +--------------------------+          +---------------------------+
   Pointeuses    |  Softic.Badge.Gateway    |          |  Softic.Badge.Web         |
   F18 / IN01 -->|  service Windows         |   SQL    |  Blazor Server            |
   (PUSH http)   |  /iclock/*  (port 8081)  |<-------->|  DevExpress 24.1          |<---- navigateurs,
   (PULL 4370) <-|  interrogation Pull      |  base    |  API api/v1 (cle d'API)   |      SSO intranet
                 |  file de commandes       | SofticBadge  pages : appareils,      |
                 |  transmission intranet   | schema badge  pointages, personnel,  |
                 +-----------+--------------+          |  commandes, journal, param.|
                             |                         +-------------+-------------+
                             | POST api/v1/attendance/punches        | GET api/v1/hr/employees
                             v                                       v
                 +------------------------------------------------------------------+
                 |  Softic.Intranet (référentiel RH, pointage web/mobile QR, SSO)   |
                 +------------------------------------------------------------------+

Deux processus, une base. La passerelle est le seul processus qui parle aux appareils ; le site web lit la base et dépose des commandes dans la file. Les deux peuvent tourner sur le même serveur (VMS-INTRANETAPP) ou être séparés.

Projets

Projet	Rôle
`Softic.Badge.Core`	Entités (Site, Device, Person, PersonDevice, BiometricTemplate, Punch, DeviceCommand, DeviceEvent, UserAccount), énumérations, payloads de commandes. Aucune dépendance.
`Softic.Badge.Protocols`	Protocoles ZKTeco en C# pur : `Push` (ADMS / iClock) et `Pull` (TCP 4370). Testé par `tests/Softic.Badge.Protocols.Tests`.
`Softic.Badge.Data`	EF Core 8 / SQL Server, schéma `badge`, migrations.
`Softic.Badge.Engine`	Services métier et tâches de fond : ingestion idempotente des pointages, file de commandes, service push, service pull, synchronisation du personnel, intégration intranet, administration, tableau de bord.
`Softic.Badge.Gateway`	Hôte ASP.NET Core minimal (service Windows) : endpoints `/iclock/*`, workers.
`Softic.Badge.Web`	Blazor Web App (.NET 8, rendu interactif serveur) + DevExpress Blazor 24.1.3 ; authentification cookie (comptes locaux, connexion unique SOFTIC Intranet par la bibliothèque commune) ; API `api/v1`.
`libs\Softic.Intranet`	Bibliothèque commune des produits SOFTIC (`Softic.Intranet.Client`, `Softic.Intranet.Client.AspNetCore` 1.7.1), copie figée de celle de la GMAO, référencée par Web : tuile, bouton « Se connecter avec SOFTIC Intranet », mode intégré, déconnexion commune (1.2.0).
`Softic.Badge.Client`	Client HTTP de l'API pour Softic.Intranet.
`Softic.Badge.Agent`	Agent de site, service Windows installé chez le client. Il lit, en lecture seule, les pointeuses du réseau local en 4370 (source `Devices`) ou la base SQL de ZKAccess (source `ZkAccess` : pointeuses et tourniquets), et relaie vers la passerelle comme un appareil PUSH. Ne dépend que de `Protocols` (`AGENT-DE-SITE.md`).

Flux principaux

Pointage (PUSH) : l'appareil appelle GET /iclock/cdata?SN=..&options=all (options renvoyées : stamps, délai, fuseau, tables à transmettre), puis POST /iclock/cdata?table=ATTLOG à chaque pointage (temps réel) ou par lot. PushProtocolService.ReceiveTableAsync analyse les lignes, PunchIngestService insère les nouveaux pointages (clé unique appareil + PIN + heure + mode) et met à jour ATTLOGStamp ; réponse OK: n.

Pointage (agent de site) : quand la pointeuse n'est pas joignable depuis la passerelle et que personne n'est sur place pour la passer en ADMS, Softic.Badge.Agent la lit en 4370 depuis le réseau local, en lecture seule, sans désactiver l'appareil. Il rejoue ensuite le dialogue PUSH ci-dessus sous le numéro de série réel : personnes (OPERLOG USER) puis pointages (ATTLOG), scrutation getrequest et commandes refusées (-4). La passerelle ne fait aucune différence avec une pointeuse ADMS.

Pointage (agent de site, source ZKAccess) : l'agent lit la base de ZKAccess par curseurs sur les colonnes identité (CHECKINOUT.LOGID, acc_monitor_log.id), en READ UNCOMMITTED, et relaie chaque appareil de Machines sous son numéro de série : pointeuses depuis CHECKINOUT et acc_monitor_log, tourniquets inBIO/ACP depuis acc_monitor_log avec leur sens. Il annonce en plus ~SofticKind et ~SofticAlias (type et nom ZKAccess, repris par ApplyOptions) et le service de chaque personne (Dept=, repris à l'import du personnel).

Pointage (PULL) : PullPollingWorker interroge chaque appareil Pull actif selon son intervalle : connexion, DisableDevice, lecture de tous les pointages, EnableDevice, ingestion idempotente, sondage technique toutes les N interrogations.

Transmission à l'intranet : chaque Punch naît avec ForwardStatus = Pending. ForwardWorker envoie les lots à POST api/v1/attendance/punches et marque Forwarded ; en cas d'échec il réessaie (10 tentatives puis Failed, relançable depuis Paramètres). Si la liaison est désactivée : Skipped.

Personnel : PersonSyncService.SyncFromIntranetAsync lit GET api/v1/hr/employees, met à jour Person (matricule = PIN, nom, carte, service, actif) et, si Intranet:AutoAssignBySite, affecte l'employé aux appareils du site de même code. Toute fiche modifiée est mise en file vers ses appareils (UserUpdate / UserDelete).

Commandes : DeviceCommand est générique (Kind + payload JSON). Pour un appareil PUSH, CommandRenderer la traduit en texte ADMS servi sur GET /iclock/getrequest ; le résultat revient sur POST /iclock/devicecmd. Pour un appareil PULL, PullCommandWorker l'exécute via ZkTcpClient.

Enrôlements sur l'appareil : les lignes USER et FP reçues dans OPERLOG créent ou complètent les personnes et leurs gabarits (Push:ImportEnrollmentsFromDevices), ce qui prépare la reprise de la base ZKAccess (lot 4).

Base de données (schéma `badge`)

Site, Device (unicité SerialNumber), Person (unicité Pin), PersonDevice (clé Person+Device, PendingSync), BiometricTemplate (Person+Type+Index), Punch (index unique Device+Pin+OccurredAt+VerifyMode, index ForwardStatus), DeviceCommand (index Device+Status+Priority), DeviceEvent, UserAccount. Historique des migrations : badge.__EFMigrationsHistory.

Sécurité

Web : cookie SofticBadge.Auth, rôles Admin / Operator / Viewer ; connexion unique SOFTIC Intranet (1.2.0) par la bibliothèque commune : ticket HS256 à usage unique sur /sso (tuile ou bouton), secret de la fiche BADGE dans Sso:SigningKey, droits du compte Badge (INTEGRATION-INTRANET.md § 4). Affichage en cadre réservé à l'intranet.
API : en-tête X-Api-Key (liste Api:Keys) ou session cookie.
Passerelle : les endpoints /iclock/* sont sans authentification (protocole ZKTeco) : exposer le port 8081 uniquement au VLAN des pointeuses (pare-feu Windows + FortiGate). Push:AutoRegister=false pour refuser les appareils inconnus.

Lots