SOTER Modeler Manual — Logos DSL Modeling Guide (MVP Release)

Ten podręcznik jest przeznaczony dla architektów korporacyjnych, analityków biznesowych i inżynierów definiujących modele w języku Logos DSL v1 oraz weryfikujących spójność procesów za pomocą narzędzi walidacyjnych SOTER MVP.

1. Założenia Modelowania SVO (Subject-Verb-Object)

SOTER nie korzysta z tradycyjnych rysunków przepływu procesów. Zamiast tego opisuje organizację jako deklaratywną ontologię SVO, składającą się z trzech głównych typów elementów:

1. Subject (Podmiot - wykonawca):
2. Reprezentuje aktywnych aktorów (ludzi, działy, systemy IT).
3. Atrybut class: "Subject" i type: "Actor".
4. Action (Czasownik - czynność):
5. Reprezentuje transformacje zasobów (procesy, zadania).
6. Atrybut class: "Action". Wymaga określenia pól: name, performer (kto wykonuje) oraz opcjonalnie in/out (jakie obiekty przetwarza) oraz constraints (warunki poprawności).
7. Object (Dopełnienie - zasób):
8. Reprezentuje pasywne zasoby (dane, dokumenty, fizyczne przedmioty).
9. Atrybut class: "Object".

2. Składnia Języka Logos DSL v1

2.1. Definiowanie Elementów

Każdy element deklarowany jest za pomocą słowa kluczowego element, unikalnego identyfikatora oraz wciętych atrybutów:

soter v1

element Manager:
    class: "Subject"
    type: "Actor"
    name: "Project Manager"

element BudgetReport:
    class: "Object"
    type: "DataArtifact"
    name: "Monthly Budget Report"

element ApproveBudget:
    class: "Action"
    type: "Action"
    name: "Approve Budget"
    performer: Manager
    in: BudgetReport
    out: BudgetReport
    constraints: "approved_amount <= total_budget"

2.2. Relacje i Połączenia

Aby połączyć elementy w logiczną strukturę procesu, używamy słowa kluczowego relationship:

relationship approve_flow:
    source: Manager
    target: ApproveBudget

2.3. Dzielenie i Kompozycja Modeli

SOTER pozwala na modularyzację modeli poprzez dołączanie innych plików za pomocą słowa kluczowego include:

include "models/common_definitions.model"

Możesz kontrolować, które elementy są widoczne podczas kompilacji i analizy za pomocą instrukcji show:

show ApproveBudget

3. Reguły Strict Mode (Ścisła Walidacja)

Linter SOTER MVP weryfikuje spójność ontologiczną modeli według reguł Strict Mode:

1. Pure Waste (Czyste Marnotrawstwo):
2. Każda czynność (Action) musi wchodzić w interakcję z jakimś obiektem (musi mieć zdefiniowane wejście in lub wyjście out). Jeśli czynność nie transformuje żadnego zasobu, zgłaszane jest ostrzeżenie Pure Waste.
3. Silent Edits (Ciche Modyfikacje):
4. Każda zmiana stanu zasobu musi być zainicjowana przez jawną akcję. Jeśli zasób zmienia stan poza zdefiniowanym przepływem akcji, linter zgłosi Silent Edits.

4. Narzędzia CLI do Walidacji

Sprawdzenie poprawności modelu Logos odbywa się lokalnie za pomocą komendy CLI:

soter validate models/my_model.model

Silnik wczyta plik, przeanalizuje zależności include, zweryfikuje składnię oraz reguły Strict Mode.

5. Rozwiązywanie Problemów (Troubleshooting)

Ostrzeżenie: Pure Waste

• Przyczyna: Zdefiniowana akcja (Action) nie posiada przypisanych obiektów wejściowych (in) ani wyjściowych (out).
• Rozwiązanie: Dodaj powiązanie z odpowiednim obiektem (zasobem), który ta akcja tworzy, modyfikuje lub zużywa.

Ostrzeżenie: Silent Edits

• Przyczyna: Wykryto zmianę stanu zasobu, która nie ma przypisanego jednoznacznego wykonawcy (akcji).
• Rozwiązanie: Zdefiniuj akcję z odpowiednimi atrybutami from/to wskazującymi na przejście stanu obiektu.

Powiązane pliki

• SOTER_MVP.md — Kompletny przewodnik po CLI i plikowym Ledgerze MVP.
• Quickstart.md — Szybki start z lokalnym SOTER CLI.
• ManualsIndex.md — Indeks dokumentacji.