Hiya

Hiya est une plateforme e-commerce mono-boutique — vitrine, panneau d'administration et API — construite pour un magasin de biens généraux en Tunisie, vendant en TND avec paiement à la livraison.

Contexte et problème. La difficulté de ce projet n'a jamais été le catalogue, mais le stock. Une boutique généraliste vend des articles avec couleur et taille, des articles avec couleur seule, et des articles sans aucune variante : un schéma pensé autour de paires couleur/taille façon prêt-à-porter casse dès le premier livre. Pire, le stock porte une condition de concurrence en son cœur : entre le moment où un client passe commande et celui où la boutique la confirme, l'article ne doit pas être vendable à quelqu'un d'autre — mais il ne doit pas non plus disparaître définitivement, sinon les commandes abandonnées videraient silencieusement le catalogue.

Solution. Les deux axes de variante sont optionnels, et les produits sans variante reçoivent malgré tout une couleur « Default » cachée, créée automatiquement, qui porte prix, stock et images — d'où un modèle de données uniforme et un seul chemin de code partout, au lieu de brancher sur la forme des variantes. Les responsabilités sont réparties par niveau : le prix vit sur la couleur, puisque chaque couleur peut être tarifée indépendamment, et le stock vit sur la taille, la feuille d'inventaire. L'unité achetable est donc le triplet (produit, couleur, taille), et les images appartiennent à la couleur pour que la galerie change quand le client en sélectionne une. Le stock repose sur un moteur de réservation souple où disponible = stock − réservé : passer commande réserve, annuler ou expirer libère, confirmer décrémente le stock et solde la réservation, annuler une commande confirmée restaure. Chaque réservation est tout-ou-rien à l'intérieur de la transaction MongoDB de l'appelant — si une seule ligne de commande ne peut être satisfaite, l'ensemble est annulé. Une tâche de fond s'exécute toutes les dix minutes pour libérer les retenues des commandes en attente au-delà de leur fenêtre de 24 heures. Les catégories forment un arbre imbriqué sans limite de profondeur, les images passent par Cloudinary, et les factures sont générées en PDF avec pdfkit.

Ingénierie et exigence qualité. La variante « Default » est le genre de décision qui se rentabilise dans toute la base de code : en refusant de traiter les produits sans variante comme un cas particulier au niveau du schéma, chaque requête, opération de panier et mutation de stock en aval reste sur un chemin unique. Le moteur de stock documente sa propre machine à états dans le code et exécute ses quatre opérations dans la session transactionnelle de l'appelant plutôt que d'en ouvrir une sienne, si bien que la logique de commande se compose correctement au lieu de valider des écritures partielles. La tâche de purge signale explicitement sa propre limite — elle tourne en processus, et un déploiement multi-instances exige de la déplacer vers un worker unique ou un ordonnanceur externe — le type de documentation des frontières connues qui maintient un système correct après sa montée en charge. Les décisions de conception elles-mêmes sont versionnées dans DECISIONS.md, consignant ce qui a été arrêté avec le propriétaire de la boutique et les points où cela remplace les exigences initiales.