US Conflicts DB

Přehled

US_Conflicts_DB je monolitická, cross-platform grafické rozhraní aplikace pro správu a analýzu amerických vojenských konfliktů a intervencí od roku ~1900 do současnosti.

Primární cíle:

• Evidence a katalogizace US vojenských operací
• Import historických dat z Excel/CSV zdrojů
• Deduplikace a čištění dat pomocí fuzzy matchingu
• Webové obohacování záznamů (Wikipedia, Wikimedia, US archivy)
• Vyhledávání nových konfliktů přes Wikidata (discovery mode)
• Pokročilé filtrování a analýza podle času, regionu, aktérů
• Export pro další zpracování (CSV, XLSX, JSON)

Klíčové aspekty:

• ✓ Intuitivní grafické rozhraní bez učební křivky
• ✓ SQLite backend bez externího serveru
• ✓ Plná lokalizace (CZ, EN)
• ✓ Podpora legacy databází s automatickou migrací
• ✓ Fuzzy matching pro detekci duplikátů (RapidFuzz)
• ✓ Multi-threaded obohacování bez zamrzávání UI
• ✓ Offline režim (práce bez internetu)
• ✓ Session-based logování pro debugging

Klíčové Vlastnosti a Funkce

🗄️ Správa Databáze

• SQLite3 backend s moderním schématem (22 sloupců)
• Automatická inicializace DB při prvním spuštění
• First-run detection s auto-importem bundled datových sad
• Backup a restore strategie (Save DB As)
• Integrity check & repair
• Statistiky DB (počet záznamů, poslední aktualizace)

📥 Import & Export

• XLSX import s inteligentním mapováním sloupců
• CSV import (drag & drop i menu)
• Drag & Drop interface (Excel, CSV, DB)
• Legacy DB migrace (starý formát → nový)
• Bundled datasety (USA_intervence_*.xlsx)
• CSV export (kompletní nebo filtrované)
• XLSX export (s formatováním a formulemi)
• JSON export (pro inetegraci s dalšími systémy)

🔍 Filtrování & Vyhledávání

• Fulltext search (slova v názvu, poznámce, aktérech)
• Filtr podle země (dropdown s ISO2 kódy)
• Filtr podle regionu (Afrika, Asie, Evropa, Karibik, atd.)
• Filtr podle roků (od–do range)
• Advanced: kombinované filtry s AND/OR logikou
• Uložené vyhledávací dotazy (search history)
• Real-time refresh (okamžitý výsledek)

🧹 Deduplikace (RapidFuzz Fuzzy Matching)

• Token_set_ratio fuzzy string matching
• Konfigurabilní threshold (50–99%)
• Interaktivní dialog s náhledem párů
• Sloučení záznamů (merge sources)
• Smazání duplicit (keep one, delete others)
• Batch deduplikace (všechny záznamy najednou)

💎 Obohacování (Multi-Source Enrichment)

• Wikipedia EN/CZ (první výsledek, snippet)
• Wikimedia Commons (media, fotky)
• US Government archives (state.gov, cia.gov, archives.gov)
• Google search (volitelný, rate-limited)
• DuckDuckGo search (fallback)
• Relevance scoring (filtrování irelevantních výsledků)
• Status summary (new/supplemented/updated/unchanged/failed)
• Background processing (non-blocking UI)
• Progress bar s runtime/ETA

🔎 Discovery Mód (Wikidata)

• Vyhledání NOVÝCH konfliktů přes Wikidata API
• Globální běh (celý svět) + regionální filtr
• Automatická detekce nového konfliktu (dedup check)
• Vložení do DB s kompletními metadaty
• Scheduling a automatizovaný běh na pozadí

🎨 UI & UX

• Splash screen se skip tlačítkem + verze
• Tabelární přehled s sortováním sloupců
• Detailní panel pro jednotlivý záznam
• Dynamické barevné zvýraznění regionů
• Rotující vlajky států (WEBP/GIF/PNG formato)
• Language buttons (8 jazyků přepínání)
• Font size změna (Shift+Wheel na tabulce)
• Column visibility persistence
• Centralizované nastavení v dialogu se záložkami

UI & Workflow

Hlavní okno (MainWindow)

• Horní bar: Menu (File, Edit, Tools, Help) + Language buttons (8 jazyků)
• Levý panel: Filtry (země, region, roky, fulltext search)
• Střed: QTableWidget s názvy konfliktů, roky, zmínami
• Pravý panel: Detail zobrazení záznamů + flag (obrázek státu)
• Dolů: Status bar (počet záznamů, poslední byla akce)

Typické workflow (uživatel)

1. Filtrování: Vybrat zemi, region, roky
2. Vyhledávání: Zadat text v search field
3. Detailní prohlídka: Kliknout na řádek tabulky → vidět detail na pravě
4. Úprava: (pokud implementováno) Edit button → dialog s form poli
5. Obohacování: Menu Tools > Enrich selected → progress bar
6. Export: File > Export as CSV/XLSX

Dynamické zvýraznění regionů

Tabulka používá barevné kódy pro jednotivé regiony:

Rotující vlajky

• Aplikace zobrazuje vlajku státu v detail panelu
• Formáty: WEBP (preferováno), GIF, PNG
• Fallback: Používá QTimer pro animaci (refresh 100ms)
• Multi-state: Pokud záznam obsahuje více zemí, vlajky rotují

Import XLSX/CSV

XLSX Import s mapováním sloupců

Workflow:

1. Uživatel vybere XLSX soubor (File > Import XLSX)
2. App otevře první list a načte sloupce
3. Dialog s mapováním: Pro každý cílový sloupec v DB vybrat zdrojový ze XLSX
4. Preview: Zobrazit prvních N řádků po mapování
5. Duplikáty: Kontrola dedup check (fuzzy match na nazev)
6. Vložení: Insert do `conflicts` tabulky

CSV Import

• Drag & drop CSV na hlavní okno NEBO File > Import CSV
• Autodetekce separátoru (comma, semicolon, tab)
• Stejné mapování sloupců jako XLSX
• Import do DB

Bundled datasety

Při prvním spuštění (first-run) app hledá tyto XLSX soubory v aktuálním dir:

• USA_intervence_20251212.xlsx
• USA_intervence_ALL_REGIONS_CZ_DETAILED_20250823.xlsx
• conflicts.xlsx
• dataset.xlsx
• Jakýkoli *.xlsx v adresáři

Pokud nalezne, nabídne automatický import.

Parsování zemí

Funkce extrahuje ISO2 kódy z textu:

Drag & Drop interface

Aplikace přijímá drag & drop:

• .xlsx (Excel import)
• .csv (CSV import)
• .db, .sqlite, .sqlite3 (legacy DB import)

Filtrování & Vyhledávání

Fulltext search (LIKE operator)

Filtry v UI

• Search field: Fulltext across name, actors, description
• Country dropdown: Filtr podle ISO2 (US, GB, FR, ...)
• Region combobox: Afrika, Asie, Evropa, Karibik, Severní Amerika, Jižní Amerika, Oceánie
• Year range (spinbox): od_roku—do_roku
• Advanced (pokud implementováno): AND/OR/NOT kombinace filtrů

Kombinovaný filtr (SQL WHERE)

Real-time refresh

• Každá změna filtru (search, country, region, años) => instant query
• QTableWidget se refreshuje s novými řádky
• Status bar zobrazuje počet matching záznamů

Search history

(Pokud implementováno) QComboBox uchovává posledních 20 vyhledávacích dotazů

Klávesové Zkratky

Troubleshooting

PROBLÉM: "ModuleNotFoundError: No module named ''"

Příčina: není nainstalován

Řešení:

PROBLÉM: "Database locked"

Příčina: DB je otevřena v jiné aplikaci nebo procesu

Řešení:

1. Zavřít app a ostatní procesy s US_Conflicts_DB.sqlite3
2. Smazat files: US_Conflicts_DB.sqlite3-shm, US_Conflicts_DB.sqlite3-wal (dočasné)
3. Restartovat aplikaci

PROBLÉM: "Enrichment nefunguje, v UI nic"

Příčina: Chyba v web requestu nebo bez internetu

Řešení:

1. Zkontroluj internet connection
2. Zjisti IP a zkus ping example.com
3. Podívej se na logs/ obsah (detailní error message)
4. Zkontroluj firewall (DuckDuckGo, Wikipedia mohou být blocked)

PROBLÉM: "Deduplikace nefunguje"

Příčina: RapidFuzz není nainstalován

Řešení:

PROBLÉM: "UI se nezměnila po nastavení (settings)"

Příčina: JSON persistence se čte jen při startu

Řešení: Restartuj aplikaci

FAQ (Často Kladené Otázky)

Q: Kolik záznamů déže aplikace zvládnout?

A: SQLite je testován až na 100k+ záznamů bez problému. UI tabulka si drží všechny záznamy v paměti (QTableWidget), takže doporučuji limit 10–50k pro plynulou UI. Pokud potřebuješ víc, použij filtery abys zobrazil jen relevantní podmnožinu.

Q: Mohu exportovat do Google Sheets?

A: Aplikace sama ne, ale exportuješ do CSV/XLSX a pak nahraješ do Google Sheets ručně. Možní budoucího integraci přes Google Drive API.

Q: Jsou data šifrovaná?

A: SQLite je nešifrovaný (plain text). Pokud chceš šifrování, použij SQLCipher nebo šifruj celý soubor externě (bitlocker, veracrypt).

Q: Jakou verzi Pythonu potřebuji?

A: Python 3.10+. Ověřeno na 3.10, 3.11, 3.12.

Q: Mohu aplikaci přenášet na Linux/macOS?

A: Ano, je cross-platform. Soubory s cestami (flags, GFX) mohou vyžadovat drobné úpravy pro Windows-specific cesty.

Q: Jak se provádí backup?

A: Menu File > Save DB As → vybrat nové jméno/umístění. Ručně kopíruješ US_Conflicts_DB.sqlite3 do bezpečného místa.

Q: Co když chci přispívat?

A: GitHub Issues s bugreporty, feature requests. Pull requests se přijímají s podmínkou, že jsou testované a dokumentované.