# CLAUDE.md — Memoire projet (site vitrine + admin)

Ce fichier est lu par tous les sous-agents. Il fait autorite. En cas de doute,
on suit CLAUDE.md avant toute autre convention.

> ## A LIRE EN PREMIER si tu reprends ce projet
>
> **[docs/reprise-projet.md](docs/reprise-projet.md)** — etat reel du projet
> (EN PRODUCTION sur www.biome.immo), facon de travailler convenue avec le
> client, integrations et leur avancement, sujets encore ouverts, et surtout la
> liste des **pieges qui ont deja coute du temps** (sorties reseau KO en SSH,
> config:cache interdit, SMTP bloque, faux positifs de code mort...).
>
> Le present fichier dit ce qu'il FAUT FAIRE ; celui-la dit OU EN EST le projet
> et ce qui a deja mal tourne.

## 1. Objectif

Reproduire A L'IDENTIQUE une maquette web (concue dans Claude Design) et lui
ajouter un back-office pour gerer les sections editables du site : contenus
de pages (Accueil, Qui-sommes-nous, Investir, guide Actualites), actualites,
offres d'emploi, partenaires, realisations (galerie), et la consultation des
formulaires recus.

La fidelite visuelle au design source est un critere de reussite non negociable :
memes couleurs, polices, espacements, breakpoints, comportements.

Note (chantier mobile termine) : la maquette source est **desktop-only**
(aucune version mobile/tablette fournie par Claude Design). Le rendu desktop
(`>1024px`) reste donc la reference pixel-perfect, strictement inchangee. Le
responsive mobile (`<=480px`) et tablette (`481-1024px`) est une adaptation
distincte, concue et validee par le client (Laurent, 2026-07-03), pas une
reproduction d'une maquette mobile qui n'existe pas. Detail complet,
justification et methode de recette : `docs/mobile-strategie.md`.

## 2. Stack

- PHP 8.2+ / Laravel (derniere version LTS/stable)
- Filament pour le back-office (CRUD, auth, upload, tableaux)
- Base de donnees : MySQL (contenus editables du site)
- Front public : Blade + assets (CSS/JS) issus de l'export Claude Design,
  SANS etape de build lourde cote serveur (assets precompiles/publies en local)
- Hebergement : mutualise OVH (voir docs/deploiement-ovh.md — contraintes fortes)

### Biens a vendre = CRM, en LECTURE SEULE (pas de HFSQL)
Les biens a vendre et surtout leurs PHOTOS proviennent du CRM. Ces DONNEES DES
BIENS ne sont PAS editables dans l'admin du site : l'interdiction d'ecriture
porte sur les donnees des biens (fiches, photos), pas sur tout flux vers le
CRM (voir le point transmission de leads ci-dessous). Regles :
- Un seul point d'acces en lecture aux biens : `app/Services/Crm/`
  (CrmClientInterface + implementation bindee dans le container), en LECTURE
  SEULE.
- Aucune ecriture des DONNEES DE BIENS vers le CRM. Aucune duplication
  editable des biens en MySQL.
- Cache court cote site (les biens/photos peuvent etre mis en cache pour la perf,
  jamais consideres comme modifiables). TTL = 900s par defaut, configurable via
  CRM_CACHE_TTL (voir app/Services/Crm/CrmClientEnCache.php).
- CRM cible = **Portail vendeur** (CRM interne Biome, Claude Code). Mode d'acces
  (API/flux, auth, photos/PDF) A CONVENIR avec l'equipe du CRM : le document de
  reference pour cette reunion est docs/contrat-crm-champs.md (champs a lire +
  leads a transmettre). Voir aussi docs/architecture-donnees.md. Tant que ce
  n'est pas fixe, `CrmClient` expose une interface stable et une implementation
  bouchon (fixtures) pour ne pas bloquer le front.
- **Transmission sortante des leads acheteurs = flux legitime, distinct de la
  lecture des biens.** Les leads "planifier une visite", "demande d'infos sur
  un bien" et "contact — branche maison" sont transmis au CRM via
  `TransmetteurLeadCrmInterface` (app/Services/Crm/), en ECRITURE, ce qui est
  attendu et voulu (decision client du 2026-07-03). Voir
  docs/architecture-donnees.md, sous-section "Transmission des leads vers le
  CRM" : contrat (endpoint, auth) A CONVENIR avec l'equipe CRM, implementation
  bouchon `TransmetteurLeadCrmJournal` active en attendant (journalise sans
  rien envoyer).

Ce qui EST editable dans l'admin (MySQL) : actualites, offres d'emploi,
partenaires, contenus de pages statiques, et la reception des formulaires
(voir docs/architecture-donnees.md pour le detail section par section).

## 3. Conventions de code (imposees)

- Commentaires et noms internes en francais SANS accents.
- Aucune requete SQL concatenee : Eloquent / Query Builder / requetes parametrees
  uniquement.
- Aucun secret dans le code : tout dans `.env` (jamais commite). Voir `.env.example`.
- Sensibilisation RGPD : pas de donnee personnelle superflue, formulaires avec
  finalite claire, logs sans donnee sensible.
- PSR-12, indentation 4 espaces (standard Laravel/PHP), typage strict quand possible.

## 4. Zones "NE PAS MODIFIER"

- `vendor/` (gere par Composer)
- Les tokens de design extraits de la maquette (couleurs, polices, espacements) :
  ils sont la reference. Toute deviation doit etre justifiee et validee.
- `.env` reel (seul `.env.example` est versionne)

## 5. Contraintes hebergement (resume — detail dans docs/)

- Pas de process persistant : pas de queue worker en demon. File d'attente en
  driver `database` declenchee par cron, ou driver `sync` si volume faible.
- Scheduler via une tache cron unique appelant `schedule:run`.
- Racine du domaine pointee sur `.../public` (jamais la racine du projet).
- Deploiement : SSH + composer.phar si l'offre le permet, sinon FTP avec `vendor/`
  transfere depuis le local. Migrations via SSH ou import SQL manuel.
- Pieges reels du mutualise OVH (constates au deploiement de new.biome.immo) :
  voir `docs/deploiement-preproduction.md` section 0 — PHP CLI hors PATH
  (`/usr/local/php8.3/bin/php`), `config:cache` INTERDIT (500), JS Livewire a
  servir en statique (`public/vendor/livewire`), chemins SSH/$HOME instables
  (toujours en absolu), planificateur via cron HTTP externe.

## 6. Workflow d'equipe

Voir `.claude/agents/`. Boucle : chef-de-projet decoupe -> dev-backend +
dev-frontend implementent -> testeur valide -> redacteur-doc documente ->
chef-de-projet integre. Tout passe par Git (branches par tache, PR relue).

## 7. Definition of Done

- La page/section correspond visuellement a la maquette (revue cote frontend).
- CRUD admin fonctionnel et protege par auth.
- Tests verts (au minimum : routes publiques, CRUD admin, validation formulaires).
- Aucun secret ni donnee perso dans le repo.
- Documentation mise a jour (README + docs/).
- Deployable sur mutualise OVH sans etape interdite (voir docs/deploiement-ovh.md).