Core — Wspólne Master Data & RBAC

Cel: Ujednolicona przestrzeń dla wspólnych zasobów master data i zarządzania dostępem opartego na rolach (RBAC) wspólnych dla wszystkich modułów API.ERP (księgowość, kadry, magazyn, majątek, CRM itp.).

Zasoby Master Data (współdzielone między modułami)

Te zasoby nie są izolowane – każdy moduł API z nich korzysta, aby zachować autonomię API:

Zasób	Cel	Używane przez
Party	Jednostka (organizacja, osoba) – dostawcy, klienci, pracownicy, dysponenci majątku	księgowość, kadry, magazyn, majątek, CRM
PartyRole	Party w roli (klient, dostawca, płatnik, pracownik itp.)	księgowość, kadry, magazyn, CRM
PartyRelationship	Relacja między dwoma PartyRole (pracodawca–pracownik, przełożony–podwładny)	kadry
Location	Miejsce fizyczne – magazyn, miejsce składowania, miejsce użytkowania, biuro	magazyn, majątek, kadry
ValueSet	Słowniki kodów – wspólne z pakietu terminologii i wdrożeniowe	wszystkie
NamingSystem	Przestrzenie identyfikatorów instalacji – klucz, faktyczny `system`, klucz referencyjny	wszystkie

Zasoby RBAC (Role-Based Access Control)

Międzymodułowy model autoryzacji:

Zasób	Cel	Używane przez
Capability	Pojedyncze uprawnienie (zdolność, akcja) – katalog kodów uprawnień	kadry
GrantAssignment	Przypisanie uprawnień (przypisuje Capability stronie w roli, w zakresie i w czasie)	kadry

Struktura Modelu Danych

Hierarchia Master Data

Party (dostawca, klient, pracownik, dysponent majątku)
  ├─ partOf (strona nadrzędna – hierarchia organizacji)
  ├─ PartyRole (party w roli: klient, dostawca, płatnik, pracownik itp.)
  │  └─ PartyRelationship (relacja między dwoma rolami)
  └─ contained: BankAccount (rachunki kontrahenta)

Location (magazyn, miejsce składowania, miejsce użytkowania, biuro)
  ├─ managingParty / owner → Party (zarządca, właściciel)
  └─ partOf (lokalizacja nadrzędna)

Hierarchia RBAC

Capability (pojedyncze uprawnienie: kod uprawnienia + nazwa)
  └─ przypisane przez GrantAssignment

GrantAssignment (kto → capability, dla jakiego scope, kiedy)
  ├─ assignedTo: Party, PartyRole, Position, OrganizationUnit
  ├─ granted: [Capability]
  ├─ scope: PartyRole, OrganizationUnit, Position
  ├─ period: start, end
  ├─ basis, givenBy
  └─ attribute: direct-only, employment-id, order-path

Endpointy API (Wszystkie Moduły)

Odczyt zwraca kopertę { "items": [...], "nextToken": null } stronicowaną parametrami count/offset; filtry mają postać system|value. Brak tras z {id} – zasób wskazuje się parametrem identifier.

Master Data:

GET   /v1/parties               — Wylicz strony (profile, type, identifier, owner, attribute, status, lastModified)
POST  /v1/parties               — Utwórz stronę (profil Contractor); odpowiedź 200
PATCH /v1/parties?identifier=system|value&owner=https://gov.pl/nip|<NIP> — Zaktualizuj stronę; odpowiedź 200

GET   /v1/party-roles           — Wylicz role stron (role wymagany, party, profile)
GET   /v1/party-relationships   — Wylicz relacje (type wymagany, partyFrom, partyTo, attribute)
GET   /v1/locations             — Wylicz lokalizacje (profile, identifier, owner, attribute, contained, type, category)
GET   /v1/value-sets            — Lista słowników albo treść słownika (url)
GET   /v1/naming-systems        — Przestrzenie identyfikatorów instalacji (usage)

RBAC:

GET   /v1/capabilities          — Wylicz uprawnienia (identifier)
GET   /v1/grant-assignments     — Wylicz przypisania (assignedTo, granted, basedOn, scope, attribute)

PartyRole, PartyRelationship, Location, ValueSet, NamingSystem, Capability i GrantAssignment są tylko do odczytu.

Zasady Projektowania

Współdzielone Master Data – zasoby master data są dostępne w API każdego modułu (księgowość, kadry, magazyn, majątek), aby utrzymać autonomię API; brak zależności runtime między modułami
Dziedziczenie DomainResource – wszystkie zasoby rozszerzają DomainResource (wzór FHIR): id, resourceType, meta, owner[], comment, category[], status, type, contained[], attribute[]; identifier[] deklarują zasoby, które je mają
Identifier + CodeableConcept – wielosystemowa identyfikacja i wspólna terminologia
Międzymodułowy RBAC – jeden model autoryzacji wspólny dla wszystkich modułów; Capability jest niezależna od dziedziny
Przypisania w czasie – GrantAssignment wspiera period (start–end) dla delegacji, czasowego podwyższenia uprawnień i compliance

Kluczowe Scenariusze

Scenariusz 1: Uprawnienie przełożonego względem podwładnych

Przełożony (PartyRole employee-1001)
  → granted: Capability <kod uprawnienia>
  → scope: PartyRole employee-2002 (podwładny)
  → attribute: direct-only = 1, employment-id = 5005

Scenariusz 2: Odczyt uprawnień pracownika

GET /v1/grant-assignments?assignedTo=<przestrzeń Party>|1001
  → wszystkie przypisania pracownika 1001 z katalogu kadrowego

Scenariusz 3: Kto ma uprawnienie względem pracownika

GET /v1/grant-assignments?scope=<przestrzeń Party>|2002&granted=<przestrzeń Capability>|<kod>
  → przełożeni pracownika 2002 z danym uprawnieniem

Przypadki Użycia per Moduł

Kadry

Capability: katalog kodów uprawnień kadrowych (wartości nadaje wdrożenie)
GrantAssignment: pracownik w roli → uprawnienie względem podwładnych, z powiązaniem do zatrudnienia

Księgowość

Party w profilu Contractor (kontrahent) z rachunkami bankowymi w contained; zapis przez POST/PATCH /v1/parties

Magazyn

Location w profilach Warehouse i StorageLocation; hierarchia przez partOf, zarządca przez managingParty

Majątek

Party w profilu AssetHolder (dysponent), Location w profilu UsagePlace (miejsce użytkowania)

Model danych — 2 warstwy RBAC

┌─────────────────────────────────────────────────────────┐
│ Warstwa 1: Katalog uprawnień                            │
│ ┌───────────────────────────────────────────────────┐   │
│ │ Capability                                        │   │
│ │ • identifier: kod uprawnienia (capability-code)   │   │
│ │ • name: nazwa                                     │   │
│ │ • description, validFrom/validTo (opcjonalne)     │   │
│ └───────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                           ▲
                           │ przypisane przez
                           │
┌─────────────────────────────────────────────────────────┐
│ Warstwa 2: Przypisanie                                  │
│ ┌───────────────────────────────────────────────────┐   │
│ │ GrantAssignment                                   │   │
│ │ • assignedTo: Reference(Party/PartyRole/Position) │   │
│ │ • granted[]: Reference(Capability)                │   │
│ │ • scope[]: Reference(PartyRole/OrganizationUnit)  │   │
│ │ • period: start, end                              │   │
│ │ • basis, givenBy                                  │   │
│ └───────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Wspólna Terminologia

Termin	Definicja
Capability	Pojedyncze uprawnienie, zdolność lub akcja identyfikowana kodem uprawnienia
GrantAssignment	Przypisanie Capability do Party, PartyRole, Position lub OrganizationUnit, w zakresie i w czasie
Scope	Kontekst (strona w roli, jednostka organizacyjna, stanowisko), do którego przypisanie się stosuje
Period	start + end (opcjonalnie; brak końca = bez wygaśnięcia)
Basis	Podstawa przypisania (CodeableConcept; kody nadaje wdrożenie)

Standardy & Wzory

Dziedziczenie DomainResource — Capability i GrantAssignment rozszerzają DomainResource
Identifier + CodeableConcept — Wielosystemowe identyfikatory i wspólna terminologia
Reference — Linki między zasobami (GrantAssignment → Capability/PartyRole)
Attribute — Typowane pola dodatkowe (np. direct-only, employment-id)
Period — Przypisania ograniczone w czasie (start, end)

Zasoby powiązane

→ docs/Resources/Core/Capability.md
→ docs/Resources/Core/GrantAssignment.md
→ Identyfikacja i parametry wdrożenia