chore: Remove outdated documentation files (analysis and build instructions)

This commit is contained in:
2026-02-09 09:48:25 -05:00
parent 02c7300c3b
commit 80ab3009aa
25 changed files with 1189 additions and 241 deletions
+426
View File
@@ -0,0 +1,426 @@
# Analyse et Améliorations - ShaarIt
## 📋 Résumé de l'Analyse du Projet
### Architecture Actuelle
**ShaarIt** est un client Android moderne pour Shaarli développé avec les meilleures pratiques Android :
```mermaid
graph TB
subgraph "Présentation [Jetpack Compose]"
A[FeedScreen] --> B[AddLinkScreen]
A --> C[EditLinkScreen]
A --> D[TagsScreen]
E[LoginScreen] --> A
end
subgraph "Domaine [Clean Architecture]"
F[LinkRepository]
G[AuthRepository]
H[UseCases]
end
subgraph "Data [API + Local]"
I[ShaarliApi - Retrofit]
J[LinkPagingSource]
K[TokenManager - Crypto]
end
A --> F
F --> I
I --> L[(Shaarli Server)]
```
### Stack Technique
| Couche | Technologie |
|--------|-------------|
| **Langage** | Kotlin 1.9.20 |
| **UI** | Jetpack Compose + Material Design 3 |
| **Architecture** | Clean Architecture + MVVM |
| **DI** | Dagger Hilt 2.48 |
| **Réseau** | Retrofit 2.9 + Moshi + OkHttp |
| **Pagination** | Paging 3 |
| **Stockage** | EncryptedSharedPreferences |
| **Async** | Coroutines & Flow |
### Fonctionnalités Existantes
1. **Authentification sécurisée** - JWT avec stockage chiffré
2. **Gestion des liens** - CRUD complet avec pagination infinie
3. **Recherche avancée** - Par termes et filtres multi-tags
4. **Intégration système** - Share Intent Android
5. **UI premium** - Thème sombre avec glassmorphism
6. **Détection de doublons** - Alertes lors de l'ajout
7. **Modes d'affichage** - Liste, grille, compact
---
## 🚀 Propositions d'Améliorations
### 1. Gestion des Notes Markdown Natif
**Problème actuel** : Shaarli supporte les notes markdown mais l'app ne les affiche pas de manière enrichie.
**Améliorations proposées** :
| Fonctionnalité | Description | Priorité |
|----------------|-------------|----------|
| **Éditeur Markdown WYSIWYG** | Éditeur visuel avec preview temps réel | Haute |
| **Rendu Markdown enrichi** | Support complet : tableaux, math (KaTeX), diagrammes Mermaid | Haute |
| **Mode lecture focus** | Vue distraction-free pour lire les longues notes | Moyenne |
| **Export PDF/HTML** | Générer des documents depuis les notes | Moyenne |
| **Templates de notes** | Templates pré-définis (meeting, todo, journal) | Basse |
**Implementation suggérée** :
```kotlin
// Nouveau composant
@Composable
fun MarkdownEditor(
value: String,
onValueChange: (String) -> Unit,
mode: EditorMode = EditorMode.SPLIT // EDIT, PREVIEW, SPLIT
)
```
---
### 2. Système de Collections/Workspaces
**Concept** : Organiser les liens en collections thématiques au-delà des simples tags.
**Fonctionnalités** :
- **Collections intelligentes** : Requêtes sauvegardées (ex: "tag:work AND tag:urgent")
- **Workspaces contextuels** : Séparer vie pro/perso/projets
- **Collections partagées** : Synchroniser certaines collections avec d'autres utilisateurs Shaarli
- **Collection aléatoire** : "Lire plus tard" avec sélection aléatoire
**UI proposée** :
```
┌─────────────────────────────────────┐
│ 📁 Mes Collections │
├─────────────────────────────────────┤
│ 💼 Work [42 items] ▸ │
│ 🏠 Personal [128 items] ▸ │
│ 📚 Reading [15 unread] ▸ │
│ ⭐ Favorites [23 items] ▸ │
│ 🔥 Hot Today [Auto] ▸ │
└─────────────────────────────────────┘
```
---
### 3. Intelligence et Automatisation
#### 3.1 Extraction Métadonnées Intelligente
```kotlin
// Service d'enrichissement automatique
interface LinkEnrichmentService {
suspend fun enrich(url: String): EnrichedMetadata
}
data class EnrichedMetadata(
val title: String,
val description: String,
val thumbnailUrl: String?,
val siteName: String?,
val readingTime: Int?, // minutes estimées
val contentType: ContentType, // ARTICLE, VIDEO, PODCAST, PAPER
val suggestedTags: List<String>, // ML-based suggestions
val summary: String? // Auto-résumé avec AI locale
)
```
**Fonctionnalités** :
- **Détection automatique** du type de contenu (article, vidéo, papier scientifique)
- **Extraction de thumbnail** et preview visuelle
- **Suggestion de tags** basée sur le contenu analysé
- **Estimation du temps de lecture**
- **Résumé automatique** via modèle ML local (Gemini Nano, ML Kit)
#### 3.2 Rappels et Suivi de Lecture
| Feature | Description |
|---------|-------------|
| **Read Later avancé** | Rappels programmables ("Relire dans 3 jours") |
| **Suivi de progression** | Marquer comme "en cours de lecture" |
| ** streaks de lecture** | Gamification pour lire les liens sauvegardés |
| **Archivage automatique** : | Déplacer les vieux liens non lus après X jours |
---
### 4. Recherche et Découverte Avancées
#### 4.1 Moteur de Recherche Full-Text
**Améliorations** :
- **Recherche sémantique** : Trouver des liens par concept, pas juste par mots-clés
- **Filtres temporels** : "Cette semaine", "Le mois dernier", "Avant 2023"
- **Recherche dans le contenu** : Indexer le contenu des pages web (via service externe ou Poche/Readwise)
- **Historique de recherche** : Suggestions basées sur les recherches passées
- **Recherches sauvegardées** : Alertes sur nouveaux liens correspondant
#### 4.2 Visualisations et Analytics
```mermaid
graph LR
A[Dashboard Analytics] --> B[Graphique d'activité]
A --> C[Tag cloud interactive]
A --> D[Tendances temporelles]
A --> E[Sources les plus sauvegardées]
A --> F[Réseau de connexions entre liens]
```
**Idées de visualisations** :
- Timeline visuelle des ajouts
- Graph de relations entre tags
- Carte des domaines les plus sauvegardés
- Statistiques d'utilisation hebdomadaires/mensuelles
---
### 5. Synchronisation et Offline-First
#### 5.1 Architecture Offline
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ UI Layer │────▶│ Repository │────▶│ Room DB │
│ Compose │ │ SyncEngine │ │ Local Cache │
└──────────────┘ └──────┬───────┘ └──────────────┘
│
▼
┌──────────────┐
│ Shaarli API │
│ REST API │
└──────────────┘
```
**Fonctionnalités** :
- **Cache local Room** : Accès instantané aux liens même hors-ligne
- **File d'attente de sync** : Ajouter/modifier hors-ligne, synchroniser automatiquement
- **Résolution de conflits** : UI pour gérer les conflits de modification
- **Sync sélective** : Choisir quelles collections synchroniser
- **Compression des données** : Sync delta pour économiser la bande passante
#### 5.2 Multi-Instance Support
| Feature | Description |
|---------|-------------|
| **Multi-comptes** | Gérer plusieurs instances Shaarli (perso, travail, projet) |
| **Switch rapide** | Changer de compte en 1 tap |
| **Vue unifiée** | Voir tous les liens de toutes les instances (optionnel) |
| **Migration d'instance** | Transférer des liens entre instances |
---
### 6. Intégrations et API
#### 6.1 Services Tierces
```kotlin
interface ThirdPartyIntegration {
// Pocket/Instapaper - Import/export
// Raindrop.io - Sync bidirectionnel
// Notion - Export vers base de données
// Obsidian - Export markdown avec liens
// Readwise - Envoi vers Reader
}
```
**Intégrations souhaitées** :
1. **Import/Export** : Pocket, Delicious, Browser bookmarks (HTML)
2. **Sync bidirectionnelle** : Raindrop.io, Pinboard
3. **Export vers** : Notion, Obsidian, Logseq
4. **Services de lecture** : Envoi vers Kindle, Readwise Reader
5. **Webhook personnalisés** : Déclencher des actions IFTTT/Zapier
#### 6.2 Widgets et Shortcuts
| Type | Fonctionnalité |
|------|----------------|
| **Home Widget** | Derniers liens ajoutés, quick-add, aléatoire |
| **Quick Settings Tile** | Ajouter le presse-papiers en 1 tap |
| **App Shortcuts** | "Ajouter lien", "Rechercher", "Aléatoire" |
| **Wear OS** | Vue minimaliste, voice input pour ajout rapide |
---
### 7. Personnalisation et Accessibilité
#### 7.1 Thèmes et Apparence
- **Thèmes dynamiques** : Material You (Monet) sur Android 12+
- **Mode OLED pur** : Noir véritable pour économiser batterie
- **Taille de texte adaptable** : Accessibilité améliorée
- **Police personnalisable** : Serif pour lecture longue, monospace pour code
- **Animations réduites** : Mode accessibilité
#### 7.2 Gestion des Données
| Feature | Description |
|---------|-------------|
| **Backup cloud** | Export chiffré vers Google Drive/Dropbox |
| **Export JSON/XML** | Sauvegarde complète avec métadonnées |
| **Historique des modifications** | Versioning des liens modifiés |
| **Corbeille** | Restauration des liens supprimés (30 jours) |
---
### 8. Fonctionnalités Avancées de Contenu
#### 8.1 Support Média Étendu
```kotlin
sealed class LinkContent {
data class Article(val url: String, val content: String)
data class Video(
val platform: VideoPlatform, // YOUTUBE, VIMEO, PEERTUBE
val duration: Duration?,
val transcriptUrl: String?
)
data class Podcast(
val episodeInfo: EpisodeInfo,
val audioUrl: String
)
data class ScientificPaper(
val doi: String?,
val authors: List<String>,
val abstract: String,
val pdfUrl: String?
)
}
```
**Fonctionnalités** :
- **Lecteur intégré vidéo** : Mini-player pour vidéos YouTube
- **Extraction PDF** : Viewer intégré pour les PDF sauvegardés
- **Podcast player** : Lecture directe avec bookmarks temporels
- **Galerie d'images** : Vue grille pour liens image (Pinterest-style)
#### 8.2 Collaboration et Partage
| Feature | Description |
|---------|-------------|
| **Liens publics** | Générer une URL publique pour un lien privé |
| **Commentaires** | Annoter les liens avec notes personnelles |
| **Partage sécurisé** : | Expiration des liens partagés |
| **Collaboration** : | Partager une collection avec édition |
---
### 9. Sécurité et Confidentialité
#### 9.1 Fonctionnalités de Sécurité
- **Verrouillage biométrique** : FaceID/Fingerprint pour accès
- **Mode privé** : Section chiffrée séparée pour liens sensibles
- **Session management** : Historique des connexions, révocation à distance
- **Audit log** : Historique de toutes les actions
#### 9.2 Confidentialité
| Feature | Description |
|---------|-------------|
| **Anonymisation** | Masquer les métadonnées d'origine |
| **Proxy intégré** | Prévisualisation sans révéler l'IP |
| **Auto-expiration** | Suppression automatique après durée définie |
| **Zero-knowledge** | Chiffrement client-side des descriptions |
---
### 10. Roadmap Priorisée
```mermaid
gantt
title Roadmap ShaarIt - Améliorations
dateFormat YYYY-MM
section Phase 1 - Fondations
Room Database (Offline) :done, p1_1, 2026-02, 4w
Markdown Rendering :active, p1_2, 2026-02, 3w
Amélioration Recherche :p1_3, 2026-03, 3w
section Phase 2 - Intelligence
Métadonnées Auto-Extract :p2_1, 2026-04, 4w
Suggestions Tags ML :p2_2, after p2_1, 3w
Collections/Workspaces :p2_3, 2026-05, 4w
section Phase 3 - Intégrations
Widgets & Shortcuts :p3_1, 2026-06, 2w
Import/Export Services :p3_2, 2026-06, 4w
Multi-Instance Support :p3_3, 2026-07, 3w
section Phase 4 - Avancé
Sync Bidirectionnelle :p4_1, 2026-08, 4w
Analytics Dashboard :p4_2, 2026-09, 3w
Wear OS App :p4_3, 2026-10, 4w
```
---
## 💡 Recommandations Immédiates
### Top 5 Priorités (Quick Wins)
1. **Éditeur Markdown Rich** - Impact utilisateur élevé, effort moyen
2. **Base de données Room** - Fondation pour offline et performances
3. **Widgets Android** - Visibilité app et accessibilité rapide
4. **Extraction métadonnées** - Auto-complétion intelligente des liens
5. **Mode lecture focus** - Amélioration UX majeure pour les notes
### Architecture Proposée pour Room
```kotlin
@Entity(tableName = "links")
data class CachedLink(
@PrimaryKey val id: Int,
val url: String,
val title: String,
val description: String,
val tags: List<String>,
val isPrivate: Boolean,
val createdAt: Long,
val updatedAt: Long,
val syncStatus: SyncStatus // SYNCED, PENDING_CREATE, PENDING_UPDATE, PENDING_DELETE
)
@Entity(tableName = "link_content")
data class LinkContentEntity(
@PrimaryKey val linkId: Int,
val thumbnailUrl: String?,
val readingTime: Int?,
val contentType: String,
val cachedHtml: String?, // Pour offline reading
val extractedText: String? // Pour recherche full-text
)
```
---
## 📊 Synthèse
### Forces Actuelles
- Architecture moderne et maintenable
- UI premium avec Material Design 3
- Sécurité robuste (chiffrement, JWT)
- Intégration système Android native
### Opportunités d'Amélioration
- **Offline-first** : Sync robuste avec gestion de conflits
- **Markdown natif** : Exploiter pleinement le support Shaarli
- **Intelligence** : ML local pour suggestions et enrichissement
- **Écosystème** : Intégrations avec outils de productivité
- **Accessibilité** : Widgets, raccourcis, multi-plateformes
### Impact Utilisateur Attendu
Avec ces améliorations, ShaarIt deviendrait :
- **Le meilleur client Android** pour Shaarli
- **Un outil de productivité complet** (pas juste un bookmark manager)
- **Une alternative viable** à Pocket, Raindrop.io, Notion Web Clipper
---
*Document créé le 28 janvier 2026*
*Analyse basée sur le code source ShaarIt v1.0*
+94
View File
@@ -0,0 +1,94 @@
# 🚀 ShaarIt - Rapport d'Audit & Plan d'Action "Next Level"
Ce document récapitule l'analyse de l'état actuel du projet et propose une série d'améliorations ciblées pour faire passer l'application d'un "excellent projet" à un "produit d'exception".
**Date de l'audit** : 31 Janvier 2026
**Version ciblée** : Codebase actuelle (v1.0-dev)
---
## 1. 📊 État des Lieux
Le projet est techniquement très solide et suit les standards modernes Android :
- **Architecture** : Clean Architecture (Presentation, Domain, Data) avec Hilt.
- **UI** : Jetpack Compose pur, Material 3, Thème personnalisé "Premium" (Cyan/DeepNavy).
- **Offline-first** : Implémentation Room complète avec SyncManager robuste.
- **Intelligence** : Intégration de Gemini (Flash 2.5) pour l'auto-tagging et l'extraction de métadonnées.
- **Fonctionnalités** : Support Markdown (éditeur + rendu), Filtres avancés, Collections.
**Verdict** : Les bases sont excellentes. "Le niveau supérieur" ne réside pas dans la refonte, mais dans le **raffinement (Polish)** et l'**Expérience Utilisateur (UX)**.
---
## 2. 💎 Propositions d'Améliorations (Le "Next Level")
Pour atteindre un niveau de qualité "Apple-like" ou "Top Tier SaaS", voici les axes prioritaires :
### 🎨 Look & Feel (Wow Factor)
| Amélioration | Description | Impact |
|--------------|-------------|--------|
| **Micro-Interactions** | Ajouter du retour haptique (`HapticFeedback`) lors des actions clés (Long press, Toggle, Save). | ⭐⭐⭐⭐⭐ (Ergonomie) |
| **Hero Transitions** | Animer la transition entre la liste et le détail d'un lien (l'image s'agrandit, le titre glisse). | ⭐⭐⭐⭐ (Visuel) |
| **Skeleton Loading** | Remplacer les indicateurs de chargement circulaires par des "Skeletons" (formes grises pulsantes) pour un rendu plus fluide. | ⭐⭐⭐⭐ (Perçu) |
| **Confetti/Feedback** | Une animation subtile lors de l'ajout réussi d'un lien ou de la complétion d'une tâche (Inbox Zero). | ⭐⭐⭐ (Plaisir) |
| **Adaptive Layouts** | Optimiser pour tablettes/foldables (Navigation Rail au lieu de Drawer) si l'écran est large. | ⭐⭐⭐ (Premium) |
### 🧠 Intelligence Artificielle (Raffinement)
L'implémentation actuelle de Gemini est fonctionnelle mais peut être optimisée :
1. **Nettoyage du Code** :
- *Problème* : `GeminiRepositoryImpl` utilise `HttpURLConnection` pour vérifier les liens.
- *Solution* : Utiliser le client `OkHttp` déjà injecté pour bénéficier du Connection Pooling et de la cohérence.
2. **Mode "Offline AI"** :
- *Idée* : Si Gemini échoue (réseau/quota), utiliser **ML Kit** (local) pour extraire du texte ou catégoriser basiquement.
3. **Prompt Engineering Contextuel** :
- Adapter le prompt selon que l'URL est une vidéo YouTube ou github (déjà partiellement fait, mais peut être affiné pour extraire les chapitres YouTube).
### ⚡ Performance & Technique
1. **Baseline Profiles** :
- Générer des Baseline Profiles pour réduire le temps de démarrage (très important pour une app de "capture rapide").
2. **Optimisation Images (Coil)** :
- S'assurer que les thumbnails sont redimensionnés par Coil en mémoire pour éviter d'allouer des bitmaps 4K pour des petites cartes.
3. **Strict Mode & Leaks** :
- Intégrer LeakCanary en debug pour s'assurer qu'aucune fuite de mémoire ne ralentit l'app sur la durée.
### 📱 Ergonomie & Intégration Système
1. **Quick Settings Tile** :
- Ajouter une tuile dans les réglages rapides d'Android pour "Ajouter le lien du presse-papier" sans ouvrir l'app.
2. **Voice Input** :
- Ajouter un bouton micro dans la barre de recherche et l'ajout de lien.
3. **Widget Interactif** :
- Si pas encore fait, le widget doit permettre de marquer un lien comme "Lu" ou de le copier sans ouvrir l'app.
4. **Share Target Optimisé** :
- Faire apparaître l'écran d'ajout *immédiatement* lors du partage depuis Chrome.
---
## 3. 📝 Plan d'Action Recommandé
Voici les tâches concrètes à intégrer :
### Priorité 1 : UX "Delight" (Rapide & Visible)
- [ ] **Haptics** : Ajouter `LocalHapticFeedback.current` dans `FeedScreen` et `LinkItem`.
- [ ] **Animations** : Implémenter `AnimatedContent` pour les changements d'état (filtres, recherche).
- [ ] **Refactor Réseau** : Remplacer `HttpURLConnection` par `OkHttp` dans `GeminiRepositoryImpl`.
### Priorité 2 : Intelligence & Fonctionnel
- [ ] **Voice Search** : Ajouter la reconnaissance vocale dans la SearchBar.
- [ ] **Quick Tile** : Créer un `TileService` pour l'ajout rapide depuis le clipboard.
### Priorité 3 : Performance & Solidité
- [ ] **Baseline Profiles** : Configurer le module benchmark.
- [ ] **Tests UI** : Ajouter des tests instrumentés pour les parcours critiques (Ajout lien -> List).
---
## 4. 💡 Idée Bonus : "The ShaarIt Daily"
Créer une vue "Daily Briefing" qui utilise Gemini pour :
- Résumer les 3 articles les plus intéressants ajoutés hier.
- Suggérer 1 "vieux lien" oublié à redécouvrir.
Ce serait une fonctionnalité "Signature" unique à votre application.
+94
View File
@@ -0,0 +1,94 @@
# ShaarIt - Instructions de Build Release
## Prérequis
- Android Studio ou Gradle CLI
- Java JDK 8+ installé
## Création du Keystore (à faire une seule fois)
### Via ligne de commande:
```bash
keytool -genkey -v -keystore shaarit-release.keystore -alias shaarit -keyalg RSA -keysize 2048 -validity 10000
```
### Informations à fournir:
- **Mot de passe keystore**: (notez-le précieusement!)
- **Nom et prénom**: Votre nom
- **Unité organisationnelle**: (ex: Development)
- **Organisation**: Votre entreprise
- **Ville**: Votre ville
- **Province/État**: Votre province
- **Code pays**: CA (pour Canada)
## Configuration de la signature
### Option 1: Variables d'environnement (recommandé)
Créez un fichier `local.properties` (ne pas commiter!) avec:
```properties
SHAARIT_KEYSTORE_PATH=../shaarit-release.keystore
SHAARIT_KEYSTORE_PASSWORD=votre_mot_de_passe
SHAARIT_KEY_ALIAS=shaarit
SHAARIT_KEY_PASSWORD=votre_mot_de_passe_cle
```
### Option 2: Fichier séparé
Créez `keystore.properties` (ne pas commiter!) avec:
```properties
storeFile=../shaarit-release.keystore
storePassword=votre_mot_de_passe
keyAlias=shaarit
keyPassword=votre_mot_de_passe_cle
```
## Build Release
### Debug build (pour tester):
```bash
./gradlew assembleDebug
```
L'APK sera dans: `app/build/outputs/apk/debug/app-debug.apk`
### Release build (pour production):
```bash
./gradlew assembleRelease
```
L'APK sera dans: `app/build/outputs/apk/release/app-release.apk`
### Bundle AAB (pour Google Play Store):
```bash
./gradlew bundleRelease
```
Le bundle sera dans: `app/build/outputs/bundle/release/app-release.aab`
## Vérification du build
Vérifiez l'APK signé:
```bash
jarsigner -verify -verbose -certs app/build/outputs/apk/release/app-release.apk
```
## Checklist avant publication
- [ ] Version code incrémenté dans `build.gradle.kts`
- [ ] Version name mise à jour
- [ ] Tests passés
- [ ] ProGuard configuré et testé
- [ ] APK signé et vérifié
- [ ] Captures d'écran prêtes pour le store
- [ ] Description de l'app rédigée
- [ ] Icône et assets graphiques finalisés
## Notes de sécurité
⚠️ **IMPORTANT**: Ne jamais commiter ces fichiers:
- `*.keystore`
- `*.jks`
- `keystore.properties`
- `local.properties` (sauf template)
Ajoutez au `.gitignore`:
```
*.keystore
*.jks
keystore.properties
```