Nieruchomości

Przegląd

Nieruchomości, którymi użytkownicy mogą zarządzać. Każda nieruchomość ma nazwę, opis, kolor, typ i adres zintegrowany z API Nova Poshta.

Kraj

Każda nieruchomość jest powiązana z krajem. Określa to format adresu, domyślną walutę i inne ustawienia regionalne.

• Kraj jest polem wymaganym podczas tworzenia lub edycji nieruchomości
• Format adresu zależy od wybranego kraju (Nova Poshta API dla Ukrainy)
• Kraj jest wyświetlany w kartach nieruchomości, listach i stronach szczegółów

Przykładowa odpowiedź

{
  "id": 1,
  "name": "My Apartment",
  "country": {
    "id": 1,
    "code": "UA",
    "name_key": "country.ua"
  },
  "property_type": {...},
  "address": {...}
}

Role użytkowników

Każda nieruchomość może mieć wielu użytkowników z różnymi rolami:

Zarządzanie użytkownikami

Właściciel nieruchomości (PROPERTY_LANDLORD) może dodawać i usuwać innych użytkowników:

• Dodawanie użytkowników: Wyszukiwanie po emailu lub telefonie. Wynik wyświetlany tylko gdy znaleziono dokładnie 1 użytkownika (ochrona prywatności).
• Jedna rola na nieruchomość: Każdy użytkownik może mieć tylko jedną rolę w ramach nieruchomości.
• PROPERTY_LANDLORD nie można dodać ręcznie: Ta rola jest przypisywana automatycznie podczas tworzenia nieruchomości.
• Właściciela nie można usunąć: Wymagana administracja do zmiany właściciela.

REST API

Wszystkie punkty końcowe API wymagają uwierzytelnienia JWT.

Uwaga dotycząca warstwy usługowej

API nieruchomości

GET    /api/v1/properties          # List user's properties
POST   /api/v1/properties          # Create property (user becomes PROPERTY_LANDLORD)
GET    /api/v1/properties/{id}     # Property details
PUT    /api/v1/properties/{id}     # Update (LANDLORD/LANDLORD_AGENT)
DELETE /api/v1/properties/{id}     # Delete (LANDLORD only)

API użytkowników nieruchomości

GET    /api/v1/properties/{id}/users              # List property users
POST   /api/v1/properties/{id}/users              # Add user
DELETE /api/v1/properties/{id}/users/{userId}     # Remove user
GET    /api/v1/properties/{id}/search-user?q=...  # Search user
GET    /api/v1/properties/{id}/available-roles    # Available roles

API opisów (tłumaczeń)

GET    /api/v1/properties/{id}/descriptions              # List description translations
POST   /api/v1/properties/{id}/descriptions              # Create/update translation (locale + description)
POST   /api/v1/properties/{id}/descriptions/translate    # AI translate to target locale

Funkcje AI

POST   /api/v1/properties/generate-description    # Generate description via Grok AI (from form data)
POST   /api/v1/geo/geocode                        # Geocode address to lat/lng (public)

API adresów Nova Poshta

GET /api/v1/nova-poshta/areas                    # List areas (oblasts)
GET /api/v1/nova-poshta/cities?area_ref=...      # Cities in area
GET /api/v1/nova-poshta/streets?city_ref=...&search=... # Search streets (min 1 char)
GET /api/v1/nova-poshta/search-by-zip?zip=...    # Find city by postal code (5 digits)

Przykład: Dodawanie użytkownika

POST /api/v1/properties/019fe131-6b2a-7c41-9d8e-3f5a2c7b1e04/users
Content-Type: application/json
Authorization: Bearer <token>

{
  "user_id": "019fe131-7a3d-7e52-8c19-4b6d3e9f2a15",
  "role_id": 12
}

Przykładowa odpowiedź

{
  "message": "User added successfully",
  "data": {
    "id": 3,
    "user_id": "019fe131-7a3d-7e52-8c19-4b6d3e9f2a15",
    "email": "[email protected]",
    "name": "John Smith",
    "role": {
      "id": 12,
      "code": "PROPERTY_TENANT",
      "name_key": "role.property_tenant"
    },
    "created_at": "2026-01-05T14:30:00+00:00"
  }
}

Przykład: Odpowiedź nieruchomości

{
  "id": 1,
  "name": "My Apartment",
  "description": "Apartment in the city center",
  "color": "var(--color-primary)",
  "property_type": {
    "id": 2,
    "code": "APARTMENT",
    "name_key": "property_type.apartment.name"
  },
  "address": {
    "area_ref": "71508128-9b87-11de-822f-000c2965ae0e",
    "area_name": "Kyiv Oblast",
    "city_ref": "e221d627-391c-11dd-90d9-001a92567626",
    "city_name": "Kyiv",
    "street_ref": "18e2ffc8-d68d-11e3-9937-003048d2b473",
    "street_name": "Khreschatyk",
    "building_number": "1A",
    "apartment_number": "42",
    "full_address": "Kyiv Oblast, Kyiv, Khreschatyk, bld. 1A, apt. 42"
  },
  "living_area": "45.50",
  "total_area": "57.80",
  "latitude": "50.4500336",
  "longitude": "30.5241361",
  "descriptions": [
    {"locale": "en", "description": "<p>Spacious apartment in the city center...</p>"},
    {"locale": "de", "description": "<p>Geräumige Wohnung im Stadtzentrum...</p>"}
  ],
  "user_role": "PROPERTY_LANDLORD",
  "users": [
    {
      "id": 1,
      "user_id": "019fe131-7a3d-7e52-8c19-4b6d3e9f2a15",
      "email": "[email protected]",
      "name": "Property Owner",
      "role": {"id": 10, "code": "PROPERTY_LANDLORD", "name_key": "role.property_landlord"},
      "created_at": "2026-01-05T12:00:00+00:00"
    }
  ],
  "created_at": "2026-01-05T12:00:00+00:00",
  "updated_at": "2026-01-05T14:30:00+00:00"
}

Wielojęzyczne opisy

Opisy nieruchomości można tłumaczyć na wiele języków. Główny opis jest przechowywany w Property, tłumaczenia w PropertyDescription.

• Encja: PropertyDescription (property_id + locale + HTML description)
• Obsługiwane języki: uk, en, ru, pl, de
• Tłumaczenie AI: Grok AI tłumaczy opis HTML zachowując tagi. Dostępne przez API i w formularzu.
• UX formularza: Edytory tłumaczeń pojawiają się gdy główny opis ma 20+ znaków. Każdy język ma edytor WYSIWYG + przycisk tłumaczenia AI.

Przykład zapisu tłumaczenia

POST /api/v1/properties/1/descriptions
Content-Type: application/json
Authorization: Bearer <token>

{
  "locale": "en",
  "description": "<p>Spacious apartment in the city center with a great view.</p>"
}

Przykład tłumaczenia AI

POST /api/v1/properties/1/descriptions/translate
Content-Type: application/json
Authorization: Bearer <token>

{
  "target_locale": "de",
  "source_html": "<p>Простора квартира в центрі міста.</p>"
}

// Response:
{
  "html": "<p>Geräumige Wohnung im Stadtzentrum.</p>",
  "locale": "de"
}

Charakterystyki nieruchomości

Każda nieruchomość może mieć dodatkowe charakterystyki: liczba pokoi, piętro, typ budynku itp. Wartości te są przechowywane w PropertyDataValue i powiązane z PropertyDataType.

Struktura danych

• PropertyDataType: Definiuje typ charakterystyki (kod, nazwa, typ danych, grupa, jednostka, ikona)
• PropertyDataValue: Przechowuje wartość dla kombinacji nieruchomość + typ danych

Grupy typów danych

Typy wartości

API charakterystyk nieruchomości

GET    /api/v1/properties/{id}/data-values           # List all values
GET    /api/v1/properties/{id}/data-values/grouped    # Values grouped by category
GET    /api/v1/properties/{id}/data-values/{code}     # Get single value by code
POST   /api/v1/properties/{id}/data-values            # Set/update a value
PUT    /api/v1/properties/{id}/data-values/batch      # Batch update multiple values
DELETE /api/v1/properties/{id}/data-values/{code}     # Delete a value

API typów danych (słownik)

GET /api/v1/property-data-types                  # List all active types
GET /api/v1/property-data-types/grouped          # Types grouped by category
GET /api/v1/property-data-types/{code}           # Get type by code
GET /api/v1/property-data-types/meta/groups      # List available groups
GET /api/v1/property-data-types/meta/data-types  # List available data types

Przykład: Ustawienie wartości

POST /api/v1/properties/1/data-values
Content-Type: application/json
Authorization: Bearer <token>

{
  "code": "ROOM_COUNT",
  "value": "3"
}

Przykładowa odpowiedź

{
  "message": "Value set successfully",
  "data": {
    "id": 42,
    "code": "ROOM_COUNT",
    "name_key": "property_data_type.room_count.name",
    "data_type": "int",
    "group_code": "apartment",
    "value": "3",
    "formatted_value": "3",
    "unit": null,
    "icon_url": "https://s3.example.com/property_data_type/room_count.svg",
    "created_at": "2026-01-17T12:00:00",
    "updated_at": "2026-01-17T12:00:00"
  }
}

Przykład: Aktualizacja zbiorcza

PUT /api/v1/properties/1/data-values/batch
Content-Type: application/json
Authorization: Bearer <token>

{
  "values": {
    "ROOM_COUNT": "3",
    "FLOOR_NUMBER": "5",
    "HAS_BALCONY": "1",
    "BUILDING_TYPE": "brick",
    "WINDOW_VIEW": "park",
    "APARTMENT_CONDITION": ""
  }
}

Przykładowa odpowiedź

{
  "message": "Values updated successfully",
  "updated": 5,
  "removed": 1,
  "errors": []
}

Integracja z interfejsem

Charakterystyki nieruchomości są wyświetlane w:

• Formularz nieruchomości: Rozwijana sekcja z pogrupowanymi polami do wprowadzania wartości
• Strona podglądu nieruchomości: Pogrupowane wyświetlanie wszystkich ustawionych wartości z ikonami
• Lista nieruchomości: Podgląd ikon pierwszych 8 wartości w kartach nieruchomości

Walidacja

Wartości są walidowane zgodnie z ich typem danych:

• bool: Musi być 0, 1, true, false, yes lub no
• int: Musi być liczbą całkowitą w określonym zakresie min/max (np. ROOM_COUNT: 1-30)
• float: Musi być liczbą w określonym zakresie min/max (np. CEILING_HEIGHT: 1.5-10.0)
• string: Musi odpowiadać dozwolonym wartościom, jeśli są zdefiniowane (np. BUILDING_TYPE: panel, brick, monolith itp.)

Swagger / OpenAPI

Pełna dokumentacja API jest dostępna w Swagger UI: /api/v1/doc

• 03. Properties / Data Values - CRUD API charakterystyk nieruchomości
• 05. References / Property Data Types - Dane słownikowe typów charakterystyk