chore: propose a plan for a partially public notes
This commit is contained in:
Julien Calixte
529
plan.md
Normal file
529
plan.md
Normal file
@@ -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<string>
|
||||
getMirrorRepoName(username: string): string
|
||||
checkMirrorExists(username: string): Promise<boolean>
|
||||
|
||||
// Synchronisation des notes
|
||||
syncNote(note: PublicNote): Promise<SyncResult>
|
||||
syncAllPublicNotes(): Promise<SyncResult[]>
|
||||
removeNoteFromMirror(notePath: string): Promise<boolean>
|
||||
|
||||
// Gestion des assets
|
||||
syncAssets(assets: string[]): Promise<string[]>
|
||||
updateAssetReferences(content: string, assetMap: Map<string, string>): string
|
||||
|
||||
// Utilitaires
|
||||
generateMirrorIndex(): Promise<void>
|
||||
updateMirrorConfig(): Promise<void>
|
||||
}
|
||||
```
|
||||
|
||||
### 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
|
||||
<!-- Dans la note privée -->
|
||||
Voir aussi [[ma-note-privee]] et [[ma-note-publique]]
|
||||
|
||||
<!-- Dans la 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
|
||||
<!-- Composant PublicNotesDashboard.vue -->
|
||||
<template>
|
||||
<div class="public-dashboard">
|
||||
<div class="dashboard-header">
|
||||
<h2>Mes Notes Publiques</h2>
|
||||
<div class="mirror-info">
|
||||
<span>Dépôt miroir : </span>
|
||||
<a :href="mirrorRepoUrl" target="_blank">
|
||||
{{ mirrorRepoName }}
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="public-notes-list">
|
||||
<div
|
||||
v-for="note in publicNotes"
|
||||
:key="note.sha"
|
||||
class="public-note-item"
|
||||
>
|
||||
<div class="note-info">
|
||||
<h3>{{ note.metadata.public_title || note.title }}</h3>
|
||||
<p>{{ note.metadata.public_description }}</p>
|
||||
<div class="note-tags">
|
||||
<span
|
||||
v-for="tag in note.metadata.public_tags"
|
||||
:key="tag"
|
||||
class="tag"
|
||||
>
|
||||
{{ tag }}
|
||||
</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="note-actions">
|
||||
<button @click="editNote(note)">Éditer</button>
|
||||
<button @click="viewPublic(note)">Voir public</button>
|
||||
<button @click="unpublish(note)">Dépublier</button>
|
||||
</div>
|
||||
|
||||
<div class="sync-status">
|
||||
<span :class="getSyncStatusClass(note)">
|
||||
{{ getSyncStatusText(note) }}
|
||||
</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
```
|
||||
|
||||
## ⚠️ 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
|
||||
<!-- ConflictResolutionModal.vue -->
|
||||
<template>
|
||||
<div class="conflict-modal" v-if="conflict">
|
||||
<div class="modal-content">
|
||||
<div class="modal-header">
|
||||
<h2>🔄 Conflit de Synchronisation</h2>
|
||||
<p>{{ conflict.description }}</p>
|
||||
</div>
|
||||
|
||||
<div class="conflict-details">
|
||||
<div class="version-comparison">
|
||||
<div class="version local">
|
||||
<h3>Version Locale</h3>
|
||||
<div class="content-preview">{{ conflict.localContent }}</div>
|
||||
</div>
|
||||
|
||||
<div class="version remote">
|
||||
<h3>Version Miroir</h3>
|
||||
<div class="content-preview">{{ conflict.remoteContent }}</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="resolution-actions">
|
||||
<button @click="acceptAutoMerge">Accepter la fusion automatique</button>
|
||||
<button @click="useLocalVersion">Utiliser la version locale</button>
|
||||
<button @click="useRemoteVersion">Utiliser la version du miroir</button>
|
||||
<button @click="editManually">Éditer manuellement</button>
|
||||
<button @click="skipSync">Ignorer cette synchronisation</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
```
|
||||
|
||||
## 🌐 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.*
|
||||
Reference in New Issue
Block a user