story-research-zapwall/features/zapwall4science-refactoring.md

# Refonte zapwall4Science - Spécifications

**Date** : Décembre 2024
**Auteur** : Équipe 4NK

## 🎯 Objectif

Transformation de Nostr Paywall en **zapwall4Science** : plateforme de publication d'articles scientifiques et de science-fiction avec système de sponsoring, commissions et rémunération des avis.

---

## 📝 Wording et terminologie

### Acteurs

- **Auteur** : Utilisateur qui publie des articles (science-fiction ou recherche scientifique)
- **Lecteur** : Utilisateur qui lit les articles et peut poster des avis
- **Site** : La plateforme zapwall4Science (recevant les commissions)

### Contenus

- **Article** : Publication d'un auteur (science-fiction ou recherche scientifique)
- **Article de présentation** : Article obligatoire créé par chaque auteur lors de son inscription, contenant sa présentation, description de son contenu et adresse de sponsoring mainnet
- **Avis** : Commentaire/évaluation d'un article par un lecteur qui a acheté l'article
- **Message d'envoi de l'article** : Message privé chiffré (kind:4) envoyé automatiquement après paiement d'un article

### Paiements

- **Paiement** : Transaction Bitcoin/Lightning pour accéder à un article ou sponsoriser un auteur
- **Sponsoring** : Paiement unique de 0.05 BTC pour sponsoriser un auteur (0.004 BTC au site, 0.046 BTC à l'auteur)
- **Commission pour le site sur la vente d'un article** : 100 sats sur chaque achat d'article (800 sats total, 700 à l'auteur)
- **Commission pour le site sur le remerciement d'un avis** : 21 sats sur chaque rémunération d'avis (70 sats au lecteur, 21 sats au site)
- **Remerciement pour l'avis** : Paiement de 70 sats (21 sats commission site) par l'auteur à un lecteur pour son avis

---

## 🏗️ Architecture fonctionnelle

### 1. Article de présentation obligatoire

**Description** : Chaque auteur doit créer un article de présentation lors de sa première connexion.

**Contenu obligatoire** :
- Titre : "Présentation de [Nom auteur]"
- Présentation personnelle de l'auteur
- Description/aperçu du type de contenu qu'il publie
- Adresse Bitcoin mainnet pour le sponsoring (obligatoire)

**Caractéristiques** :
- Article gratuit (pas de paiement requis)
- Visible par tous
- Tag spécial : `presentation: true`
- Tag : `category: author-presentation`
- Tag : `mainnet_address: [adresse]`
- Non supprimable (peut être édité)
- Un seul par auteur

**Fichiers à créer/modifier** :
- `components/AuthorPresentationEditor.tsx` : Éditeur d'article de présentation
- `lib/articlePublisher.ts` : Vérification de l'existence d'un article de présentation
- `hooks/useAuthorPresentation.ts` : Hook pour gérer l'article de présentation
- `types/nostr.ts` : Ajout du type `AuthorPresentationArticle`

---

### 2. Division en 2 catégories

**Catégories** :
1. **Science-fiction** (`category: science-fiction`)
2. **Recherche scientifique** (`category: scientific-research`)

**Fonctionnalités** :
- Les auteurs peuvent publier dans les 2 catégories
- Filtrage par catégorie sur la page d'accueil
- Onglets ou sections distinctes pour chaque catégorie
- Tag obligatoire `category` sur chaque article (sauf article de présentation)

**Fichiers à créer/modifier** :
- `components/CategoryFilter.tsx` : Filtre par catégorie
- `pages/index.tsx` : Affichage par catégories
- `lib/articleFiltering.ts` : Filtrage par catégorie
- `types/nostr.ts` : Ajout de `ArticleCategory`

---

### 3. Tri des articles

**Ordre de tri** :
1. **Par sponsoring** : Auteurs les plus sponsorisés en premier
2. **Par date** : Articles les plus récents en premier (parmi les auteurs de même niveau de sponsoring)

**Calcul du sponsoring** :
- Somme totale des paiements de sponsoring reçus par l'auteur
- Stocké dans un tag sur l'article de présentation : `total_sponsoring: [montant en sats]`
- Mis à jour à chaque nouveau sponsoring

**Fichiers à créer/modifier** :
- `lib/articleFiltering.ts` : Tri par sponsoring puis date
- `lib/sponsoring.ts` : Service de gestion du sponsoring
- `types/nostr.ts` : Ajout de `totalSponsoring` dans `Article`

---

### 4. Système de sponsoring

**Montant** : 0.05 BTC (5 000 000 sats)

**Répartition** :
- **Site** : 0.004 BTC (400 000 sats) - frais de transaction payés par l'auteur
- **Auteur** : 0.046 BTC (4 600 000 sats) - frais de transaction payés par l'auteur

**Fonctionnement** :
- Paiement unique vers l'adresse mainnet de l'auteur (depuis l'article de présentation)
- Transaction Bitcoin mainnet (pas Lightning)
- Mise à jour du tag `total_sponsoring` sur l'article de présentation
- Affichage du montant total sponsorisé sur le profil de l'auteur

**Fichiers à créer/modifier** :
- `components/SponsorButton.tsx` : Bouton de sponsoring
- `lib/sponsoring.ts` : Service de sponsoring
- `lib/bitcoinMainnet.ts` : Service pour les paiements mainnet
- `types/sponsoring.ts` : Types pour le sponsoring

---

### 5. Paiement d'article modifié (BOLT12)

**Montant** : 800 sats

**Répartition** :
- **Auteur** : 700 sats - frais de transaction payés par l'auteur
- **Site** : 100 sats - frais de transaction payés par l'auteur

**Technologie** : BOLT12 (offers) pour diviser automatiquement le paiement

**Fonctionnement** :
- Création d'une offre BOLT12 avec split automatique
- 700 sats vers l'adresse Lightning de l'auteur
- 100 sats vers l'adresse Lightning du site
- Frais de transaction payés par l'auteur (déduits de sa part)

**Fichiers à créer/modifier** :
- `lib/bolt12.ts` : Service BOLT12 pour les offres avec split
- `lib/payment.ts` : Modification pour utiliser BOLT12
- `types/payment.ts` : Types pour BOLT12

---

### 6. Système de rémunération des avis

**Conditions** :
- Seuls les lecteurs qui ont acheté l'article peuvent poster un avis
- L'auteur peut rémunérer un avis avec 70 sats

**Répartition** :
- **Lecteur (auteur de l'avis)** : 70 sats - frais de transaction payés par l'auteur
- **Site** : 21 sats - frais de transaction payés par l'auteur

**Fonctionnement** :
- Bouton "Remercier" sur chaque avis (visible uniquement par l'auteur de l'article)
- Paiement Lightning avec split automatique (BOLT12)
- Tag sur l'avis : `rewarded: true`, `reward_amount: 70`

**Fichiers à créer/modifier** :
- `components/ArticleReview.tsx` : Composant d'avis avec bouton de rémunération
- `components/ReviewRewardButton.tsx` : Bouton de rémunération d'avis
- `lib/reviewReward.ts` : Service de rémunération des avis
- `types/reviews.ts` : Types pour les avis

---

## 🔧 Modifications techniques

### Structure de données

#### Article de présentation
```typescript
interface AuthorPresentationArticle extends Article {
  category: 'author-presentation'
  mainnetAddress: string
  totalSponsoring: number // en sats
  isPresentation: true
}
```

#### Article standard
```typescript
interface StandardArticle extends Article {
  category: 'science-fiction' | 'scientific-research'
  authorPresentationId: string // ID de l'article de présentation
  lightningAddress: string // Adresse Lightning de l'auteur
}
```

#### Avis
```typescript
interface Review {
  id: string
  articleId: string
  authorPubkey: string // Auteur de l'article
  reviewerPubkey: string // Lecteur qui a écrit l'avis
  content: string
  rating?: number // 1-5 étoiles
  createdAt: number
  rewarded: boolean
  rewardAmount?: number // 70 sats si rémunéré
  rewardTransactionId?: string
}
```

### Tags Nostr

#### Article de présentation
```
- title: "Présentation de [Nom]"
- category: "author-presentation"
- presentation: "true"
- mainnet_address: "[adresse Bitcoin]"
- total_sponsoring: "[montant en sats]"
```

#### Article standard
```
- title: "[Titre]"
- category: "science-fiction" | "scientific-research"
- preview: "[Aperçu]"
- zap: "800"
- author_presentation_id: "[ID article présentation]"
- lightning_address: "[adresse Lightning auteur]"
- invoice: "[BOLT12 offer]"
```

#### Avis (kind:1 avec tag spécial)
```
- review: "true"
- e: "[ID article]"
- p: "[pubkey auteur]"
- rating: "[1-5]"
- rewarded: "true" | "false"
- reward_amount: "70" (si rémunéré)
```

---

## 📁 Fichiers à créer

### Nouveaux composants
- `components/AuthorPresentationEditor.tsx`
- `components/CategoryFilter.tsx`
- `components/CategoryTabs.tsx`
- `components/SponsorButton.tsx`
- `components/ArticleReview.tsx`
- `components/ReviewRewardButton.tsx`
- `components/ReviewForm.tsx`

### Nouveaux services
- `lib/sponsoring.ts`
- `lib/bitcoinMainnet.ts`
- `lib/bolt12.ts`
- `lib/reviewReward.ts`
- `lib/reviews.ts`

### Nouveaux hooks
- `hooks/useAuthorPresentation.ts`
- `hooks/useSponsoring.ts`
- `hooks/useReviews.ts`
- `hooks/useReviewReward.ts`

### Nouveaux types
- `types/sponsoring.ts`
- `types/reviews.ts`
- `types/bolt12.ts`

---

## 📁 Fichiers à modifier

### Pages
- `pages/index.tsx` : Ajout des catégories et tri par sponsoring
- `pages/publish.tsx` : Sélection de catégorie obligatoire
- `pages/profile.tsx` : Affichage de l'article de présentation et sponsoring

### Composants existants
- `components/ArticleCard.tsx` : Affichage catégorie et sponsoring
- `components/ArticleEditor.tsx` : Sélection de catégorie
- `components/UserProfile.tsx` : Affichage sponsoring total

### Services existants
- `lib/articlePublisher.ts` : Vérification article de présentation
- `lib/payment.ts` : Migration vers BOLT12
- `lib/articleFiltering.ts` : Tri par sponsoring
- `lib/nostr.ts` : Parsing des nouveaux tags

### Types existants
- `types/nostr.ts` : Ajout des nouveaux types

---

## 🔄 Flux utilisateur

### Inscription d'un auteur
1. Connexion avec Nostr
2. Redirection vers création d'article de présentation (obligatoire)
3. Remplissage : présentation, description, adresse mainnet
4. Publication de l'article de présentation
5. Accès à la plateforme

### Publication d'un article
1. Sélection de la catégorie (science-fiction ou recherche)
2. Remplissage du formulaire (titre, preview, contenu)
3. Création de l'offre BOLT12 avec split (700/100)
4. Publication avec tags appropriés

### Achat d'un article
1. Clic sur "Unlock for 800 sats"
2. Affichage de l'offre BOLT12
3. Paiement Lightning
4. Réception automatique du contenu (message privé)
5. Possibilité de poster un avis

### Sponsoring d'un auteur
1. Clic sur "Sponsor" sur l'article de présentation
2. Affichage de l'adresse mainnet
3. Paiement Bitcoin mainnet de 0.05 BTC
4. Mise à jour du sponsoring total
5. Tri mis à jour

### Rémunération d'un avis
1. Auteur voit l'avis d'un lecteur qui a acheté
2. Clic sur "Remercier (70 sats)"
3. Paiement Lightning avec split (70/21)
4. Tag `rewarded: true` sur l'avis

---

## ⚠️ Points d'attention

### BOLT12
- Vérifier la compatibilité avec Alby/WebLN pour BOLT12
- Implémenter le split automatique dans l'offre
- Gérer les frais de transaction

### Bitcoin Mainnet
- Intégration avec un service de paiement mainnet (ou QR code)
- Vérification des paiements mainnet
- Gestion des confirmations

### Sécurité
- Vérifier que seuls les acheteurs peuvent poster des avis
- Vérifier que seul l'auteur peut rémunérer les avis
- Vérifier l'authenticité des paiements

### Performance
- Indexer les articles par catégorie
- Indexer les auteurs par sponsoring total
- Cache des calculs de tri

---

## 📊 Priorités d'implémentation

### Phase 1 - Fondations
1. ✅ Wording et terminologie (documentation)
2. ⏳ Article de présentation obligatoire
3. ⏳ Division en catégories
4. ⏳ Tri par sponsoring puis date

### Phase 2 - Paiements
5. ⏳ Système de sponsoring (Bitcoin mainnet)
6. ⏳ Migration vers BOLT12 pour les articles
7. ⏳ Split automatique des paiements

### Phase 3 - Avis et rémunération
8. ⏳ Système d'avis (seulement pour acheteurs)
9. ⏳ Rémunération des avis par l'auteur

### Phase 4 - UI/UX
10. ⏳ Interface par catégories
11. ⏳ Affichage du sponsoring
12. ⏳ Interface de rémunération des avis

---

## 🎨 Renommage

- **Nom du site** : zapwall4Science
- **Titre** : "zapwall4Science - Science Fiction & Scientific Research"
- **Description** : "Plateforme de publication d'articles scientifiques et de science-fiction avec sponsoring et rémunération des avis"

**Fichiers à modifier** :
- `pages/index.tsx` : Titre et description
- `pages/_app.tsx` : Titre par défaut
- `README.md` : Nom et description
- Tous les composants avec "Nostr Paywall" → "zapwall4Science"

---

## 📝 Notes techniques

### BOLT12 Offers
- Utiliser `lightning:lno1...` pour les offres
- Split automatique via les métadonnées de l'offre
- Vérifier la compatibilité avec les wallets Lightning

### Bitcoin Mainnet
- Utiliser une API de vérification de transactions (blockchain.info, blockstream, etc.)
- QR code pour faciliter les paiements
- Affichage clair de l'adresse et du montant

### Stockage
- Stocker les montants de sponsoring dans IndexedDB
- Cache des calculs de tri
- Synchronisation avec les événements Nostr

---

## ✅ Checklist de validation

- [ ] Article de présentation créé pour chaque auteur
- [ ] Catégories fonctionnelles (science-fiction / recherche)
- [ ] Tri par sponsoring puis date opérationnel
- [ ] Sponsoring Bitcoin mainnet fonctionnel
- [ ] Paiements articles avec BOLT12 et split
- [ ] Avis uniquement pour les acheteurs
- [ ] Rémunération des avis fonctionnelle
- [ ] Wording cohérent partout
- [ ] Renommage complet en zapwall4Science