Zakladne ukony

komunikacia a generovanie kodu

  • Vzdy komunikujk somnou v slovenskom jazyku.
  • Kod, a komentare k nemu pis vyhradne v anglickom jazyku
  • Vsetky funkcionality vyvyjaj metodou TDD, rozhodni ci stacia unit testy, alebo treba integracne
  • Pouzivame php 8.5 a preto vyuzivaj vsetky jeho features
  • Pouzivame najnovisie symfony verziu a preto vyuzivaj vsetky jeho features
  • Vzdycky ked zapracujes niejaky zasadnu vec to systemu, poznac si do suboru .junie/guidelines.md velmi strucne co za funkcionalitu si spravil. aby o nej vedel pri dalsej praci. ale pis tam len podstatne architektonicke zmeny, nie bezne veci.

CSS & Twig Component Štandard 2026

Tento dokument definuje pravidlá pre organizáciu súborov a písanie kódu pre Symfony Twig komponenty. AI musí pri generovaní komponentov striktne dodržiavať túto adresárovú štruktúru a metodiku kódovania.

1. Adresárová štruktúra komponentov

Všetky Twig komponenty sa nachádzajú v priečinku src_component/. Každý komponent má vlastný podpričinok rozdelený podľa kategórie (napr. Layout, UI, Form). Na generovanie tejto štruktúry používaj command php bin/console make:sdc-component Layout:Hero a pridaj parameter --stimulus pokiaľ potrebujeme stimulus controller.

Vzorová štruktúra (príklad Hero):

src_component/
  Layout/
    Hero/
      Hero.php    # Logika komponentu (Twig Component class)
      Hero.html.twig       # Šablóna (Template)
      Hero_controller.js   # Stimulus kontrolér (ak je potrebný)
      Hero.css             # Štýly špecifické pre tento komponent


namespace App\Component\Layout\Hero;
use Tito10047\UX\TwigComponentSdc\Attribute\AsSdcComponent;
#[AsSdcComponent('Layout:Hero')]
final class Hero {
}

2. Pravidlá pre písanie CSS v komponente

Pri písaní štýlov v súbore Hero.css (alebo akomkoľvek inom komponentovom CSS) musí AI dodržiavať tieto pravidlá:

A. Zapuzdrenie (Scoping)

Všetky štýly v súbore komponentu musia byť obalené v hlavnej triede komponentu (Block v metodike CUBE), aby sa zabránilo úniku štýlov do globálneho priestoru.

  • Pravidlo: Používaj názov komponentu ako hlavný selektor.
  • Technológia: Používaj natívny CSS Nesting.

B. Vrstvy kaskády (@layer)

Všetky komponentové štýly musia patriť do vrstvy components. Tým sa zabezpečí, že utility triedy (vrstva utilities) ich môžu v prípade potreby prebiť.

C. CUBE CSS Metodika v rámci súboru

  • Block (B): Definuj vizuál komponentu (farby, border, fonty).
  • Exception (E): Stavy (napr. [data-state="active"]) definuj vo vnútri bloku.
  • Composition (C): Ak komponent vyžaduje špecifický vnútorný layout, rieš ho tu.

Príklad správne napísaného Hero.css:

D. Dark mode

pre vsetky komponenty musi byt spravena aj dark verzia. pouzi uz existujuce premenne

@layer components {
  /* Hlavný blok komponentu */
  .hero {
    position: relative;
    padding-block: var(--space-xl);
    background: var(--color-surface);

    /* Vnútorné elementy pomocou nestingu */
    & .hero__title {
      font-size: var(--size-step-3);
      line-height: 1.1;
    }

    /* Výnimky/Stavy pomocou data-atribútov */
    &[data-variant="dark"] {
      background: var(--color-dark);
      color: var(--color-white);
    }
  }
}

Stimulus controller

Nazov stimulus controllera ziskas tak ze pouzijes trait App\Component\Trait\Stimulus a jeho twig premennu {{ controller }} pouzivaj stimulus ctargety takto data-{{ controller }}-target="content" a data-action="click->{{ controller }}#expand"

4. Turbo Štandard

Symfony UX Turbo je integrované a aktívne (Turbo Drive).

A. Turbo Frames

  • Používaj pre nezávislé časti stránky, ktoré sa majú aktualizovať samostatne.
  • ID rámu musí byť unikátne: <turbo-frame id="frame_{{ component_id }}">.
  • Ak odkaz/formulár nemá meniť rám, použi data-turbo-frame="_top".

B. Turbo Streams

  • Používaj pre komplexnejšie zmeny (napr. pridanie položky do zoznamu, zobrazenie notifikácie).
  • Šablóny streamov pomenuj s príponou .stream.twig.
  • Podporované akcie: append, prepend, replace, update, remove, before, after.

C. Turbo Drive

  • Pre vypnutie Turba na špecifickom odkaze/formulári použi data-turbo="false".
  • Pri inicializácii JS knižníc tretích strán použi event turbo:load namiesto DOMContentLoaded.

5. Implementácia v Twig & PHP

  • HeroComponent.php: Musí odkazovať na správnu šablónu HeroHtml.twig.
  • HeroHtml.twig: - Hlavný element musí mať triedu zhodnú s názvom CSS bloku (napr. class="hero").
  • moze obsahovať atribút pre Stimulus kontrolér: {{ attributes.defaults({ 'data-controller': controller }) }}.
  • Triedy zapisuj v CUBE formáte: <div class="[ hero ] [ l-stack ] {{ classes|default('') }}">.

Inštrukcia pre AI: 1. Pri vytváraní nového komponentu vygeneruj všetky 3 súbory (PHP, Twig, CSS) podľa vyššie uvedenej štruktúry. JS generuj len ak je potrebne. 2. Vždy používaj @layer components a natívny nesting. 3. CSS píš tak, aby bolo nezávislé a znovupoužiteľné, pričom sa spoliehaj na globálne CSS premenné (variables). 4. Design Tokens Metodika: V projekte rozlišujeme dva typy premenných: - Tokeny (Primitíva): Prefix --clr- (napr. --clr-bureau-blue). Definujú fixné surové hodnoty. Nepoužívaj ich priamo v komponentoch, ak existuje sémantický ekvivalent. - Sémantika (Systém): Prefix --color- (napr. --color-primary, --color-surface). Tieto sa menia podľa témy (light/dark). Komponenty by mali primárne používať tieto premenné.

Obrazky

Obrazky pridavame pomocou komponenty tito10047/progressive-image-bundle tymto stylom:

<twig:pgi:Image 
    src="images/hero.jpg" 
    sizes="sm:12 md:6@landscape lg:[100%]@square xl:[500x600]"
    alt="Responsive hero image" 
    :preload="false"
/>

pricom ratia si definujeme v

progressive_image:
    responsive_strategy:
        ratios:
            landscape: "16/9"
            portrait: "3/4"
            square: "1/1"

breakpointy pozname xs,sm,md:,lg,

Názvoslovie (Hierarchia)

  • Ministerstvo (Ministry) (Celý web – Ministerstvo Satiry)
  • Odbor (Department) (Tých tvojich 5 hlavných kategórií, napr. Odbor domáceho chaosu)
  • Referát (Section) (Konkrétna téma, napr. Referát stratených lyžičiek)
  • Konanie (Proceeding) (Konkrétny typ listu/priestupku, ktorý si človek vyberie)
  • Podnet / Prípad (Case) (Konkrétna objednávka od zákazníka)

Databáza

  • mygrácie psúštame pomocou príkazu php bin/console doctrine:migrations:migrate --backup --no-interaction. ak migracia padne, treba zmazat vsetky tabulky v databazy a nahrat ich spat zo zalohy. nikdy sa nesnaz opravovat poskodenu databazu z padnutej migracie
  • entity generuj prikazom php bin/console make:entity <NazovEntity> --no-interaction
  • sql na databazu musis pustat tymto commandom php bin/console doctrine:query:dql

Spomienky

  • implementovaná podpora pre generate_promt: true v konfigurácii generovania obrázkov. Ak je voľba aktívna, pôvodný prompt sa najprv spracuje pomocou AiServiceInterface::generateText() a výsledok sa použije na generovanie obrázka.
  • implementované flash správy (FlashMessage komponent) s automatickým skrývaním a CUBE CSS štýlovaním, vložené globálne do layoutu.
  • implementované rozhranie AiServiceInterface pre generovanie textu a obrázkov. Predvolený poskytovateľ zmenený z OpenAI na Google Nano Banana (GeminiAiService s modelom gemini-2.5-flash-image).
    • GeminiAiService automaticky určuje optimálne aspectRatio a imageSize (1K, 2K, 4K) na základe požadovaných rozmerov podľa špecifikácie Google API.
  • v subore TwigComponentCssListener.php sa do hlavicky requesty vkladaju styly
  • implementovany VichUploaderBundle pre logo oddelenia
  • ProceedingsComponent: implementovany algoritmus pre dynamicky layout gridu (colspan/rowspan) pomocou striedajucich sa patternov tak, aby bol posledny riadok vzdy vyplneny. Vyčlenený do samostatnej služby ProceedingsLayoutCalculator.
  • ProceedingComponent: implementovaná detekcia pretečenia obsahu cez Stimulus a dynamické zvyšovanie rowspan/colspan s animáciou cez View Transitions API.
  • HeaderComponent: implementované hamburger menu pre mobilné zobrazenie pomocou Stimulus kontroléra a natívneho CSS nestingu.
  • ButtonComponent: univerzálny komponent pre tlačidlá s podporou pre ikony (vrátane animovanej pečiatky), veľkosti, farby a click animácie.
  • View Transitions API: implementované plynulé prechody pri navigácii z homepage na detail oddelenia pre názov a popis (sect-title-{id}, sect-desc-{id}). Keďže používame Turbo 7, integrácia je riešená manuálne cez event turbo:before-render v assets/app.js.
  • OpenAiService: implementovaná služba na generovanie textu (GPT-4o mini) a obrázkov (DALL-E 3) pomocou openai-php/client s konfiguráciou cez autowiring environmentálnych premenných.
  • AudioHelper: vyčlenená spoločná logika pre prácu so zvukom (fade, random start, duration, speed) do assets/utils/audio_helper.js. Implementovaná metóda stop() na bezpečné zastavenie zvuku a vyčistenie intervalov.
  • implementovaná entita SiteSetting a služba AppSettings pre globálne nastavenia webu.
    • SiteSetting používa objektový prístup (jeden riadok v DB) s fixnými poliami (napr. homepageHeroImage) a variabilným JSON poľom settings.
    • Služba AppSettings podporuje caching a transparentný prístup k nastaveniam cez get($key).
  • pridaný univerzálny command app:generate:images na generovanie hero obrázkov pre oddelenia (section) and fotiek vedúcich pre odbory (department) pomocou AI (DALL-E 3 a GPT-4o mini). Prerobený na CQRS (odosiela GenerateEntityImagesCommand, ktorý následne odosiela GenerateImageCommand).
  • implementovaný vlastný LiipImagine filter transparent, ktorý nahradí farbu na pozícii 1x1 (pixel [0,0]) transparentnosťou s nastaviteľným tresholdom. Používa natívnu imagick knižnicu pre maximálnu efektivitu. Registruje sa cez App\Imagine\Filter\Loader\TransparentFilterLoader.
  • SectionCrudController: pridané tlačidlo "View Proceedings", ktoré presmeruje na zoznam konaní vyfiltrovaných pre danú sekciu.
  • Implementované AI generovanie údajov pre konanie (Proceeding):
    • Pridaný GenerateProceedingDataCommand a jeho handler pre asynchrónne spracovanie cez Messenger.
    • AI generuje kompletné dáta vrátane požiadaviek (ProceedingRequirement) na základe zadanej témy a sekcie.
    • Pole intendedFor v entite Proceeding zmenené na JSON pole, upravená administrácia a šablóna pre zobrazenie zoznamu.
    • Integrované do administrácie sekcií cez vlastnú akciu a formulár na zadanie témy.
  • Implementované hromadné navrhovanie konaní (Bulk Proceeding Suggestion):
    • V SectionCrudController pribudla akcia AI Bulk Suggest Proceedings (ikona žiarovky).
    • AI synchrónne navrhne témy konaní na základe kontextu sekcie.
    • Výsledok sa nezapisuje priamo, ale vloží sa do formulára generate_proceeding_form, kde ho môže administrátor upraviť pred odoslaním na finálne vygenerovanie dát (cez Messenger).
  • Pole type v entite ProceedingTag bolo zmenené na enum ProceedingTagType (perpetrator, location, intensity).
  • Implementovaná administrácia pre ProceedingTag a jej prepojenie v ProceedingCrudController cez AssociationField s podporou autocomplete a filtrovania.