Architecture et extension du produit
Où placer une règle et comment faire évoluer une surface publique.
Les couches#
Les routes et les actions d'interface appellent les services métier. Ceux-ci portent les règles de validation, les transitions, les calculs et les effets associés. L'accès aux données s'appuie sur Drizzle et PostgreSQL. Les intégrations externes passent par des adaptateurs.
Une fonction exposée en interface, en REST et en MCP doit réutiliser la même règle métier. Un nouveau canal n'est pas une occasion de réimplémenter la facturation ou la signature séparément.
Organisation et permissions#
Le contexte d'organisation doit être établi avant toute lecture ou écriture de données isolées. La base applique la séparation par RLS ; les permissions et la visibilité bornent ensuite les gestes et les fiches accessibles dans cette organisation.
Testez avec le rôle applicatif réel. Un test sous un superutilisateur PostgreSQL ne prouve pas le comportement de la sécurité en production.
Ajouter une opération REST#
- Définissez les schémas d'entrée, les réponses et les erreurs.
- Réutilisez le handler, les scopes, le périmètre et le service métier appropriés.
- Déclarez l'opération dans le registre OpenAPI.
- Testez les cas autorisés, les refus et la séparation des organisations.
- Régénérez le contrat et les types partagés.
- Complétez le guide de parcours et la note de version si le comportement visible change.
Ajouter un outil MCP#
Déclarez l'outil dans le registre métier et fournissez un nom, un titre, une description, un scope et un schéma d'entrée. Réutilisez les services et les gardes du produit. Traitez l'idempotence et les approbations selon les effets de l'action.
La référence de documentation lit la composition du registre. Une nouvelle forme non reconnue doit faire échouer la génération plutôt que produire un catalogue incomplet.
Faire évoluer le modèle#
Une migration doit préserver l'isolation, les invariants métier et les chemins de restauration. Examinez l'impact sur les listes, les exports, le mobile, les webhooks, les schémas MCP et les champs personnalisés.
Les formats d'intégration doivent être traités comme des contrats. Préférez une évolution additive documentée ; préparez explicitement toute rupture et le parcours de migration des clients.