Reference: AI Parsing¶

Modul AI Parsing zajišťuje automatizované vytěžování dat z dokumentů (faktury, účtenky) pomocí externí služby Apertia.ai. Slouží jako most mezi příchozími soubory (e-mailové přílohy, dokumenty v CRM) a strukturovanými entitami v CRM (Faktury, Nabídky).

Architektura a tok dat¶

Proces zpracování je asynchronní a řízený stavy entity AiParsingRecord.

flowchart TD
    Email[Příchozí E-mail] -->|Hook| Extractor[EmailExtractor]
    File[Dokument v CRM] -->|Akce| Extractor

    Extractor -->|Vytvoření| Record[AiParsingRecord<br/>(Status: Draft)]
    Extractor -->|Upload| API[Apertia.ai API]

    API -->|200 OK| RecordSent[AiParsingRecord<br/>(Status: Sent)]

    API -.->|Webhook Callback| Webhook[ProcessExtractionCallback]
    Webhook -->|Update JSON| RecordReceived[AiParsingRecord<br/>(Status: Received)]

    RecordReceived -->|Trigger| Service[AiParsingRecordService]
    Service -->|Provider::process| RecordParsed[AiParsingRecord<br/>(Status: Parsed)]

    RecordParsed -->|Provider::apply| Entity[Cílová Entita<br/>(např. Přijatá faktura)]
    Entity -->|Link| RecordCompleted[AiParsingRecord<br/>(Status: Completed)]

Datové entity¶

AiParsingRecord¶

Hlavní entita sledující proces vytěžení jednoho dokumentu.

Pole	Typ	Popis
`status`	Enum	Stav procesu: `Draft` -> `Sent` -> `Received` -> `Parsed` -> `Completed` (nebo `Failed`).
`extractionEntityType`	Varchar	Cílový typ entity (např. `SupplierInvoice`).
`parsedData`	JSON	Strukturovaná data po zpracování providerem (připravená pro CRM).
`receivedData`	JSON	Surová data z externí AI služby.
`attachments`	File	Původní vytěžovaný soubor.
`parent`	Link	Vazba na entitu, odkud vytěžení vzniklo (např. Email).
`children`	Link	Vazba na vytvořenou cílovou entitu.

Komponenty systému¶

Extractors (Vytěžovače)¶

Získávají soubory a kontext ze zdrojových entit. - EmailExtractor: Zpracovává přílohy e-mailů. Kontroluje odesílatele/příjemce vůči povoleným seznamům. - DocumentExtractor: Umožňuje ruční spuštění nad entitou Dokument.

Providers (Poskytovatelé logiky)¶

Definují logiku pro konkrétní typ cílové entity. Mapují obecná data z AI do specifických polí CRM. - SupplierInvoiceProvider: Mapuje data na Přijatou fakturu (dodavatel, IČO, položky, částky). - InvoiceLikeProvider: Obecná třída pro fakturační doklady.

Integrace (Apertia API)¶

Komunikace probíhá s externím endpointem definovaným v administraci. - Autentizace: Bearer Token. - Upload: Multipart POST request se souborem. - Callback: Webhook přijímající JSON s vytěženými daty.

Konfigurace (System Settings)¶

Nastavení v data/config.php nebo přes UI administrace.

aiParsableEntityTypeList: Seznam entit povolených pro vytěžování.
aiParsableEmails: E-mailové adresy, ze kterých se má automaticky vytěžovat.
aiParsingEntityMatchingMode: Režim párování (createIfNotFound - vytvoří např. nového dodavatele, awaitExisting - čeká na existujícího).
aiParsingAutoCompletionAfterParsing: Pokud true, systém se pokusí automaticky vytvořit cílovou entitu ihned po přijetí dat (bez nutnosti schválení uživatelem).