scenar-creator/.github/copilot-instructions.md

Účel

Krátké, konkrétní instrukce pro AI agenta pracujícího v tomto repozitáři. Cílem je rychle pochopit architekturu, běžné konvence a kde dělat bezpečné úpravy.

Velký obraz (architektura)

• Jedna hlavní aplikace: cgi-bin/scenar.py — jednosouborová CGI aplikace, která vykresluje HTML formuláře a generuje výsledný Excel soubor.
• Statické soubory a šablona: templates/ (obsahuje scenar_template.xlsx).
• Webroot a temp: DOCROOT a TMP_DIR jsou v cgi-bin/scenar.py (výchozí /var/www/htdocs a /var/www/htdocs/tmp). Dockerfile také nastavuje DocumentRoot na /var/www/htdocs a vytváří /var/www/htdocs/tmp.

Důležité soubory

• cgi-bin/scenar.py — hlavní logika (upload, parsování Excelu pomocí pandas, tvorba Excelu pomocí openpyxl, HTML formuláře). Hledejte: funkce read_excel, create_timetable, get_program_types, konstanty DOCROOT, TMP_DIR.
• templates/scenar_template.xlsx — excelová šablona, kterou UI nabízí ke stažení.
• Dockerfile — ukazuje produkční runtime (Python 3.12-slim, instalace pandas a openpyxl, Apache s CGI, DocumentRoot /var/www/htdocs, port 8080).

Datový a HTTP tok (konkrétně z kódu)

• Kroková sekvence přes POST parameter step (1 → 2 → 3):
  • step=1: zobrazí formulář s nahráním Excelu (pole file).
  • step=2: načte Excel (pandas), zjistí unikátní typy (Typ) a zobrazí formulář pro zadání type_code_{i}, desc_{i}, color_{i}.
  • step=3: vytvoří výsledný sešit, uloží ho do TMP_DIR a odkaz vrátí jako /tmp/<safe_name>.

Pole formuláře a pojmenování

• Upload: pole file (v step=1).
• Základní metadatová pole: title, detail, debug (checkbox dává ladicí výstup), step.
• Dynamické pole pro typy: type_code_{i}, desc_{i}, color_{i} — exportované z dat a pak poskytnuté v step=2.
• Interně pro krok 3 se používá file_content_base64 k bezpečnému přenosu obsahu mezi kroky.

Konvence projektu

• HTML šablony nejsou separátní (JS/templating) — jsou inline v scenar.py. Upravujte opatrně: změny stylu/inl. HTML jsou v blocích if step == '1' / step == '2'.
• Soubor s výsledkem se ukládá s „safe“ jménem: povolena jsou alfanumerická znaky, . _ - a mezera. Pokud měníte pojmenování, ověřte odkazy /tmp/<name>.
• Barvy pro OpenPyXL: kód se převádí na formát AARRGGBB ('FF' + raw_color.lstrip('#')).

Chyby, logika validací a okrajové případy

• Parsování času: funkce normalize_time podporuje formáty %H:%M a %H:%M:%S.
• read_excel validuje datum/časy a sbírá error_rows. Překryvy časů detekuje a tyto řádky vyřadí (viz overlap_errors).
• Pokud chybí definice typu (Typ v Excelu není přiřazen v UI), skript formou HTML vrací chybu.

Závislosti a runtime

• Python: Dockerfile používá python:3.12-slim (projekt tedy cílí na moderní 3.12). Lokálně bude fungovat i Python 3.10+ (exports v repozitáři naznačují 3.10/3.9 přítomnost), ale pro přesnost použijte 3.12.
• Klíčové Python balíčky: pandas, openpyxl. Jsou instalovány v Dockerfile.

Vývojové workflow (rychlé ověření lokálně)

• Rychlý způsob pro lokální testování bez Dockeru (repo má cgi-bin/):

  1. Spusť z kořene repozitáře Python simple CGI server (vytvoří cgi-bin/ endpointy):

     python -m http.server --cgi 8000

  2. Otevři v prohlížeči: http://localhost:8000/cgi-bin/scenar.py

• Pro produkční podobu použij Dockerfile (Apache + CGI) — Dockerfile vystavuje port 8080.

Co upravovat a kde (rychlé reference)

• Změny chování Excelu / parsování: uprav read_excel a normalize_time v cgi-bin/scenar.py.
• Změny vzhledu formulářů: uprav HTML stringy v if step == '1' a if step == '2'.
• Cesty a přístupová práva: pokud měníš DocumentRoot/TMP, uprav i DOCROOT/TMP_DIR v scenar.py a odpovídající část v Dockerfile.

Příklady (konkrétní ukázky z kódu)

• Detekce typů: for key in form.keys(): if key.startswith('type_code_'): — při rozšiřování formulářů zachovat tuto konvenci.
• Barva pro openpyxl: color_hex = 'FF' + raw_color.lstrip('#').
• Safe filename: safe_name = "".join(ch if ch.isalnum() or ch in "._- " else "_" for ch in filename).

Poznámky pro agenta

• Buď konkrétní: ukaž přesné linie/názvy funkcí, pokud navrhuješ změnu. Např. "Uprav calculate_row_height v create_timetable když měníš rozměry řádků".
• Nevkládej náhodné závislosti — kontroluj import v cgi-bin/scenar.py a Dockerfile.
• Pokud budeš navrhovat CLI nebo refaktor na framework (Flask apod.), nejprve vyznač migraci: oddělit HTML do šablon a nasadit routy místo CGI.

---

Pokud chceš, upravím instrukci na míru (více/ méně detailů) nebo přidám krátký seznam rychlých úkolů (např. přidat requirements.txt, unit testy pro read_excel).