Tagger/README.md

🏷️ Tagger

Desktopová aplikace pro správu a organizaci souborů pomocí hierarchických tagů (štítků).

✨ Hlavní funkce

• 📁 Rekurzivní procházení složek
• 🏷️ Hierarchické tagy (kategorie/název)
• 🔍 Filtrování podle tagů a textu
• 💾 Metadata v JSON souborech (.!tag)
• 🎬 Automatická detekce rozlišení videí (ffprobe)
• 🎨 Dvě verze GUI: klasické a moderní (qBittorrent-style)

🚀 Rychlý start

# Instalace závislostí
poetry install

# Spuštění (moderní GUI)
poetry run python Tagger_modern.py

# Nebo klasické GUI
poetry run python Tagger.py

📸 Screenshot

Moderní GUI (qBittorrent-style)

┌─────────────────────────────────────────────────────┐
│ 📁 Otevřít │ 🔄 │ 🏷️ │ 📅     🔍 [____]  Toolbar
├────────────┬────────────────────────────────────────┤
│ 📂 Štítky  │ Název    │Datum│Štítky│Velikost       │
│  ├─📁 Stav │ file1.txt│2025 │HD    │1.2 MB         │
│  │ ☑ Nové  │ file2.mp4│     │4K    │15 MB          │
│  ├─📁 Video│ file3.jpg│     │RAW   │845 KB         │
│  │ ☐ HD    │                                        │
├────────────┴────────────────────────────────────────┤
│ Připraven              3 vybráno │ 125 souborů      │
└─────────────────────────────────────────────────────┘

🎯 Použití

1. Otevři složku - Načti soubory ze složky (rekurzivně)
2. Vytvoř tagy - Hierarchická struktura (kategorie → tagy)
3. Přiřaď tagy - Označ soubory, vyber tagy
4. Filtruj - Klikni na tagy pro filtrování souborů
5. Vyhledávej - Textové vyhledávání v názvech

⌨️ Keyboard Shortcuts (moderní GUI)

• Ctrl+O - Otevřít složku
• Ctrl+T - Přiřadit tagy
• Ctrl+D - Nastavit datum
• F5 - Refresh
• Del - Smazat z indexu

🏗️ Architektura

┌─────────────────────────────────┐
│  Presentation (UI)              │  ← Tkinter GUI
├─────────────────────────────────┤
│  Business Logic                 │  ← FileManager, TagManager
├─────────────────────────────────┤
│  Data Layer                     │  ← File, Tag models
├─────────────────────────────────┤
│  Persistence                    │  ← JSON .!tag soubory
└─────────────────────────────────┘

📁 Struktura projektu

Tagger/
├── Tagger.py              # Entry point (klasické GUI)
├── Tagger_modern.py       # Entry point (moderní GUI)
├── PROJECT_NOTES.md       # ⭐ Kompletní dokumentace
├── src/
│   ├── core/              # Business logika
│   │   ├── file.py
│   │   ├── tag.py
│   │   ├── file_manager.py
│   │   └── tag_manager.py
│   └── ui/
│       ├── gui.py         # Klasické GUI
│       └── gui_modern.py  # Moderní GUI
└── tests/                 # 116 testů

🧪 Testování

# Všechny testy (116 testů, 100% core coverage)
poetry run pytest tests/ -v

# S coverage report
poetry run pytest tests/ --cov=src/core --cov-report=html

📝 Dokumentace

Veškerá dokumentace je v jednom souboru:

👉 PROJECT_NOTES.md ⭐

Obsahuje:

• Kompletní dokumentaci projektu
• Architektonická rozhodnutí (ADR)
• Coding standards
• Git workflow
• Known issues & TODO
• Debugování tipy
• Pravidla pro AI asistenty

🛠️ Technologie

• Python: 3.12
• GUI: Tkinter (standard library)
• Dependencies: Pillow (PIL)
• Package manager: Poetry
• Testing: pytest

📊 Metriky

• Řádky kódu: ~1060 Python LOC
• Testy: 116 (všechny ✅)
• Test coverage: 100% core modulů
• GUI verze: 2 (klasická + moderní)

🎯 Design Decisions

Proč JSON místo databáze?

• ✅ Jednoduchý backup (copy složky)
• ✅ Git-friendly (plain text)
• ✅ Portable (žádné DB dependencies)
• ✅ Metadata zůstanou při přesunu souboru

Proč Tkinter?

• ✅ Standard library (žádné extra deps)
• ✅ Cross-platform
• ✅ Dobře dokumentované

Proč Poetry?

• ✅ Deterministické buildy (poetry.lock)
• ✅ Dev dependencies oddělené
• ✅ Moderní nástroj

🐛 Known Issues

• Git merge konflikty s poetry.lock při merge devel→feature
• Dlouhé operace (ffprobe) blokují UI - TODO: threading

🚀 Plánované features

• Progress bar pro dlouhé operace
• Undo/Redo mechanismus
• Export do CSV/Excel
• Dark mode theme
• Drag & drop souborů

📄 License

MIT License

👤 Autor

honza

---

Pro detailní dokumentaci viz PROJECT_NOTES.md