# Projektowe zasady dla Codex

## Baza danych i migracje
- `DB_HOST_REMOTE` jest techniczne tylko dla agenta (Codex) do recznych operacji DB/migracji.
- Nie podpinaj `DB_HOST_REMOTE` do runtime aplikacji.
- Runtime aplikacji ma korzystac standardowo z `DB_HOST`.

## Zasady pisania kodu
- Kod ma być czytelny „dla obcego”: jasne nazwy, mało magii
- Brak „skrótów na szybko” typu logika w widokach, copy-paste, losowe helpery bez spójności
- Każda funkcja/klasa ma mieć jedną odpowiedzialność, zwykle do 30–50 linii (jeśli dłuższe – dzielić)
- max 3 poziomy zagnieżdżeń (if/foreach), reszta do osobnych metod
- Nazewnictwo:
  - klasy: PascalCase
  - metody/zmienne: camelCase
  - stałe: UPPER_SNAKE_CASE
- Zero „skrótologii” w nazwach (np. $d, $tmp, $x1) poza pętlami 2–3 linijki
- medoo + prepared statements bez wyjątków (żadnego sklejania SQL stringiem)
- XSS: escape w widokach (np. helper e())
- CSRF dla formularzy, sensowna obsługa sesji
- Kod ma mieć komentarze tylko tam, gdzie wyjaśniają „dlaczego”, nie „co”

## Utrwalanie stalych wymagan
- Trwale wymagania techniczne zapisuj w tym pliku (`AGENTS.md`) w root projektu.
- Dla zmiennych srodowiskowych utrzymuj tez wpisy w `.env.example`.
- Dokumentacje techniczna utrzymuj w folderze `DOCS`:
  - `DOCS/DB_SCHEMA.md` - aktualny schemat bazy danych (aktualizacja przy kazdej zmianie migracji/schematu),
  - `DOCS/ARCHITECTURE.md` - struktura klas, metod, modulow i przeplywow,
  - `DOCS/TECH_CHANGELOG.md` - chronologiczny log zmian technicznych (co i dlaczego).
- Przy kazdej nowej funkcji lub zmianie:
  - zaktualizuj odpowiednie sekcje w `DOCS/DB_SCHEMA.md`, `DOCS/ARCHITECTURE.md`, `DOCS/TECH_CHANGELOG.md`,
  - opisz nowe tabele/kolumny/indeksy/FK, nowe klasy/metody oraz zmiany kontraktow API.

## Wdrażanie poprawek
- Przed wdrożeniem zmian w kodzie, przeglądnij, poniższe dokumenty aby nowe kody dopasować do istniejacych już rozwiązań:
  - `DOCS/DB_SCHEMA.md` - aktualny schemat bazy danych
  - `DOCS/ARCHITECTURE.md` - struktura klas, metod, modulow i przeplywow
- Zrób plan i mi go przedstaw
- Po akceptacji przejdź do wdrożenia
- Po wdrożeniu przeprowadź testy

## Alerty i potwierdzenia UI
- W aplikacji uzywaj modulu `resources/modules/jquery-alerts` (build do `public/assets/js/modules/jquery-alerts.js` i `public/assets/css/modules/jquery-alerts.css`).
- Nie dodawaj nowych natywnych `alert()` / `confirm()` w widokach; dla potwierdzen akcji (np. usuwanie) korzystaj z `window.OrderProAlerts.confirm(...)`.

## Style frontendu
- Nie trzymaj styli CSS w plikach widokow (`resources/views/...`).
- Wszystkie style umieszczaj w plikach SCSS (`resources/scss/...`) i buduj do `public/assets/css/...`.
- Interfejs ma byc kompaktowy: preferuj mniejsze odstepy i gestszy uklad, tak aby pokazywac jak najwiecej informacji na jednym ekranie bez przewijania.

## Reuzywalnosc UI
- Nie powielaj kodu takich samych elementow widoku.
- Jezeli ten sam blok UI wystepuje w wiecej niz jednym miejscu, wydziel go do wspolnego komponentu (np. `resources/views/components/...`) i uzywaj ponownie.
- Zmiany wspolnego komponentu musza byc propagowane do wszystkich miejsc uzycia.

## Srodowisko lokalne (Windows)
- Komenda `php` jest dostepna z instalacji XAMPP (`C:\xampp\php\php.exe`).
- Jezeli `php` nie jest widoczne w terminalu, dodaj `C:\xampp\php` do zmiennej `PATH` (User).