Dokumenty (Document)¶

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

Automatyczne generowanie dokumentów — szablony DOCX wypełniane danymi z systemu.

Co to jest?¶

Domena Dokumentów zarządza szablonami dokumentów i ich generowaniem. To jak drukarka z gotowymi formularzami — wgrywasz szablon umowy z polami do wypełnienia (np. reservation.first_name lub rezerwacja.imie), a system automatycznie podstawia dane i generuje gotowy dokument.

System obsługuje: - Szablony DOCX z placeholderami (format PhpWord: ${klucz}) - Automatyczne wypełnianie danymi z kontekstu (rezerwacja, obiekt, organizacja, użytkownik, system) - Dwujęzyczne klucze — angielskie (reservation.first_name) i polskie (rezerwacja.imie) - Przypisanie szablonów do obiektów (Item) i organizacji (Organization) - Generowanie dokumentów dla rezerwacji, obiektów i organizacji - Walidację kluczy podczas wgrywania szablonu - Zarządzanie stanem aktywności szablonów

Jakie problemy rozwiązuje?¶

Struktura domeny¶

app/Domain/Document/
├── Action/
│   ├── Attr/
│   │   └── GetFullFilePathAttr.php          # Resolves full file path from storage disk
│   ├── Controller/
│   │   ├── IndexDocumentController.php       # Lista dokumentów (filtr assignable)
│   │   ├── ShowDocumentController.php        # Szczegóły dokumentu
│   │   ├── StoreDocumentController.php       # Tworzenie + przypisanie
│   │   ├── UpdateDocumentController.php      # Aktualizacja metadanych
│   │   ├── AssignDocumentController.php      # Przypisanie do modelu
│   │   ├── UnassignDocumentController.php    # Odpisanie od modelu
│   │   ├── GenerateDocumentController.php    # Generowanie wypełnionego dokumentu
│   │   ├── DownloadDocumentController.php    # Pobieranie szablonu źródłowego
│   │   ├── IndexDocumentKeyController.php    # Lista kluczy placeholderów
│   │   └── ShowDocumentKeyController.php     # Szczegóły klucza
│   └── Other/
│       ├── AssignDocumentToModel.php         # Przypisanie z deduplikacją
│       ├── BuildContext.php                  # Budowanie kontekstu danych
│       ├── CreateDocument.php                # Upload + walidacja kluczy + zapis
│       ├── CreateDocumentAssignable.php      # Batch tworzenie przypisań
│       ├── DocumentGenerator.php             # Generowanie DOCX (PhpWord)
│       ├── DocumentKeyResolver.php           # Mapowanie kluczy EN↔PL + rozwiązywanie wartości
│       ├── DocumentParser.php                # Ekstrakcja placeholderów + walidacja
│       ├── UnassignDocumentFromModel.php     # Usuwanie przypisania
│       └── UpdateDocument.php                # Aktualizacja metadanych
├── Controller/
│   ├── DocumentController.php                # Główny kontroler (9 metod)
│   └── DocumentKeyController.php             # Kontroler kluczy (2 metody)
├── Model/
│   ├── Document.php                          # Szablon dokumentu
│   ├── DocumentAssignable.php                # Polimorficzne przypisanie
│   └── DocumentKey.php                       # Klucz placeholdera (baza danych)
├── Observer/
│   └── DocumentObserver.php                  # Pusty observer (zarejestrowany via ObservedBy)
├── Request/
│   ├── AssignDocumentControllerRequest.php   # Walidacja przypisania
│   ├── GenerateDocumentControllerRequest.php # Walidacja generowania
│   ├── IndexDocumentControllerRequest.php    # Walidacja listy dokumentów
│   ├── IndexDocumentKeyControllerRequest.php # Walidacja listy kluczy
│   ├── StoreDocumentControllerRequest.php    # Walidacja uploadu + klucze DOCX
│   ├── UpdateDocumentControllerRequest.php   # Walidacja aktualizacji
│   └── Rule/
│       └── GeneratedForExistsRule.php        # Walidacja istnienia modelu docelowego
├── Resource/
│   ├── DocumentResource.php                  # Zasób dokumentu
│   ├── DocumentAssignableResource.php        # Zasób przypisania
│   └── DocumentKeyResource.php               # Zasób klucza
└── Service/
    ├── DocumentEnumService.php               # Typy dokumentów + konteksty kluczy
    ├── TraitDocument.php                     # Metody domenowe
    └── TraitControllerDocument.php           # Delegacja do Action/Controller

Kluczowe funkcjonalności¶

Dla administratora / supervisora / pracownika¶

Jak to działa?¶

Scenariusz 1: Tworzenie szablonu dokumentu¶

flowchart LR
    A[Admin tworzy szablon DOCX] --> B[Wgrywa do systemu]
    B --> C{Walidacja kluczy}
    C -->|OK| D[Przypisuje do obiektu/organizacji]
    C -->|Błąd| E[Odrzucenie z listą<br/>nieznanych kluczy]
    D --> F[Szablon gotowy do użycia]

1. Administrator tworzy dokument Word z placeholderami w formacie ${klucz}
2. Klucze mogą być w języku angielskim (np. reservation.first_name) lub polskim (np. rezerwacja.imie)
3. Wgrywa szablon do systemu — system automatycznie wyciąga placeholdery z DOCX
4. System waliduje klucze — sprawdza czy istnieją w tabeli document_keys (kolumna key lub key_pl)
5. Jeśli klucze są nieznane → plik odrzucony z listą nieprawidłowych kluczy (HTTP 422)
6. Przypisuje szablon do konkretnego obiektu (Item) i/lub organizacji (Organization)

Scenariusz 2: Generowanie dokumentu¶

sequenceDiagram
    participant P as Pracownik
    participant S as System
    participant BC as BuildContext
    participant DKR as DocumentKeyResolver
    participant DG as DocumentGenerator

    P->>S: POST /documents/{id}/generate
    Note over P,S: generated_for_type + generated_for_id
    S->>BC: Buduje kontekst danych
    BC-->>S: {reservation, item, organization, user}
    S->>DG: Generuje dokument
    DG->>DG: Wyciąga placeholdery z szablonu
    DG->>DKR: Rozwiązuje wartości kluczy
    DKR-->>DG: Mapowane wartości
    DG->>DG: Wypełnia szablon (PhpWord)
    DG-->>S: Wygenerowany plik DOCX
    S-->>P: BinaryFileResponse (download)

1. Pracownik wskazuje typ i ID obiektu, dla którego generuje dokument
2. BuildContext buduje kontekst danych:
   • Reservation → ładuje rezerwację + reservationable (Item lub ActivityItem) + organizację
   • Item → ładuje obiekt + organizację
   • Organization → ładuje organizację
   • Zawsze dodaje zalogowanego użytkownika (auth()->user())
3. DocumentGenerator wyciąga placeholdery z szablonu DOCX
4. DocumentKeyResolver mapuje klucze (obsługuje polskie i angielskie nazwy) i rozwiązuje wartości z kontekstu
5. Nierozwiązane wartości zastępowane są symbolem {...}
6. Wygenerowany plik zapisywany w storage/app/private/generated/{uuid}.docx
7. Nazwa pliku do pobrania: {slug-nazwy-dokumentu}_{YmdHis}.docx

Modele danych¶

Document¶

Model: Domain\Document\Model\Document — rozszerza CustomModel (logowanie aktywności via Spatie), HasUuids, TraitDocument, #[ObservedBy(DocumentObserver)].

Relacje: assignables() → HasMany DocumentAssignable

Computed: full_file_path — accessor rozwiązujący pełną ścieżkę pliku (obsługuje URLe HTTP i ścieżki dyskowe).

DocumentKey¶

Model: Domain\Document\Model\DocumentKey — rozszerza CustomModel, HasUuids. Brak ObservedBy — nie ma observera.

Tabela: document_keys — przechowuje definicje kluczy do walidacji.

DocumentAssignable¶

Model: Domain\Document\Model\DocumentAssignable — rozszerza CustomModel, HasUuids. Relacja polimorficzna (MorphTo).

Relacje: document() → BelongsTo Document, assignable() → MorphTo (Item lub Organization).

Struktura tabel w bazie danych¶

Migracja: 0001_01_01_000029_create_documents.php

Tabela documents¶

Indeksy: (type, is_active)

Tabela document_assignables¶

Klucz obcy: document_id → documents.id ON DELETE CASCADE

Constraint unique: (document_id, assignable_type, assignable_id)

Indeksy: document_id, (assignable_type, assignable_id)

Tabela document_keys¶

Indeksy: key (unique), context, key_pl

Typy dokumentów¶

Źródło: DocumentEnumService::getDocumentTypes().

Konteksty kluczy¶

Źródło: DocumentEnumService::getDocumentKeyContexts().

Dostępne placeholdery¶

System udostępnia 32 placeholdery do wykorzystania w szablonach. Każdy klucz ma wersję angielską i polską — w szablonie DOCX można użyć dowolnej z nich.

Dane rezerwacji (12 kluczy)¶

Dane obiektu (8 kluczy)¶

Dane organizacji (6 kluczy)¶

Dane użytkownika (2 klucze)¶

Dane systemowe (4 klucze)¶

Powiązania z innymi domenami¶

API Endpoints¶

Dokumenty (/api/documents)¶

Klucze dokumentów (/api/document-keys)¶

Parametry żądań¶

Store (POST /documents)¶

Update (PATCH /documents/{id})¶

Generate (POST /documents/{id}/generate)¶

GeneratedForExistsRule — niestandardowa reguła walidacji sprawdzająca istnienie rekordu w odpowiedniej tabeli na podstawie generated_for_type.

Assign (POST /documents/{id}/assign)¶

Index Documents (GET /documents)¶

Index DocumentKeys (GET /document-keys)¶

Odpowiedzi API¶

DocumentResource¶

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Umowa najmu sali",
    "type": "contract",
    "type_lang": "Contract",
    "file_path": "documents/contract/abc123.docx",
    "file_name": "umowa_najmu_sali.docx",
    "file_size": 45678,
    "description": "Szablon umowy najmu sali konferencyjnej",
    "is_active": true,
    "created_at": "2024-02-15 10:00:00",
    "updated_at": "2024-02-15 10:00:00",
    "can": {
        "view": true,
        "create": true,
        "update": true
    },
    "assignables": [
        {
            "id": "...",
            "document_id": "550e8400-...",
            "assignable_type": "Domain\\Item\\Model\\Item",
            "assignable_id": "...",
            "created_at": "2024-02-15 10:00:00",
            "updated_at": "2024-02-15 10:00:00"
        }
    ]
}

Relacje: RELATIONS = ['assignables'].

DocumentKeyResource¶

{
    "id": "660e8400-...",
    "key": "reservation.first_name",
    "key_pl": "rezerwacja.imie",
    "label": "Imię rezerwującego",
    "description": "Imię osoby dokonującej rezerwacji",
    "context": "reservation",
    "context_pl": "Reservation",
    "value_type": "string",
    "example_value": "Jan",
    "created_at": "2024-02-15 10:00:00",
    "updated_at": "2024-02-15 10:00:00"
}

Odpowiedzi na Store/Update¶

Endpointy store i update zwracają komunikat sukcesu (nie zasób):

{
    "data": "The document has been successfully added"
}

Tworzenie szablonu¶

Krok 1: Sprawdź dostępne klucze¶

Użyj endpointu GET /api/document-keys aby zobaczyć listę dostępnych kluczy. Filtruj po kontekście: ?context=reservation.

Krok 2: Przygotuj dokument Word¶

Stwórz dokument .docx z placeholderami w formacie ${klucz} (format PhpWord TemplateProcessor):

UMOWA NAJMU

zawarta dnia ${system.current_date} (lub ${system.aktualna_data})

pomiędzy:
${organization.name} z siedzibą ${organization.full_address}
NIP: ${organization.nip}, REGON: ${organization.regon}
reprezentowaną przez ${user.name}

a

${reservation.first_name} ${reservation.last_name}
email: ${reservation.email}, tel: ${reservation.mobile_phone}

Przedmiot najmu: ${item.name}
Adres obiektu: ${item.full_address}
Pojemność: ${item.capacity} osób

Termin: od ${reservation.date_time_from} do ${reservation.date_time_to}
Kwota: ${reservation.total_price} zł

${rezerwacja.imie} ${rezerwacja.nazwisko}
zamieszkałym: ${obiekt.miasto}

Krok 3: Wgraj szablon¶

POST /api/documents
Content-Type: multipart/form-data

name: "Umowa najmu sali"
type: "contract"
file: [plik.docx]
description: "Szablon umowy najmu"
assignables[0][assignable_type]: "Domain\Item\Model\Item"
assignables[0][assignable_id]: "uuid-obiektu"

System automatycznie: 1. Wyciągnie placeholdery z pliku DOCX 2. Zwaliduje klucze w tabeli document_keys 3. Zapisze plik w storage/app/private/documents/{type}/ 4. Utworzy rekord Document i przypisania DocumentAssignable

Krok 4: Generuj dokument¶

POST /api/documents/{documentId}/generate

{
    "generated_for_type": "Domain\\Reservation\\Model\\Reservation",
    "generated_for_id": "uuid-rezerwacji"
}

Odpowiedź: BinaryFileResponse — plik DOCX do pobrania.

Budowanie kontekstu (BuildContext)¶

Kontekst danych budowany jest automatycznie na podstawie generated_for_type:

flowchart TD
    A[generated_for_type] --> B{Typ}
    B -->|Reservation| C[Ładuj rezerwację<br/>+ reservationable<br/>+ reservationSlots]
    B -->|Item| D[Ładuj obiekt<br/>+ organizację]
    B -->|Organization| E[Ładuj organizację]

    C --> F{reservationable type}
    F -->|Item| G["context: reservation, item, organization"]
    F -->|ActivityItem| H["context: reservation, activity_item, activity, organization"]

    D --> I["context: item, organization"]
    E --> J["context: organization"]

    G --> K[+ user z auth]
    H --> K
    I --> K
    J --> K

Mechanizm rozwiązywania kluczy (DocumentKeyResolver)¶

flowchart LR
    A["Klucz z szablonu<br/>(np. rezerwacja.imie)"] --> B[normalizeKey]
    B --> C{"Czy klucz PL<br/>w keyMappings?"}
    C -->|Tak| D["Zamień na EN<br/>(reservation.first_name)"]
    C -->|Nie| E[Użyj oryginalnego]
    D --> F[resolveKey]
    E --> F
    F --> G{Prefix klucza}
    G -->|reservation.| H[resolveReservationKey]
    G -->|item.| I[resolveItemKey]
    G -->|organization.| J[resolveOrganizationKey]
    G -->|user.| K[resolveUserKey]
    G -->|system.| L[resolveSystemKey]
    H --> M[Wartość z modelu]
    I --> M
    J --> M
    K --> M
    L --> M

Kluczowe szczegóły: - reservation.total_price — formatowany: number_format($value, 2, ',', ' ') (np. 250,00) - reservation.created_at — format: Y-m-d H:i - item.full_address / organization.full_address — składany z pól: "{street} {street_number}, {postal_code} {city}" - system.name — pobierany z config('app.name', 'Zajmij.to') - reservation.days_time_array — zwraca tablicę → konwertowana na tekst via implode("\n", ...)

Przechowywanie plików¶

Dysk: private (Laravel Storage).

Limit rozmiaru: max 10 MB (10240 KB) — walidacja w StoreDocumentControllerRequest.

Format: wyłącznie DOCX (mimes:docx, mimetypes:application/vnd.openxmlformats-officedocument.wordprocessingml.document).

Wyjątki¶

InvalidDocumentKeysException (Infrastructure\Exceptions) — rzucany przez CreateDocument gdy walidacja kluczy w DOCX nie przejdzie. Wiadomość zawiera listę nieprawidłowych kluczy.

Wartość biznesowa¶

Technologia¶

Uprawnienia¶

Policy (DocumentPolicy)¶

DocumentPolicy rozszerza BasePolicy (która w before() nadaje Adminowi pełny dostęp).

Observer¶

DocumentObserver — zarejestrowany via #[ObservedBy(DocumentObserver::class)] na modelu Document. Klasa jest pusta — nie implementuje żadnych hooków lifecycle.

Diagram komponentów¶

flowchart TB
    subgraph Controllers
        DC[DocumentController<br/>9 metod]
        DKC[DocumentKeyController<br/>2 metody]
    end

    subgraph "Action/Controller"
        IDC[IndexDocumentController]
        SDC[ShowDocumentController]
        STDC[StoreDocumentController]
        UDC[UpdateDocumentController]
        ADC[AssignDocumentController]
        UADC[UnassignDocumentController]
        GDC[GenerateDocumentController]
        DDC[DownloadDocumentController]
        IDKC[IndexDocumentKeyController]
        SDKC[ShowDocumentKeyController]
    end

    subgraph "Action/Other"
        CD[CreateDocument]
        UD[UpdateDocument]
        ADM[AssignDocumentToModel]
        UADM[UnassignDocumentFromModel]
        CDA[CreateDocumentAssignable]
        DG[DocumentGenerator]
        DP[DocumentParser]
        DKR[DocumentKeyResolver]
        BC[BuildContext]
    end

    subgraph Models
        D[Document]
        DK[DocumentKey]
        DA[DocumentAssignable]
    end

    DC --> IDC & SDC & STDC & UDC & ADC & UADC & GDC & DDC
    DKC --> IDKC & SDKC

    STDC --> CD --> DP
    STDC --> CDA
    UDC --> UD
    ADC --> ADM
    UADC --> DA
    GDC --> BC & DG
    DG --> DP & DKR

    CD --> D & DA
    DP --> DK
    ADM --> DA
    BC --> D

Znane ograniczenia i TODO¶