# Sommaire du Cahier des Charges Technique : Circuy

Ce document traduit le [cahier des charges fonctionnel](../functional/Sommaire.md) en décisions techniques implémentables. Chaque chapitre tranche ; les alternatives écartées sont consignées dans le registre d'ADR du chapitre 0.

**Périmètre V1 :** SDK client, extension d'édition, backend, dashboard, analytics. Le module IA « Page-Skill » et l'architecture event-driven à webhooks sont hors périmètre et traités en chapitre 10 comme extensions futures.

---

### **0. Périmètre, Hypothèses et Registre des Décisions**
* **0.1. Périmètre V1 et exclusions explicites** : ce qui est construit, ce qui est reporté, et pourquoi.
* **0.2. Hypothèses de charge** : volumétrie cible chiffrée servant de référence à tous les dimensionnements.
* **0.3. Registre d'ADR** : décisions structurantes, alternative ennuyeuse rejetée, coût opérationnel accepté.
* **0.4. Écarts assumés avec le cahier fonctionnel** : points où le besoin fonctionnel est amendé, et justification.

### **1. Architecture Générale et Structure du Dépôt**
* **1.1. Vue d'ensemble** : les quatre briques et leurs frontières de confiance.
* **1.2. Structure du monorepo** : découpage en paquets pnpm, règles de dépendance entre paquets.
* **1.3. Le paquet partagé** : schémas de validation et types, source unique de vérité des contrats.
* **1.4. Outillage** : gestionnaire de paquets, compilation, formatage, lint, versions figées.

### **2. Contrat JSON de Parcours et Modèle de Données**
* **2.1. Le contrat de parcours** : forme JSON complète, types d'étapes, déclencheurs, branchements.
* **2.2. Le contrat de cible** : représentation d'un sélecteur multi-critères et de ses replis.
* **2.3. Versionnage** : identité stable des étapes, brouillon contre version publiée, immutabilité.
* **2.4. Schéma PostgreSQL** : tables, contraintes, index justifiés, stratégie de migration Drizzle.
* **2.5. Modèle multi-locataire** : organisation, projet, clé d'API, cloisonnement des données.

### **3. SDK Client**
* **3.1. Intégration et amorçage** : snippet, chargement différé, cycle de vie, budget de performance.
* **3.2. Moteur de rendu** : couche Circuy sur `@floating-ui/dom`, isolation Shadow DOM, thème.
* **3.3. Résolution de cible** : ordre de repli de l'auto-healing, attente d'élément, abandon contrôlé.
* **3.4. Machine d'exécution** : progression, branchements, navigation multi-pages, support des SPA.
* **3.5. Persistance locale** : forme stockée, TTL, conventions de nommage, purge.
* **3.6. Télémétrie** : événements émis, transport Beacon, dégradation silencieuse.
* **3.7. Accessibilité** : navigation clavier, gestion du focus, rôles ARIA, `prefers-reduced-motion`.

### **4. Extension d'Édition**
* **4.1. Architecture WXT** : entrypoints, service worker, content script, messagerie interne.
* **4.2. Overlay d'édition** : isolation, modes de positionnement, non-interférence avec le site hôte.
* **4.3. Inspecteur visuel** : survol, capture, algorithme de génération du sélecteur multi-critères.
* **4.4. Édition des étapes** : formulaire, assainissement du contenu riche, édition des branchements.
* **4.5. Prévisualisation fidèle** : réutilisation du moteur de rendu du SDK, écarts assumés.
* **4.6. Publication** : validation locale, envoi authentifié, gestion des conflits d'édition.

### **5. Backend et API**
* **5.1. Surface d'API** : endpoints publics de lecture et endpoints privés d'administration.
* **5.2. Validation et contrats** : schéma partagé aux frontières, codes d'erreur, versionnage d'API.
* **5.3. Publication** : transaction de publication, génération de la version distribuable.
* **5.4. Moteur de ciblage** : répartition des règles entre serveur et client, format et évaluation.
* **5.5. Ingestion des analytics** : endpoint de collecte, validation, protection contre l'abus.
* **5.6. Agrégation** : calcul des taux de complétion et des abandons, fraîcheur acceptée.

### **6. Dashboard**
* **6.1. Périmètre V1** : écrans strictement nécessaires, et ce qui est volontairement absent.
* **6.2. Architecture front** : application servie en statique, authentification, appels API typés.
* **6.3. Restitution des analytics** : tunnel par étape, statistiques de choix, exports.
* **6.4. Modération** : gestion des statuts de parcours et journal des publications.

### **7. Distribution, Cache et Environnements**
* **7.1. Noms de domaine et distribution du SDK** : découpage des hôtes, versionnage du script, politique de compatibilité ascendante.
* **7.2. Distribution des parcours** : manifeste court-caché et versions immuables, sans purge propriétaire.
* **7.3. En-têtes et clés de cache** : `Cache-Control`, `ETag`, variation par clé publique et par chemin.
* **7.4. Hébergement souverain** : cible d'infrastructure, topologie de déploiement, sauvegardes.
* **7.5. Environnements** : développement, recette, production, et promotion entre eux.
* **7.6. Observabilité** : journaux, métriques minimales, alertes qui réveillent un humain.

### **8. Sécurité, Authentification et RGPD**
* **8.1. Frontières de confiance** : ce qui est validé, où, et contre quoi.
* **8.2. Clé publique du SDK** : nature, restriction par domaine, ce qu'elle n'autorise pas.
* **8.3. Authentification des administrateurs** : méthode retenue en V1, sessions, révocation.
* **8.4. Authentification de l'extension** : obtention et stockage du jeton, renouvellement.
* **8.5. Contenu injecté** : assainissement, politique de sécurité de contenu, protection du site hôte.
* **8.6. RGPD** : données réellement collectées, base légale, rétention, sous-traitance, droits.

### **9. Tests et Qualité**
* **9.1. Stratégie par brique** : ce qui est testé unitairement, ce qui exige un navigateur réel.
* **9.2. Banc d'essai de la résilience** : pages de référence dont le DOM change, validation de l'auto-healing.
* **9.3. Intégration continue** : étapes, seuils bloquants, durée cible.

### **10. Extensions Futures**
* **10.1. Module IA « Page-Skill »** : conditions d'entrée, risques identifiés, impacts sur l'existant.
* **10.2. Synchronisation event-driven** : cas d'usage réels attendus avant construction.
* **10.3. Critères de déclenchement** : ce qui doit être mesuré avant d'ouvrir ces chantiers.

### **11. Roadmap et Lots de Développement**
* **11.1. Séquencement** : ordre des lots et dépendances entre eux.
* **11.2. Définition de terminé** : critères de sortie de chaque lot.
* **11.3. Premier jalon démontrable** : la plus petite boucle de bout en bout qui prouve le produit.