Scenar Creator

Moderní CGI aplikace pro vytváření časových plánů (timetablů) z Excelu nebo přímé editace v prohlížeči.

Co to dělá

Scenar Creator je webová aplikace, která vám pomáhá vytvářet a spravovat timetably (časové plány) pro konference, školení a další akce. Aplikace podporuje:

• ✅ Import z Excelu — načtení seznamu programů/přednášek a automatické vytvoření timetablu
• ✅ Inline editor — přímá editace programu v prohlížeči bez Excelu (JavaScript row management)
• ✅ Validace dat — kontrola překryvů, chybějících polí, neplatných časů
• ✅ Export do Excelu — vygenerovaný timetable se stáhne v profesionálním formátu
• ✅ Barevné rozlišení — jednotlivé typy programu s vlastními barvami
• ✅ Plná test coverage — 10 testů jednotek + integrace s Docker/Podman

Instalace a spuštění

Lokálně (bez Dockeru)

1. Klonuj a připrav prostředí:

git clone <repo>
cd scenar-creator
python -m venv .venv
source .venv/bin/activate  # na Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Spusť s jednoduchým CGI serverem:

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

3. Spusť testy:

pytest -q
# Bez integračních testů (Docker):
pytest -q -m "not integration"

Podman/Docker (produkční)

1. Postav image:

./scripts/build_image.sh
# nebo ručně:
podman build -t scenar-creator:latest .

2. Spusť kontejner:

./scripts/start_scenar.sh
# Aplikace bude dostupná na http://127.0.0.1:8080/

3. Zastavit kontejner:

./scripts/stop_scenar.sh

Git Hooks (pre-commit)

Aplikace obsahuje git hooks, které spouští testy před commitem.

Jednorazová instalace hooků:

chmod +x scripts/install_hooks.sh
./scripts/install_hooks.sh
# nebo ručně:
git config core.hooksPath .githooks

Použití:

• Běžný commit — spustí se rychlé testy (bez Dockeru):

  git commit -m "..."  # Spustí: pytest -q -m "not integration"
  

• Commit s integračními testy (Podman):

  RUN_INTEGRATION=1 git commit -m "..."
  

Workflow — Jak používat aplikaci

1️⃣ Import z Excelu (klasicky)

1. Otevři http://localhost:8000/cgi-bin/scenar.py
2. Klikni na tab "Importovat Excel"
3. Stáhni šablonu (scenar_template.xlsx)
4. Vyplň tabulku:
   - Datum (YYYY-MM-DD)
   - Začátek (HH:MM)
   - Konec (HH:MM)
   - Program (název přednášky)
   - Typ (kategorie: WORKSHOP, LECTURE, atd.)
   - Garant (vedoucí, autor)
   - Poznámka (dodatečné info)
5. Uploaduj soubor
6. Zadej popis typů a barvy
7. Stáhni Excel timetable

2️⃣ Inline Editor (bez Excelu)

1. Otevři http://localhost:8000/cgi-bin/scenar.py
2. Klikni na tab "Vytvořit inline"
3. Vyplň název a detail akce
4. V tabulce "Program (řádky)":
   - Přidej řádky tlačítkem "+ Přidat řádek"
   - Vyplň Datum, Začátek, Konec, Program, Typ, Garant, Poznámka
   - Smažování řádku: klikni "Smazat"
5. V sekci "Typy programu":
   - Přidej typy tlačítkem "+ Přidat typ"
   - Vyplň název typu, popis a zvolíkona barvu
   - Barvy se aplikují na timetable
6. Generuj scénář a stáhni Excel

Workflow — Jak používat aplikaci

Import z Excelu (nejčastěji)

1. Otevři http://localhost:8000/cgi-bin/scenar.py
2. Stáhni šablonu (scenar_template.xlsx)
3. Vyplň tabulku:
   - Datum: 2025-11-14
   - Začátek: 09:00
   - Konec: 10:00
   - Program: Úvodní přednáška
   - Typ: PŘEDNÁŠKA
   - Garant: Jméno lektora
   - Poznámka: Volitelně
4. Nahraj upravený Excel
5. Vyplň název a detail akce
6. Přiřaď barvy jednotlivým typům programu
7. Stáhni vygenerovaný timetable (Excel)

Struktura projektu

.
├── .github/copilot-instructions.md   # AI instrukce pro agenty
├── .githooks/
│   └── pre-commit                     # Git hook se spuštěním testů
├── cgi-bin/
│   └── scenar.py                      # Hlavní CGI aplikace (UI)
├── scenar/
│   ├── __init__.py
│   └── core.py                        # Jádro logiky (bez CGI)
├── scripts/
│   ├── build_image.sh                 # Postav Podman image
│   ├── start_scenar.sh                # Spusť kontejner
│   ├── stop_scenar.sh                 # Zastavit kontejner
│   └── install_hooks.sh               # Instaluj git hooks
├── templates/
│   └── scenar_template.xlsx           # Excel šablona
├── tests/
│   ├── test_read_excel.py             # Testy parsování
│   └── test_docker_integration.py     # Docker build test
├── tmp/                               # Výstupní soubory (gitignored)
├── Dockerfile                         # Runtime pro produkci
├── requirements.txt                   # Python balíčky (verze)
└── pytest.ini                         # Pytest konfigurace

Architektura

Core logika (scenar/core.py)

Obsahuje importovatelné funkce bez CGI závislostí:

• read_excel(file_content) — Parsování Excelu (pandas), detekce překryvů, validace
• create_timetable(...) — Tvorba OpenPyXL sešitu s timetablem
• validate_inputs(title, detail, file_size) — Bezpečnostní validace vstupů

Chybové typy:

• ScenarsError — obecná chyba
• ValidationError — vstupní validace
• TemplateError — problém s Excel šablonou

CGI wrapper (cgi-bin/scenar.py)

Komunikace s webem:

• step=1: Domovská stránka s formulářem
• step=2: Načtení Excelu, extrakce typů
• step=3: Generování timetablu a stažení

Podman/Docker

• Obraz: Python 3.12-slim + Apache2 + CGI
• Port: 8080
• DocumentRoot: /var/www/htdocs

Vývoj

Editace

• UI formuláře (HTML): cgi-bin/scenar.py
• Logika (bez CGI): scenar/core.py
• Šablona: templates/scenar_template.xlsx

Konvence

• Časy: %H:%M nebo %H:%M:%S
• Excel sloupce: Datum, Zacatek, Konec, Program, Typ, Garant, Poznamka
• Barvy: CSS hex → OpenPyXL AARRGGBB
• Bezpečnost: všechny vstupy validovány a escaped

Testování

# Unit testy
pytest tests/test_read_excel.py -v

# Integrační (Podman build):
pytest tests/test_docker_integration.py -v

# Všechno:
pytest -v

Troubleshooting

Podman machine (macOS):

podman machine start

ImportError scenar.core:

export PYTHONPATH="/path/to/repo:$PYTHONPATH"

Testy selhávají:

source .venv/bin/activate
pip install -r requirements.txt
pytest -q

Kontakt

Autor: Martin Sukaný — martin@sukany.cz