Pola

Moduł zarządzania polami stanowi fundament architektury Metadata-Driven w systemie Ammonly. Umożliwia pełną kontrolę nad strukturą danych, zachowaniem formularzy, tabelami DataGrid oraz regułami walidacji w poszczególnych modułach bez konieczności ingerencji w kod źródłowy.

Uwaga dotycząca typów pól

Niniejszy artykuł omawia mechanizmy architektoniczne, właściwości, organizację i walidację pól. Szczegółowy opis poszczególnych typów pól (UiType) znajduje się w dedykowanej kategorii modułu.

---

Spis treści

• 1. Istota architektury metadanych
• 2. Podstawowe właściwości pola
• 3. Flagi zachowania i integralności
• 4. Integracja z DataGrid i widokami
• 5. Organizacja w sekcjach formularza
• 6. Deklaratywne reguły walidacji
• 7. Powiązania relacyjne i słownikowe
• 8. Bezpieczeństwo i ścieżka audytu

---

1. Istota architektury metadanych

W systemie Ammonly definicja pól nie jest zakorzeniona na sztywno w szablonach HTML ani w kontrolerach. Każde pole jest autonomicznym obiektem metadanych przechowywanym w rejestrze systemowym.

flowchart LR
    A[Rejestr Metadanych Pola] --> B[Silnik Walidacji API]
    A --> C[Dynamiczny Generator Formularza]
    A --> D[Tabela DataGrid i Filtry]
    A --> E[Rejestr Zmian Audit Log]

Kluczowe korzyści architektury metadanych:

1. Pojedyncze źródło prawdy (Single Source of Truth): Zmiana etykiety, wymagalności lub reguły walidacji w metadanych automatycznie odzwierciedla się w interfejsie przeglądarkowym, API REST oraz logach.
2. API-First & Zero Redundancy: Te same metadane sterują renderowaniem formularzy Twig/HTMX oraz walidacją zapytań POST, PUT i PATCH w REST API.
3. Elastyczność i skalowalność: Administratorzy mogą rekonfigurować logikę pól w dowolnym momencie bez ryzyka destabilizacji kodu bazowego platformy.

---

2. Podstawowe właściwości pola

Każde pole w systemie opisane jest zestawem kluczowych atrybutów konfiguracyjnych:

Właściwość	Klucz techniczny	Opis i zastosowanie
Etykieta	label	Nazwa wyświetlana w interfejsie użytkownika, formularzach i nagłówkach tabel.
Klucz pola	field_key	Unikalny identyfikator programistyczny w ramach danego modułu (np. start_date).
Wyrażenie SQL	column_expression	Fizyczne mapowanie na kolumnę w tabeli (np. wt.start_date).
Wartość domyślna	default_value	Domyślna wartość wstawiana przy tworzeniu nowego rekordu.
Wskazówka (Hint)	placeholder	Tekst pomocniczy wyświetlany w pustym polu jako wskazówka.

---

3. Flagi zachowania i integralności

Flagi logiczne określają dostępność pola dla użytkownika oraz wymuszają reguły integralności danych zarówno na poziomie formularza, jak i bezpośrednio w silniku bazy danych.

graph TD
    Field[Pole rekordu] --> Mandatory{Wymagane?}
    Mandatory -- Tak --> BlockEmpty[Wymuszenie wartości w UI i API]
    Field --> Unique{Unikalne?}
    Unique -- Tak --> CheckDB[Weryfikacja unikalności w tabeli]
    Field --> Readonly{Tylko do odczytu?}
    Readonly -- Tak --> ProtectWrite[Zablokowanie edycji przez CRUD]
    Field --> System{Systemowe?}
    System -- Tak --> HideOrProtect[Blokada usunięcia / ukrycie konfiguracji]

Przegląd flag:

• Wymagalność (is_mandatory): Oznacza pole jako bezwzględnie wymagane. Formularz nie zezwoli na zapis przy pustej wartości, a silnik API natychmiast zwróci błąd walidacji HTTP 422.
• Unikalność (is_unique): Zapobiega duplikatom w obrębie tabeli modułu. Przy próbie zapisu system weryfikuje, czy rekord o takiej samej wartości już istnieje w bazie danych.
• Tylko do odczytu (is_readonly): Wartość pola może być ustawiana wyłącznie automatycznie przez system, algorytmy obliczeniowe, importy lub przepływy pracy. Użytkownik nie może jej zmodyfikować w formularzu.
• Pole systemowe (is_system): Chroni integralność silnika. Pola oznaczone tą flagą (np. identyfikatory, daty utworzenia, twórca rekordu) nie podlegają usunięciu ani niekontrolowanym zmianom konfiguracji.

---

4. Integracja z DataGrid i widokami

Pola definiują, w jaki sposób użytkownicy mogą wchodzić w interakcję z danymi na listach i w tabelach:

Sortowanie (is_sortable)

• Włącza możliwość kliknięcia nagłówka kolumny DataGrid w celu posortowania danych rosnąco lub malejąco.
• Wyrażenie kolumny jest bezpiecznie przekazywane do klauzuli ORDER BY w zapytaniu SQL.

Filtrowanie (is_filterable)

• Udostępnia pole w pasku szybkiego wyszukiwania oraz w konstruktorze filtrów zaawansowanych.
• W zależności od charakteru pola system automatycznie dobiera odpowiednie operatory porównania (np. równa się, zawiera, jest większe niż, w zakresie dat).

---

5. Organizacja w sekcjach formularza

Układ wizualny formularza edycji rekordu nie jest zdefiniowany statycznie, lecz wynika z relacji pól z sekcjami:

flowchart TD
    Module[Moduł Biznesowy] --> Sec1[Sekcja: Dane podstawowe]
    Module --> Sec2[Sekcja: Rozliczenia i czas]
    Module --> Sec3[Sekcja: Informacje systemowe]

    Sec1 --> F1[sort_order: 10 - Temat]
    Sec1 --> F2[sort_order: 20 - Status]
    Sec2 --> F3[sort_order: 10 - Data rozpoczęcia]
    Sec2 --> F4[sort_order: 20 - Data zakończenia]

Mechanizm grupowania i pozycjonowania:

1. Sekcja nadrzędna (section_id): Przypisuje pole do konkretnego bloku tematycznego w widoku rekordu.
2. Kolejność wyświetlania (sort_order): Liczba całkowita determinująca pozycję pola wewnątrz danej sekcji. Mniejsza wartość oznacza wyższą pozycję na ekranie.
3. Układ siatki Bootstrap/Tabler: Pola są automatycznie formatowane w responsywnych wierszach i kolumnach, zapewniając przejrzystość na monitorach desktopowych i urządzeniach mobilnych.

---

6. Deklaratywne reguły walidacji

Jednym z najbardziej zaawansowanych mechanizmów modułu pól jest kolumna validation_rules. Pozwala ona na deklarowanie reguł sprawdzających poprawność wprowadzanych danych w formacie JSON.

Standardowe reguły walidacji:

• min / max: Wartości minimalne i maksymalne dla pól liczbowych.
• min_length / max_length: Wymagana minimalna lub dopuszczalna maksymalna długość łańcucha znaków.
• regex: Wzorzec wyrażenia regularnego (np. kod pocztowy, identyfikator podatkowy).
• allowed_values: Zamknięta lista dopuszczalnych wartości tekstowych.

Zaawansowane reguły relacyjne (Cross-Field Validation):

Platforma Ammonly obsługuje dynamiczne reguły sprawdzające zależności pomiędzy polami w formularzu:

{
  "after_or_equal": "start_date",
  "max_duration_hours": 24
}

sequenceDiagram
    autonumber
    actor User as Użytkownik
    participant Form as Formularz UI (record-form.js)
    participant API as Silnik API (UniversalValidationEngine)
    participant DB as Baza Danych

    User->>Form: Wprowadza datę zakończenia (różnica > 24h)
    Form-->>User: Natychmiastowy komunikat błędu pod polem (blokada submitu)
    User->>Form: Próba ominięcia UI / bezpośredni POST do API
    Form->>API: Wysłanie payloadu JSON
    API->>API: Sprawdzenie reguły max_duration_hours
    API-->>User: Odpowiedź 422 Unprocessable Entity

• after_or_equal: Sprawdza, czy wartość daty lub czasu nie jest wcześniejsza niż data podana w innym polu (np. data zakończenia zadania w relacji do daty rozpoczęcia).
• max_duration_hours: Wylicza różnicę w czasie pomiędzy polem bazowym a bieżącym, blokując wpisy przekraczające zdefiniowany limit godzin (np. maksymalnie 24 godziny ciągłego czasu pracy).

Dwuwarstwowa ochrona

Reguły zdefiniowane w metadanych są automatycznie przenoszone do atrybutów data-* formularza HTML, dzięki czemu użytkownik otrzymuje natychmiastową informację o błędzie w przeglądarce. Jednocześnie backendowy silnik walidacji bezwzględnie weryfikuje reguły przy każdym zapytaniu REST API.

---

7. Powiązania relacyjne i słownikowe

Pola w systemie Ammonly pełnią kluczową rolę w łączeniu rozproszonych encji w zintegrowany ekosystem:

Relacje między modułami:

• Referencje 1:N: Przechowują klucz obcy do rekordu w innym module (np. przypisanie zadania do projektu).
• Relacje polimorficzne: Umożliwiają dynamiczny wybór modułu docelowego, a następnie konkretnego rekordu (np. powiązanie wpisu czasu pracy zamiennie z Firmą, Partnerem lub Kontaktem).
• Wyświetlanie złożone (relation_display): Określa, jak powiązany rekord jest prezentowany użytkownikowi (np. złożenie imienia i nazwiska lub numeru umowy z jej nazwą).

Słowniki wartości (Picklists):

• Zamiast statycznych list wyboru, pole może być powiązane ze słownikiem systemowym (picklist_id).
• Zmiana opcji, etykiet, kolorów i ikon w słowniku natychmiast aktualizuje wygląd we wszystkich modułach.

---

8. Bezpieczeństwo i ścieżka audytu

Bezpieczeństwo danych na poziomie pojedynczych atrybutów jest integralną częścią architektury Ammonly:

1. Uprawnienia kontekstowe (Field-Level Security): Uprawnienia odczytu i zapisu mogą być precyzyjnie ograniczane na podstawie profilu i roli zalogowanego użytkownika.
2. Rejestr historii zmian (Audit Trail): Każda modyfikacja wartości pola generuje wpis w audycie zawierający poprzednią wartość, nową wartość, identyfikator użytkownika oraz dokładny znacznik czasu.
3. Ochrona przed wstrzykiwaniem danych: Wszystkie operacje zapisu i odczytu realizowane są wyłącznie za pomocą sparametryzowanych zapytań SQL (Prepared Statements).