diff --git a/.kilocode/rules/brief.md b/.kilocode/rules/brief.md new file mode 100644 index 0000000..f512c32 --- /dev/null +++ b/.kilocode/rules/brief.md @@ -0,0 +1,5 @@ +# brief.md + +LiteNote is a UI web app for note taking. It connects with GitHub and, starting from README.md, create beautiful pages to display markdown files with links adding pages à la Matuschak. + +The url looks like `https://litenote.space/{user}/{repo}`. If the repo is public, LiteNote will directly get raw markdown files. If the repo is private, the user must authenticate first. diff --git a/plan.md b/plan.md new file mode 100644 index 0000000..d3ce0ba --- /dev/null +++ b/plan.md @@ -0,0 +1,529 @@ +# Plan d'Implémentation - Partage Public de Notes LiteNote + +## 🎯 Vision de la Fonctionnalité + +Permettre aux utilisateurs de LiteNote de **partager publiquement certaines notes de leurs dépôts privés** sans aucune infrastructure supplémentaire. Cette fonctionnalité utilise un système de "miroir public" intelligent qui synchronise automatiquement les notes marquées comme publiques vers un dépôt GitHub public dédié. + +## 🏗️ Architecture Technique + +### Composants Principaux + +1. **Système de Métadonnées YAML** : Utilise le frontmatter pour marquer les notes publiques +2. **Dépôt Miroir Automatique** : `{username}-litenote-public` créé automatiquement +3. **Service de Synchronisation** : Gestion intelligente des mises à jour +4. **Processeur de Liens** : Transformation des liens inter-notes +5. **Gestionnaire d'Erreurs** : Résolution automatique et manuelle des conflits + +### Flux de Fonctionnement + +```mermaid +graph LR + A[Note Privée] --> B[Métadonnées public: true] + B --> C[Détection Automatique] + C --> D[Traitement des Liens] + D --> E[Synchronisation Miroir] + E --> F[Note Publique Accessible] +``` + +## 📝 Système de Métadonnées + +### Format des Métadonnées Publiques + +```yaml +--- +# Métadonnées de publication +public: true +public_title: "Mon Guide Public" +public_description: "Description visible publiquement" +public_tags: ["guide", "tutorial", "public"] +public_category: "documentation" + +# Métadonnées de synchronisation +public_created: "2024-01-15T10:30:00Z" +public_updated: "2024-01-20T14:45:00Z" +public_version: 2 + +# Options de publication +public_show_backlinks: false +public_allow_comments: true +public_featured: false +--- + +# Contenu de la note... +``` + +### Métadonnées Disponibles + +| Champ | Obligatoire | Description | Exemple | +| ----------------------- | ----------- | --------------------------------------- | ---------------------------- | +| `public` | ✅ | Active le partage public | `true` | +| `public_title` | ❌ | Titre personnalisé pour le public | `"Mon Guide Complet"` | +| `public_description` | ❌ | Description visible publiquement | `"Un guide détaillé sur..."` | +| `public_tags` | ❌ | Tags pour organiser vos notes publiques | `["guide", "tutorial"]` | +| `public_category` | ❌ | Catégorie de la note | `"documentation"` | +| `public_show_backlinks` | ❌ | Afficher les liens entrants | `false` | +| `public_featured` | ❌ | Mettre en avant cette note | `true` | + +## 🗂️ Structure du Dépôt Miroir Public + +```sh +{username}-litenote-public/ +├── README.md # Page d'accueil générée +├── .litenote-mirror.json # Configuration du miroir +├── .github/ +│ └── workflows/ +│ └── pages.yml # Déploiement GitHub Pages (optionnel) +├── notes/ +│ ├── index.md # Index des notes publiques +│ ├── guides/ +│ │ ├── guide-1.md +│ │ └── guide-2.md +│ └── articles/ +│ └── article-1.md +├── assets/ +│ ├── images/ +│ └── files/ +└── _data/ + ├── notes-index.json # Index searchable + └── tags.json # Index des tags +``` + +### Configuration du Miroir (.litenote-mirror.json) + +```json +{ + "version": "1.0", + "source_repo": "username/private-notes", + "created": "2024-01-15T10:30:00Z", + "last_sync": "2024-01-20T14:45:00Z", + "sync_count": 42, + "settings": { + "auto_generate_index": true, + "preserve_folder_structure": true, + "copy_assets": true, + "generate_rss": false + }, + "stats": { + "total_notes": 15, + "total_assets": 8, + "total_tags": 12 + } +} +``` + +## 🔄 Service de Synchronisation + +### Architecture du Service + +```typescript +interface MirrorSyncService { + // Gestion du dépôt miroir + createMirrorRepo(username: string): Promise + getMirrorRepoName(username: string): string + checkMirrorExists(username: string): Promise + + // Synchronisation des notes + syncNote(note: PublicNote): Promise + syncAllPublicNotes(): Promise + removeNoteFromMirror(notePath: string): Promise + + // Gestion des assets + syncAssets(assets: string[]): Promise + updateAssetReferences(content: string, assetMap: Map): string + + // Utilitaires + generateMirrorIndex(): Promise + updateMirrorConfig(): Promise +} +``` + +### Flux de Synchronisation + +```mermaid +graph TD + A[Note modifiée] --> B[Détection changement] + B --> C{Note publique?} + C -->|Non| D[Vérifier si était publique] + C -->|Oui| E[Extraire métadonnées] + D -->|Était publique| F[Supprimer du miroir] + D -->|N'était pas publique| G[Aucune action] + E --> H[Analyser assets référencés] + H --> I[Préparer contenu pour miroir] + I --> J{Dépôt miroir existe?} + J -->|Non| K[Créer dépôt miroir] + J -->|Oui| L[Synchroniser assets] + K --> L + L --> M[Commit note vers miroir] + M --> N[Mettre à jour index] + N --> O[Notification utilisateur] + F --> P[Mettre à jour index] + P --> O +``` + +## 🔗 Gestion des Liens Inter-Notes + +### Problématique des Liens + +Dans LiteNote, les utilisateurs utilisent la syntaxe `[[nom-de-note]]` pour créer des liens entre notes. Quand une note devient publique, ces liens peuvent pointer vers : + +1. **Notes publiques** → Doivent être transformés en liens fonctionnels +2. **Notes privées** → Doivent être gérés avec avertissement +3. **Notes inexistantes** → Doivent être préservés comme liens brisés + +### Algorithme de Transformation + +```mermaid +graph TD + A[Contenu avec liens [[note]]] --> B[Extraire tous les liens] + B --> C[Pour chaque lien] + C --> D{Note existe?} + D -->|Non| E[Marquer comme lien brisé] + D -->|Oui| F{Note est publique?} + F -->|Oui| G[Transformer en lien relatif] + F -->|Non| H[Transformer en lien désactivé] + G --> I[Ajouter à la liste des liens publics] + H --> J[Ajouter à la liste des liens privés] + E --> K[Ajouter à la liste des liens brisés] + I --> L[Générer contenu final] + J --> L + K --> L +``` + +### Transformation des Liens + +```markdown + +Voir aussi [[ma-note-privee]] et [[ma-note-publique]] + + +Voir aussi [ma-note-privee](# "Cette note n'est pas publique") et [ma-note-publique](./ma-note-publique.md) +``` + +## 🎛️ Interface Utilisateur + +### Indicateurs Visuels + +**Dans la liste des notes** : + +- 🌐 Icône pour les notes publiques +- 📝 Icône pour les notes privées +- ⏳ Icône pour les notes en cours de synchronisation + +**Dans l'éditeur de note** : + +- Badge "PUBLIC" dans l'en-tête +- Lien vers la version publique +- Statut de synchronisation + +### Dashboard des Notes Publiques + +```vue + + +``` + +## ⚠️ Gestion des Erreurs et Conflits + +### Types d'Erreurs + +1. **Erreurs de Création du Dépôt Miroir** + - Nom de dépôt déjà pris → Proposition de noms alternatifs + - Permissions insuffisantes → Guide pour configurer les permissions GitHub + - Quota GitHub dépassé → Information sur les limites et solutions + +2. **Erreurs de Synchronisation** + - Conflits de contenu → Résolution automatique ou manuelle + - Fichiers trop volumineux → Compression ou exclusion automatique + - Rate limiting GitHub → Queue avec retry automatique + +3. **Erreurs de Réseau** + - Perte de connexion → Mise en queue pour synchronisation ultérieure + - Timeout API → Retry avec backoff exponentiel + - Authentification expirée → Refresh automatique du token + +### Interface de Résolution des Conflits + +```vue + + +``` + +## 🌐 URLs Publiques + +Vos notes publiques sont accessibles via : + +``` +Format principal : +https://litenote.space/{username}/{username}-litenote-public + +Note spécifique : +https://litenote.space/{username}/{username}-litenote-public?note=notes/ma-note.md + +Avec GitHub Pages (optionnel) : +https://{username}.github.io/{username}-litenote-public/ +``` + +## 🔒 Sécurité et Confidentialité + +### Ce qui est Partagé + +- ✅ **Contenu des notes** marquées `public: true` +- ✅ **Assets référencés** (images, fichiers) dans ces notes +- ✅ **Métadonnées publiques** définies par vous + +### Ce qui Reste Privé + +- ❌ **Toutes les autres notes** de votre dépôt privé +- ❌ **Historique des commits** du dépôt privé +- ❌ **Métadonnées privées** (dates de création, etc.) +- ❌ **Structure complète** de votre dépôt privé + +## 🚀 Plan d'Implémentation + +### Phase 1 : Fondations (2-3 semaines) + +#### 1.1 Système de Détection des Métadonnées + +- [ ] Parser de frontmatter YAML +- [ ] Interface `PublicNoteMetadata` +- [ ] Détecteur de changements de statut public + +#### 1.2 Service de Base du Dépôt Miroir + +- [ ] Création automatique du dépôt miroir +- [ ] Vérification d'existence +- [ ] Configuration initiale + +#### 1.3 Synchronisation Basique + +- [ ] Commit de notes vers le miroir +- [ ] Suppression de notes du miroir +- [ ] Mise à jour des métadonnées du miroir + +### Phase 2 : Fonctionnalités Avancées (2-3 semaines) + +#### 2.1 Processeur de Liens Intelligent + +- [ ] Détection des liens `[[note]]` +- [ ] Transformation des liens publics +- [ ] Gestion des liens privés et brisés +- [ ] Interface d'avertissement des liens + +#### 2.2 Interface Utilisateur Complète + +- [ ] Dashboard des notes publiques +- [ ] Indicateurs visuels dans l'interface +- [ ] Composant de gestion des métadonnées publiques +- [ ] Aperçu des notes publiques + +#### 2.3 Gestion des Assets + +- [ ] Détection des assets référencés +- [ ] Copie vers le dépôt miroir +- [ ] Mise à jour des références + +### Phase 3 : Robustesse et Optimisation (1-2 semaines) + +#### 3.1 Gestion des Erreurs + +- [ ] Gestionnaire d'erreurs complet +- [ ] Interface de résolution des conflits +- [ ] Queue de synchronisation avec retry +- [ ] Notifications utilisateur + +#### 3.2 Performance et Cache + +- [ ] Optimisation des requêtes GitHub +- [ ] Cache des métadonnées publiques +- [ ] Synchronisation incrémentale + +#### 3.3 Documentation et Tests + +- [ ] Documentation utilisateur complète +- [ ] Tests unitaires et d'intégration +- [ ] Guide de migration + +## 📊 Fichiers à Créer/Modifier + +### Nouveaux Fichiers + +``` +src/modules/public-sharing/ +├── interfaces/ +│ ├── PublicNoteMetadata.ts +│ ├── MirrorConfig.ts +│ └── SyncResult.ts +├── services/ +│ ├── MirrorSyncService.ts +│ ├── FrontmatterParser.ts +│ ├── LinkProcessor.ts +│ └── ErrorHandler.ts +├── hooks/ +│ ├── usePublicNoteSync.ts +│ ├── usePublicNotes.ts +│ └── useMirrorRepo.ts +├── components/ +│ ├── PublicNotesDashboard.vue +│ ├── PublicNoteManager.vue +│ ├── LinkWarningsPanel.vue +│ ├── ConflictResolutionModal.vue +│ └── SyncStatusNotification.vue +└── store/ + └── publicNotes.store.ts +``` + +### Fichiers à Modifier + +``` +src/hooks/useGitHubContent.hook.ts # Intégration sync publique +src/hooks/useFile.hook.ts # Détection métadonnées +src/components/FluxNote.vue # Indicateurs visuels +src/router/router.ts # Nouvelles routes +src/views/ShareNotes.vue # Amélioration partage +``` + +## 🎯 Critères de Succès + +### Fonctionnels + +- [ ] Une note avec `public: true` est automatiquement synchronisée +- [ ] Le dépôt miroir est créé automatiquement +- [ ] Les liens inter-notes sont correctement transformés +- [ ] L'interface utilisateur est intuitive et informative +- [ ] Les erreurs sont gérées gracieusement + +### Non-Fonctionnels + +- [ ] Synchronisation en moins de 5 secondes pour une note standard +- [ ] Interface réactive et sans blocage +- [ ] Gestion robuste des pannes réseau +- [ ] Sécurité : aucune fuite de données privées + +### Expérience Utilisateur + +- [ ] Workflow simple : ajouter `public: true` suffit +- [ ] Feedback visuel clair sur le statut de synchronisation +- [ ] Résolution guidée des conflits +- [ ] Documentation claire et accessible + +## 🔮 Évolutions Futures + +### Fonctionnalités Avancées + +- **Intégrations tierces** : RSS, SEO, analytics +- **Fonctionnalités sociales** : Commentaires, likes, partages +- **Thèmes personnalisés** : Apparence des notes publiques +- **Collaboration** : Co-édition de notes publiques + +### Optimisations Techniques + +- **CDN pour assets** : Performance améliorée +- **Indexation full-text** : Recherche dans les notes publiques +- **API publique** : Accès programmatique aux notes +- **Webhooks** : Notifications de changements + +--- + +## 📋 Checklist de Validation + +### Avant Implémentation + +- [ ] Architecture validée par l'équipe +- [ ] Spécifications techniques approuvées +- [ ] Maquettes UI/UX validées +- [ ] Plan de tests défini + +### Pendant l'Implémentation + +- [ ] Tests unitaires pour chaque composant +- [ ] Tests d'intégration avec GitHub API +- [ ] Validation de sécurité +- [ ] Tests de performance + +### Avant Déploiement + +- [ ] Tests utilisateur avec groupe pilote +- [ ] Documentation utilisateur complète +- [ ] Plan de rollback défini +- [ ] Monitoring et alertes configurés + +--- + +*Ce plan constitue la feuille de route complète pour l'implémentation de la fonctionnalité de partage public de LiteNote. Il peut être adapté selon les priorités et contraintes du projet.*