Bâtir un écran de caisse sur StillDeep

Des fichiers .proto de stilldeep.v1 à une première vente : générer le client, ouvrir un quart, remplir un panier, encaisser, écouter les événements.

Avec un agent de code

Claude Code, Codex, Cursor et les autres agents lisent cette documentation telle quelle :

llms.txt liste chaque page en Markdown ; ajoutez .md à toute adresse pour sa version Markdown.
Le serveur MCP en lecture seule, à /mcp, cherche et lit la documentation et le contrat (search_docs, read_page, list_pages, get_contract). Claude Code : claude mcp add --transport http stilldeep <site>/mcp.
La compétence /.well-known/agent-skills/stilldeep-pos-screen/SKILL.md donne à l'agent les étapes ci-dessous.
Chaque fichier .proto est servi en texte brut à /contracts/<fichier>.proto.

Décrivez votre commerce et l'écran voulu ; l'agent suit les étapes ci-dessous et le moteur vérifie chaque vente.

Obtenir le contrat

Les fichiers .proto du paquet stilldeep.v1 décrivent chaque service du poste : ventes, catalogue, membres, cartes, périphériques, événements, reçus, réservations, rendez-vous, location, inventaire, quarts et configuration. Les clients .NET utilisent le paquet StillDeep.Intelligence.Contracts ; les autres langages génèrent leur code à partir des mêmes fichiers.

Générer le client

Utilisez les outils gRPC de votre langage :

TypeScript et Node.js : @grpc/grpc-js avec ts-proto ou protoc-gen-ts.
Python : grpcio-tools.
Go : protoc-gen-go et protoc-gen-go-grpc.
.NET, Java, Kotlin, Rust, C++ : les générateurs gRPC officiels.

Les guides pas à pas avec les commandes sont dans la référence : générer un client, client TypeScript, client Python, client Go.

Se brancher au poste

Le moteur du poste écoute sur le poste lui-même (HTTP/2, port 50051 par défaut). L'écran ne parle jamais au serveur du commerce : le poste s'occupe pour lui du proxy, de la file d'envoi et du mode hors ligne.

Faire une première vente

Ouvrir un quart

Connectez l'employé par badge ou mot de passe et ouvrez un quart. Chaque appel suivant porte l'identifiant du quart.

Ouvrir un panier et ajouter des articles

Ajoutez des articles par scan de code-barres ou recherche au catalogue, avec leurs quantités (décimales pour la vente au poids). Rattachez un client si la vente en exige un.

Encaisser

Listez les modes de paiement actifs, choisissez-en un, encaissez le montant. Plusieurs paiements peuvent se partager une vente.

Finaliser

Finalisez la vente : le moteur l'écrit localement, l'envoie par la file d'envoi et rend le reçu à imprimer.

Gérer les refus

Chaque refus arrive en google.rpc.Status avec un code stable (par exemple shift_paused ou stock_short). Affichez au caissier un message tiré du code ; ne réessayez jamais à l'aveugle. Le serveur revérifie chaque vente : un refus peut arriver alors que l'écran croyait tout correct.

Écouter les événements

Le service d'événements diffuse ce qui se passe sur le poste : disponibilité des ressources limitées, messages du chat, décisions du serveur. Un écran s'abonne une fois et se met à jour lui-même.

Partir d'un exemple

Les clients exemples couvrent un commerce simple, une boutique, un cinéma, une billetterie, une borne libre-service, une animalerie avec toilettage, et des clients web en Node.js et en Go. Partez de celui qui ressemble le plus à votre commerce et remplacez son écran.

Règles du contrat

La version 1 ne reçoit jamais de changement incompatible ; une version 2 serait un paquet distinct.
Argent en cents int64, pourcentages en points de base, quantités en millièmes.
Horodatages en UTC.
Ne croyez jamais l'écran : le moteur et le serveur valident tout, alors gardez les règles d'affaires hors du client.