Soneta Addon Planning

Planowanie projektu modułu/dodatku Soneta

Skill prowadzi interaktywny proces planowania nowego modułu dla platformy Soneta (programy enova365 i Triva — oparte na tej samej platformie technologicznej). Efektem jest dokumentacja projektowa, która w kolejnych krokach zasila skille /soneta-business-xml (model danych), /soneta-form-xml (formularze) i /soneta-programming (logika).

Ten plik jest mapą procesu — po kroku wstępnym (Etap 0) następują trzy etapy o rosnącym poziomie szczegółowości. Szczegółowe specyfikacje sekcji każdego etapu są w plikach references/, które czytasz dopiero, gdy dochodzisz do danego etapu.

Na końcu, po zamknięciu etapów, generujesz dokument TODO z kolejnymi krokami implementacji.

Etapy 1–3 osadzają plan w istniejącym modelu danych przez inwentaryzację narzędziami scan-modules i scan-folders — wymagania środowiska, uruchomienie i użycie planistyczne opisuje references/dane-referencyjne.md. Przeczytaj go przy pierwszym sięgnięciu po inwentaryzację (najpóźniej w sekcji 1.5 Etapu 1); tam też jest reguła postępowania, gdy środowiska brak.

Jak prowadzić rozmowę

Proces jest interaktywny. Nie generuj całego dokumentu naraz — pracuj etap po etapie:

0. Zacznij od Etapu 0 — krok wstępny niezależny od treści modułu (references/etap-0-przygotowanie.md): ustal nazwę firmy i zadbaj o repozytorium Git, zanim przejdziesz do Etapu 1.
1. Wczytaj etap — gdy zaczynasz Etap N, przeczytaj references/etap-N-*.md. Plik zawiera pytania do zadania oraz szczegółową specyfikację sekcji tego etapu.
2. Zbierz informacje — zacznij od ogólnej idei modułu (co chce osiągnąć, dla kogo, jaki problem rozwiązuje), potem doprecyzowuj pytaniami z pliku etapu.
3. Opracuj etap — na podstawie odpowiedzi wygeneruj dokument etapu. Etap jest opracowany dopiero, gdy każda sekcja z pliku etapu jest wypełniona albo jawnie odnotowana jako otwarta kwestia — gdy czegoś brakuje, zadaj konkretne pytanie zamiast zgadywać.
4. Poczekaj na zatwierdzenie — przedstaw dokument i poczekaj na akceptację/uwagi. Nie przechodź dalej bez wyraźnej zgody.
5. Iteruj i przejdź dalej — po poprawkach i akceptacji przejdź do kolejnego etapu.

Prowadź rozmowę po polsku. Zadawaj pytania grupami tematycznymi (2–4 na raz) — nie zasypuj użytkownika listą 15 pytań naraz — i dostosowuj kolejne pytania do odpowiedzi.

Zapis dokumentów

Każdy etap zapisz jako osobny plik Markdown w katalogu roboczym projektu (domyślnie podkatalog nazwany po module, np. plan-<nazwa-modułu>/), chyba że użytkownik wskaże inne miejsce:

• etap-1-wizja.md, etap-2-architektura.md, etap-3-specyfikacja.md
• otwarte-kwestie.md — prowadzona przez cały proces
• todo.md — na końcu

Przed utworzeniem katalogu upewnij się z użytkownikiem co do nazwy modułu i lokalizacji.

Otwarte kwestie

Otwarte kwestie to jedno wspólne miejsce, w którym zbierane są wszystkie decyzje projektowe pozostające do podjęcia — użytkownik ma w każdym momencie jasny obraz tego, co blokuje przejście dalej. Prowadź tę listę przez cały proces.

Co trafia na listę

Dopisuj nową kwestię zawsze, gdy:

• pojawia się pytanie projektowe, na które nie znasz odpowiedzi — zamiast zgadywać, zapisz je jako otwartą kwestię,
• istnieje kilka alternatyw i wybór należy do użytkownika (np. wariant struktury danych, sposób integracji),
• brakuje informacji od osoby trzeciej (klient, inny zespół, dział prawny, licencjonowanie),
• decyzję świadomie odkładasz „na później", aby nie blokować bieżącego etapu,
• użytkownik mówi „zastanowię się", „dopytam", „nie wiem jeszcze" — to sygnał do założenia wpisu.

Nie zostawiaj nierozstrzygniętych założeń ukrytych w treści dokumentu — każde takie miejsce powinno mieć odpowiadający wpis na liście.

Struktura tabeli

• Obszar — czego dotyczy (dane, UI, integracje, uprawnienia, wydajność, licencje, proces…).
• Wpływ — jak duże są konsekwencje decyzji dla projektu.
• Blokująca — czy kwestia uniemożliwia zatwierdzenie etapu lub rozpoczęcie implementacji.
• Status — cykl życia: Otwarta → W trakcie → Zamknięta.
• Decyzja i uzasadnienie — przy zamknięciu wpisz nie tylko co postanowiono, ale i dlaczego. Nigdy nie usuwaj zamkniętych kwestii — stanowią historię decyzji.

Zasady prowadzenia

1. Numeracja jest stała — raz nadany numer nie zmienia się; zamknięte pozycje zostają na liście.
2. Aktualizuj na bieżąco — gdy zapadnie decyzja, od razu zmień status na Zamknięta i uzupełnij kolumnę decyzji.
3. Prezentuj na końcu każdego etapu — pokaż pełną listę i wyraźnie wskaż kwestie otwarte oraz blokujące.
4. Bramka jakości — nie przechodź do kolejnego etapu z otwartymi kwestiami blokującymi dla tego etapu. Kwestie nieblokujące można przenieść dalej, ale muszą pozostać widoczne.
5. Powiązanie z TODO — „Zamknięcie otwartych kwestii" jest pozycją TODO; do implementacji nie wchodzimy z otwartymi kwestiami blokującymi.

Lokalizacja projektów kodu (etap implementacji)

Dokumenty planistyczne (etapy, otwarte kwestie, TODO) trzymasz w podkatalogu planu — patrz „Zapis dokumentów". Natomiast gdy proces dojdzie do budowania folderów projektów (rusztowanie solucji dodatku — patrz skill /soneta-programming, new-addon-cli.md), twórz je bezpośrednio w bieżącym katalogu roboczym: plik solucji (.sln) oraz projekty (Firma.NazwaModulu, Firma.NazwaModulu.UI, Firma.NazwaModulu.Tests) mają leżeć w katalogu, w którym pracujesz, a nie w zagnieżdżonym podfolderze. Dzięki temu repozytorium Git założone w Etapie 0 obejmuje solucję od razu. Nazwy projektów budujesz z ustalonej w Etapie 0 nazwy firmy.

Dokument TODO

Po zamknięciu wszystkich etapów wygeneruj dokument TODO z kolejnymi krokami:

Uzupełnienie planu

• Weryfikacja i zatwierdzenie Etapu 1 przez interesariuszy
• Weryfikacja i zatwierdzenie Etapu 2 przez zespół projektowy
• Uzupełnienie specyfikacji szczegółowej (Etap 3) dla wszystkich obiektów
• Zamknięcie otwartych kwestii

Implementacja

• Rusztowanie solucji w bieżącym katalogu (projekty Firma.NazwaModulu*, → skill /soneta-programming, new-addon-cli.md)
• Model danych — tabele, pola, relacje
• Plik business.xml (→ skill /soneta-business-xml)
• Struktura menu, listy, widoki
• Formularze i zakładki (→ skill /soneta-form-xml)
• Konfiguracja — słowniki, definicje, ustawienia
• Dane konfiguracyjne inicjujące bazę (sekcja 3.14) — pliki *.dbinit.xml w projekcie jako EmbeddedResource; budowa pliku → skill /soneta-config (import-export-xml), osadzenie → /soneta-programming (new-addon-cli), test wczytania przez dbmgr importxml → /soneta-tools
• Weryfikatory — walidacja danych wprowadzanych przez operatora (→ skill /soneta-programming, verifiers.md)
• Workery i czynności (→ skill /soneta-programming, worker-extender.md)
• Algorytmy w transakcji serwerowej — logika zależna od równoległej pracy stanowisk (→ skill /soneta-programming, events.md)
• Raporty i wydruki
• Procesy Workflow
• Wskaźniki i wykresy BI
• Uprawnienia i role
• Integracje z innymi systemami
• Baza Demo i dane demonstracyjne
• Testy integracyjne — dla każdego workera, każdego algorytmu obiektu biznesowego, każdego weryfikatora i każdej logiki w transakcji serwerowej (→ skill /soneta-programming, integration-tests.md)
• Dokumentacja użytkownika i techniczna

Powiązanie z innymi skillami

Już podczas planowania korzystasz z narzędzi inwentaryzacyjnych: scan-modules i scan-props (skill /soneta-programming) oraz scan-folders (skill /soneta-config) — łącznie odwzorowują istniejący model danych i menu platformy (patrz references/dane-referencyjne.md).

Po zatwierdzeniu planu projektu:

1. /soneta-business-xml — generowanie pliku business.xml na podstawie modelu danych z Etapu 3 (sekcje 3.1–3.3).
2. /soneta-form-xml — generowanie formularzy i widoków UI na podstawie sekcji 3.4 i 3.5.
3. /soneta-programming — implementacja logiki biznesowej i testów; dokumenty właściwe dla poszczególnych obszarów Etapu 3 wskazują strzałki (→) przy pozycjach dokumentu TODO powyżej.