Dodanie nowego konta Gmail¶

Pełny walkthrough podpięcia nowej skrzynki Gmail do modułu Obsługi Klienta. Procedura jest osobna od podpięcia skrzynki Mailcow (które jest trywialne — adres + hasło IMAP).

Kiedy używać

Operator chce odbierać wiadomości z konta Gmail (np. firmowe support@<firma>.com w Google Workspace) w panelu, w jednej skrzynce z marketplace'ami.
Nie: jeśli firma używa Mailcow (*@aiofactory.pl itp.) — wtedy podpinasz przez Mailcow IMAP, patrz Inwentarz Usług → Mailcow.

Wymagane: 2-Step Verification w koncie Google

Gmail wymaga dla zewnętrznych klientów IMAP hasła aplikacji (App Password). Hasła aplikacji są dostępne TYLKO dla kont z 2-Step Verification. Włącz 2FA przed kolejnym krokiem (myaccount.google.com/security).

Krok 1 — wygeneruj hasło aplikacji Google¶

Najprostsza ścieżka — nie wymaga Google Cloud Console.

Otwórz myaccount.google.com/apppasswords zalogowany na konto, które chcesz podpiąć.
Pole „Nazwa aplikacji" → wpisz Panel AIO Factory (dowolne, służy tylko do rozpoznania w liście).
Kliknij Utwórz → Google pokaże 16-znakowe hasło, np. abcd efgh ijkl mnop.
Skopiuj hasło BEZ SPACJI — abcdefghijklmnop. Spacje w UI są tylko dla czytelności.

Hasło aplikacji widać tylko raz

Po zamknięciu okna Google nie pokaże go ponownie. Jeśli zgubisz — usuń wpis z listy i wygeneruj nowe.

Zapisz hasło tymczasowo (np. w Bitwardenie pod panel-aio / gmail-app-password-<adres>) — będzie potrzebne za chwilę.

Krok 2 — dodaj skrzynkę w panelu¶

panel.aiofactory.pl → Marketplace → Konfiguracja → Konta e-mail (/marketplace/config/email-accounts).

W lewej kolumnie Dodaj konto:

Pole	Wartość
Dostawca	`Gmail` (dropdown)
Etykieta	dowolna nazwa do rozpoznania, np. `Support PL Gmail`
Adres e-mail	pełny adres, np. `kontakt@firma.pl` (Workspace) lub `you@gmail.com`
Hasło aplikacji Google	16-znakowy ciąg z Kroku 1 (BEZ SPACJI)

Kliknij Dodaj konto.

Co się dzieje po kliknięciu¶

Panel wykonuje realne połączenie SMTP do Gmaila zanim zapisze konto:

Walidacja po stronie panelu — czy adres ma format *@*.*, czy hasło ma 16 znaków bez spacji.
Test SMTP (smtp.gmail.com:587, STARTTLS, AUTH LOGIN) — łączenie + uwierzytelnienie. Bez wysłania wiadomości.
Jeśli błąd — panel pokaże komunikat na czerwono (np. „SMTP odrzucił hasło dla you@gmail.com na smtp.gmail.com:587: 535 5.7.8 Username and Password not accepted").
Jeśli OK — zapis do Convex z hasłem zaszyfrowanym po stronie backendu.
Po zapisie panel automatycznie pobiera etykiety Gmail (gmail.users.labels.list) — żeby reguły przydziału pokazywały listę bez czekania na cykl IMAP fetch.

Konto pojawi się na liście z badgem Gmail + Hasło ustawione.

Gmail Workspace vs. zwykłe Gmail

Procedura identyczna dla obu. Jedyna różnica — konta Workspace mogą mieć politykę org wyłączającą hasła aplikacji. Jeśli myaccount.google.com/apppasswords zwraca „Ta opcja jest niedostępna dla Twojego konta", skontaktuj się z administratorem Workspace — musi włączyć opcję „Allow less secure apps and IMAP access" w admin.google.com → Security → Less secure apps.

Krok 3 — zsynchronizuj etykiety i ustaw reguły¶

Po dodaniu konta, panel zna listę etykiet Gmail. Zobacz je w karcie konta na liście — sekcja Etykiety Gmail. Jeśli pusta — kliknij Odśwież etykiety (przycisk z ikoną cyklicznych strzałek).

Następnie:

Marketplace → Konfiguracja → Reguły przydziału (/marketplace/config/cs-rules) — utwórz regułę typu „wiadomości z etykiety Reklamacje w koncie Support PL Gmail → przydziel do operatora Anna".
Obsługa Klienta → zakładka Zgłoszenia — od następnego ticku IMAP fetch (f/support/email/fetch_imap.py, co 1 min) pojawiają się nowe wiadomości jako zgłoszenia.

Pierwszy fetch po dodaniu konta dociąga ostatnie ~50 wiadomości (window startowy) — kolejne fetches dociągają tylko delta (Gmail historyId / IMAP UID NEXT).

Krok 4 — weryfikacja¶

Po ~5 minutach od dodania:

Wyślij testową wiadomość na adres skonfigurowany (z prywatnej skrzynki).
Otwórz Obsługa Klienta → Zgłoszenia w panelu — w ciągu minuty powinno pojawić się nowe zgłoszenie z odpowiednim badgem (Gmail / etykieta).
Odpowiedz z poziomu panelu („Odpowiedz" w wątku) — sprawdź, że odpowiedź dotarła do nadawcy (z kontakt@firma.pl, nie z aiofactory).

Jeśli zgłoszenie nie pojawia się w ciągu 5 minut:

Sprawdź logi flowu fetch IMAP: wmill job list --script-path f/support/email/fetch_imap --limit 10. Zła autoryzacja widoczna jako imap_authenticate failed: ....
Konfiguracja → Konta e-mail → upewnij się, że badge Hasło ustawione jest zielony. Jeśli nie — usuń konto i dodaj ponownie z nowym hasłem aplikacji.

Tryb zaawansowany — OAuth 2.0 (Google Cloud Console)¶

Hasło aplikacji jest prostszą ścieżką dla 99 % przypadków. OAuth 2.0 jest konieczny tylko wtedy, gdy:

Twoja organizacja zablokowała hasła aplikacji dla kont Workspace.
Chcesz scope-limited dostęp (gmail.readonly zamiast IMAP full inbox).
Wymóg compliance — token rotation z refresh_token.

Setup OAuth (~10 min)¶

Google Cloud Console (console.cloud.google.com) → utwórz nowy Project (lub użyj istniejącego panel-aio).
APIs & Services → Library → włącz Gmail API.
APIs & Services → OAuth consent screen → External user type → wypełnij ekran zgody (App name Panel AIO Factory, support email właściciela, scope: https://www.googleapis.com/auth/gmail.modify, https://www.googleapis.com/auth/gmail.readonly).
APIs & Services → Credentials → Create Credentials → OAuth client ID:
Application type: Web application.
Authorized redirect URIs: https://panel.aiofactory.pl/api/cs/email-accounts/oauth/callback.
Skopiuj Client ID + Client Secret → SOPS:

sops dashboard/.env.sops.yaml
# Dodaj:
GMAIL_OAUTH_CLIENT_ID=...apps.googleusercontent.com
GMAIL_OAUTH_CLIENT_SECRET=GOCSPX-...

Redeploy dashboardu: just deploy-dashboard (envs są wczytywane przy starcie kontenera).
W panelu, na ekranie Dodaj konto, wybierz Gmail (OAuth) → przycisk Połącz z Google — przekierowanie na consent screen → zgoda → callback zapisuje refresh_token w Convex.

Implementacja OAuth jest częściowa (stan 2026-05)

UI wspiera obecnie tylko ścieżkę App Password. Pełny przepływ OAuth z refresh_token jest przygotowany w schemie Convex (emailAccounts.gmailOAuth.refreshToken) ale UI flow „Połącz z Google" nie jest jeszcze zaimplementowany w panelu. Jeśli faktycznie potrzebny — to feature-request do dewelopera. Na bieżąco używaj App Password.

Pułapki i FAQ¶

Problem	Najpewniejsza przyczyna	Fix
`535 5.7.8 Username and Password not accepted`	Hasło aplikacji ma spację albo to zwykłe hasło konta	Usuń konto → wygeneruj nowe app password → wklej bez spacji
`imap_authenticate failed: Application-specific password required`	Konto bez 2FA — hasło aplikacji nieaktywne	Włącz 2-Step Verification w `myaccount.google.com/security`, potem retry
Etykiety Gmail puste mimo Hasło ustawione	Pierwszy refresh po dodaniu konta — czasem trwa	Kliknij Odśwież etykiety w karcie konta. Jeśli ciągle puste — Gmail API rate limit
Wiadomości wpadają z dużym opóźnieniem	Gmail IMAP idle nie używany — panel pollu co 1 min	Akceptowalne. Opóźnienie max ~60s
Konto zniknęło z listy bez akcji	Nie może się stać sam — sprawdź `audit_log` w Convexie kto wykonał DELETE	Restore z backupu (`Convex restore`) lub re-add
Po reset hasła aplikacji wszystko nadal pokazuje Hasło ustawione	Panel cache; restartuj Convexa albo poczekaj 30 s	Spróbuj usunąć i dodać ponownie

Powiązane¶

Obsługa Klienta — przewodnik — co dalej po podpięciu skrzynki (scenariusze, reguły).
Sekrety — gdzie OAuth client secret idzie, jeśli używasz wariantu OAuth.
dashboard/src/routes/marketplace/config/email-accounts/+page.svelte — kod UI.
dashboard/src/routes/api/cs/email-accounts/verify-smtp/+server.ts — endpoint walidacji SMTP.
windmill/f/support/verify_smtp_credentials.py — backend Windmilla weryfikujący poświadczenia.
windmill/f/support/email/fetch_imap.py — flow pobierający wiadomości z IMAP.