Dostęp specjalny (UiType: special_access)

Pole Dostęp specjalny (special_access, kod UiType: 6010) jest kluczowym komponentem silnika bezpieczeństwa i cyklu życia rekordów w platformie Ammonly. Umożliwia precyzyjne sterowanie widocznością, archiwizacją, usuwaniem miękkim (soft delete) oraz izolacją rekordów systemowych i poufnych.

Wyłączność modyfikacji

Modyfikacja wartości pola Dostęp specjalny jest dozwolona wyłącznie dla użytkowników posiadających uprawnienie Superuser. Dla pozostałych użytkowników kontrolka formularza pozostaje zablokowana (zabezpieczenie interfejsu i warstwy REST API).

---

Spis treści

• 1. Rola i przeznaczenie pola
• 2. Wartości i stany cyklu życia
• 3. Zasady uprawnień i ograniczenia dostępu
• 4. Różnica między statusem biznesowym a dostępem specjalnym
• 5. Zabezpieczenia systemowe i warstwa backendowa
• 6. Prezentacja w interfejsie i DataGrid

---

1. Rola i przeznaczenie pola

W systemie Ammonly każdy rekord modułu CRUD posiada wbudowaną kolumnę special_access typu TINYINT UNSIGNED NOT NULL DEFAULT 1. Pole to odpowiada za:

1. Zarządzanie cyklem życia rekordu: Przenoszenie rekordów pomiędzy stanem aktywnym, archiwum a koszem bez fizycznego usuwania danych z bazy.
2. Kontrolę widoczności i izolację: Ochronę rekordów ukrytych przed niepowołanym wglądem.
3. Standaryzację filtrów DataGrid: Automatyczną agregację liczby rekordów w dedykowanych zakładkach widoków listowych.

flowchart TD
    A[Tworzenie Rekordu] -->|Domyślnie DEFAULT 1| B[Widoczny / Visible]
    B -->|Archiwizacja przez Superusera| C[Zarchiwizowany / Archived: 2]
    B -->|Usunięcie miękkie przez Superusera| D[Usunięty / Kosz: 3]
    B -->|Ukrycie poufne przez Superusera| E[Ukryty / Hidden: 0]
    C -->|Przywrócenie| B
    D -->|Przywrócenie| B
    E -->|Odkrycie| B

---

2. Wartości i stany cyklu życia

System definiuje 4 standardowe poziomy dostępu specjalnego:

Kod SQL	Nazwa techniczna	Etykieta UI	Kolor Badge	Domyślna ikona	Dostępność
1	AVAILABLE / VISIBLE	Widoczny	success	bi bi-check-circle	Domyślny status tworzonego rekordu. Widoczny dla wszystkich uprawnionych użytkowników.
2	ARCHIVED	Zarchiwizowany	warning	bi bi-archive	Dostępny wyłącznie dla właściciela (owner), współwłaścicieli (co_owners) oraz superusera.
3	DELETED	Usunięty / Kosz	danger	bi bi-trash	Soft delete. Dostępny wyłącznie dla właściciela (owner), współwłaścicieli (co_owners) oraz superusera.
0	HIDDEN	Ukryty	dark	bi bi-eye-slash	Rekord ukryty. Dostępny i widoczny wyłącznie dla superuserów. Niewidoczny dla zwykłych użytkowników.

---

3. Zasady uprawnień i ograniczenia dostępu

Rekordy Widoczne (1 = Widoczny)

• Rekord w stanie 1 podlega standardowym regułom bezpieczeństwa modułu (uprawnienia modułu, profil użytkownika, bezpośredni właściciel, współwłaściciele lub uprawnienia współdzielone przez strukturę organizacyjną).
• Nowo tworzone rekordy we wszystkich modułach automatycznie otrzymują wartość 1 na poziomie definicji bazy danych (DEFAULT 1).

Rekordy Zarchiwizowane (2 = Zarchiwizowany) i Usunięte (3 = Usunięty)

• Dostęp do rekordów zarchiwizowanych i usuniętych jest rygorystycznie zawężony:
  • Dostęp mają wyłącznie bezpośredni właściciele (owner_type = 'user' i owner = actor_id),
  • Współwłaściciele rekordu (co_owners oraz relacje w tabeli a_core_record_co_owners),
  • Superuserzy systemu.
• Uprawnienia współdzielone przez strukturę firmy (structure) ani reguły delegowane (a_core_access_user_owners) nie dają dostępu do rekordów oznaczonych kodem 2 lub 3.

Rekordy Ukryte (0 = Ukryty)

• Rekord oznaczony kodem 0 jest całkowicie niewidoczny w zapytaniach DataGrid, widokach szczegółowych oraz API dla użytkowników nieposiadających uprawnienia Superuser.
• Silnik UniversalFilterClauseBuilder automatycznie aplikuje klauzulę special_access != 0 dla każdego zapytania wykonywanego przez zwykłego użytkownika.

---

4. Różnica między statusem biznesowym a dostępem specjalnym

W architekturze Ammonly występuje ścisłe rozgraniczenie dwóch pojęć:

classDiagram
    class RekordModulu {
        +VARCHAR status "Status biznesowy (np. planned, active, closed)"
        +TINYINT special_access "Dostęp specjalny (0=Ukryty, 1=Widoczny, 2=Archiwum, 3=Kosz)"
    }

1. Status biznesowy (status):

   • Pole słownikowe (np. planned, in_progress, completed, cancelled w Zadaniach czy active, inactive w Użytkownikach).
   • Każdy moduł posiada własny słownik statusów biznesowych dopasowany do specyfiki procesu.
   • Zmiana statusu biznesowego nie wpływa na techniczne ukrywanie rekordu ani na reguły dostępu właścicielskiego.

2. Dostęp specjalny (special_access):

   • Pole uniwersalne, obecne w każdym module systemu.
   • Posiada ściśle zdefiniowane 4 wartości systemowe (0, 1, 2, 3).
   • Bezpośrednio steruje filtrowaniem w silniku zapytań SQL (UniversalQueryBuilder), blokowaniem odczytu (assertRecordReadOwnership) i dostępnością w zakładkach DataGrid.

---

5. Zabezpieczenia systemowe i warstwa backendowa

Ochrona zapisu (Superuser Only)

Próba przesłania wartości pola special_access przez użytkownika bez flagi is_superuser:

• Zostaje automatycznie usunięta z payloadu zapisu w metodzie sanitizeWriteFields() silnika UniversalCrudService.
• Próba bezpośredniej zmiany przez dedykowane API updateSpecialAccess() skutkuje natychmiastowym rzuceniem wyjątku PermissionDeniedException.

Ochrona odczytu pojedynczego rekordu

Próba pobrania szczegółów rekordu (GET /api/v1/*/:id) weryfikowana jest przez metodę assertRecordReadOwnership():

• Jeśli special_access === 0 i użytkownik nie jest superuserem -> błąd 403 Forbidden.
• Jeśli special_access IN (2, 3) i użytkownik nie jest bezpośrednim właścicielem ani współwłaścicielem -> błąd 403 Forbidden.

---

6. Prezentacja w interfejsie i DataGrid

Formularz edycji i tworzenia

• W widoku tworzenia i edycji pole special_access renderowane jest przy użyciu dedykowanego szablonu Twig special_access.twig.
• Dla użytkowników bez uprawnień Superuser pole posiada atrybut disabled oraz ikonę kłódki informującą o braku uprawnień do zmiany poziomu dostępu.

Zakładki statusów w DataGrid

W nagłówku tabel DataGrid dostępne są zakładki szybkiego przełączania widoków:

• Widoczne (1) – domyślny widok aktywnych rekordów.
• Zarchiwizowane (2) – rekordy przeniesione do archiwum.
• Kosz (3) – rekordy usunięte miękko z możliwością ich przywrócenia.
• Ukryte (0) – widoczne wyłącznie na koncie Superusera.