Automatizace údajů z e-mailů do Excelu
Nápad na projekt vznikl při rozhovoru s člověkem, který vede firmu zaměřenou na návrh a realizaci čistých prostorů. V některých pracovních procesech zaměstnanci ručně přepisují údaje z příchozích e-mailů do tabulek. Cílem proto bylo ověřit, zda lze část této opakované práce automatizovat.
Vytvořil jsem demonstrační aplikaci, která se po autorizaci připojí k testovacímu Gmailu, vyhledá odpovídající objednávkové e-maily a pomocí Gemini API z jejich obsahu získá kód a název položky, počet kusů, jednotkovou cenu, měnu a případné číslo objednávky. Strukturovaná data následně uloží do souboru Excel.
Projekt vznikal jako prototyp s testovacími údaji a hypotetickými podmínkami. Jeho účelem je ukázat technickou proveditelnost a možné snížení množství ručního přepisování. Před skutečným firemním nasazením by bylo nutné řešení dále otestovat, upravit podle reálného procesu a doplnit provozní bezpečnostní pravidla.
Architektura projektu
Aplikace je rozdělena do menších modulů. Každý soubor má jednu hlavní odpovědnost, takže lze jednotlivé části samostatně testovat a případné chyby hledat na konkrétním místě.
index.js je hlavní spouštěcí soubor. Řídí celý proces od přípravy Excelu přes přihlášení ke Gmailu až po zpracování nových e-mailů a uložení výsledků. Zároveň vypisuje průběh a souhrn do konzole.
auth.js zajišťuje OAuth autorizaci vůči Googlu. Aplikace díky tomu nepoužívá heslo k e-mailové schránce a získává pouze oprávnění potřebné pro čtení zpráv.
readEmail.js komunikuje s Gmail API. Vyhledává maximálně stanovený počet zpráv podle dotazu, například podle stáří a předmětu, načítá jejich text a předává také Gmail ID, předmět, odesílatele a čas přijetí.
gemini.js posílá text e-mailu do Gemini API. Model nevrací vizuálně vytvořenou tabulku, ale JSON podle předem určeného schématu. Výstup má proto stále stejné názvy polí a lze jej spolehlivěji zpracovat v další části programu.
excel.js vytváří nebo načítá sešit, kontroluje dříve zpracované zprávy, ověřuje data a zapisuje objednávky do jednotlivých listů. Obsahuje také nabídku pro pokračování v existujícím souboru nebo vytvoření nové evidence se zálohou předchozí verze.
testGemini.js, testExcel.js a testExcelData.js umožňují samostatně ověřit komunikaci s AI, vytvoření sešitu a zápis testovacích dat bez spuštění celé aplikace.
.env obsahuje lokální konfiguraci, například Gemini API klíč. Složka creds/ obsahuje neveřejné údaje potřebné pro Google OAuth. package.json popisuje projekt, jeho závislosti a příkaz pro spuštění.
Architektura struktury programu:
Jak to funguje
Po spuštění aplikace se nejprve připraví výstupní sešit. Pokud soubor ještě neexistuje, program vytvoří nový. Pokud již existuje, uživatel může pokračovat v dosavadní evidenci, začít znovu nebo aplikaci ukončit.
Následně proběhne přihlášení pomocí Google OAuth a aplikace se připojí k testovací e-mailové schránce. Gmail API vyhledá zprávy odpovídající nastavenému filtru. V demonstrační verzi jde například o zprávy staré nejvýše tři dny, jejichž předmět obsahuje slovo objednavka.
Ještě před použitím Gemini program porovná Gmail ID zprávy s evidencí již zpracovaných e-mailů. Pokud ID v evidenci existuje, zprávu přeskočí. Tím se zabrání opakovanému zápisu i zbytečnému volání AI API.
Text nové zprávy se odešle do Gemini API. Model podle JSON schématu vrátí číslo objednávky a seznam položek. Každá položka obsahuje kód, název, počet kusů, jednotkovou cenu a měnu. Pokud údaj v e-mailu chybí, model jej nemá domýšlet a vrátí prázdnou hodnotu určenou ke kontrole.
JavaScript výsledek ověří a teprve potom jej předá modulu pro Excel. Každá položka objednávky se zapíše na samostatný řádek. Celková cena vzniká výpočtem počtu kusů a ceny za jeden kus, takže tento výpočet není ponechán pouze na AI. Po dokončení se sešit uloží a konzole zobrazí počet přidaných, přeskočených a neúspěšně zpracovaných zpráv.
Průběh aplikace v konzoli:
Excel, duplicity a zálohy
Výsledný soubor objednavky.xlsx obsahuje dva listy. List Objednávky uchovává jednotlivé položky, jejich zdrojový e-mail, objednávkové údaje a vypočítanou celkovou cenu. List Zpracované e-maily slouží jako trvalá evidence zpráv, které už program dokončil.
Hlavním klíčem pro kontrolu duplicity je Gmail ID zprávy. Toto ID je pro konkrétní e-mail stabilnější než datum, předmět nebo jméno odesílatele. Pokud jeden e-mail obsahuje více položek, každý řádek dostane vlastní identifikátor složený z Gmail ID a pořadí položky.
Evidence je uložena přímo v Excelu, a proto zůstává zachována i po vypnutí programu. Při příštím spuštění lze pokračovat ve stejném souboru a doplnit pouze nové zprávy. Neúspěšně zpracovaný e-mail se za dokončený neoznačí, takže jej lze při dalším spuštění zkusit znovu.
Pokud uživatel zvolí možnost začít znovu, původní sešit se nejprve přejmenuje na záložní kopii s časovým údajem v názvu. Až potom aplikace vytvoří nový prázdný soubor. Tento postup chrání před nechtěnou ztrátou předchozí evidence.
Výstupní tabulka:
Ošetření chyb a bezpečnost
Program kontroluje chybějící API klíč, neplatnou Google autorizaci, nedostupné Gmail API, prázdný obsah zprávy, prázdnou nebo neplatnou odpověď Gemini a data, která neodpovídají očekávané struktuře. Chyba jednoho e-mailu nemusí ukončit zpracování ostatních zpráv. Závažná chyba při spuštění nebo ukládání se zobrazí v konzoli.
Při zápisu do Excelu může nastat problém, pokud má uživatel soubor současně otevřený. Aplikace proto tuto situaci rozpozná a upozorní, že je potřeba sešit zavřít. E-mail se do evidence dokončených zpráv přidává až po ověření získaných dat a přípravě jeho položek k zápisu.
API klíče, OAuth údaje a autorizační tokeny nejsou součástí veřejného zdrojového kódu. Lokálně se ukládají do neveřejných konfiguračních souborů, které musí být uvedeny v .gitignore. Při nasazení na server je vhodné použít proměnné prostředí nebo správce tajných údajů a omezit přístup pouze na účet aplikace.
Gmail autorizace používá pouze oprávnění pro čtení zpráv. Prototyp je určen výhradně pro testovací nebo necitlivé objednávky. E-maily s osobními, obchodně citlivými nebo jinak důvěrnými údaji nemají být bez právního, bezpečnostního a smluvního posouzení odesílány do externího AI API.
Výstup AI je vždy nutné považovat za automaticky získaný návrh dat. JSON schéma, nízká míra náhodnosti a následná validace snižují riziko chyb, ale nenahrazují kontrolu člověkem u neúplných nebo neobvyklých objednávek.
Výsledek a další rozvoj
Výsledkem je funkční demonstrační aplikace, která propojuje autorizované čtení Gmailu, strukturovanou extrakci údajů pomocí Gemini a trvalé ukládání objednávek do Excelu. Projekt řeší celý základní cyklus od nalezení zprávy až po kontrolu duplicity, výpočet ceny a uložení výsledku.
Při práci na projektu jsem si prakticky vyzkoušel OAuth, komunikaci s REST API, práci s JSON schématem, asynchronní JavaScript, validaci dat, zápis do XLSX a rozdělení aplikace do samostatných modulů. Důležitou částí bylo také postupné hledání chyb v autorizaci a sjednocení dat mezi jednotlivými částmi programu.
Další rozvoj může zahrnovat přesnější firemní pravidla, širší práci s HTML e-maily a přílohami, označení zpráv vyžadujících kontrolu, automatické spouštění na serveru, provozní logování a napojení na firemní informační systém. Před produkčním použitím by bylo nutné provést také bezpečnostní, právní a uživatelské testování.