Plan de recette et de déploiement des applications Loutre

Ce document prépare les opérations ; il ne les autorise pas. Aucun déploiement de production, redémarrage CodexPi, changement QNAP/Jellyfin ou exposition publique ne doit être exécuté sans accord explicite.

1. Conditions d'entrée

Une application peut entrer en recette uniquement si sa branche contient un commit identifié, si son worktree est propre hors artefacts ignorés, si ses tests métier et son build passent à nouveau depuis ce commit et si ses limites matérielles sont documentées. Le statut reste au maximum TESTING avant cette recette.

Pour les connecteurs QNAP, Jellyfin, Docker, SMB, Home Assistant ou réseau, la recette commence avec des fixtures et un compte ou jeton de lecture seule. Une simulation doit être étiquetée comme telle dans l'interface. Aucun média, virtual host, certificat, appareil ou montage n'est modifié pendant cette étape.

2. Sauvegardes avant changement

Arrêter toute nouvelle tâche de déploiement et attendre la fin de la session Codex active.
Enregistrer le SHA de CodexPi, le SHA de l'application et les versions d'images actuellement actives.
Copier les bases SQLite avec leur méthode de sauvegarde cohérente (VACUUM INTO ou API de sauvegarde SQLite), puis vérifier PRAGMA integrity_check sur la copie.
Sauvegarder les volumes applicatifs concernés sans inclure les jetons, cookies ou profils dans les journaux de preuve.
Exporter la configuration Compose résolue en masquant les variables sensibles.
Pour le reverse proxy QNAP, obtenir séparément une sauvegarde en lecture seule des fichiers autorisés. Aucune écriture NAS n'est incluse dans le déploiement CodexPi.

Les sauvegardes portent un horodatage UTC et sont conservées hors des worktrees Git. Un test de lecture est obligatoire avant de poursuivre.

3. Recette isolée

Chaque application est construite depuis son commit dans un projet Compose distinct, avec un nom de projet unique, un volume de recette neuf et un port lié uniquement à 127.0.0.1. Une seule application lourde est démarrée à la fois sur le Raspberry Pi.

La recette vérifie :

santé HTTP et démarrage sans migration destructive ;
authentification et isolation entre utilisateurs ;
création, modification, réouverture après redémarrage et suppression lorsque prévue ;
erreurs de validation et indisponibilité des connecteurs ;
build frontend, navigation mobile 390 px et absence d'erreur JavaScript ;
absence de bouton essentiel fictif ;
persistance sur le volume de recette ;
limites CPU/RAM et taille des journaux ;
export/import ou sauvegarde spécifique à l'application ;
URL interne d'ouverture depuis le catalogue CodexPi.

Les applications d'infrastructure comparent les valeurs affichées à la source autorisée. Une valeur issue d'une fixture ne valide jamais le connecteur réel.

4. Passage contrôlé

Après présentation des preuves, l'utilisateur choisit explicitement l'application et la fenêtre de déploiement. Le changement utilise une nouvelle image immuable étiquetée avec le SHA, puis un remplacement ciblé du seul service concerné. Il n'inclut jamais docker compose down -v, un redémarrage du Pi/NAS, une modification SSH/pare-feu ou une modification automatique du reverse proxy QNAP.

Les contrôles immédiats sont : santé, connexion, lecture de données existantes, écriture d'une donnée de contrôle réversible, réouverture, journaux sans secret et lien « Ouvrir » du catalogue. READY_V0 n'est attribué qu'après leur réussite.

5. Rollback

Le rollback restaure l'image précédente et la configuration Compose précédente. Si une migration de données a été appliquée, son plan spécifique doit être testé avant le déploiement ; à défaut, l'application repasse en lecture seule et la base sauvegardée est restaurée dans un volume distinct pour comparaison. Les volumes actuels ne sont jamais supprimés automatiquement.

Un échec de santé, une perte d'authentification, une erreur de persistance, une consommation anormale ou une divergence avec une source réelle déclenche le rollback. L'incident et les commandes réellement exécutées sont ajoutés à l'historique, sans valeur secrète.

6. Ordre proposé

PWA Factory, déjà en TESTING.
Pi Doctor en mode collecte/diagnostic uniquement.
LoutreOS en lecture seule.
Codex Commander et Autonomous Dev Studio.
Applications CRUD locales : LoutreFinance, Smart Inventory, AutoCare, Knowledge Graph, PrintPilot, TripOrganizer et LoutreHome.
Connecteurs réseau ou externes : NetworkGuardian, LoutreBrain, Reverse Proxy Manager et modules NASFLIX.

Cet ordre limite les risques : les intégrations QNAP, réseau et médias restent les dernières et conservent leur mode lecture seule tant qu'une validation séparée n'est pas accordée.

7. Registre et workflow préparé

Le registre central application_registry contient exactement les 17 applications métier ; le portail App Store reste un composant de CodexPi et n'est pas compté comme une dix-huitième application. Chaque ligne conserve l'identifiant du portefeuille, le type, le répertoire cible, le commit, les stacks backend/frontend, l'URL interne, la route d'ouverture, les preuves de tests, les dépendances, le statut et les limites de déploiement.

Les statuts de mise en service sont distincts des statuts de développement :

DEVELOPMENT_READY : code récupérable, mais V0 ou preuves encore incomplètes ;
TESTING : validations isolées en cours ou terminées sans recette cible ;
INTEGRATION_READY : commit, tests métier, persistance et route prêts pour recette ;
DEPLOYED : révision réellement démarrée dans l'environnement déclaré ;
OPERATIONAL : healthchecks, route, HTTPS et scénarios métier vérifiés sur la cible ;
BLOCKED : preuve ou dépendance indispensable absente.

Les API /api/application-registry et /api/application-registry/mission exposent respectivement le registre et la supervision de la file. La préparation d'un déploiement crée un enregistrement PREPARED et dix étapes persistantes : sauvegarde, dépendances, migrations, configuration, démarrage, healthcheck, routes, HTTPS, smoke test et rollback. Elle n'exécute aucune commande. Une cible doit être privée, le commit doit correspondre au registre et une préparation de production exige INTEGRATION_READY.

Les plans LoutreOS, Pi Doctor, Reverse Proxy Manager et NASFLIX embarquent en plus une liste structurée de contrôles de connecteurs. Chaque contrôle précise le mode autorisé (read-only, Docker rootless, diagnostic uniquement ou brouillon) et la preuve attendue. Ces lignes restent des exigences de recette : leur présence dans un plan ne signifie jamais que le Raspberry Pi, QNAP ou Jellyfin a été contacté.

DEPLOYED et OPERATIONAL ne peuvent pas être saisis manuellement. Leur future promotion devra provenir du workflow exécuté après autorisation, avec preuves attachées à chaque étape. Ainsi, des tests unitaires verts ne suffisent jamais à rendre une application opérationnelle.

8. Tableau de mise en service des 17 applications

Projet	Code	Tests	Intégration	Déploiement	Opérationnel
LoutreOS	Commit `2021e40`, collecteur/FastAPI/React	56 backend, 7 frontend, 2 navigateur, persistance et HTTP validés	Route réelle CodexPi et connecteurs Pi/Docker/QNAP/Jellyfin cible manquants	`TESTING`, aucune cible déployée	NON — sources réelles externes non testées
NetworkGuardian	Worktree FastAPI/React existant	29 backend et build ; parcours cible à refaire	URL CodexPi, découverte autorisée et carte réseau cible manquantes	`DEVELOPMENT_READY`	NON — réseau réel non vérifié
Reverse Proxy Manager	Worktree FastAPI/React et parseur Apache	25 backend et 6 navigateur conservés	Source QNAP en lecture seule, certificats et workflow de validation manquants	`TESTING`	NON — QNAP non connecté
Codex Commander	Module CodexPi et application isolée existants	12 backend/build ; navigateur incomplet	Unification, collaboration et reprise réelle à valider	`DEVELOPMENT_READY`	NON — session V0 cible non validée
Autonomous Dev Studio	Module CodexPi fonctionnel partiel	Tests intégrés, aucun parcours complet jusqu'à preview	Versionnement, correction automatique et preview bout en bout manquants	`DEVELOPMENT_READY`	NON — aucune application complète produite en recette
LoutreBrain	Worktree FastAPI/FTS5/React existant	18 backend et build ; navigateur à refaire	Recherche sémantique, index CodexPi et route réelle manquants	`TESTING`	NON — moteur cible non validé
LoutreFinance	Worktree Django/React existant	17 Django et 2 navigateur conservés	Revalidation persistance, route CodexPi et recette privée manquantes	`TESTING`	NON — aucune cible démarrée
PrintPilot	Worktree FastAPI/React existant	37 backend et build	Route, preview et connecteurs matériels explicites manquants	`DEVELOPMENT_READY`	NON — aucune imprimante réelle testée
LoutreHome	Worktree FastAPI/React existant	14 backend et build	Capteurs/automatisations, route et Home Assistant/MQTT cible manquants	`DEVELOPMENT_READY`	NON — données simulées uniquement
AutoCare	Worktree FastAPI/React existant	25 backend et build	Route, documents/assurances et preview cible à valider	`DEVELOPMENT_READY`	NON — aucune cible démarrée
Smart Inventory	Worktree FastAPI/React existant	23 backend et build	Route, photos/documents et restauration cible à valider	`DEVELOPMENT_READY`	NON — aucune cible démarrée
Knowledge Graph	Worktree FastAPI/React/SVG existant	13 backend et build	Lien LoutreBrain, route et parcours mobile cible manquants	`DEVELOPMENT_READY`	NON — aucune cible démarrée
TripOrganizer	Worktree FastAPI/React existant	17 backend et build	Documents, carte optionnelle, route et mode hors ligne cible manquants	`DEVELOPMENT_READY`	NON — aucune cible démarrée
PWA Factory	Commit `7f31d2c`, éditeur intégré	Tests CRUD/export ZIP et démarrage de l'export réussis	Recette HTTPS/iPhone et validation visuelle cible manquantes	`TESTING`	NON — non déployée et installation iPhone non testée
NASFLIX MediaHealth	Code partiel dans NASFLIX	Tests connexes uniquement	Rapport, historique, corruption potentielle et Jellyfin réel manquants	`DEVELOPMENT_READY`	NON — aucune analyse cible complète
NASFLIX AI Media Curator	Module NASFLIX partiel	Acceptation dédiée absente	Historique, collections brouillon et Jellyfin cible à valider	`DEVELOPMENT_READY`	NON — recommandations cibles non vérifiées
Pi Doctor	Commit `a5dc22e`, collecteurs, FastAPI/React et module CodexPi	38 backend, 3 frontend, 4 navigateur, build et HTTP loopback validés	systemd, Docker cible, ingestion CodexPi et session spécialisée réels restent à valider	`TESTING`	NON — service hôte non installé et connecteurs réels non testés

11 KiB Raw Permalink Blame History