# Prompt: E-mailový tiketovací systém nad Gmail API > Zdroj: [webotvurci.cz/blog/tiketovaci-system-gmail-api/](https://www.webotvurci.cz/blog/tiketovaci-system-gmail-api/) — Webotvůrci s.r.o. Dokument je anonymizovaný: adresy, domény i cesty jsou placeholdery. > **Jak tenhle dokument použít:** Zkopíruj ho celý jako systémový/úvodní prompt pro svého coding agenta (Claude Code, Codex, Cursor…). Je psaný jako zadání + „lessons learned" z produkčního provozu podobného systému ve webové agentuře (Laravel + React, ~4 schránky, tisíce tiketů). Technologie si vyber vlastní — důležitá jsou pravidla a edge cases, ne framework. Sekce označené **⚠️ EDGE CASE** jsou věci, které nás v produkci reálně kously a stály nás opravný commit. --- ## 0. Role a cíl Jsi senior backend/fullstack vývojář. Stavíš interní tiketovací systém, kde **každé e-mailové vlákno = jeden tiket**. E-maily se čtou i odesílají přes **Gmail API** (jeden Google Workspace účet, více send-as aliasů = více „schránek"). Uživatelé (agenti) odpovídají z webového UI, odpověď musí odejít tak, aby ji klient viděl jako normální e-mail ve stejném vlákně a aby jeho další odpověď zase dorazila do stejného tiketu. Priority v tomto pořadí: 1. **Nikdy tiše neztratit e-mail** (příchozí ani odchozí). Raději duplicita jednou za čas než ztráta. 2. **Nikdy nepsat někomu, komu nemáme** (naše vlastní adresy, adresy formulářů, lidé, které klient z vlákna vyhodil). 3. Správné vláknování v Gmailu i Outlooku. 4. Až potom UX. --- ## 1. Klíčová architektonická rozhodnutí | Rozhodnutí | Volba | Proč | |---|---|---| | Gmail OAuth | **Oddělený OAuth klient od loginu** | Login OAuth (identita) a Gmail OAuth (offline refresh token, `gmail.modify`) mají jiné scopy i životní cyklus. Nemíchat. | | Gmail účet | Jeden účet, více send-as aliasů | Každý alias = jedna schránka v aplikaci. Aliasy se tahají z `users/me/settings/sendAs`. | | Příjem | **Polling každých 5 min** (ne Pub/Sub push) | Jednodušší, stačí pro interní podporu. Push přidej až když budeš potřebovat < 1 min latenci. | | Co pollovat | **Vždy jen `label:{štítek-schránky} is:unread`** | Nikdy nečíst celý inbox. Mailbox bez štítku se přeskočí a zaloguje. Štítky přiřazují Gmail filtry (nastaví admin v Gmailu podle To/alias). | | Po zpracování | **Archivovat** (odebrat `INBOX` + `UNREAD`), štítek nechat | Inbox v Gmailu zůstane čistý, zpráva je pořád dohledatelná přes štítek, dedup podle `gmail_message_id` brání opakovanému zpracování. | | Odesílání | `messages/send` s `threadId` | E-mail se objeví v Sent složce Gmailu a Gmail ho zařadí do vlákna. | | Dedup | `UNIQUE` na `ticket_messages.gmail_message_id` | `exists()` guard nestačí (viz race níže). | | Vláknování | `gmail_thread_id` primárně, `In-Reply-To`/`References` jako fallback | Gmail thread ID je spolehlivější, ale pokrývá jen zprávy, které Gmail sám spojil. | | SLA | Předpočítané deadliny na tiketu (`first_response_due_at`, `resolution_due_at`) | Levnější než počítat při každém čtení; breach hlídá cron každou minutu. | | Přístup | Per-schránka (`ticket_mailbox_user` pivot) | Kdo nemá schránku, tiket nevidí ani nehledá. | | AI | Draft → lidská kontrola → odeslání | AI nikdy neodesílá přímo. | | Tokeny | Šifrované v DB (`encrypted` cast) | Refresh token = trvalý přístup ke schránce. | --- ## 2. Google Cloud + OAuth ### Setup 1. Google Cloud Console → **APIs & Services → Library → Gmail API → Enable**. 2. **OAuth consent screen** — Internal (Workspace) nebo External. Scopy: - `https://www.googleapis.com/auth/gmail.modify` (čtení, odesílání, labely) - `https://www.googleapis.com/auth/gmail.settings.basic` (send-as aliasy) 3. **Credentials → OAuth 2.0 Client ID → Web application**, redirect URI přesně `https://tvoje-domena/api/tickets/gmail/callback` (+ localhost varianta pro dev). 4. ENV: `GMAIL_CLIENT_ID`, `GMAIL_CLIENT_SECRET`, `GMAIL_REDIRECT_URI`. ### Flow ``` 1. Owner klikne "Připojit Gmail" → GET /api/tickets/gmail/auth-url (auth. endpoint) → backend vygeneruje state (random 40 znaků), uloží do CACHE (ne session!) s user_id a TTL 10 min, vrátí URL na accounts.google.com/o/oauth2/v2/auth s: response_type=code, access_type=offline, prompt=consent, scope=..., state=... 2. Frontend přesměruje na URL. 3. Google → callback GET /api/tickets/gmail/callback?code=&state= (VEŘEJNÁ routa, bez auth) → Cache::pull(state) – musí existovat, jinak redirect ?error=invalid_state → POST oauth2.googleapis.com/token (grant_type=authorization_code) → GET gmail/v1/users/me/profile → emailAddress → uložit GmailAccount (singleton) – access_token, refresh_token, token_expires_at, scopes → redirect na frontend /settings/mailboxes?connected=1 ``` **⚠️ EDGE CASE – state v cache, ne v session.** Callback z Googlu přichází bez Sanctum/Bearer tokenu a mimo SPA session. Když jsme state drželi v session, callback ho neviděl. Cache s TTL + `pull()` (jednorázové) to řeší a zároveň brání replay. **⚠️ EDGE CASE – `refresh_token` přijde jen napoprvé.** Google vrací `refresh_token` pouze při prvním consentu (nebo s `prompt=consent`). Při re-autorizaci existujícího účtu **nepřepisuj refresh_token prázdnou hodnotou** — updatuj ho jen když v odpovědi je. Když vytváříš účet poprvé a refresh_token chybí, odmítni (`?error=no_refresh_token`), jinak budeš mít účet, který za hodinu přestane fungovat. **⚠️ EDGE CASE – token refresh s neúplnou odpovědí.** Google občas vrátí HTTP 200 bez `access_token` (intermitentní chyba). Bez guardu jsme přepsali platný token v DB `null`em a další request selhal na „Invalid token" → nutná ruční reautorizace. Validuj `access_token` v odpovědi a při jeho absenci vyhoď výjimku, DB nesahej. **Expirace:** považuj token za expirovaný **5 minut před** `token_expires_at` (žádný request nesmí běžet s tokenem, který vyprší uprostřed). **Send-as aliasy:** endpoint `GET /settings/sendAs`. V UI pro tvorbu schránky nabízej jen aliasy, které ještě žádná schránka nepoužívá. Aliasy jsou dostupné všem přihlášeným (reply editor je potřebuje pro dropdown „Od:"), správa propojení jen ownerovi. --- ## 3. Datový model (minimum) ``` gmail_accounts id, email, access_token(enc), refresh_token(enc), token_expires_at, scopes(json), connected_by_user_id, last_polled_at, is_active ticket_mailboxes id, gmail_account_id, name, email_address, gmail_label_id, gmail_label_name, signature, default_assignee_id, default_sla_policy_id, is_active, color, sort_order ticket_mailbox_user mailbox_id, user_id, role tickets id, number(unique seq), ticket_mailbox_id, assigned_user_id, client_id, subject, status, priority, requester_name, requester_email, requester_email_normalized(lower, index), cc_emails(json), tags(json), source(email|manual), gmail_thread_id(UNIQUE nullable), first_response_due_at, resolution_due_at, first_responded_at, resolved_at, closed_at, sla_*_breached, last_message_at, last_inbound_at, last_outbound_at, message_count, is_spam, merged_into_ticket_id ticket_messages id, ticket_id, user_id(null=inbound), direction(inbound|outbound), from_email, from_name, reply_to, to_emails(json), cc_emails(json), bcc_emails(json), subject, body_html, body_text, body_stripped, search_text, gmail_message_id(UNIQUE nullable), gmail_thread_id, message_id_header(INDEX!), in_reply_to, references_header, attachments_count, attachments_meta(json), attachments_processed_at, sent_at ticket_attachments id, ticket_message_id, filename, mime_type, size_bytes, gmail_attachment_id(TEXT, ne varchar!), source(gmail|upload), storage_path, storage_disk, is_downloaded, downloaded_at, purged_at ticket_comments id, ticket_id, user_id, type(note|system|ai_draft), content, is_promoted… ticket_forwards id, ticket_id, ticket_message_id, ticket_automation_rule_id, to_email, subject, attachments_count, lease_owner, gmail_message_id, sent_at UNIQUE(rule_id, message_id, to_email) ticket_sla_policies, ticket_automation_rules(+logs), ticket_canned_responses, ticket_presences ``` **⚠️ EDGE CASE – `gmail_attachment_id` je dlouhý.** Gmail attachment ID má běžně 200–400+ znaků. `VARCHAR(255)` ti ho ořízne/odmítne → přílohy se tiše nestáhnou. Použij `TEXT`. **⚠️ EDGE CASE – index na `message_id_header`.** Fallback vláknování dělá `WHERE message_id_header IN (...)`. Bez indexu je to full scan při každém příchozím e-mailu. **Číslo tiketu:** v Postgresu vlastní `SEQUENCE`, ne `MAX()+1` (race). Ukazuj uživatelům jeden identifikátor (my `id`), ne dva. **`requester_email_normalized`:** vždy lowercase, pro hledání a párování klienta. E-mailové adresy porovnávej **vždy case-insensitive** — všude, kde se objeví `in_array`, používej lowercase obou stran. --- ## 4. Příjem e-mailů (polling → tiket) ### Pipeline ``` cron každých 5 min (withoutOverlapping!) → pollAll() pro každý aktivní mailbox s aktivním Gmail účtem: - mailbox bez gmail_label_name → skip + warning (nikdy nečíst celý inbox) - listMessages("is:unread label:{label}") s paginací, strop 500 zpráv/poll - pro každou zprávu: processMessage() - při 429 → zastavit tento mailbox (zbytek dojede příští cron), když zbývá >10 zpráv → Slack alert - uložit last_polled_at processMessage(mailbox, gmailMessageId): 1. Dedup: existuje ticket_messages.gmail_message_id? → archivovat v Gmailu, skip 2. getMessage(id, format=full) 3. parseEmailHeaders() – From/To/Cc/Reply-To/Subject/Message-ID/In-Reply-To/References/Date/ Auto-Submitted/X-Auto-Response-Suppress + rekurzivní extractBody() 4. isAutoReply()? → archivovat, skip 5. isSentByUs()? (From je některá z našich schránek) → archivovat, skip 6. Tělo přes attachmentId? → dostáhnout 7. stripHtmlWrapper(body_html), resolveInlineImages(cid: → data:URI) 8. body_stripped = stripQuotedReply(text) 9. DB transakce: findExistingTicket() ? addInboundMessage() : createFromEmail() catch UNIQUE violation na gmail_message_id → race, skip jako duplikát 10. Po commitu: stáhnout přílohy, nastavit attachments_processed_at 11. archiveMessage() (removeLabelIds: [UNREAD, INBOX]) ``` **⚠️ EDGE CASE – race mezi cronem a ručním „Synchronizovat teď".** Dva pollery zpracují stejnou zprávu, oba projdou `exists()` guardem, oba vytvoří tiket. Řešení: `UNIQUE(gmail_message_id)` + insert v transakci + catch constraint violation → považovat za duplikát. Ruční sync navíc drž za 60s cooldownem (cache klíč) a spouštěj ho na pozadí přes frontu, ne v requestu. **⚠️ EDGE CASE – tělo zprávy není inline.** Gmail API někdy nevrátí `body.data`, ale `body.attachmentId` i pro `text/html`/`text/plain` (větší těla). Musíš si ID zapamatovat a dotáhnout přes `messages/{id}/attachments/{attId}`. Jinak vznikne prázdný tiket. **⚠️ EDGE CASE – NDR/bounce vytváří ghost tikety.** `Auto-Submitted` header pokryje out-of-office, ale bounce od mailer-daemonů často header nemá. Detekuj i podle předmětu (`mail delivery failed`, `undelivered mail returned`, `delivery status notification`, `failure notice`, `returned mail`, česky `doručení selhalo`, `nedoručeno`) a podle odesílatele (`mailer-daemon@`, `postmaster@`, `noreply@`, `no-reply@`, `bounce@`, `bounces@`). Hodnota `Auto-Submitted: no` NENÍ auto-reply. **⚠️ EDGE CASE – naše vlastní odchozí e-maily v inboxu.** Když někdo odpoví klientovi přímo z Gmailu (mimo aplikaci) a Gmail filtr zprávu oštítkuje, poll ji vidí. Skip podle `From ∈ naše schránky`. (Odpovědi odeslané aplikací mají `gmail_message_id` uložený, takže je zachytí dedup.) **⚠️ EDGE CASE – `References` s 1000 ID.** Dlouhá forwardovaná vlákna mají stovky Message-ID. `whereIn` s tisícem hodnot je pomalý a zbytečný — ber **posledních 20** (nejnovější jsou nejpravděpodobnější match). **⚠️ EDGE CASE – Reply-To rovné From.** Když `Reply-To == From`, ignoruj ho (ulož null). Jinak ti logika „Reply-To má přednost" zbytečně komplikuje adresaci. **⚠️ EDGE CASE – Date header.** Parsuj s try/catch a fallbackem na `now()`; převeď do svého timezone. Neplatné Date hlavičky existují. ### Parsování MIME (extractBody, rekurzivně) Pravidla, která jsme museli postupně přidat: - Filename bývá v `payload.filename`, **ale někdy jen v `Content-Disposition: attachment; filename="..."`** nebo RFC 5987 `filename*=UTF-8''...` (URL-encoded) → dekóduj. - **Příloha je:** (a) má filename + attachmentId; (b) má filename + inline data a není `text/html`/`text/plain`; (c) `Content-Disposition: attachment` i bez filename (doplň `attachment`); (d) má attachmentId, není inline obrázek a MIME není tělo (`text/html`, `text/plain`, `multipart/*`). - **Inline obrázek** = má `Content-ID` + `image/*` MIME. Ulož mapu `cid → attachmentId`, po parsování stáhni a nahraď `cid:xxx` (i `CID:`) za `data:image/...;base64,...` v `body_html`. Prohlížeč `cid:` nezobrazí. (Ano, zvětší to DB řádek; alternativa je servírovat obrázky přes vlastní endpoint. Pozor: tohle jsou synchronní Gmail API cally per obrázek — u newsletterů s 20 obrázky to poll zpomalí; do budoucna přesunout do jobu.) - Malé přílohy mohou přijít **inline v `body.data`** bez attachmentId → dekóduj base64url (`-_` → `+/`) se **strict** módem; `false` = poškozená data, záznam nevytvářej. - Loguj MIME strom (`mimeType [filename] (data inline|attachmentId, size)`) na debug úrovni — při ladění „proč chybí příloha" to ušetří hodiny. - **Strip ``, ``, `…`, ``** z `body_html` — budeš ho vkládat do vlastního iframe/wrapperu a nested HTML dokument rozbije rendering. - `stripQuotedReply`: odstraň řádky začínající `>`, bloky `On … wrote:` a česky `Dne … napsal(a):`. Výsledek ulož do `body_stripped` (náhled v seznamu, AI kontext). Originál nikdy nemaž. --- ## 5. Vláknování (threading) ### Příchozí → existující tiket 1. `tickets.gmail_thread_id == message.threadId` → match. 2. Fallback: `In-Reply-To` + posledních 20 z `References` → `ticket_messages.message_id_header IN (...)` → tiket té zprávy. 3. Nic → nový tiket. ### Odchozí odpověď — hlavičky ``` Message-ID: (ulož do message_id_header!) In-Reply-To: References: + ' ' + + Gmail API parametr threadId = ticket.gmail_thread_id ``` **⚠️ EDGE CASE – Outlook trhá vlákno.** Původně jsme stavěli `In-Reply-To` jen z poslední **příchozí** zprávy. Když agent odpověděl dvakrát po sobě (klient mezitím nepsal), druhá odpověď odkazovala na starou zprávu klienta a naše první odpověď v řetězci chyběla. Gmail to tolerantně sloučí, Outlook ne → klient viděl dvě vlákna. Rodič musí být **poslední zpráva bez ohledu na směr** a `References` = rodičovské `References` + rodičovo `Message-ID` (rodič už nese celý řetězec, takže vznikne kompletní RFC 5322 chain). **⚠️ EDGE CASE – ORM default ordering.** Měli jsme vztah `messages()` s výchozím `orderBy('sent_at' ASC)`. `->orderByDesc('sent_at')->first()` se k tomu jen **přidal** a vrátil NEJSTARŠÍ zprávu → špatné `In-Reply-To` i špatný příjemce. Když máš default ordering na relaci, u každého dotazu na „poslední zprávu" ho explicitně resetuj (`reorder()`). Řaď vždy `sent_at DESC, id DESC` (dvě zprávy ve stejné sekundě). **⚠️ EDGE CASE – Gmail `threadId` u compose.** U nově založeného odchozího e-mailu (compose) vezmi `threadId` z odpovědi `messages/send` a ulož na tiket — jinak klientova odpověď nenajde tiket přes primární cestu. **⚠️ EDGE CASE – Gmail zařadí do vlákna jen při shodném Subject.** Když posíláš do `threadId` e-mail s jiným předmětem (např. `Fwd:`), Gmail request odmítne. Přeposílání proto posílej **bez** `threadId` jako samostatný e-mail. **Header injection:** všechny hodnoty do hlaviček (Subject, From name, filename, In-Reply-To) projdou funkcí, která **nejdřív odstraní `\r`, `\n`, `\0`** a teprve pak případně RFC 2047 zakóduje (`=?UTF-8?B?...?=` jen pro non-ASCII). Předmět teče z cizího e-mailu; `"...\r\nBcc: attacker@..."` by jinak přidal hlavičku do e-mailu, který odesíláš ty. --- ## 6. Komu jde odpověď (nejvíc bugů za celý projekt) Tohle je oblast, kde jsme udělali **pět** opravných commitů. Zaveď tři jasně oddělené pojmy a každý počítej na jednom místě: ### 6.1 `replyRecipientEmail(ticket)` — do pole **To** ``` pro příchozí zprávy od nejnovější (limit 20): kandidát = zpráva.reply_to (pokud je) JINAK zpráva.from_email pokud kandidát ∈ našeAdresy(tiket) → další zpráva jinak → vrať kandidáta fallback: ticket.requester_email ``` **⚠️ EDGE CASE – poptávka z webového formuláře.** WordPress/Shoptet formulář pošle notifikaci `From: wordpress@nase-domena.cz`, `Reply-To: klient@firma.cz`. První odpověď šla správně na Reply-To. Jakmile ale klient odpověděl sám (jeho zpráva už Reply-To nemá), fallback na `requester_email` (= adresa formuláře, která nemá schránku) poslal další odpovědi do prázdna a klient zůstal jen v kopii. → Proto pořadí *Reply-To poslední příchozí → její From → starší příchozí → requester*. **⚠️ EDGE CASE – Reply-To stíní From jen u své vlastní zprávy.** První verze plošně vyloučila From každé zprávy, která kdy měla Reply-To, přes celý tiket. Když stejná adresa napsala znovu bez Reply-To, přeskočili jsme ji a odpověděli na starší Reply-To — klidně úplně jinému člověku. Pro **To** platí stínění jen v rámci jedné zprávy. Pro **CC** (viz níže) ticket-wide, protože tam je riziko opačné (nejhůř někdo chybí). ### 6.2 `requesterEmail(ticket)` — **identita** klienta (párování s CRM, předvyplnění zakázky) = `Reply-To ?: From` **PRVNÍ** příchozí zprávy. Schválně ne `replyRecipientEmail`: ten ukazuje na toho, kdo psal naposledy, a to může být kolega z kopie. Identitu tiketu drží ten, kdo ho založil. Při auto-linku na klienta zkus nejdřív Reply-To, pak From, pak firemní doménu (ne freemail — gmail.com/seznam.cz doménové párování vypni). ### 6.3 `ccFromLastMessage(ticket)` — prefill **CC** pro příští odpověď ``` poslední zpráva vlákna (jakýkoli směr): outbound → její cc_emails minus replyRecipient inbound → externalParticipants(To + CC + From) minus: našeAdresy(tiket), replyRecipient, Reply-To té zprávy a jím stíněný From, ticket-wide stíněné From adresy (formuláře) ``` **⚠️ EDGE CASE – CC se kumulovalo.** Napíše A s B v kopii, odpovíme, pak odpoví B a A vědomě vynechá. Naše další odpověď šla zase na A+B, protože `cc_emails` na tiketu jsme jen přidávali. **Kopie musí zrcadlit poslední zprávu vlákna** — přesně jako Reply-All v mailovém klientu. Kdo byl vyhozen, nesmí se tam vracet; kdo byl přidán, je tam hned. **⚠️ EDGE CASE – poslední zpráva je naše.** Agent u odpovědi ručně upraví CC. Přepočet, který koukal jen na příchozí zprávy, by jeho volbu zahodil. Když je poslední zpráva outbound, platí CC, které agent reálně použil. `sendReply()` proto ukládá použité CC na tiket. **⚠️ EDGE CASE – odesílatel z kopie.** Když odpoví kolega klienta (byl v CC), má v „To" nás a původního klienta v CC. Do `externalParticipants` proto patří i `From` zprávy — jinak by při naší odpovědi (To = původní klient) kolega z vlákna vypadl. **⚠️ EDGE CASE – naše send-as aliasy nejsou v tabulce schránek.** Agent odpověděl z aliasu, klient dal Reply-All, a náš alias se přilepil do CC tiketu. `našeAdresy(tiket)` = adresy schránek **+ `from_email` všech odchozích zpráv tiketu** (použitý alias je v DB, žádné volání Gmail API v cestě zpracování). **⚠️ EDGE CASE – klient dvakrát.** Starší tikety měly klienta v `cc_emails` (z doby, kdy jsme ho brali jako účastníka). Před odesláním vždy: `CC minus To`, `BCC minus (To + CC)`, case-insensitive, dedup. **⚠️ EDGE CASE – souběžný zápis CC.** Cron + ruční sync zpracují dvě zprávy jednoho vlákna současně, obě čtou stejné stale CC, pozdější update zahodí adresy té první. Přepočet CC dělej pod **row lockem** (`SELECT … FOR UPDATE`) a z nejnovější zprávy **v DB**, ne z právě zpracovávaného payloadu. **⚠️ EDGE CASE – cache našich adres.** Seznam adres schránek jsme cachovali 5 min. Po přidání nové schránky se její adresa 5 minut lepila do CC. Cache invaliduj při každém uložení/smazání schránky. ### 6.4 Varování v UI Pokud **poslední příchozí** zpráva měla externí příjemce, které agent do CC nedal, vrať po odeslání `warning: original_had_multiple_recipients` se seznamem — UI ukáže toast. (První verze koukala na první zprávu vlákna, takže lidé přidaní v průběhu konverzace varování nespustili.) ### 6.5 Frontend — prefill CC - Prefill klíčuj **`ticketId + recipient + join(cc_emails)`**, ne jen ID tiketu: refetch se stejným CC ruční úpravy nepřepíše, ale změna kopie příchozí zprávou se ukáže hned. - Při přechodu na jiný tiket **resetuj celý stav editoru** (CC, BCC, přílohy, next status). Pokud se komponenta neremountuje (detail se kreslí z cache seznamu), zůstanou tam data z předchozího tiketu. Pozor na React StrictMode — ref, který hlídá „prefill už proběhl", resetuj spolu se stavem. - Ukazuj vedle editoru **„Komu: …"**, ať agent vidí, kam odpověď jde, a tlačítko na zkopírování adresy. - Validace e-mailu přísnější než HTML5: vyžaduj TLD ≥ 2 znaky. Vstup do chip inputu splituj na `,`, `;` (Outlook) i whitespace. --- ## 7. Odesílání odpovědi ### Sestavení RFC 822 ``` From: =?UTF-8?B?...?= To: Cc: … (jen když neprázdné) Bcc: … Subject: Re: MIME-Version: 1.0 Message-ID / In-Reply-To / References (viz §5) Tělo (RFC 2387): s inline obrázky + přílohami: multipart/mixed > multipart/related > multipart/alternative s inline obrázky: multipart/related > multipart/alternative s přílohami: multipart/mixed > multipart/alternative jinak: multipart/alternative (text/plain + text/html, quoted-printable) Inline obrázek: Content-ID: , Content-Disposition: inline, base64 + chunk_split Příloha: Content-Disposition: attachment; filename="RFC2047", base64 + chunk_split ``` Payload pro API: `raw = base64url(rfc822)` bez paddingu, + `threadId`. ### Obsah odpovědi 1. Text agenta (HTML z editoru). 2. **Podpis**: vlastní podpis uživatele má přednost před výchozím podpisem schránky. Šablona s proměnnými (`{{jmeno}}`, `{{email}}`, `{{telefon}}`, `{{funkce}}`); hodnoty escapuj; pokud je šablona HTML, sanitizuj (strip `script/style/iframe/object/embed/form`, `on*=` atributy, `javascript:` v href/src). 3. **Inline obrázky**: frontend před odesláním vytáhne `` z HTML do `File` objektů s CID (`inline_images[]` + `inline_image_cids[]` ve FormData) a v HTML nahradí `src="cid:…"`. Backend udělá totéž ještě jednou jako defense-in-depth (fast-path: když HTML neobsahuje `data:image`, regex přeskoč). 4. **Do DB** ulož `body_html` s obrázky **obnovenými zpět na data-URI** (prohlížeč `cid:` nezobrazí) — ale **bez** citované historie. 5. **Citovaná historie** (jen do odeslaného MIME, ne do DB) — viz níže. **⚠️ EDGE CASE – 49MB e-mail a OOM (nejdražší bug).** První verze citovala do každé odpovědi **celé vlákno** z plného `body_html`. Klientův mail klient nám naši citaci poslal zpět, my ji uložili v plné délce a příště ocitovali znovu → každá výměna velikost ~zdvojnásobila. Po 26 zprávách 49 MB, `memory exhausted`. Pravidla: - Cituj **jen poslední zprávu vlákna** (dělá to tak Gmail i Outlook; ta sama nese starší citace, růst je lineární). - Když je poslední zpráva **naše odchozí** (agent odpovídá podruhé v řadě), přibal i **poslední příchozí** — odchozí zprávy mají v DB jen napsaný text bez citace, takže samotná citace naší odpovědi by neobsahovala dotaz klienta. - **Rozpočet 200 kB na celou citaci** (HTML i text zvlášť); ořez přes `mb_strcut` (nikdy uprostřed UTF-8 znaku) + `[…zkráceno…]`. - `` v citaci nahraď placeholderem `[vložený obrázek]`. - Zprávy načítej **po jedné cíleným dotazem**, ne `->get()` nad celým vláknem. **⚠️ EDGE CASE – Gmail 5MB JSON limit vs. inline screenshoty.** Base64 obrázky v `body_html` snadno překročí limit JSON endpointu (5 MB po base64) i nginx buffery → opaque 500 bez záznamu v Sentry. Řešení: extrakce do CID příloh (výše) + **nad ~3,5 MB syrových dat posílej přes upload endpoint** `upload/gmail/v1/users/me/messages/send?uploadType=multipart` (limit 35 MB). Multipart tělo skládej do **streamu** (`php://temp`), ne do stringu — u 20MB zprávy by ti konkatenace + HTTP klient držely 3 kopie v paměti. Velikost rozhoduj z `strlen(raw)`, ne z `strlen(json_encode(payload))` (to vyrobí další kopii o třetinu větší jen kvůli změření). **⚠️ EDGE CASE – tvrdý strop 25 MB.** Gmail odmítne cokoli nad 25 MB. Zkontroluj velikost **před** sestavením payloadu a vyhoď vlastní `MessageTooLargeException` → HTTP 413 s lidskou hláškou („E-mail má X MB, limit je 25 MB, pošlete odkazem"). Nehlásit do Sentry — není to chyba aplikace. **⚠️ EDGE CASE – limit příloh 17 MB, ne 18.** Gmail měří celou zprávu **po** base64 (+33 %) a `chunk_split` (+2,6 %). 18 MB dat = 24,7 MB v MIME + tělo + citace → přes limit. Inline obrázky **počítej do limitu spolu s přílohami** (původně neměly žádnou kontrolu a byly druhou cestou k OOM). ### Po odeslání — konzistence DB ``` sendResult = gmail.send(raw, threadId) if (!sendResult.id) → RuntimeException "Gmail nevrátil ID; e-mail MOHL odejít, ověřte v Gmailu" DB transakce: ticket.gmail_thread_id ??= sendResult.threadId TicketMessage(outbound, gmail_message_id, message_id_header, to/cc/bcc, body_html(display), …) ticket: message_count++, last_message_at, last_outbound_at, first_responded_at ??= now, cc_emails = použité CC catch → Log::critical + Slack "ORPHANED EMAIL" + výjimka "Neodesílejte znovu, Gmail ID: …" přílohy uložit lokálně MIMO transakci (selhání nesmí shodit už odeslaný e-mail) volitelně: next_status (výchozí 'resolved'), assigned_user_id (rozlišuj "nezasláno" od "explicitně null") ``` **⚠️ EDGE CASE – e-mail odešel, DB zápis selhal.** Bez ošetření agent vidí chybu, klikne znovu, klient dostane duplikát. Proto: neúplná odpověď Gmailu = výjimka s varováním; DB selhání po odeslání = critical log + Slack + explicitní hláška „neodesílejte znovu". **Další pravidla odesílání:** - Odpověď na `closed` tiket zamítni (nejdřív reopen). - Rate limit na `/reply` a `/compose` (my 30/min/uživatel) — chrání Gmail kvótu i před zneužitím. - Hlášky chyb v produkci **neodhalují `$e->getMessage()`** (může obsahovat tokeny/cesty); loguj plně, uživateli generickou hlášku. - `Ctrl+Enter` odešle; tlačítko Odeslat s tooltipem proč je disabled. --- ## 8. Přílohy ### Příchozí - Blocklist **přípon** (`exe bat cmd scr pif com vbs vbe js jse wsf wsh ps1 msi dll svg svgz`) a **MIME** (`application/x-msdownload`, `x-sh`, …). Gmail je stejně zablokuje na druhé straně. - **SVG nikdy** — ani jako přílohu, ani do náhledu (XSS přes `