Archestack w VS Code

Z rozszerzeniem Archestack dla Visual Studio Code Twoja aplikacja jest repozytorium git i działa na Twojej własnej maszynie. Otwórz folder repozytorium, a rozszerzenie uruchomi dla niego lokalny Archestack: PostgreSQL, API i builder, z runtime'u dostarczanego z rozszerzeniem. Nie ma przestrzeni roboczej, z którą trzeba się łączyć, ani niczego innego do instalowania. Script Modules, Business Events, strony, szablony i tabele są plikami w folderze, a każdy zapisany plik dociera do lokalnego Archestack chwilę później.

Ten lokalny Archestack nazywa się projektem. Należy do repozytorium: członek zespołu, który je sklonuje, dostaje ten sam projekt, zbudowany z tych samych plików. Praca w zespole opisuje, jak programiści większej firmy dzielą jedno repozytorium, a strona Rozszerzenie VS Code w szczegółach pokazuje każdy ekran.

Instalacja

Rozszerzenia nie ma jeszcze w Visual Studio Marketplace. Jest dostarczane jako plik VSIX: w VS Code otwórz Command Palette, uruchom Extensions: Install from VSIX... i wskaż plik. Wymaga VS Code 1.90 lub nowszego.

Używaj wersji dla Windows (x64). Zawiera runtime Archestack, API, builder i PostgreSQL, więc projekt działa bez instalowania czegokolwiek innego. PDF-y renderują się w Edge albo Chrome, który jest już zainstalowany na maszynie. Wersja uniwersalna nie ma runtime'u i zamiast tego uruchamia projekty w Docker Desktop.

Rozszerzenie nie potrzebuje rozszerzenia C# od Microsoftu ani C# Dev Kit. Jego funkcje C# pochodzą z samego projektu, a jego skrypty otwierają się we własnym języku, więc każde z nich może pozostać zainstalowane i nie będą sobie wchodzić w drogę.

Uruchomienie projektu

• Nowa aplikacja. Otwórz pusty folder, otwórz widok Archestack na pasku aktywności i wybierz Start project. Rozszerzenie dodaje archestack.json, tworzy świeżą bazę danych, uruchamia API i builder i samo loguje się jako admin projektu. New Package zakłada następnie folder pierwszego package'a.
• Istniejące repozytorium. Sklonuj je i otwórz jego folder. Okno samo uruchamia projekt: pierwsze uruchomienie tworzy bazę danych i wczytuje repozytorium, najpierw tabele wszystkich packages, potem artefakty, zależności przed packages, które ich potrzebują. Świeży klon staje się działającą aplikacją w ciągu około piętnastu sekund, a po ponownym otwarciu okna projekt znów rusza.

Projekt jest opisany w archestack.json, który jest commitowany:

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

Builder i API dzielą webPort, a PostgreSQL nasłuchuje na dbPort, oba wyłącznie na 127.0.0.1. Baza danych projektu, jego wygenerowane hasła i logi znajdują się w .archestack/project/, który git ignoruje. Pakiety NuGet pobierane przez jego skrypty też są tam trzymane, w .archestack/project/nuget, albo w woluminie Dockera o nazwie nuget, gdy projekt działa w Dockerze, więc restart nie pobiera ich ponownie.

Pasek stanu pokazuje projekt jako local. Jego lista otwiera builder projektu w przeglądarce, zatrzymuje projekt i pokazuje logi API. Reset Project Database wyrzuca dane projektu i wczytuje repozytorium od nowa.

Projekt należy do okna, w którym działa. Zamknięcie lub przeładowanie okna zatrzymuje API i PostgreSQL, więc nic nie działa dalej w tle, a następne okno uruchamia je ponownie w kilka sekund. Jeśli API przestanie odpowiadać w trakcie pracy, okno uruchomi je ponownie w ciągu dziesięciu sekund.

Repozytorium

Repozytorium zawiera jeden folder na package i jeden lub więcej plików na artefakt:

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

Odwołania między artefaktami to nazwy, nigdy identyfikatory z bazy danych. W plikach nie ma niczego, o czym decyduje się osobno w każdym środowisku: to, kto może widzieć stronę, czy cokolwiek jest publiczne, uprawnienia Data API i historia uruchomień zostają w każdym środowisku. Ta sama zawartość zawsze daje te same bajty, więc git pokazuje tylko prawdziwe zmiany.

Projekt dostaje zawartość folderu przy każdym zapisie. Zapisana zmiana w packages/ dociera do niego chwilę później, a to, co usuniesz w folderze, jest tam usuwane, łącznie z całym folderem package'a. Nie ma czego wysyłać. Wyjątkiem są tabele: zmieniają się przez migracje.

New Package zakłada folder package'a, a New Artifact in Package (kliknij prawym przyciskiem cokolwiek w packages/ w widoku Explorer albo + przy package'u w widoku Workspace) zapisuje pliki nowego artefaktu i pyta tylko o to, bez czego nie może on istnieć, na przykład o Business Entity, do którego należy Business Event. Nowa strona jest stroną w kodzie. Dla nowego pliku kodu współdzielonego podajesz ścieżkę, a rozszerzenie pliku mówi, czym on jest. Add File przy artefakcie w widoku Workspace dodaje obok niego plik: strona dostaje własny plik obok swoich widoków, które importują go jako ./Row, a Script Module, Business Event albo inny skrypt, który jest jednym plikiem, dostaje plik kodu współdzielonego w tym samym package'u, w folderze nazwanym jak on, z którego może korzystać każdy skrypt.

Builder projektu też działa, w przeglądarce. Zmiana wprowadzona w nim nie trafia do folderu, dopóki nie przeniesiesz jej przez Pull Package to Folder, a package zmieniony w obu miejscach zostaje nietknięty, o czym rozszerzenie informuje jeden raz, więc nic nie zostaje nadpisane. Pobrane zmiany commituj jak każdą inną zmianę.

Edycja artefaktów

Kod artefaktu jest plikiem, a jego ustawienia to plik JSON obok niego, który otwiera się w formularzu. Każda zmiana w formularzu jest zapisywana w pliku; Edit as JSON otwiera tekst.

Business Entity otwiera się w edytorze encji. Jego tabele i kolumny wybiera się z bazy danych projektu, więc nazwa, która nie istnieje, zostaje oznaczona, zanim zapiszesz. Własne ustawienia przestrzeni roboczej też są plikami, w workspace/: branding z logotypami i układy opublikowanej aplikacji, każde otwierane w formularzu.

Skrypty C#

Script Modules, skrypty Business Events, skrypty danych PDF, Scheduled Events i skrypty testów mają funkcje C# edytora .NET. Obsługuje je kompilator samego projektu, więc edytor widzi dokładnie to, co skrypt widzi, kiedy działa:

• Podpowiedzi, z sygnaturą i dokumentacją każdej składowej.
• Opisy po najechaniu kursorem i informacje o parametrach podczas pisania wywołania.
• Błędy i ostrzeżenia na bieżąco, w trakcie pisania.
• Go to Definition (F12). Na metodzie Script Module otwiera skrypt tego modułu, na parametrze ustawienia, które go deklarują, a na czymkolwiek innym jego deklaracje, tylko do odczytu.
• Format Document, w stylu .NET.

Edytor zna prawdziwe globale skryptów (Db, Entity, Modules, Mail, Notify, Pdf, Ocr, Doc i Log), parametry modułu jako typowane zmienne, a w Business Event kolumny encji na Entity. Business Entities są typowanymi zbiorami na Db, a Script Modules typowanymi metodami na Modules, więc kolumna o zmienionej nazwie albo błędny argument to błąd w jego linii, zanim cokolwiek się uruchomi:

// 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();

Sekcja Business Entities jako typowane zbiory na stronie Reference wyjaśnia, jak powstają nazwy.

Typy, których potrzebuje więcej niż jeden skrypt, takie jak rekordy i helpery, trafiają do współdzielonego pliku C# w folderze code/ package'a. To zwykły C# z tymi samymi funkcjami, a F12 na jednym z jego typów w skrypcie otwiera ten plik. Sekcja Shared Code na stronie Reference wyjaśnia, czego może używać plik współdzielony.

Biblioteki z NuGet są deklarowane w nuget.json package'a, każda w dokładnej wersji, a ich typy są podpowiadane jak cała reszta, gdy tylko przestrzeń robocza je pobierze. Zobacz NuGet Packages na stronie Reference.

Testowanie Script Module

Test nad kodem Script Module uruchamia moduł tak, jak robi to zakładka Test w builderze, ze skryptem w takiej postaci, w jakiej ma go edytor, zapisanym lub nie. Znajdziesz go też na pasku tytułu edytora, przy module w widoku Workspace i w jego formularzu. Panel obok skryptu pyta o parametry, sprawdza każdą wartość względem jej typu i zapamiętuje je na następny raz. Moduł, który nie potrzebuje żadnej wartości, której jeszcze nie ma, uruchamia się od razu, a Ctrl+Enter w panelu uruchamia go ponownie. Panel pokazuje, czy test przeszedł, co moduł zwrócił i co zapisał do Log, a przy błędzie komunikat z przyciskiem prowadzącym do jego wiersza.

Test działa w trybie próbnym: zapisy przez Db i Files są wymieniane, a nie wykonywane, a maile i powiadomienia wymieniane, a nie wysyłane, także te z modułów, które wywołuje. Wszystko inne, co skrypt robi sam, dzieje się naprawdę: wywołania HTTP, System.IO i wszystko, co robi pakiet NuGet, na przykład połączenie z inną bazą danych. Zaznacz Show the SQL it ran, żeby zobaczyć jego instrukcje w panelu SQL Trace. Testować mogą tylko role admin i owner. Test mówi, co robi jedno uruchomienie; sprawdzenie, które działa za każdym razem, to przypadek testowy, zobacz Testy.

Kod stron i szablonów

Kod strony i plik .tsx Frontend Template są sprawdzane względem tego, co ten kod naprawdę ma do dyspozycji, gdy działa: backend, pageContext, currentUser, hooki, React, każdy komponent MUI z jego propsami, ikony oraz typ wiersza dla każdego Business Entity, na przykład CustomerRow. Działają podpowiedzi, opisy po najechaniu kursorem, błędy, przejście do definicji, zmiana nazwy i Format Document, a return na najwyższym poziomie jest w porządku. Wszystko działa na TypeScripcie dostarczanym z VS Code, więc nie trzeba niczego instalować.

Kod można rozłożyć na kilka plików. Własne pliki strony leżą w jej folderze obok widoków i są importowane jako ./OrderRow; kod, którego używa więcej niż jedna strona, trafia do folderu code/ package'a i jest importowany z @/, z dowolnego package'a repozytorium. Importy są sprawdzane i typowane, przejście do definicji podąża za nimi, a zmiana nazwy zmienia każdy plik, który tej nazwy używa.

What page code can use, link nad kodem każdej strony i każdego szablonu, otwiera obok pełną listę: każdy global z opisem tego, co robi, i przykładem oraz typy wierszy projektu. Builder pokazuje tę samą listę.

Podglądy

Open Preview to the Side, przycisk w prawym górnym rogu PDF Template, Frontend Template, kodu strony albo układu aplikacji, pokazuje go w stanie, w jakim jest w edytorze, zapisanym lub nie, i nadąża za każdą zmianą:

• PDF Template renderuje projekt. Jego skrypt danych działa w trybie próbnym, więc podgląd nigdy nie zapisuje wiersza ani nie wysyła maila. Wartości parametrów można zmienić u góry.
• Frontend Template albo stronę renderuje własna aplikacja projektu, z parametrami szablonu albo identyfikatorem rekordu strony u góry oraz z własnymi plikami strony i kodem współdzielonym repozytorium w stanie, w jakim są w edytorach. Strona jest rysowana w układzie aplikacji, który opublikowana aplikacja wokół niej umieszcza; pasek narzędzi przełącza na inny układ albo na żaden.
• Układ aplikacji rysuje własna powłoka opublikowanej aplikacji, dla wybranej przez Ciebie strony.
• Szablon, stronę albo układ można pokazać na telefonie, tablecie albo komputerze w prawdziwym rozmiarze, poziomo albo we własnym rozmiarze, i powiększyć tak, by się zmieściły, albo do wybranego procentu. Następny podgląd otwiera się na urządzeniu wybranym ostatnio.

Tabele

Tabele package'a są plikami, packages/<package>/tables/<table>.json, po jednym na tabelę. Otwierają się w edytorze tabel: kolumny z typami, klucze, wartości domyślne i klucze obce oraz indeksy tabeli. Widok Database wymienia tabele projektu; Open Database Diagram rysuje je razem z kluczami obcymi, a przeciągnięcie tabeli na diagramie zapisuje layout.json package'a. New Table pyta, do którego package'a należy tabela.

Zapisanie pliku tabeli nie zmienia bazy danych projektu. Reszta folderu trafia do projektu, a widok Workspace i komunikat mówią, które zmiany tabel czekają na migrację. Świeża baza danych projektu, przy pierwszym uruchomieniu albo po resecie, dostaje tabele z folderu sama.

Migracje i wycofywanie

Add Migration planuje zmiany tabel względem bazy danych projektu i pokazuje każdą operację, jej ryzyko i dokładny SQL. Operacje, które tracą dane, takie jak usunięcie tabeli lub kolumny albo zawężenie typu, wymagają zaznaczenia Allow data loss. Przegląd wymienia też typowane skrypty, które po tej zmianie przestałyby się kompilować. Migracja jest zapisywana jako oczekujące wdrożenie z nazwą podpowiadaną na podstawie tego, co się zmienia, na przykład AddTechnicianSkill; Deploy ją uruchamia, a Add and Deploy robi obie rzeczy naraz.

Widok Deployments to historia, od najnowszych. Show SQL pokazuje, co wdrożenie wykona. Roll Back to Here planuje przywrócenie tabel do stanu, w jakim zostawiło je wcześniejsze wdrożenie, i dodaje to jako osobne oczekujące wdrożenie, do przejrzenia i wdrożenia jak każda migracja. Wycofanie przywraca strukturę, nigdy dane: wiersze w tabeli lub kolumnie, którą usuwa, przepadają.

Drop Table usuwa plik tabeli i oznacza tabelę; znika ona, gdy zostanie wdrożona migracja z dozwoloną utratą danych.

Konsola SQL

New SQL Query otwiera edytor SQL na bazie danych projektu, z podpowiadaniem tabel i kolumn. Run Query (Ctrl+Enter) wykonuje zaznaczenie albo cały plik, instrukcja po instrukcji, każdą zatwierdzaną osobno, i zatrzymuje się na pierwszym błędzie. Wyniki otwierają się obok edytora, do 1000 wierszy każdy, i można je skopiować jako CSV. Przed DELETE nic nie pyta o potwierdzenie.

Plany zapytań i śledzenie SQL

Explain Query pokazuje plan, który PostgreSQL wybiera dla zaznaczenia albo dla instrukcji, w której stoi kursor: każdy krok, co każdy z nich czyta i ilu wierszy się spodziewa. Explain Analyze Query (Ctrl+Alt+Enter) wykonuje instrukcję, żeby pokazać rzeczywiste czasy i liczby wierszy, w transakcji, która jest wycofywana, więc nawet DELETE zostawia wiersze na miejscu. Plan wyróżnia krok, który zajmuje najwięcej czasu, i to, co warto obejrzeć drugi raz: skan, który czyta tysiące wierszy, żeby zostawić kilka, szacunek liczby wierszy daleki od tego, co wróciło, sortowanie, które musiało zejść na dysk.

Trace SQL pokazuje SQL, który wysyła sam Archestack. Kliknij prawym przyciskiem Script Module albo Business Entity w widoku Workspace albo użyj przycisku w jego pliku lub formularzu. Script Module działa z wartościami parametrów, które podasz, domyślnie w trybie próbnym, w którym zapisy są rejestrowane, a nie wykonywane. Business Entity jest odczytywany tak, jak odczytuje go siatka strony. Panel SQL Trace wymienia wtedy każdą instrukcję z jej wartościami, czasem trwania i kodem, który ją wysłał, i potrafi zebrać razem te same instrukcje, żeby pokazać zapytanie wykonywane raz na wiersz. Kliknij instrukcję, żeby zobaczyć jej plan, otworzyć ją jako SQL ze wstawionymi wartościami albo ją skopiować. W widoku Testing to samo dla przypadków testowych robi Run with SQL Trace. Śledzić SQL mogą tylko role admin i owner.

Testy

Run Tests w widoku Workspace uruchamia testy wszystkich packages albo jednego package'a, jeden zestaw albo pojedynczy przypadek. Folder najpierw trafia do projektu, więc przypadek sprawdza skrypty i strony w postaci, w jakiej są w folderze. Każdy przypadek działa w testowym sandboxie, osobnej bazie danych, nigdy na danych projektu, a maile i powiadomienia są rejestrowane, a nie wysyłane. Cztery przypadki działają jednocześnie. Każdy przypadek pokazuje w drzewie swój ostatni wynik i czas trwania; kliknięcie go pokazuje, co zawiodło, wartość oczekiwaną wobec rzeczywistej i to, co wypisał. Widok Testing wymienia te same przypadki.

Sprawdzenie, którego nie da się wyrazić jednym przedmiotem sprawdzenia i jednym operatorem, jest sprawdzeniem w kodzie: osobnym plikiem C#, który działa po przypadku, ma do dyspozycji Result, Output, Error i Failed i kończy się niepowodzeniem, gdy rzuci wyjątek, nie przejdzie Assert albo zwróci false.

Event Log

Widok Event Log pokazuje, co zostało uruchomione w projekcie, pogrupowane według rodzaju: Business Events, Script Modules, Scheduled Events, uruchomienia testów, poczta i kopie zapasowe, każdy z uruchomieniami i niepowodzeniami z ostatniej doby. Nowe niepowodzenie jest liczone na plakietce widoku i ogłaszane na bieżąco. Kliknij wpis, żeby przeczytać wszystko, co zarejestrował. Open Artifact otwiera plik skryptu, w którym wystąpił błąd, na linii z błędem.

Data API

Endpoint Data API udostępnia Business Entity innym systemom pod adresem takim jak /api/data/v1/customers. Należy do pakietu jak każdy inny artefakt: jeden plik, api/customers.json, nazwany od jego trasy i zawierający wszystkie jego wersje. Plik otwiera się w formularzu: encja, którą udostępnia, jego nazwa i trasa, a dla każdej wersji status, dzień sunset, rozmiar strony, operacje i pola. Każde pole to publiczna nazwa nad kolumną encji, zwracana, zapisywalna lub wymagana; formularz podpowiada kolumny i oznacza pole, którego kolumny encja nie ma.

Endpoint może też wywoływać Script Module, do pracy, która wykracza poza odczyt lub zapis wierszy. Każda wersja wskazuje moduł i jedyną metodę, na którą odpowiada, POST z parametrami w ciele JSON albo GET z parametrami w adresie URL, i wymienia parametry, które wysyłają wywołujący: publiczną nazwę nad parametrem modułu, wymaganą lub nie, z opisem. Formularz podpowiada parametry modułu i oznacza ten, którego moduł potrzebuje, a wersja go nie przekazuje. Wywołujący dostaje to, co zwraca moduł, w formacie JSON. Moduł oznaczony jako admin only taki pozostaje: wywołać go mogą tylko role admin i owner, więc jego endpoint nie przyjmuje uprawnień.

Opublikowana wersja może tylko rosnąć. Dodawanie pól i operacji jest w porządku; usunięcie pola albo zmiana jego nazwy, odebranie mu zapisu, uczynienie go wymaganym lub usunięcie operacji zepsułoby systemy, które ją wywołują, więc trafia to do nowej wersji, którą formularz zaczyna jako kopię wyświetlanej. W endpoincie, który wywołuje Script Module, wersja zachowuje swój moduł i metodę i zyskuje tylko parametry opcjonalne. Zapis, który psuje opublikowaną wersję, zostaje odrzucony z podaniem powodu. Aktywacja wersji proponuje oznaczenie starszych jako przestarzałe: nadal są obsługiwane i w nagłówkach informują wywołujących, że są przestarzałe, a gdy go ustawisz, także o dniu sunset, dopóki nie przestawisz ich na Retired.

Widok Data API pokazuje endpointy projektu z ich wersjami oraz jego klientów API. Try It na endpoincie lub wersji wysyła prawdziwe żądania i pokazuje odpowiedź tak, jak przyszła, razem z nagłówkami: jako ty, jeśli chcesz z wykonanym SQL, albo z kluczem klienta API, żeby zobaczyć dokładnie, co ten klient może wywołać. Na endpoincie, który wywołuje Script Module, wysyła wywołanie z przykładowymi parametrami. Przyciski widoku otwierają dokument OpenAPI wszystkiego, co możesz wywołać, oraz How to connect, przewodnik dla tych, którzy na nim budują.

To, kto może wywoływać endpoint, ustala każde środowisko i nigdy nie trafia to do pliku. Edit access in the workspace w formularzu otwiera uprawnienia: które role mogą listować, pobierać, tworzyć, aktualizować lub usuwać albo wywoływać moduł. Klient API to konto usługi z rolami i kluczem zamiast hasła. New API Client tworzy nowego i pokazuje jego klucz jeden raz; Rotate Key go zastępuje, a stary klucz od razu przestaje działać.

Agenci kodujący

Repozytorium mówi agentom kodującym, takim jak Claude Code i Codex, co mogą w nim tworzyć, tak jak MCP Server mówi to podłączonemu modelowi. New Package i każde pobranie zapisują:

• AGENTS.md: jak zmiana trafia do aplikacji, reguły, których przestrzega każdy plik, błędy, których należy unikać, i przykład każdego rodzaju artefaktu. Przepisywana jest tylko oznaczona sekcja rozszerzenia, więc własne notatki Twojego zespołu w tym pliku zostają.
• CLAUDE.md, który kieruje Claude Code do AGENTS.md.
• docs/archestack/: przewodniki po skryptach i testach oraz to, czego może używać kod stron. Folder jest commitowany, więc agent pracujący na świeżym klonie też je ma.
• .archestack/context/: Business Entities projektu i jego wygenerowany model danych, tylko dla tej maszyny.

Update Agent Instructions zapisuje je ponownie. Zmiany agenta to zapisane pliki, tak jak Twoje, więc docierają do projektu w ten sam sposób; człowiek je przegląda i commituje.

Praca w zespole

W większej firmie repozytorium jest źródłem prawdy o aplikacji, tak jak infrastructure as code opisuje serwery: wszystko, z czego składa się aplikacja, jest plikiem w git, przeglądanym i wersjonowanym jak każdy inny kod, a każde środowisko jest budowane z tych plików. Rozszerzenie jest narzędziem, którym każdy programista na nich pracuje.

Programista 1

Pliki repozytorium Projekt lokalny

Programista 2

Pliki repozytorium Projekt lokalny

Programista 3

Pliki repozytorium Projekt lokalny

push i pull

Serwer git

Repozytorium: gałęzie, pull requesty i main

Pipeline

Build, testy, plan, wdrożenie

Test

Hostowany Archestack

Akceptacja

Hostowany Archestack

Produkcja

Hostowany Archestack

Każdy programista uruchamia własną kopię

Każdy programista klonuje repozytorium i je otwiera, a jego okno uruchamia własny projekt, z własną bazą danych, na jego własnej maszynie. Nikt nie dzieli deweloperskiej przestrzeni roboczej, więc nikt nie nadpisuje cudzej pracy, a skrypt, który się psuje, zostaje na jednej maszynie, dopóki nie zostanie naprawiony. Nowy członek zespołu ma działającą aplikację około piętnastu sekund po sklonowaniu. Tabele projektu są na początku puste, a przypadki testowe zapisują potrzebne im wiersze we własnym sandboxie, więc każdy programista testuje na tych samych danych.

Jeden package na zespół

Duża aplikacja to kilka packages, każdy w osobnym folderze z własnymi tabelami, Business Entities, stronami, skryptami i testami. Podziel je tak, jak podzielona jest firma, a zespoły będą pracować głównie we własnych folderach:

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

Package wymienia w swoim package.json packages, których potrzebuje, po nazwie i zakresie wersji:

{
  "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": []
}

Sama wersja, na przykład 2.0, oznacza tę wersję lub nowszą, [2.0] dokładnie tę jedną, a [2.0,3.0) cokolwiek od 2.0 do 3.0, ale bez 3.0. Projekt wczytuje zależności przed packages, które ich potrzebują. Tabela, której właścicielem jest inny package, jest dołączana jako tylko referencyjna: package może wskazywać na nią kluczem obcym, ale nigdy jej nie zmienia. Funkcja code owners Twojej platformy git może wtedy wymagać, żeby każdy folder przeglądał zespół, który jest jego właścicielem.

Albo repozytorium na zespół

Zespoły, które mają też wydawać wersje we własnym rytmie, mogą zamiast tego mieć każdy własne repozytorium, a wraz z nim własną aplikację, projekt i środowiska. Dane, których właścicielem jest jeden zespół, a których potrzebuje inny, trafiają do niego jako tabele third-party: jego środowiska łączą się z bazą danych zespołu, który jest ich właścicielem, i według harmonogramu tworzą kopie lustrzane potrzebnych tabel. Tabelę lustrzaną czyta się jak każdą inną tabelę aplikacji, w Business Entities, stronach i skryptach.

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

• Jeden właściciel na tabelę. Tabelę lustrzaną zmienia się w aplikacji, która jest jej właścicielem; pozostałe czytają swoją kopię. Wyjątkiem są kolumny oznaczone jako zarządzane przez Archestack: przechowują własne dodatki zespołu i synchronizacja nigdy ich nie nadpisuje.
• Tak aktualna jak ostatnia synchronizacja. Tabela synchronizuje się w całości albo tylko o to, co się zmieniło, a to wymaga kolumny mówiącej, kiedy wiersz ostatnio się zmienił, na przykład modified_at.
• Połączenia należą do środowiska. Nie ma ich w plikach, więc każde środowisko łączy się ze swoim odpowiednikiem: akceptacyjne z akceptacyjnym, produkcyjne z produkcyjnym.

Jedno repozytorium z jednym package'em na zespół jest wdrażane jako jedna aplikacja, a package może wskazywać kluczem obcym na tabelę innego package'a. Repozytorium na zespół pozwala każdemu zespołowi wydawać wersje samodzielnie, a płaci się za to kopiami, które są tylko tak aktualne jak ich ostatnia synchronizacja.

Gałęzie i przeglądy

• Pracuj na gałęzi i otwieraj pull request, jak przy każdym kodzie. Każde odwołanie jest nazwą, a ta sama zawartość zawsze daje te same bajty, więc diff pokazuje tylko to, co ktoś zmienił: linię skryptu, kolumnę, JSX strony, nigdy przenumerowany identyfikator ani klucze w innej kolejności.
• Przełączenie się na inną gałąź zmienia pliki, a projekt podąża za nimi tak, jak podąża za Twoimi zapisami. Zmiany tabel czekają wtedy na migrację; Reset Project Database zamiast tego zaczyna od nowa od tabel tej gałęzi.
• Recenzent przełącza się na gałąź, ma ją uruchomioną we własnym projekcie i uruchamia na niej testy package'a przez Run Tests. Testy znajdują się w package'u, więc podróżują razem z kodem, który testują.
• AGENTS.md i docs/archestack/ są commitowane, więc agent kodujący każdego programisty przestrzega tych samych reguł.

Tabele w zespole

Plik tabeli opisuje strukturę, jaką tabela powinna mieć, a nie kroki, które do niej prowadzą. Po pobraniu zmian z git albo scaleniu gałęzi projekt każdego programisty planuje własną migrację z plików tabel przez Add Migration, a przegląd pokazuje dokładnie to, co ta baza danych wykona, łącznie z utratą danych i typowanymi skryptami, które przestałyby się kompilować. Każde narzędzie zapisuje plik tabeli w jednej kanonicznej postaci, więc zmiany dwóch osób w tej samej tabeli są w konflikcie tylko tam, gdzie zmieniają to samo.

O czym decyduje każde środowisko

To, kto może widzieć stronę, co jest publiczne, uprawnienia Data API i klienci API, użytkownicy i role, konta pocztowe, połączenia z innymi systemami i historia uruchomień nie są zapisane w plikach. Ustawiają je administratorzy każdego środowiska, więc scalenie nigdy nie może uczynić niczego publicznym ani nikomu dać dostępu.

Środowiska testowe, akceptacyjne i produkcyjne są wdrażane z repozytorium przez pipeline, jak opisuje strona Strategia wdrożeń.

Ustawienia

Przeniesienie istniejącego package'a

Package, który do tej pory istnieje tylko w hostowanej przestrzeni roboczej, trafia do repozytorium jeden raz: uruchom Connect to Workspace z Command Palette, zaloguj się, użyj Pull Package to Folder na tym package'u i ponownie wybierz projekt na pasku stanu. Od tej chwili źródłem jest folder, a projekt go uruchamia. Tabele package'a przychodzą razem z nim, a tabele, na które wskazuje kluczem obcym, są oznaczone jako tylko referencyjne, dzięki czemu projekt może utworzyć każdą tabelę, której package potrzebuje. W projekcie, który ma już bazę danych, te tabele czekają na migrację jak każda inna zmiana tabel.

Pułapki

• Projekt zaczyna z pustymi tabelami. Folder przenosi strukturę, nie wiersze. Wczytywanie danych podstawowych z repozytorium nie jest jeszcze dostępne.
• Tabele nigdy nie zmieniają się przy zapisie. Bazę danych projektu zmienia tylko wdrożona migracja, poza świeżym uruchomieniem albo resetem.
• Reset wyrzuca dane projektu. Cała reszta jest w folderze i wraca; wiersze, które wprowadziłeś, nie wracają.
• Zmiany z buildera zostają w projekcie, dopóki nie pobierzesz ich do folderu, a reset je traci.

Co dalej

Strona Przestrzenie robocze i hosting wyjaśnia, gdzie działa Twoja aplikacja, gdy opuści Twoją maszynę. Strona Reference opisuje dokładniej packages, Script Modules i wdrożenia bazy danych.