Devlog #7 : Historique des Commandes, PHPStan et Documentation Métier
Focus : Robustesse applicative via l'analyse statique, correction de bugs dans la gestion des adresses, et une réflexion clé sur la documentation des règles métier.
📋 Nouvel Endpoint : Historique des Années
Pour alimenter les filtres de l'historique des commandes côté frontend, j'ai ajouté un endpoint dédié à la récupération des années durant lesquelles au moins une commande a été passée.
Cela évite d'exposer un filtre par année avec des valeurs statiques côté client, et garantit que seules les années réellement disponibles sont proposées à l'utilisateur.
Point technique : beberlei/DoctrineExtensions
Pour extraire l'année d'une date dans une requête DQL, j'avais initialement créé une fonction DQL personnalisée (YEAR). En révisant ce code, j'ai découvert la librairie beberlei/DoctrineExtensions, qui propose déjà un catalogue de fonctions SQL (YEAR, MONTH, DATE_FORMAT...) de manière plus stable et maintenue.
⚠️ Nuance importante : Cette librairie ne couvre pas
UNACCENT. En effet,UNACCENTn'est pas une extension Doctrine mais une extension propre à PostgreSQL — elle doit donc rester une fonction custom déclarée manuellement dans Doctrine.
🐛 Corrections : Gestion des Adresses
Plusieurs bugs ont été identifiés et corrigés dans le module de gestion des adresses utilisateur :
| Bug | Description | Correction |
|---|---|---|
| Propriété manquante | Le champ companyName (nom d'entreprise) était absent du modèle |
Ajout de la propriété dans l'entité, le DTO et le Mapper |
| Suppression adresse par défaut | L'API permettait de supprimer l'adresse par défaut, laissant l'utilisateur sans adresse valide | Ajout d'une règle métier : une adresse par défaut ne peut être supprimée que si une autre a été désignée au préalable |
| Code HTTP incorrect | L'API retournait un 200 OK en cas d'échec de suppression d'une adresse par défaut |
Correction du statut de retour en 422 Unprocessable Entity |
🔍 Analyse Statique : PHPStan
PHPStan a été intégré au projet pour détecter les erreurs de typage statique avant même l'exécution. L'IA a été utilisée pour assister la correction des erreurs détectées et compléter la couverture de tests manquante.
🧠 Insight clé : Documenter les Règles Métier pour l'IA
Ce devlog est l'occasion de partager une réflexion structurante sur la collaboration avec l'IA pour le frontend.
Le constat : En utilisant l'IA comme un "collègue frontend" disposant uniquement de la documentation MkDocs et de la documentation OpenAPI, je me suis heurté à une limite claire : l'IA n'a pas connaissance des règles métier implicites.
Exemple concret : La documentation OpenAPI expose un endpoint DELETE /api/addresses/{id}. L'IA génère un bouton "Supprimer" sans savoir que :
- il faut désactiver ce bouton si c'est l'adresse par défaut,
- il faut désactiver ce bouton si c'est la seule adresse de la liste.
La solution : Formaliser ces règles directement dans la documentation MkDocs, dans une section dédiée aux comportements attendus par feature. La documentation ne doit pas seulement décrire ce que fait l'API, mais aussi dans quelles conditions chaque action est permise.
Ce principe est désormais appliqué à chaque nouvelle feature : toute règle métier non-évidente est documentée ici avant d'être implémentée côté frontend.