Guide d'utilisation des identifiants employés — COS vs id interne

Contexte

Dans ce projet il existe deux identifiants liés aux salariés :
- `id` : la clé primaire interne (entier auto-incrémenté) utilisée par la base de données et pour les relations/FK.
- `COS` (ou `Id_Salarie` selon les tables) : identifiant métier/historique provenant d'anciens exports (Access, ancien SI).

Question : utiliser `COS` dans les URLs (ex. `/api/employes/:cos`) au lieu de `id` interne ?

Résumé rapide

- Oui, on peut utiliser le `COS` dans les URLs et dans le front pour l'UX si c'est ce que le client a sous la main. Mais il y a des précautions :
  - S'assurer que `COS` est unique et indexé en base (ou ajouter un index/contrainte unique si pertinent).
  - Implémenter une résolution côté serveur (lookup) qui convertit `COS` -> `id` interne pour la logique métier, ou supporter les deux formes explicites.
  - À long terme, préférer l'`id` interne pour les relations, URLs et FK (plus sûr, stable, indexé).

Options pratiques (avec recommandations)

1) Quick win — Endpoint de résolution (recommandé pour transition)
- Ajouter un endpoint `GET /api/employes/by-cos/:cos` qui renvoie l'objet salarié (ou au moins `{ id }`).
- Avantages : peu intrusif, front existant peut continuer d'utiliser COS puis demander l'`id` interne au besoin.
- Exemple de réponse :
  - 200: `{ id: 123, cos: 5504, nom: 'Dupont' }`
  - 404: `{ message: 'Employé non trouvé' }`
- Sécurité : protéger par auth et rate-limit si nécessaire.

2) Support dual dans routes existantes (pratique mais ambigu)
- Autoriser `/api/employes/:identifier` et détecter si `identifier` est un `id` interne (entier petit) ou un `COS` métier.
- Implémentation : tenter `getById(parseInt(...))`, si null, fallback `getByCos(...)`.
- Risques : performances (deux queries), ambiguïtés si formats se chevauchent.

3) Migration front → `id` interne (meilleur long terme)
- Mettre à jour le front pour stocker et propager l'`id` interne (ex. lors d'une recherche/selection).
- Avantages : cohérence, meilleures performances, moins de code serveur spécial.
- Plan de migration : 1) ajouter lookup endpoint, 2) modifier front pour récupérer id interne à l'affichage, 3) basculer URLs, 4) retirer endpoints temporaires.

Points techniques à vérifier

- Unicité : vérifier que `COS`/`ID_Contrat` est unique ou ajouter contrainte unique si approprié.
- Indexation : ajouter index sur la colonne métier pour rapides recherches `WHERE COS = ?`.
- Nulls & formats : normaliser les valeurs (trim, int coercion).
- Tests : ajouter unit/integration tests pour le lookup et les cas d'ambiguïté.
- Sécurité : requireAuth sur endpoints, ne pas exposer données sensibles dans le lookup.

Exemples SQL

- Ajouter un index (MySQL):

  ALTER TABLE `employes` ADD INDEX `idx_cos` (`COS`);

- Ajouter contrainte d'unicité (après vérification des doublons):

  ALTER TABLE `employes` ADD UNIQUE INDEX `uq_cos` (`COS`);

Notes sur code et services

- Le serveur devrait garder la logique métier sur l'`id` interne. Le lookup renvoie l'enregistrement complet (ou uniquement l'`id`) puis les services existants (`getEmployeById`, etc.) sont utilisés.
- Nomme clairement les fonctions : `getEmployeById(id)`, `getEmployeByCos(cos)` pour éviter confusion.

Tests recommandés

- Unit tests pour `getEmployeByCos` et `GET /api/employes/by-cos/:cos` couvrant :
  - existant, non trouvé, input invalide, cas avec doublons (si existants)
- Integration tests pour vérifier que front + lookup renvoient bien `id` utilisable par d'autres endpoints.

Conclusion / Reco rapide

- Implémenter d'abord un endpoint de lookup (`/by-cos/:cos`) et ajouter un index/contrainte si possible.
- Puis, planifier migration du front pour utiliser `id` interne et supprimer la logique de résolution quand les clients sont migrés.

Si tu veux, je peux :
- Générer l'endpoint lookup pour `employes` (comme j'ai fait pour `contrats`), avec tests, ou
- Lister toutes les occurrences de `COS`/`ID_Contrat` dans le repo pour évaluer l'effort de migration.

Indique ce que tu souhaites que je fasse ensuite.