# 15. Guide des champs des modèles de documents

Dernière mise à jour : 31 août 2026  
Référence technique : `documents-modeles-generation.service.ts`

Ce guide explique comment préparer un modèle Word pour le module Documents automatiques et recense les champs automatiquement reconnus par la version analysée de RH Connect.

## Format attendu

- Le fichier doit être un véritable `.docx` Microsoft Word.
- Les fichiers `.doc`, `.docm`, PDF et modèles contenant des macros VBA sont refusés.
- La taille du DOCX ne doit pas dépasser 10 Mio.
- Son contenu décompressé ne doit pas dépasser 50 Mio.
- Le document doit contenir au moins une balise au format `{nomDuChamp}`.
- Le nom d'une balise commence par une lettre et contient au maximum 100 caractères : lettres, chiffres, `_`, `-` ou `.`.
- Une balise inconnue devient un champ manuel à compléter avant génération.
- Lors de l'import, tous les champs détectés sont considérés comme obligatoires.
- Une valeur saisie ne peut pas dépasser 10 000 caractères.

Exemple minimal :

```text
Je soussigné(e), {signataireNom}, certifie que {titreNomPrenom}
est employé(e) au sein de {entreprise} depuis le {dateEmbauche}.
```

## Règles d'écriture dans Word

- Écrire chaque balise exactement entre une accolade ouvrante et une accolade fermante.
- Éviter d'appliquer plusieurs styles au milieu d'une balise.
- Ne pas ajouter d'espace dans les accolades : utiliser `{nomPrenom}`, pas `{ nomPrenom }`.
- Une même balise peut être utilisée plusieurs fois.
- Les retours à la ligne contenus dans une valeur sont conservés.
- Tester le DOCX puis le PDF avant d'activer une nouvelle version.
- Une balise reconnue est préremplie, mais sa valeur reste modifiable dans l'écran de génération.

La résolution ignore les accents, la casse et les séparateurs pour reconnaître les alias. Il reste recommandé d'utiliser exactement les noms documentés ci-dessous afin de garder des modèles lisibles et homogènes.

## Champs du salarié

| Balise recommandée | Alias reconnus | Valeur |
|---|---|---|
| `{cos}` | `{matricule}`, `{numeroSalarie}` | Identifiant COS du salarié |
| `{civilite}` | `{titre}` | Monsieur, Madame ou Mademoiselle |
| `{nom}` | `{nomSalarie}` | Nom du salarié |
| `{prenom}` | `{prenomSalarie}` | Prénom du salarié |
| `{nomPrenom}` | `{salarieNomPrenom}` | Nom puis prénom |
| `{prenomNom}` | — | Prénom puis nom |
| `{titreNomPrenom}` | `{identiteSalarie}` | Civilité, prénom et nom |
| `{domicilie}` | `{formuleDomiciliation}` | `domicilié`, `domiciliée` ou `domicilié(e)` |
| `{adresse}` | `{adresseLigne}`, `{adresseSalarie}` | Rue, code postal et ville sur une ligne |
| `{rue}` | `{adresseRue}` | Rue du salarié |
| `{codePostal}` | — | Code postal |
| `{ville}` | `{villeSalarie}` | Ville |
| `{telephone}` | `{telephoneSalarie}` | Téléphone, avec priorité au téléphone principal puis au mobile |
| `{email}` | `{emailSalarie}` | E-mail Envie 2E, sinon e-mail personnel |
| `{dateNaissance}` | — | Date de naissance |
| `{lieuNaissance}` | `{paysNaissance}` | Lieu de naissance enregistré |
| `{nationalite}` | — | Nationalité |
| `{numeroSecuriteSociale}` | `{numeroSecu}`, `{nss}` | Numéro de sécurité sociale |
| `{genreAccord}` | `{genre}` | `e` pour une salariée, sinon vide |
| `{genrePronom}` | `{genre2}` | `elle` ou `il` |
| `{titreSejour}` | — | Type de titre de séjour |
| `{numeroCarteSejour}` | — | Numéro de carte/titre de séjour |
| `{dateExpirationTitreSejour}` | `{dateExpiration}` | Date d'expiration du titre |
| `{dateFinCmu}` | — | Date de fin de CMU |
| `{dateFinDerogationMutuelle}` | `{dateEcheanceMutuelle}` | Fin de dérogation mutuelle |
| `{motifDerogationMutuelle}` | — | Motif de dérogation mutuelle |

## Champs du contrat

Le service utilise le contrat le plus récent, trié par date de début décroissante puis identifiant décroissant.

| Balise recommandée | Alias reconnus | Valeur |
|---|---|---|
| `{typeContrat}` | `{contrat}`, `{tcs}` | Type de contrat |
| `{motifContrat}` | — | Motif du contrat |
| `{dateEmbauche}` | `{dateDebutContrat}` | Date de début du contrat |
| `{dateFinContrat}` | `{dateSortiePrevue}` | Date de sortie prévue |
| `{dateSortieReelle}` | — | Date de sortie réelle |
| `{poste}` | `{emploi}`, `{qualification}` | Poste ou qualification |
| `{etablissement}` | — | Établissement du contrat |
| `{secteur}` | — | Secteur du contrat |
| `{categorie}` | `{classification}` | Catégorie/classification |
| `{niveau}` | — | Niveau |
| `{echelon}` | — | Échelon |
| `{coefficient}` | — | Coefficient |
| `{salaireMensuel}` | `{salaireMensuelBrut}` | Salaire mensuel brut enregistré |
| `{heuresHebdomadaires}` | `{nbHeuresHebdo}` | Nombre d'heures hebdomadaires |
| `{heuresMensuelles}` | `{mensu}` | Mensualisation |
| `{dateReprise}` | — | Jour suivant la date de sortie prévue |
| `{dureeContrat}` | — | Période `Du … au …` ou `Durée indéterminée` |
| `{contratsTexte}` | — | Historique synthétique des contrats, une ligne par contrat |

## Champs du signataire

Le signataire doit être sélectionné dans l'écran de génération et être actif dans Paramètres.

| Balise recommandée | Alias reconnus | Valeur |
|---|---|---|
| `{signataireNom}` | `{nomSignataire}`, `{correspondantNom}` | Prénom et nom du signataire |
| `{signataireFonction}` | `{fonctionSignataire}`, `{correspondantFonction}` | Fonction du signataire |
| `{formuleSoussignataire}` | — | Texte `soussigné(e)` |

Si un modèle contient un champ de signataire sans qu'une personne soit sélectionnée, la valeur automatique sera vide et devra être complétée manuellement. Si un identifiant de signataire invalide est transmis, la génération échoue.

## Champs généraux et établissement

| Balise recommandée | Alias reconnus | Valeur |
|---|---|---|
| `{dateDocument}` | `{dateDuDocument}`, `{dateEdition}` | Date de génération |
| `{lieuDocument}` | `{lieuSignature}` | Établissement du contrat, sinon `Lesquin` |
| `{entreprise}` | `{societe}` | Entreprise du référentiel établissement, sinon établissement du contrat |
| `{adresseEntreprise}` | — | Adresse de l'établissement, sinon adresse du siège |
| `{telephoneEntreprise}` | — | Variable `DOCUMENT_COMPANY_PHONE` ou valeur par défaut configurée dans le code |
| `{siret}` | — | Variable `DOCUMENT_COMPANY_SIRET` ou valeur par défaut configurée dans le code |
| `{urssaf}` | — | Variable `DOCUMENT_COMPANY_URSSAF` ou valeur par défaut configurée dans le code |

Les valeurs légales par défaut doivent être vérifiées avant la mise en production. La configuration d'environnement est préférable à une modification directe dans un modèle.

## Champs manuels

Toute balise valide absente des tableaux précédents devient un champ manuel. Par exemple :

```text
{objetCourrier}
{descriptionFaits}
{dateEntretien}
{heureEntretien}
{numeroRecommande}
```

Le libellé affiché est généré depuis le nom de la balise. Une balise commençant par `date` est présentée comme une date. Une balise contenant `dateheure` est affichée comme date et heure. Les autres balises importées sont actuellement typées comme texte.

Attention : tous les champs importés sont marqués obligatoires dans la version analysée, y compris les champs manuels. Pour rendre un champ réellement facultatif, une évolution du paramétrage des champs est nécessaire.

## Dates et formats

- Les dates automatiques sont préremplies au format ISO `AAAA-MM-JJ` pour l'écran HTML.
- Lors de la génération, un champ de type date est rendu en `JJ/MM/AAAA`.
- Un champ dont le nom contient `dateheure` est rendu en `JJ/MM/AAAA à HHhMM`.
- Le fuseau utilisé pour les dates automatiques est `Europe/Paris`.

## Import d'un modèle unique

1. Ouvrir Paramètres puis Modèles de documents.
2. Cliquer sur Nouveau modèle.
3. Saisir le libellé, le code technique, la catégorie, l'établissement éventuel et la description.
4. Sélectionner le fichier `.docx`.
5. Importer le modèle en brouillon.
6. Vérifier la liste des champs détectés.
7. Ouvrir l'aperçu de la dernière version.
8. Tester avec un salarié représentatif et un signataire.
9. Activer seulement après validation du Word et du PDF.

Le code technique utilise uniquement des minuscules, chiffres et tirets, par exemple `attestation-emploi`. Une nouvelle version conserve le même code.

## Import d'un lot ZIP

Un lot peut contenir au maximum 100 modèles, un `manifest.csv` ou `manifest.json`, et les fichiers DOCX référencés. Le ZIP ne doit pas dépasser 100 Mio et son contenu décompressé 250 Mio.

En CSV, les colonnes obligatoires sont :

```text
fichier;libelle;code;categorie
```

Les colonnes facultatives sont :

```text
etablissement;description
```

Exemple :

```csv
fichier;libelle;code;categorie;etablissement;description
templates/attestation-emploi.docx;Attestation d'emploi;attestation-emploi;Attestations;;Attestation employeur standard
```

Un code déjà présent dans RH Connect est ignoré lors de l'import en lot. Un même code présent plusieurs fois dans le manifeste est également ignoré.

## Recette avant activation

- le document s'importe sans erreur ;
- toutes les balises attendues sont détectées ;
- aucune balise parasite n'apparaît ;
- les champs automatiques correspondent au salarié et au dernier contrat ;
- les valeurs absentes restent compréhensibles ;
- les textes longs ne cassent pas la mise en page ;
- les dates sont au format français dans le document final ;
- le signataire et sa fonction sont corrects ;
- le Word reste éditable ;
- le PDF LibreOffice est visuellement identique ;
- les sauts de page, tableaux, en-têtes et pieds de page sont conservés ;
- le modèle n'est activé qu'après validation métier.

## Limites connues

- Il n'existe pas encore d'écran pour rendre individuellement un champ facultatif.
- Les champs automatiques sont reconnus par alias mais le modèle ne conserve pas un lien typé vers la donnée source.
- Les conditions complexes et boucles Docxtemplater ne sont pas documentées ni garanties par l'import actuel.
- Le « dernier contrat » documentaire n'applique pas nécessairement toutes les règles du statut actif.
- Les valeurs légales de l'entreprise peuvent provenir de valeurs par défaut si l'environnement n'est pas configuré.
- L'aperçu PDF dépend de LibreOffice dans le conteneur backend.
- Une nouvelle balise automatique nécessite une modification du service, des tests et une mise à jour de ce guide.

## Ajouter un nouveau champ automatique

1. Choisir un nom stable et non ambigu.
2. Ajouter sa valeur et ses éventuels alias dans `buildDynamicDocumentDraft()`.
3. Sélectionner la source appropriée : salarié, contrat, signataire ou établissement.
4. Définir le comportement lorsque la donnée est absente.
5. Ajouter des tests unitaires avec valeur normale, valeur nulle et alias.
6. Tester un modèle Word puis PDF.
7. Ajouter immédiatement la balise à ce dictionnaire.