"""
Générateur de documentation Markdown pour l'aide Homelab Automation.
"""

from pathlib import Path


def build_help_markdown(html_path: Path = None, html_content: str = None) -> str:
    """Génère le contenu Markdown d'aide professionnel.
    
    Args:
        html_path: Non utilisé (conservé pour compatibilité)
        html_content: Non utilisé (conservé pour compatibilité)
    
    Returns:
        Contenu Markdown formaté professionnellement
    """
    return _get_professional_help_markdown()


def _get_professional_help_markdown() -> str:
    """Retourne la documentation d'aide complète et professionnelle."""
    return """# Homelab Automation Dashboard

## Guide d'Utilisation

Bienvenue dans le guide officiel de votre **Homelab Automation Dashboard** !  
Découvrez comment gérer et automatiser efficacement votre infrastructure grâce à cette solution puissante et centralisée.

---

## Table des Matières

1. [Démarrage Rapide](#démarrage-rapide)
2. [Indicateurs de Santé des Hosts](#indicateurs-de-santé-des-hosts)
3. [Architecture de la Solution](#architecture-de-la-solution)
4. [Fonctionnalités par Section](#fonctionnalités-par-section)
5. [Système de Notifications](#système-de-notifications-ntfy)
6. [Playbooks Ansible Disponibles](#playbooks-ansible-disponibles)
7. [Référence API](#référence-api)
8. [Dépannage](#dépannage)
9. [Raccourcis et Astuces](#raccourcis-et-astuces)

---

## Démarrage Rapide

### Étape 1 : Ajouter vos Hosts

Commencez par ajouter vos serveurs dans la section **Hosts**. Chaque host nécessite :
- Un nom unique
- Une adresse IP
- Un système d'exploitation

### Étape 2 : Bootstrap Ansible

Exécutez le **Bootstrap** sur chaque host pour configurer :
- L'accès SSH avec clé publique
- L'utilisateur d'automatisation
- Les prérequis Ansible (Python, sudo)

### Étape 3 : Automatiser

Utilisez les **Actions Rapides** ou exécutez des playbooks personnalisés pour automatiser vos tâches récurrentes.

---

## Indicateurs de Santé des Hosts

Chaque host affiche un indicateur visuel de santé représenté par des barres colorées. Cet indicateur combine plusieurs facteurs pour évaluer l'état global de votre serveur.

### Comprendre l'Indicateur

| Niveau | Barres | Description |
|--------|--------|-------------|
| **Excellent** | 5 barres vertes | Host en ligne, bootstrap OK, vérifié récemment |
| **Bon** | 3-4 barres jaunes | Host fonctionnel mais certains aspects à améliorer |
| **Moyen** | 2 barres oranges | Attention requise - vérification recommandée |
| **Faible** | 1 barre rouge | Host hors ligne ou non configuré |

### Facteurs de Calcul du Score

| Facteur | Points | Description |
|---------|--------|-------------|
| Statut en ligne | +2 | Le host répond aux requêtes réseau |
| Bootstrap Ansible OK | +1 | SSH et prérequis Ansible configurés |
| Vérifié récemment (<1h) | +2 | Dernière vérification il y a moins d'une heure |
| Vérifié aujourd'hui | +1 | Dernière vérification dans les 24 dernières heures |

> **Astuce :** Exécutez régulièrement un `Health Check` pour maintenir un score de santé élevé.

### Statuts Bootstrap Ansible

- **Ansible Ready** : Le host est entièrement configuré pour Ansible. L'utilisateur automation existe, la clé SSH est déployée et sudo est configuré sans mot de passe.
- **Non configuré** : Le bootstrap n'a pas encore été exécuté sur ce host. Cliquez sur le bouton **Bootstrap** pour configurer l'accès Ansible.

#### Que signifie "Jamais vérifié" ?

Ce message apparaît lorsqu'aucun Health Check n'a été exécuté sur le host depuis son ajout. Le système ne peut pas déterminer l'état réel du serveur. Lancez un Health Check pour mettre à jour le statut et obtenir un score de santé précis.

---

## Architecture de la Solution

### Stack Technologique

| Composant | Technologie | Description |
|-----------|-------------|-------------|
| **Backend** | FastAPI (Python) | API REST haute performance |
| **Automation** | Ansible | Gestion de configuration |
| **Frontend** | HTML/CSS/JS + TailwindCSS | Interface web moderne |
| **Déploiement** | Docker & Docker Compose | Conteneurisation |
| **Temps réel** | WebSocket | Mises à jour live |

### Structure des Fichiers

```
homelab-automation/
├── app/
│   ├── routes/             # Routes API FastAPI
│   ├── models/             # Modèles SQLAlchemy
│   ├── schemas/            # Schémas Pydantic
│   ├── services/           # Logique métier
│   ├── index.html          # Interface web
│   └── main.js             # Logique frontend
├── ansible/
│   ├── inventory/
│   │   ├── hosts.yml       # Inventaire des hosts
│   │   └── group_vars/     # Variables par groupe
│   └── playbooks/          # Playbooks Ansible
├── alembic/                # Migrations de base de données
├── data/                   # Base de données SQLite
├── tasks_logs/             # Logs des tâches
├── docker-compose.yml
└── Dockerfile
```

---

## Fonctionnalités par Section

### Dashboard

Vue d'ensemble centralisée de votre infrastructure homelab.

- **Métriques en temps réel** : État des hosts (Online/Offline), statistiques des tâches (Succès/Échec)
- **Actions Rapides** : Accès immédiat aux opérations courantes (Mise à jour globale, Health Check général)
- **Aperçu des Hosts** : Liste condensée avec indicateurs de statut et OS pour une surveillance rapide
- **Notifications** : Alertes visuelles sur les dernières activités importantes

### Hosts

Gestion complète du cycle de vie de vos serveurs.

- **Inventaire** : Ajout, modification et suppression de hosts avec détection d'OS
- **Bootstrap Ansible** : Préparation automatique des serveurs (User, Clés SSH, Sudo)
- **Indicateurs de Santé** : Score de santé détaillé basé sur la connectivité et la configuration
- **Actions Individuelles** : Exécution de playbooks spécifiques (Upgrade, Backup, Reboot) sur un host
- **Détails Avancés** : Vue détaillée avec historique des tâches et logs spécifiques au host

### Playbooks

Bibliothèque et exécution de playbooks Ansible personnalisés.

- **Catalogue** : Liste de tous les playbooks disponibles dans votre répertoire
- **Exécution Ciblée** : Lancement de playbooks sur des hosts spécifiques ou des groupes
- **Logs en Direct** : Suivi temps réel de l'exécution Ansible (console output)
- **Historique** : Accès rapide aux résultats des exécutions précédentes

### Tasks

Traçabilité complète de toutes les opérations d'automatisation.

- **Suivi d'État** : Visualisation instantanée (En cours, Succès, Échec)
- **Filtrage Avancé** : Recherche par statut, par date ou par type d'action
- **Logs Détaillés** : Accès aux sorties standard et d'erreur pour le débogage
- **Auto-refresh** : Mise à jour automatique des tâches en cours d'exécution

### Schedules

Planification automatisée des tâches récurrentes.

- **Planification Cron** : Configuration flexible de la fréquence d'exécution
- **Tâches Récurrentes** : Backups quotidiens, Mises à jour hebdomadaires, Health Checks horaires
- **Ciblage** : Définition des hosts ou groupes cibles pour chaque planification
- **Gestion** : Activation, désactivation ou modification des planifications existantes

### Logs

Journal technique des événements système.

- **Streaming WebSocket** : Arrivée des logs en temps réel sans rechargement de page
- **Niveaux de Log** : Distinction claire entre Info, Warning et Error
- **Export** : Possibilité de télécharger les logs pour analyse externe
- **Rétention** : Gestion de l'historique et nettoyage des logs anciens

### Alertes

Centre de messages pour les événements importants.

- **Suivi** : Consultez les alertes récentes (succès/échec, changements d'état)
- **Lecture** : Les alertes peuvent être marquées comme lues pour garder une boîte de réception propre
- **Notifications** : Certaines alertes peuvent déclencher des notifications ntfy (si activé)

### Configuration

Paramètres de l'application et intégrations.

- **Paramètres applicatifs** : Options persistées (ex: collecte des métriques)
- **Notifications** : Configuration et test du service ntfy
- **Sécurité** : Gestion du compte utilisateur (mot de passe) via l'écran utilisateur

---

## Système de Notifications (ntfy)

Restez informé de l'état de votre infrastructure grâce au système de notifications intégré basé sur **ntfy**.

### Canaux et Configuration

Les notifications sont envoyées via le service ntfy, permettant de recevoir des alertes push sur mobile et desktop.

- **Push Mobile** : Via l'application ntfy (Android/iOS)
- **Web Push** : Notifications navigateur sur desktop
- **Priorité** : Gestion des niveaux d'urgence (Low à High)

### Types d'Alertes

Vous recevez des notifications pour les événements critiques :

- ✅ Succès des Backups
- ❌ Échecs de Tâches
- ⚠️ Changements de Santé Host
- 🛠️ Fin de Bootstrap

---

## Playbooks Ansible Disponibles

### bootstrap-host.yml

Configure un nouveau host pour Ansible : création utilisateur, clé SSH, sudo sans mot de passe.

> **Note :** Requis avant toute autre opération

### health-check.yml

Vérifie l'état de santé : CPU, RAM, disque, services critiques.

> **Note :** Exécution rapide, non destructif

### system-upgrade.yml

Met à jour tous les paquets système (apt/yum/dnf selon l'OS).

> **Attention :** Peut nécessiter un redémarrage

### backup-config.yml

Sauvegarde les fichiers de configuration importants (/etc, configs apps).

> **Note :** Stockage local ou distant

---

## Référence API

L'API REST est accessible sur le port configuré. Authentification via header `Authorization: Bearer <token>`.

| Endpoint | Méthode | Description |
|----------|---------|-------------|
| `/api/hosts` | GET | Liste tous les hosts |
| `/api/hosts` | POST | Ajoute un nouveau host |
| `/api/hosts/{id}` | PUT | Modifie un host existant |
| `/api/hosts/{id}` | DELETE | Supprime un host |
| `/api/tasks/logs` | GET | Récupère les logs de tâches |
| `/api/ansible/playbooks` | GET | Liste les playbooks disponibles |
| `/api/ansible/execute` | POST | Exécute un playbook |
| `/api/schedules` | GET | Liste les planifications |
| `/api/schedules` | POST | Crée une planification |
| `/api/metrics` | GET | Métriques du dashboard |
| `/api/auth/login` | POST | Authentification utilisateur |
| `/api/auth/me` | GET | Informations utilisateur courant |

---

## Dépannage

### Le bootstrap échoue avec "Permission denied"

**Cause :** Les identifiants SSH fournis sont incorrects ou l'utilisateur n'a pas les droits sudo.

**Solution :** Vérifiez le nom d'utilisateur et mot de passe. Assurez-vous que l'utilisateur peut exécuter `sudo` sur le host cible.

### Les hosts apparaissent "offline" alors qu'ils sont accessibles

**Cause :** Le health check n'a pas été exécuté ou la clé SSH n'est pas configurée.

**Solution :** Exécutez le bootstrap si ce n'est pas fait, puis lancez un Health Check.

### Les tâches restent bloquées "En cours"

**Cause :** Le processus Ansible peut être bloqué ou le host ne répond plus.

**Solution :** Vérifiez la connectivité réseau. Consultez les logs système pour plus de détails. Redémarrez le conteneur Docker si nécessaire.

### L'interface ne se met pas à jour en temps réel

**Cause :** La connexion WebSocket est interrompue.

**Solution :** Rafraîchissez la page. Vérifiez que le port WebSocket n'est pas bloqué par un firewall ou proxy.

---

## Raccourcis et Astuces

### Navigation

- Cliquez sur le logo pour revenir au Dashboard
- Utilisez les onglets du menu pour naviguer
- Le thème clair/sombre est persistant

### Productivité

- Filtrez les hosts par groupe pour des actions groupées
- Utilisez les filtres de date pour retrouver des tâches
- Exportez les logs avant de les effacer

---

*Documentation générée par Homelab Automation Dashboard v1.0*
"""