72 lines
4.5 KiB
Markdown
72 lines
4.5 KiB
Markdown
# Documentation technique – zapwall4science (Dec 2025)
|
||
|
||
## 1) Cartographie services/hooks/types (responsabilités, dépendances)
|
||
|
||
- **Services Nostr**
|
||
- `lib/nostr.ts` : pool SimplePool, publish générique, clés locales; queries article.
|
||
- `lib/nostrEventParsing.ts` : parsing events → Article/Series/Review (tags kind_type, series, media, banner).
|
||
- `lib/nostrTags.ts` : construction des tags article/série/avis (site, type science-fiction/research, kind_type, media/bannière).
|
||
- `lib/seriesQueries.ts`, `lib/articleQueries.ts`, `lib/reviews.ts` : fetch séries, articles par série, critiques.
|
||
- `lib/articlePublisher.ts`, `lib/articleMutations.ts` : publication article/preview/presentation, update/delete, kind_type, séries, médias, bannière.
|
||
- `lib/seriesAggregation.ts`, `lib/reviewAggregation.ts`, `lib/zapAggregation.ts` : agrégats sponsoring/achats/remerciements.
|
||
- `lib/zapVerification.ts` : vérification zap receipts (verifyEvent).
|
||
- `lib/nostrconnect.ts` : Nostr Connect (handler, sécurité).
|
||
- `lib/nostrRemoteSigner.ts` : signature distante (pas de fallback silencieux).
|
||
- `lib/nip95.ts` : upload médias NIP-95 (images ≤5Mo, vidéos ≤45Mo, types restreints).
|
||
- **Paiement / Lightning**
|
||
- `lib/alby.ts` : WebLN (enable, makeInvoice, sendPayment).
|
||
- `lib/payment.ts`, `lib/paymentPolling.ts` : statut paiements, polling.
|
||
- `lib/articleInvoice.ts` : facture article (zapAmount, expiry), tags preview.
|
||
- **Stockage**
|
||
- `lib/storage/cryptoHelpers.ts` : AES-GCM, dérivation/import clé, conversions b64.
|
||
- `lib/storage/indexedDB.ts` : set/get/delete/clearExpired chiffré, TTL.
|
||
- `lib/articleStorage.ts` : clé maître locale (base64), secret par article, persistance contenu privé + facture.
|
||
- **Hooks**
|
||
- `hooks/useArticles.ts`, `hooks/useUserArticles.ts` : subscriptions articles, filtres catégorie, unsubscribe direct (pas de .then).
|
||
- `hooks/useArticleEditing.ts` : édition/suppression article.
|
||
- Autres : `useNotificationCenter`, `useNostrConnect`, etc.
|
||
- **Types**
|
||
- `types/nostr.ts` : Article, Series, Review, MediaRef, KindType, catégories; exactOptionalPropertyTypes respecté.
|
||
- `types/nostr-tools-extended.ts` : extensions SimplePool/Sub.
|
||
- `types/alby.ts` : WebLNProvider, invoice types.
|
||
|
||
## 2) Guide Nostr (publication, update/delete, zap, remote signer)
|
||
|
||
- Publication générique : `nostrService.publishEvent(eventTemplate)` (signEvent, created_at contrôlé).
|
||
- Article : `articlePublisher.publishArticle` (preview + tags kind_type/site/category/series/banner/media), contenu privé chiffré stocké.
|
||
- Update article : `publishArticleUpdate` (`lib/articleMutations.ts`) tags `e` (original) + `replace`, publie preview + contenu privé chiffré.
|
||
- Delete article : `deleteArticleEvent` (kind 5, tag e) — erreurs remontées, pas de fallback.
|
||
- Série : `publishSeries` (kind 1, tags kind_type=series, cover, description).
|
||
- Avis : `publishReview` (kind 1, kind_type=review, article/series/author tags).
|
||
- Zap verification : `lib/zapVerification.ts` (verifyEvent).
|
||
- Agrégats : `aggregateZapSats` / `getSeriesAggregates` / `getReviewTipsForArticle`.
|
||
- Remote signer : `lib/nostrRemoteSigner.ts` (clé fournie), sans valeurs de repli implicites.
|
||
|
||
## 3) Guide Stockage
|
||
|
||
- Chiffrement : `cryptoHelpers` (AES-GCM), entrée BufferSource conforme Web Crypto.
|
||
- IndexedDB : `storage/indexedDB.ts` stocke `{ iv, ciphertext, expiresAt }`, purge `clearExpired`.
|
||
- Secret : `articleStorage` génère clé maître (localStorage, base64, 32 bytes) puis secret `<master>:<articleId>`.
|
||
- Données : contenu privé + facture, TTL 30 jours, suppression via `removeStoredPrivateContent`.
|
||
|
||
## 4) Guide Paiements
|
||
|
||
- WebLN/Alby : `lib/alby.ts` (enable, makeInvoice, sendPayment).
|
||
- Facture article : `createArticleInvoice` (zapAmount, expiry).
|
||
- Publication article : `articlePublisher` gère preview event + stockage contenu privé.
|
||
- Polling / vérif : `paymentPolling.ts`, `payment.ts`; agrégats via zap receipts (`zapAggregation.ts`).
|
||
- Envoi contenu privé : via publisher/mutations après paiement confirmé.
|
||
|
||
## 5) Médias / NIP-95
|
||
|
||
- Upload via `uploadMedia(file)` (URL `NEXT_PUBLIC_NIP95_UPLOAD_URL`), validation type/taille.
|
||
- Utilisation dans `MarkdownEditor` (insertion markdown), bannière dans ArticleDraft.
|
||
|
||
## 6) Contrib (référence rapide)
|
||
|
||
- Lint/typage obligatoires (`npm run lint`, `npm run type-check`).
|
||
- Pas de tests/analytics ajoutés.
|
||
- Pas de fallback implicite, pas de `ts-ignore`/`any` non justifié.
|
||
- Accessibilité : ARIA/clavier/contraste.
|
||
- Documentation : corrections dans `fixKnowledge/`, features dans `features/`.
|