vnuswilliams/laravel-geo-checkin

Package Laravel de pointage de présence par géolocalisation, conçu pour être installé à la fois dans Squarhe (application admin RH/paie) et dans le portail employé, deux applications séparées qui partagent la même base de données.

Principe central : sans localisation définie par l'entreprise, aucun pointage ne peut être validé.

Fonctionnement

1. L'entreprise (côté Squarhe) définit un ou plusieurs sites de travail : nom, coordonnées GPS (latitude/longitude) et rayon de tolérance en mètres.
2. L'employé, depuis le portail employé, clique sur « Pointer ». Le navigateur renvoie sa position GPS (latitude, longitude, précision).
3. Le package calcule la distance entre la position de l'employé et le site de référence via la formule de Haversine.
4. Si distance <= radius_meters → pointage valid. Sinon → out_of_range (conservé pour traçabilité, mais marqué suspect).
5. Le pointage est enregistré dans deux tables : le log brut (attendances) et la synthèse journalière (attendance_days).
6. Côté Squarhe, un tableau de bord permet de consulter, filtrer et exporter ces présences.

Installation

Pendant le développement (path repository)

// composer.json des deux projets (Squarhe + portail employé)
"repositories": [
    { "type": "path", "url": "../laravel-geo-checkin" }
]

composer require vnuswilliams/laravel-geo-checkin
php artisan migrate

Le ServiceProvider est auto-découvert (extra.laravel.providers). La base étant partagée, il suffit d'exécuter les migrations depuis un seul des deux projets.

Publication de la configuration (optionnel)

php artisan vendor:publish --tag=geo-checkin-config

Configuration

Tables créées

work_locations — les sites de référence

attendances — le log brut de chaque pointage

attendance_days — la synthèse journalière

Services

GeoDistanceService

use VnusWilliams\GeoCheckin\Services\GeoDistanceService;

$distance = app(GeoDistanceService::class)
    ->distanceInMeters(4.0511, 9.7679, 3.8480, 11.5021); // ≈ 200 000 m

CheckinService — point d'entrée unique

use VnusWilliams\GeoCheckin\Enums\AttendanceType;
use VnusWilliams\GeoCheckin\Services\CheckinService;

$attendance = app(CheckinService::class)->register(
    employee: $employee,
    latitude: $lat,
    longitude: $lng,
    accuracyMeters: $accuracy,
    type: AttendanceType::CheckIn,
);

$attendance->status; // AttendanceStatus::Valid | OutOfRange | NoLocationDefined | Pending

Règles de résolution du site de référence :

1. le site assigné à l'employé via sa relation workLocation (si active) ;
2. le premier site actif de son entreprise ;
3. le premier site actif globalement.

Composants Livewire 4 (single-file, natifs)

Les composants sont enregistrés sous le namespace geo-checkin dans le ServiceProvider du package et utilisables directement dans les deux applications.

Côté employé (portail)

<livewire:geo-checkin::employee-checkin-widget />

Boutons « Pointer (arrivée) » et « Dépointer (départ) », récupération de la position GPS via l'API du navigateur (navigator.geolocation).

Côté admin (Squarhe)

<livewire:geo-checkin::admin-work-location-manager />
<livewire:geo-checkin::admin-attendance-report />

• admin-work-location-manager : CRUD des sites avec carte cliquable (Leaflet.js + OpenStreetMap, sans clé API).
• admin-attendance-report : tableau de bord filtrable par employé, période et statut, avec export CSV. Les exports Excel (FastExcel) et PDF (DomPDF) peuvent être branchés par l'application en réutilisant ses propres patterns.

Sécurité et fiabilité

• Pas de site = pas de validation : statut no_location_defined explicite plutôt qu'une erreur.
• Précision GPS : au-delà du seuil configuré, statut pending (validation manuelle) plutôt qu'un rejet injuste.
• Anti-triche : l'IP de chaque pointage est journalisée à titre indicatif. La géolocalisation navigateur reste falsifiable ; une app mobile native serait nécessaire pour une fiabilité renforcée.
• Multi-site : les sites sont liés à company_id ; chaque synthèse journalière conserve le site utilisé.

Tests

composer install
vendor/bin/phpunit
vendor/bin/pint --test

27 tests (unitaires + fonctionnels) couvrent : le calcul de distance, la validation dans/à l'extérieur du rayon, l'absence de site, la faible précision GPS, la synthèse journalière unique, le calcul des minutes travaillées, la résolution multi-site, la journalisation IP, et les composants Livewire.

Évolutions possibles

• Calcul automatique des retards (horaires d'ouverture de l'entreprise).
• Détection des absences (aucun AttendanceDay un jour ouvré).
• Application mobile native pour une géolocalisation plus fiable.
• Connexion de worked_minutes au module paie de Squarhe.