Bruno Charest
ec0931134c
- 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
352 lines
16 KiB
Markdown
352 lines
16 KiB
Markdown
# ShaarIt
|
||
|
||
**ShaarIt** est un client Android natif pour [Shaarli](https://github.com/shaarli/Shaarli), le gestionnaire de favoris auto-hébergé. Développé avec les technologies Android modernes, il offre une expérience mobile fluide pour gérer vos liens.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
---
|
||
|
||
## 📱 Fonctionnalités
|
||
|
||
### 🔐 Authentification
|
||
- 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 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
|
||
- Compteur d'utilisation par tag
|
||
- Filtrage rapide du flux par tag
|
||
- Tags favoris pour accès rapide
|
||
|
||
### 📁 Collections
|
||
- 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
|
||
- Édition avec prévisualisation en temps réel
|
||
- Mode édition/prévisualisation/split
|
||
- 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) 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 et du favicon
|
||
- Suggestion automatique de tags basée sur le domaine
|
||
|
||
### 📊 Tableau de Bord
|
||
- Statistiques d'utilisation (liens totaux, cette semaine, ce mois)
|
||
- Temps de lecture total et moyen
|
||
- Répartition par type de contenu
|
||
- Tags les plus utilisés
|
||
- Graphique d'activité sur 30 jours
|
||
|
||
### <20> 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
|
||
|
||
### <20>💾 Import/Export
|
||
- Export JSON (format complet avec métadonnées)
|
||
- Export CSV (compatible Excel)
|
||
- Export HTML (format Netscape/Chrome bookmarks)
|
||
- Import depuis JSON (export ShaarIt)
|
||
- Import depuis HTML (bookmarks Chrome/Firefox)
|
||
|
||
### 🔄 Synchronisation
|
||
- Synchronisation automatique en arrière-plan (WorkManager)
|
||
- Mode offline-first : modifications en attente
|
||
- Résolution de conflits intelligente
|
||
- File d'attente des opérations
|
||
|
||
### 🔗 Intégration système
|
||
- **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
|
||
- **Deep Links** : Navigation directe via `shaarit://feed`, `shaarit://add`, `shaarit://search`, etc.
|
||
- Ouverture des liens dans le navigateur par défaut
|
||
|
||
### 🎨 Interface Utilisateur
|
||
- **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)
|
||
|
||
---
|
||
|
||
## 🛠️ Stack Technique
|
||
|
||
| Catégorie | Technologie |
|
||
|-----------|-------------|
|
||
| **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.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 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+
|
||
- **Compose Compiler** : 1.5.4
|
||
|
||
---
|
||
|
||
## 📥 Installation
|
||
|
||
### Prérequis utilisateur
|
||
- Un serveur Shaarli auto-hébergé (v0.12+) avec l'API v1 activée
|
||
- Un appareil Android 7.0+ ou un émulateur
|
||
|
||
### Obtenir l'APK
|
||
|
||
#### Méthode 1 : Téléchargement direct
|
||
Récupérez le dernier APK depuis la section [Releases](../../releases).
|
||
|
||
#### Méthode 2 : Compilation depuis les sources
|
||
|
||
1. Clonez le repository :
|
||
```bash
|
||
git clone https://github.com/votre-username/ShaarIt.git
|
||
cd ShaarIt
|
||
```
|
||
|
||
2. Compilez l'APK debug :
|
||
```bash
|
||
./gradlew assembleDebug
|
||
```
|
||
|
||
L'APK sera généré dans `app/build/outputs/apk/debug/`
|
||
|
||
3. Ou compilez l'APK release (nécessite une configuration de signature) :
|
||
```bash
|
||
./gradlew assembleRelease
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 Guide d'utilisation
|
||
|
||
### Première configuration
|
||
1. Ouvrez l'application
|
||
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
|
||
- Créez des collections pour regrouper des liens par thème
|
||
- Épinglez les liens importants pour un accès rapide
|
||
|
||
### Mode hors-ligne
|
||
- Tous les liens sont stockés localement dans la base de données Room
|
||
- Les modifications sont synchronisées automatiquement quand la connexion est disponible
|
||
- Consultez vos favoris même sans connexion Internet
|
||
|
||
---
|
||
|
||
## 🏗️ Architecture
|
||
|
||
Le projet suit les principes de la **Clean Architecture** avec une séparation claire des couches :
|
||
|
||
```
|
||
├── data/ # Couche de données
|
||
│ ├── api/ # API Retrofit (ShaarliApi)
|
||
│ ├── dto/ # Data Transfer Objects (Moshi)
|
||
│ ├── local/ # Base de données Room
|
||
│ │ ├── dao/ # Data Access Objects (Link, Tag, Collection)
|
||
│ │ ├── entity/ # Entités Room + FTS4
|
||
│ │ ├── converter/ # Type converters Room
|
||
│ │ └── database/ # Configuration de la DB
|
||
│ ├── 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 (ShaarliLink, ShaarliTag, etc.)
|
||
│ ├── repository/ # Interfaces des repositories
|
||
│ └── usecase/ # Use cases (AnalyzeUrl, GenerateTags, Classify, Login)
|
||
├── presentation/ # Couche présentation
|
||
│ ├── 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 / 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/ # 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 + 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 (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…) |
|
||
|
||
---
|
||
|
||
## 🤝 Contribution
|
||
|
||
Les contributions sont les bienvenues ! N'hésitez pas à :
|
||
- Ouvrir une issue pour signaler un bug ou suggérer une fonctionnalité
|
||
- Soumettre une pull request
|
||
- Améliorer la documentation
|
||
|
||
### Signaler un bug
|
||
1. Vérifiez que le bug n'a pas déjà été signalé
|
||
2. Ouvrez une issue avec :
|
||
- Description claire du problème
|
||
- Étapes pour reproduire
|
||
- Comportement attendu vs réel
|
||
- Version Android et de l'app
|
||
- Logs si disponibles
|
||
|
||
---
|
||
|
||
## 📝 Licence
|
||
|
||
Ce projet est sous licence MIT. Voir le fichier [LICENSE](LICENSE) pour plus de détails.
|
||
|
||
---
|
||
|
||
## 🙏 Remerciements
|
||
|
||
- [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
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
<sub>Fait avec ❤️ pour la communauté Shaarli</sub>
|
||
</div>
|