# Placeholders couleurs & logo pour les templates PDF

Ce document reference les placeholders disponibles dans les templates HTML
de devis et factures. Ces placeholders sont automatiquement remplaces par
les valeurs configurees dans la gestion de configuration facturation
(table `facturation_config`, API `Api_FacturationConfig.php`).

## Placeholders couleurs

| Placeholder              | Cle facturation_config | Defaut     | Usage                                                     |
|--------------------------|------------------------|------------|-----------------------------------------------------------|
| `{{couleur_primaire}}`   | `couleur_primaire`     | `#4CAF50`  | Couleur principale (titres, bordures, entetes de tableau) |
| `{{couleur_secondaire}}` | `couleur_secondaire`   | `#2196F3`  | Couleur secondaire (accents, blocs secondaires)           |

### Format
- Hex RGB strict : `#RRGGBB` (6 chiffres hex apres le `#`).
- Exemple valide : `#4CAF50`, `#FF8800`.
- Exemples invalides : `#FFF` (trop court), `red` (nom), `#GGG` (non hex),
  `rgb(0,255,0)` (pas hex).

### Comment les utiliser dans un template

```css
.items-table th {
    background-color: {{couleur_primaire}};   /* configurable */
}

.accent-box {
    border-color: {{couleur_secondaire}};     /* configurable */
}

.fixed-border {
    border-color: #1a1a4e;                    /* couleur en dur, non substituee */
}
```

**Regle** : si tu veux qu'un element change quand l'utilisateur modifie la
config facturation, utilise `{{couleur_primaire}}` ou `{{couleur_secondaire}}`.
Si tu veux une couleur fixe qui ne change jamais, mets le code hex directement
(ex: `#1a1a4e`).

## Placeholder logo

| Placeholder                 | Cle facturation_config | Defaut | Usage                              |
|-----------------------------|------------------------|--------|------------------------------------|
| `{{logo_entreprise_url}}`   | `Logo_entreprise_Pdf`  | aucun  | Logo entreprise en base64 (embed)  |

### Comportement
- Si un logo a ete uploade (POST sur l'API), `{{logo_entreprise_url}}` est
  remplace par une `data:image/png;base64,...` (ou jpeg) embarquee dans le PDF.
- Si aucun logo n'est configure, le bloc conditionnel entier est supprime.

### Syntaxe bloc conditionnel

Le logo doit etre encadre dans un bloc conditionnel pour ne pas afficher
un `<img>` casse quand il n'y a pas de logo :

```html
{{#logo_entreprise_url}}
<img src="{{logo_entreprise_url}}" style="max-height:50px; float:left; margin-right:10px;">
{{/logo_entreprise_url}}
```

- Si logo present : les tags `{{#...}}` et `{{/...}}` sont supprimes et
  `{{logo_entreprise_url}}` est remplace par le base64.
- Si logo absent : tout le bloc `{{#...}}...{{/...}}` est supprime du HTML.

## Blocs conditionnels generiques

La syntaxe `{{#variable}}...{{/variable}}` est supportee pour toute variable
template. Si la variable a une valeur non vide, le contenu du bloc est garde
et les tags `{{#}}`/`{{/}}` supprimes. Si la variable est absente du
search/replace (non fournie par le generateur), le bloc est **deplie** par
defaut (comportement du preg_replace generique). Seul le logo beneficie d'une
suppression propre du bloc quand il est absent.

## Variables disponibles (devis)

```
{{couleur_primaire}}        {{couleur_secondaire}}      {{logo_entreprise_url}}
{{entreprise_name}}         {{entreprise_address}}      {{entreprise_contact}}
{{reference_devis}}         {{date_creation_formattee}} {{titre}}
{{client_info}}             {{adresse_chantier}}        {{code_postal_chantier}}
{{ville_chantier}}          {{items_rows}}              {{total_ht}}
{{taux_tva}}                {{total_tva}}               {{total_ttc}}
{{duree_validite}}          {{date_generation}}         {{footer_text}}
```

## Variables disponibles (facture)

```
{{couleur_primaire}}        {{couleur_secondaire}}      {{logo_entreprise_url}}
{{entreprise_name}}         {{entreprise_statut_suffix}} {{capital_social}}
{{entreprise_address}}      {{entreprise_code_postal}}  {{entreprise_ville}}
{{entreprise_pays}}         {{entreprise_siret}}        {{entreprise_tva_intracomm}}
{{entreprise_email}}        {{entreprise_telephone}}    {{reference_facture}}
{{reference_devis_origine}} {{date_emission_formattee}} {{titre}}
{{client_info}}             {{client_adresse}}          {{client_code_postal}}
{{client_ville}}            {{client_pays}}             {{client_tva_intracomm}}
{{client_siret}}            {{items_rows}}              {{total_ht}}
{{taux_tva}}                {{total_tva}}               {{total_ttc}}
{{conditions_paiement}}     {{mention_legale}}          {{penalites_retard}}
{{iban}}                    {{bic}}                     {{date_generation}}
{{footer_text}}
```

## Configuration cote front

- **GET** `Api_FacturationConfig.php` → retourne toute la config dont
  `couleur_primaire`, `couleur_secondaire`, `Logo_entreprise_Pdf` (booleen
  `true`/`false` indiquant la presence d'un logo). Les details S3 (bucket,
  key_file) ne sont **pas** exposes au front.
- **GET** `Api_FacturationConfig_Logo.php` → stream binaire du logo (proxy
  backend vers S3). A utiliser directement dans une balise `<img>` :
  `<img src="/src/Api/Api_FacturationConfig_Logo.php">`. Reponses : 200
  (image/png | image/jpeg, Cache-Control 1h), 404 (aucun logo), 500 (S3).
- **PUT** `Api_FacturationConfig.php` (JSON) → update couleurs :
  `{"couleur_primaire":"#RRGGBB","couleur_secondaire":"#RRGGBB"}`.
- **POST** `Api_FacturationConfig.php` (multipart/form-data, champ `fichier`)
  → upload logo (PNG/JPEG, max 2 Mo). Reponse : `{message, logo_present: true}`.
- **DELETE** `Api_FacturationConfig.php` → supprime le logo. Reponse :
  `{message: "Logo supprime"}`.

> **Regle** : le frontend n'a **jamais** d'acces direct a MinIO/S3. Tout passe
> par le backend (stream proxy pour l'aperçu, base64 embarque pour les PDF).