# 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
│   │   ├── IntroController.php        # Ekran powitalny / onboarding
│   │   ├── CmstilesController.php     # Ekran główny z kafelkami/widgetami
│   │   ├── PerformanceController.php  # Analiza wyników/wykresy stóp zwrotu
│   │   ├── SaldoController.php        # Zwraca string salda lub widok
│   │   ├── MonetyController.php       # Historia monet i transakcji
│   │   ├── MenuController.php         # Menu nawigacyjne
│   │   └── Action/                    # Kontrolery akcji domenowych
│   │       └── UpdateAction.php       # Obsługa /action/update
│   │
│   └── Library/            # Biznesowe biblioteki domenowe aplikacji
│       └── Ticker.php      # Klasa giełdowa (wskaźniki FV, ROE, P/E, linki Yahoo/TV, flagi)
│
├── 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)
│   ├── intro.phtml         # Treść ekranu startowego
│   ├── monety.phtml        # Widok historii monet
│   ├── performance/        # Szablony modułu performance (page.phtml, widget.phtml)
│   └── menu.phtml          # Widok menu
│
├── 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:
   use Phoenix\Core\Library\Uzytki;
2. Generowanie Przycisków: Korzystamy z metod pomocniczych klasy Uzytki:
   $odswiez = Uzytki::buttonGeneruj("CMSWindowShow('Center', 'monety');", '⟳', 'Refresh');
   $close   = Uzytki::buttonCloseGeneruj();
3. Izolacja Domenowa: Klasy biznesowe (Ticker, kalkulatory giełdowe, brokerzy) należą wyłącznie do Phoenix\Terminal\. Nie przenosimy logiki giełdowej do rdzenia pphpc.

---

### B. Standard Routingu i Mapowanie Tras (Migracja ze starego silnika)
* Akcje rdzenne CMS (sesja, parametry systemowe):
  * Stare: process/CMSUpdate.ajax.php
  * Nowe: /core/action/update
* Akcje domenowe aplikacji (handel, blokady, errory tickerów):
  * Stare: process/update.ajax.php
  * Nowe: /action/update
* Widgety i podstrony asynchroniczne:
  * www/funkcje.ajax.php ➔ /funkcje?render=widget
  * www/handel.ajax.php ➔ /handel?render=widget
  * www/zalecenia.ajax.php ➔ /zalecenia?render=widget
  * www/saldo.ajax.php ➔ /saldo?render=inline
* Okna dialogowe (Modale):
  * Stare: CMSWindowShow('Center', 'nazwa.ajax')
  * Nowe: CMSWindowShow('Center', 'nazwa') (parametr render=window jest wstrzykiwany automatycznie przez JS)

---

### C. Zastąpienie mechanizmu uzytki::include2str
W starym kodzie proceduralnym używano uzytki::include2str('plik.ajax.php', ['oDB']).
W nowym silniku obiektowym odpowiednikiem jest bezpośrednie wywołanie metody index() kontrolera:

$oSaldo = new SaldoController();
$saldo = $oSaldo->index();

---

### D. 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 z widoku .phtml.
   * Brak parametru (bezpośrednie wejście z paska URL): Kontroler owija treść w główny layout aplikacji.
2. Standard PSR-7 / Nyholm:
   Kontrolery zwracają obiekty implementujące PSR-7 (Nyholm\Psr7\Response) lub czysty string opakowywany przez Router. Nigdy nie wykonujemy bezpośredniego header() ani exit wewnątrz kontrolerów.

---

### E. Standard Obsługi Okien i Loaderów (CMSWindowShow)
Funkcja JS CMSWindowShow:
1. Natychmiast wstrzykuje oryginalny loader GIF i czyści poprzednią zawartość okna (eliminuje miganie starych danych).
2. Automatycznie oczyszcza nazwę widoku z wiodących slashy oraz rozszerzeń .ajax / .php.
3. Dokleja parametr render=window do obiektu URLSearchParams(args).

Implementacja JS:
function CMSWindowShow(window, page, args = {})
{
    CMSWindowHide('Over');

    const $win = $("#CMSWindow" + window);
    const $shadow = $("#CMSShadow");

    const loaderHtml = `
        <div class="CMSKontener">
            <div class="CMSWnetrze CMSCenter">
                <img class="CMSLoading" src="/assets/img/anime/CMSLoading.gif" alt="Ładowanie..." />
            </div>
        </div>
    `;
    $win.html(loaderHtml);
    $shadow.fadeIn(200);
    $win.fadeIn(200);

    let cleanPage = page.toString().replace(/^\/+/, '').replace(/\.(ajax|php)$/, '');

    const params = new URLSearchParams(args);
    params.set('render', 'window');

    const url = `/${cleanPage}?${params.toString()}`;

    $.ajax({
        url: url,
        type: 'GET',
        success: function(response) {
            $win.html(response);
        },
        error: function(xhr) {
            console.error(`Błąd ładowania okna [${cleanPage}]:`, xhr.status, xhr.statusText);
        }
    });
}

---

### F. Zasoby Statyczne (Assets)
Wszystkie ścieżki do zasobów statycznych w widokach PHTML muszą być bezwzględne i wskazywać na katalog /assets/:
* Tła: style="background-image: url('/assets/img/bg/konta.png');"
* Animacje i ikony: src="/assets/img/anime/CMSLoading.gif"
* Style i skrypty: /assets/css/app.css, /assets/js/app.js

---

### G. Struktura DOM i Nakładanie Warstw
* Kontener #CMSIntro musi znajdować się na samym dole pliku views/cmstiles.phtml, aby naturalna kolejność rysowania w DOM stawiała go na wierzchu kafelków position: absolute bez sztucznych z-index.
* Główną funkcją startową JS jest CMSInit().
* Zapytanie AJAX dociągające intro wykonuje się wyłącznie wtedy, gdy selektor $('#CMSIntro') jest obecny w strukturze DOM.