Reference

Każde narzędzie, w jednym miejscu

Ta strona to praktyczna referencja dla każdego narzędzia w pasku bocznym twojego środowiska Archestack. Każda sekcja opisuje, co narzędzie robi, kiedy po nie sięgać, kroki dla najbardziej typowych przepływów pracy oraz pułapki, w które wpadają nowi użytkownicy. Ostatnia sekcja (Script-callable APIs) dokumentuje dokładną powierzchnię, którą skrypty mogą wywoływać.

Schema Designer

Wizualny edytor schemy bazy danych, tabele, kolumny, typy, relacje, indeksy, który auto-zapisuje do dokumentu JSON. Schema jest źródłem prawdy dla twojej aplikacji; żadne inne narzędzie nie widzi kolumny, dopóki nie dodasz jej tutaj i nie wdrożysz.

Typowy przepływ pracy: na pasku narzędzi kliknij Add Table (ikona-przycisk). Otwiera się okno dialogowe zatytułowane "Create New Table"; wpisz nazwę (tekst pomocniczy przypomina "Lowercase with underscores recommended"), kliknij Create. Tabela pojawi się na kanwie z auto-wygenerowanym kluczem głównym id SERIAL. Wybierz tabelę, prawy panel otworzy się na karcie Columns. Dodawaj kolumny z ramki "Add column" z przerywanym obramowaniem na dole (pole nazwy, rozwijana lista Type, kliknij Add Column). Kliknij każdą kolumnę, aby ją rozwinąć i dostosować przełączniki (PK, NULL, UQ), Length i Default value.

Typy kolumn dostępne w rozwijanej liście Type: SERIAL, BIGSERIAL, INTEGER, BIGINT, SMALLINT, DECIMAL, NUMERIC, REAL, DOUBLE PRECISION, VARCHAR, CHAR, TEXT, BOOLEAN, DATE, TIME, TIMESTAMP, TIMESTAMPTZ, UUID, JSON, JSONB, BYTEA, INET, CIDR, MACADDR, MONEY, INTERVAL plus typy geometryczne i tablicowe. Długość ma znaczenie tylko dla VARCHAR i CHAR.

Klucze obce żyją w karcie Relations prawego panelu (nie "Relationships"). Przewiń do "Add relationship": wybierz kolumnę FK na aktualnej tabeli, typ relacji (One-to-One / One-to-Many / Many-to-Many), tabelę references, kolumnę references i kliknij Add Relationship. Każda relacja ma rozwijane listy On Delete i On Update (CASCADE / SET NULL / SET DEFAULT / RESTRICT / NO ACTION).

Auto-save: wskaźnik w lewym dolnym rogu przeskakuje między "Auto saving..." a "Saved". Na pasku narzędzi jest też przycisk Save (włączony tylko, gdy są oczekujące zmiany) dla jawnych zapisów.

Inne przyciski paska narzędzi: Add Group (wizualne kontenery dla powiązanych tabel, panel właściwości zatytułowany "Group"), Add Text (adnotacje w formie wolnej, panel właściwości zatytułowany "Text Annotation"), kontrolki zoom, filtr package, wyszukiwanie tabel.

Pułapki: zmiana nazwy kolumny produkuje destrukcyjny plan (drop + add), edytuj SQL na karcie Generated SQL wdrożenia, używając RENAME COLUMN, jeśli chcesz zachować dane. Dodanie kolumny NOT NULL do niepustej tabeli bez wartości default zawodzi, ustaw ją jako nullable, uzupełnij dane, a potem zmień. Przycisk Deploy z paska narzędzi przenosi cię na stronę konfiguracji wdrożenia, nie bezpośrednio do wdrożenia.

Database Deployments

Wymienia każde wdrożenie z jego statusem (Draft / Executing / Succeeded / Failed) i uruchamia nowe. Route: /database-deployments/overview.

Przyciski w prawym górnym rogu: Refresh (przeładuj listę), New Deployment (utwórz nowy draft).

Z Schema Designer: zielony przycisk Deploy z ikoną rakiety na pasku narzędzi Schema Designer przenosi cię na /database-deployments/configure/new, świeżą stronę konfiguracji wdrożenia.

Strona konfiguracji wdrożenia: dwie karty.

  • Configuration - edytory skryptów pre/post-deployment (PostgreSQL) z przyciskiem Test Run dla każdego. Pre-script uruchamia się przed zmianami schemy; post-script po. Przydatne do uzupełniania danych, odbudowy indeksów lub czyszczenia obszaru staging. Plus przełącznik Force Deploy (Allow Data Loss) dla operacji destrukcyjnych.
  • Generated SQL - pokazuje migrację wygenerowaną przez platformę. SQL jest edytowalny. Przycisk Regenerate (ikona refresh) ponownie uruchamia diff, jeśli wprowadziłeś zmiany w schemie od otwarcia tej strony.

Przyciski u góry: Back, Save (zapisuje konfigurację jako Draft), Deploy (uruchamia wdrożenie natychmiast). Deploy to to, co klikasz na końcu.

Pułapki: wdrożenia nie są automatycznie opakowane w transakcję, niepowodzenie w połowie pozostawia bazę danych w stanie częściowym. Dla ryzykownych migracji opakuj swoje instrukcje w BEGIN; ... COMMIT; w pre-script. Przełącznik Force Deploy pomija sprawdzenia bezpieczeństwa; używaj go świadomie.

Business Entities

Wyselekcjonowane widoki zbudowane na master table plus joinach z powiązanych tabel. Strony wiążą się z Business Entities, nigdy z surowymi tabelami. Zobacz Concepts -> Business Entities, by dowiedzieć się dlaczego.

Typowy przepływ pracy: kliknij Create. Otwiera się pełnostronicowy edytor z kartami Visual, JSON, Events. Ustaw Entity Name, Master Table (Autocomplete) i Label Column (kolumna, której wartość reprezentuje rekord w pickerach). Zapisz, BE auto-generuje listę natywnych kolumn z master table.

Dodawanie joinów: przewiń do karty Join Configurator i kliknij Add Join. Każdy join otwiera się jako Accordion z: Join Type (INNER / LEFT / RIGHT), From Table, To Table (Autocomplete pogrupowane według Database Tables / Third Party), From Column, To Column, opcjonalne rozwijane listy Type Cast oraz picker kolumn dla tego, które kolumny docelowe ujawnić.

Agregacje: na joinie przełącz Aggregate Mode. Dla każdej wybranej kolumny wybierasz wtedy Aggregate Function: COUNT / SUM / AVG / MIN / MAX / COUNT DISTINCT. "Liczba otwartych kontaktów na tej Company" to kanoniczny przykład.

Run Preview: edytor ma przycisk Run Preview (z ikoną play), który wykonuje pełną konfigurację join i pokazuje prawdziwe wiersze w siatce danych. Jeśli kolumna join wraca pusta, kolumna nie została zaznaczona w pickerze kolumn joina (lub relacja jest źle skonfigurowana).

Wiele BE per master table: nic nie powstrzymuje cię przed posiadaniem customer (sales view) i customer (support view) na tym samym masterze. Różne strony, różne kolumny dla różnych odbiorców, ten sam podstawowy wiersz.

Pułapki: kolumny dołączone i agregowane są tylko do odczytu. Aby edytować dołączoną etykietę, przejdź do rekordu źródłowego. Kolumny agregowane są przeliczane na każdym zapytaniu, w porządku dla setek wierszy, wolne dla milionów.

Page Editor

Konfiguruje interfejs uruchomieniowy, wiążąc Page z Business Entity. Platforma auto-generuje sekcje na podstawie kolumn BE; stamtąd dostrajasz układ. Nie ma osobnego "picker szablonów", każda strona zaczyna od tej samej wygenerowanej bazy, którą dostosowujesz.

Typowy przepływ pracy: kliknij Create. Uzupełnij Page Name, Page Route (np. /companies), wybierz Business Entity (Autocomplete). Strona otwiera się w edytorze z kartami Visual, Overview, Create, Entities, Events, JSON. Dostosuj auto-wygenerowany układ, a następnie przełącz Switch Published w nagłówku u góry na ON.

Typy widgetów pól (Select Type na każdym polu): Text, Textarea, Number, Date, Select, Checkbox, Email. Użyj Select dla pól klucza obcego i ustaw autocomplete Entity pola na referencjonowane BE, aby użytkownicy wybierali po etykiecie.

Karty w formularzu szczegółów: kliknij Add Tab w karcie Visual. Wewnątrz karty możesz dodać sekcję RelatedGrid powiązaną z innym BE, filtrowaną przez PK aktualnego rekordu. Klasyczny przykład: strona Company z kartami "Contacts" i "Deals", każda filtrowana przez company_id = id aktualnej firmy.

Przyciski akcji w inspektorze nagłówka formularza szczegółów. Kliknij Add w sekcji Actions. Każda akcja ma Label, Icon (Save / Delete / Add / Refresh / Download / Bolt / None), Variant (Contained / Outlined / Text), Color (Primary / Secondary / Error / Success / Warning / Info) oraz Steps (uporządkowana lista: Save Record, Delete Record, Navigate, Business Events, Custom). Aby uruchomić Business Event z przycisku, ustaw typ kroku na Business Events i wybierz event po nazwie.

Publikacja: Switch Published w nagłówku u góry to jedyna kontrolka publikacji. ON = strona pojawia się pod Published Pages w pasku bocznym, a końcowi użytkownicy nawigujący do jej route ją widzą. OFF = draft (tylko ty w edytorze widzisz swoje zmiany).

Pułapki: auto-wygenerowane kolumny na świeżym Page odzwierciedlają BE, jeśli BE się zmieni (dodajesz join), Page nie złapie automatycznie nowych kolumn. Przeładuj stronę w edytorze lub dodaj kolumnę ręcznie do sekcji. Aktualnie nie ma typu kroku akcji "Generate PDF", aby podpiąć PDF pod przycisk strony, wystaw PDF przez Script Module, który wywołuje endpoint REST, i użyj kroku Custom (lub wywołaj endpoint bezpośrednio z Frontend Template).

Business Events

Reguły, które odpalają się przy zmianach danych (lub na harmonogramie, lub ręcznie) i uruchamiają akcje, gdy warunki są spełnione. Mechanizm "gdy zdarza się X, zrób Y" platformy. Zobacz Concepts -> Business Events dla modelu.

Typowy przepływ pracy: kliknij Create. Ustaw Rule Name, przełącz Enabled. Wybierz Business Entity. Zaznacz jeden lub więcej Triggers: BeforeCreate / BeforeUpdate / AfterCreate / AfterUpdate / BeforeDelete / OnSchedule / Manual / InitialValue. Zbuduj drzewo warunków (grupy AND/OR). Dodaj jedną lub więcej akcji w FlowCanvas. Zapisz.

Typy akcji (RuleActionKind):

  • Execute Script - uruchom skrypt C#. Najbardziej elastyczna akcja; sięgaj po nią, gdy chcesz ustawić pole, zrobić obliczenie, wywołać API, cokolwiek niestandardowego. Skrypt dostaje Entity (mutuj go na triggerach Before*, by zmienić zapis w locie), OldEntity, Log, Db, Modules.
  • Validate - skrypt zwracający bool. true oznacza, że walidacja nie powiodła się, a zapis jest zablokowany skonfigurowanym komunikatem błędu. Opcjonalnie podświetla konkretne kolumny przez errorColumns.
  • Block Operation - twarde zatrzymanie operacji ze skonfigurowanym komunikatem. Bez skryptu.
  • Create Entity - wstawia rekord do innego BE. Wartości pól wspierają wyrażenia szablonów takie jak {{ Entity.column_name }} i {{ now() }}.
  • Update Entity - aktualizuje rekordy w innym BE pasujące do filtra warunków. Te same wyrażenia szablonów.
  • Delete Entity - usuwa rekordy pasujące do warunku. Odmawia odpalenia bez warunku (bezpieczeństwo).
  • Send Email / Send Webhook / Publish Event - zdefiniowane w schemie jako przyszłe rozszerzenia; aktualnie logowane i pomijane.

Wzorzec "ustaw pole": nie ma osobnej akcji Set Field. Sposobem na ustawienie pola jest Execute Script na triggerze Before*, który mutuje Entity. Przykład: Entity.title = ((string)Entity.title)?.Trim();. Platforma utrwala zmodyfikowane Entity jako część zapisu w locie, bez dodatkowego zapytania, bez ryzyka rekurencji.

Run Simulation: karta Simulate edytora triggera ma picker rekordów i przycisk Run Simulation. Platforma uruchamia twoje warunki i akcje przeciwko wybranemu rekordowi bez utrwalania zmian, operacje zapisu wykonują się w transakcji, która jest cofana. Panel wyjścia pokazuje, które warunki pasowały i co zrobiłaby każda akcja. Użyj tego, aby wyłapać błędną konfigurację, zanim trafi w żywe dane.

Wyrażenia szablonów w konfiguracji akcji używają nawiasów {{ ... }}. Rzeczywiste tokeny: {{ Entity.column }}, {{ OldEntity.column }}, {{ now() }} / {{ getdate() }}, {{ today() }}, {{ guid() }} / {{ newid() }}, {{ year() }}, {{ month() }}, {{ day() }}, {{ timestamp() }}, agregaty jak {{ SUM(column) }} w kontekstach join oraz post-substytucyjna arytmetyka jak {{ Entity.quantity * Entity.price }}. Nie ma tokenu {{ user.email }}.

Operatory warunków: Equals, NotEquals, GreaterThan, LessThan, GreaterThanOrEqual, LessThanOrEqual, Like (= ILIKE), Contains (= ILIKE %value%), IsNull, IsNotNull, In (= ANY(...)).

Pułapki: trigger, który mutuje ten sam rekord, który obserwuje, odpali się ponownie, jeśli użyjesz Update Entity; zamiast tego użyj Before Update + Execute Script + Entity.field = .... Dwa triggery na tym samym evencie odpalają się w kolejności priorytetów. Wyłączone eventy nadal pojawiają się na liście, przełącznik Enabled jest oddzielny od konfiguracji triggera.

Script Modules

Wielokrotnego użytku skrypty C# kompilowane w czasie wykonania przez Roslyn. Przyjmują parametry, odpytują bazę danych przez helper Db, zwracają wartość. Wywoływalne z Business Events, Scheduled Events i bezpośrednio z frontendu.

Typowy przepływ pracy: kliknij Create. Edytor otwiera się z kartami Edit, Parameters, Test, JSON. Nazwij moduł (PascalCase, np. RecalcOpenRevenue). W karcie Parameters kliknij Add dla każdego parametru (Name, Type, Required, Default Value). Opcje typu: string, int, decimal, double, bool, DateTime. Wróć do karty Edit, napisz C#. IntelliSense jest włączony.

Panel Test: karta Test pokazuje wejścia parametrów po lewej i przycisk Run (ikona PlayArrow). Kliknij Run; prawa strona pokazuje wskaźnik sukcesu lub błędu, log wyjścia i wartość zwracaną (sformatowaną w JSON).

Helper Db, zobacz pełną referencję w Script-callable APIs poniżej.

Wywoływanie z Business Event: dodaj akcję Execute Script, której ciało wywołuje moduł: 

await Modules.CallAsync("RecalcCompanyOpenDealValue", new Dictionary<string, object?> {
    ["company_id"] = Entity.company_id
});

Wywoływanie ze Scheduled Event: utwórz event z triggerem On Schedule, ustaw cron, dodaj akcję Execute Script z tym samym ciałem Modules.CallAsync.

Logowanie: każde wywołanie pisze wpis do Event Logs z czasem wykonania, parametrami i wynikiem (lub błędem).

Pułapki: zawsze await wywołania Db, zapomnienie kompiluje się, ale zwraca Task. Zwroty są przekazywane jako obiekty (nie serializowane do JSON przez framework); do konsumpcji frontendowej zwracaj anonimowe obiekty z polami prymitywnymi. Suggestion-on-commit-character jest celowo wyłączone w edytorze; użyj Tab, aby zaakceptować.

Frontend Templates

Wielokrotnego użytku fragmenty UI pisane w TSX, które page editor może wrzucić do strony. Przydatne, gdy skonfigurowane szablony nie wystarczają, niestandardowe wykresy, nietypowe układy, integracje z widgetami zewnętrznymi.

Typowy przepływ pracy: kliknij Create, nazwij szablon, napisz komponent TSX w edytorze. Komponent otrzymuje propsy: record (aktualny wiersz, gdy osadzony w formularzu szczegółów), refresh (ponowne pobranie danych) i kilka helperów. Zapisz. Odwołaj się do szablonu z pola Page Editor.

Pakowalne: templates przepływają przez system Package jak każdy inny obiekt konfiguracji, są kaskadowane, gdy strona, która ich używa, jest dodawana do package.

Pułapki: TSX jest w sandboxie, nie możesz importować dowolnych paczek npm. Trzymaj się React + dostarczonych helperów.

PDF Templates

HTML + szablon Scriban + mały skrypt danych C#, który renderuje się do PDF (headless Chromium). Każdy szablon jest wywoływalny po nazwie ze skryptu przez REST lub bezpośrednio z przycisku na Page (z małym adapterem, zobacz poniżej).

Typowy przepływ pracy: kliknij + Create. Edytor otwiera się z polami tekstowymi Name i Description u góry, pięcioma kartami po lewej stronie (HTML Template, Data Script, Settings, Params, JSON) oraz zawsze włączonym panelem PDF Preview po prawej. Karty Data Script i HTML Template otwierają edytor Monaco w lewej połowie; podgląd jest ponownie renderowany przy zapisie (zielony przycisk Update w prawym górnym rogu).

Zadeklaruj parametry w karcie Params przez przycisk + Add (Name, Type, Required, Default Value). Etykieta karty aktualizuje się do Params (n) z liczbą. Format strony / orientacja / marginesy / skala / nagłówek / stopka żyją w karcie Settings.

Kształt skryptu danych (zobacz tutorial PDF Invoices dla prawdziwego): 

var deal = await Db.GetAsync("deal", deal_id);
var lines = await Db.From("deal_line")
    .Where("deal_id", "=", deal_id).ToListAsync();

return new {
    InvoiceNumber = $"INV-{deal.id:D6}",
    Lines = lines.Select(l => new { l.description, l.quantity })
};

Kształt szablonu HTML (Scriban, podobny do Liquid/Handlebars): 

<h1>{{ InvoiceNumber }}</h1>
<table>
  {{ for line in Lines }}
  <tr><td>{{ line.description }}</td><td>{{ line.quantity }}</td></tr>
  {{ end }}
</table>

Panel podglądu: zawsze widoczny po prawej stronie edytora. Ponownie renderuje się przy zapisie (zielony przycisk Update). Zawiera kolumnę miniatur dla wielostronicowych PDF i wbudowany pasek narzędzi viewera (zoom, obrót, download, print). Ikony-przyciski w prawym górnym rogu edytora przełączają widoczność panelu podglądu i edycję pełnoekranową.

Wywoływanie z zewnątrz edytora:

  • POST /api/v1/pdf-templates/{id}/preview - renderuje po ID, zwraca application/pdf. Używane przez panel podglądu edytora.
  • POST /api/v1/pdf-templates/generate/{name} - renderuje po nazwie, zwraca application/pdf.
  • POST /api/v1/pdf-templates/generate/{name}/base64 - to samo, ale zwraca { "data": "<base64>" }.

Przekaż wartości parametrów w ciele JSON. Auth to standardowy Bearer token.

Ograniczenie w trial: zarówno endpoint generate, jak i endpoint {id}/preview (używany przez panel podglądu edytora) zwracają 403 w trybie trial, renderowanie PDF jest całkowicie zablokowane. Nadal możesz autorować szablon (data script, HTML, settings, parameters) i zapisać go; po prostu nie zobaczysz wyrenderowanego PDF, dopóki nie będziesz na płatnym środowisku.

Uwaga o renderowaniu wywoływanym ze skryptu: kontekst skryptowy C# nie udostępnia globalnej zmiennej Pdf. Aby wyrenderować PDF ze Script Module dzisiaj, wywołaj endpoint REST generate przez HttpClient. (Autocomplete edytora skryptów reklamuje Pdf.RenderAsync dla zgodności do przodu; runtime binding nie jest jeszcze podpięty.)

Pułapki: Scriban domyślnie escapuje HTML. Łamania stron są sterowane CSS, page-break-before: always na sekcji. Czcionki dostępne na serwerze renderującym są ograniczone do systemowych plus rodzin Noto i Liberation, osadź własną przez base64 @font-face, jeśli potrzebujesz czcionki brandowej.

Scheduled Events

Ten sam system Event Trigger co Business Events, z zaznaczonym triggerem On Schedule. Używaj go do nocnych przeliczeń, tygodniowych digestów, okresowych czyszczeń, miesięcznych raportów.

Typowy przepływ pracy: utwórz Business Event z triggerem On Schedule (zamiast lub oprócz triggerów zmiany danych). Skonfiguruj wyrażenie cron. Dodaj akcję Execute Script, której ciało wywołuje Script Module przez Modules.CallAsync(...).

Wyrażenia cron: w stylu Quartz, 6 lub 7 pól, zobacz Concepts -> Scheduled Events dla typowych wzorców. Czasy są w czasie serwera (UTC na stacku produkcyjnym).

Pułapki: długo trwające zadanie, które przekracza swój interwał cron, nie podwaja się, Quartz nie odpali drugiej instancji tego samego zadania równolegle, drugi tick jest pomijany. Niepowodzone uruchomienia nie auto-ponawiają się; wbuduj ponowienia w skrypt.

Packages

Eksportowalne wiązki obiektów konfiguracji (BE, strony, eventy, skrypty, templates, schema) z kaskadowymi zależnościami. Dodanie Page do package automatycznie ciąga wszystko, do czego ta strona się odwołuje.

Typowy przepływ pracy (eksport): kliknij Create, nazwij i ustaw wersję package'a. Dodaj obiekty najwyższego poziomu, na których ci zależy, zwykle garść stron. Otwórz panel linked-items, aby zobaczyć listę kaskadową (co package faktycznie będzie zawierał). Odznacz cokolwiek chcesz pominąć. Zdecyduj, czy zawrzeć dane (przełącznik przy eksporcie). Kliknij Export, dostajesz ZIP.

Typowy przepływ pracy (import): na środowisku docelowym otwórz Packages, kliknij Import, wgraj ZIP. Platforma pokazuje, co zostanie dodane lub zaktualizowane. Delty schemy nie są auto-stosowane, jeśli package odwołuje się do kolumny, która nie istnieje na docelu, import zawodzi.

Pułapki: identyfikatory są po nazwie, nie po ID numerycznym. BE o nazwie "customer" na źródle wiąże się z BE o nazwie "customer" na docelu, zmień nazwę po jednej ze stron, a link się zrywa.

Third-Party Data Connections

Połączenia do zewnętrznych baz danych (Postgres, SQL Server, MySQL, inne), które importują tabele na harmonogramie. Zaimportowane tabele zachowują się jak natywne tabele, pokazują się w Schema Designer i mogą być referencjonowane przez Business Entities, Pages i Scripts.

Typowy przepływ pracy: utwórz połączenie (connection string, test, zapis). Wymień dostępne zdalne tabele; wybierz, które zaimportować. Dla każdej zaimportowanej tabeli ustaw tryb synchronizacji (Full / Delta) i wyzwalacz synchronizacji (cron / manual / stały interwał).

Mirrored, nie federated: zaimportowane dane żyją w twojej własnej omnicore-db. Odczyty są szybkie (lokalny Postgres). Trade-off: nieaktualność między synchronizacjami.

Kolumny zarządzane przez aplikację: oznacz niektóre kolumny jako "managed by Archestack", nie zostaną nadpisane przez przyszłe synchronizacje. Przydatne, gdy chcesz anotować dane vendora własnymi flagami statusu.

Pułapki: pierwsza synchronizacja dużej tabeli może chwilę zająć. Synchronizacje delta wymagają kolumny, której konektor może użyć jako znacznika, zwykle timestamp modified_at.

AI Builder

Prowadzony kreator, w którym opisujesz funkcję w języku naturalnym, a kreator generuje plan budowy, dodania do schemy, zmiany BE, strony, eventy, który przeglądasz linijka po linijce i stosujesz. Generowanie planu jest robione przez zewnętrzny LLM twojego wyboru (Claude, ChatGPT, Gemini), kreator komponuje samowystarczalny prompt, który wklejasz, i akceptuje odpowiedź JSON. Nie ma już asystenta czatu w aplikacji.

Typowy przepływ pracy: opisz funkcję w 1-3 zdaniach ("add support for service appointments, each one has a date, a customer, a vehicle, and a status"). Kliknij Generate prompt, wklej go do swojego zewnętrznego LLM, wklej odpowiedź JSON z powrotem do kroku Import, kliknij Review. Odznacz cokolwiek, czego nie chcesz. Kliknij Apply.

Działa dobrze dla: funkcji w stylu CRUD, prostych automatyzacji, prostych rozszerzeń istniejących entities.

Mniej dobrze dla: nieoczywistych reguł biznesowych, złożonych wieloetapowych workflowów. Plan to punkt startowy, recenzuj go jak PR juniora.

Pułapki: apply jest nieodwracalne. Dla ryzykownych funkcji najpierw zrób backup (lub zastosuj na środowisku trial, oceń, a następnie odbuduj na produkcji z wynikowego Package).

Object Browser

Surowy widok każdej natywnej i zaimportowanej tabeli, dodawaj, edytuj, usuwaj wiersze bezpośrednio. Zawiera CSV import do hurtowego ładowania.

Kiedy po niego sięgać:

  • Hurtowe ładowanie danych referencyjnych zanim istnieją strony (kraje, waluty, enumeracje statusów).
  • Debugowanie, oglądanie, co faktycznie jest w tabeli, gdy strona zachowuje się dziwnie.
  • Szybkie edycje admin danych, które nie są jeszcze udostępnione przez Page.
  • CSV import: wybierz tabelę, wgraj plik, zmapuj kolumny do pól, podgląd, commit.

Pułapki: Object Browser odpala Business Events (przechodzi przez tę samą ścieżkę zapisu EntityService co frontend). Wyjątek to bezpośredni SQL przez Database Deployments, to omija wszystko.

Dependency Graph

Mapa tylko do odczytu pokazująca, jak obiekty konfiguracji w twoim środowisku odwołują się do siebie nawzajem. Osiem typów zasobów pojawia się jako węzły, pokolorowane według typu: Business Entities, Pages, Event Triggers, Script Modules, PDF Templates, Frontend Templates, Scheduled Events i Packages. Krawędź między dwoma węzłami oznacza, że jeden zasób zależy od drugiego. Sięgnij po nią, aby odpowiedzieć na pytania "co by się zepsuło, gdybym to usunął?" oraz "czy jest tu coś nieużywanego?".

Co oznacza krawędź: Page powiązana z Business Entity, Event Trigger zarejestrowany na Business Entity, krok akcji Page, który odpala Event Trigger, skrypt, który wywołuje inny Script Module przez Modules.CallAsync("Name"), skrypt, który renderuje PDF Template, Scheduled Event, który odpala Event Trigger, lub Package, który zawiera zasób. To widok design-time, odzwierciedla to, co twoja konfiguracja łączy ze sobą, a nie ruch w czasie wykonywania na żywo.

Dwa rodzaje problemów są wizualnie uwypuklone:

  • Loose ends (sieroty) - węzły, do których nic się nie odwołuje i które same do niczego się nie odwołują. Są zbierane w obramowanym na czerwono pasie "Loose ends" na dole płótna. Script Module, którego nikt nie wywołuje; Page powiązana z niczym.
  • Dangling references - rysowane jako czerwone przerywane krawędzie. Odwołanie istnieje w konfiguracji, ale jego cel nie może zostać znaleziony, na przykład krok akcji Page, który nadal wskazuje na usunięty Event Trigger, lub skrypt, który wywołuje Script Module po nazwie, która już nie istnieje.

Typowy przepływ pracy: otwórz Dependency Graph z sekcji Tools w sidebarze. Lewy panel ma wyszukiwanie po nazwie, wybór Layout (Left to right, Top to bottom, By type, Force-directed), przełączniki Group by package, Show loose ends i Show edges oraz listę kontrolną według typu. Kliknij węzeł, aby wejść w tryb skupienia: ten węzeł i jego bezpośredni sąsiedzi pozostają jasne, podczas gdy reszta grafu przygasa, dzięki czemu możesz dokładnie prześledzić, czego dotyka dany zasób. Kliknij tło płótna, aby wyczyścić skupienie. Każdy węzeł ma mały przycisk otwierania w nowej karcie, który przeskakuje wprost do edytora tego zasobu. Wiersz statystyk u góry podaje liczbę węzłów, krawędzi, sierot i dangling references.

Group by package: owija członków każdego package w opisaną przerywaną ramkę, abyś mógł zobaczyć package jako całość i wypatrzeć zasoby, które wciągnął kaskadowo.

Pułapki: graf jest budowany na żądanie z bieżącego stanu, użyj przycisku odświeżania po zmianie zasobów gdzie indziej. Krawędzie pochodzące ze skryptów są znajdowane przez skanowanie ciał skryptów w poszukiwaniu dosłownej formy wywołania Modules.CallAsync("Name"), moduł wywołany przez obliczoną nazwę nie pokaże krawędzi. Dangling reference zawsze warto naprawić; sierota często nie, zupełnie nowy Script Module liczy się jako sierota, dopóki coś go nie wywoła.

Event Logs

Audytowy ślad wszystkiego, co platforma uruchomiła, Business Events, Script Modules, Scheduled Events, synchronizacje third-party.

Typowy przepływ pracy: otwórz Event Logs, ustaw Status na Failed, kliknij we wpis. Panel szczegółów pokazuje payload (stan rekordu w czasie, przekazane parametry), wyjątek ze stack trace oraz timing.

Powiadomienia w czasie rzeczywistym: ikona dzwonka na górnym pasku aplikacji administracyjnej ujawnia nieprzeczytane niepowodzenia przez SignalR.

Pułapki: log może urosnąć duży. Stare wpisy są trzymane na zawsze domyślnie; jeśli dysk jest problemem, ustaw Scheduled Event, który czyści wpisy starsze niż N dni.

User Management

Tworzenie, zapraszanie i zarządzanie użytkownikami; przypisywanie ról realm. Opakowuje REST API administracyjne Keycloaka.

Role:

  • admin - wszystko; może zarządzać wszystkimi Business Units, użytkownikami, rolami, ustawieniami systemowymi.
  • owner - zarządza własnymi Business Units, może edytować strony administracyjne i runtime.
  • editor - może przeglądać i edytować strony runtime, ale nie zmieniać konfiguracji schema/BE/event.
  • user - tylko do odczytu na stronach runtime.

Pułapki: degradacja użytkownika z admin w trakcie sesji nie wyrzuca go, zmiana stosuje się przy następnym odświeżeniu tokenu (zwykle w ciągu minuty).

Business Units

Grupy oparte na Keycloak, które ograniczają widoczność na pojedynczych zasobach. Zobacz Concepts -> Business Units dla modelu.

Typowy przepływ pracy: utwórz BU. Zaproś członków emailem i wybierz rolę. Przypisz zasoby, idąc do każdego BE / Page / Trigger lub przez panel linked-items BU.

Kaskadowe przypisania: gdy przypisujesz Page do BU, przypisanie kaskaduje na BE, do którego strona się wiąże.

Pułapki: aktywne BU użytkownika ustawia się w przełączniku BU na górnym pasku i utrzymuje się w localStorage. Nowi użytkownicy domyślnie trafiają do pierwszej BU; jeśli strona listy jest podejrzanie pusta, sprawdź, które BU jest aktywne.

Database Backups

Nocny pg_dump wszystkich trzech baz danych. Ręczny trigger / upload / restore z UI.

Typowy przepływ pracy: Trigger now -> Download -> Upload -> Restore. Harmonogram domyślnie nocny o 03:00 UTC.

Ograniczenie w trial: Backups są wyłączone w środowisku trial.

Branding

Zmień wyświetlaną nazwę aplikacji, logo (jasne + ciemne) i podstawowy schemat kolorów, stosowany w runtime, bez rebuildu.

Typowy przepływ pracy: ustaw nazwę aplikacji, wgraj logo jasne i logo ciemne (PNG/JPG/SVG, ≤ 10 MB), wybierz podstawowy kolor brandowy. Zapisz. Odśwież przeglądarkę.

Pułapki: favicon nie jest nadpisywany przez Branding, jest wbudowany w SPA.

Translations

Edytor klucz/wartość dla tekstów UI aplikacji. Dodawanie nowych locale, nadpisywanie domyślnych etykiet per klient.

Typowy przepływ pracy: wybierz locale, wyszukaj klucz, wpisz nową wartość, zapisz. Odśwież aplikację administracyjną.

Pułapki: tłumaczenia są ładowane raz na sesję; użytkownicy na nieaktualnej karcie nie zobaczą zmian, dopóki nie odświeżą. Niektóre etykiety (nagłówki kolumn z BE) pochodzą z konfiguracji BE, nie z translations.

Script-callable APIs

Dokładna powierzchnia, którą skrypty mogą wywoływać. Zweryfikowana w źródle, każda metoda poniżej faktycznie istnieje.

Globale

Każdy skrypt dostaje te zmienne najwyższego poziomu (żadne inne nazwy nie istnieją w zakresie skryptu):

  • Entity - dynamic ExpandoObject. Aktualny rekord. Dostęp do pól przez Entity.column_name. Mutowanie Entity w triggerze Before* utrwala zmiany jako część zapisu w locie.
  • OldEntity - dynamic ExpandoObject. Poprzedni rekord (triggery update + delete). Tylko do odczytu.
  • Log - ILogger. Log.LogInformation("..."), Log.LogWarning(...), Log.LogError(...). Pisze do logów serwera i wpisu Event Log.
  • Db - DbHelper. Dostęp do bazy danych (zobacz poniżej).
  • Modules - ModulesHelper. Wywołaj inne Script Modules: await Modules.CallAsync("ModuleName", new Dictionary<string, object?> { ["param"] = value }). Zwraca Task<object?>.
  • Pdf - ScriptPdfHelper. Wyrenderuj zapisany PDF Template po nazwie: await Pdf.GenerateAsync("invoice", new Dictionary<string, string> { ["id"] = Entity.id.ToString() }) zwraca byte[]; await Pdf.GenerateBase64Async(...) zwraca ten sam payload zakodowany base64. Parametry są przekazywane do skryptu danych szablonu jako zmienne lokalne typu string.

Nie ma globalnych User, Http, Email, Templates ani żadnych innych.

Db - metody pojedynczego wiersza + zapisu

Wszystkie async, wszystkie na obiekcie najwyższego poziomu Db:

  • await Db.GetAsync(string table, object id) - pobierz wiersz po kluczu głównym. Zwraca dynamic? (lub null, jeśli nie znaleziono).
  • await Db.CreateAsync(string table, object values) - wstaw. values może być anonimowym obiektem lub Dictionary<string, object?>. Odpala triggery Before/After Create. Zwraca int (nowe ID).
  • await Db.UpdateAsync(string table, object id, object values) - update po PK. Odpala triggery Before/After Update.
  • await Db.DeleteAsync(string table, object id) - delete po PK. Odpala trigger Before Delete.

Db - fluentowy budowniczy zapytań

Zacznij od Db.From(table). Połącz filtry, potem terminator:

  • .Where(string column, string op, object? value = null) - dodaj klauzulę WHERE. Operatory: =, != / <>, >, >=, <, <=, LIKE, ILIKE, IN, IS NULL, IS NOT NULL. Łańcuchuj wiele wywołań .Where(...) dla AND.
  • .OrderBy(string column, bool desc = false) - ustaw ORDER BY. Tylko jedno dozwolone per zapytanie.
  • .Limit(int limit) - maksymalna liczba wierszy. Domyślnie 1000.

Terminatory (każdy uruchamia zapytanie):

  • await ...ToListAsync() - zwraca List<dynamic>.
  • await ...FirstAsync() - zwraca dynamic? (pierwszy match lub null). Tymczasowo ustawia limit na 1.
  • await ...CountAsync() - zwraca int.

Nie ma SumAsync, MaxAsync, FirstOrDefaultAsync ani SingleAsync. Dla agregacji pobierz przez ToListAsync() i zredukuj w C#.

Przepracowany przykład

// Get a row by ID, query a list, calculate a sum, update.
var order = await Db.GetAsync("orders", 42);
if (order == null) return false;

var items = await Db.From("order_items")
    .Where("order_id", "=", order.id)
    .OrderBy("id")
    .ToListAsync();

decimal totalAmount = 0;
foreach (var item in items) {
    totalAmount += (decimal)(item.amount ?? 0);
}

await Db.UpdateAsync("orders", 42, new {
    total = totalAmount,
    updated_at = DateTime.UtcNow
});

return true;

Tryb symulacji

Podczas symulacji triggera (przycisk Run Simulation na Business Event), platforma ustawia Db.SimulationMode = true. Wszystkie operacje zapisu (CreateAsync, UpdateAsync, DeleteAsync) uruchamiają się wewnątrz transakcji PostgreSQL, która jest zawsze cofana na końcu. Operacje odczytu działają normalnie. To właśnie sprawia, że Run Simulation jest bezpieczne do użycia przeciwko prawdziwym danym.

Modules

  • await Modules.CallAsync(string moduleName, Dictionary<string, object?>? parameters = null) - wywołaj inny Script Module po nazwie. Parametry stają się typowanymi zmiennymi w skrypcie wywołanego modułu. Zwraca Task<object?> (cokolwiek moduł zwrócił).

Wyrażenia szablonów (akcje Business Event)

Konfiguracja akcji używa nawiasów {{ ... }}. Pełna lista poprawnych tokenów:

  • {{ Entity.column_name }} / {{ Entity.id }}
  • {{ OldEntity.column_name }}
  • {{ now() }} / {{ getdate() }} - datetime ISO 8601 UTC
  • {{ today() }} - string daty
  • {{ guid() }} / {{ newid() }} - świeży GUID
  • {{ year() }}, {{ month() }}, {{ day() }}, {{ timestamp() }} - sekundy Unix
  • {{ empty() }}, {{ null() }}
  • Agregaty w kontekście join: {{ SUM(column) }}, {{ AVG() }}, {{ COUNT() }}, {{ MIN() }}, {{ MAX() }}
  • Arytmetyka: {{ Entity.quantity * Entity.price }} - ewaluowana po podstawieniu przez DataTable.Compute()

Nie ma tokenu {{ user.email }} ani innego tokenu związanego z użytkownikiem.