Archestack dans VS Code

Avec l'extension Archestack pour Visual Studio Code, votre application est un dépôt git et tourne sur votre propre machine. Ouvrez le dossier du dépôt et l'extension démarre pour lui un Archestack local : PostgreSQL, l'API et le builder, à partir du runtime fourni avec l'extension. Il n'y a aucun espace de travail auquel se connecter et rien d'autre à installer. Les Script Modules, les Business Events, les pages, les templates et les tables sont des fichiers dans le dossier, et chaque fichier que vous enregistrez atteint l'Archestack local un instant plus tard.

Cet Archestack local s'appelle le projet. Il appartient au dépôt : un collègue qui le clone obtient le même projet, construit à partir des mêmes fichiers. Travailler en équipe explique comment les développeurs d'une entreprise plus grande se partagent un même dépôt, et L'extension VS Code en détail montre chaque écran.

Installation

L'extension n'est pas encore sur le Visual Studio Marketplace. Elle est fournie sous forme de fichier VSIX : dans VS Code, ouvrez la Command Palette, lancez Extensions: Install from VSIX... et choisissez le fichier. Elle nécessite VS Code 1.90 ou une version plus récente.

Utilisez la variante Windows (x64). Elle embarque le runtime Archestack, l'API, le builder et PostgreSQL, si bien qu'un projet tourne sans rien installer d'autre. Les PDF sont rendus dans l'Edge ou le Chrome déjà présent sur la machine. La variante universelle n'a pas de runtime et fait tourner les projets dans Docker Desktop à la place.

L'extension n'a besoin ni de l'extension C# de Microsoft ni du C# Dev Kit. Ses fonctionnalités C# viennent du projet lui-même, et ses scripts s'ouvrent dans un langage qui lui est propre, si bien que l'une ou l'autre peut rester installée sans que les deux se gênent.

Démarrer un projet

• Une nouvelle application. Ouvrez un dossier vide, ouvrez la vue Archestack dans la barre d'activité et choisissez Start project. L'extension ajoute archestack.json, crée une base de données neuve, démarre l'API et le builder, et se connecte d'elle-même en tant qu'admin du projet. New Package crée ensuite le premier dossier de package.
• Un dépôt existant. Clonez-le et ouvrez son dossier. La fenêtre démarre le projet d'elle-même : le premier démarrage crée la base de données et charge le dépôt, d'abord les tables de chaque package, puis les artefacts, les dépendances avant les packages qui en ont besoin. Un clone tout frais devient une application opérationnelle en une quinzaine de secondes, et rouvrir la fenêtre reprend le projet.

Le projet est décrit dans archestack.json, qui est commité :

"project": {
  "name": "archestack-sales",
  "engine": "native",
  "webPort": 5310,
  "dbPort": 5312,
  "adminEmail": "admin@archestack.local"
}

Le builder et l'API partagent webPort et PostgreSQL écoute sur dbPort, tous deux uniquement sur 127.0.0.1. La base de données du projet, ses mots de passe générés et ses logs se trouvent dans .archestack/project/, que git ignore. Les paquets NuGet que ses scripts téléchargent y sont conservés aussi, dans .archestack/project/nuget, ou dans un volume Docker nommé nuget quand le projet tourne dans Docker, si bien qu'un redémarrage ne les télécharge pas à nouveau.

La barre d'état affiche le projet sous le nom local. Sa liste ouvre le builder du projet dans le navigateur, arrête le projet et affiche les logs de l'API. Reset Project Database jette les données du projet et recharge le dépôt.

Le projet appartient à la fenêtre qui le fait tourner. Fermer ou recharger la fenêtre arrête l'API et PostgreSQL, donc rien ne reste en cours d'exécution, et la fenêtre suivante les redémarre en quelques secondes. Si l'API cesse de répondre pendant que vous travaillez, la fenêtre la redémarre dans les dix secondes.

Le dépôt

Un dépôt contient un dossier par package, et un ou plusieurs fichiers par artefact :

archestack.json                 the environments this repository knows, and its packages
packages/sales/
  package.json                  name, version, dependencies
  nuget.json                    the NuGet packages its scripts use, each at an exact version
  tables/orders.json            one per table: columns, keys, indexes, foreign keys
  layout.json                   where the tables sit on the diagram
  entities/Order.json
  scripts/Calc.csx + Calc.json  a script module: its code, and its parameters
  code/Sales/OrderSummary.cs    shared code, named by its path: C# every script can use,
  code/components/StatusChip.tsx  and modules pages import from @/
  triggers/Order/OnCreate.json + OnCreate.1.csx
  pages/Orders/page.json + overview.tsx + OrderRow.tsx   a page's own files beside its views
  templates/Card/template.json + template.tsx
  pdf/Invoice/template.json + template.html + data.csx
  schedules/nightly.json
  tests/smoke/suite.json + cases/doubles.json + doubles.csx
  api/customers.json            a Data API endpoint, named by its route, every version inside
workspace/
  branding.json, logo.png, layouts.json

Les références entre artefacts sont des noms, jamais des identifiants de base de données. Rien de ce qui se décide par environnement ne figure dans les fichiers : qui peut voir une page, si quelque chose est public, les autorisations de la Data API et l'historique des exécutions restent propres à chaque environnement. Le même contenu donne toujours les mêmes octets, donc git ne montre que les vrais changements.

Le projet est alimenté par le dossier au fil de vos enregistrements. Une modification enregistrée sous packages/ l'atteint un instant plus tard, et ce que vous supprimez dans le dossier y est supprimé, dossier de package entier compris. Il n'y a rien à pousser. Les tables font exception : elles changent au moyen de migrations.

New Package crée un dossier de package, et New Artifact in Package (clic droit sur n'importe quel élément sous packages/ dans l'Explorer, ou + sur un package dans la vue Workspace) écrit les fichiers d'un nouvel artefact, en ne demandant que ce sans quoi il ne peut pas exister, comme l'entité à laquelle appartient un Business Event. Une nouvelle page est une page de code. Un nouveau fichier de code partagé demande son chemin, et son extension indique ce qu'il est. Add File sur un artefact de la vue Workspace ajoute un fichier à côté de lui : une page reçoit un fichier à elle à côté de ses vues, qui l'importent comme ./Row, et un Script Module, un Business Event ou un autre script, qui tient en un seul fichier, reçoit un fichier de code partagé dans le même package, dans un dossier à son nom, que tout script peut utiliser.

Le builder du projet fonctionne aussi, dans le navigateur. Une modification faite là n'est pas dans le dossier tant que vous ne la ramenez pas avec Pull Package to Folder, et un package modifié aux deux endroits est laissé tel quel et signalé une fois, donc rien n'est écrasé. Commitez ce que vous récupérez comme n'importe quelle autre modification.

Modifier les artefacts

Le code d'un artefact est un fichier, et ses réglages sont le JSON qui se trouve à côté, qui s'ouvre dans un formulaire. Chaque modification dans le formulaire est écrite dans le fichier ; Edit as JSON ouvre le texte.

Un Business Entity s'ouvre dans l'éditeur d'entité. Ses tables et ses colonnes sont choisies dans la base de données du projet, donc un nom qui n'existe pas est signalé avant l'enregistrement. Les réglages propres à l'espace de travail sont aussi des fichiers, dans workspace/ : le branding avec ses logos, et les layouts de l'application publiée, chacun s'ouvrant dans un formulaire.

Scripts C#

Les Script Modules, les scripts des Business Events, les data scripts PDF, les Scheduled Events et les scripts de test bénéficient des fonctionnalités C# d'un éditeur .NET. Elles sont fournies par le propre compilateur du projet, si bien que l'éditeur voit exactement ce que le script voit à l'exécution :

• Les complétions, avec la signature et la documentation de chaque membre.
• Le survol, et les informations sur les paramètres pendant que vous tapez un appel.
• Les erreurs et les avertissements au fil de la frappe.
• Go to Definition (F12). Sur la méthode d'un Script Module, il ouvre le script de ce module, sur un paramètre les réglages qui le déclarent, et sur tout le reste ses déclarations, en lecture seule.
• Format Document, dans le style .NET.

L'éditeur connaît les vraies variables globales des scripts (Db, Entity, Modules, Mail, Notify, Pdf, Ocr, Doc et Log), les paramètres d'un module sous forme de variables typées et, dans un Business Event, les colonnes de l'entité sur Entity. Les Business Entities sont des ensembles typés sur Db et les Script Modules des méthodes typées sur Modules, donc une colonne renommée ou un mauvais argument est une erreur sur sa ligne avant que quoi que ce soit ne s'exécute :

// A script module is a typed method: a wrong name or argument is an error as you type
var total = await Modules.Calc(qty: 2);

// Every business entity is a typed set
var open = await Db.Order
    .Where(o => o.Status == "Open")
    .ToListAsync();

Les Business Entities comme ensembles typés, dans la référence, explique comment les noms sont formés.

Les types dont plusieurs scripts ont besoin, comme des records et des helpers, vont dans un fichier C# partagé sous le dossier code/ d'un package. C'est du C# ordinaire, qui bénéficie des mêmes fonctionnalités, et F12 sur l'un de ses types dans un script ouvre le fichier. Shared Code, dans la référence, explique ce qu'un fichier partagé peut utiliser.

Les bibliothèques NuGet sont déclarées dans le nuget.json du package, chacune à une version exacte, et leurs types se complètent comme le reste une fois que l'espace de travail les a téléchargées. Voir NuGet Packages dans la référence.

Tester un Script Module

Test, au-dessus du code d'un Script Module, exécute le module comme le fait l'onglet Test du builder, avec le script tel que l'éditeur l'a, enregistré ou non. On le trouve aussi dans la barre de titre de l'éditeur, sur le module dans la vue Workspace et dans son formulaire. Un panneau à côté du script demande les paramètres, vérifie chaque valeur selon son type et les retient pour la fois suivante. Un module qui n'a besoin d'aucune valeur qu'il n'a pas déjà s'exécute aussitôt, et Ctrl+Enter dans le panneau le relance. Le panneau indique s'il a réussi, ce qu'il a renvoyé et ce qu'il a écrit dans Log, et en cas d'échec l'erreur avec un bouton vers sa ligne.

Un test s'exécute à blanc : les écritures via Db et Files sont listées au lieu d'être faites, les mails et les notifications listés au lieu d'être envoyés, y compris ceux des modules qu'il appelle. Tout ce que le script fait d'autre par lui-même est réel : les appels HTTP, System.IO, et tout ce que fait un paquet NuGet, comme une connexion à une autre base de données. Cochez Show the SQL it ran pour voir ses instructions dans le panneau SQL Trace. Seuls les rôles admin et owner peuvent tester. Un test dit ce que fait une exécution ; une vérification qui tourne à chaque fois est un cas de test, voir Tests.

Code des pages et des templates

Le code d'une page et le .tsx d'un Frontend Template sont vérifiés par rapport à ce dont ce code dispose réellement à l'exécution : backend, pageContext, currentUser, les hooks, React, chaque composant MUI avec ses props, les icônes, et un type de ligne pour chaque Business Entity, comme CustomerRow. Les complétions, le survol, les erreurs, l'accès à la définition, le renommage et Format Document fonctionnent tous, et un return au premier niveau est accepté. Tout cela tourne sur le TypeScript fourni avec VS Code, donc il n'y a rien à installer.

Le code peut être réparti sur plusieurs fichiers. Les propres fichiers d'une page se trouvent dans son dossier, à côté des vues, et s'importent sous la forme ./OrderRow ; le code dont plusieurs pages se servent va dans le dossier code/ d'un package et s'importe depuis @/, depuis n'importe quel package du dépôt. Les imports sont vérifiés et typés, l'accès à la définition les suit, et un renommage modifie chaque fichier qui utilise le nom.

What page code can use, le lien au-dessus du code de chaque page et de chaque template, ouvre la liste complète à côté : chaque variable globale avec ce qu'elle fait et un exemple, et les types de ligne du projet. Le builder affiche la même liste.

Aperçus

Open Preview to the Side, le bouton en haut à droite d'un PDF Template, d'un Frontend Template, du code d'une page ou d'un layout d'application, l'affiche tel qu'il est dans l'éditeur, enregistré ou non, et suit chaque modification :

• Un PDF Template est rendu par le projet. Son data script s'exécute à blanc, donc un aperçu n'écrit jamais de ligne et n'envoie jamais de mail. Les valeurs des paramètres peuvent être modifiées en haut.
• Un Frontend Template ou une page est rendu par la propre application du projet, avec les paramètres du template ou l'id d'enregistrement de la page en haut, et avec les propres fichiers de la page et le code partagé du dépôt tels qu'ils sont dans leurs éditeurs. Une page est dessinée dans le layout d'application que l'application publiée met autour d'elle ; la barre d'outils passe à un autre layout ou à aucun.
• Un layout d'application est dessiné par le propre shell de l'application publiée, pour une page que vous choisissez.
• Un template, une page ou un layout peut s'afficher sur un téléphone, une tablette ou un ordinateur à sa taille réelle, en paysage ou à une taille de votre choix, et être zoomé pour tenir dans le panneau ou à un pourcentage. L'aperçu suivant s'ouvre sur le dernier appareil choisi.

Tables

Les tables d'un package sont des fichiers, packages/<package>/tables/<table>.json, un par table. Ils s'ouvrent dans l'éditeur de tables : les colonnes avec leurs types, les clés, les valeurs par défaut et les clés étrangères, et les index de la table. La vue Database liste les tables du projet ; Open Database Diagram les dessine avec leurs clés étrangères, et faire glisser une table sur le diagramme écrit le layout.json du package. New Table demande à quel package la table appartient.

Enregistrer un fichier de table ne modifie pas la base de données du projet. Le reste du dossier est bien transmis, et la vue Workspace ainsi qu'un message indiquent quelles modifications de tables attendent une migration. Une base de données de projet neuve, au premier démarrage ou après une réinitialisation, reçoit d'elle-même les tables du dossier.

Migrations et retour arrière

Add Migration planifie les modifications de tables par rapport à la base de données du projet et affiche chaque opération, son risque et le SQL exact. Les opérations qui perdent des données, comme supprimer une table ou une colonne ou restreindre un type, demandent de cocher Allow data loss. La revue liste aussi les scripts typés que la modification empêcherait de compiler. La migration est enregistrée comme un déploiement en attente portant un nom, suggéré d'après ce qui change, comme AddTechnicianSkill ; Deploy l'exécute, et Add and Deploy fait les deux à la fois.

La vue Deployments est l'historique, du plus récent au plus ancien. Show SQL montre ce qu'un déploiement exécute. Roll Back to Here planifie le retour des tables à ce qu'un déploiement antérieur avait produit, et l'ajoute comme un déploiement en attente à part entière, à revoir et à déployer comme n'importe quelle migration. Un retour arrière restaure la structure, jamais les données : les lignes d'une table ou d'une colonne qu'il supprime sont perdues.

Drop Table retire le fichier de la table et marque la table ; elle disparaît quand une migration autorisant la perte de données est déployée.

Console SQL

New SQL Query ouvre un éditeur SQL sur la base de données du projet, avec la complétion des tables et des colonnes. Run Query (Ctrl+Enter) exécute la sélection, ou le fichier entier, instruction par instruction, chacune validée séparément, et s'arrête à la première erreur. Les résultats s'ouvrent à côté de l'éditeur, jusqu'à 1 000 lignes chacun, et se copient en CSV. Rien ne demande de confirmation avant un DELETE.

Plans de requête et traces SQL

Explain Query montre le plan que PostgreSQL choisit pour la sélection, ou pour l'instruction où se trouve le curseur : chaque étape, ce que chacune lit et combien de lignes elle attend. Explain Analyze Query (Ctrl+Alt+Enter) exécute l'instruction pour obtenir les temps et les nombres de lignes réels, dans une transaction ensuite annulée, donc même un DELETE garde ses lignes. Le plan signale l'étape qui prend le plus de temps et ce qui mérite un second regard : un parcours qui lit des milliers de lignes pour en garder quelques-unes, une estimation de lignes loin de ce qui est revenu, un tri qui a dû déborder sur le disque.

Trace SQL montre le SQL qu'Archestack envoie lui-même. Faites un clic droit sur un Script Module ou un Business Entity dans la vue Workspace, ou utilisez le bouton de son fichier ou de son formulaire. Un Script Module s'exécute avec les valeurs de paramètres que vous donnez, à blanc par défaut : ses écritures sont enregistrées au lieu d'être faites. Un Business Entity est lu comme la grille d'une page le lit. Le panneau SQL Trace liste alors chaque instruction avec ses valeurs, sa durée et le code qui l'a envoyée, et peut regrouper les instructions identiques pour faire apparaître une requête exécutée une fois par ligne. Cliquez sur une instruction pour voir son plan, l'ouvrir en SQL avec ses valeurs en place ou la copier. Dans la vue Testing, Run with SQL Trace fait de même pour les cas de test. Seuls les rôles admin et owner peuvent lancer une trace.

Tests

Run Tests dans la vue Workspace exécute les tests de tous les packages, ceux d'un seul package, une suite ou un seul cas. Le dossier est d'abord transmis au projet, donc un cas met à l'épreuve les scripts et les pages tels qu'ils sont dans le dossier. Chaque cas s'exécute dans une sandbox de test, une base de données à part, jamais sur les données du projet, et les mails et les notifications sont enregistrés au lieu d'être envoyés. Quatre cas s'exécutent en même temps. Dans l'arborescence, chaque cas affiche son dernier résultat et sa durée ; un clic dessus montre ce qui a échoué, l'attendu face au réel, et ce qu'il a affiché. La vue Testing liste les mêmes cas.

Une vérification qu'un seul sujet et un seul opérateur ne peuvent pas exprimer est une vérification de code : un fichier C# à part qui s'exécute après le cas, avec Result, Output, Error et Failed à portée de main, et qui échoue quand il lève une exception, fait échouer un Assert ou retourne false.

Event Log

La vue Event Log montre ce qui s'est exécuté dans le projet, regroupé par type : Business Events, Script Modules, Scheduled Events, exécutions de tests, mails et sauvegardes, chacun avec les exécutions et les échecs du dernier jour. Un nouvel échec est compté sur le badge de la vue et annoncé au moment où il se produit. Cliquez sur une entrée pour lire tout ce qu'elle a enregistré. Open Artifact ouvre le fichier du script dans lequel l'échec s'est produit, sur la ligne en échec.

Data API

Un endpoint de la Data API expose une Business Entity à d'autres systèmes, à une adresse comme /api/data/v1/customers. Il appartient à un package comme tout autre artefact : un seul fichier, api/customers.json, nommé d'après sa route et contenant toutes ses versions. Le fichier s'ouvre dans un formulaire : l'entité qu'il expose, son nom et sa route, et pour chaque version son statut, son jour de sunset, sa taille de page, ses opérations et ses champs. Chaque champ est un nom public posé sur une colonne de l'entité, renvoyé, modifiable ou obligatoire ; le formulaire propose les colonnes et signale un champ dont l'entité n'a pas la colonne.

Un endpoint peut aussi appeler un Script Module, pour un travail qui dépasse la lecture ou l'écriture de lignes. Chaque version nomme le module et la seule méthode à laquelle elle répond, POST avec les paramètres dans un corps JSON ou GET avec eux dans la chaîne de requête, et liste les paramètres que les appelants envoient : un nom public sur un paramètre du module, obligatoire ou non, avec une description. Le formulaire propose les paramètres du module et signale celui dont le module a besoin mais que la version ne transmet pas. L'appelant reçoit ce que le module renvoie, en JSON. Un module marqué admin only le reste : seuls les admins et les owners peuvent l'appeler, son endpoint ne prend donc aucune autorisation.

Une version publiée ne peut que grandir. Ajouter des champs et des opérations ne pose pas de problème ; supprimer ou renommer un champ, lui retirer l'écriture, le rendre obligatoire ou supprimer une opération casserait les systèmes qui l'appellent, et va donc dans une nouvelle version, que le formulaire démarre comme copie de celle affichée. Pour un endpoint qui appelle un Script Module, la version garde son module et sa méthode, et ne gagne que des paramètres optionnels. Un enregistrement qui casse une version publiée est refusé, avec la raison. Activer une version propose de déprécier les plus anciennes : elles restent servies et indiquent aux appelants, dans leurs en-têtes, qu'elles sont dépréciées et, dès que vous en fixez un, leur jour de sunset, jusqu'à ce que vous les passiez à Retired.

La vue Data API liste les endpoints du projet avec leurs versions, ainsi que ses API clients. Try It sur un endpoint ou une version envoie de vraies requêtes et affiche la réponse telle qu'elle est arrivée, en-têtes compris : en votre nom, avec le SQL exécuté si vous le souhaitez, ou avec la clé d'un API client, pour voir exactement ce que ce client peut appeler. Sur un endpoint qui appelle un Script Module, il envoie l'appel avec des paramètres d'exemple. Les boutons de la vue ouvrent le document OpenAPI de tout ce que vous pouvez appeler et How to connect, le guide pour ceux qui construisent dessus.

Qui peut appeler un endpoint se décide dans chaque environnement et ne figure jamais dans le fichier. Dans le formulaire, Edit access in the workspace ouvre les autorisations : quels rôles peuvent lister, lire, créer, modifier ou supprimer, ou appeler le module. Un API client est un compte de service avec des rôles et une clé au lieu d'un mot de passe. New API Client en crée un et affiche sa clé une seule fois ; Rotate Key la remplace, et l'ancienne clé cesse aussitôt de fonctionner.

Agents de code

Le dépôt indique aux agents de code comme Claude Code et Codex ce qu'ils peuvent y créer, de la même façon que le MCP Server l'indique à un modèle connecté. New Package et chaque pull écrivent :

• AGENTS.md : comment une modification atteint l'application, les règles que suit chaque fichier, les erreurs à éviter et un exemple de chaque type d'artefact. Seule la section balisée de l'extension est réécrite, donc les notes propres à votre équipe dans ce fichier restent en place.
• CLAUDE.md, qui renvoie Claude Code vers AGENTS.md.
• docs/archestack/ : les guides de script et de test, et ce que le code des pages peut utiliser. Ce dossier est commité, donc un agent qui travaille sur un clone tout frais en dispose aussi.
• .archestack/context/ : les Business Entities du projet et son modèle de données généré, pour cette machine uniquement.

Update Agent Instructions les réécrit. Les modifications d'un agent sont des fichiers enregistrés comme les vôtres, elles atteignent donc le projet de la même façon ; une personne les relit et les commite.

Travailler en équipe

Dans une entreprise plus grande, le dépôt est la source de vérité de l'application, de la même façon que l'infrastructure as code décrit des serveurs : tout ce qui compose l'application est un fichier dans git, relu et versionné comme n'importe quel autre code, et chaque environnement est construit à partir de ces fichiers. L'extension est ce avec quoi chaque développeur travaille dessus.

Développeur 1

Fichiers du dépôt Projet local

Développeur 2

Fichiers du dépôt Projet local

Développeur 3

Fichiers du dépôt Projet local

push et pull

Serveur git

Le dépôt : branches, pull requests et main

Pipeline

Build, tests, plan, déploiement

Test

Archestack hébergé

Recette

Archestack hébergé

Production

Archestack hébergé

Chaque développeur fait tourner sa propre copie

Chaque développeur clone le dépôt et l'ouvre, et sa fenêtre fait tourner un projet qui lui est propre, avec sa propre base de données, sur sa propre machine. Personne ne partage un espace de travail de développement, donc personne n'enregistre par-dessus le travail d'un autre, et un script qui casse reste sur une seule machine jusqu'à ce qu'il soit corrigé. Un nouveau membre de l'équipe a l'application qui tourne une quinzaine de secondes après le clone. Les tables d'un projet démarrent vides, et les cas de test écrivent les lignes dont ils ont besoin dans leur propre sandbox, donc chaque développeur teste sur les mêmes données.

Un package par équipe

Une grande application se compose de plusieurs packages, chacun un dossier avec ses propres tables, Business Entities, pages, scripts et tests. Découpez-les comme l'entreprise est découpée, et les équipes travaillent surtout dans des dossiers qui leur sont propres :

packages/
  core/        customers, products, shared scripts     team Platform
  sales/       quotes and orders, needs core           team Sales
  planning/    work orders and schedules, needs core   team Operations
  invoicing/   invoices and PDF templates, needs sales team Finance

Un package nomme les packages dont il a besoin dans son package.json, par nom et par plage de versions :

{
  "formatVersion": 1,
  "name": "invoicing",
  "version": "1.4.0",
  "description": "Invoices and their PDFs, made from sales orders.",
  "dependencies": [
    { "name": "sales", "versionRange": "[2.0,3.0)" }
  ],
  "masterData": []
}

Une version seule comme 2.0 signifie cette version ou une plus récente, [2.0] exactement celle-là, et [2.0,3.0) n'importe quelle version à partir de 2.0 jusqu'à 3.0, non comprise. Un projet charge les dépendances avant les packages qui en ont besoin. Une table qu'un autre package possède est emportée comme simple référence : un package peut y faire pointer une clé étrangère, mais ne la modifie jamais. La fonctionnalité code owners de votre hébergeur git peut ensuite exiger, pour chaque dossier, une relecture par l'équipe qui le possède.

Ou un dépôt par équipe

Les équipes qui doivent aussi pouvoir livrer à leur propre rythme peuvent chacune posséder un dépôt à la place, et avec lui une application, un projet et des environnements qui leur sont propres. Les données qu'une équipe possède et dont une autre a besoin atteignent cette autre équipe sous forme de tables tierces : ses environnements se connectent à la base de données de l'équipe propriétaire et mettent en miroir les tables dont ils ont besoin, selon une planification. Une table en miroir se lit comme n'importe quelle autre table de l'application, dans les Business Entities, les pages et les scripts.

sales-app/       team Sales        owns customers, quotes and orders
planning-app/    team Operations   mirrors customers from sales-app
invoicing-app/   team Finance      mirrors customers and orders from sales-app

• Un seul propriétaire par table. Une table en miroir se modifie dans l'application qui la possède ; les autres lisent leur copie. Les colonnes marquées comme "gérées par Archestack" font exception : elles contiennent les ajouts propres à une équipe, et une synchronisation ne les écrase jamais.
• Aussi à jour que la dernière synchronisation. Une table se synchronise en entier ou selon ce qui a changé, ce qui demande une colonne indiquant quand une ligne a changé pour la dernière fois, comme modified_at.
• Les connexions appartiennent à l'environnement. Elles ne figurent pas dans les fichiers, donc chaque environnement se connecte à son propre homologue : la recette à la recette, la production à la production.

Un seul dépôt avec un package par équipe se déploie comme une seule application, et un package peut faire pointer une clé étrangère vers une table d'un autre package. Un dépôt par équipe permet à chaque équipe de livrer à son propre rythme, et le paie avec des copies qui ne sont jamais plus à jour que leur dernière synchronisation.

Branches et relectures

• Travaillez sur une branche et ouvrez une pull request, comme pour n'importe quel code. Chaque référence est un nom et le même contenu donne toujours les mêmes octets, donc un diff ne montre que ce que quelqu'un a modifié : une ligne d'un script, une colonne, le JSX d'une page, jamais un id renuméroté ou des clés réordonnées.
• Passer sur une autre branche modifie les fichiers, et le projet les suit comme il suit vos enregistrements. Les modifications de tables attendent alors une migration ; Reset Project Database repart plutôt des tables de la branche.
• Un relecteur passe sur la branche, la fait tourner dans son propre projet et exécute dessus les tests du package avec Run Tests. Les tests vivent dans le package, ils voyagent donc avec le code qu'ils testent.
• AGENTS.md et docs/archestack/ sont commités, donc l'agent de code de chaque développeur suit les mêmes règles.

Les tables en équipe

Un fichier de table décrit la structure qu'une table doit avoir, pas les étapes pour y arriver. Après un pull ou une fusion, le projet de chaque développeur planifie sa propre migration à partir des fichiers de table avec Add Migration, et la revue montre exactement ce que cette base de données va exécuter, perte de données et scripts typés qui ne compileraient plus compris. Chaque outil écrit un fichier de table sous une seule forme canonique, donc les modifications de deux personnes sur une même table n'entrent en conflit que là où elles changent la même chose.

Ce que chaque environnement décide

Qui peut voir une page, ce qui est public, les autorisations de la Data API et les API clients, les utilisateurs et les rôles, les comptes mail, les connexions à d'autres systèmes et l'historique des exécutions ne figurent pas dans les fichiers. Les administrateurs de chaque environnement les règlent, donc une fusion ne peut jamais rendre quelque chose public ni donner accès à qui que ce soit.

Le test, la recette et la production sont déployés depuis le dépôt par un pipeline, comme le décrit Stratégie de déploiement.

Paramètres

Faire entrer un package existant

Un package qui n'existe jusqu'ici que dans un espace de travail hébergé entre une fois dans le dépôt : lancez Connect to Workspace depuis la Command Palette, connectez-vous, utilisez Pull Package to Folder sur le package, puis choisissez de nouveau le projet dans la barre d'état. À partir de là, le dossier est la source et le projet le fait tourner. Les tables du package l'accompagnent, celles vers lesquelles il pointe une clé étrangère étant marquées comme simples références, afin que le projet puisse créer chaque table dont le package a besoin. Dans un projet qui a déjà une base de données, ces tables attendent une migration comme toute autre modification de table.

Pièges

• Un projet démarre avec des tables vides. Le dossier porte la structure, pas les lignes. Le chargement de données de base depuis le dépôt n'est pas encore disponible.
• Les tables ne changent jamais à l'enregistrement. Seule une migration déployée modifie la base de données du projet, en dehors d'un démarrage à neuf ou d'une réinitialisation.
• Une réinitialisation jette les données du projet. Tout le reste est dans le dossier et revient ; les lignes que vous avez saisies, non.
• Les modifications faites dans le builder restent dans le projet jusqu'à ce que vous les récupériez dans le dossier, et une réinitialisation les fait perdre.

Pour aller plus loin

Espaces de travail et hébergement explique où tourne votre application une fois qu'elle quitte votre machine. La référence couvre plus en détail les packages, les Script Modules et les déploiements de base de données.