# 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.

![Tech Stack](https://img.shields.io/badge/Kotlin-7F52FF?style=flat&logo=kotlin&logoColor=white)
![Android](https://img.shields.io/badge/Android-3DDC84?style=flat&logo=android&logoColor=white)
![Jetpack Compose](https://img.shields.io/badge/Jetpack%20Compose-4285F4?style=flat&logo=jetpack-compose&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-yellow.svg)

---

## 📱 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

### � 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)
- 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>