Konfiguracja modułu poczty

Ready4Docs obsługuje konta pocztowe poprzez protokół IMAP z dwoma trybami synchronizacji:

Typy kont pocztowych

Typ konta	Opis	Synchronizacja
imap	Standardowy IMAP	Polling (co 10-60 sek)
imap-idle	IMAP z IDLE	Push (natychmiastowa)
m365	Microsoft 365	Graph API + Webhooks
google	Google Workspace	Gmail API + Push

Workery synchronizacji

System używa dwóch workerów do synchronizacji poczty:

1. Mail Sync Daemon (polling)

Obsługuje konta bez wsparcia IDLE. Sprawdza nowe wiadomości w interwałach 10-60 sekund.

# Status
sudo supervisorctl status ready4docs-mail-sync-daemon

# Logi
tail -f /home/ready4docs/public_html/backend/storage/logs/mail-sync-daemon.log

# Restart
sudo supervisorctl restart ready4docs-mail-sync-daemon

Konfiguracja supervisor: /etc/supervisor/conf.d/ready4docs-mail.conf

[program:ready4docs-mail-sync-daemon]
command=php /home/ready4docs/public_html/backend/artisan mail:sync-daemon --min-interval=10 --max-interval=60
autostart=true
autorestart=true
user=www-data
numprocs=1
stdout_logfile=/home/ready4docs/public_html/backend/storage/logs/mail-sync-daemon.log

2. Mail IDLE Worker (push)

Obsługuje konta z IDLE. Utrzymuje stałe połączenie z serwerem IMAP i otrzymuje powiadomienia o nowych wiadomościach natychmiast.

Kiedy jest potrzebny: Tylko gdy istnieje przynajmniej jedno konto z account_type = 'imap-idle'.

# Sprawdź czy są konta IDLE
php artisan tinker --execute="echo \App\Models\MailAccount::where('account_type', 'imap-idle')->count();"

# Jeśli są konta IDLE - zainstaluj worker
sudo cp /home/ready4docs/public_html/backend/supervisor/mail-idle.conf /etc/supervisor/conf.d/ready4docs-mail-idle.conf
sudo supervisorctl reread
sudo supervisorctl update

# Status
sudo supervisorctl status ready4docs-mail-idle:*

# Logi
tail -f /home/ready4docs/public_html/backend/storage/logs/mail-idle.log

Konfiguracja supervisor: /etc/supervisor/conf.d/ready4docs-mail-idle.conf

[program:ready4docs-mail-idle]
command=php /home/ready4docs/public_html/backend/artisan queue:work redis --queue=mail-idle --sleep=3 --tries=1 --timeout=0 --max-jobs=1
autostart=true
autorestart=true
user=www-data
numprocs=4
stdout_logfile=/home/ready4docs/public_html/backend/storage/logs/mail-idle.log
stopwaitsecs=3600

Sprawdzanie wsparcia IDLE

Przed dodaniem konta możesz sprawdzić czy serwer IMAP obsługuje IDLE:

# Test dla konkretnego konta
php artisan mail:test-idle <account_id>

# Test dla wszystkich kont IMAP
php artisan mail:test-idle

Serwery obsługujące IDLE:

• Gmail / Google Workspace ✅
• Microsoft 365 / Outlook.com ✅
• Większość nowoczesnych serwerów IMAP ✅
• Starsze serwery (np. niektóre hostingi współdzielone) ❌

Dodawanie konta pocztowego

1. Przez API (automatyczne wykrywanie IDLE)

POST /api/mail/accounts
{
  "email": "user@example.com",
  "imap_host": "imap.example.com",
  "imap_port": 993,
  "imap_encryption": "ssl",
  "smtp_host": "smtp.example.com",
  "smtp_port": 587,
  "smtp_encryption": "tls",
  "settings": {
    "username": "user@example.com",
    "password": "secret"
  }
}

System automatycznie:

1. Testuje połączenie IMAP
2. Sprawdza capabilities serwera
3. Ustawia account_type na imap-idle lub imap

2. Ręczna zmiana typu konta

php artisan tinker
>>> $account = \App\Models\MailAccount::where('email', 'user@example.com')->first();
>>> $account->update(['account_type' => 'imap-idle']);

Po zmianie na imap-idle uruchom IDLE worker (jeśli jeszcze nie działa).

Konfiguracja Google OAuth (Gmail / Google Workspace)

Ready4Docs obsługuje integrację z Gmail i Google Workspace poprzez OAuth 2.0. Umożliwia to bezpieczne połączenie bez konieczności włączania “Dostęp do mniej bezpiecznych aplikacji” lub generowania haseł aplikacji.

Wymagane kroki

1. Utwórz projekt w Google Cloud Console

1. Przejdź do Google Cloud Console
2. Utwórz nowy projekt lub wybierz istniejący
3. W menu nawigacji wybierz APIs & Services → Library
4. Wyszukaj i włącz Gmail API

2. Skonfiguruj OAuth consent screen

1. W menu wybierz APIs & Services → OAuth consent screen
2. Wybierz typ użytkownika:
   • Internal - tylko dla użytkowników z Twojej organizacji Google Workspace
   • External - dla wszystkich użytkowników Gmail
3. Wypełnij formularz:
   • App name: Ready4Docs
   • User support email: Twój email
   • Developer contact email: Twój email
4. W sekcji Scopes dodaj:
   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/gmail.send
   • https://www.googleapis.com/auth/gmail.modify
   • https://mail.google.com/
5. Zapisz i kontynuuj

3. Utwórz OAuth 2.0 credentials

1. W menu wybierz APIs & Services → Credentials
2. Kliknij Create Credentials → OAuth 2.0 Client ID
3. Wybierz Application type: Web application
4. Wypełnij formularz:
   • Name: Ready4Docs Mail Integration
   • Authorized redirect URIs:

     https://your-domain.com/api/auth/google/callback
     http://localhost:8000/api/auth/google/callback  # dla dev

5. Kliknij Create
6. Zapisz Client ID i Client Secret - będą potrzebne w konfiguracji

4. Skonfiguruj backend (Laravel)

Dodaj credentials do pliku .env:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=https://your-domain.com/api/auth/google/callback

Uwaga: GOOGLE_REDIRECT_URI jest opcjonalne - domyślnie używa APP_URL/api/auth/google/callback

5. Dodaj konto Google w Ready4Docs

1. Zaloguj się do Ready4Docs
2. Przejdź do Poczta → Konta
3. Kliknij Dodaj konto
4. Wybierz Gmail / Google Workspace
5. Podaj adres email (np. user@gmail.com lub user@twoja-firma.com)
6. Kliknij Połącz z Google
7. Autoryzuj aplikację w oknie Google OAuth
8. Po autoryzacji zostaniesz przekierowany z powrotem do Ready4Docs

System automatycznie:

• Pobierze i zapisze access_token i refresh_token
• Ustawi account_type na google
• Skonfiguruje IMAP/SMTP dla Gmail (imap.gmail.com:993, smtp.gmail.com:465)

API Endpoints

Endpoint	Metoda	Opis
/api/auth/google	GET	Redirect do Google OAuth
/api/auth/google/callback	GET	Callback handler (public)
/api/auth/google/revoke/{accountId}	POST	Odwołaj dostęp OAuth
/api/auth/google/refresh/{accountId}	POST	Ręczne odświeżenie tokenu

Automatyczne odświeżanie tokenów

GoogleMailService automatycznie odświeża access_token gdy:

• Token wygasł (lub wygaśnie za mniej niż 5 minut)
• Jest dostępny refresh_token

Tokeny są odświeżane w tle podczas:

• Synchronizacji wiadomości IMAP
• Wysyłania wiadomości SMTP
• Manualnego wywołania /api/auth/google/refresh/{accountId}

Rozwiązywanie problemów

Błąd: “Missing refresh_token”

Google nie zwraca refresh_token jeśli użytkownik już wcześniej autoryzował aplikację. Rozwiązanie:

1. Odwołaj dostęp: https://myaccount.google.com/permissions
2. Autoryzuj konto ponownie w Ready4Docs
3. Upewnij się, że w OAuth flow jest parametr prompt=consent

Błąd: “Invalid refresh token”

Refresh token może wygasnąć jeśli:

• Nie był używany przez 6 miesięcy
• Użytkownik zmienił hasło
• Użytkownik odwołał dostęp

Rozwiązanie: Re-autoryzuj konto w Ready4Docs.

Błąd: “Access denied” podczas autoryzacji

Sprawdź:

1. Czy Gmail API jest włączone w Google Cloud Console
2. Czy OAuth consent screen jest opublikowany (jeśli External)
3. Czy redirect URI w Google Cloud Console dokładnie pasuje do URI w aplikacji

Bezpieczeństwo

• Access tokens wygasają co ~1 godzinę
• Refresh tokens są ważne bezterminowo (dopóki nie zostaną odwołane)
• Wszystkie tokeny są szyfrowane w bazie danych (Laravel Crypt)
• Komunikacja z Google API odbywa się przez HTTPS
• Zalecane: Użyj Internal OAuth consent screen dla Google Workspace

Monitorowanie

Sprawdzenie statusu workerów

sudo supervisorctl status | grep ready4docs-mail

Oczekiwany output:

ready4docs-mail-sync-daemon      RUNNING   pid 12345, uptime 1:23:45
ready4docs-mail-idle:00          RUNNING   pid 12346, uptime 1:23:45  # tylko jeśli są konta IDLE
ready4docs-mail-idle:01          RUNNING   pid 12347, uptime 1:23:45
ready4docs-mail-idle:02          RUNNING   pid 12348, uptime 1:23:45
ready4docs-mail-idle:03          RUNNING   pid 12349, uptime 1:23:45

Sprawdzenie ostatniej synchronizacji

php artisan tinker --execute="
\App\Models\MailAccount::select('email', 'account_type', 'status', 'last_sync_at', 'error_count')
  ->get()
  ->each(fn(\$a) => print(\"{$a->email} | {$a->account_type} | {$a->status} | {$a->last_sync_at} | errors: {$a->error_count}\n\"));
"

Logi błędów

# Ogólne logi Laravel
tail -f /home/ready4docs/public_html/backend/storage/logs/laravel.log | grep -i mail

# Logi sync daemon
tail -f /home/ready4docs/public_html/backend/storage/logs/mail-sync-daemon.log

# Logi IDLE worker
tail -f /home/ready4docs/public_html/backend/storage/logs/mail-idle.log

Rozwiązywanie problemów

Konto ma status “disabled”

Konto jest automatycznie wyłączane po 5 kolejnych błędach synchronizacji.

# Sprawdź błąd
php artisan tinker --execute="
\$a = \App\Models\MailAccount::where('email', 'user@example.com')->first();
echo \"Status: {\$a->status}\nError: {\$a->last_error}\nCount: {\$a->error_count}\";
"

# Włącz ponownie
php artisan tinker --execute="
\App\Models\MailAccount::where('email', 'user@example.com')->first()->enable();
"

IDLE worker nie startuje

1. Sprawdź czy są konta imap-idle:

   php artisan tinker --execute="echo \App\Models\MailAccount::where('account_type', 'imap-idle')->count();"

2. Jeśli są, sprawdź konfigurację supervisor:

   ls -la /etc/supervisor/conf.d/ | grep idle

3. Zainstaluj konfigurację jeśli brakuje:

   sudo cp /home/ready4docs/public_html/backend/supervisor/mail-idle.conf /etc/supervisor/conf.d/ready4docs-mail-idle.conf
   sudo supervisorctl reread && sudo supervisorctl update

Wiadomości nie synchronizują się

1. Sprawdź status konta:

   php artisan tinker --execute="\App\Models\MailAccount::first()->only(['status', 'last_sync_at', 'last_error']);"

2. Wymuś synchronizację:

   php artisan mail:sync-daemon --once

3. Sprawdź logi:

   tail -100 /home/ready4docs/public_html/backend/storage/logs/mail-sync-daemon.log

Komendy artisan

Komenda	Opis
mail:sync-daemon	Uruchom daemon synchronizacji (polling)
mail:idle:start	Uruchom IDLE listenery dla kont
mail:test-idle	Sprawdź czy serwer obsługuje IDLE
mail:resync	Wymuś ponowną synchronizację wiadomości
mail:resync-attachments	Ponownie pobierz załączniki