# Skill zarządzania programem Soneta (enova365) przez MCP

## 1. Przepływ pracy (workflow MCP)

Narzędzia MCP `soneta_ui` są **zależne od siebie** — muszą być wywoływane w określonej sekwencji:

```
get_modules → get_folders → navigate_to_folder → retrieve_list → focus_row / open_form → switch_form_page → update_field_value
                                                                   ↓
                                                              add_object → update_field_value
```

### Zasady sekwencji

- `retrieve_list` wymaga wcześniejszego `navigate_to_folder`
- `open_form(objectID)` wymaga `objectID` z odpowiedzi `retrieve_list`
- `switch_form_page(pageID)` wymaga `pageID` z odpowiedzi `open_form`
- `update_field_value` działa tylko na polach oznaczonych jako `edytowany`
- `add_object` tworzy nowy obiekt w aktualnie nawigowanym folderze
- `focus_row(objectID)` zaznacza wiersz na liście bez otwierania formularza

### Narzędzia eksploracyjne (niezależne)

- `get_modules` — lista modułów (punkt startowy)
- `get_folders(programFolder)` — podfoldery danego modułu/folderu

## 2. Formaty danych (CultureInfo.InvariantCulture)

Wszystkie wartości przesyłane z/do programu muszą używać formatu InvariantCulture:

| Typ | Format | Przykład |
|-----|--------|----------|
| Date | `yyyy-MM-dd` | `2026-03-25` |
| FromTo | `yyyy-MM-dd..yyyy-MM-dd` | `2026-01-01..2026-03-31` |
| Bool | `Tak` / `Nie` | `Tak` |
| Number | kropka dziesiętna | `1234.56` |
| Filter | `["filterID=Wartość"]` | `["_Status=Aktywny", "_DataListy=2026-01-01.."]` |


## Foldery w programie

| Intencja użytkownika | programFolder |
|---|---|
| terminarz, zadania do wykonania | `Terminarz` |
| zarządzanie dokumentami, DMS | `DMS` |
| procesy workflow | `Workflow` |

## 4. Typowe scenariusze krok po kroku

### Scenariusz A — Odczyt danych z listy

```
1. navigate_to_folder(programFolder)     — otwórz folder
2. retrieve_list(filters?, pageNumber?)  — pobierz dane (opcjonalnie z filtrami)
3. Prezentuj wyniki użytkownikowi
```

### Scenariusz B — Podgląd szczegółów obiektu

```
1. navigate_to_folder(programFolder)     — otwórz folder
2. retrieve_list()                       — pobierz listę, znajdź objectID
3. open_form(objectID)                   — otwórz formularz
4. switch_form_page(pageID)              — przełącz zakładkę jeśli potrzeba
```

### Scenariusz C — Edycja istniejącego obiektu

```
1. navigate_to_folder(programFolder)     — otwórz folder
2. retrieve_list()                       — znajdź obiekt
3. open_form(objectID)                   — otwórz formularz
4. switch_form_page(pageID)              — przejdź do zakładki z polem (jeśli trzeba)
5. update_field_value(["fieldID=value"]) — zmień wartość pola oznaczonego 'edytowany'
```

### Scenariusz D — Dodawanie nowego obiektu

```
1. navigate_to_folder(programFolder)     — otwórz odpowiedni folder
2. add_object()                          — utwórz nowy obiekt
3. update_field_value(["fieldID=value"]) — wypełnij wymagane pola
```

### Scenariusz E — Przeglądanie dużej listy (stronicowanie)

```
1. navigate_to_folder(programFolder)
2. retrieve_list(pageNumber=0)           — pierwsza strona
3. retrieve_list(pageNumber=1)           — kolejna strona
4. ... kontynuuj aż dane się wyczerpią
```

### Scenariusz F — Nawigacja eksploracyjna (nieznany folder)

```
1. get_modules()                         — lista modułów
2. get_folders(moduł)                    — foldery w module
3. get_folders(moduł/podfolder)          — dalsze podfoldery (jeśli type=folders)
4. navigate_to_folder(znaleziony_folder) — otwórz właściwy folder
```

## 5. Zasady bezpieczeństwa


- **Edytuj tylko pola** oznaczone jako `edytowany` — nie próbuj wymuszać zmian na polach tylko do odczytu
- **Nie zakładaj filterID filtrów** — odczytaj je z odpowiedzi `retrieve_list`
- **Nie zakładaj fieldID zmienianych pól** — odczytaj je z odpowiedzi `open_form`, `switch_form_page`, `add_object`
- **Edytuj tylko pola na aktualnej zakładce** — odczytaj je z odpowiedzi `open_form`, `switch_form_page`, `add_object`. Żeby zmienić pole na innej zakładce użyj `switch_form_page`
- **Stronicowanie** — używaj `pageNumber` do iteracji po dużych listach, nie próbuj pobrać wszystkiego naraz

## 6. Obsługa błędów

| Problem | Rozwiązanie |
|---|---|
| `navigate_to_folder` zwraca błąd | Sprawdź ścieżkę przez `get_folders` — ścieżka może być nieprawidłowa |
| Lista jest pusta | Zasugeruj zmianę lub usunięcie filtrów |
| Pole nie jest `edytowany` | Poinformuj użytkownika — pole jest tylko do odczytu |
| Brak `objectID` | Najpierw wykonaj `retrieve_list` aby uzyskać identyfikatory |
| Brak `pageID` | Najpierw wykonaj `open_form` aby uzyskać listę zakładek |
| Nieznany folder | Użyj `get_modules` → `get_folders` do eksploracji struktury |

## 7. Parametr navigate_to_folder — newTab

- `newTab: true` — otwiera folder w nowej karcie (nie zamyka aktualnego widoku)
- `newTab: false` (domyślnie) — zastępuje aktualny widok
- Używaj `newTab: true` gdy użytkownik chce porównać dane z dwóch folderów