Repo backend/obambu_node (Python 3.11, FastAPI, SQLite)

Contenu actuel

• Structure déjà posée : app/main.py (FastAPI + redirection docs), app/models.py (schémas Pydantic), app/storage.py (SQLite + docs/meta), requirements.txt (FastAPI/uvicorn/pydantic).
• Dossiers présents : storage/docs, storage/meta, static/, devices/, scripts tools/ pour signatures/bundles.
• README actuel : guide d’installation (venv + pip), commandes de lancement, génération de clés ed25519 (admin_sign.py).

Prérequis et outils

• Python 3.11+, pip. Environnement virtuel recommandé pour isoler les dépendances.
• OS cible : laptop/mini-PC (dev), Raspberry Pi envisageable (optimiser plus tard).

Choix structurants (Phase 0)

• FastAPI pour rapidité de prototypage, auto-docs (OpenAPI), simplicité de validation.
• SQLite en local pour garder la base monofichier et portable (copiable en USB).
• Stockage fichiers à plat pour les docs, méta en JSON pour inspection rapide.

Fichiers clés à surveiller

• app/main.py : point d’entrée, routes publiques/admin.
• app/storage.py : logique d’index, chemins docs/meta, hash.
• admin_sign.py : génération et signature admin (clé ed25519).
• requirements.txt : gèle la version de FastAPI/uvicorn pour éviter les surprises.

Points à garder en tête pour la suite

• Prévoir migration vers Postgres ou moteur embarqué plus tard si concurrence accrue.
• Maintenir la compatibilité air-gap : aucune dépendance réseau pour démarrer.
• Documenter les chemins de stockage pour les scripts de sync (Phase 4).

Endpoints init : /health, POST /api/v1/device/hello

/health

• Rôle : vérification rapide de l’état du nœud (pour scripts de supervision ou probes locales).
• Réponse attendue : statut simple (JSON) pour signaler que l’API répond.

/api/v1/device/hello

• Rôle : enregistrer ou mettre à jour un device (ID, type de station, version firmware).
• Effet attendu : créer la fiche device si absente, renvoyer un message de bienvenue et la version de config.
• Prévoir : journalisation minimale (timestamp, device_id), garde-fous anti-spam (à raffiner Phase 1/2).

Décisions et limites actuelles

• Pas encore de jeton/signature obligatoire sur ces endpoints de base (sécurisation à pousser en Phase 5).
• Pas de quotas ni de throttling, à ajouter quand les flux se multiplieront.

Stack FastAPI + lancement uvicorn

Environnement

• FastAPI + uvicorn pour le serveur; Pydantic pour validation des payloads.
• SQLite (fichier storage/obambu.sqlite) pour conserver devices/config/plan de contenus.

Lancement et exploitation

• Commande de dev : uvicorn app.main:app --reload (port par défaut 8000).
• Points de vigilance : droits d’écriture sur storage/, création des dossiers au premier démarrage.
• Logs : surveiller les traces pour détecter les premiers enregistrements device et les erreurs de stockage.

Choix et raisons

• Reload en dev pour itérer vite; en prod, passer en mode workers (gunicorn/uvicorn) et désactiver reload.
• Pas de dépendance externe (DB, cache) pour rester déployable sur un laptop isolé.
• Orientation « portable » : répertoire storage/ copiable sur clé USB pour tests de synchro.