scenar-creator/README.md

# 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í:**

```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
```

3) **Spusť testy:**

```bash
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
```

## Kontakt

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