docs: Update comprehensive documentation with AI features, health checks, and architecture improvements

- Document automatic token verification on startup and note:// prefix for Markdown notes - Add extensive AI capabilities section (Gemini integration, auto-tagging, content classification, multi-model fallback) - Document link health monitoring system with dead link detection and exclusion features - Add file sharing support (Markdown/text files) and deep links documentation - Update technology
2026-02-10 21:15:30 -05:00
parent c8a9e6653b
commit ec0931134c
39 changed files with 4717 additions and 308 deletions
@@ -15,16 +15,19 @@
 - Connexion sécurisée à votre instance Shaarli auto-hébergée (API v1)
 - Stockage chiffré des tokens JWT et secrets API via `EncryptedSharedPreferences`
 - Génération automatique de tokens JWT avec algorithme HS512
+- Vérification automatique du token au démarrage (skip login si valide)

 ### 📚 Gestion des Favoris
 - **Flux infini** : Défilement continu avec chargement progressif (Paging 3)
 - **Recherche avancée** : Recherche locale avec FTS4 (full-text search) et filtrage par tags
 - **Mode hors-ligne** : Consultation et modification des liens même sans connexion
 - **Ajout rapide** : Création de liens privés/publics avec description, tags et extraction automatique de métadonnées
+- **Notes Markdown** : Création de notes enrichies (pas uniquement des URLs) avec le préfixe `note://`
 - **Édition** : Modification complète des liens existants avec éditeur Markdown
 - **Suppression** : Gestion facile des favoris avec file d'attente de sync
 - **Détection des doublons** : Alerte lors de l'ajout d'un lien existant avec option de mise à jour
- **Liens épinglés** : Mise en avant des liens importants
+- **Liens épinglés** : Mise en avant des liens importants avec écran dédié
+- **Vérification santé des liens** : Détection automatique des liens morts (Dead Links) en arrière-plan

 ### 🏷️ Gestion des Tags
 - Vue dédiée pour parcourir tous les tags
@@ -33,8 +36,9 @@
 - Tags favoris pour accès rapide

 ### 📁 Collections
- Organisation des liens en collections
- Collections intelligentes avec filtres automatiques
+- Organisation des liens en collections manuelles ou intelligentes
+- Collections intelligentes avec filtres automatiques (basées sur les tags)
+- Synchronisation des collections via le serveur Shaarli
 - Vue grille adaptative pour les collections

 ### 📝 Éditeur Markdown
@@ -43,11 +47,19 @@
 - Mode lecture focus sans distraction
 - Barre d'outils de formatage

+### 🤖 Intelligence Artificielle (Google Gemini)
+- **Analyse IA d'URL** : Extraction intelligente du titre, description et tags via Gemini
+- **Suggestions de tags IA** : Génération automatique de tags pertinents
+- **Classification de contenu** : Détection automatique du type (Article, Vidéo, Tutorial, Repository)
+- **Fallback multi-modèles** : Essai automatique de plusieurs modèles Gemini (2.5 Flash Lite → 1.5 Flash)
+- **Classification en lot** : Scan et classification de tous les bookmarks existants
+
 ### 🌐 Extraction de Métadonnées
- Extraction automatique des OpenGraph (titre, description, image)
- Détection du type de contenu (article, vidéo, image, audio, code, etc.)
+- Extraction automatique des OpenGraph (titre, description, image) via JSoup
+- Détection du type de contenu (article, vidéo, image, audio, code, repository, social, etc.)
 - Estimation du temps de lecture
- Extraction du nom du site
+- Extraction du nom du site et du favicon
+- Suggestion automatique de tags basée sur le domaine

 ### 📊 Tableau de Bord
 - Statistiques d'utilisation (liens totaux, cette semaine, ce mois)
@@ -56,7 +68,15 @@
 - Tags les plus utilisés
 - Graphique d'activité sur 30 jours

-### 💾 Import/Export
+### � Vérification des Liens (Health Check)
+- Détection automatique des liens morts via WorkManager (toutes les 12h)
+- Système de seuil : 3 échecs consécutifs avant de marquer un lien comme « mort »
+- Filtrage intelligent (exclusion des notes, réseau local, IPs privées)
+- Vérification manuelle à la demande depuis les paramètres
+- Écran dédié de gestion des liens morts
+- Exclusion de liens spécifiques du health check
+
+### �💾 Import/Export
 - Export JSON (format complet avec métadonnées)
 - Export CSV (compatible Excel)
 - Export HTML (format Netscape/Chrome bookmarks)
@@ -70,20 +90,21 @@
 - File d'attente des opérations

 ### 🔗 Intégration système
- **Share Intent Android** : Sauvegarde rapide depuis n'importe quelle app
+- **Share Intent Android** : Sauvegarde rapide depuis n'importe quelle app (URLs et fichiers texte/Markdown)
+- **Partage de fichiers** : Import de fichiers `.md`, `.txt` directement comme notes Shaarli
 - **App Shortcuts** : Accès rapide via appui long sur l'icône (Ajouter, Aléatoire, Rechercher, Collections)
 - **Quick Settings Tile** : Tuile pour ajouter rapidement un lien
- **Widget** : Widget d'accueil affichant les liens récents
+- **Deep Links** : Navigation directe via `shaarit://feed`, `shaarit://add`, `shaarit://search`, etc.
 - Ouverture des liens dans le navigateur par défaut

 ### 🎨 Interface Utilisateur
- **Material You (Monet)** : Couleurs dynamiques basées sur le fond d'écran (Android 12+)
- **Mode OLED** : Noir pur pour les écrans AMOLED
- **Design premium** : Thème sombre moderne avec dégradés
- **Material Design 3** : Composants UI natifs Android
- **Animations fluides** : Transitions et effets visuels
+- **15 thèmes sombres** : ShaarIt, GitHub, Linear, Spotify, Notion, Discord, Dracula, One Dark Pro, Tokyo Night, Nord, Night Owl, Anthracite, Cyberpunk, Navy Élégance, Tons Terreux
+- **Design premium** : Composants glassmorphism avec effets visuels
+- **Material Design 3** : Composants UI natifs Jetpack Compose
+- **Skeleton Loading** : Chargement élégant avec shimmer effect
 - **Trois modes d'affichage** : Liste détaillée, grille compacte, ou vue compacte
 - **Pull-to-refresh** : Actualisation du flux par glissement
+- **Edge-to-Edge** : Support des insets système (barre de statut, navigation)

 ---

@@ -91,24 +112,30 @@

 | Catégorie | Technologie |
 |-----------|-------------|
-| **Langage** | Kotlin 2.0.0 |
-| **UI** | Jetpack Compose + Material Design 3 |
+| **Langage** | Kotlin 1.9.20 |
+| **UI** | Jetpack Compose (BOM 2023.08) + Material Design 3 |
 | **Architecture** | Clean Architecture + MVVM |
-| **Injection de dépendances** | Dagger Hilt 2.51.1 |
-| **Réseau** | Retrofit 2.11.0 + Moshi 1.15.1 + OkHttp 4.12.0 |
-| **Base de données locale** | Room 2.6.1 |
-| **Pagination** | Paging 3 |
+| **Injection de dépendances** | Dagger Hilt 2.48.1 |
+| **Réseau** | Retrofit 2.9.0 + Moshi 1.15.0 + OkHttp 4.12.0 |
+| **Base de données locale** | Room 2.6.1 (avec FTS4) |
+| **Pagination** | Paging 3 (3.2.1) |
 | **Concurrence** | Coroutines & Flow |
 | **Background work** | WorkManager 2.9.0 |
 | **Stockage sécurisé** | AndroidX Security Crypto |
-| **Navigation** | Navigation Compose |
-| **Compilation** | Gradle 8.0+ avec KSP |
+| **Navigation** | Navigation Compose 2.7.6 |
+| **Images** | Coil 2.6.0 |
+| **Markdown** | compose-markdown 0.4.1 |
+| **HTML Parsing** | JSoup 1.17.1 |
+| **IA** | Google Gemini AI SDK 0.9.0 |
+| **Sérialisation** | Kotlin Serialization 1.6.2 |
+| **Compilation** | AGP 8.13.2 + KSP 1.9.20 |

 ### Compatibilité
- **minSdk**: 24 (Android 7.0)
- **targetSdk**: 34 (Android 14)
- **compileSdk**: 34
- **JDK requis**: 17+
+- **minSdk** : 24 (Android 7.0)
+- **targetSdk** : 34 (Android 14)
+- **compileSdk** : 34
+- **JDK requis** : 17+
+- **Compose Compiler** : 1.5.4

 ---

@@ -149,14 +176,27 @@ L'APK sera généré dans `app/build/outputs/apk/debug/`

 ### Première configuration
 1. Ouvrez l'application
-2. Entrez l'URL de votre instance Shaarli
+2. Entrez l'URL de votre instance Shaarli (ex: `https://monserveur.com/shaarli`)
 3. Entrez votre nom d'utilisateur et mot de passe
 4. L'application générera automatiquement les tokens API nécessaires
+5. *(Optionnel)* Configurez votre clé API Gemini dans Paramètres pour l'auto-tagging IA

 ### Ajouter un lien
 - **Via l'app** : Appuyez sur le bouton + et entrez l'URL
 - **Via le partage Android** : Partagez n'importe quelle URL vers ShaarIt depuis n'importe quelle app
 - **Via Quick Settings** : Ajoutez la tuile ShaarIt dans vos paramètres rapides
+- **Fichier Markdown** : Partagez un fichier `.md` ou `.txt` pour l'importer comme note
+
+### Créer une note
+- Sur l'écran d'ajout, basculez en mode **Note** (au lieu de Bookmark)
+- Rédigez le titre et le contenu en Markdown
+- La note sera sauvegardée sur votre instance Shaarli avec un identifiant unique
+
+### Intelligence Artificielle
+1. Obtenez une clé API sur [Google AI Studio](https://aistudio.google.com/)
+2. Allez dans **Paramètres** → **Clé API Gemini** et entrez votre clé
+3. Lors de l'ajout d'un lien, appuyez sur le bouton IA pour analyser automatiquement l'URL
+4. L'IA remplira le titre, la description et suggérera des tags pertinents

 ### Organiser vos liens
 - Utilisez les tags pour catégoriser vos liens
@@ -176,52 +216,98 @@ Le projet suit les principes de la **Clean Architecture** avec une séparation c

 ```
 ├── data/                    # Couche de données
-│   ├── api/                # API Retrofit
+│   ├── api/                # API Retrofit (ShaarliApi)
+│   ├── dto/                # Data Transfer Objects (Moshi)
 │   ├── local/              # Base de données Room
-│   │   ├── dao/           # Data Access Objects
-│   │   ├── entity/        # Entités Room
+│   │   ├── dao/           # Data Access Objects (Link, Tag, Collection)
+│   │   ├── entity/        # Entités Room + FTS4
+│   │   ├── converter/     # Type converters Room
 │   │   └── database/      # Configuration de la DB
-│   ├── sync/              # Synchronisation
-│   ├── export/            # Import/Export
-│   └── repository/        # Implémentations des repositories
+│   ├── mapper/             # Mappers DTO ↔ Entity ↔ Domain
+│   ├── metadata/           # Extraction métadonnées (JSoup/OpenGraph)
+│   ├── paging/             # PagingSource réseau
+│   ├── sync/               # SyncManager + ConflictResolver + SyncWorker
+│   ├── worker/             # LinkHealthCheckWorker
+│   ├── export/             # BookmarkExporter (JSON, CSV, HTML)
+│   └── repository/         # Implémentations (Link, Auth, Gemini)
 ├── domain/                 # Couche domaine
-│   ├── model/             # Modèles métier
-│   └── repository/        # Interfaces des repositories
+│   ├── model/             # Modèles métier (ShaarliLink, ShaarliTag, etc.)
+│   ├── repository/        # Interfaces des repositories
+│   └── usecase/           # Use cases (AnalyzeUrl, GenerateTags, Classify, Login)
 ├── presentation/           # Couche présentation
-│   ├── feed/              # Écran principal
-│   ├── add/               # Ajout de liens
+│   ├── feed/              # Écran principal + vues (List, Grid, Compact)
+│   ├── add/               # Ajout de liens / notes
 │   ├── edit/              # Édition de liens
+│   ├── auth/              # Écran de connexion
 │   ├── tags/              # Gestion des tags
 │   ├── collections/       # Collections
-│   ├── dashboard/         # Tableau de bord
-│   ├── settings/          # Paramètres
-│   └── nav/               # Navigation
+│   ├── dashboard/         # Tableau de bord / statistiques
+│   ├── deadlinks/         # Gestion des liens morts
+│   ├── pinned/            # Liens épinglés
+│   ├── settings/          # Paramètres (sync, export, IA, thèmes)
+│   ├── help/              # Écran d'aide
+│   └── nav/               # Navigation (NavGraph + Deep Links)
+├── ui/                     # Composants UI réutilisables
+│   ├── components/        # GlassCard, TagChip, MarkdownEditor, SkeletonLoader
+│   └── theme/             # 15 thèmes + typographie + préférences
+├── service/                # AddLinkTileService (Quick Settings)
 └── core/                   # Utilitaires
-    ├── di/                # Injection de dépendances
-    ├── network/           # Configuration réseau
-    └── storage/           # Stockage local
+    ├── di/                # Modules Hilt (App, Database, Network, Repository)
+    ├── network/           # AuthInterceptor + HostSelectionInterceptor
+    ├── storage/           # TokenManager (EncryptedSharedPreferences)
+    └── util/              # JwtGenerator
 ```

 ---

 ## 🚀 Roadmap

+### Complété ✅
 - [x] Synchronisation en arrière-plan avec WorkManager
- [x] Mode hors-ligne avec Room
- [x] Éditeur Markdown
- [x] Extraction de métadonnées OpenGraph
- [x] Collections d'organisation
- [x] Liens épinglés
- [x] Widget d'accueil
- [x] App Shortcuts
+- [x] Mode hors-ligne avec Room + architecture offline-first
+- [x] Éditeur Markdown (édition + prévisualisation + split)
+- [x] Extraction de métadonnées OpenGraph (JSoup)
+- [x] Collections manuelles et intelligentes
+- [x] Liens épinglés avec écran dédié
+- [x] App Shortcuts + Deep Links (`shaarit://`)
 - [x] Quick Settings Tile
- [x] Tableau de bord analytique
- [x] Import/Export
- [x] Material You (Monet)
- [ ] Recherche avancée avec filtres multiples
- [ ] Suggestions de tags par IA
- [ ] Mode lecture sans distraction pour les articles
- [ ] Partage de collections
+- [x] Tableau de bord analytique (statistiques, graphiques)
+- [x] Import/Export (JSON, CSV, HTML Netscape)
+- [x] 15 thèmes sombres premium
+- [x] Intelligence Artificielle (Google Gemini) — auto-tagging, analyse d'URL, classification
+- [x] Recherche FTS4 (full-text search) + filtres multi-tags
+- [x] Détection et gestion des liens morts (Health Check)
+- [x] Support des notes Markdown (pas uniquement des URLs)
+- [x] Partage de fichiers `.md` / `.txt` via Share Intent
+- [x] Skeleton Loading (shimmer effect)
+- [x] Résolution de conflits de synchronisation
+- [x] Synchronisation des collections via le serveur Shaarli
+- [x] Optimisations de performance — R8/ProGuard, Baseline Profiles, sync incrémentale
+- [x] Recherche FTS4 activée dans le repository — Moteur FTS4 intégré dans `LinkRepositoryImpl`
+- [x] Migrations Room explicites — `MIGRATION_4_5` explicite + fallback ciblé pour v1-v3
+
+### Prochaines étapes 🔜
+- [ ] Mode lecture sans distraction (Reader Mode) pour les articles
+- [ ] Widget d'accueil interactif (Glance)
+- [ ] Partage de collections entre utilisateurs
+- [ ] Support multi-instances Shaarli
+- [ ] Verrouillage biométrique
+- [ ] Rappels de lecture (« Lire plus tard » avec notifications)
+- [ ] Voice Input dans la recherche et l'ajout de lien
+- [ ] Adaptive Layouts pour tablettes et foldables
+- [ ] Thème clair et Material You (Monet) dynamique sur Android 12+
+
+---
+
+## 📄 Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Performance & UX Optimale](docs/PERFORMANCE_ET_UX_OPTIMALE.md) | Analyse de performance complète, 24 optimisations identifiées, plan d'action priorisé |
+| [Analyse et Améliorations](docs/ANALYSE_ET_AMELIORATIONS.md) | Propositions d'améliorations fonctionnelles et architecturales |
+| [Rapport d'Audit v2](docs/RAPPORT_AMELIORATION_v2.md) | Audit UX « Next Level » — micro-interactions, IA, ergonomie |
+| [Instructions de Build Release](docs/RELEASE_BUILD.md) | Guide de création du keystore, signature et build release |
+| [Roadmap Prochaines Fonctionnalités](docs/ROADMAP_PROCHAINES_FONCTIONNALITES.md) | Analyse détaillée des 9 fonctionnalités à implémenter (Reader Mode, Widget, Biométrie, Material You…) |

 ---

@@ -253,6 +339,9 @@ Ce projet est sous licence MIT. Voir le fichier [LICENSE](LICENSE) pour plus de

 - [Shaarli](https://github.com/shaarli/Shaarli) - Le projet original de gestionnaire de favoris
 - [Jetpack Compose](https://developer.android.com/jetpack/compose) - Framework UI moderne d'Android
+- [Google Gemini](https://ai.google.dev/) - IA générative pour l'enrichissement intelligent
+- [JSoup](https://jsoup.org/) - Parsing HTML pour l'extraction de métadonnées
+- [Coil](https://coil-kt.github.io/coil/) - Chargement d'images optimisé pour Compose
 - La communauté open source pour les excellentes bibliothèques utilisées

 ---