---
phase: 02-jawnosc-cen
plan: 01
subsystem: api
tags: [xml, rewrite-rules, wp-cron, transient, admin-page, dane.gov.pl]

requires:
  - phase: 01-historia-cen
    provides: tabela wp_price_history + cron dzienny apartamenty_record_prices + pola ACF

provides:
  - publiczny endpoint /ceny-mieszkan.xml z cenami i historią cen
  - publiczny endpoint /ceny-mieszkan.md5
  - publiczny endpoint /dane-gov-pl.xml (katalog XSD-compliant)
  - publiczny endpoint /dane-gov-pl.md5
  - strona wp-admin: Narzędzia → Jawność Cen

affects: []

tech-stack:
  added: []
  patterns:
    - WP rewrite rules + query_vars dla custom XML endpoints
    - Transient cache z inwalidacją przez cron
    - XML generowany jako czysty PHP string z htmlspecialchars(ENT_XML1)

key-files:
  created:
    - docs/jawnosc-cen.md
  modified:
    - wp-content/plugins/elementor-addon/elementor-addon.php

key-decisions:
  - "XML jako czysty PHP string zamiast DOMDocument — brak zależności od ext-dom"
  - "Transient cache 1h — inwalidowany przez istniejący cron dzienny"
  - "Wszystko w jednym pliku pluginu — zgodnie z boundaries planu"

patterns-established:
  - "Endpointy XML przez add_rewrite_rule() + query_vars + template_redirect"
  - "Cache przez set_transient/get_transient z delete_transient w cronie"

duration: ~30min
started: 2026-03-12T00:00:00Z
completed: 2026-03-12T00:30:00Z
---

# Faza 02 Plan 01: Jawność Cen — XML Endpoints — Summary

**Publiczne endpointy XML cen apartamentów + katalog dane.gov.pl + strona admina do zgłoszenia do Ministerstwa.**

## Performance

| Metric | Value |
|--------|-------|
| Duration | ~30 min |
| Started | 2026-03-12 |
| Completed | 2026-03-12 |
| Tasks | 3 auto + 1 checkpoint |
| Files modified | 1 (elementor-addon.php) |
| Files created | 1 (docs/jawnosc-cen.md) |

## Acceptance Criteria Results

| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Endpoint cen mieszkań dostępny | Pass | /ceny-mieszkan.xml zwraca HTTP 200, Content-Type: application/xml, struktura <lokale> poprawna |
| AC-2: MD5 companions poprawne | Pass | /ceny-mieszkan.md5 i /dane-gov-pl.md5 zwracają 32-znakowy lowercase hex |
| AC-3: Katalog dane.gov.pl zgodny z XSD | Pass | /dane-gov-pl.xml zawiera <datasets>, URL w <resource> wskazuje na /ceny-mieszkan.xml |
| AC-4: Strona administracyjna z URL-ami | Pass | Narzędzia → Jawność Cen widoczne, URL-e i przyciski działają |

## Accomplishments

- Cztery publiczne endpointy XML wdrożone przez WP rewrite rules — bez konfiguracji serwera
- Transient cache 1h z automatyczną inwalidacją przy cronie dziennym
- Strona admina z URL-ami gotowymi do skopiowania i zgłoszenia do Ministerstwa
- Dokumentacja klienta w `docs/jawnosc-cen.md` — co i jak zgłosić do dane.gov.pl

## Files Created/Modified

| File | Change | Purpose |
|------|--------|---------|
| `wp-content/plugins/elementor-addon/elementor-addon.php` | Modified | +250 linii: rewrite rules, XML generators, template_redirect, admin page |
| `docs/jawnosc-cen.md` | Created | Instrukcja dla klienta: co zbudowano + kroki po stronie Ministerstwa |

## Decisions Made

| Decision | Rationale | Impact |
|----------|-----------|--------|
| XML przez czysty PHP string (htmlspecialchars ENT_XML1) zamiast DOMDocument | Brak gwarancji że ext-dom jest dostępne na hostingu | Bezpieczniejsze, działa wszędzie |
| Cache transient 1h, inwalidowany przez cron | Cron i tak działa raz dziennie — cache nie ma sensu trzymać dłużej niż 1h w razie ręcznych zmian | Balans między wydajnością a świeżością danych |
| Wszystko w elementor-addon.php | Zgodnie z boundaries — nie tworzyć osobnych plików | Mniej plików do zarządzania |

## Deviations from Plan

None — plan wykonany dokładnie zgodnie ze specyfikacją.

## Issues Encountered

None.

## Next Phase Readiness

**Ready:**
- Faza 02 kompletna — oba plany tej fazy nie istnieją (był tylko 02-01)
- Milestone v0.1 czeka na: plan 01-02 (widget HTML + CSS popup + JS handler)

**Concerns:**
- Plan 01-02 z fazy 01-historia-cen wciąż oczekuje na APPLY — należy go wykonać

**Blockers:**
- None dla fazy 02
- Plan 01-02 (faza 01) nadal nie wykonany — jeśli popup historii cen jest wymagany do v0.1

---
*Phase: 02-jawnosc-cen, Plan: 01*
*Completed: 2026-03-12*