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 (FK, HR, WMS, CRM, itp.).

Zasoby Master Data (Rozproszone Across Modułów)

Te zasoby nie są izolowane – każdy API modułu je zawiera, aby zachować autonomię API:

Zasób	Cel	Używane przez
Party	Jednostka (organizacja, osoba) – dostawcy, klienci, pracownicy, magazyny	FK, HR, WMS, CRM
PartyRole	Party w roli (klient, dostawca, płatnik, pracownik, itp.)	FK, HR, WMS, CRM
PartyRelationship	Relacja między dwoma PartyRole (klient–dostawca, pracodawca–pracownik)	FK, HR, WMS, CRM
Location	Miejsce fizyczne – strefa magazynu, biuro, budynek, pojemnik	FK, HR, WMS

Zasoby RBAC (Role-Based Access Control)

Cross-modul model autoryzacji:

Zasób	Cel	Używane przez
Capability	Pojedyncze uprawnienie (zdolność, akcja) – np. „ZatwierdzFakturę", „PrzyjmijTowary", „ZatwierdzUrop"	FK, HR, WMS, CRM
GrantAssignment	Przypisanie uprawnień (przypisuje Capability/Duty do Party, Position, OrganizationUnit, scoped i time-bounded)	FK, HR, WMS, CRM

Struktura Modelu Danych

Hierarchia Master Data

Party (dostawca, klient, pracownik, magazyn)
  ├─ PartyRole (party w roli: klient, dostawca, płatnik, pracownik, itp.)
  │  └─ PartyRelationship (relacja między dwoma rolami)
  ├─ Locations zarządzane przez party
  └─ Group membership (grupa klientów, grupa pracowników, itp.)

Location (magazyn, biuro, budynek, pojemnik)
  ├─ PartyRole (manager lokalizacji, właściciel)
  └─ partOf hierarchy (lokalizacja nadrzędna)

Hierarchia RBAC

Capability (pojedyncze uprawnienie: "zatwierdzenie-faktury", "wydaj-towary")
  └─ przypisane przez GrantAssignment

GrantAssignment (kto → duty/capability, dla jakiego scope, kiedy)
  ├─ assignedTo: Party, PartyRole, Position, OrganizationUnit
  ├─ granted: [Duty, Capability]
  ├─ scope: OrganizationUnit, Party, Position
  └─ period: effectiveDate, expiryDate

Endpointy API (Wszystkie Moduły)

Master Data:

GET /v1/parties — Wylicz parties
POST /v1/parties — Utwórz party
PATCH /v1/parties/{id} — Zaktualizuj party

GET /v1/parties/{id}/party-roles — Pobierz role party
GET /v1/party-roles — Wylicz party roles
POST /v1/party-roles — Przypisz rolę

GET /v1/party-relationships — Wylicz relacje
POST /v1/party-relationships — Utwórz relację

GET /v1/locations — Wylicz lokalizacje
POST /v1/locations — Utwórz lokalizację
PATCH /v1/locations/{id} — Zaktualizuj lokalizację

RBAC:

GET /v1/capabilities — Wylicz uprawnienia
POST /v1/capabilities — Utwórz uprawnienie
PATCH /v1/capabilities/{id} — Zaktualizuj uprawnienie

GET /v1/grant-assignments — Wylicz przypisania (filtruj po assignedTo, scope, grantedCapability)
POST /v1/grant-assignments — Utwórz przypisanie
PATCH /v1/grant-assignments/{id} — Zaktualizuj przypisanie (przedłuż okres, itp.)
DELETE /v1/grant-assignments/{id} — Wycofaj przypisanie

Zasady Projektowania

Rozproszone Master Data – zasoby master data są zawarte w API każdego modułu (FK, HR, WMS, CRM), aby utrzymać autonomię API; żadnych cross-modul runtime dependencies
DomainResource Inheritance – wszystkie zasoby rozszerzają DomainResource (wzór FHIR): id, meta, identifier[], status, type, attribute[], reference[]
Identifier + CodeableConcept – wielosystemowa identyfikacja i wspólna terminologia
Cross-Modul RBAC – einzelny model autoryzacji wspólny dla wszystkich modułów; Capability i Duty są domain-agnostic
Time-Bounded Assignments – GrantAssignment wspiera period (effective–expiry dates) dla delegacji, times elevation, i compliance

Kluczowe Scenariusze

Scenariusz 1: Multi-Level Organizational Approval Hierarchy

Alice (CEO): Duty "CFO" → zatwierdź wszystkie faktury
┠─ Bob (Dyrektor Finansów): Duty "Finance Manager" → zatwierdź faktury €5k–€50k per dept
┠─ Charlie (Księgowy): Duty "Accountant" → zatwierdź faktury €500–€5k
└─ Diana: Capability "expense-approval" (≤ €1k)

Scenariusz 2: WMS Operations

Frank (Pracownik Magazynu): Capability "confirm-goods-receipt" + "issue-goods"
  └─ Scope: Location "Central Warehouse Zone A"

Scenariusz 3: Temporary Delegation (Acting Manager)

Grace (Manager) → Delegowana Duty "Team Lead" 
  └─ Period: 2026-02-01 do 2026-02-28 (nieobecność managera)
  └─ Basis: delegation
  └─ Scope: Department "Sales"

Przypadki Użycia per Moduł

HR (Human Resources)

Capability: "ApproveLeave", "ApproveExpenseReport", "SubmitTimesheet"
Duty: "HR Manager" = [ApproveLeave, ApproveExpenseReport, ManageEmployeeData]
GrantAssignment: "Alice" posiadała Duty "HR Manager" dla Department "HR" od 2026-01-01

FK (Finance-Accounting)

Capability: "ApproveInvoice", "PostToGeneralLedger", "ExportMainBook", "ViewBankAccount"
Duty: "Finance Manager (Invoicing)" = [ApproveInvoice, PostToGL, ExportMainBook]
GrantAssignment: "Bob" posiadał Duty "Finance Manager (Invoicing)" dla "Finance Dept", może zatwierdzać faktury do €10.000

WMS (Warehouse)

Capability: "ConfirmGoodsReceipt", "IssueGoods", "AdjustInventory", "CreateTransfer"
Duty: "Warehouse Manager" = [ConfirmReceipt, IssueGoods, AdjustInventory, CreateTransfer]
GrantAssignment: "Charlie" posiadał Duty "Warehouse Manager" dla "Central Warehouse", effectiveDate 2026-01

CRM / Order-to-Cash

Capability: "CreateSalesOrder", "ConfirmDelivery", "ReceivePayment"
Duty: "Sales Manager" = [CreateSalesOrder, ConfirmDelivery]
GrantAssignment: "Diana" posiadała Duty "Sales Manager" dla "Region A", może tworzyć ZS do €50.000

Data Model — 3-Layer RBAC

┌─────────────────────────────────────────────────────────┐
│ Layer 1: Capability Catalog                            │
│ ┌───────────────────────────────────────────────────┐   │
│ │ Capability (permission/ability)                   │   │
│ │ • identifier: "approve-expense"                   │   │
│ │ • name: "Approve Expense Report"                  │   │
│ │ • type: "approval"                                │   │
│ │ • description: "Can approve expense reports up to" │   │
│ │ • validFrom/To: date range (optional)             │   │
│ └───────────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘
                           ▲
                           │ used by
                           │
┌─────────────────────────────────────────────────────────┐
│ Layer 2: Duty (Role) Definition                         │
│ ┌───────────────────────────────────────────────────┐   │
│ │ Duty (role/profile)                               │   │
│ │ • identifier: "finance-manager"                   │   │
│ │ • name: "Finance Manager"                         │   │
│ │ • type: "job-role"                                │   │
│ │ • capabilities[]: [                               │   │
│ │    -> Capability: "approve-invoice",              │   │
│ │    -> Capability: "post-gl-entry",                │   │
│ │    -> Capability: "export-mainbook"               │   │
│ │   ]                                               │   │
│ └───────────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘
                           ▲
                           │ assigned via
                           │
┌─────────────────────────────────────────────────────────┐
│ Layer 3: Grant Assignment                               │
│ ┌───────────────────────────────────────────────────┐   │
│ │ GrantAssignment (permission grant)                │   │
│ │ • assignedTo: Reference(Party/PartyRole/Position) │   │
│ │ • granted[]: [                                    │   │
│ │    -> Duty: "finance-manager",                    │   │
│ │    -> Capability: "exception-approval"            │   │
│ │   ]                                               │   │
│ │ • scope: Reference(Organization, Department)     │   │
│ │ • effectiveDate: 2026-01-01                       │   │
│ │ • expiryDate: 2026-12-31                          │   │
│ │ • basis: "appointment", "delegation", "promotion" │   │
│ │ • basedOn: Reference(Document/Employment)         │   │
│ └───────────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘

Use Cases by Module

HR (Human Resources)

Capability: "ApproveLeave", "ApproveExpenseReport", "SubmitTimesheet"
Duty: "HR Manager" = [ApproveLeave, ApproveExpenseReport, ManageEmployeeData]
GrantAssignment: "Alice" held Duty "HR Manager" for Department "HR" from 2026-01-01

FK (Finance-Accounting)

Capability: "ApproveInvoice", "PostToGeneralLedger", "ExportMainBook", "ViewBankAccount"
Duty: "Finance Manager (Invoicing)" = [ApproveInvoice, PostToGL, ExportMainBook]
GrantAssignment: "Bob" held Duty "Finance Manager (Invoicing)" for "Finance Dept", can approve invoices up to €10,000

WMS (Warehouse)

Capability: "ConfirmGoodsReceipt", "IssueGoods", "AdjustInventory", "CreateTransfer"
Duty: "Warehouse Manager" = [ConfirmReceipt, IssueGoods, AdjustInventory, CreateTransfer]
GrantAssignment: "Charlie" held Duty "Warehouse Manager" for "Central Warehouse", effective 2026-01

CRM / Order-to-Cash

Capability: "CreateSalesOrder", "ConfirmDelivery", "ReceivePayment"
Duty: "Sales Manager" = [CreateSalesOrder, ConfirmDelivery]
GrantAssignment: "Diana" held Duty "Sales Manager" for "Region A", can create SOs up to €50,000

Egzanuplowanie Multi-Modul: Budget Approval Hierarchy

Organizacja:
  - HQ (Dyrektor: Alice)
    - Finance Dept (Manager: Bob)
      - Accounting (Lead: Charlie)
      - Treasury (Lead: Diana)
    - HR Dept (Manager: Eve)
      - Recruiting (Coordinator: Frank)

GrantAssignments:
  1. Alice → Duty "CFO"
     • Scope: HQ
     • Granted: [ApproveExpense >€50k, EmergencyProcurement, ApprovePayroll]

  2. Bob → Duty "Finance Manager"
     • Scope: Finance Dept
     • Granted: [ApproveExpense €5k–€50k, ApproveInvoice, PostToGL]

  3. Charlie → Duty "Accountant"
     • Scope: Accounting team
     • Granted: [Capability "ApproveExpense <€5k", Duty "Accountant"]

  4. Eve → Duty "HR Manager"
     • Scope: HR Dept
     • Granted: [ApproveLeave, ApproveExpenseReport, ManageEmployeeData]

  5. Frank → Capability "RecruitmentCoordinator"
     • Scope: HR Dept / Recruiting
     • Granted: [PostJobOffer, ScheduleInterview]

Approval Workflow (Purchase Requisition):
  - Frank (Recruiting) przesyła PurchaseRequisition (e.g., €3k office supplies)
    → Scope: Recruiting team
    → Route do Eve (HR Manager, via GrantAssignment #4, może zatwierdzić HR expensesе)
    → Eve zatwierdza → Charlie (Accountant, via GrantAssignment #3) postuje do GL

Migracja z HR do Core

Przed (HR-only):

docs/Resources/HR/
  Capability.md
  Duty.md
  GrantAssignment.md

Po (Core RBAC):

docs/Resources/Core/
  Capability.md
  GrantAssignment.md
  README.md (ten plik)

docs/Resources/HR/
  → Referencje do Core resources (bez dupliacji)

API Specs: - API-ERP-Canonical-EOD.yaml — zawiera /v1/capabilities, /v1/grant-assignments - API-ERP-Canonical-WMS.yaml — zawiera /v1/capabilities, /v1/grant-assignments - API-ERP-Canonical-HR.yaml — zawiera /v1/capabilities, /v1/grant-assignments

Wspólna Terminologia

Termin	Definicja
Capability	Pojedyncze uprawnienie, zdolność lub akcja (np. „ApproveInvoice", „IssueGoods")
GrantAssignment	Przypisanie Capability do Party, PartyRole, Position lub OrganizationUnit, scoped i time-bounded
Scope	Kontekst (Organization, Department, Team, Warehouse), do którego przypisanie się stosuje
Period	effectiveDate + expiryDate (opcjonalnie; null = bez wygaśnięcia)
Basis	Powód przypisania (np. „appointment", „delegation", „promotion", „temporary-authorization")

Standardy & Wzory

DomainResource inheritance — Capability i GrantAssignment rozszerzają DomainResource
Identifier + CodeableConcept — Wielosystemowe IDs i wspólna terminologia
Reference — Linki między zasobami (GrantAssignment → Capability/Party)
Attribute — Typed custom fields (np. approve limits, cost centers)
Period — Time-bounded assignments (effectiveDate, expiryDate)

Zasoby powiązane

→ docs/Resources/Core/Capability.md → docs/Resources/Core/GrantAssignment.md → Przykłady workflow'ów RBAC: sekcje demonstracyjne w dokumentacji Core