# Utilisation API en Réseau Local (VM / OpenClaw)

Ce guide explique comment exposer et consommer l'API backend Jardin depuis des machines VM de votre réseau local, y compris un poste équipé d'OpenClaw.

## 1. Vérifier l'accessibilité API sur le LAN

Le backend écoute sur le port `8060` via Docker Compose.

Depuis la machine hôte:

```bash
curl http://127.0.0.1:8060/api/health
```

Depuis une VM du réseau local (remplacez `192.168.1.50`):

```bash
curl http://192.168.1.50:8060/api/health
```

Réponse attendue:

```json
{"status":"ok"}
```

Si ça ne répond pas:
- vérifier que Docker est démarré
- vérifier que le pare-feu autorise `8060/tcp`
- vérifier l'IP LAN de l'hôte

## 2. CORS pour clients web distants (OpenClaw UI navigateur)

Si l'appel API est fait côté navigateur depuis une autre origine (ex: UI OpenClaw sur une VM), il faut autoriser cette origine dans `CORS_ORIGINS`.

Exemple `.env`:

```env
CORS_ORIGINS=http://localhost:5173,http://localhost:8061,http://192.168.1.80:3000
```

Puis redémarrer:

```bash
docker compose up -d --build backend
```

Note:
- appel serveur-à-serveur: CORS non requis
- appel navigateur: CORS requis

## 3. Endpoints utiles pour automatisation VM/OpenClaw

Santé:

```bash
curl http://192.168.1.50:8060/api/health
```

Météo tableau:

```bash
curl "http://192.168.1.50:8060/api/meteo/tableau?center_date=2026-02-22&span=15"
```

Rafraîchir jobs météo:

```bash
curl -X POST http://192.168.1.50:8060/api/meteo/refresh
```

Lire réglages:

```bash
curl http://192.168.1.50:8060/api/settings
```

Activer debug UI:

```bash
curl -X PUT http://192.168.1.50:8060/api/settings \
  -H "Content-Type: application/json" \
  -d '{"debug_mode":"1"}'
```

Stats debug backend (CPU/RAM/disque conteneur):

```bash
curl http://192.168.1.50:8060/api/settings/debug/system
```

Upload fichier:

```bash
curl -X POST http://192.168.1.50:8060/api/upload \
  -F "file=@/chemin/fichier.mp4"
```

Télécharger une sauvegarde ZIP (BDD + uploads + fichiers texte):

```bash
curl -L "http://192.168.1.50:8060/api/settings/backup/download" \
  -o "jardin_backup.zip"
```

## 4. Scripts de mise à jour BDD (hors webapp)

Station locale -> DB:

```bash
python3 station_meteo/update_station_db.py
```

Historique Open-Meteo -> DB:

```bash
python3 station_meteo/update_openmeteo_history_db.py --start-date 2026-01-01 --end-date 2026-02-22
```

## 5. Paramètres recommandés pour OpenClaw

- Base URL API: `http://192.168.1.50:8060`
- Endpoint test: `/api/health`
- Timeout conseillé: `15-30s`
- Corps JSON: UTF-8
- Pour upload: `multipart/form-data`

## 6. Skill OpenClaw recommandé

Le skill à utiliser s'appelle désormais: `jardin-api-backend`.

Emplacement dans le repo:

- `skills/jardin-api-backend/SKILL.md`
- `skills/jardin-api-backend/references/backend-api-recipes.md`
- `skills/jardin-api-backend/consigne.md`

Installation rapide (exemple):

```bash
mkdir -p ~/.codex/skills
cp -R skills/jardin-api-backend ~/.codex/skills/
```

Ensuite, relancer OpenClaw et vérifier que le skill **Jardin API Backend** apparaît.

## 7. Sécurité (important)

L'API actuelle est sans authentification. Sur réseau local, minimum recommandé:
- segmenter le réseau (VLAN/VM dédiées)
- filtrer par IP source (pare-feu hôte)
- ne pas exposer directement sur Internet
- idéalement: reverse proxy + authentification (Basic/Auth token) ou VPN

## 8. Swagger

Documentation interactive:

- `http://<IP_HOTE>:8060/docs`