Bruno Charest
7277342d4a
- Add extensive documentation for offline mode, sync, collections, and dashboard features - Document new Material You theming, OLED mode, and widget capabilities - Include detailed sections on metadata extraction, Markdown editor, and import/export - Update technology stack versions (Kotlin 2.0.0, Hilt 2.51.1, Retrofit 2.11.0, Room 2.6.1) - Simplify installation and compilation instructions - Add user guide with first-time setup and
263 lines
9.2 KiB
Markdown
263 lines
9.2 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
|
|
|
|
### 📚 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
|
|
- **É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
|
|
|
|
### 🏷️ 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
|
|
- Collections intelligentes avec filtres automatiques
|
|
- 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
|
|
|
|
### 🌐 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.)
|
|
- Estimation du temps de lecture
|
|
- Extraction du nom du site
|
|
|
|
### 📊 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
|
|
|
|
### 💾 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
|
|
- **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
|
|
- 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
|
|
- **Trois modes d'affichage** : Liste détaillée, grille compacte, ou vue compacte
|
|
- **Pull-to-refresh** : Actualisation du flux par glissement
|
|
|
|
---
|
|
|
|
## 🛠️ Stack Technique
|
|
|
|
| Catégorie | Technologie |
|
|
|-----------|-------------|
|
|
| **Langage** | Kotlin 2.0.0 |
|
|
| **UI** | Jetpack Compose + 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 |
|
|
| **Concurrence** | Coroutines & Flow |
|
|
| **Background work** | WorkManager 2.9.0 |
|
|
| **Stockage sécurisé** | AndroidX Security Crypto |
|
|
| **Navigation** | Navigation Compose |
|
|
| **Compilation** | Gradle 8.0+ avec KSP |
|
|
|
|
### Compatibilité
|
|
- **minSdk**: 24 (Android 7.0)
|
|
- **targetSdk**: 34 (Android 14)
|
|
- **compileSdk**: 34
|
|
- **JDK requis**: 17+
|
|
|
|
---
|
|
|
|
## 📥 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
|
|
3. Entrez votre nom d'utilisateur et mot de passe
|
|
4. L'application générera automatiquement les tokens API nécessaires
|
|
|
|
### 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
|
|
|
|
### 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
|
|
│ ├── local/ # Base de données Room
|
|
│ │ ├── dao/ # Data Access Objects
|
|
│ │ ├── entity/ # Entités Room
|
|
│ │ └── database/ # Configuration de la DB
|
|
│ ├── sync/ # Synchronisation
|
|
│ ├── export/ # Import/Export
|
|
│ └── repository/ # Implémentations des repositories
|
|
├── domain/ # Couche domaine
|
|
│ ├── model/ # Modèles métier
|
|
│ └── repository/ # Interfaces des repositories
|
|
├── presentation/ # Couche présentation
|
|
│ ├── feed/ # Écran principal
|
|
│ ├── add/ # Ajout de liens
|
|
│ ├── edit/ # Édition de liens
|
|
│ ├── tags/ # Gestion des tags
|
|
│ ├── collections/ # Collections
|
|
│ ├── dashboard/ # Tableau de bord
|
|
│ ├── settings/ # Paramètres
|
|
│ └── nav/ # Navigation
|
|
└── core/ # Utilitaires
|
|
├── di/ # Injection de dépendances
|
|
├── network/ # Configuration réseau
|
|
└── storage/ # Stockage local
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Roadmap
|
|
|
|
- [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] 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
|
|
|
|
---
|
|
|
|
## 🤝 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
|
|
- La communauté open source pour les excellentes bibliothèques utilisées
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
<sub>Fait avec ❤️ pour la communauté Shaarli</sub>
|
|
</div>
|