Troubleshooting & Operational Runbook

This operational runbook provides field diagnostic instructions for common edge cases, errors, and integration failures.

---

1. Quick Incident Matrix

Symptom	Probable Cause	Fast Diagnostic	Remediation Action
500 Internal Server Error on API call	Missing .env file or permission issue	Check delete_log.txt or Nginx error.log	Copy .env.example to .env and configure keys. Verify chmod 775 data/.
401 Unauthorized on /api/create_offer.php	Missing or mismatched X-Secret-Key header	Inspect request headers	Ensure caller sends header X-Secret-Key: <DEALFLOW_API_SECRET>.
Google Calendar slots not appearing	Expired or invalid Google Refresh Token	Check scheduler/backend/api_debug.log	Re-authenticate Google Calendar via auth_start.php to obtain fresh token.
Brak pliku konfiguracyjnego error	Requested calendar ID not found in data/	Verify scheduler/data/{id}.json exists	Ensure ID exists or fallback to ?id=default.
Ten link wygasł (ważny 72h)	Member onboarding invitation token has expired	Check expires_at in dealflow/data/{token}.json	Issue a new onboarding invitation from the Planovi CRM / Flutter app.

---

2. Deep Dive Diagnostics

A. Google OAuth Refresh Token Failures

If the scheduler log reports Google Auth Warning: Token failed:

1. Check scheduler/backend/config_google.php to verify GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
2. Ensure the redirect URI in Google Cloud Console matches https://<domain>/backend/auth_callback.php.
3. Re-run authorization: navigate to https://<domain>/backend/auth_start.php in a browser and complete consent.

B. Directory Permissions Error

If create_offer.php responds with Failed to save offer file. Check directory permissions:

1. SSH into VPS 191.218.165.149.
2. Inspect directory owner: ls -ld /var/www/planovi-microservices/dealflow/data.
3. Fix ownership:

   sudo chown -R www-data:www-data /var/www/planovi-microservices/dealflow/data
   sudo chmod -R 775 /var/www/planovi-microservices/dealflow/data

C. Nginx Direct Access to /data/ Protection

Ensure that external visitors cannot browse raw JSON data files directly (e.g. navigating to https://dealflow.planovi.app/data/deal_123.json):

• Verify that Nginx blocks requests matching /data/ with 403 Forbidden:

  location ^~ /data/ {
      deny all;
      return 403;
  }