# Jawność cen — dokumentacja

## Co zostało zbudowane

Cztery publiczne endpointy HTTP oraz strona administracyjna, spełniające wymóg ustawy o jawności cen nieruchomości.

### Endpointy

| URL | Opis |
|-----|------|
| `/ceny-mieszkan.xml` | XML z cenami wszystkich lokali + historia zmian z bazy danych |
| `/ceny-mieszkan.md5` | Hash MD5 powyższego pliku XML (32-znakowy lowercase hex) |
| `/dane-gov-pl.xml` | Katalog zgodny z XSD portalu dane.gov.pl, wskazujący na plik cen |
| `/dane-gov-pl.md5` | Hash MD5 katalogu |

Wszystkie endpointy są publicznie dostępne bez logowania.

### Strona administracyjna

**wp-admin → Narzędzia → Jawność Cen**

Pokazuje oba URL-e do zgłoszenia do Ministerstwa z przyciskami „Kopiuj URL" i „Otwórz XML".

---

## Jak to działa

### Plik cen (`/ceny-mieszkan.xml`)

- Pobiera wszystkie opublikowane posty typu `apartamenty`
- Dla każdego lokalu odczytuje pola ACF: `information_type`, `information_floor`, `information_floor_space`, `information_price`, `information_price_m2`, `information_status`
- Dołącza historię cen z tabeli `wp_price_history` (ta sama tabela co cron dzienny)
- Wynik cachowany w transiencie WordPress na **1 godzinę**
- Cache jest automatycznie czyszczony przy każdym uruchomieniu crona dziennego

Struktura XML:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<lokale inwestycja="Wyszyńskiego 12" generowany="2026-03-12T10:00:00+01:00">
  <lokal id="123">
    <nazwa>A1 – Lokal 101</nazwa>
    <typ>mieszkanie</typ>
    <pietro>1</pietro>
    <powierzchnia>35,68</powierzchnia>
    <status>dostępny</status>
    <cena_brutto>677 920</cena_brutto>
    <cena_za_m2>19 000</cena_za_m2>
    <data_aktualizacji>2026-03-12</data_aktualizacji>
    <historia_cen>
      <zmiana data="2026-03-12">
        <cena_brutto>677 920</cena_brutto>
        <cena_za_m2>19 000</cena_za_m2>
      </zmiana>
    </historia_cen>
  </lokal>
</lokale>
```

### Katalog dane.gov.pl (`/dane-gov-pl.xml`)

Statyczny XML generowany dynamicznie — URL zasobu pobierany przez `home_url()`, data przez `date()`. Zgodny z XSD `otwarte_dane_latest.xsd` portalu dane.gov.pl.

### Kod źródłowy

Plik: `wp-content/plugins/elementor-addon/elementor-addon.php`

| Funkcja | Opis |
|---------|------|
| `apartamenty_xml_rewrite_rules()` | Rejestruje reguły URL dla endpointów |
| `apartamenty_xml_query_vars()` | Dodaje query vars do WordPress |
| `apartamenty_generate_price_xml()` | Generuje XML cen z cachowaniem |
| `apartamenty_generate_datagov_xml()` | Generuje XML katalogu dane.gov.pl |
| `apartamenty_xml_template_redirect()` | Obsługuje żądania HTTP i wysyła odpowiedź |
| `apartamenty_jawnosc_cen_menu()` | Rejestruje stronę w menu Narzędzia |
| `apartamenty_jawnosc_cen_page()` | Renderuje stronę administracyjną |

---

## Co musi zrobić Klient

### Krok 1: Flush rewrite rules (jednorazowo po wdrożeniu)

Po każdym wdrożeniu zmian w pluginie należy odświeżyć reguły permalink:

**wp-admin → Ustawienia → Bezpośrednie odnośniki → kliknij „Zapisz zmiany"**

Bez tego kroku endpointy XML zwracają błąd 404.

### Krok 2: Zgłoszenie do portalu dane.gov.pl

1. Zaloguj się na [dane.gov.pl](https://dane.gov.pl) (konto instytucjonalne dewelopera lub pełnomocnika)
2. W panelu wydawcy wybierz „Dodaj zbiór danych" lub „Zasilanie automatyczne (harvester)"
3. Podaj URL katalogu:
   ```
   https://wyszynskiego12.pagedev.pl/dane-gov-pl.xml
   ```
4. Portal będzie automatycznie pobierał ten plik (codziennie) i aktualizował dane w rejestrze

> Jeśli portal dane.gov.pl wymaga wcześniejszej rejestracji instytucji — należy ją przeprowadzić osobno. Kontakt: **kontakt@dane.gov.pl**

### Krok 3 (opcjonalnie): Weryfikacja endpointów przed zgłoszeniem

Przed podaniem URL-a do Ministerstwa warto sprawdzić każdy endpoint ręcznie:

| URL | Oczekiwany wynik |
|-----|-----------------|
| `/ceny-mieszkan.xml` | XML z listą lokali, Content-Type: application/xml |
| `/ceny-mieszkan.md5` | 32-znakowy ciąg liter i cyfr, np. `a3f2b1c9...` |
| `/dane-gov-pl.xml` | XML z elementem `<datasets>`, URL w `<resource>` wskazuje na `/ceny-mieszkan.xml` |
| `/dane-gov-pl.md5` | 32-znakowy ciąg liter i cyfr |

---

## Aktualizacja danych

Dane w pliku XML są aktualizowane **automatycznie**:

- Ceny pobierane są z pól ACF w WordPress — wystarczy zaktualizować pole `information_price` w edytorze posta, a nowa cena pojawi się w XML po max. 1 godzinie (czas życia cache)
- Historia cen zapisywana jest codziennie przez WP Cron (szczegóły w `docs/readme.md`)
- Cache XML czyszczony jest przy każdym uruchomieniu crona

**Ręczne wymuszenie odświeżenia XML** (np. po pilnej zmianie ceny):

Przez WP-CLI (SSH):
```bash
wp transient delete apartamenty_price_xml_cache
```

Lub przez phpMyAdmin / SQL:
```sql
DELETE FROM wp_options WHERE option_name = '_transient_apartamenty_price_xml_cache';
DELETE FROM wp_options WHERE option_name = '_transient_timeout_apartamenty_price_xml_cache';
```

---

## Uwagi techniczne

- Endpointy nie wymagają żadnej konfiguracji po stronie serwera (nginx/Apache) — działają przez mechanizm rewrite rules WordPress
- XML generowany jest jako czysty string PHP z `htmlspecialchars(ENT_XML1)` — bezpieczny dla znaków specjalnych w nazwach lokali
- Katalog dane.gov.pl zawiera hardcodowane dane inwestycji (Wyszyńskiego 12) — jeśli dane inwestycji się zmienią, należy zaktualizować funkcję `apartamenty_generate_datagov_xml()` w pluginie