vCard QR Generator
Une petite application web auto-hébergée qui transforme des coordonnées en codes QR vCard pour des cartes d'affaires, avec un logo optionnel au centre. Je l'ai construite pour tourner en un seul processus local, et comme le contact vit dans le QR lui-même, n'importe quel appareil photo de téléphone peut le lire et proposer d'enregistrer le contact, sans connexion Internet.
Architecture
Un seul processus FastAPI sert des pages Jinja2 rendues côté serveur : un tableau de bord, un formulaire d'employé et une page de paramètres. Les employés sont des lignes dans SQLite via SQLAlchemy, et le texte de la vCard n'est pas stocké mais reconstruit à partir de la ligne chaque fois qu'un QR ou un téléchargement .vcf en a besoin. À chaque enregistrement, segno encode ce texte en un PNG et un SVG nommés d'après le slug de l'employé, et Pillow colle le logo sur le PNG. Téléverser un nouveau logo d'entreprise régénère tous les QR qui utilisent celui par défaut.
Décisions clés
Un générateur de vCard écrit à la main
La plupart des bibliothèques vCard produisent une sortie qui diffère un peu de ce qu'attendent Apple Contacts et Google Contacts, alors j'ai écrit un petit générateur à la main. Il produit du vCard 3.0 avec des fins de ligne CRLF et place N avant FN, parce qu'iOS est pointilleux sur l'ordre des champs. Les noms, le poste et l'entreprise sont échappés pour les barres obliques inverses, les virgules, les points-virgules et les retours à la ligne, en commençant par les barres obliques inverses pour ne pas doubler les nouveaux échappements.
Correction d'erreur de niveau H pour faire place au logo
Le PNG reçoit un logo carré collé en son centre, sur 22 % de la largeur de l'image, ce qui couvre une partie du code. Je génère chaque code au niveau H, la correction d'erreur la plus forte, qui peut récupérer environ 30 % des données, donc il se lit encore sur les téléphones récents. Le SVG n'a pas de logo et reste un vecteur propre pour l'impression, où un graphiste peut placer le logo à la main.
Un slug par personne nomme chaque fichier
Chaque employé reçoit un slug tiré de son nom : les accents sont retirés, le texte passe en minuscules et les espaces deviennent des traits d'union. Si le slug est déjà pris, l'application ajoute -2, -3, et ainsi de suite. Le slug nomme le PNG, le SVG et le logo personnalisé de la personne, donc quand un changement de nom le modifie, l'application supprime les anciens fichiers QR, déplace le logo et en écrit de nouveaux.
Le point difficile
La photo que les téléphones n'enregistraient pas
Les premières versions mettaient une photo en base64 dans la vCard, mais les téléphones ne l'enregistraient généralement pas. Les applications appareil photo d'iOS et d'Android ne lisent que les champs courants d'un QR, alors que l'analyseur complet de l'application Contacts lit bien la photo quand on ouvre un fichier .vcf. La seule correction fiable est un QR qui pointe vers un serveur, ce qui exige un hôte public et Internet au moment de la lecture. J'ai gardé le QR statique et hors ligne, retiré la photo et déplacé l'image de marque vers un logo au centre du code.
Sécurité et performance
- Les scripts de lancement lient l'application à 127.0.0.1 seulement et il n'y a pas d'écran de connexion, donc elle reste un outil local pour un seul utilisateur. Le README précise de ne pas l'exposer publiquement sans ajouter une authentification et HTTPS.
- Un logo téléversé est refusé s'il est vide, s'il dépasse 5 Mo, s'il est déclaré autrement qu'en PNG ou JPG, ou si Pillow ne peut pas le décoder. L'application enregistre ensuite un PNG réencodé de 400 sur 400 pixels, jamais le fichier d'origine.