feat(commercial) : géolocalisation des adresses Tiers (lat/lng + géocodage BAN + pin ajustable) (ERP-122)
Ajoute la géolocalisation aux adresses Client et Fournisseur, socle de la tournée commerciale (M6 field-sales). Back : - migration : latitude/longitude NUMERIC(10,7), geo_manual BOOLEAN, geocoded_at TIMESTAMPTZ sur client_address et supplier_address (+ COMMENT ON COLUMN FR) - GeolocatableAddressInterface (Shared/Domain/Contract) implémenté par les deux entités ; bornes WGS84 validées (Range -90/90, -180/180, messages FR) - GeocoderInterface + BanGeocoder (api-adresse.data.gouv.fr), branché via AddressGeocoder dans les processors ; géocodage auto au create/update - RG-6.08 : geo_manual=true fige les coordonnées (pas de réécriture auto) - symfony/http-client passe en dépendance de production Front : - AddressGeoPin (Leaflet + OSM) : marqueur déplaçable -> PATCH lat/lng + geoManual=true, bouton Re-géocoder, badges « à géolocaliser » / « pin manuel » - intégration dans les blocs adresse Client et Fournisseur Tests : PHPUnit (géocodage create, non-réécriture RG-6.08, mapping BAN, bornes) + Vitest (drag du pin, badges, re-géocodage).
This commit is contained in:
Matthieu
@@ -0,0 +1,49 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Shared\Application\Service;
|
||||
|
||||
use App\Shared\Domain\Contract\GeocoderInterface;
|
||||
use App\Shared\Domain\Contract\GeolocatableAddressInterface;
|
||||
use DateTimeImmutable;
|
||||
|
||||
/**
|
||||
* Geocodage automatique d'une adresse Tiers a la creation / mise a jour
|
||||
* (M6.1, spec § 7). Appele par les processors d'adresse (ClientAddressProcessor
|
||||
* / SupplierAddressProcessor) AVANT le persist.
|
||||
*
|
||||
* RG-6.08 : si le pin a ete corrige a la main (geoManual = true), les
|
||||
* coordonnees sont FIGEES — aucun geocodage, aucune reecriture. Le front
|
||||
* « re-geocode » en repassant geoManual a false (le prochain save regeocode).
|
||||
*
|
||||
* En cas d'echec du geocodage (BAN indisponible, adresse introuvable), les
|
||||
* coordonnees existantes sont CONSERVEES en l'etat : pas de retour en arriere
|
||||
* silencieux, l'adresse reste sauvegardable (badge « a geolocaliser » cote
|
||||
* front si elle n'a aucune coordonnee).
|
||||
*/
|
||||
final class AddressGeocoder
|
||||
{
|
||||
public function __construct(
|
||||
private readonly GeocoderInterface $geocoder,
|
||||
) {}
|
||||
|
||||
public function geocode(GeolocatableAddressInterface $address): void
|
||||
{
|
||||
// RG-6.08 : pin manuel -> coordonnees figees.
|
||||
if ($address->isGeoManual()) {
|
||||
return;
|
||||
}
|
||||
|
||||
$coordinates = $this->geocoder->geocode($address->getDisplayLabel());
|
||||
if (null === $coordinates) {
|
||||
return;
|
||||
}
|
||||
|
||||
$address
|
||||
->setLatitude($coordinates->latitude)
|
||||
->setLongitude($coordinates->longitude)
|
||||
->setGeocodedAt(new DateTimeImmutable())
|
||||
;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Shared\Domain\Contract;
|
||||
|
||||
use App\Shared\Domain\ValueObject\Coordinates;
|
||||
|
||||
/**
|
||||
* Geocodage d'une adresse postale en coordonnees WGS84 (M6.1, spec § 7).
|
||||
*
|
||||
* Encapsule le fournisseur de geocodage (decision Q-M6-3 : BAN
|
||||
* api-adresse.data.gouv.fr) derriere un contrat pour pouvoir en changer sans
|
||||
* toucher aux appelants.
|
||||
*
|
||||
* Contrat d'erreur : `null` si l'adresse n'est pas geocodable (aucun resultat,
|
||||
* score trop faible) OU si le fournisseur est indisponible (reseau, 5xx). Le
|
||||
* geocodage ne doit JAMAIS bloquer la sauvegarde d'une adresse — une adresse
|
||||
* sans coordonnees reste valide (badge « a geolocaliser », spec § 3.2).
|
||||
*/
|
||||
interface GeocoderInterface
|
||||
{
|
||||
public function geocode(string $address): ?Coordinates;
|
||||
}
|
||||
@@ -0,0 +1,41 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Shared\Domain\Contract;
|
||||
|
||||
use DateTimeImmutable;
|
||||
|
||||
/**
|
||||
* Adresse Tiers geolocalisable (M6.1, spec § 3.2 / § 4.1).
|
||||
*
|
||||
* Implementee par ClientAddress et SupplierAddress (module Commercial) ; le
|
||||
* futur module FieldSales consommera ce contrat pour router les tournees sans
|
||||
* importer le module Commercial (regle ABSOLUE n°1).
|
||||
*
|
||||
* Les setters (latitude / longitude / geocodedAt) sont la surface d'ecriture
|
||||
* du service de geocodage automatique (AddressGeocoder) ; isGeoManual() porte
|
||||
* la RG-6.08 — un pin corrige a la main fige les coordonnees, le geocodage
|
||||
* auto ne les reecrit plus.
|
||||
*/
|
||||
interface GeolocatableAddressInterface
|
||||
{
|
||||
/** Latitude WGS84 en chaine decimale NUMERIC(10,7), null si non geolocalisee. */
|
||||
public function getLatitude(): ?string;
|
||||
|
||||
/** Longitude WGS84 en chaine decimale NUMERIC(10,7), null si non geolocalisee. */
|
||||
public function getLongitude(): ?string;
|
||||
|
||||
/** Adresse postale affichable / geocodable (rue, code postal, ville). */
|
||||
public function getDisplayLabel(): string;
|
||||
|
||||
/** RG-6.08 : pin corrige a la main — le geocodage auto ne reecrit plus. */
|
||||
public function isGeoManual(): bool;
|
||||
|
||||
public function setLatitude(float|string|null $latitude): static;
|
||||
|
||||
public function setLongitude(float|string|null $longitude): static;
|
||||
|
||||
/** Date du dernier geocodage automatique reussi (posee par AddressGeocoder). */
|
||||
public function setGeocodedAt(?DateTimeImmutable $geocodedAt): static;
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Shared\Domain\ValueObject;
|
||||
|
||||
/**
|
||||
* Paire de coordonnees WGS84 (latitude / longitude) portee en chaines
|
||||
* decimales a 7 decimales — meme format que les colonnes NUMERIC(10,7) des
|
||||
* adresses Tiers (M6.1, spec § 4.1). Immutable.
|
||||
*/
|
||||
final readonly class Coordinates
|
||||
{
|
||||
public function __construct(
|
||||
public string $latitude,
|
||||
public string $longitude,
|
||||
) {}
|
||||
|
||||
/**
|
||||
* Fabrique depuis des flottants (ex: geometry GeoJSON de la BAN), arrondis
|
||||
* au format NUMERIC(10,7) des colonnes.
|
||||
*/
|
||||
public static function fromFloats(float $latitude, float $longitude): self
|
||||
{
|
||||
return new self(
|
||||
number_format($latitude, 7, '.', ''),
|
||||
number_format($longitude, 7, '.', ''),
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -243,6 +243,10 @@ final class ColumnCommentsCatalog
|
||||
'billing_email' => 'Email de facturation — obligatoire si is_billing, null sinon (RG-1.11, chk_client_address_billing_email).',
|
||||
'billing_email_secondary' => '2e email de facturation, optionnel (max 2). Interdit hors facturation, normalise en minuscules (RG-1.21).',
|
||||
'position' => 'Ordre d affichage de l adresse dans la liste du client (croissant).',
|
||||
'latitude' => 'Latitude WGS84 de l adresse (geocodage BAN ou pin manuel). NULL = non geolocalisee, exclue du calcul de tournee (RG-6.05).',
|
||||
'longitude' => 'Longitude WGS84 de l adresse (geocodage BAN ou pin manuel). NULL = non geolocalisee.',
|
||||
'geo_manual' => 'Pin positionne/corrige a la main : si vrai, le geocodage auto ne reecrit plus les coordonnees (RG-6.08). Faux par defaut.',
|
||||
'geocoded_at' => 'Date du dernier geocodage automatique reussi (NULL si jamais geocode ou pin 100% manuel).',
|
||||
] + self::timestampableBlamableComments(),
|
||||
|
||||
'client_address_site' => [
|
||||
@@ -332,6 +336,10 @@ final class ColumnCommentsCatalog
|
||||
'bennes' => 'Nombre de bennes sur le site fournisseur (entier nullable) — specifique fournisseur.',
|
||||
'triage_provider' => 'Le fournisseur est prestataire de triage sur cette adresse. Faux par defaut.',
|
||||
'position' => 'Ordre d affichage de l adresse dans la liste du fournisseur (croissant).',
|
||||
'latitude' => 'Latitude WGS84 de l adresse (geocodage BAN ou pin manuel). NULL = non geolocalisee, exclue du calcul de tournee (RG-6.05).',
|
||||
'longitude' => 'Longitude WGS84 de l adresse (geocodage BAN ou pin manuel). NULL = non geolocalisee.',
|
||||
'geo_manual' => 'Pin positionne/corrige a la main : si vrai, le geocodage auto ne reecrit plus les coordonnees (RG-6.08). Faux par defaut.',
|
||||
'geocoded_at' => 'Date du dernier geocodage automatique reussi (NULL si jamais geocode ou pin 100% manuel).',
|
||||
] + self::timestampableBlamableComments(),
|
||||
|
||||
'supplier_address_site' => [
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace App\Shared\Infrastructure\Geocoding;
|
||||
|
||||
use App\Shared\Domain\Contract\GeocoderInterface;
|
||||
use App\Shared\Domain\ValueObject\Coordinates;
|
||||
use Psr\Log\LoggerInterface;
|
||||
use Symfony\Contracts\HttpClient\HttpClientInterface;
|
||||
use Throwable;
|
||||
|
||||
/**
|
||||
* Geocodeur branche sur la Base Adresse Nationale (BAN) —
|
||||
* `api-adresse.data.gouv.fr` (decision Q-M6-3, spec M6 § 7). Meme endpoint
|
||||
* `/search/` que l'autocompletion d'adresse cote front
|
||||
* (useAddressAutocomplete) : integration unique, service public gratuit.
|
||||
*
|
||||
* Tolerance aux pannes : toute erreur (reseau, 5xx, payload inattendu) est
|
||||
* loggee et convertie en `null` — le geocodage ne bloque jamais la sauvegarde
|
||||
* d'une adresse (contrat GeocoderInterface).
|
||||
*/
|
||||
final class BanGeocoder implements GeocoderInterface
|
||||
{
|
||||
private const string SEARCH_URL = 'https://api-adresse.data.gouv.fr/search/';
|
||||
|
||||
/**
|
||||
* Score BAN minimal (0..1) pour considerer le resultat fiable. En deca
|
||||
* (adresse etrangere, lieu-dit inconnu...), on prefere « pas de
|
||||
* coordonnees » a une position fantaisiste — le pin manuel prend le relais
|
||||
* (spec § 3.2).
|
||||
*/
|
||||
private const float MIN_SCORE = 0.4;
|
||||
|
||||
public function __construct(
|
||||
private readonly HttpClientInterface $httpClient,
|
||||
private readonly LoggerInterface $logger,
|
||||
) {}
|
||||
|
||||
public function geocode(string $address): ?Coordinates
|
||||
{
|
||||
$query = trim($address);
|
||||
if ('' === $query) {
|
||||
return null;
|
||||
}
|
||||
|
||||
try {
|
||||
$response = $this->httpClient->request('GET', self::SEARCH_URL, [
|
||||
'query' => ['q' => $query, 'limit' => 1],
|
||||
'timeout' => 5,
|
||||
]);
|
||||
|
||||
/** @var array{features?: list<array{geometry?: array{coordinates?: array{0: float|int, 1: float|int}}, properties?: array{score?: float|int}}>} $payload */
|
||||
$payload = $response->toArray();
|
||||
} catch (Throwable $e) {
|
||||
$this->logger->warning('Geocodage BAN indisponible : {message}', [
|
||||
'message' => $e->getMessage(),
|
||||
'address' => $query,
|
||||
]);
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
$feature = $payload['features'][0] ?? null;
|
||||
if (null === $feature) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$score = (float) ($feature['properties']['score'] ?? 0.0);
|
||||
if ($score < self::MIN_SCORE) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// GeoJSON : coordinates = [longitude, latitude].
|
||||
$coordinates = $feature['geometry']['coordinates'] ?? null;
|
||||
if (!is_array($coordinates) || !isset($coordinates[0], $coordinates[1])
|
||||
|| !is_numeric($coordinates[0]) || !is_numeric($coordinates[1])) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return Coordinates::fromFloats((float) $coordinates[1], (float) $coordinates[0]);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user