soneta-erp-skills/soneta-place-def-elementow/SKILL.md

---

name: soneta-place-def-elementow description: Tworzenie i konfiguracja definicji elementów wynagrodzenia w enova365/Soneta przez MCP soneta_ui. Algorytmy naliczania (kreator, edytor C#, wbudowane), wzorce algorytmiczne, receptury kodu C# dla elementów płacowych, konfiguracja PIT/ZUS/nieobecności. Używaj gdy użytkownik: (1) chce utworzyć/skonfigurować definicję elementu wynagrodzenia (zakładki Ogólne, Deklaracje, Nieobecności, Algorytm); (2) pyta o algorytm naliczania (kreator, edytor, kod C#); (3) potrzebuje kodu C# do edytora algorytmu (_Param, _Wylicz, _Wartość1h); (4) pyta o wzorce dla dodatków, nieobecności, zasiłków; (5) wspomina 'definicja elementu', 'element wynagrodzenia', 'algorytm płacowy', 'WypSkladnik', 'WypElement', 'premia procentowa', 'dodatek stażowy', 'zasiłek chorobowy', 'ekwiwalent za urlop'; (6) pisze recepturę kodu płacowego (staż pracy, wymiar etatu, czas pracy, wskaźniki, cechy pracownika).

Definicje elementów wynagrodzenia — enova365

Ten skill zawiera kompletną wiedzę o tworzeniu i konfigurowaniu definicji elementów wynagrodzenia w enova365. Wiedza jest podzielona na pliki referencyjne — czytaj odpowiedni plik w zależności od potrzeby.

Spis treści referencji

Plik	Kiedy czytać	Zawartość
references/algorytmy-naliczania.md	Gdy trzeba wybrać typ algorytmu, skonfigurować kreator lub napisać kod edytora	Typy algorytmów, parametry kreatora (podstawa, mnożnik, korekty), struktura kodu C# edytora, przykłady kompletnych algorytmów
references/wzorce-algorytmiczne.md	Gdy trzeba znaleźć najbliższy wzorzec dla nowego elementu	12 wzorców dla Dodatków (A-L), 5 dla Nieobecności (A-E), 5 dla Dodatków automatycznych (A-E) — z analizy ~247 definicji
references/receptury-kodu.md	Gdy trzeba napisać konkretny fragment kodu C#	24 kategorie gotowych fragmentów: iterowanie po elementach, wynagrodzenie zasadnicze, nieobecności, wymiar etatu, czas pracy, okresy, staż, cechy, wskaźniki, parametry dodatku, zaokrąglenia, netto→brutto, urlopy, debugowanie
references/api-algorytmow.md	Gdy potrzebna jest referencja API — pola, metody, klasy, typy	Pola WypSkladnik, metody pomocnicze, klasy naliczania, moduły, dostęp do konfiguracji, operacje na typach danych, sygnatury metod
references/metody-sterujace-naliczaniem.md	Gdy element musi wpływać na podstawy urlopów lub zasiłków	Metody _PodstawaUrlopu, _PodstawaZasiłku, klasa PodstawaZasiłkuArgs

Lokalizacja w programie

Folder konfiguracyjny: Ustawienia/Kadry i płace/Płace/Elementy wynagrodzenia

Formularz zawiera:

• Listę definicji (gridID: _New_CfgDefElementowExtender_DefElementow)
• Filtry pod listą:
  • Rodzaj — typ elementu (31 rodzajów)
  • Zakres — Standardowe / Definiowane / Razem (pokaż wszystkie)
  • Stan — Aktywne / Zablokowane / Razem (pokaż wszystkie)

Aby zobaczyć wszystkie definicje, ustaw Zakres=Razem i Stan=Razem.

Rodzaje elementów wynagrodzenia

Rodzaj	Klasa elementu	Typowe zastosowanie
Etat	WypElementEtat	Wynagrodzenie zasadnicze (mies./godz.), dochód deklarowany
Dodatek	WypElementDodatek	Premie, dodatki (funkcyjny, stażowy), ekwiwalenty, ryczałty, odprawy, potrącenia, korekty, odsetki
Dodatek automatyczny	WypElementDodatekAutomatyczny	Elementy naliczane automatycznie (PPK, potrącenie OPP, wynagrodzenie postojowe)
Nieobecność	WypElementNieobecnosc	Wynagrodzenie za urlopy, zasiłki (chorobowy, macierzyński, opiekuńczy), świadczenia rehabilitacyjne
Nadgodziny I/II/św	WypElementNadgodziny	Dopłata do nadgodzin 50%, 100%, za święta
Nocne	WypElementNocne	Dopłata za godziny nocne
Akord	WypElementAkord	Wynagrodzenie akordowe
Nagroda	WypElementNagroda	Nagroda pieniężna
Kara	WypElementKara	Kara pieniężna
Umowa	WypElementUmowa	Umowy cywilnoprawne, IFT-1, PIT-8A, PIT-R
Umowa rozliczenie	WypElementUmowa	Wyrównania umów zlecenia, kontraktów menedżerskich
Świadczenie	WypElementSwiadczenie	Świadczenia socjalne (z limitem i bez)
Odchyłki	WypElementOdchylki	Rozliczenie odchyłek czasu pracy, przerwy na karmienie
Zaliczka / Zaliczka zwrot	WypElementZaliczka	Zaliczki i ich spłaty
Pożyczka / Pożyczka spłata	WypElementPozyczka	Pożyczki KZP/ZFM, spłaty, umorzenia
Fund poż składka/wpisowe/wycofanie	—	Składki KZP/ZFM, wpisowe, wycofanie wkładu
Wyrównanie do minimalnej	WypElementWyrownanie	Wyrównanie do minimalnej płacy
Zajęcie komornicze	WypElementZajecie	Alimenty, zajęcia komornicze
Przychód od składki pracodawcy PPK	—	Przychód PPK, zwroty składek PPK
Zwrot nadpłaty PPK	—	Zwroty nadpłat PPK
Zbieg pracy i rodzicielstwa	—	Urlop wychowawczy/macierzyński przy zbiegu z pracą

Zakładki formularza definicji

Ogólne (DefinicjaElementuProPage)

Pole	Opis	Przykładowe wartości
Nazwa	Unikalna nazwa definicji	Premia procentowa
Nazwa wyświetlana	Nazwa wyświetlana operatorowi	Premia procentowa
Skrót	Krótki identyfikator	Prm.procent
Kod	Opcjonalny kod zewnętrzny	—
Blokada	Czy definicja zablokowana	Nie/Tak
Naliczanie	Płatna z góry / z dołu	PłatnaZDołu
Typ okresu naliczania	Jak często naliczać	Jednorazowa, Każdy okres, Co n miesięcy
Przyrównuj do najniższego	Czy wliczać do wyrównania	Tak/Nie
Korygowany	Czy generować korektę przy zmianie	Tak/Nie
Generuj zerowy element	Czy generować przy wartości 0	Tak/Nie
Definicja listy płac	Do której listy płac	LPE (objectID=3)
Rodzaj wypłaty	Etat/Umowa/InnaWyplata	Etat
Kolejność na listach płac	Porządek sortowania	0-99
Identyfikator	Identyfikator C# (auto)	Premia_Procentowa

Deklaracje (DefinicjaElementuDeklaracjePage)

Konfiguracja podatków i składek ZUS:

Sekcja	Kluczowe pola
PIT	Pozycja PIT, typ zaliczki (wg skali / procentowe), koszty uzyskania, ulga podatkowa
ZUS	Podstawa składek społecznych, składka zdrowotna, FP, FGŚP, kod RSA
Priorytet	Priorytet naliczania podatków i składek

Nieobecności (DefinicjaElementuNieobecnosciProPage)

Konfiguracja wliczania do podstaw urlopów i zasiłków:

Sekcja	Opcje
Wynagrodzenia za urlop	NieWliczać, WliczaćAktualnąWartość, WliczaćPoPrzeliczeniu, WliczaćJakZasadnicze
Wynagrodzenia za ekwiwalent	j.w. + opcja dopełnienia
Zasiłki (pracownicy)	NieWliczać, WliczaćDla, DopełniaćWedługGodzinDla, DopełniaćJakZasadniczeDla
Zasiłki (inni ubezpieczeni)	j.w.

Algorytm/Ogólne (DefinicjaElementuAlgorytmPage)

Główna zakładka konfiguracji algorytmu — szczegóły w references/algorytmy-naliczania.md.

Algorytm/Edytor (DefinicjaElementuEdytorPage)

Pole kodu C# (typ code) — edytor algorytmu. Aktywny gdy Algorytm = "Edytor algorytmu".

Algorytm/Podgląd (DefinicjaElementuPodgladPage)

Podgląd wygenerowanego kodu C# (read-only).

Tworzenie nowego elementu — krok po kroku przez MCP

1. navigate_to_folder("Ustawienia/Kadry i płace/Płace/Elementy wynagrodzenia")
2. add_subobject(gridID="_New_CfgDefElementowExtender_DefElementow")
3. update_field_value — wypełnij zakładkę Ogólne (nazwa, skrót, naliczanie, lista płac)
4. switch_form_page("DefinicjaElementuAlgorytmPage") — skonfiguruj algorytm
5. [opcjonalnie] switch_form_page("DefinicjaElementuEdytorPage") — wpisz kod C#
6. switch_form_page("DefinicjaElementuDeklaracjePage") — skonfiguruj PIT/ZUS
7. switch_form_page("DefinicjaElementuNieobecnosciProPage") — skonfiguruj wliczanie do podstaw
8. accept_subform() — zatwierdź podformularz
9. save_form() — zapisz do bazy

Wybór algorytmu

Scenariusz	Zalecany algorytm
Prosta kwota lub procent od zasadniczego	Kreator algorytmu — wystarczy ustawić Podstawę i Mnożnik
Złożona logika (warunki, nietypowe obliczenia)	Edytor algorytmu — własny kod C#
Naliczanie jak urlop/ekwiwalent	Jak urlop wypoczynkowy / Jak ekwiwalent za urlop
Naliczanie za okres nieobecności	Za okres nieobecności

Formatowanie kodu w edytorze (przez MCP)

Znaki nowej linii w kodzie C# przez MCP wstawiamy jako \\n:

update_field_value(["_Tekst=public void Nazwa_Param(...) {\\n    ...\\n}\\n\\npublic Currency Nazwa_Wylicz(...) {\\n    return ...;\\n}"])

Wskazówki przy tworzeniu nowych algorytmów

1. Element to parametr metody — w kodzie algorytmu Element nie jest zmienną globalną ani polem klasy — jest pierwszym parametrem każdej metody (_Param, _Wylicz, _Wartość1h itd.). Metoda musi zawsze zawierać te parametry. Typ tego parametru musi odpowiadać rodzajowi definiowanego elementu:

   • Etat → Soneta.Place.WypElementEtat Element
   • Dodatek → Soneta.Place.WypElementDodatek Element
   • Dodatek automatyczny → Soneta.Place.WypElementDodatekAutomatyczny Element
   • Nieobecność → Soneta.Place.WypElementNieobecnosc Element
   • Nadgodziny → Soneta.Place.WypElementNadgodziny Element
   • Umowa → Soneta.Place.WypElementUmowa Element

   Przykład: jeśli algorytm odwołuje się do Element.DodHistoria.Podstawa, a definicja jest rodzaju Dodatek, to sygnatura metody musi wyglądać:

   public void MojDodatek_Param(WypElementDodatek Element, WypSkladnik Składnik) { ... }
   

2. Wybierz wzorzec — większość nowych elementów pasuje do jednego z istniejących wzorców. Przeczytaj references/wzorce-algorytmiczne.md i zacznij od skopiowania najbliższego wzorca.

3. Źródło kwoty — zdecyduj skąd pochodzi podstawa:

   • Kwota z parametrów pracownika → Element.DodHistoria.Podstawa (Wzorzec A)
   • Kwota z konfiguracji programu → module.Config.Zasiłki.*[Date] (Wzorzec B)
   • Kwota stała z definicji → Element.Definicja.Algorytm.KreatorAlgorytmu.Podstawa (Wzorzec C)
   • Procent od zasadniczego → ZasadniczeNominalne(Date) + Element.DodHistoria.Procent (Wzorzec D)

4. Czas i dni — prawie wszystkie algorytmy ustawiają czas i dni z normy:

   CzasDni cd = Element.Pracownik.Czasy.Norma(Składnik.Okres);
   Składnik.Czas = cd.Czas;
   Składnik.Dni = cd.Dni;
   

5. Pomniejszenie za nieobecności — użyj kreatora algorytmu z konfiguracją korekt lub ręcznie: Element.Pracownik.Czasy.Nieobecnosci(Składnik.Okres).Dni

6. Proporcjonalność do okresu — gdy okres składnika jest krótszy niż pełny okres naliczania, przelicz proporcjonalnie (jak w Premii procentowej — Wzorzec D).

7. Zasiłki — zawsze używaj new PodstawaZasiłku(Element) i WyliczPodstawęZasiłkuZaDzień(...) — nie obliczaj podstawy zasiłku ręcznie.

8. Urlopy okolicznościowe — używaj new NaliczanieOkolicznosciowy(Element, Składnik).NaliczPodstawy() — automatycznie ustawi Podstawa1 (za godziny) i Podstawa2 (za dni).

9. Ekwiwalenty i odprawy — używaj new NaliczanieEkwiwalent(Element, Składnik).NaliczPodstawy().

10. Element.DodHistoria.Podstawa vs Element.DodHistoria.Kwota — w rzeczywistych algorytmach kreatorowych kwota pobierana jest z Element.DodHistoria.Podstawa (nie .Kwota). Pole .Kwota występuje w dokumentacji, ale .Podstawa jest częściej stosowane w generowanym kodzie.

11. Dodatkowe metody — jeśli element ma odbiorców płatności (potrącenia, alimenty), zdefiniuj metody _Odbiorca i _RachunekOdbiorcy. Jeśli okres naliczania wymaga podziału, zdefiniuj _CięcieOkresu. Jeśli element wpływa na podstawy urlopów/zasiłków — przeczytaj references/metody-sterujace-naliczaniem.md.