Concepts

Veille (surveillance)

Un scrap récurrent qui compare chaque exécution à la précédente et fait remonter des signaux de réputation.

Une veille est la réexécution planifiée d'un job ou pipeline existant. Chaque exécution est comparée à la précédente, et les différences sont exposées comme signaux.

Une veille est créée à partir d'un job scrap existant (la source). Sa requête + zones + paramètres deviennent le modèle, cloné à chaque exécution planifiée.

   job source (scrap ponctuel)
        │  enregistré comme veille, fréquence = 7 jours
        ▼
   run 1   ──►   poi_list_v1
        │  7 jours plus tard
        ▼
   run 2   ──►   poi_list_v2
        │  diff(v1, v2)
        ▼
   rapport de changements :
     - nouveaux POIs (ouvertures)
     - POIs fermés (introuvables)
     - POIs modifiés (notes en baisse, contact changé, ...)

Fréquence

Jours, 1–365. L'horaire est volontairement interdit : la donnée prospect n'évolue pas aussi vite, et les rate limits sources ne tiendraient pas. Typique : 7 (hebdo), 30 (mensuel), 90 (trimestriel).

Signaux

Trois catégories extraites de chaque diff :

new — dans la nouvelle exécution, absent avant (concurrents nouvellement ouverts, partenaires, cibles d'acquisition)
closed — absent de la nouvelle exécution, présent avant (nettoyage prospection ; signal précoce de fermeture)
modified — présent dans les deux, changé :
Delta de note — chute Google = signal fort « client en difficulté »
Delta de nombre d'avis — activité en envol ou en stagnation
Delta de contact — téléphone ou site web changé (souvent un relancement)

Les lignes modifiées sont scorées ; l'endpoint signals les renvoie classées.

Endpoints

GET    /api/veille                              # liste les veilles utilisateur
POST   /api/veille                              # création
PATCH  /api/veille/{id}                         # mise à jour nom, fréquence, statut
DELETE /api/veille/{id}                         # suppression douce
GET    /api/veille/{id}/runs                    # historique des exécutions
GET    /api/veille/{id}/runs/{run_id}           # une exécution + diff
GET    /api/veille/{id}/runs/{run_id}/signals   # signaux filtrés, scorés

L'endpoint signals supporte CSV / JSON / XLSX via ?format=….

États

État	Signification
`active`	S'exécute selon le planning
`paused`	Planning suspendu ; exécutions existantes conservées
`deleted`	Supprimé en douce ; données conservées

Une exécution de veille est un job normal — mêmes workers, mêmes quotas. Ne compte dans le plafond de jobs en cours qu'au moment de l'exécution.