# AGENTS.md — Règles de développement · SensiTools Ce fichier cadre le travail de tout agent (Claude, Codex…) sur ce dépôt. **À lire au début de CHAQUE session, avant de coder.** En cas de doute, on demande plutôt que d'inventer. Si une règle ci-dessous est enfreinte, on corrige avant de continuer. --- ## 1. Principes fondateurs (non négociables) 1. **Cause racine, pas de patch.** On ne bidouille pas un rustine qui masque le symptôme : on cherche la cause, on la comprend, on répare à la source — sans emporter le métier au passage. 2. **On réutilise avant de créer (composants UI).** Avant de créer un composant, on regarde les composants existants. On n'en crée un nouveau **que si** aucun ne convient — et alors on le conçoit pour être réutilisable, pas jetable. 3. **Idem pour tout élément de base de données ou composant technique** (table, colonne, entité, service, endpoint, classe utilitaire) : on réutilise ou on étend l'existant avant d'ajouter du neuf. --- ## 2. Atomic design & couche de composants - La couche UI = **includes Twig** dans `templates/components/*.twig` (`button`, `badge`, `person`, `status`, `unit_menu`, `project_select_menu`, `project_subnav`…). Inventaire vivant sur **`/admin/composants`**. - Avant toute UI : chercher l'**atome / molécule** existant. **Étendre** le composant partagé (ajouter un paramètre `variant`/`size`/…) plutôt que forker une variante locale qui diverge. - Un composant = **une responsabilité**, paramétré, sans duplication de styles. Ce qu'il remplace est documenté dans son en-tête (cf. `button.html.twig`). - **Un concept est conçu une seule fois.** Si deux pages ont le même en-tête, c'est le **même** composant (ex. la barre de contexte projet partagée entre Planning, Cadrage, Droits, Jalons). - On reste sur des **includes simples**. Pas de `ux-twig-component` (provoque une boucle dans ce projet). --- ## 3. Architecture (la boussole) - **Le métier au centre, les technos en périphérie.** - **Un concept conçu une fois** (voir §2). - **Quand une source est coupable, on répare la source** sans casser le métier autour. - Layout des modules : `App\` + `App\Integration` (le fourre-tout `src/Service` est dissous). Les entités ne sont pas déplacées. --- ## 4. Base de données & migrations - **Migrations écrites À LA MAIN.** **JAMAIS** `doctrine:migrations:diff` : le diff Doctrine **DROP** les tables SQL brut (`personal_*`, `project_planning_presence`…) qu'il ne connaît pas. - Colonnes/tables **additives** avec **valeur par défaut** → zéro impact sur l'existant. - Après migration : `doctrine:schema:validate`. Un « not in sync » résiduel de **renommage d'index** est du bruit pré-existant (toléré, conséquence des migrations manuelles) — mais on vérifie que ce n'est bien que ça. - On réutilise les champs existants avant d'en ajouter (ex. `plannedHours` **est déjà** le vendu au niveau fin : on clarifie via un alias, on ne duplique pas la colonne). --- ## 5. Sécurité (non négociable) - **Jamais** manipuler, demander ou saisir un mot de passe — même en local. On donne la procédure à l'utilisateur. - **Autorisations projet** : visibilité **globale** (petite agence) ; **édition par projet** via `ProjectVoter` (CP/DP du projet, responsable de pôle, Direction, Admin). - Attention au **décalage pare-feu / voter** : `security.yaml` filtre sur le **rôle global**, l'accès métier se joue **par projet** dans le voter (cas Camille : CP *du projet* ≠ rôle global `ROLE_PROJECT_MANAGER`). - Les rôles viennent de `collaborators.json` (source de vérité, rapprochement par **email**) via `app:accounts:bootstrap` — à rejouer après tout changement de rôle. --- ## 6. Données & personnes - `collaborators.json` = **source de vérité** des personnes. Une personne absente n'est **jamais créée à la volée** — elle est signalée. - **Import projets** : `scripts/dump_xlsx.py` (dump compact, peu de jetons) → JSON (schéma `docs/CONSIGNE_IMPORT_PROJETS.md`) → `app:projects:import` (création seule, jamais d'écrasement). On **écrase toujours** le tampon `config/fixtures/projects_from_excel.json` (hors Git). --- ## 7. Ne pas casser l'existant - Les zones stables/sensibles se touchent **sur demande explicite** et avec l'esprit « ne rien casser » (ex. onglet Planning : header gelé, équipe figée, drag/resize). - On **réutilise les mécanismes existants** plutôt que d'en bâtir un parallèle (ex. les endpoints `restore` du planning ont servi de base à l'undo côté client). --- ## 8. Qualité & vérification (avant de dire « c'est fait ») - Lint systématique : `php -l`, `bin/console lint:twig`, `bin/console lint:yaml`, `bin/console doctrine:schema:validate`. - Vérifier que la route répond (`curl` → 302/200), sans casser au rendu. - **Rendre compte fidèlement** : si ce n'est pas testé (ex. pas de login), le dire. Pas de survente ; un échec se rapporte tel quel. - **CSS** : bumper le cache-buster `?v=` dans `base.html.twig` à **chaque** modif de `public/styles/app.css`. - Theming : passer par les **tokens / classes existantes**, pages theme-aware. --- ## 9. Déploiement - Cible **OVH**, dév local **Docker** (`docker compose exec -T app …`, `-T database`). - **L'agent ne pousse pas.** Le `git` du terminal n'est pas connecté : c'est **l'utilisateur qui pousse à la main**. L'agent commit en local et **fournit les commandes** (pas de `git push` inutile dans les consignes). - Déploiement OVH (à lancer par l'utilisateur, après son push) : ```bash ssh sensipod@ssh.cluster102.hosting.ovh.net cd ~/apps/SensiTools-Gestion-de-Projet/sos-symfony && bash scripts/deploy.sh ``` `deploy.sh` enchaîne : sauvegarde → récupération du code → dépendances → migrations → **`cache:clear` + `cache:warmup`**. - Vidage de cache seul (sans redéployer) : ```bash php bin/console cache:clear && php bin/console cache:warmup ``` - Fichiers **hors Git** (fixtures de données réelles) : transfert par `scp`, jamais via `git`. --- ## 10. Style de collaboration - Avancer par **étapes plus grandes**, moins de narration : on fait et on montre. - Français. Code lisible qui **ressemble au code environnant** (densité de commentaires, nommage, idiomes du fichier).