Organizacje (Organization)¶

Ostatnia aktualizacja dokumentacji: 26 lutego 2026 Stan synchronizacji z kodem: Zsynchronizowany

Jednostki zarządzające obiektami — szkoły, MOSiR-y, domy kultury i inne instytucje publiczne.

1. Opis ogólny¶

Domena Organizacji zarządza jednostkami odpowiedzialnymi za obiekty i zajęcia w systemie rezerwacji. To jak struktura organizacyjna gminy — każda szkoła, ośrodek sportowy czy dom kultury to osobna organizacja, która ma swoje obiekty, pracowników i rezerwacje.

System obsługuje 22 typy organizacji (od szkół po parki i kluby sportowe) i umożliwia przypisywanie pracowników, zarządzanie stanem aktywności oraz kaskadowe propagowanie zmian na powiązane encje.

Jakie problemy rozwiązuje?¶

2. Architektura domeny¶

2.1 Modele danych¶

Model Organization¶

• Plik: app/Domain/Organization/Model/Organization.php
• Tabela: organizations
• Klucz główny: UUID (trait HasUuids, $incrementing = false, $keyType = 'string')
• Bazowy model: Infrastructure\Vendor\CustomModel
• Traity: TraitOrganization, TraitSupport
• Observer: OrganizationObserver (atrybut #[ObservedBy])

Pola fillable (17):

Atrybuty wyliczane (accessory):

Relacje (7 × HasMany):

Filtry publiczne (query builder): id, type, name, city, commune, district, voivodeship

Model OrganizationEmployee¶

• Plik: app/Domain/Organization/Model/OrganizationEmployee.php
• Tabela: organization_employees
• Klucz główny: UUID (trait HasUuids)
• Observer: OrganizationEmployeeObserver (atrybut #[ObservedBy])
• Rola: Model pośredni (junction table) łączący User z Organization

Pola fillable (2):

Relacje (2 × BelongsTo):

Filtry publiczne: id, organization_id, user_id, organization.type, user.name, organization.nip, organization.regon, organization.name, created_at

2.2 Diagram relacji¶

erDiagram
    ORGANIZATION ||--o{ ORGANIZATION_EMPLOYEE : "ma pracowników"
    USER ||--o{ ORGANIZATION_EMPLOYEE : "pracuje w"
    ORGANIZATION ||--o{ ITEM : "posiada obiekty"
    ORGANIZATION ||--o{ ACTIVITY : "prowadzi zajęcia"
    ORGANIZATION ||--o{ SCHEDULE : "ma harmonogramy"
    ORGANIZATION ||--o{ RESERVATION : "ma rezerwacje"
    ORGANIZATION ||--o{ REVIEW : "ma opinie"
    ORGANIZATION ||--o{ COMPLAINT : "ma reklamacje"

    ORGANIZATION {
        uuid id PK
        enum type
        string nip UK
        string regon UK
        string name
        string email
        boolean is_active
    }

    ORGANIZATION_EMPLOYEE {
        uuid id PK
        uuid organization_id FK
        uuid user_id FK
    }

2.3 Struktura tabel w bazie danych¶

Migracja: database/migrations/0001_01_01_000014_create_organizations.php

Tabela organizations¶

Tabela organization_employees¶

Constrainty:

• UNIQUE (organization_id, user_id) — ten sam użytkownik nie może być dwukrotnie przypisany do tej samej organizacji
• FK organization_id → organizations.id ON DELETE CASCADE
• FK user_id → users.id ON DELETE CASCADE

3. Endpointy API¶

3.1 Organizacje¶

GET /api/organizations¶

• Opis: Lista organizacji z paginacją i filtrowaniem
• Autoryzacja: Publiczny (dostępny bez logowania) + wersja autentykowana
• Query Parameters:
  • filter[id] — filtr exact po UUID
  • filter[type] — filtr exact po typie organizacji
  • Standardowe parametry paginacji (page, per_page, sort)
• Response (sukces): 200 OK

  {
    "data": [
      {
        "id": "uuid",
        "type": "school",
        "type_lang": "Szkoła",
        "nip": "1234567890",
        "regon": "123456789",
        "name": "Szkoła Podstawowa nr 1",
        "email": "szkola1@example.com",
        "mobile_phone": "123456789",
        "stationary_phone": null,
        "street": "ul. Szkolna",
        "street_number": "1",
        "postal_code": "00-001",
        "city": "Warszawa",
        "commune": "Warszawa",
        "district": "Warszawa",
        "voivodeship": "mazowieckie",
        "teryt_data": [],
        "is_active": true,
        "created_at": "2026-01-15 10:00:00",
        "updated_at": "2026-01-15 10:00:00",
        "can_be_edit": true,
        "total_items": 5,
        "total_activities": 3,
        "total_employees": 2,
        "total_reviews": 10,
        "avg_reviews": 4.25,
        "can": {}
      }
    ],
    "meta": { "...paginacja..." }
  }
  

• Uwaga: Dla niezalogowanych użytkowników pola can_be_edit, total_items, total_activities, total_employees, is_in_use i can nie są zwracane

GET /api/organizations/{organizationId}¶

• Opis: Szczegóły jednej organizacji
• Autoryzacja: Publiczny (dostępny bez logowania) + wersja autentykowana
• Parametry URL: organizationId — UUID organizacji
• Response (sukces): 200 OK — struktura jak w index, pojedynczy obiekt
• Response (błędy):
  • 404 Not Found — organizacja nie istnieje (NotFoundModelException)

POST /api/organizations¶

• Opis: Utworzenie nowej organizacji
• Autoryzacja: Rola ADMIN (middleware) + Policy create (zawsze false — blokowane przez policy, dostęp tylko dla ADMIN przez before() w BasePolicy)
• Body (Request): StoreOrganizationControllerRequest

  {
    "type": "required|string|in:municipality,school,...(22 wartości)",
    "nip": "required|digits:10|unique:organizations,nip|ValidCorrectNIPRule",
    "regon": "required|string|regex:/^[0-9]+$/|unique:organizations,regon|ValidCorrectRegonRule",
    "name": "required|string|max:500",
    "email": "required|email|max:255",
    "mobile_phone": "required|regex:/^([0-9\\s\\-\\+\\(\\)]{6,20})$/",
    "stationary_phone": "nullable|sometimes|regex:/^([0-9\\s\\-\\+\\(\\)]{6,20})$/",
    "street": "required|string|max:255",
    "street_number": "required|string|max:50",
    "postal_code": "required|regex:/^[0-9]{2}-[0-9]{3}$/",
    "city": "required|string|max:255",
    "commune": "required|string|max:255",
    "district": "required|string|max:255",
    "voivodeship": "required|string|max:255",
    "teryt_data": "required|array",
    "teryt_data.*": "string|max:255"
  }
  

• Response (sukces): 200 OK

  {
    "message": "The Organization has been successfully added",
    "status": 200,
    "error": false
  }
  

• Reguły walidacji dodatkowe:
  • ValidCorrectNIPRule — walidacja sumy kontrolnej NIP
  • ValidCorrectRegonRule — walidacja sumy kontrolnej REGON
  • NIP i REGON muszą być unikalne w tabeli organizations

PATCH /api/organizations/{organizationId}¶

• Opis: Aktualizacja danych organizacji
• Autoryzacja: Rola ADMIN lub SUPERVISOR (middleware) + Policy update (supervisor musi należeć do organizacji)
• Parametry URL: organizationId — UUID organizacji
• Body (Request): UpdateOrganizationControllerRequest

  {
    "type": "sometimes|nullable|string|in:...(22 wartości)",
    "nip": "sometimes|nullable|digits:10|unique:organizations,nip,{organizationId}|ValidCorrectNIPRule",
    "regon": "sometimes|nullable|string|regex:/^[0-9]+$/|unique:organizations,regon,{organizationId}|ValidCorrectRegonRule",
    "name": "sometimes|nullable|string|max:500",
    "email": "sometimes|nullable|email|max:255",
    "mobile_phone": "sometimes|nullable|regex:/^([0-9\\s\\-\\+\\(\\)]{6,20})$/",
    "stationary_phone": "sometimes|nullable|regex:/^([0-9\\s\\-\\+\\(\\)]{6,20})$/",
    "...reszta pól adresowych z 'sometimes|nullable'..."
  }
  

• Response (sukces): 200 OK

  {
    "message": "The Organization has been successfully updated",
    "status": 200,
    "error": false
  }
  

• Reguły biznesowe: Reguła unique dla NIP/REGON ignoruje aktualny rekord (parametr ignore($this->route('organizationId')))

PATCH /api/organizations/{organizationId}/change-state¶

• Opis: Przełączenie stanu aktywności organizacji (is_active)
• Autoryzacja: Rola ADMIN (middleware) + Policy update
• Parametry URL: organizationId — UUID organizacji
• Body: Brak — stan jest przełączany automatycznie (toggle)
• Response (sukces): 200 OK
• Efekty uboczne: Kaskadowa zmiana stanu na powiązanych obiektach (zobacz sekcję Kaskadowa dezaktywacja)

3.2 Pracownicy organizacji¶

GET /api/organization-employees¶

• Opis: Lista pracowników organizacji z paginacją i filtrowaniem
• Autoryzacja: Publiczny (dostępny bez logowania) + wersja autentykowana
• Query Parameters:
  • filter[id] — exact po UUID
  • filter[organization_id] — exact po organizacji
  • filter[user_id] — exact po użytkowniku
  • filter[organization.type] — exact po typie organizacji
  • filter[user.name] — partial po nazwie użytkownika
  • filter[organization.nip] — partial po NIP
  • filter[organization.regon] — partial po REGON
  • filter[organization.name] — partial po nazwie organizacji
  • Standardowe parametry paginacji
• Response (sukces): 200 OK

  {
    "data": [
      {
        "id": "uuid",
        "organization_id": "uuid",
        "user_id": "uuid",
        "can_be_edit": true,
        "created_at": "2026-01-15 10:00:00",
        "updated_at": "2026-01-15 10:00:00",
        "can": {},
        "organization": { "...dane organizacji..." },
        "user": { "...dane użytkownika..." }
      }
    ]
  }
  

• Relacje eager-loaded: organization, user
• Uwaga: Dla niezalogowanych pola can nie jest zwracane

POST /api/organization-employees¶

• Opis: Przypisanie pracownika do organizacji
• Autoryzacja: Rola ADMIN (middleware) + Policy create (zawsze false — dostęp przez BasePolicy::before())
• Body (Request): StoreOrganizationEmployeeControllerRequest

  {
    "organization_id": "required|uuid|exists:organizations,id",
    "user_id": "required|uuid|exists:users,id|UniqueOrganizationEmployeeRule"
  }
  

• Response (sukces): 200 OK

  {
    "message": "The Organization Employee has been successfully added",
    "status": 200,
    "error": false
  }
  

• Reguły walidacji:
  • UniqueOrganizationEmployeeRule — sprawdza czy użytkownik nie jest już pracownikiem tej organizacji
  • organization_id musi istnieć w tabeli organizations
  • user_id musi istnieć w tabeli users
• Efekty uboczne: Powiadomienie email do nowego pracownika (OrganizationEmployeeCreatedNotification)

DELETE /api/organization-employees/{organizationEmployeeId}¶

• Opis: Usunięcie pracownika z organizacji
• Autoryzacja: Rola ADMIN (middleware) + Policy update (zawsze false — dostęp przez BasePolicy::before())
• Parametry URL: organizationEmployeeId — UUID powiązania pracownik-organizacja
• Response (sukces): 200 OK

  {
    "message": "The Organization Employee was deleted successfully",
    "status": 200,
    "error": false
  }
  

• Response (błędy):
  • 404 Not Found — powiązanie nie istnieje (NotFoundModelException)
• Efekty uboczne:
  1. Usunięcie uprawnień managera obiektów dla tego pracownika w tej organizacji (DeleteEmployeeItemManagers)
  2. Powiadomienie email do pracownika (OrganizationEmployeeDeletedNotification)

4. Logika biznesowa¶

4.1 Główne procesy¶

Tworzenie organizacji¶

flowchart LR
    A[Request POST] --> B[Walidacja\nStoreOrganizationControllerRequest]
    B --> C[Sprawdzenie roli ADMIN]
    C --> D[Policy: create]
    D --> E[CreateOrganization\n__invoke]
    E --> F[Organization::create]
    F --> G[Odpowiedź 200]

1. Request przechodzi walidację (typ, NIP z sumą kontrolną, REGON z sumą kontrolną, dane adresowe)
2. Middleware sprawdza rolę ADMIN
3. Policy create (w BasePolicy::before() admin ma pełen dostęp)
4. Klasa CreateOrganization wywołuje Organization::create($validated)
5. Zwraca komunikat sukcesu

Przypisanie pracownika¶

flowchart TD
    A[Request POST] --> B[Walidacja]
    B --> C{Czy user już\njest pracownikiem?}
    C -->|Tak| D[Błąd 422:\nUniqueOrganizationEmployeeRule]
    C -->|Nie| E[CreateOrganizationEmployee]
    E --> F[OrganizationEmployee::create]
    F --> G[Observer: created]
    G --> H[SimpleSendNotificationJob]
    H --> I[Email:\nPrzypisanie do organizacji]

Usunięcie pracownika¶

flowchart TD
    A[Request DELETE] --> B[Znalezienie rekordu]
    B --> C{Istnieje?}
    C -->|Nie| D[404 NotFoundModelException]
    C -->|Tak| E[delete]
    E --> F[Observer: deleting]
    F --> G[DeleteEmployeeItemManagers\nUsunięcie uprawnień managera]
    E --> H[Observer: deleted]
    H --> I[SimpleSendNotificationJob]
    I --> J[Email:\nUsunięcie z organizacji]

4.2 Reguły biznesowe¶

1. NIP musi być unikalny — każda organizacja ma inny NIP, walidowany sumą kontrolną (ValidCorrectNIPRule)
2. REGON musi być unikalny — walidowany sumą kontrolną (ValidCorrectRegonRule)
3. Pracownik nie może być przypisany dwukrotnie — tabela ma constraint UNIQUE(organization_id, user_id) + walidacja UniqueOrganizationEmployeeRule
4. Dezaktywacja kaskaduje — zmiana is_active propaguje się na wszystkie powiązane obiekty (przez organization_id)
5. Usunięcie pracownika czyści uprawnienia managera — ItemManager powiązane z pracownikiem i organizacją są kasowane
6. Supervisor może edytować tylko swoją organizację — Policy update wymaga przynależności do organizacji
7. Usunięcie organizacji kaskaduje na pracowników — ON DELETE CASCADE na foreign key
8. Usunięcie użytkownika kaskaduje na powiązania — ON DELETE CASCADE na foreign key user_id
9. Asynchroniczna kaskada dla dużych organizacji — jeśli >50 obiektów, zmiana stanu realizowana jest przez job na kolejce

4.3 Walidacje¶

Tworzenie organizacji (StoreOrganizationControllerRequest)¶

Aktualizacja organizacji (UpdateOrganizationControllerRequest)¶

Identyczne pola jak przy tworzeniu, ale z sometimes|nullable zamiast required. Reguły unique dla NIP/REGON ignorują bieżący rekord (ignore($this->route('organizationId'))).

Przypisanie pracownika (StoreOrganizationEmployeeControllerRequest)¶

5. Autoryzacja i uprawnienia¶

Middleware (w konstruktorze kontrolera)¶

Policy OrganizationPolicy¶

Policy OrganizationEmployeePolicy¶

Macierz uprawnień¶

6. Eventy i efekty uboczne¶

Łańcuch observerów¶

flowchart TD
    subgraph "Organization updated"
        A1[OrganizationObserver::updated] --> A2[UpdatedOrganizationObserver]
        A2 --> A3[UpdatedIsActiveOrganizationObserver]
        A3 --> A4{is_active changed?}
        A4 -->|Tak| A5{total_items > 50?}
        A5 -->|Tak| A6[ChangeStateAllObjectModelsJob\nkolejka: domain]
        A5 -->|Nie| A7[changeStateAllObjectModels\nsynchronicznie]
        A4 -->|Nie| A8[Brak akcji]
    end

    subgraph "OrganizationEmployee created"
        B1[OrganizationEmployeeObserver::created] --> B2[SimpleSendNotificationJob]
        B2 --> B3[OrganizationEmployeeCreatedNotification\nemail]
    end

    subgraph "OrganizationEmployee deleting"
        C1[OrganizationEmployeeObserver::deleting] --> C2[DeletingOrganizationEmployeeObserver]
        C2 --> C3[DeleteEmployeeItemManagers]
        C3 --> C4[Usunięcie ItemManager\ndla user_id + organization_id]
    end

    subgraph "OrganizationEmployee deleted"
        D1[OrganizationEmployeeObserver::deleted] --> D2[SimpleSendNotificationJob]
        D2 --> D3[OrganizationEmployeeDeletedNotification\nemail]
    end

Klasy Action/Other¶

7. Powiadomienia¶

Obie notyfikacje są wysyłane asynchronicznie przez SimpleSendNotificationJob z kolejki powiadomień.

8. Powiązania z innymi domenami¶

9. Konfiguracja¶

Domena Organization nie posiada dedykowanych parametrów konfiguracyjnych w domains/configuration.md. Kluczowe stałe:

• Próg asynchronicznej kaskady: 50 obiektów (UpdatedIsActiveOrganizationObserver — jeśli organizacja ma >50 items, zmiana stanu trafia na kolejkę domain)
• Kolejka dla kaskady: SupportEnumService::ON_QUEUE_DOMAIN
• Typy organizacji: 22 wartości zdefiniowane w OrganizationEnumService (nie konfigurowane — hardcoded w enum)

10. Znane ograniczenia i TODO¶

1. Brak softDelete — organizacje są usuwane permanentnie (hard delete z kaskadą). W praktyce dezaktywacja (is_active = false) pełni rolę soft delete.
2. Policy create/update zawsze false — autoryzacja opiera się wyłącznie na BasePolicy::before() i middleware ról, co może powodować niespójności
3. Brak walidacji unikalności email — w przeciwieństwie do NIP i REGON, email organizacji nie ma constraintu unikalności
4. 22 typów, nie 21 — enum OrganizationEnumService zawiera 22 wartości (dodano event_venue)

Typy organizacji¶

System obsługuje 22 typów organizacji:

Kaskadowa dezaktywacja¶

Gdy organizacja zostaje dezaktywowana (is_active: true → false):

flowchart TD
    A[Dezaktywacja organizacji] --> B[OrganizationObserver::updated]
    B --> C[UpdatedIsActiveOrganizationObserver]
    C --> D{is_active zmienione?}
    D -->|Nie| E[Koniec]
    D -->|Tak| F{Więcej niż 50 obiektów?}
    F -->|Tak| G[ChangeStateAllObjectModelsJob\nkolejka: domain]
    F -->|Nie| H[changeStateAllObjectModels\nsynchronicznie]
    G --> I[Dezaktywacja obiektów]
    H --> I
    I --> J[Dezaktywacja zajęć]
    J --> K[Dezaktywacja harmonogramów]

Pracownicy organizacji¶

Przypisanie pracownika¶

sequenceDiagram
    participant Admin
    participant API
    participant Walidacja
    participant Observer
    participant Email

    Admin->>API: POST /organization-employees
    API->>Walidacja: StoreOrganizationEmployeeControllerRequest
    Walidacja->>Walidacja: UUID exists? Unique?
    Walidacja-->>API: OK
    API->>API: OrganizationEmployee::create()
    API->>Observer: created event
    Observer->>Email: SimpleSendNotificationJob
    Email->>Email: "Przypisanie do organizacji"
    API-->>Admin: 200 OK

Usunięcie pracownika¶

sequenceDiagram
    participant Admin
    participant API
    participant Observer
    participant ItemManager
    participant Email

    Admin->>API: DELETE /organization-employees/{id}
    API->>API: OrganizationEmployee::find(id)
    API->>Observer: deleting event
    Observer->>ItemManager: DeleteEmployeeItemManagers
    ItemManager->>ItemManager: Usunięcie uprawnień managera
    API->>API: delete()
    API->>Observer: deleted event
    Observer->>Email: SimpleSendNotificationJob
    Email->>Email: "Usunięcie z organizacji"
    API-->>Admin: 200 OK

Statystyki organizacji¶

System automatycznie oblicza agregaty za pomocą ApplyOrganizationAggregatesOrm:

Wartość biznesowa¶

Historia zmian¶