bright-y/prototype-maintenance

Maintenance de Prototype

Utilisez cette compétence pour rendre un prototype existant plus facile à modifier sur de nombreux cycles d'itération produit.

L'objectif n'est pas de reconcevoir le produit. Préservez le comportement actuel et la direction visuelle tout en améliorant la maintenabilité, la propriété des fichiers et la vitesse de validation.

Périmètre et Remise

• Utilisez cette compétence pour l'itération structurelle continue et la cartographie de la propriété dans un prototype existant. Pour un découpage ou un conditionnement statique de première fois, utilisez static-prototype-splitter lorsqu'il est disponible ; ce n'est pas une dépendance requise.
• Une petite demande de copie, de mise en page ou de comportement ne nécessite pas une refonte complète des répertoires. Ne divisez que les responsabilités pertinentes pour la demande.
• Conservez le nom de fichier d'entrée existant, le framework, le modèle de script et le flux de travail d'aperçu. La mise en page app.html ci-dessous est un exemple, pas une exigence de renommage.
• Suivez les règles d'autorisation de l'utilisateur pour le remplacement de fichiers, la configuration, les dépendances, l'accès réseau, les serveurs locaux et les données stockées. Cette compétence n'accorde pas ces autorisations.

Quand Déclencher

Déclenchez cette compétence lorsque l'utilisateur demande de :

• Améliorer la vitesse de modification ultérieure du prototype.
• Diviser le JS par page, composant, champ, modale, store ou couche de données.
• Diviser le CSS par les périmètres base, layout, page, composant, modale et champ.
• Séparer les données mock, les données de seed, les schémas et la logique d'état/store.
• Créer ou mettre à jour un README de maintenance de prototype.
• Créer ou mettre à jour un CHANGE-MAP qui fait correspondre les futures demandes aux fichiers.
• Continuer à optimiser un prototype interactif existant.
• Faire en sorte qu'un aperçu combiné et des fichiers divisés restent maintenables ensemble.
• Expliquer où une future modification du prototype devrait être effectuée.

Principes par Défaut

• Suivez le langage de l'utilisateur et la terminologie existante du prototype.
• Lisez l'entrée actuelle et les références de script actives avant de modifier.
• Conservez la conception visuelle originale et l'intention d'interaction, sauf si l'utilisateur demande une refonte.
• Ne réécrivez pas tout dans un framework, sauf demande explicite.
• Évitez une seconde implémentation divergente. L'aperçu combiné doit charger les modules partagés/divisés ou être généré à partir d'eux.
• Gardez les modifications concentrées sur la maintenabilité et le comportement demandé du produit.
• Le fractionnement n'est pas terminé lorsque de nouveaux fichiers sont simplement ajoutés. Chaque fractionnement doit également réduire la responsabilité de l'ancien fichier afin que les futures modifications aient un propriétaire évident.
• Gardez les modifications non liées intactes et préservez les fichiers d'entrée d'origine et les fichiers remplacés. Concentrez les modifications autorisées sur l'implémentation active ; ne supprimez pas les fichiers hérités et ne remplacez pas les documents protégés sans approbation.
• Après les modifications, vérifiez la syntaxe et l'interaction principale de l'aperçu lorsque c'est pratique.

Structure Recommandée

Adaptez les noms au projet, mais préférez cette forme pour les prototypes interactifs statiques :

prototype/
├── app.html
├── README-prototype.md
├── CHANGE-MAP.md
├── assets/
│   ├── css/
│   │   ├── base.css
│   │   ├── layout.css
│   │   ├── components.css
│   │   ├── modals.css
│   │   ├── fields.css
│   │   └── pages/
│   │       ├── home.css
│   │       ├── editor.css
│   │       └── fill.css
│   └── js/
│       └── app/
│           ├── core.js
│           ├── runtime.js
│           ├── pages/
│           ├── components/
│           ├── fields/
│           ├── modals/
│           ├── data/
│           ├── store/
│           └── utils/
└── pages/
    └── ...

Utilisez des noms équivalents lorsque le domaine du prototype diffère. L'important est le fractionnement des responsabilités.

Pour les petits prototypes, une structure plus plate est acceptable. Pour les prototypes qui changent fréquemment, préférez la structure de répertoires ci-dessus afin que chaque demande future corresponde à un petit fichier.

Responsabilités des Couches

Couche d'Entrée

Conservez l'entrée d'aperçu combiné actuelle ; app.html est le nom d'exemple utilisé ci-dessous.

Elle doit contenir :

• Cadre d'appareil ou coque d'aperçu, le cas échéant.
• Conteneur racine.
• Liens CSS.
• Références de script ordonnées.

Elle ne doit pas contenir la plupart de la logique métier.

Couche Page

Utilisez des fichiers de page pour le rendu de page et la mise en page spécifique à la page :

• Accueil/liste/recherche/onglets.
• Page d'édition/création/édition.
• Page de remplissage/aperçu/soumission/détail.
• Pages de connexion/inscription/onboarding.
• Pages de paramètres/compte.

Lorsque l'utilisateur demande de modifier une mise en page de page ou une copie de page, commencez ici.

Si un fichier de page contient plusieurs sous-vues fréquemment modifiées, divisez-le à nouveau. Exemple :

pages/home/
├── index.js
├── search.js
├── my-forms.js
└── submitted.js

Couche Champ ou Composant

Utilisez des fichiers champ/composant pour les blocs d'interface utilisateur répétés :

• Étiquettes de type de champ.
• Valeurs par défaut des champs.
• Aperçu du champ dans l'éditeur.
• Contrôles de la page de remplissage.
• Rendu d'upload/image/fichier/radio/checkbox/OCR/date.

Lorsque l'utilisateur demande de modifier un type d'élément, évitez de rechercher toute l'application d'abord. Commencez par les fichiers de configuration et de rendu des champs.

Lorsqu'un prototype a de nombreux contrôles de formulaire ou cartes répétées, préférez les registres :

fields/
├── registry.js
├── text.js
├── image.js
├── file.js
├── options.js
└── ocr.js

Couche Modale

Utilisez des fichiers modaux pour :

• Feuille de paramètres de champ.
• Feuille de sélecteur de type.
• Tiroir de tri.
• Boîtes de dialogue de confirmation.
• Feuille de bibliothèque d'ajout d'élément.

Gardez l'état de la modale local lorsque c'est possible, et ne validez les données qu'après les actions de confirmation.

Couche Données

Séparez les données du comportement du store.

Utilisez data/ pour :

• Modèles mock.
• Listes d'industries/catégories.
• Définitions de types de champs.
• Utilisateurs et exemples de démonstration.
• Enregistrements de seed et fixtures.

Utilisez store/ pour :

• Clés de stockage local.
• Sauvegarde/suppression/mise à jour de formulaire.
• Sauvegarde/suppression/mise à jour d'enregistrement de soumission.
• Normalisation des données et migrations.

Ne mélangez pas les règles de stockage dans les rendus de page, sauf si le prototype est très petit.

Lorsque des données locales existantes peuvent déjà exister, préservez leurs clés et les modifications de l'utilisateur. Ajoutez uniquement les enregistrements de seed manquants par des ID stables et rendez le seeding idempotent ; ne réécrivez pas les enregistrements modifiés, ne dupliquez pas les éléments et ne réinitialisez pas le stockage local lors du rechargement. Traitez les migrations de schéma comme une opération distincte et autorisée avec un chemin de récupération documenté.

Couche CSS

Divisez le CSS par propriété, pas seulement par taille :

• base.css : variables, reset, typographie.
• layout.css : coque, cadre d'appareil, conteneur de page, primitives de grille.
• components.css : boutons, entrées, cartes, onglets, chips.
• modals.css : feuilles, tiroirs, boîtes de dialogue de confirmation, toast.
• fields.css : contrôles de champ et aperçus d'éléments de formulaire.
• pages/*.css : mise en page et exceptions spécifiques à la page.

Si un sélecteur est réutilisé sur plusieurs pages, conservez-le dans components ou fields. S'il est spécifique à une page, déplacez-le dans le CSS de cette page.

Couche Journal des Modifications

Ajoutez CHANGE-MAP.md pour les prototypes censés recevoir de nombreux cycles de modifications.

Il doit mapper les demandes utilisateur courantes directement aux fichiers :

# Change Map

## Pages
- Page d'accueil : assets/js/app/pages/home/index.js
- Page de modèle : assets/js/app/pages/templates/index.js
- Éditeur de formulaire : assets/js/app/pages/editor/index.js

## Champs
- Champ d'upload d'image : assets/js/app/fields/image.js
- Champ d'upload de fichier : assets/js/app/fields/file.js
- Champs radio/checkbox : assets/js/app/fields/options.js

## Modales
- Modale de paramètres de champ : assets/js/app/modals/field-settings.js
- Tiroir de tri : assets/js/app/modals/sort.js

## Données
- Données de modèles : assets/js/app/data/templates.js
- Catégories d'industries : assets/js/app/data/industries.js

## Styles
- Styles de page de modèle : assets/css/pages/templates.css
- Styles de champ : assets/css/fields.css

Gardez CHANGE-MAP court. C'est un index d'édition, pas une documentation produit.

Couche Runtime

Utilisez des fichiers runtime pour :

• Distribution du routeur/rendu.
• Délégation d'événements.
• Gestion des gestes.
• Distribution d'actions.
• Amorçage.

Si le runtime devient volumineux, divisez-le par type d'interaction, mais gardez un point d'entrée clair.

README de Maintenance

Lorsque demandé, ajoutez ou mettez à jour README-prototype.md dans la racine du prototype.

Incluez :

• Point d'entrée d'aperçu total.
• URL d'aperçu local et ports réservés, le cas échéant.
• Mappage page-vers-fichier.
• Mappage champ/composant-vers-fichier.
• Mappage modale-vers-fichier.
• Emplacement de la couche de données.
• Emplacement de la couche CSS.
• Emplacement de CHANGE-MAP.
• Comment rafraîchir et valider après les modifications.
• Exemples courants de changements futurs, comme "modifier le champ d'upload d'image" ou "modifier la page de soumission de formulaire".

Gardez-le concis et utile. Il est destiné aux humains qui maintiennent le prototype, pas à un long journal de développement.

Flux de Travail

1. Inspectez les fichiers d'entrée actifs.

   • Utilisez rg --files, grep et des lectures ciblées.
   • Confirmez quels scripts sont réellement chargés par l'aperçu combiné.
   • Ne supposez pas que les fichiers divisés existants sont actifs.

2. Identifiez la propriété actuelle.

   • Renders de page.
   • Renders/configurations de champ.
   • Modales/tiroirs.
   • Helpers store/données.
   • Gestionnaires d'événements runtime.

3. Divisez avec soin.

   • Préférez d'abord l'extraction mécanique lorsque la préservation du comportement est importante.
   • Gardez l'ordre de chargement des scripts explicite dans app.html.
   • Évitez de modifier le comportement pendant le fractionnement, sauf si l'utilisateur a également demandé des changements de comportement.
   • Après avoir extrait un module, supprimez ou réduisez la responsabilité correspondante de l'ancien fichier. Ne laissez pas deux propriétaires actifs pour la même page, le même composant, la même modale, le même ensemble de données ou le même sélecteur CSS.
   • Laissez les fichiers combinés hérités inutilisés plutôt que de les supprimer, sauf si l'utilisateur confirme la suppression.
   • Préservez le modèle de script classique ou ES-module existant. Vérifiez l'ordre de chargement, les exports et les gestionnaires d'événements en ligne après avoir déplacé les fonctions.
   • Rendez les responsabilités de montage/démontage de vue explicites. Supprimez les écouteurs et minuteries obsolètes lors du départ d'une vue afin que la navigation répétée ne duplique pas les actions.

4. Divisez les données lorsque les données augmentent.

   • Déplacez les grandes données mock hors des renders de page et des fichiers store.
   • Gardez les fixtures de seed déterministes et faciles à parcourir.
   • Fusionnez les nouvelles données de seed dans les données locales existantes lorsque c'est possible.
   • Si les données sont déplacées vers data/, faites en sorte que les fichiers store/état consomment ces données au lieu de conserver une copie active en double.

5. Divisez le CSS lorsque les changements visuels deviennent lents.

   • Commencez par base/layout/components/pages.
   • Déplacez les sélecteurs propres à une page dans le CSS de la page.
   • Déplacez les contrôles réutilisables dans le CSS des composants ou des champs.
   • Après avoir déplacé les sélecteurs, supprimez les sélecteurs actifs en double de la feuille de style globale précédente, sauf s'ils sont intentionnellement conservés en tant que styles de composants partagés.
   • Préservez l'ordre de cascade et les points d'arrêt réactifs ; rebasez les chemins CSS url(...), les polices et les chemins d'importation par rapport au nouvel emplacement du fichier.

6. Mettez à jour ou créez README et CHANGE-MAP.

   • Documentez la structure active finale.
   • Rendez clair quel fichier éditer pour les futures demandes courantes.
   • Incluez l'URL d'aperçu local, les ports réservés et les instructions de cache busting lorsque cela est pertinent.

7. Vérifiez.

   • Vérifiez récursivement les fichiers JavaScript réellement possédés par le prototype, y compris les fichiers de page/composant imbriqués. Lorsque Python et Node sont déjà disponibles, cet exemple vérifie .js, .mjs et .cjs sous assets/js ; adaptez la racine au projet. N'installez pas d'environnements d'exécution juste pour l'exécuter.

     python3 - <<'PY_CHECK'
     from pathlib import Path
     import subprocess
     import sys
     
     root = Path("assets/js")
     files = sorted(p for p in root.rglob("*")
                    if p.is_file() and p.suffix in {".js", ".mjs", ".cjs"}
                    and not {"node_modules", "vendor", ".git"}.intersection(p.parts))
     if not files:
         sys.exit("Aucun fichier JavaScript trouvé ; vérifiez la racine de vérification.")
     failed = False
     for path in files:
         failed |= subprocess.run(["node", "--check", str(path)]).returncode != 0
     sys.exit(1 if failed else 0)
     PY_CHECK
     

   • Pour les projets framework ou un mode de module différent, utilisez les vérifications de projet existantes. Un passage de syntaxe ne prouve pas le comportement du navigateur.
   • Ouvrez l'aperçu combiné.
   • Comparez le comportement affecté avec la base de référence, y compris la navigation avant/arrière, la revisite de la vue modifiée, la confirmation/annulation de la modale et l'état enregistré après le rafraîchissement, le cas échéant.
   • Vérifiez les erreurs de la console du navigateur lorsque c'est pratique.

Règles de Granularité de Fractionnement

Utilisez ces règles pour éviter à la fois le sous-fractionnement et le sur-fractionnement :

• Si un fichier est modifié à plusieurs reprises pour des demandes non liées, divisez-le.
• Si une page contient plusieurs sous-vues qui changent indépendamment, divisez les sous-vues.
• Si les données mock prennent plus de place que la logique qui les entoure, déplacez-les vers data/.
• Envisagez fields/ lorsque plusieurs types de champs/contrôles changent indépendamment ; ne divisez pas uniquement pour atteindre un nombre.
• Envisagez modals/ lorsque les boîtes de dialogue ou les tiroirs ont des besoins de maintenance ou d'état distincts.
• Si les modifications CSS nécessitent de rechercher une grande feuille de style globale, divisez par page et composant.
• Si un fichier est stable et rarement modifié, ne le divisez pas uniquement pour l'esthétique.

Aides à la Validation

Préférez une validation simple et sans dépendance pour les prototypes statiques :

• Utilisez node --check pour la syntaxe JS.
• Pour le cache busting, substituez une valeur réelle, par exemple app.html?t=20261109-153000 ; Date.now() tapé littéralement dans une URL est une chaîne fixe. Une simple requête HTML ne rafraîchit pas le JS/CSS mis en cache séparément, alors utilisez les contrôles de cache du navigateur ou la stratégie de versionnement des actifs existante si nécessaire.
• Gardez le port d'aperçu local stable lorsque l'utilisateur en a choisi un.
• Vérifiez l'interaction modifiée dans le navigateur après des refontes structurelles.
• L'ouverture directe du fichier est acceptable pour les pages statiques compatibles. Les fragments récupérés et les modules ES du navigateur nécessitent généralement HTTP ; documentez le mode d'ouverture et réutilisez le serveur d'aperçu existant lorsqu'il est disponible. Le démarrage d'un nouveau serveur suit les règles d'autorisation de l'utilisateur.

Style de Réponse

Lorsque vous terminez, dites à l'utilisateur :

• Ce qui a été divisé ou documenté.
• Le fichier d'entrée actif.
• Les chemins de nouveaux fichiers les plus importants.
• Si README-prototype.md ou CHANGE-MAP.md a été créé ou mis à jour.
• Quelle vérification a été effectuée.
• Tous les fichiers hérités laissés en place intentionnellement.

Gardez la réponse finale courte et pratique.