Repository Guidelines

Struktura projektu i organizacja modułów

To repozytorium zawiera aplikację PHP w lekkiej architekturze MVC do zarządzania reklamami.

Punkty wejścia: index.php, ajax.php, api.php, cron.php, install.php
Kontrolery: autoload/controls/class.*.php (\controls)
Fabryki (dostęp do danych): autoload/factory/class.*.php (\factory)
Warstwa widoku: autoload/view/class.*.php (\view)
Integracje zewnętrzne (Google Ads, OpenAI, Claude, Meta): autoload/services/
Szablony: templates/<moduł>/
Style: layout/style.scss -> layout/style.css
Zmiany schematu bazy: migrations/*.sql (numerowane, przyrostowe)
Dokumentacja techniczna i notatki: docs/

Komendy build/test/development

php -S localhost:8000 - uruchamia lokalny serwer PHP z katalogu repozytorium.
php install.php - wykonuje oczekujące migracje bazy danych.
php install.php --with_demo - wykonuje migracje i ładuje dane demonstracyjne.
php install.php --force - wymusza ponowne uruchomienie wszystkich migracji (ostrożnie).
php -l ścieżka\do\pliku.php - sprawdza składnię pliku PHP.

Projekt nie wymaga standardowo pipeline Node/Composer do uruchomienia. SCSS kompiluje się zwykle przez VS Code Live Sass Compiler podczas edycji layout/style.scss.

Styl kodu i konwencje nazewnictwa

Zachowuj obecny wzorzec nazw plików/klas: class.Moduł.php, namespace małymi literami (np. \controls).
Nazwy klas: PascalCase; metody, zmienne i kolumny DB: snake_case.
Utrzymuj styl formatowania zgodny z edytowanym plikiem (historyczny styl nawiasów i wcięć).
Preferuj małe, statyczne metody w kontrolerach/fabrykach oraz jawne tablice danych do szablonów/JSON.

Wytyczne testowania

W repozytorium nie ma obecnie skonfigurowanego automatycznego zestawu testów (phpunit nie jest skonfigurowany).

Wykonuj ręczne testy smoke dla zmienionych tras, np. /campaigns/main_view, /users/settings.
Dla zmian w API/AJAX sprawdzaj odpowiedzi JSON zarówno dla sukcesu, jak i błędów.
Przed PR uruchamiaj php -l dla każdego modyfikowanego pliku PHP.

Zasady commitów i pull requestów

Stosuj krótkie, rzeczowe komunikaty commitów. Historia preferuje prefiksy Conventional Commits, szczególnie feat: (oraz fix:, refactor:, chore:).
Jeden commit powinien obejmować jeden spójny zakres zmian (schema, backend, UI).
PR powinien zawierać: cel zmian, listę zmienionych modułów/ścieżek, wpływ na migracje, kroki testowe i zrzuty ekranu dla zmian UI.
Dodawaj powiązane ID zadania/issue, jeśli istnieją.

Bezpieczeństwo i konfiguracja

Traktuj config.php i klucze API jako dane wrażliwe; nie commituj prawdziwych sekretów.
Tymczasowe pliki debugowe z tmp/ nie powinny trafiać do commitów produkcyjnych, chyba że jest to celowe.

2.8 KiB Raw Blame History