From c1331dff72133fa4f7925e0dc847a259e632d240 Mon Sep 17 00:00:00 2001 From: openclaw Date: Thu, 19 Mar 2026 13:25:36 +0100 Subject: [PATCH] Clean capitalisation inbox and integrate frontend link-out pattern --- 10_frontend_patterns_valides.md | 46 ++++++++- 95_a_capitaliser.md | 139 ++++---------------------- 96_review_capitalisation.md | 171 -------------------------------- scripts/aliases.sh | 0 4 files changed, 62 insertions(+), 294 deletions(-) delete mode 100644 96_review_capitalisation.md mode change 100644 => 100755 scripts/aliases.sh diff --git a/10_frontend_patterns_valides.md b/10_frontend_patterns_valides.md index 61f3b5b..e9d30b0 100644 --- a/10_frontend_patterns_valides.md +++ b/10_frontend_patterns_valides.md @@ -12,7 +12,7 @@ Il sert de **mémoire durable** pour éviter : - de redélibérer éternellement sur des sujets déjà tranchés, - de propager des “bonnes pratiques” théoriques non éprouvées. -Dernière mise à jour : 16-03-2026 +Dernière mise à jour : 19-03-2026 --- @@ -24,6 +24,7 @@ Dernière mise à jour : 16-03-2026 - [Navigation réactive post-action async (React / Expo Router)](#pattern-navigation-reactive-post-action-async) - [Refresh idempotent sur store de liste paginée](#pattern-refresh-idempotent-liste-paginee) - [UI admin légère sur domaine existant](#pattern-ui-admin-legere-domaine-existant) +- [Intégration tierce en mode link-out — préférer une page locale canonique](#pattern-link-out-page-locale-canonique) --- @@ -383,6 +384,49 @@ const handleOAuth = async () => { --- +--- + + +## Pattern : Intégration tierce en mode link-out — préférer une page locale canonique + +### Synthèse + +- **Objectif** : éviter les parcours concurrents et centraliser les garde-fous UX quand une fonctionnalité publique dépend d’un service tiers externe. +- **Contexte** : site ou webapp avec CTA publics menant vers un tiers de réservation, paiement, prise de rendez-vous ou formulaire externe. +- **Quand l’utiliser** : dès qu’une fonctionnalité externe dispose d’une page locale dédiée côté produit (`/reservation`, `/booking`, etc.). +- **Quand l’éviter** : si le produit assume volontairement une sortie directe unique vers le tiers, sans page locale intermédiaire ni besoin de contextualisation. + +### Analyse + +- **Avantages** : + - UX plus cohérente entre home, navigation et pages dédiées + - garde-fous, wording et fallbacks centralisés au même endroit + - facilite l’évolution future vers embed, click-to-load ou variantes de parcours +- **Limites / vigilance** : + - ajoute une étape intermédiaire si la page locale n’apporte aucune valeur + - demande de maintenir l’alignement entre les CTA internes et le parcours canonique + +### Validation + +- Validé le : 19-03-2026 +- Contexte technique : site web public / intégration tierce en mode lien externe + +### Implémentation (exemple minimal) + +```txt +- faire pointer les CTA internes (home, nav, landing) vers une page locale dédiée +- faire de cette page locale le point canonique vers le service tiers externe +- centraliser sur cette page le contexte utile, les garde-fous et les fallbacks +- éviter les sorties directes concurrentes vers le tiers depuis plusieurs endroits du site +``` + +### Checklist + +- [ ] Un parcours canonique unique est défini +- [ ] Les CTA internes convergent vers la page locale dédiée +- [ ] Les garde-fous et fallbacks sont centralisés +- [ ] Les sorties directes concurrentes vers le tiers sont évitées ou justifiées + ### Principes transverses - Un pattern = une responsabilité claire diff --git a/95_a_capitaliser.md b/95_a_capitaliser.md index 2a909fd..3ce34a8 100644 --- a/95_a_capitaliser.md +++ b/95_a_capitaliser.md @@ -77,131 +77,26 @@ Description courte, factuelle, orientée réutilisation. --- -# Revue de tri — 2026-03-16 - -Cette section sert à qualifier les propositions en attente avant intégration manuelle. - -## Rappel - -L'exemple plus haut est conservé volontairement pour montrer aux agents le format attendu. -Il ne fait pas partie des propositions à intégrer. - -## À intégrer - -Intégré le 16-03-2026 dans les fichiers cibles. - -## À fusionner avant intégration - -- `2026-03-16 — app-template-resto` → `10_backend_patterns_valides.md` - `Isolation des guards purs des modules server-only` -- `2026-03-16 — app-template-resto` → `10_backend_patterns_valides.md` - ``server-only` réservé aux modules avec APIs Next.js exclusivement serveur` -- `2026-03-16 — app-template-resto` → `10_backend_patterns_valides.md` - `Server Action Next.js — isoler la logique pure dans un module injectable` - -Fusion recommandée : -`Next.js server-only / Server Actions : garder l'orchestration runtime-only fine et extraire la logique pure testable` - -- `2026-03-16 — app-template-resto` → `10_backend_patterns_valides.md` - `Transaction obligatoire pour les opérations auth multi-étapes` -- `2026-03-16 — app-template-resto` → `10_backend_patterns_valides.md` - `Suppression de session idempotente (P2025)` - -Fusion recommandée : -`Opérations auth sensibles : atomiques, idempotentes et cohérentes en cas d'erreur` - -## À laisser en tampon - -- `2026-03-10 — app-alexandrie` → `10_backend_patterns_valides.md` - `Progression V1 calculée sans persistance dédiée` - Motif : intéressant mais encore trop lié à un choix produit / modélisation métier. -- `2026-03-16 — app-template-resto` → `10_backend_risques_et_vigilance.md` - `Divergence schéma / spec story` - Motif : utile en review, mais trop lié au process de story pour la mémoire durable. -- `2026-03-16 — app-template-resto / code-review story 1.11` → `10_backend_risques_et_vigilance.md` - `server-only dans les repositories bloque les tests unitaires` - Motif : le problème est réel, mais la solution proposée (`stub` local) ne doit pas devenir un standard. - -2026-03-10 — app-alexandrie - -FILE_UPDATE_PROPOSAL -Fichier cible : 10_backend_patterns_valides.md - -Pourquoi : -Pattern réutilisable pour exposer une progression V1 sans ouvrir trop tôt un domaine `achievements` ou `analytics`, tout en gardant une couture propre vers des contributions futures. - -Proposition : - -## Progression V1 calculée sans persistance dédiée - -Pour une feature de progression minimum viable : -- garder l'agrégat dans le domaine métier déjà source de vérité (`content`, `billing`, etc.) -- calculer les compteurs période (`thisWeek`, `thisMonth`) côté base avec `count`/agrégations filtrées -- centraliser le catalogue d'objectifs en code explicite et testable -- prévoir une couture zéro-safe pour les sources futures (`contributions`, `posts`, etc.) au lieu d'inventer les tables en avance - -Évite le scope creep vers un module `achievements` prématuré et garde un contrat stable. - -2026-03-16 — app-template-resto - -FILE_UPDATE_PROPOSAL -Fichier cible : 10_backend_patterns_valides.md - -Pourquoi : -Code review story 1.9 a révélé un pattern récurrent : les services avec opérations multi-étapes (hash + update + delete) doivent systématiquement utiliser $transaction pour éviter les race conditions. - -Proposition : -**Pattern : Transaction obligatoire pour les opérations auth multi-étapes** -Toute opération qui combine hashing de mot de passe + update user + invalidation de tokens doit être enveloppée dans `prisma.$transaction()`. Sans transaction, une interruption entre les étapes laisse l'état incohérent (ex: token valide après reset du mot de passe). -Exemple : consumePasswordReset — marquer consumedAt + update passwordHash + deleteMany autres tokens dans une seule transaction. +_Aucune entrée pour le moment_ --- -2026-03-16 — app-template-resto -FILE_UPDATE_PROPOSAL -Fichier cible : 10_backend_risques_et_vigilance.md +# Rôle dans l'architecture -Pourquoi : -Code review story 1.9 a révélé un anti-pattern : les tâches de story peuvent déclarer [x] consumedAt sans que le champ existe réellement dans le schéma Prisma. +``` +Projet + ↓ +Proposition + ↓ +95_a_capitaliser.md + ↓ +Validation humaine + ↓ +Lead_tech +``` -Proposition : -**Anti-pattern : Divergence schéma / spec story** -Lors d'une implémentation, valider que chaque champ mentionné dans les tâches (consumedAt, tokenHash, etc.) existe réellement dans le schéma Prisma avant de marquer la tâche [x]. Une story peut décrire consumedAt comme stratégie de conception sans que le champ soit présent — toujours croiser avec schema.prisma. +Ce mécanisme permet : ---- -2026-03-16 — app-template-resto - -FILE_UPDATE_PROPOSAL -Fichier cible : 10_backend_patterns_valides.md - -Pourquoi : -Pattern validé sur story 1.10 — suppression de session avec gestion idempotente, réutilisable pour toute opération de révocation. - -Proposition : -**Pattern : Suppression de session idempotente (P2025)** -Lors d'une déconnexion ou révocation de session, entourer le `prisma.session.delete()` d'un try/catch qui absorbe silencieusement le code Prisma `P2025` (record not found). Une session peut déjà avoir été supprimée (expiration, logout concurrent) — ce n'est pas une erreur, ne pas la propager. - ---- -2026-03-19 — app-template-restau - -FILE_UPDATE_PROPOSAL -Fichier cible : 10_frontend_patterns_valides.md - -Pourquoi : -Sur les fonctionnalités publiques reposant sur un service tiers en mode link-out (ex: réservation), un parcours canonique unique évite les ambiguïtés UX et centralise mieux les garde-fous, le wording et les fallbacks. - -Proposition : -### Intégration tierce en mode link-out : préférer une page locale canonique - -Quand une fonctionnalité publique dépend d’un service tiers accessible via lien externe, préférer le parcours : - -- CTA internes (home, navigation, landing) → page locale du site -- page locale dédiée → service tiers externe - -Éviter de mélanger plusieurs parcours concurrents (ex: home qui sort directement vers le tiers alors qu’une page `/reservation` dédiée existe déjà). - -Bénéfices : -- UX plus cohérente -- garde-fous centralisés au même endroit -- fallbacks plus simples à gérer -- évolution facilitée vers une variante embed / click-to-load +- d'éviter la pollution de la base de connaissance +- de capitaliser progressivement l'expérience des projets +- de garder `Lead_tech` cohérent et fiable. diff --git a/96_review_capitalisation.md b/96_review_capitalisation.md deleted file mode 100644 index 9d39c73..0000000 --- a/96_review_capitalisation.md +++ /dev/null @@ -1,171 +0,0 @@ -# Review de capitalisation — 2026-03-19 - -Source revue : `95_a_capitaliser.md` -Périmètre de comparaison : `10_*`, `40_decisions_et_archi.md`, `90_debug_et_postmortem.md` - -## Méthode - -- L’exemple de format présent en tête de `95_a_capitaliser.md` n’est pas traité comme une proposition. -- Les entrées ont été triées selon 5 statuts : `duplicate`, `near-duplicate`, `candidate`, `too-local`, `unclear`. -- Aucun contenu n’a été intégré dans les fichiers de connaissance validée. - ---- - -## duplicate - -Aucune entrée classée `duplicate`. - ---- - -## near-duplicate - -### 2026-03-16 — app-template-resto -**Cible proposée :** `10_backend_patterns_valides.md` -**Titre :** Transaction obligatoire pour les opérations auth multi-étapes - -**Verdict :** `near-duplicate` - -**Pourquoi :** -- Recouvre fortement des principes déjà validés dans : - - `10_backend_patterns_valides.md` → `Token à usage unique — génération, hash et invalidation atomique` - - `40_decisions_et_archi.md` → `Idempotence et gestion des retries pour les opérations sensibles` -- L’apport utile existe, mais la proposition actuelle est une spécialisation auth/password-reset d’un invariant plus large : opérations sensibles multi-écritures = transaction. - -**Recommandation :** -- À fusionner si intégration future, sous une formulation plus générique : transaction pour opérations sensibles multi-étapes, avec exemple auth. - -### 2026-03-16 — app-template-resto -**Cible proposée :** `10_backend_patterns_valides.md` -**Titre :** Isolation des guards purs des modules server-only - -**Verdict :** `near-duplicate` - -**Pourquoi :** -- Quasi même famille d’idée que : - - `server-only` réservé aux modules avec APIs Next.js exclusivement serveur - - `Server Action Next.js — isoler la logique pure dans un module injectable` -- Le cœur du savoir est le même : isoler la logique pure, limiter `server-only` aux bords runtime-only. - -**Recommandation :** -- Ne pas intégrer seul. -- À absorber dans une entrée fusionnée sur `server-only` / testabilité / extraction de logique pure. - -### 2026-03-16 — app-template-resto / code-review story 1.11 -**Cible proposée :** `10_backend_risques_et_vigilance.md` -**Titre :** `server-only` dans les repositories bloque les tests unitaires - -**Verdict :** `near-duplicate` - -**Pourquoi :** -- Même problème racine que les propositions précédentes sur `server-only`. -- Le risque est réel, mais il double essentiellement un futur pattern plus général sur la frontière runtime-only. -- La mitigation par stub `server-only` en test ne doit pas être capitalisée comme pratique de référence. - -**Recommandation :** -- Ne pas intégrer sous cette forme. -- Si capitalisation ultérieure : reformuler le risque autour de “mélanger logique pure et dépendances runtime-only nuit à la testabilité”. - ---- - -## candidate - -### 2026-03-16 — app-template-resto -**Cible proposée :** `10_backend_patterns_valides.md` -**Titre :** `server-only` réservé aux modules avec APIs Next.js exclusivement serveur - -**Verdict :** `candidate` - -**Pourquoi :** -- Savoir réutilisable, concret, testable, avec périmètre clair. -- Pas trouvé tel quel dans les fichiers validés. -- Complète utilement les patterns backend existants sur testabilité et séparation des responsabilités. - -**Réserve :** -- À intégrer seulement après fusion avec les autres entrées proches sur `server-only` et Server Actions, pour éviter trois patterns quasi redondants. - -### 2026-03-16 — app-template-resto -**Cible proposée :** `10_backend_patterns_valides.md` -**Titre :** Suppression de session idempotente (P2025) - -**Verdict :** `candidate` - -**Pourquoi :** -- Cas réutilisable au-delà du projet : révocation/logout/suppression concurrente. -- Complète les principes généraux d’idempotence déjà présents avec un exemple Prisma actionnable. -- Suffisamment concret pour mériter potentiellement un pattern dédié si d’autres cas analogues existent. - -**Réserve :** -- Bien cadrer le contexte technique (`Prisma`, suppression de session/révocation) pour éviter d’en faire une règle trop générale. - -### 2026-03-16 — app-template-resto -**Cible proposée :** `10_backend_patterns_valides.md` -**Titre :** Server Action Next.js — isoler la logique pure dans un module injectable - -**Verdict :** `candidate` - -**Pourquoi :** -- Le pattern est clair, réutilisable, et dépasse le cas local. -- Il apporte une couture explicite entre runtime Next.js et logique testable. -- Aucun équivalent direct n’est déjà capitalisé dans les fichiers validés. - -**Réserve :** -- À fusionner avec les deux autres entrées `server-only` pour produire une seule entrée robuste : frontière runtime-only fine, orchestration en bord, logique pure injectable/testable. - ---- - -## too-local - -### 2026-03-10 — app-alexandrie -**Cible proposée :** `10_backend_patterns_valides.md` -**Titre :** Progression V1 calculée sans persistance dédiée - -**Verdict :** `too-local` - -**Pourquoi :** -- Le raisonnement est intéressant, mais reste très lié à un arbitrage produit/modélisation métier V1. -- Réutilisabilité trop faible en l’état : dépend du type de progression, du domaine, et du niveau d’anticipation produit. -- Même conclusion que la revue déjà présente dans `95_a_capitaliser.md` : utile, mais pas encore assez universel pour mémoire durable. - -### 2026-03-16 — app-template-resto -**Cible proposée :** `10_backend_risques_et_vigilance.md` -**Titre :** Divergence schéma / spec story - -**Verdict :** `too-local` - -**Pourquoi :** -- Le problème relève surtout d’un défaut de process de story/review, pas d’un risque backend durable au bon niveau d’abstraction. -- Trop attaché au contexte BMAD/story-writing et à Prisma sur ce cas précis. -- Mieux traité dans des conventions de review ou de rédaction projet que dans la base Lead Tech durable. - ---- - -## unclear - -Aucune entrée classée `unclear`. - ---- - -## Intégré - -### 2026-03-19 - -- Intégré dans `10_backend_patterns_valides.md` : - - `Next.js runtime-only — orchestration en bord et logique pure testable` -- Cette intégration absorbe les propositions proches suivantes : - - `Isolation des guards purs des modules server-only` - - ``server-only` réservé aux modules avec APIs Next.js exclusivement serveur` - - `Server Action Next.js — isoler la logique pure dans un module injectable` -- La proposition `server-only dans les repositories bloque les tests unitaires` n’a pas été intégrée comme risque autonome ; son signal utile est couvert par le pattern fusionné ci-dessus. - ---- - -## Synthèse - -- **Candidates solides après fusion :** - - famille `server-only` / Server Actions / logique pure testable - - suppression de session idempotente (`P2025`) si on assume un pattern Prisma ciblé -- **À ne pas intégrer en l’état :** - - progression V1 sans persistance dédiée - - divergence schéma / spec story -- **Point principal de déduplication :** - - trois entrées parlent en pratique du même sujet : frontière runtime Next.js (`server-only`) vs logique pure testable. diff --git a/scripts/aliases.sh b/scripts/aliases.sh old mode 100644 new mode 100755