Systém nákupů v Telegramu: případ agentního vývoje bez kódu

# Jak techlead bez psaní kódu vytvořil systém nákupů v Telegramu: případ agentního vývoje

Když se interní nákupy v týmu změnily v chaos ztracených žádostí a nesouladných požadavků, technický lídr se rozhodl vytvořit systém na bázi Telegramu. Bez jediné řádky kódu, s využitím agentních systémů a jasné architektury, postavil řešení s OCR, moderací a bezpečným nasazením. Vysvětlíme, jak na to, aniž byste ztratili kontrolu nad kvalitou.

Problém: chaos místo nákupního procesu

V malých týmech nákupy často začínají neformálními domluvami. Nejprve papírky, pak poznámky, potom samostatný topic v Telegramu. Vznikne řád: pošlete odkaz, cenu, množství a odůvodnění. V praxi se ale část žádostí ztratí, část projde oklikou, někdy chybí cena nebo odůvodnění a lidé zapomenou na své požadavky. Výsledek: techlead tráví čas ne řízením nákupů, ale bojem s chaotickou formou. Klíčové zjištění: pokud proces ovlivňuje peníze, nesmí fungovat jako volná konverzace.

Infrastrukturní požadavky: od „botíka“ k systému

Původní nápad — jednoduchý Telegram-bot — rychle narazil na infrastrukturní složitosti. Kvůli nestabilnímu fungování Telegramu bez VPN bylo potřeba:

• Zahraniční VPS
• Vlastní VPN-síť
• Spolehlivý automatický restart
• Pohodlné nasazení
• Mechanismus rollbacku po neúspěšném releasu

To už není „skript na večer“, ale plnohodnotný inženýrský okruh. Zkušenosti ukazují: „jednoduchá automatizace“ často skrývá složitou infrastrukturu.

Agentní vývoj: akcelerátor, ne náhrada myšlení

Projekt byl realizován s pomocí ChatGPT a agentního systému, ale neobešlo se to bez aktivní účasti techleada. Proces zahrnoval:

• Formulaci úkolu a rozdělení rolí
• Upřesnění business logiky
• Ruční testování scénářů
• Odhalení rozporů a chyb
• Návrat k bodovým opravám
• Opakované testování

Agent zrychlil cyklus: zkrátil čas mezi objevením problému a ověřením nové realizace. Hlavní závěr: syntaxi kódu lze delegovat, ale systémové myšlení a architektura zůstávají klíčové. Bez jasného modelu procesu agent jen zrychlí realizaci nedokonalé logiky.

Odmítnutí „kouzel“: přechod k wizard-scénáři

První hypotéza — automatické extrahování dat z odkazu — se ukázala jako neudržitelná kvůli:

• Rozmanitosti webů
• Nestabilní struktuře stránek
• Nejednoznačným cenám
• Složitému renderování dat
• Nepřátelské logice marketplaceů

Místo toho byl zaveden wizard-scénář:

• Připojit screenshot
• Uvést odkaz
• Napsat odůvodnění
• Uvést množství
• Případně zadat cenu ručně (pokud OCR nerozpoznal)
• Zkontrolovat finální kartu před potvrzením

Tento přístup je méně „wow“, ale zajišťuje ovladatelnost — klíčový faktor pro operační procesy.

Proč LLM nestaly základem systému

Ačkoli lákadlo použít LLM pro zpracování požadavků bylo velké, padla volba na jednoduchý stack:

• Python
• Telegram bot framework
• SQLite
• Lokální OCR
• HTML-reporty na šablonách
• systemd pro služby a timery

Odůvodnění:

• Fungování na slabém VPS
• Nezávislost na externích API za běhu
• Absence placeného inference za každý požadavek
• Jednoduchost debugování
• Předvídatelnost chování

Toto řešení podtrhuje důležitý princip: ne každá úloha těží z nasazení AI. Někdy přísná FSM a validace přinášejí více než složité modely.

Systém stavů: základ spolehlivosti

Žádost se ukázala jako entita s životním cyklem zahrnujícím stavy:

• Draft
• Čeká na obrázek
• Čeká na odkaz
• Čeká na odůvodnění
• Čeká na potvrzení
• Na moderaci
• Vrácena k úpravám
• Přenesena do dalšího období
• Urgentní
• Odeslána

Pro řízení tohoto cyklu byla použita FSM. Příklad kódu:

class PurchaseWizard(StatesGroup):
    waiting_for_image = State()
    waiting_for_link = State()
    waiting_for_reason = State()
    waiting_for_qty_lots = State()
    waiting_for_lot_size = State()
    waiting_for_manual_price = State()
    waiting_for_confirmation = State()

a doménové stavy:

class PurchaseStatus(str, Enum):
    DRAFT = "draft"
    AWAITING_IMAGE = "awaiting_image"
    AWAITING_LINK = "awaiting_link"
    AWAITING_REASON = "awaiting_reason"
    AWAITING_QTY = "awaiting_qty_lots"
    AWAITING_CONFIRMATION = "awaiting_confirmation"
    COMPLETE = "complete"
    PENDING_MODERATION = "pending_moderation"
    RETURNED_FOR_REVISION = "returned_for_revision"
    APPROVED = "approved"
    CANCELLED = "cancelled"
    SENT = "sent"

Když proces zahrnuje role, peníze a deadliny, je nutné přejít od zpracování zpráv k řízení stavů.

Architektura: jednoduchost jako známka zralosti

Schéma systému:

Telegram user
    ↓
Bot handlers / FSM
    ↓
Purchase service
    ├── SQLite
    ├── OCR service
    ├── Moderation logic
    ├── HTML report builder
    └── Reminder / maintenance jobs
            ↓
        systemd service + timers

Struktura projektu:

purchase_bot/
├── app/
│   ├── bot/
│   ├── db/
│   ├── services/
│   ├── templates/
│   └── main.py
├── data/
│   ├── uploads/
│   ├── reports/
│   └── bot.db
├── scripts/
├── deploy/
└── README.md

Odmítnutí Dockeru a těžkých DB v první verzi umožnilo soustředit se na funkcionalitu. Pro interní nástroje je jednoduchá architektura známkou zralosti, ne slabosti.

Telegram UX: rozhraní místo proudu zpráv

Práce s Telegramem odhalila složitosti:

• Vytrvalé staré tlačítka
• Překrývání karet
• Paralelní existence starých a nových verzí žádostí
• Zpoždění v notifikacích
• Nejde se chování tlačítka „Zpět"
• Zacyklení obrazovek
• Smeti v chatu

Řešení: navrhovat bota jako systém obrazovek se stavy. Hlavní principy:

• Jediná aktuální obrazovka
• Odstranění zastaralých zpráv
• Bezpečné zpracování starých callback-tlačítek
• Oddělení pravidel pro menu, notifikace a pracovní karty

Tento přístup, ač ne dokonalý, zajišťuje denní použitelnost systému.

Reálný proces narušuje symetrii

Nasazení moderace, urgentních žádostí a přenosů mezi obdobími ukázalo, že reálný proces neodpovídá upraveným schématům. Například druhá etapa moderace může být zbytečným třením, pokud první žádost již plně zpracovala. Bylo nutné přebudovat logiku podle reálných potřeb, ne podle diagramů. To je známý pattern pro techleady: pokud schéma brání toku, lámat schéma.

Nejklikatější bugy — na rozhraních vrstev

Kritické chyby nevznikaly v hlavních funkcích, ale na přechodech vrstev. Například:

• Tlačítko „Potvrdit“ zamrzalo kvůli porovnání timezone-aware a timezone-naive objektů
• Nesoulad formátů dat mezi moduly
• Problémy synchronizace stavů při aktualizaci

Tyto bugy podtrhují důležitost pečlivého návrhu rozhraní mezi komponentami.

Co je důležité

• Architektura je důležitější než agenti: I při použití agentních systémů zůstává jasná architektura a systémové myšlení nezbytné. Agenti zrychlují realizaci, ale nenahrazují návrh.
• Ovladatelnost nad „chytrostí“: Pro operační procesy je spolehlivost a jednoduchost důležitější než automatizace složitých úkolů. Wizard-scénáře bývají efektivnější než pokusy o plnou automatizaci.
• Stavy, ne zprávy: Při rolích, penězích a deadlinech navrhujte systém jako řízený životní cyklus s explicitními stavy.
• Jednoduchost jako strategie: Pro interní nástroje se vyhněte architektonické nadváze. Minimální stack na slabém hardwaru zajišťuje spolehlivost a jednoduchou údržbu.
• UX v Telegramu vyžaduje disciplínu: Boti v Telegramu musí být navrženi jako systém obrazovek, ne proud zpráv. Odstranění zastaralých prvků a jediná obrazovka jsou klíčové pro uživatelský zážitek.

— Editorial Team