Architektura systemu¶

Domain-Driven Design — trójwarstwowa architektura z 31 domenami biznesowymi.

Przegląd architektury¶

System Zajmij.to został zbudowany zgodnie z zasadami Domain-Driven Design (DDD). Kod jest podzielony na trzy główne warstwy:

flowchart TB
    subgraph app[Aplikacja]
        D[Domain<br/>Logika biznesowa]
        I[Infrastructure<br/>Frameworki i zewnętrzne]
        S[Support<br/>Współdzielone narzędzia]
    end

    D --> S
    I --> S
    D -.-> I

Trzy warstwy¶

1. Domain (Domena)¶

Lokalizacja: app/Domain/

Rdzeń aplikacji — logika biznesowa zorganizowana w 31 kontekstów domenowych.

2. Infrastructure (Infrastruktura)¶

Lokalizacja: app/Infrastructure/

Warstwa techniczna — framework, middleware, zewnętrzne integracje.

3. Support (Wsparcie)¶

Lokalizacja: app/Support/

Współdzielone narzędzia używane przez wszystkie domeny.

Wzorce architektoniczne¶

Single-Action Controllers¶

Każda akcja kontrolera to osobna klasa:

Domain/{Domain}/Action/Controller/
├── IndexOrganizationController.php
├── ShowOrganizationController.php
├── StoreOrganizationController.php
├── UpdateOrganizationController.php
└── DeleteOrganizationController.php

Zalety: - Łatwiejsze testowanie - Jasna odpowiedzialność - Mniejsze pliki

Trait-Based Services¶

Logika biznesowa w traitach:

class OrganizationController extends Controller
{
    use TraitSupport;
    use TraitControllerOrganization;

    public function index(Request $request)
    {
        return $this->indexOrganizationController($validated);
    }
}

Traity: - TraitSupport — bazowe metody dla wszystkich - Trait{Domain} — logika domenowa - TraitController{Domain} — orkiestracja kontrolera

Observer Pattern¶

Obserwatorzy modeli w Action/Other/:

Domain/Reservation/Action/Other/
├── CreatingReservationObserver.php
├── UpdatingReservationObserver.php
└── DeletingReservationObserver.php

Middleware Pipeline¶

Każde żądanie API przechodzi przez pipeline:

flowchart LR
    A[Request] --> B[check_versions]
    B --> C[global_database_transaction]
    C --> D[auth:api]
    D --> E[app_mode]
    E --> F[to_user_access]
    F --> G[user_accepted_agreements]
    G --> H[Controller]

Global Database Transaction¶

Wszystkie żądania API w transakcji:

Routing¶

Struktura plików¶

routes/
├── web.php           # Fallback — redirect na frontend
├── api.php           # Główny plik z middleware
├── auth.php          # Include authenticated routes
├── noAuth.php        # Include public routes
└── api/
    ├── auth/         # Chronione endpointy
    │   ├── reservation.php
    │   ├── organization.php
    │   └── ...
    └── noAuth/       # Publiczne endpointy
        ├── reservation.php
        └── ...

Konwencje¶

Kolejki i asynchroniczność¶

8 dedykowanych kolejek¶

Job Callback¶

Wszystkie joby w JobCallback:

flowchart TD
    A[Job::handle] --> B[JobCallback]
    B --> C[Begin Transaction]
    C --> D{Sukces?}
    D -->|Tak| E[Commit]
    D -->|Nie| F[Rollback]
    F --> G[Log Error]
    G --> H[Send Alert]

Baza danych¶

Konwencje¶

Relacje polimorficzne¶

Wiele modeli używa polimorfizmu:

reservations
├── reservationable_type  # Item lub ActivityItem
└── reservationable_id    # UUID obiektu

Strategia indeksowania¶

System stosuje kompleksową strategię indeksowania bazy danych dla optymalnej wydajności przy dużym ruchu.

Automatyczne indeksy:

• Klucze główne (UUID) — zawsze indeksowane
• Klucze obce (->foreign()) — MySQL/InnoDB automatycznie tworzy indeks
• Kolumny polimorficzne (uuidMorphs) — Laravel tworzy indeks kompozytowy [type, id]
• Kolumny ->unique() — unique constraint = indeks

Ręczne indeksy na kolumnach filtrowanych:

Indeksy kompozytowe (wielokolumnowe):

Generowanie kodu¶

Tworzenie nowej domeny¶

php artisan support:make-domain --domainName=Product

Generuje pełną strukturę: - Model, Controller, Request, Resource - Akcje (Controller/, Attr/, Other/) - Traity serwisowe - Plik routingu

Diagramy domen¶

Domeny podstawowe¶

flowchart LR
    R[Reservation] --> I[Item]
    R --> A[ActivityItem]
    A --> AC[Activity]
    I --> O[Organization]
    AC --> O
    R --> C[Client]
    R --> P[Pricing]

Domeny użytkowników¶

flowchart LR
    U[User] --> RO[Role]
    U --> O[Organization]
    O --> E[Employee]
    I[Item] --> M[Manager]
    T[Trainer] --> AI[ActivityItem]

Domeny komunikacji¶

flowchart LR
    R[Reservation] --> N[Notification]
    R --> RE[Review]
    R --> CO[Complaint]
    CO --> TH[Thread/Messages]

System autoryzacji (Policies)¶

System implementuje dwuwarstwową autoryzację:

Warstwa 1: Role Middleware¶

Gruboziarnista kontrola — sprawdza czy użytkownik ma odpowiednią rolę:

$this->middleware('role:admin|supervisor|employee', ['only' => ['store', 'update']]);

Warstwa 2: Laravel Policies¶

Granularna autoryzacja per zasób — sprawdza czy użytkownik ma dostęp do konkretnego obiektu:

$this->authorize('update', Item::find($itemId));

BasePolicy¶

Wszystkie policies dziedziczą z Support\Policy\BasePolicy:

• Admin bypass — admin ma pełny dostęp (metoda before())
• Organization membership — belongsToOrganization() sprawdza przynależność do organizacji
• Item management — isItemManager() sprawdza zarządzanie zasobem

Kategorie policies¶

Pole can w API¶

Każda odpowiedź API zawiera pole can z uprawnieniami frontendu:

{
    "id": "uuid",
    "name": "Sala konferencyjna",
    "can": {
        "update": true,
        "changeState": false
    }
}

Endpoint /api/me/abilities¶

Zwraca globalne uprawnienia użytkownika:

{
    "create_organization": false,
    "create_item": true,
    "create_activity": true,
    "manage_users": false,
    "view_reports": true
}

flowchart TD
    A[Request] --> B{Role Middleware}
    B -->|Brak roli| C[403 Forbidden]
    B -->|Ma rolę| D{Policy authorize}
    D -->|Brak dostępu do zasobu| C
    D -->|Ma dostęp| E[Kontroler]
    E --> F[Response + pole can]

Global Scopes — filtrowanie danych (READ)¶

System stosuje dwa globalne scope'y rejestrowane w Infrastructure\Vendor\CustomModel:

UserAccessesGlobalScope¶

Plik: Support\Action\Scope\UserAccessesGlobalScope

Automatycznie filtruje dane READ (zapytania SELECT) na poziomie Eloquent. Każdy model dziedziczący z CustomModel przechodzi przez ten scope.

flowchart TD
    A[Query] --> B{Auth?}
    B -->|Nie| C[Brak filtrowania]
    B -->|Tak| D{Admin?}
    D -->|Tak| C
    D -->|Nie| E{Typ modelu}
    E -->|User-owned| F[where user_id]
    E -->|Organization| G[whereIn organization_id]
    E -->|Przez relację| H[whereHas parent → org]
    E -->|Polimorficzny| I[whereHasMorph → org]
    E -->|Kolumna organization_id| G
    E -->|Kolumna reservation_id| J[whereHas reservation → org]
    E -->|Default| C

Strategie filtrowania:

Wyjątki od CustomModel:

• Media — rozszerza Spatie Media, rejestruje scope bezpośrednio w booted()
• ActivityLog — rozszerza Spatie Activity, NIE rejestruje scope (admin-only via middleware)
• User — rozszerza Laravel Authenticatable, NIE rejestruje scope (filtrowany przez ToUserAccessMiddleware)

IsActiveGlobalScope¶

Plik: Support\Action\Scope\IsActiveGlobalScope

Filtruje niezalogowanych użytkowników — ukrywa nieaktywne/niepubliczne/anulowane rekordy.

Best practices¶