proto-note (annotation de prototype)

Couche d'annotation de changements de prototype (proto-note)

Superpose sur un prototype HTML mono-page un « guide de navigation des changements pour le développeur » : panneau d'annotation sombre fixe à droite (cases à cocher par module + cartes d'annotation) ↔ ancres numérotées sur la page + connecteurs canvas ; positionnement bidirectionnel au survol/au clic ; cartes d'annotation avec lien profond SDD.

Installation et structure

# Skill personnel (recommandé)
git clone https://github.com/pessimistcamellia/proto-note.git ~/.cursor/skills/proto-note

# Ou dans le projet
git clone https://github.com/pessimistcamellia/proto-note.git .cursor/skills/proto-note

Vous pouvez aussi copier l'intégralité du répertoire vers le chemin ci-dessus. Structure :

proto-note/
├── SKILL.md
├── assets/diff-annotator.js      # Moteur d'annotation (à intégrer tel quel dans le prototype, ne pas modifier la logique)
├── references/changeset-schema.md
├── docs/screenshots/             # Captures d'écran du README
└── scripts/deploy_github.sh      # Déploiement alternatif GitHub Pages

Dépendances d'environnement

Capacité	Outil	En cas d'absence
Localisation du stack technique / code source	codewiki MCP (ou équivalent de recherche de code)	Utiliser une URL en ligne + le dépôt source + le DOM du navigateur pour reconstituer
Lien profond SDD	lark-cli (Feishu)	Remplir manuellement l'URL du document et le blockId du chapitre ; si non-Feishu, lier à l'ancre du chapitre correspondant
Calibrage pixel perfect	DevTools du navigateur / chrome-devtools MCP	Ouvrir manuellement la page en ligne pour comparaison
Déploiement	Hébergement statique intranet (prioritaire)	GitHub Pages personnel (deploy_github.sh, nécessite autorisation gh)

Si l'équipe possède d'autres skills de normes front-end (ex. liste blanche de choix techniques, utilisation de la bibliothèque de composants), les lire selon les besoins avant la réalisation ; sinon, se baser sur le code source du dépôt cible et la documentation de l'équipe.

Plan par défaut : bibliothèque de composants et priorité de publication

Exécuter par ordre de priorité ; si une étape n'est pas disponible, passer à la suivante. La dernière étape est le fallback par défaut :

1. Bibliothèque de composants / normes (prioritaire) : utiliser la bibliothèque de composants et les normes réellement utilisées dans le système en ligne cible (vérifier le code source / le DOM / les skills de l'équipe). Interdiction de changer de bibliothèque sans justification.
2. Adresse de publication (prioritaire) : s'il existe un hébergement statique intranet existant (ou une adresse intranet convenue par l'équipe), publier d'abord sur l'intranet.
3. Fallback par défaut : si la bibliothèque de composants / normes réelles n'est pas disponible, ou si l'accès est impossible en raison de droits, de réseau, d'indisponibilité de l'intranet, etc. → les composants peuvent être choisis librement selon un plan générique (toujours en HTML mono-page interactif) ; publier sur le dépôt GitHub personnel (Pages) de l'utilisateur. Avant le déploiement, vérifier l'autorisation gh ; si non autorisé, communiquer d'abord avec l'utilisateur, interdiction de pousser vers un dépôt privé sans consentement.

Règles produit impératives

1. Trois niveaux de changement + type : page / module / champ ; types à distinguer : ajout, texte, plage énumérée, logique, flux, suppression. Interdiction d'étiqueter vaguement « ajout ».
2. Masquage par défaut, activation par module : ne pas afficher les annotations à l'ouverture ; activer par page::module ; l'état est stocké dans localStorage. Pour les modules ajoutés, la clé manquante par défaut est true (visible). Interdiction d'hériter du masquage d'un interrupteur précédemment désactivé ; l'état sale est nettoyé en mettant à niveau la version LS_KEY.
3. Lier uniquement au SDD, ne pas afficher le PRD : les cartes d'annotation utilisent URL du document SDD#blockId.
4. Informations concises : le panneau d'annotation ne contient pas de numéro de version, de ligne de base, d'instructions d'utilisation ; desc ne contient que la conclusion.
5. Tout clic doit être efficace : cocher un module déclenche le changement de vue + défilement + positionnement avec pulsation.
6. État de révision uniquement dans le panneau d'annotation : les états normal/vide/erreur, etc. sont placés dans demoControls ; les vrais onglets métier restent dans la page métier.
7. Les branches d'entrée donnent des exemples reproductibles : examples doivent correspondre au fixture ; interdiction de valeurs factices de substitution.
8. Le panneau d'annotation ne doit pas masquer le contenu : ne pas compresser la mise en page métier ; utiliser un espaceur pour étendre scrollWidth, le défilement horizontal permet de voir tout le côté droit. Interdiction d'ajouter uniquement body padding-right ou de modifier la largeur de la racine métier.
9. La bibliothèque de composants et les normes doivent donner la priorité au réel en ligne : si la restitution est possible, elle doit être effectuée (voir l'étape 1 du « Plan par défaut »). Même bibliothèque de composants ne signifie pas restitution – le squelette, les jeux/largeurs de colonnes, les colonnes figées, la structure des cellules, la disposition des colonnes d'action, les noms de classes personnalisés et les styles clés doivent être comparés au DOM/code source en ligne ; avant la livraison, faire des captures d'écran écran par écran pour comparaison. Ce n'est que si la bibliothèque de composants/normes réelles ne peut pas être obtenue qu'un fallback avec des composants génériques est autorisé.
10. Publication prioritaire sur l'intranet, sinon GitHub personnel : s'il existe une adresse intranet, l'utiliser en priorité ; sinon, publier sur GitHub Pages personnel (voir les étapes 2-3 du « Plan par défaut »).
11. « Avant » = état actuel en ligne : pour les ajouts, écrire « Cette page/module/fonction/champ n'existe pas » ; interdiction d'écrire des différences par rapport à la version précédente du démo ; les nouveaux points en ligne ne doivent pas être omis.
12. Pas de cible UI, pas de connexion : pour les flux/processus purs, target: null, pas d'ancre ; la carte est placée dans « Processus et flux · Page invisible », et classée à la fin des changements.
13. Changements dans une fenêtre modale : cliquer sur une carte d'annotation doit passer par DIFF_HOOKS.locate pour ouvrir la fenêtre modale avant de connecter ; l'ancre/le connecteur doit avoir un z-index supérieur à la fenêtre modale (le moteur utilise la plage 9000).
14. Fenêtre modale suit le défilement horizontal et vertical de la page : lorsque le panneau d'annotation est ouvert, le conteneur de la fenêtre modale se déplace avec (-scrollX,-scrollY) (le moteur gère cela) ; interdiction de verrouiller le défilement pour l'éviter.
15. Les objets téléchargeables doivent être au vrai format : les modèles/reçus doivent avoir le même format et la même structure que le vrai métier (ex. deux feuilles doivent être un vrai .xlsx), interdiction d'utiliser CSV pour usurper.
16. Réaliser plusieurs versions et les lier : pour le backend d'administration, le frontend C, etc., créer des HTML séparés par système ; un menu unifié indique « Système · Page » ; s'il y a des données inter-pages, simuler l'écriture/lecture/démarrage/arrêt/exception.
17. Les cartes d'annotation doivent pouvoir rediriger vers le SDD : lorsqu'un SDD existe, configurer sdd.section + blockId pour chaque changement (ou point de fonction concerné) ; la carte affiche un lien profond ; le clic doit ouvrir le chapitre correspondant, pas seulement écrire le nom du chapitre.

Spécifications de la couche d'affichage (déjà intégrées dans le moteur, ne pas revenir en arrière)

• Panneau d'annotation droit : bleu marine foncé, largeur 360px, peut être réduit à une entrée flottante.
• Défilement horizontal : utiliser document.body.scrollWidth pour mesurer la largeur métier (l'espaceur est en position:absolute, n'entre pas dans cette valeur) ; ne pas masquer d'abord l'espaceur pour mesurer. Restaurer le défilement avec behavior: "instant" pour éviter les conflits avec scroll-behavior: smooth.
• Ancres : coordonnées du document position:absolute, épinglées au coin supérieur gauche de la cible ; interdiction de fixed + suivi d'image ; masquer en cas d'obstruction avec elementFromPoint.
• Connecteurs : pas de fil en temps normal ; n'en dessiner qu'un au survol/au fixage ; l'état fixé prime sur l'état survolé ; le point de départ prend le rect en temps réel.
• Carte d'annotation : numéro + titre + type·niveau + conclusion + avant/après + SDD ; peut contenir examples.
• Zone de démo : segmented control en haut du panneau d'annotation → DIFF_HOOKS.setDemoState.

Restitution du stack technique (Étape 0)

Exécuter selon le « Plan par défaut » : restituer si possible ; sinon, enregistrer la raison puis utiliser le fallback de choix libre.

1. Si l'utilisateur n'a pas fourni d'URL en ligne → le rappeler d'abord ; si toujours rien, rechercher automatiquement le système/les routes/le code source.
2. Utiliser codewiki (ou recherche de code source) pour confirmer : framework, bibliothèque de composants, routes → fichiers de pages, extraits de templates clés ; si nécessaire, vérifier la fraîcheur de l'index et calibrer avec le DOM en ligne.
3. Priorité à l'utilisation de la bibliothèque de composants et des normes réelles du dépôt cible ; les nouveaux composants réutilisent les types/taille/disposition existants de la page. Même bibliothèque de composants ne signifie pas restitution – le squelette, les jeux/largeurs de colonnes, les colonnes figées, la disposition des colonnes d'action, les noms de classes personnalisés doivent être comparés au DOM/code source en ligne.
4. S'il existe un skill de normes d'équipe, le suivre ; sinon, se baser sur le dépôt cible et la documentation.
5. En cas de manque de données pixel perfect ou de recherche : ouvrir la page en ligne pour capturer le mode de montage, les noms de classes des composants, les largeurs de colonnes du tableau/colonnes figées, la structure de la colonne d'action, les styles computed personnalisés.
6. Le résultat reste un HTML mono-page ; si possible, utiliser un CDN pour importer le même framework/bibliothèque de composants. Si la restitution complète de la page est impossible, choisir librement une bibliothèque de composants courante pour réaliser le prototype interactif, et mentionner dans les notes de livraison la « raison de la non-restitution ».
7. Publication : s'il existe une adresse statique intranet, l'utiliser en priorité ; sinon, après avoir obtenu l'autorisation GitHub de l'utilisateur, utiliser deploy_github.sh pour publier sur le dépôt personnel.

Pièges fréquents : ne pas définir une min-width trop large sur le conteneur externe qui étoufferait le tableau (cela supprimerait le défilement interne et les colonnes fixed) ; la barre de menu unifiée utilise position:fixed, pour éviter que le défilement horizontal de la page large ne coupe la barre.

Multi-pages / Multi-systèmes et liaison de données

1. D'abord, lister la matrice : système → page → états clés → données amont/aval ; différents stacks techniques dans des fichiers séparés, ne pas forcer la fusion.
2. Menu unifié : nommer « Système · Page », mettre en évidence la page courante ; le menu ne fait pas d'annotation de changement.
3. Déployer dans le même répertoire de même origine pour garantir le partage du localStorage.
4. Clé d'état partagé : proto-note:<requirement-slug>:state:v1 ; après lecture/écriture, dispatcher un événement sur la même page, écouter storage entre les onglets.
5. L'URL ne contient que l'ID métier ; le contenu est dans l'état partagé. Si les origines sont différentes, privilégier la modification pour les rendre identiques, sinon utiliser postMessage et vérifier l'origin.
6. Intégrer un fixture + « Réinitialiser les données de démo » ; les états amont/aval et les exceptions doivent être reproductibles.

Workflow

0. Étape 0 : Restitution du stack technique.
1. Extraire la liste des changements, la matrice systèmes/pages, les branches d'entrée et les relations de données inter-pages à partir du PRD → voir references/changeset-schema.md.
2. Récupérer le blockId SDD et l'écrire dans chaque sdd.
3. Réaliser le prototype par système ; pour les systèmes multiples, ajouter un menu et un état partagé et vérifier la liaison.
4. Intégrer la couche d'annotation :
   • Ajouter data-diff-page au conteneur ; compléter les cibles avec un id ; implémenter DIFF_HOOKS.locate / setDemoState.
   • Déplacer l'onglet de révision dans meta.demoControls.
   • Écrire les branches dans examples (correspondant au fixture).
   • Avant </body>, intégrer DIFF_CHANGESET, puis copier le bloc entier de la version la plus récente de assets/diff-annotator.js (ne pas utiliser une copie obsolète).
5. Déploiement et auto-vérification :

   • Priorité intranet : s'il existe un hébergement statique intranet existant, y télécharger ; si la clé d'objet n'est pas écrasée, utiliser un nouveau chemin (-v2, etc.) ; se baser sur l'URL retournée + md5.

   • Fallback GitHub Pages : si l'intranet n'est pas disponible, publier sur le dépôt personnel. D'abord gh auth status ; si pas de droits, communiquer et effectuer gh auth login. Interdiction de pousser vers un dépôt privé sans autorisation :

     bash ~/.cursor/skills/proto-note/scripts/deploy_github.sh <slug> ./index.html
     

Liste d'auto-vérification

• Si la restitution est possible, utiliser la bibliothèque de composants/normes réelles en ligne ; sinon, noter la raison et utiliser le fallback de choix libre
• Publication prioritaire sur l'intranet ; si l'intranet est indisponible, publier sur GitHub personnel après autorisation
• Comparaison écran par écran avec la version en ligne (si page en ligne : largeurs de colonnes, colonnes figées, colonne d'action, pagination, barre supérieure)
• Pas d'ancre/connecteur au départ ; modules non cochés ; les modules ajoutés sont visibles par défaut pour les anciens visiteurs
• Cocher un module n'affiche que la carte/l'ancre/le connecteur correspondant, avec positionnement automatique ; les changements dans une fenêtre modale s'ouvrent automatiquement et le connecteur est au-dessus de la fenêtre
• Pas de dérive des ancres au défilement ; pas de fil en temps normal, un seul fil au fixage/survol ; l'état fixé n'est pas capté par le hover
• Le panneau d'annotation ouvert permet un défilement horizontal pour voir tout le côté droit ; la position de défilement n'est pas réinitialisée par les mises à jour du DOM ; la fenêtre modale suit le défilement horizontal et vertical de la page
• target:null n'a pas d'ancre ; la carte est dans « Processus et flux » et en fin de liste ; « Avant » correspond à l'état en ligne, aucun oubli
• Le lien profond SDD sur la carte d'annotation s'ouvre et se positionne sur le chapitre correspondant
• L'état de démonstration est uniquement dans le panneau d'annotation ; examples sont reproductibles ; le format de l'objet téléchargeable est correct
• Le menu multi-systèmes est accessible ; la lecture/écriture inter-prototytypes, le rafraîchissement, les onglets multiples et la réinitialisation sont cohérents
• Le panneau d'annotation réduit est propre ; l'interaction métier n'est pas affectée

Références

• README.md de ce dépôt (captures d'écran, Live demo, description du plan par défaut)
• Live demo : https://pessimistcamellia.github.io/non-ecommerce-thirdparty-order-prototype/admin-upload.html