# Structure de l'extension Pilot Control

## Arborescence des fichiers

```
gnome-pilot-extension/
│
├── metadata.json              # Métadonnées de l'extension (UUID, version, etc.)
├── extension.js              # Point d'entrée principal (bouton panel + menu)
├── prefs.js                  # Fenêtre de préférences (optionnel V1)
├── yamlConfig.js            # Module de lecture/écriture YAML
├── serviceManager.js        # Gestion du service systemd
├── stylesheet.css           # Styles CSS personnalisés
│
├── ui/                       # Composants d'interface utilisateur
│   ├── pilotWindow.js       # Fenêtre principale (3 sections)
│   ├── metricEditDialog.js  # Dialogue d'édition des métriques
│   └── commandEditDialog.js # Dialogue d'édition des commandes
│
├── schemas/                  # GSettings schema (optionnel, vide pour V1)
│
├── install.sh               # Script d'installation automatique
├── README.md                # Documentation complète
├── GUIDE_DEBUTANT.md       # Guide pour débutants
└── STRUCTURE.md            # Ce fichier (vue d'ensemble)
```

## Diagramme de flux

```
┌─────────────────────────────────────────────────────────────┐
│                     GNOME Shell Panel                        │
│                                                              │
│  [Icon] Pilot Control ▼                                     │
│         ├─ Status: 🟢 Running                               │
│         ├─ Start Service                                    │
│         ├─ Stop Service                                     │
│         ├─ Restart Service                                  │
│         ├─ Open Control Panel ──────────┐                   │
│         └─ Reload Config                │                   │
└──────────────────────────────────────────┼──────────────────┘
                                           │
                                           ▼
┌──────────────────────────────────────────────────────────────┐
│                   Pilot Control Panel                        │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ [Refresh] [Save]                                       │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌─ Service Control ──────────────────────────────────────┐  │
│  │ Service Status        [Switch ON/OFF]                  │  │
│  │ Auto-start Service    [Switch ON/OFF]                  │  │
│  │ Restart Service       [Button: Restart]                │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌─ Telemetry Metrics ────────────────────────────────────┐  │
│  │ Enable Telemetry     [Switch ON/OFF]                   │  │
│  │                                                         │  │
│  │ CPU Usage            [Switch] [Edit...]                │  │
│  │ Memory Usage         [Switch] [Edit...]                │  │
│  │ Battery              [Switch] [Edit...]                │  │
│  │ Temperature          [Switch] [Edit...]                │  │
│  │ IP Address           [Switch] [Edit...]                │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌─ Commands ─────────────────────────────────────────────┐  │
│  │ Enable Commands      [Switch ON/OFF]                   │  │
│  │ Allowed Commands     [Edit...]                         │  │
│  │   → shutdown, reboot, sleep, hibernate, screen         │  │
│  └─────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘
```

## Flux de données

```
┌──────────────┐
│   User       │
│   Action     │
└──────┬───────┘
       │
       ▼
┌──────────────────────────────────────────┐
│         extension.js                     │
│  (PilotIndicator: Panel Button + Menu)   │
└──────┬───────────────────────────────────┘
       │
       ├─────────────────────┐
       │                     │
       ▼                     ▼
┌──────────────┐      ┌──────────────┐
│ Service      │      │ ui/          │
│ Manager      │      │ pilotWindow  │
└──────┬───────┘      └──────┬───────┘
       │                     │
       │                     ▼
       │              ┌──────────────┐
       │              │ yamlConfig   │
       │              │ (Parser)     │
       │              └──────┬───────┘
       │                     │
       ▼                     ▼
┌──────────────┐      ┌──────────────┐
│ systemctl    │      │ config.yaml  │
│ commands     │      │ (Pilot V2)   │
└──────────────┘      └──────────────┘
       │                     │
       └─────────┬───────────┘
                 │
                 ▼
         ┌──────────────┐
         │ mqtt_pilot   │
         │ .service     │
         │ (Pilot V2)   │
         └──────────────┘
```

## Interactions entre modules

### 1. extension.js → serviceManager.js
```javascript
// Contrôle du service systemd
serviceManager.startService()
serviceManager.stopService()
serviceManager.restartService()
serviceManager.isServiceActive()
```

### 2. extension.js → ui/pilotWindow.js
```javascript
// Ouvre la fenêtre principale
new PilotWindow(extension, yamlConfig, serviceManager)
window.show()
```

### 3. ui/pilotWindow.js → yamlConfig.js
```javascript
// Lecture de la config
yamlConfig.load()
yamlConfig.getTelemetryMetrics()
yamlConfig.getCommandsAllowlist()

// Modification de la config
yamlConfig.updateTelemetryMetric(name, updates)
yamlConfig.setTelemetryEnabled(enabled)
yamlConfig.updateCommandsAllowlist(newList)

// Sauvegarde
yamlConfig.save()
```

### 4. ui/pilotWindow.js → ui/metricEditDialog.js
```javascript
// Édition d'une métrique
const dialog = new MetricEditDialog(parent, metricName, config)
dialog.connect('response', (dlg, responseId) => {
    const updates = dialog.getUpdates()
    // Appliquer les modifications
})
```

### 5. ui/pilotWindow.js → ui/commandEditDialog.js
```javascript
// Édition de la allowlist
const dialog = new CommandEditDialog(parent, currentAllowlist)
dialog.connect('response', (dlg, responseId) => {
    const newAllowlist = dialog.getAllowlist()
    // Appliquer les modifications
})
```

## Cycle de vie de l'extension

```
1. GNOME Shell démarre
   ↓
2. Extension activée (enable())
   ↓
3. PilotIndicator créé
   ↓
4. Icône ajoutée au panel
   ↓
5. Menu construit
   ↓
6. Config chargée (yamlConfig.load())
   ↓
7. Status du service vérifié
   ↓
8. Extension prête

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

User clique sur "Open Control Panel"
   ↓
PilotWindow créée
   ↓
Sections construites (Service, Telemetry, Commands)
   ↓
Données chargées depuis config.yaml
   ↓
Interface affichée

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

User modifie un paramètre
   ↓
Config marquée comme "dirty"
   ↓
User clique "Save"
   ↓
Backup créé (config.yaml.backup_timestamp)
   ↓
Nouveau config.yaml écrit
   ↓
Service redémarré (systemctl restart)
   ↓
Interface mise à jour

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Extension désactivée (disable())
   ↓
Fenêtre détruite
   ↓
Indicateur supprimé du panel
   ↓
Extension arrêtée
```

## Technologies utilisées

| Technologie | Version | Usage |
|-------------|---------|-------|
| **GJS** | - | JavaScript runtime pour GNOME |
| **GTK4** | 4.x | Toolkit d'interface graphique |
| **Libadwaita** | 1.x | Composants UI modernes GNOME |
| **GLib** | 2.x | Utilitaires système (fichiers, processus) |
| **Gio** | 2.x | I/O (lecture/écriture fichiers) |
| **GNOME Shell** | 45+ | Environnement de bureau |

## Dépendances externes

L'extension **n'a pas** de dépendances externes npm/node. Tout est fourni par :

- GNOME Shell
- GJS (inclus avec GNOME)
- GTK4 et Libadwaita (librairies système)

## Permissions requises

L'extension nécessite :

1. **Accès fichiers** :
   - Lecture : `~/app/pilot/pilot-v2/config.yaml`
   - Écriture : `~/app/pilot/pilot-v2/config.yaml`
   - Création de backups : `~/app/pilot/pilot-v2/config.yaml.backup_*`

2. **Commandes systemctl** :
   - `systemctl --user start mqtt_pilot.service`
   - `systemctl --user stop mqtt_pilot.service`
   - `systemctl --user restart mqtt_pilot.service`
   - `systemctl --user status mqtt_pilot.service`
   - `systemctl --user is-active mqtt_pilot.service`
   - `systemctl --user enable mqtt_pilot.service`
   - `systemctl --user disable mqtt_pilot.service`

3. **Logs** :
   - `journalctl --user -u mqtt_pilot.service`

## Sécurité

### Ce que l'extension PEUT faire :
- ✅ Lire et modifier le fichier config.yaml de l'utilisateur
- ✅ Contrôler le service systemd de l'utilisateur (--user)
- ✅ Créer des sauvegardes des fichiers de configuration

### Ce que l'extension NE PEUT PAS faire :
- ❌ Accéder aux services système (nécessite sudo)
- ❌ Modifier des fichiers en dehors du home directory
- ❌ Exécuter des commandes arbitraires non validées
- ❌ Accéder au réseau (pas d'API MQTT directe)

## Limites de V1

1. **Parser YAML simple** : Ne gère que la structure de config.yaml de Pilot V2
2. **Pas de validation avancée** : Entrées utilisateur validées basiquement
3. **Rechargement par redémarrage** : Nécessite un restart du service (pas de reload à chaud)
4. **Une seule instance** : Gère uniquement un service Pilot à la fois
5. **Pas de logs temps réel** : Pas d'affichage des logs dans l'interface

## Extensions futures possibles

- Support de plusieurs instances de Pilot
- Visualisation des logs en temps réel
- Notifications pour événements importants
- Graphiques de métriques (historique)
- Export/import de configurations
- Validation avancée des entrées (regex, ranges)
- Thèmes sombres/clairs personnalisés
- Support de configurations complexes (YAML avancé)

## Ressources

- [Documentation GNOME Extensions](https://gjs.guide/extensions/)
- [GTK4 Documentation](https://docs.gtk.org/gtk4/)
- [Libadwaita Documentation](https://gnome.pages.gitlab.gnome.org/libadwaita/)
- [GJS Examples](https://gitlab.gnome.org/GNOME/gjs/-/tree/master/examples)