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¶