Initialisation Forge IoT : `forge iot:init`¶

Statut : commande de préparation.
Elle copie la migration SQL Forge IoT du package vers mvc/migrations/ du projet, mais n'applique pas le SQL.
C'est forge migration:apply qui le fait ensuite, séparation volontaire pour rester lisible et relisible.

Objectif¶

Boucler le parcours du starter Bonjour IoT : passer de la réponse pédagogique

{"error": "iot_storage_not_ready"}

à une table iot_events prête à être créée par forge migration:apply.
Aucune connexion base, aucun SQL exécuté.

Usage¶

forge iot:init

Aucune option à ce ticket.
Aide via :

forge iot:init --help

Flux recommandé¶

forge iot:doctor       # vérifier package, config, migration, API HTTP
forge iot:init         # copier la migration vers mvc/migrations/
forge migration:apply  # créer la table iot_events en base
forge run              # démarrer l'application

Avec ce parcours :

forge iot:doctor confirme que forge-mvc-iot est installé, que la configuration est correcte et que la migration est embarquée dans le package.
forge iot:init copie le .sql depuis le package vers mvc/migrations/ du projet.
Idempotent.
forge migration:apply (commande Forge Core existante) crée la table.
forge run démarre le serveur ; les routes /welcome-optin-iot/events et /api/iot/events peuvent maintenant retourner des données réelles.

Comportement¶

Cas normal : fichier copié¶

[OK] Migration IoT copiée : mvc/migrations/20260528120000_create_iot_events.sql

[INFO] Lance maintenant : forge migration:apply

Exit code : 0.

Cas idempotent : déjà présent, contenu identique¶

[OK] Migration IoT déjà présente (identique) : mvc/migrations/20260528120000_create_iot_events.sql

[INFO] Lance maintenant : forge migration:apply

Exit code : 0.
La commande est sûre à rejouer.

Cas conflit : fichier présent, contenu différent¶

[WARN] mvc/migrations/20260528120000_create_iot_events.sql existe et diffère - aucune modification.

Exit code : 0.
Aucun écrasement : si l'utilisateur a modifié la migration localement, la décision lui revient ; la commande ne touche rien.
Pour repartir de la version packagée, supprimer manuellement le fichier puis relancer forge iot:init.

Cas dossier inexistant¶

Si mvc/ existe mais pas mvc/migrations/, le dossier est créé :

[INFO] Dossier mvc/migrations/ créé.
[OK] Migration IoT copiée : mvc/migrations/20260528120000_create_iot_events.sql

[INFO] Lance maintenant : forge migration:apply

Cas hors projet Forge¶

[ERREUR] Ce dossier ne ressemble pas à un projet Forge.
Conseil : lance cette commande à la racine du projet (dossier mvc/ attendu).

Exit code : 1.

Lecture des migrations packagées¶

La commande utilise importlib.resources pour lire les ressources embarquées dans le package Python, fonctionne identiquement en install éditable (depuis le monorepo) et en install PyPI réelle.

Le ticket IOT-PACKAGE-DATA-MIGRATIONS-001 a embarqué les .sql via [tool.setuptools.package-data] dans pyproject.toml, garantissant que forge iot:init trouve toujours sa source quelle que soit l'installation.

Hors périmètre¶

Sont volontairement hors périmètre de cette commande :

pas de forge migration:apply automatique : séparation explicite préparation / exécution ;
pas de connexion à MariaDB ;
pas de vérification que la table iot_events existe déjà ;
pas de rollback de migration ;
pas d'option interactive (--force, --diff, etc.) ;
pas de subscriber MQTT lancé ;
pas de modification de fichiers en dehors de mvc/migrations/.

Module opt-in absent¶

Si forge-mvc-iot n'est pas installé, forge iot:init retourne :

Erreur : module forge-mvc-iot non installé.
indice : installe le module opt-in : pip install forge-mvc-iot

Forge Core reste fonctionnel sans le module : l'import est paresseux côté dispatcher (forge.py).

Initialisation Forge IoT : forge iot:init¶