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
2026-06-11 14:31:35 +02:00
parent 431d831c8b
commit de4aaa1d64
34 changed files with 1966 additions and 204 deletions
@@ -0,0 +1,216 @@
<template>
<div data-testid="geo-pin">
<div class="mb-1 flex items-center gap-2">
<span class="text-sm font-medium text-gray-700">{{ t('commercial.geo.title') }}</span>
<!-- Badge « a geolocaliser » : adresse valide mais sans coordonnees
(spec M6 § 3.2 exclue du calcul de tournee, RG-6.05). -->
<span
v-if="!hasCoords"
class="inline-flex items-center rounded-full bg-yellow-100 px-2 py-0.5 text-xs font-medium text-yellow-800"
data-testid="geo-badge-missing"
>
{{ t('commercial.geo.toGeolocate') }}
</span>
<!-- Pin fige a la main (RG-6.08) : informatif. -->
<span
v-else-if="geoManual"
class="inline-flex items-center rounded-full bg-blue-100 px-2 py-0.5 text-xs font-medium text-blue-800"
data-testid="geo-badge-manual"
>
{{ t('commercial.geo.manualPin') }}
</span>
</div>
<!-- Mini-carte Leaflet (exception documentee a @malio/layer-ui : carte
interactive, type non couvert par la lib cf. frontend.md
§ Composants formulaires). TODO : migrer si la lib couvre un jour
les cartes. -->
<div
v-if="hasCoords"
ref="mapEl"
class="h-48 w-full rounded border border-gray-200"
data-testid="geo-map"
/>
<p v-if="hasCoords && !readonly" class="mt-1 text-xs text-gray-500">
{{ t('commercial.geo.dragHint') }}
</p>
<div v-if="!readonly" class="mt-2 flex items-center gap-4">
<MalioButton
variant="secondary"
:label="t('commercial.geo.regeocode')"
:disabled="regeocoding || !canRegeocode"
data-testid="geo-regeocode"
@click="regeocode"
/>
<span v-if="regeocodeFailed" class="text-xs text-red-600" data-testid="geo-regeocode-failed">
{{ t('commercial.geo.regeocodeFailed') }}
</span>
</div>
</div>
</template>
<script setup lang="ts">
import type { Map as LeafletMap, Marker } from 'leaflet'
import { useAddressAutocomplete } from '~/shared/composables/useAddressAutocomplete'
/**
* Mini-carte d'ajustement du pin d'une adresse Tiers (M6.1, spec § 8.3).
*
* - Marqueur deplacable : au drag, emet les coordonnees corrigees avec
* geoManual = true (RG-6.08 : le geocodage auto ne reecrira plus). Le parent
* met a jour le brouillon ; la persistance suit le submit du formulaire
* (POST/PATCH de l'adresse), comme tous les champs du bloc.
* - « Re-geocoder depuis l'adresse » : previsualise la position BAN cote front
* et emet geoManual = false — au save, le back (BanGeocoder) refait autorite
* et pose geocodedAt.
* - Sans coordonnees : pas de carte, badge « a geolocaliser ».
*/
const props = defineProps<{
/** Latitude WGS84 (chaine decimale) ou null si non geolocalisee. */
latitude: string | null
/** Longitude WGS84 (chaine decimale) ou null si non geolocalisee. */
longitude: string | null
/** RG-6.08 : pin deja corrige a la main. */
geoManual: boolean
/** Adresse postale a re-geocoder (« rue, code postal ville »). */
geocodeQuery: string | null
readonly?: boolean
}>()
const emit = defineEmits<{
/** Nouveau positionnement du pin (drag manuel ou re-geocodage previsualise). */
'update:coords': [value: { latitude: string, longitude: string, geoManual: boolean }]
}>()
const { t } = useI18n()
const autocomplete = useAddressAutocomplete()
const mapEl = ref<HTMLElement | null>(null)
const regeocoding = ref(false)
const regeocodeFailed = ref(false)
const hasCoords = computed(() =>
props.latitude !== null && props.latitude !== ''
&& props.longitude !== null && props.longitude !== '',
)
const canRegeocode = computed(() => (props.geocodeQuery ?? '').trim().length >= 3)
// Instances Leaflet (hors reactivite Vue : un proxy sur la Map casse Leaflet).
let map: LeafletMap | null = null
let marker: Marker | null = null
/** Zoom d'affichage du pin (niveau rue). */
const PIN_ZOOM = 16
/**
* Monte la carte Leaflet dans le conteneur (import dynamique : la lib n'est
* chargee que si l'adresse a des coordonnees).
*/
async function ensureMap(): Promise<void> {
if (map !== null || mapEl.value === null || !hasCoords.value) {
return
}
const mod = await import('leaflet')
const L = mod.default ?? mod
await import('leaflet/dist/leaflet.css')
// Le conteneur peut avoir disparu pendant le chargement async (v-if).
if (mapEl.value === null) {
return
}
const position: [number, number] = [Number(props.latitude), Number(props.longitude)]
map = L.map(mapEl.value, { scrollWheelZoom: false }).setView(position, PIN_ZOOM)
L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>',
maxZoom: 19,
}).addTo(map)
// divIcon SVG inline : evite les assets PNG de Leaflet (chemins casses par
// le bundler Vite sans configuration dediee).
const icon = L.divIcon({
className: '',
html: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="28" height="40" fill="#2563eb" stroke="#1e40af" stroke-width="0.5"><path d="M12 0C7 0 3 4 3 9c0 6.6 9 15 9 15s9-8.4 9-15c0-5-4-9-9-9zm0 12.5A3.5 3.5 0 1 1 12 5.5a3.5 3.5 0 0 1 0 7z"/></svg>',
iconSize: [28, 40],
iconAnchor: [14, 40],
})
marker = L.marker(position, { icon, draggable: !props.readonly }).addTo(map)
marker.on('dragend', onMarkerDragEnd)
}
/** Drag du pin -> coordonnees corrigees + geoManual (RG-6.08). */
function onMarkerDragEnd(): void {
if (marker === null) {
return
}
const position = marker.getLatLng()
emit('update:coords', {
latitude: position.lat.toFixed(7),
longitude: position.lng.toFixed(7),
geoManual: true,
})
}
/**
* « Re-geocoder depuis l'adresse » : previsualisation BAN cote front. Emet
* geoManual = false — le geocodage serveur refait autorite au save.
*/
async function regeocode(): Promise<void> {
regeocodeFailed.value = false
const query = (props.geocodeQuery ?? '').trim()
if (query.length < 3) {
regeocodeFailed.value = true
return
}
regeocoding.value = true
try {
const coords = await autocomplete.geocode(query)
if (coords === null) {
regeocodeFailed.value = true
return
}
emit('update:coords', { ...coords, geoManual: false })
}
catch {
// BAN indisponible : position inchangee, message inline.
regeocodeFailed.value = true
}
finally {
regeocoding.value = false
}
}
// Coordonnees modifiees par le parent (drag deja applique, re-geocodage,
// rechargement) : recale le marqueur, ou monte la carte si elle n'existe pas
// encore (premieres coordonnees d'une adresse « a geolocaliser »).
watch(
() => [props.latitude, props.longitude] as const,
async () => {
if (!hasCoords.value) {
return
}
if (map === null) {
await nextTick()
await ensureMap()
return
}
const position: [number, number] = [Number(props.latitude), Number(props.longitude)]
marker?.setLatLng(position)
map.panTo(position)
},
)
onMounted(ensureMap)
onBeforeUnmount(() => {
map?.remove()
map = null
marker = null
})
</script>
@@ -178,6 +178,19 @@
/>
</div>
<!-- Pin geographique de l'adresse (M6.1, spec § 8.3) : mini-carte avec
marqueur ajustable, persiste au submit comme le reste du bloc. -->
<div class="col-span-4">
<AddressGeoPin
:latitude="model.latitude"
:longitude="model.longitude"
:geo-manual="model.geoManual"
:geocode-query="geocodeQuery"
:readonly="readonly"
@update:coords="onCoordsUpdate"
/>
</div>
</div>
</template>
@@ -289,6 +302,24 @@ function update<K extends keyof AddressFormDraft>(field: K, value: AddressFormDr
emit('update:modelValue', { ...props.modelValue, [field]: value })
}
// Adresse postale a re-geocoder (« rue, code postal ville ») — miroir du
// getDisplayLabel() serveur (le complement bruite le geocodage, exclu).
const geocodeQuery = computed<string | null>(() => {
const locality = [model.value.postalCode, model.value.city].filter(Boolean).join(' ')
const parts = [model.value.street, locality].filter(part => part && String(part).trim() !== '')
return parts.length > 0 ? parts.join(', ') : null
})
/** Pin deplace / re-geocode : repercute coordonnees + drapeau manuel (RG-6.08). */
function onCoordsUpdate(coords: { latitude: string, longitude: string, geoManual: boolean }): void {
emit('update:modelValue', {
...props.modelValue,
latitude: coords.latitude,
longitude: coords.longitude,
geoManual: coords.geoManual,
})
}
/** Revele le 2e champ email de facturation (clic sur le « + »). */
function revealSecondaryBillingEmail(): void {
emit('update:modelValue', { ...props.modelValue, hasSecondaryBillingEmail: true })
@@ -162,6 +162,19 @@
:readonly="readonly"
@update:model-value="(v: boolean) => update('triageProvider', v)"
/>
<!-- Pin geographique de l'adresse (M6.1, spec § 8.3) : mini-carte avec
marqueur ajustable, persiste au submit comme le reste du bloc. -->
<div class="col-span-4">
<AddressGeoPin
:latitude="model.latitude"
:longitude="model.longitude"
:geo-manual="model.geoManual"
:geocode-query="geocodeQuery"
:readonly="readonly"
@update:coords="onCoordsUpdate"
/>
</div>
</div>
</template>
@@ -243,6 +256,24 @@ function update<K extends keyof SupplierAddressFormDraft>(field: K, value: Suppl
emit('update:modelValue', { ...props.modelValue, [field]: value })
}
// Adresse postale a re-geocoder (« rue, code postal ville ») — miroir du
// getDisplayLabel() serveur (le complement bruite le geocodage, exclu).
const geocodeQuery = computed<string | null>(() => {
const locality = [model.value.postalCode, model.value.city].filter(Boolean).join(' ')
const parts = [model.value.street, locality].filter(part => part && String(part).trim() !== '')
return parts.length > 0 ? parts.join(', ') : null
})
/** Pin deplace / re-geocode : repercute coordonnees + drapeau manuel (RG-6.08). */
function onCoordsUpdate(coords: { latitude: string, longitude: string, geoManual: boolean }): void {
emit('update:modelValue', {
...props.modelValue,
latitude: coords.latitude,
longitude: coords.longitude,
geoManual: coords.geoManual,
})
}
/** Previent le parent (toast unique) que l'autocompletion est indisponible. */
function notifyUnavailable(): void {
if (!unavailableNotified) {
@@ -0,0 +1,151 @@
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { mount, flushPromises } from '@vue/test-utils'
import { ref, computed, watch, nextTick, onMounted, onBeforeUnmount } from 'vue'
import AddressGeoPin from '../AddressGeoPin.vue'
// Mock Leaflet (hoisted) : capture le handler `dragend` et pilote la position
// renvoyee par getLatLng — permet de simuler un drag du marqueur sans DOM reel.
const leafletState = vi.hoisted(() => ({
dragendHandler: null as (() => void) | null,
markerPosition: { lat: 0, lng: 0 },
}))
vi.mock('leaflet', () => {
const marker = {
addTo: vi.fn().mockReturnThis(),
on: vi.fn((event: string, handler: () => void) => {
if (event === 'dragend') {
leafletState.dragendHandler = handler
}
}),
getLatLng: vi.fn(() => leafletState.markerPosition),
setLatLng: vi.fn(),
}
const map = {
setView: vi.fn().mockReturnThis(),
panTo: vi.fn(),
remove: vi.fn(),
}
const L = {
map: vi.fn(() => map),
tileLayer: vi.fn(() => ({ addTo: vi.fn() })),
divIcon: vi.fn(() => ({})),
marker: vi.fn(() => marker),
}
return { default: L, ...L }
})
vi.mock('leaflet/dist/leaflet.css', () => ({ default: {} }))
// Mock controlable du geocodage BAN (bouton « Re-geocoder »).
const { geocodeMock } = vi.hoisted(() => ({ geocodeMock: vi.fn() }))
vi.mock('~/shared/composables/useAddressAutocomplete', () => ({
useAddressAutocomplete: () => ({ geocode: geocodeMock }),
}))
// Auto-imports Nuxt/Vue utilises sans import explicite par le composant.
vi.stubGlobal('useI18n', () => ({ t: (key: string) => key }))
vi.stubGlobal('ref', ref)
vi.stubGlobal('computed', computed)
vi.stubGlobal('watch', watch)
vi.stubGlobal('nextTick', nextTick)
vi.stubGlobal('onMounted', onMounted)
vi.stubGlobal('onBeforeUnmount', onBeforeUnmount)
interface PinProps {
latitude?: string | null
longitude?: string | null
geoManual?: boolean
geocodeQuery?: string | null
readonly?: boolean
}
function mountPin(props: PinProps = {}) {
return mount(AddressGeoPin, {
props: {
latitude: null,
longitude: null,
geoManual: false,
geocodeQuery: '1 rue du Test, 86100 Châtellerault',
...props,
},
global: {
stubs: { MalioButton: true },
},
})
}
beforeEach(() => {
leafletState.dragendHandler = null
geocodeMock.mockReset()
})
describe('AddressGeoPin — adresse sans coordonnees', () => {
it('affiche le badge « a geolocaliser » et aucune carte', () => {
const wrapper = mountPin()
expect(wrapper.find('[data-testid="geo-badge-missing"]').exists()).toBe(true)
expect(wrapper.find('[data-testid="geo-map"]').exists()).toBe(false)
})
})
describe('AddressGeoPin — drag du marqueur (RG-6.08)', () => {
it('emet les coordonnees corrigees avec geoManual=true au dragend', async () => {
const wrapper = mountPin({ latitude: '46.5802596', longitude: '0.3404333' })
await flushPromises() // import dynamique de Leaflet + montage carte
expect(leafletState.dragendHandler).not.toBeNull()
// L'utilisateur depose le pin ailleurs (lieu-dit mal geocode).
leafletState.markerPosition = { lat: 48.1234567, lng: -1.6543217 }
leafletState.dragendHandler?.()
const emitted = wrapper.emitted('update:coords')
expect(emitted).toHaveLength(1)
expect(emitted?.[0]?.[0]).toEqual({
latitude: '48.1234567',
longitude: '-1.6543217',
geoManual: true,
})
})
it('affiche le badge « pin manuel » quand geoManual est vrai', () => {
const wrapper = mountPin({ latitude: '46.58', longitude: '0.34', geoManual: true })
expect(wrapper.find('[data-testid="geo-badge-manual"]').exists()).toBe(true)
expect(wrapper.find('[data-testid="geo-badge-missing"]').exists()).toBe(false)
})
})
describe('AddressGeoPin — re-geocodage depuis l\'adresse', () => {
it('emet la position BAN avec geoManual=false (le back refera autorite au save)', async () => {
geocodeMock.mockResolvedValueOnce({ latitude: '46.5802596', longitude: '0.3404333' })
const wrapper = mountPin()
await wrapper.find('[data-testid="geo-regeocode"]').trigger('click')
await flushPromises()
expect(geocodeMock).toHaveBeenCalledWith('1 rue du Test, 86100 Châtellerault')
expect(wrapper.emitted('update:coords')?.[0]?.[0]).toEqual({
latitude: '46.5802596',
longitude: '0.3404333',
geoManual: false,
})
})
it('signale l\'echec sans emettre quand la BAN ne trouve rien', async () => {
geocodeMock.mockResolvedValueOnce(null)
const wrapper = mountPin()
await wrapper.find('[data-testid="geo-regeocode"]').trigger('click')
await flushPromises()
expect(wrapper.emitted('update:coords')).toBeUndefined()
expect(wrapper.find('[data-testid="geo-regeocode-failed"]').exists()).toBe(true)
})
it('masque le bouton en lecture seule', () => {
const wrapper = mountPin({ readonly: true })
expect(wrapper.find('[data-testid="geo-regeocode"]').exists()).toBe(false)
})
})
@@ -65,6 +65,8 @@ function mountBlock(street: string | null) {
MalioSelectCheckbox: true,
MalioInputText: true,
MalioInputAutocomplete: MalioInputAutocompleteStub,
// Pin geographique (M6.1) : teste dans AddressGeoPin.spec.ts.
AddressGeoPin: true,
},
},
})
@@ -130,6 +132,8 @@ describe('ClientAddressBlock — mapping erreur par champ (ERP-101)', () => {
MalioSelectCheckbox: true,
MalioInputAutocomplete: MalioInputAutocompleteStub,
MalioInputText: MalioInputTextProbe,
// Pin geographique (M6.1) : teste dans AddressGeoPin.spec.ts.
AddressGeoPin: true,
},
},
})
@@ -51,6 +51,12 @@ export interface AddressFormDraft {
billingEmailSecondary: string | null
/** Drapeau UI : 2e champ email revele (comme hasSecondaryPhone). */
hasSecondaryBillingEmail: boolean
/** Latitude WGS84 (chaine decimale NUMERIC(10,7)), null si non geolocalisee (M6.1). */
latitude: string | null
/** Longitude WGS84 (chaine decimale NUMERIC(10,7)), null si non geolocalisee (M6.1). */
longitude: string | null
/** RG-6.08 : pin corrige a la main — le geocodage auto ne reecrit plus. */
geoManual: boolean
}
/** Un RIB du client (onglet Comptabilite). */
@@ -96,6 +102,9 @@ export function emptyAddress(): AddressFormDraft {
billingEmail: null,
billingEmailSecondary: null,
hasSecondaryBillingEmail: false,
latitude: null,
longitude: null,
geoManual: false,
}
}
@@ -55,6 +55,12 @@ export interface SupplierAddressFormDraft {
bennes: string | null
/** Prestation de triage (specifique fournisseur, portee par l'adresse — RG). */
triageProvider: boolean
/** Latitude WGS84 (chaine decimale NUMERIC(10,7)), null si non geolocalisee (M6.1). */
latitude: string | null
/** Longitude WGS84 (chaine decimale NUMERIC(10,7)), null si non geolocalisee (M6.1). */
longitude: string | null
/** RG-6.08 : pin corrige a la main — le geocodage auto ne reecrit plus. */
geoManual: boolean
}
/** Un RIB du fournisseur (onglet Comptabilite). */
@@ -95,6 +101,9 @@ export function emptyAddress(): SupplierAddressFormDraft {
contactIris: [],
bennes: '0',
triageProvider: false,
latitude: null,
longitude: null,
geoManual: false,
}
}
@@ -69,6 +69,10 @@ export interface AddressRead extends HydraRef {
isBilling?: boolean
isBroker?: boolean
isDistributor?: boolean
/** Geolocalisation (M6.1) : chaines decimales NUMERIC(10,7) cote API. */
latitude?: string | null
longitude?: string | null
geoManual?: boolean
sites?: SiteRead[]
categories?: CategoryRead[]
// L'embed M2M des contacts d'adresse peut etre un objet (partiel) ou un IRI nu.
@@ -225,6 +229,9 @@ export function mapAddressToDraft(address: AddressRead): AddressFormDraft {
billingEmail: address.billingEmail ?? null,
billingEmailSecondary: address.billingEmailSecondary ?? null,
hasSecondaryBillingEmail: (address.billingEmailSecondary ?? null) !== null && address.billingEmailSecondary !== '',
latitude: address.latitude ?? null,
longitude: address.longitude ?? null,
geoManual: address.geoManual === true,
}
}
@@ -254,6 +254,11 @@ export function buildAddressPayload(
contacts: address.contactIris,
billingEmail: isBillingEmailRequired ? (address.billingEmail || null) : null,
billingEmailSecondary: isBillingEmailRequired && address.hasSecondaryBillingEmail ? (address.billingEmailSecondary || null) : null,
// Geolocalisation (M6.1) : pin manuel persiste avec geoManual=true ;
// geoManual=false laisse le back regeocoder depuis l'adresse postale.
latitude: address.latitude || null,
longitude: address.longitude || null,
geoManual: address.geoManual,
}, ADDRESS_REQUIRED_NON_NULLABLE_KEYS, options)
}
@@ -76,6 +76,10 @@ export interface AddressRead extends HydraRef {
streetComplement?: string | null
bennes?: number | null
triageProvider?: boolean
/** Geolocalisation (M6.1) : chaines decimales NUMERIC(10,7) cote API. */
latitude?: string | null
longitude?: string | null
geoManual?: boolean
sites?: SiteRead[]
categories?: CategoryRead[]
// L'embed M2M des contacts d'adresse peut etre un objet (partiel) ou un IRI nu.
@@ -200,6 +204,9 @@ export function mapAddressToDraft(address: AddressRead): SupplierAddressFormDraf
contactIris: (address.contacts ?? []).map(c => (typeof c === 'string' ? c : c['@id'])),
bennes: address.bennes != null ? String(address.bennes) : '0',
triageProvider: address.triageProvider ?? false,
latitude: address.latitude ?? null,
longitude: address.longitude ?? null,
geoManual: address.geoManual === true,
}
}
@@ -237,6 +237,11 @@ export function buildAddressPayload(address: SupplierAddressFormDraft, options:
contacts: address.contactIris,
bennes: address.bennes !== null && address.bennes !== '' ? Number(address.bennes) : null,
triageProvider: address.triageProvider,
// Geolocalisation (M6.1) : pin manuel persiste avec geoManual=true ;
// geoManual=false laisse le back regeocoder depuis l'adresse postale.
latitude: address.latitude || null,
longitude: address.longitude || null,
geoManual: address.geoManual,
}, ADDRESS_REQUIRED_NON_NULLABLE_KEYS, options)
}