# Dobre praktyki przy tworzeniu modelu danych

## Wprowadzenie do modelowania danych

Tworząc model danych dla aplikacji w Eximee, należy kierować się zasadami, które ułatwią utrzymanie systemu oraz zapewnią spójność danych w skali całej organizacji. Dobrze zaprojektowany model to fundament sprawnego przepływu informacji między interfejsem użytkownika a silnikiem procesowym.

### Standardy nazewnictwa kluczy

Skuteczny model danych powinien być intuicyjny. Przy projektowaniu kluczy stosuj poniższe standardy techniczne:

| Aspekt               | Zasada                                                              | Przykład (Dobrze)       | Przykład (Źle)     |
| -------------------- | ------------------------------------------------------------------- | ----------------------- | ------------------ |
| **Format**           | Stosuj camelCase, jeden język (angielski), brak znaków PL i spacji. | `startDateOfEmployment` | `Data_Rozpoczecia` |
| **Logika (Boolean)** | Zaczynaj od `is` lub `has`.                                         | `isPoliticallyExposed`  | `czy_pep`          |
| **Wzorzec "of"**     | Używaj konstrukcji "of" dla jasności kontekstu.                     | `countryOfResidence`    | `residenceCountry` |
| **Identyfikatory**   | Unikaj generycznego `id`. Dodawaj kontekst biznesowy.               | `customerId`            | `id`               |

### Zasady projektowania struktury i rozwoju

Poniższe reguły definiują podejście do architektury modelu i jego ewolucji w czasie:

| Zasada                     | Opis i uzasadnienie biznesowe                                                                                                                                                                                                             |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hierarchia i struktura** | Struktura drzewa musi odpowiadać naturalnej hierarchii danych biznesowych. Grupuj pola w obiekty semantyczne (np. `customerData.name` lub `registerAddress`). Ułatwia to mapowanie całych struktur do usług i zwiększa czytelność modelu. |
| **Dane vs Obliczenia**     | Przechowuj dane źródłowe (np. daty), a nie wartości zmienne lub wyliczalne (np. wiek). Jeśli wyliczenie jest niezbędne, dodaj je jako pole obok zasilane dynamicznie przez provider.                                                      |
| **Unikanie duplikacji**    | Przed dodaniem pola sprawdź, czy podobna informacja już istnieje. Różne obiekty (np. adresy) powinny dzielić te same nazwy kluczy wewnętrznych (np. `streetName`), aby zachować spójność technologiczną.                                  |
| **Strategia YAGNI**        | Nie modeluj struktury „na zapas”. Dodawaj tylko te pola, które są rzeczywiście wymagane na obecnym etapie procesu. Nadmiarowy model utrudnia analitykę.                                                                                   |
| **Reużywalność**           | Projektując nową strukturę, traktuj istniejące modele w innych aplikacjach jako punkt odniesienia. Zachowuj jednolite nazewnictwo tych samych pojęć w skali całej organizacji.                                                            |
| **Aktualizacja wymagań**   | Przy każdej modyfikacji procesu BPMN (np. dodanie lub usunięcie kroku) lub formularza (np. dodanie nowej sekcji z danymi) wykonaj analizę wpływu na model danych. Brak synchronizacji to najczęstsza przyczyna błędów.                    |

### Dokumentacja i parametry techniczne

Model danych w Eximee to nie tylko struktura, ale również metadane ułatwiające integrację i utrzymanie:

| Parametr                    | Zasada i dobre praktyki                                                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Atrybut `docs`**          | Dokumentuj znaczenie biznesowe oraz kontekst kluczy i providerów. W dokumentacji aplikacji stosuj pełną notację kropkową (np. `customerData.address.street`). |
| **Wartość `defaultValue`**  | Pozwala na przypisanie domyślnej wartości (np. flaga `false`), gdy źródła nie dostarczą danych. Zapobiega to błędom typu `null pointer`.                      |
| **Krotność (Multiplicity)** | Parametry muszą precyzyjnie oddawać logikę biznesową. Dla pól wymaganych `Min=1`. Dla list o nieograniczonej długości stosuj `Max=null`.                      |
| **Logika źródeł**           | Dokumentuj kolejność i mapowania dostawców (providers). Pamiętaj - pierwsze źródło, które zwróci wartość inną niż `null`, ma pierwszeństwo.                   |

## Typowe błędy i jak ich unikać

Poniżej przedstawiono przegląd najczęstrzych błędów popełnianych przy tworzeniu modelu danych oraz jego wykorzystaniu - ich przyczyny, skutki oraz jak ich unikać.

| Błąd                          | Przyczyna                                               | Skutek                                                                                                   | Rozwiązanie                                                                                                                                                                                                            |
| ----------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Brak powiązania z formularzem | Zapomniano ustawić "Klucz modelu danych" w komponencie. | Dane nie są zapisywane (pole puste po odświeżeniu).                                                      | Ustaw klucz w właściwościach komponentu, wpisując dokładny klucz pola z modelu danych. Po zapisaniu formularza komponent zapisze swoją wartość do tego pola, a przy uruchomieniu pobierze z modelu istniejącą wartość. |
| Literówki i niezgodności nazw | Ręczne wpisywanie nazw w opcji "Klucz modelu danych".   | Komponent nie połączy się z właściwym polem w modelu danych - wartość nie zapisze się do modelu.         | "Używaj ikony kopiowania obok klucza w modelu danych.                                                                                                                                                                  |
| Błędne użycie tablic          | Pominięcie notacji indeksowej (np. `produkty.cena`).    | Składnia bez \[] lub indeksu jest niepoprawna i spowoduje błąd uniemożliwiający uruchomienie formularza. | W sekcjach powtarzalnych stosuj notację `produkty[].cena`.                                                                                                                                                             |
| Niewidoczny model danych      | Brak artefaktu w aplikacji.                             | Model nie został zainicjowany.                                                                           | Użyj przycisku "Zainicjuj model danych" w zakładce "Model danych" aplikacji.                                                                                                                                           |