# BDC Collecteur — agent de relevé SNMP (Phase 10, Lot 1)

Agent ultra léger déployé **chez le client**. Il interroge les copieurs en **SNMP**
(MIB Printer RFC 3805 : n° de série, niveaux toner, compteurs) et **pousse** la
télémétrie vers le serveur BDC Pro. Il s'installe en **service Windows** (démarrage
automatique au boot) et fonctionne en arrière-plan.

> **RGPD — par conception** : l'agent ne collecte **que de la télémétrie machine**
> (n° de série, niveaux de consommables, compteurs de pages). **Jamais** de noms
> d'utilisateurs, de titres de documents ni de contenu de jobs d'impression. Le flux
> est **sortant uniquement** (l'agent pousse vers BDC en HTTPS) : aucun port ouvert
> chez le client. Les relevés ont une **rétention configurable** côté serveur.

## Installation en 2 minutes (recommandé)

Aucune édition de fichier n'est nécessaire — un assistant vous guide.

1. **Téléchargez l'agent** : https://snmp.levgend.fr
2. **Faites un clic droit** sur `bdc-collecteur.exe` → **« Exécuter en tant
   qu'administrateur »** (nécessaire pour installer le service Windows).
3. L'assistant s'ouvre et vous demande simplement :
   - le **code d'enrôlement** fourni par votre prestataire ;
   - s'il doit **rechercher les copieurs** automatiquement sur le réseau (recommandé).
4. Il enrôle l'agent, installe le service et le démarre. **C'est tout** : l'agent
   tourne désormais en arrière-plan et relève les copieurs automatiquement.

> L'URL du serveur est déjà pré-renseignée. Windows peut afficher un avertissement
> « éditeur inconnu » (binaire non signé) : cliquez sur « Informations complémentaires »
> → « Exécuter quand même ».

Pour relancer l'assistant plus tard (changer de code, refaire un scan) :
double-cliquez à nouveau sur l'exe, ou lancez `bdc-collecteur.exe setup`.

## Architecture

```
copieurs (SNMP) ──▶ agent (ce programme) ──HTTPS push──▶ BDC  /api/collecteur/*
                       │
                       └─ file d'attente sur disque (résilience réseau)
```

- `main.go` — cycle de vie du service + boucles de polling (toner / compteur / heartbeat / flush)
- `config.go` — `config.json` local (le serveur fait foi pour fréquences & SNMP)
- `snmp.go` — lecture SNMP (Printer-MIB)
- `client.go` — appels `/api/collecteur/{enroll,sync,heartbeat}` (token agent)
- `queue.go` — file d'attente disque + rejeu ordonné (réseau coupé → on garde et on réessaie)
- `sysinfo.go` — hostname / OS / IP locale (indicatifs)

## Prérequis de build

Go **1.21+**. Le poste de dev n'a pas Go installé → deux options :

**Option A — Go installé sur la machine**
```bash
cd C:\Claude\BDC\bdc-collecteur
go mod tidy            # récupère gosnmp + kardianos/service
go build -o bdc-collecteur.exe .
```

**Option B — toolchain Go portable** (comme le Node 20 portable du mobile)
1. Télécharger l'archive `go1.21.x.windows-amd64.zip` depuis https://go.dev/dl/
2. La dézipper dans `C:\Claude\BDC\bdc-collecteur\go\`
3. Builder :
```powershell
$env:GOROOT="C:\Claude\BDC\bdc-collecteur\go"
$env:PATH="$env:GOROOT\bin;$env:PATH"
cd C:\Claude\BDC\bdc-collecteur
go mod tidy
go build -o bdc-collecteur.exe .
```

> Build multiplateforme possible (`GOOS=windows GOARCH=amd64`). Cible principale :
> Windows amd64 (PC/serveurs clients).

## Procédure d'installation manuelle (avancé)

> La plupart des installations passent par l'**assistant** (voir « Installation en
> 2 minutes » plus haut). Cette procédure manuelle ne sert que pour un déploiement
> scripté ou un cas particulier.

1. **Côté BDC** (staff) : générer un **code d'enrôlement** pour le client concerné
   (`POST /api/collecteurs/code` avec `entreprise_id`). Le code est valable 72 h.
2. **Sur la machine cliente** : copier `bdc-collecteur.exe`, puis créer `config.json`
   (à partir de `config.example.json`) :
   - `server_url` : l'URL HTTPS publique du serveur BDC
   - `enroll_code` : le code généré à l'étape 1
   - `printers` : la liste des IP des copieurs. Pour la **découverte automatique**,
     laisser vide puis lancer le scan SNMP du réseau :
     ```powershell
     .\bdc-collecteur.exe scan              # liste les copieurs SNMP trouvés
     .\bdc-collecteur.exe scan -save        # + ajoute les copieurs à config.printers
     .\bdc-collecteur.exe scan -subnet 192.168.10.0/24   # cible un sous-réseau précis
     ```
     Le scan utilise la `community`/`version` SNMP de `config.json`. Sélection :
     `-save` ajoute tous les copieurs détectés ; sinon, éditer `printers` à la main
     pour ne garder que les machines concernées.
3. **Installer le service** (PowerShell admin) :
```powershell
.\bdc-collecteur.exe install
.\bdc-collecteur.exe start
```
4. Au démarrage, l'agent **échange le code contre un token permanent** (le code est
   alors effacé de `config.json`), adopte la config serveur, puis relève les copieurs.

### Test / debug
```powershell
.\bdc-collecteur.exe once   # une collecte unique puis sortie (vérif terrain)
.\bdc-collecteur.exe run    # exécution en avant-plan (logs console)
```

### Désinstallation
```powershell
.\bdc-collecteur.exe stop
.\bdc-collecteur.exe uninstall
```

## Commandes
| Commande | Effet |
|----------|-------|
| `setup` | **assistant interactif** (code, scan, enrôlement, installation) — aussi lancé au double-clic |
| `install` / `uninstall` | (dés)enregistre le service Windows (démarrage auto) |
| `start` / `stop` / `restart` | pilote le service |
| `run` | exécute en avant-plan (utilisé par le gestionnaire de services) |
| `once` | une collecte unique puis sortie (test) |
| `scan` | découverte SNMP du réseau (`-subnet CIDR`, `-save` pour ajouter à `config.printers`) |
| `-config <chemin>` | fichier de config alternatif (défaut : à côté de l'exe) |

## Fonctionnement

### Fréquences de relève
| Quoi | Défaut | Réglable |
|------|--------|----------|
| Niveaux **toner** | toutes les **15 min** | BDC → Réglages (`collecteur_toner_interval_min`) |
| **Compteurs** pages | toutes les **24 h** | BDC → Réglages (`collecteur_compteur_interval_min`) |
| **Heartbeat** (présence + adoption config) | toutes les **5 min** | fixe |
| **Flush** de la file vers le serveur | toutes les **1 min** | fixe |

Une **collecte immédiate** (toner + compteur) a lieu au démarrage du service. Les fréquences
poussées par le serveur sont appliquées **au prochain redémarrage** du service.

### File d'attente = état courant (instant T), pas l'historique
La file disque assure la résilience réseau, mais on **ne rejoue pas tout l'historique** d'une
coupure : à chaque relève, les lots en attente sont **fusionnés en un unique instantané** ne
conservant que le **dernier relevé par (copieur, couleur)** (et le dernier compteur). À la
reprise du réseau, l'agent ne pousse donc que l'**état courant** des copieurs. La détection de
changement de cartouche reste correcte : le serveur compare au dernier niveau qu'**il** a stocké,
pas aux relevés intermédiaires perdus pendant la coupure.

### Changer l'URL du backend sans repasser sur site
L'agent connaît le backend via `server_url` dans son `config.json`. Deux façons de la faire évoluer :

1. **Recommandé — utiliser un nom DNS stable** (`https://bdc.mondomaine.fr`) plutôt qu'une IP.
   Un changement d'IP du serveur ne nécessite alors **qu'une mise à jour DNS**, les agents
   ne bougent pas.
2. **Migration pilotée depuis BDC** : Réglages → Général → « URL backend poussée aux agents ».
   La nouvelle URL est transmise à tous les agents au prochain heartbeat ; ils l'**adoptent et la
   persistent** dans `config.json`. ⚠️ Ne fonctionne **que si l'ancien backend reste joignable**
   pendant la bascule (l'agent y apprend la nouvelle URL). Pour un changement d'IP **brutal** sans
   recouvrement, seule l'option DNS évite de repasser sur chaque site.

## Limites connues
- SNMP **v1/v2c** seulement (v3 = TODO Lot ultérieur si un client l'impose).
- Changement de fréquence/SNMP/URL poussé par le serveur : **appliqué au prochain
  redémarrage** du service (la liste d'IP, elle, est adoptée au heartbeat).
- Le **rapprochement n° série → parc** est **côté serveur** (Lot 2). La file étant
  fusionnée en un instantané (cf. « instant T »), il n'y a plus d'historique à dédupliquer.
- **Pas un dépôt Git** à ce stade (comme `bdc-mobile`) : versionné à part le moment venu.