# 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. | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.eximee.com/budowanie-aplikacji/model-danych/dobre-praktyki-przy-tworzeniu-modelu-danych.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.