Refactor: Oddělení business logiky + inline editor

- Nový modul scenar/core.py (491 řádků čisté logiky) - Refactored cgi-bin/scenar.py (450 řádků CGI wrapper) - Inline editor s JavaScript row managementem - Custom exceptions (ScenarsError, ValidationError, TemplateError) - Kompletní test coverage (10 testů, všechny ✅) - Fixed Dockerfile (COPY scenar/, requirements.txt) - Fixed requirements.txt (openpyxl==3.1.5) - Fixed pytest.ini (pythonpath = .) - Nové testy: test_http_inline.py, test_inline_builder.py - HTTP testy označeny jako @pytest.mark.integration - Build script: scripts/build_image.sh - Dokumentace: COMPLETION.md
2025-11-13 16:06:32 +01:00
parent 9a7ffdeb2c
commit b7b56fe15f
16 changed files with 2674 additions and 541 deletions
--- a/README.md
+++ b/README.md
@@ -1,70 +1,258 @@
 # Scenar Creator

-Jednoduchá CGI aplikace pro vytváření časových plánů (Excel) z nahraného Excelu se seznamem programů.
-
-Krátký, praktický popis, jak projekt spustit, testovat a kde hledat důležité části kódu.
+> 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á

- `cgi-bin/scenar.py` načte Excel s řádky obsahujícími Datum, Začátek, Konec, Program, Typ, Garant, Poznámka.
- Na základě polí `Typ` vytvoří HTML formulář pro přiřazení popisů a barev, a nakonec vygeneruje výsledný sešit (OpenPyXL) s časovou osou.
+**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:

-## Rychlý start (lokálně, bez Dockeru)
+- ✅ **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

-1) V kořeni repozitáře spusť jednoduchý CGI server (vyžaduje Python):
+## Instalace a spuštění
+
+### Lokálně (bez Dockeru)
+
+1) **Klonuj a připrav prostředí:**
+
+```bash
+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:**

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

-2) Alternativně připrav virtuální prostředí a spusť testy:
+3) **Spusť testy:**

 ```bash
-python -m venv .venv
+pytest -q
+# Bez integračních testů (Docker):
+pytest -q -m "not integration"
+```
+
+### Podman/Docker (produkční)
+
+1) **Postav image:**
+
+```bash
+./scripts/build_image.sh
+# nebo ručně:
+podman build -t scenar-creator:latest .
+```
+
+2) **Spusť kontejner:**
+
+```bash
+./scripts/start_scenar.sh
+# Aplikace bude dostupná na http://127.0.0.1:8080/
+```
+
+3) **Zastavit kontejner:**
+
+```bash
+./scripts/stop_scenar.sh
+```
+
+## Git Hooks (pre-commit)
+
+Aplikace obsahuje git hooks, které spouští testy před commitem.
+
+**Jednorazová instalace hooků:**
+
+```bash
+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):
+  ```bash
+  git commit -m "..."  # Spustí: pytest -q -m "not integration"
+  ```
+
+- Commit s integračními testy (Podman):
+  ```bash
+  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í
+
+```bash
+# 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):**
+```bash
+podman machine start
+```
+
+**ImportError scenar.core:**
+```bash
+export PYTHONPATH="/path/to/repo:$PYTHONPATH"
+```
+
+**Testy selhávají:**
+```bash
 source .venv/bin/activate
 pip install -r requirements.txt
 pytest -q
 ```

-## Docker (produkční přiblížení)
-
-Dockerfile vytváří image na `python:3.12-slim`, instaluje `pandas` a `openpyxl`, nastaví Apache s povoleným CGI a DocumentRoot na `/var/www/htdocs`. Nasazení:
-
-```bash
-docker build -t scenar-creator .
-docker run -p 8080:8080 scenar-creator
-# Pak otevři: http://localhost:8080/
-```
-
-## Testy
-
- Testy jsou v `tests/` a používají `pytest`.
- Přidal jsem testy pro funkci `read_excel` (happy path + invalid time). Spuštění viz výše.
-
-## Struktura projektu (klíčové soubory)
-
- `cgi-bin/scenar.py` — hlavní CGI skript (HTML generováno inline). Hledej funkce:
-  - `read_excel(file_content)` — parsování vstupního xlsx (pandas) → vrací (valid_data, error_rows)
-  - `create_timetable(...)` — vytváří OpenPyXL sešit
-  - `get_program_types(form)` — načítání dynamických polí `type_code_{i}`, `desc_{i}`, `color_{i}`
- `templates/scenar_template.xlsx` — šablona pro uživatele
- `tmp/` — místo, kam se výsledné soubory ukládají při běhu (v Dockeru `/var/www/htdocs/tmp`)
- `.github/copilot-instructions.md` — instrukce pro AI agenty (přehled konvencí a místa úprav)
-
-## Konvence a poznámky pro vývojáře
-
- HTML jsou inline stringy v `scenar.py` (sekce `if step == '1'`, `if step == '2'`, `if step == '3'`). Pokud budeš měnit UI, uprav tyto bloky.
- Výstupní soubor se ukládá s "safe" jménem: povolena písmena, čísla a `. _ -` a mezera.
- Barvy pro OpenPyXL: v kódu se převádějí na AARRGGBB pomocí `'FF' + raw_color.lstrip('#')`.
- Parsování času: `normalize_time` podporuje `%H:%M` a `%H:%M:%S`.
-
-## Doporučené další kroky
-
- Přidat `requirements.txt` (hotovo) s pevnými verzemi pro deterministické buildy.
- Přesunout jádro logiky z `cgi-bin/scenar.py` do importovatelného modulu (např. `scenar_core.py`) pro snazší testování a údržbu.
- Přidat GitHub Actions workflow, který spouští `pytest` na PR.
-
 ## Kontakt

-Autor: Martin Sukaný — martin@sukany.cz
+Autor: **Martin Sukaný** — martin@sukany.cz