Jacek Pyziak
1b5e403c31
- Implement AllegroShipmentService for managing shipment creation and status checks. - Create ShipmentController to handle shipment preparation and label downloading. - Introduce ShipmentPackageRepository for database interactions related to shipment packages. - Add methods for retrieving delivery services, creating shipments, checking creation status, and downloading labels. - Implement address validation and token management for Allegro API integration.
59 lines
3.3 KiB
Markdown
59 lines
3.3 KiB
Markdown
# 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).
|