# AGENTS.md — Phoenix Terminal (PT)

## 1. Rola i Przeznaczenie
PT (Phoenix Terminal) to dedykowana aplikacja giełdowa i analityczna z rodziny Phoenix.

Zawiera 100% logiki biznesowej, domenowej i prawdy o giełdzie (tickerach, wskaźnikach, portfelach, brokerage API, saldach monet, dywidendach itp.). Opiera się na silniku pphpc (Phoenix Core) oraz bazowym komponencie pphpa (Phoenix Application).

* Vendor Namespace (PSR-4): Phoenix\Terminal\ (mapowany na katalog src/)
* Silnik bazowy (używane namespaces):
  * Phoenix\Core\Database
  * Phoenix\Core\Router
  * Phoenix\Core\Wykres
  * Phoenix\Core\Library\Uzytki (zawsze PascalCase!)
* Punkt wejścia aplikacji: public/index.php

---

## 2. Mapa Katalogów i Odpowiedzialności

pt/
├── database/               # Definicje struktury i danych giełdowych
│   ├── schema.sql          # Główny schemat tabel bazy danych
│   ├── data.sql            # Dane początkowe/konfiguracyjne
│   └── views/              # SQL-owe widoki analityczne (01_tickery, 01_pozycje, 02_handel itp.)
│
├── public/                 # Katalog publiczny serwera WWW (DocumentRoot)
│   ├── index.php           # Główny front controller aplikacji
│   ├── sw.js               # Service Worker PWA
│   └── assets/             # Statyczne zasoby dedykowane dla Phoenix Terminal
│       ├── css/
│       │   ├── app.css     # Style specyficzne dla aplikacji Terminala
│       │   └── core.css    # Style bazowe CMS
│       ├── js/             # Logika kliencka JS (app.js, core.js)
│       ├── json/           # Manifest PWA (manifest.json)
│       └── img/            # Grafiki domenowe, tła i animacje (/assets/img/...)
│
├── src/                    # Główny kod PHP aplikacji (Namespace: Phoenix\Terminal)
│   ├── Controller/         # Kontrolery stron i widgetów Terminala
│   │   ├── Action/         # Kontrolery akcji domenowych i API (np. UpdateAction, StripeAction)
│   │   ├── Data/           # Kontrolery dostarczające surowe dane (np. TickerSzukajData)
│   │   ├── *Controller.php # Wiele dedykowanych kontrolerów (np. DywidendyController, WykresytaController, Ticker*Controller)
│   ├── Library/            # Biznesowe biblioteki domenowe aplikacji (Main, Ticker)
│   └── Service/            # Usługi biznesowe (TickerService)
│
├── views/                  # Szablony PHTML widoków (strony, widgety, podglądy)
│   ├── layout.phtml        # Główny szablon otoczki HTML
│   ├── cmstiles.phtml      # Widok główny (kafelki + umieszczony div #CMSIntro)
│   ├── dywidendy.phtml     # Widok dywidend wraz z wbudowanym wykresem
│   ├── wykresyta.phtml     # Widok do renderowania pełnych wykresów analitycznych
│   └── [wiele innych...]   # Specyficzne widoki dla kafelków, menu, monet, raportów
│
├── composer.json           # Autoload PSR-4 i zależności
└── composer.lock           # Spójne wersje pakietów

---

## 3. Złote Zasady Architektury i Standardy Kodu

### A. Nazewnictwo, Importy i PSR-4 / PSR-12
1. PascalCase dla Klas: Zawsze używamy wielkich liter w nagłówkach use oraz wywołaniach statycznych.
2. Klasa Uzytki (i inne biblioteki): Klasa narzędziowa `Uzytki` musi być zawsze poprawnie zaimportowana z przestrzeni `Phoenix\Core\Library\Uzytki`. Należy pamiętać, że jest to element Core, a nie samej aplikacji Terminala.
3. Generowanie Przycisków: Korzystamy z metod pomocniczych klasy Uzytki:
   $odswiez = Uzytki::buttonGeneruj("CMSWindowShow('Center', 'monety');", '⟳', 'Refresh');
   $close   = Uzytki::buttonCloseGeneruj();
4. Izolacja Domenowa: Klasy czysto biznesowe dla samej aplikacji (np. Ticker, kalkulatory giełdowe) należą do przestrzeni `Phoenix\Terminal\`. Nie przenosimy logiki czysto giełdowej aplikacji do rdzenia pphpc.
5. Zewnętrzne API i Brokerzy: Ponieważ klasy obsługujące zewnętrzne API (np. do brokerów) mogą być współdzielone przez różne serwisy, umieszczamy je bezpośrednio w `Phoenix\Core\Library` (np. obok klasy Uzytki). Sama integracja i docelowa obsługa danego brokera pozostaje w aplikacji (Terminal).
6. Framework Wykresów: Używamy klasy bibliotecznej z core `Phoenix\Core\Library\Wykres` do tworzenia wykresów za pośrednictwem Chart.js. Składanie wykresu następuje na backendzie poprzez definiowanie skal, etykiet i linii.

---

### B. Standard Routingu i Mapowanie Tras (Migracja ze starego silnika)
* Akcje rdzenne CMS (sesja, parametry systemowe): /core/action/update
* Akcje domenowe aplikacji (handel, blokady, errory tickerów): /action/update
* Widgety i podstrony asynchroniczne: /nazwa?render=widget lub /nazwa?render=inline
* Okna dialogowe (Modale):
  CMSWindowShow('Center', 'nazwa') (parametr render=window jest wstrzykiwany automatycznie przez JS, więc nie ma potrzeby dodawania końcówek .php ani .ajax).

---

### C. Model Renderowania i Odpowiedzi HTTP (Nyholm PSR-7)
1. Tryby parametru ?render=:
   * render=window / render=widget / render=inline / render=ajax ➔ Kontroler zwraca czysty wycinek HTML (fragment) zazwyczaj zbudowany ze zmiennych zaimportowanych z dedykowanego widoku .phtml. W oknach modali kontrolery mogą całkowicie zwrócić przygotowany ob_get_clean().
   * Brak parametru (bezpośrednie wejście z paska URL): Kontroler owija treść w główny layout.phtml.

---

### D. Sesje Użytkownika i Zarządzanie Uprawnieniami
Autoryzacja i ustawienia uprawnień przechowywane są w zmiennych globalnych `$_SESSION` kontrolowanych najczęściej na etapie `LoginAction`. Dostęp do funkcji aplikacji oparty jest o następujące znaczniki:

* `$_SESSION['CMSU']` – Przechowuje unikalne UID (User ID) aktualnie zalogowanego użytkownika (często używane w zapytaniach SQL do bazy danych, aby przypiąć pozycję lub saldo do usera).
* `$_SESSION['CMSL']` – Flaga logowania (wartość true oznacza, że użytkownik jest zalogowany). Wiele kontrolerów sprawdza jej obecność poprzez `!empty($_SESSION['CMSL'])`.
* `$_SESSION['CMSS']` – Status dostępu / Poziom (liczbowy, im większy, tym silniejsze uprawnienia).
* `$_SESSION['CMSR']` – Redaktor (Redactor), zazwyczaj uprawnienia `CMSS > 4`. Pozwala na zmiany operacyjne w tickerach (jak edycja raportów czy flagi).
* `$_SESSION['CMSP']` – Programista (Developer), zazwyczaj uprawnienia `CMSS > 6`. Umożliwia wyszukiwanie głębokich logów lub funkcji systemowych w TickerSzukajController.
* `$_SESSION['CMSA']` – Administrator (Admin), zazwyczaj uprawnienia `CMSS > 7`.
* `$_SESSION['CMSG']` – Super Administrator, zazwyczaj uprawnienia `CMSS > 8`. Przydaje się np. do funkcji `/action/update?tryb=reUID` pozwalającej administratorowi na logowanie na konta innych graczy.

Ważne jest, aby zabezpieczać dostęp na początku metod w kontrolerach. Przykład poprawnej weryfikacji dostępu dla użytkownika zalogowanego to:
```php
if (empty($_SESSION['CMSL'])) {
    // brak dostępu lub przekierowanie
}
$userId = $_SESSION['CMSU'] ?? 0;
```

---

### E. Standard Obsługi Okien i Loaderów (CMSWindowShow)
Funkcja JS CMSWindowShow:
1. Natychmiast wstrzykuje oryginalny loader GIF i czyści poprzednią zawartość okna.
2. Oczyszcza nazwę widoku z wiodących slashy oraz rozszerzeń .ajax / .php.
3. Dokleja parametr render=window do wywołania po to, by uchronić framework przed zwrotem pełnego układu strony (layout.phtml). Używane klasycznie na kafelkach z klasą `CMSLink` i `onClick`.