orderPRO/AGENTS.md

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).