update

.paul/phases/19-extras-translations-admin/19-01-SUMMARY.md

@@ -0,0 +1,129 @@
+---
+phase: 19-extras-translations-admin
+plan: 01
+subsystem: i18n
+tags: [admin-panel, extras, polylang, softra-pricelist, bilingual]
+
+requires:
+  - phase: 17-bilingual-packages-and-softra-errors
+    provides: resolve_locale() helper w REST proxy
+
+provides:
+  - Option carei_extras_seen (auto-collected PL names z Softra pricelist)
+  - Option carei_extras_translations (admin override PL → EN)
+  - Submenu wp-admin → Rezerwacje → Tłumaczenia extras
+  - Helpery: remember_extra_name, get_extras_seen, get_extras_translations, translate_extra_name
+  - REST /pricelist per-locale name replacement z fallbackiem do PL
+
+affects: []
+
+tech-stack:
+  added: []
+  patterns:
+    - "Auto-collect + admin override: seen list zbiera się runtime, admin wypełnia override, fallback do oryginału"
+    - "Option z autoload=false — lista seen może rosnąć, nie blokuje boot WP"
+
+key-files:
+  modified:
+    - wp-content/plugins/carei-reservation/includes/class-admin-panel.php
+    - wp-content/plugins/carei-reservation/includes/class-rest-proxy.php
+
+key-decisions:
+  - "Auto-collect przez update_option z autoload=false — prosty, brak wymogu osobnej tabeli DB"
+  - "Sortowanie seen alphabetically z SORT_NATURAL | SORT_FLAG_CASE — przyjazna kolejność w UI"
+  - "Zero zmian w JS frontendu — `?lang=` z Phase 17 wystarcza"
+  - "Nonce + sanitize_text_field na EN inputach — standardowa walidacja WP"
+  - "Fallback do PL dla pustych/niezdefiniowanych override'ów — graceful degradation"
+
+patterns-established:
+  - "Admin panel UI pattern: lista seen (readonly) + input override (editable) + submit z nonce"
+
+duration: ~20min
+started: 2026-04-22
+completed: 2026-04-22
+---
+
+# Phase 19 Plan 01: Extras translations admin panel — Summary
+
+**Panel `wp-admin → Rezerwacje → Tłumaczenia extras` pozwala administratorowi zarządzać tłumaczeniami dynamicznych nazw opcji dodatkowych zwracanych z Softra API. Auto-collect PL nazw + override EN + fallback do PL. Milestone v0.8 — 100% complete.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~20min |
+| Tasks | 2 auto + 1 human-verify completed |
+| Files modified | 2 |
+| New options in WP DB | 2 (seen, translations) |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Auto-collect PL names | Pass | Każdy request `/pricelist` dopisuje nowe nazwy do `carei_extras_seen` |
+| AC-2: Panel admin zarządza tłumaczeniami | Pass | Submenu, formularz z nonce, sanitize, redirect z komunikatem |
+| AC-3: REST pricelist zwraca EN gdy override | Pass | Per-locale replacement z fallbackiem do PL |
+
+## Accomplishments
+
+- **2 nowe WP options:** `carei_extras_seen` (lista PL names) + `carei_extras_translations` (map PL → EN)
+- **4 static helpery** w `Carei_Admin_Panel` — czysta API do używania z innych klas
+- **Submenu admin** z pełnym UX: lista alfabetyczna, info placeholder dla pustej listy, komunikaty sukcesu, nonce protection
+- **REST `/pricelist` integration** — runtime auto-collect + per-locale replacement, bez dotykania JS frontendu
+- **Reuse Phase 17** `resolve_locale()` helper — brak duplikacji logiki
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `includes/class-admin-panel.php` | Modified | Stałe, helpery, submenu, render, save handler |
+| `includes/class-rest-proxy.php` | Modified | `get_pricelist()` auto-collect + per-locale replacement |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| WP options zamiast custom table | Lista seen i map override są małe (<100 wpisów) — nadmierna inżynieria | Szybki deploy, standardowy WP pattern |
+| `autoload=false` dla options | Lista seen rośnie z czasem — nie ładujemy jej przy każdym request | Zero impact na WP boot performance |
+| Fallback do PL dla pustego override | User może nie tłumaczyć wszystkiego — nigdy nie crashujemy | Graceful degradation, spójna z Phase 17 |
+| Sortowanie SORT_NATURAL | UX: "Fotelik 1+2" przed "Fotelik 10" w liście | Przyjazna kolejność w panelu admin |
+| Zero zmian w JS | Phase 17 `?lang=` już działa, frontend nie musi wiedzieć o override | Minimalna surface area zmian |
+
+## Deviations from Plan
+
+### Summary
+
+| Type | Count | Impact |
+|------|-------|--------|
+| Auto-fixed | 0 | — |
+| Scope additions | 0 | — |
+| Deferred | 0 | — |
+
+**Total impact:** Plan wykonany 1:1.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+
+**Milestone v0.8 COMPLETE.**
+
+**System tłumaczeń teraz kompletny:**
+- Statyczne stringi PHP/JS: `.po`/`.mo` (Phase 16+18)
+- Pakiety ochronne: pola `_en` w DB (Phase 17)
+- Błędy Softra: słownik 13 wpisów w `map_error_message()` (Phase 17)
+- Dynamiczne extras: admin override (Phase 19)
+
+**Co pozostaje po polsku w wersji EN (świadome):**
+- Nazwy miast w widgetach mapa/miasta/oddziały — dane biznesowe
+- Nazwy krajów w sekcji wyjazdu zagranicznego — lookup COUNTRY_FLAGS
+- Nazwy klas pojazdów z Softra (np. "Opel Astra Combi") — dane biznesowe
+
+**Concerns:** None. Admin musi wypełnić override dla nowych Softra extras — akceptowalny manual overhead.
+
+**Blockers:** None.
+
+---
+*Phase: 19-extras-translations-admin, Plan: 01*
+*Completed: 2026-04-22*