Kompletny przewodnik po rozwiązywaniu problemów, FAQ i troubleshooting dla SmartFlowAI - od błędów instalacji po problemy z bazą danych.

Na podstawie rzeczywistych logów aplikacji i zgłoszeń użytkowników, oto TOP 10 problemów z rozwiązaniami:

Objaw:

SupabaseException: Invalid API key

Przyczyna: Nieprawidłowe lub brakujące klucze Supabase/OpenAI

Rozwiązanie krok po kroku:

1. Sprawdź plik konfiguracyjny:

# Sprawdź czy plik istnieje
ls -la .streamlit/secrets.toml

# Sprawdź zawartość
cat .streamlit/secrets.toml

2. Popraw klucze Supabase:

# .streamlit/secrets.toml
SUPABASE_URL = "https://twoj-projekt.supabase.co"
SUPABASE_ANON_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
SUPABASE_SERVICE_ROLE_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

3. Sprawdź klucz OpenAI:

OPENAI_API_KEY = "sk-proj-..."

4. Restart aplikacji:

# Zatrzymaj Streamlit (Ctrl+C)
# Uruchom ponownie
streamlit run streamlit_app.py

Weryfikacja:

• ✅ Aplikacja uruchamia się bez błędów
• ✅ Możesz się zalogować
• ✅ Analiza AI działa

Objaw:

ModuleNotFoundError: No module named 'fpdf'

Przyczyna: Niekompletna instalacja zależności

Rozwiązanie:

1. Aktywuj środowisko wirtualne:

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

2. Zainstaluj brakujące moduły:

# Konkretny moduł
pip install fpdf2

# Wszystkie zależności
pip install -r requirements.txt

# Sprawdź instalację
pip list | grep fpdf

3. Sprawdź requirements.txt:

streamlit>=1.28.0
supabase>=2.0.0
openai>=1.0.0
fpdf2>=2.7.6
python-dotenv>=1.0.0

Weryfikacja:

# Test importu
python -c "from fpdf import FPDF; print('OK')"

Objaw:

relation "public.processes" does not exist
'SyncClient' object has no attribute 'sql'

Przyczyna: Niezainicjalizowana baza danych lub błędna konfiguracja

Rozwiązanie:

1. Sprawdź połączenie z Supabase:

# test_connection.py
import streamlit as st
from supabase import create_client

url = st.secrets["SUPABASE_URL"]
key = st.secrets["SUPABASE_ANON_KEY"]

try:
    supabase = create_client(url, key)
    result = supabase.table('users').select('*').limit(1).execute()
    print("✅ Połączenie OK")
except Exception as e:
    print(f"❌ Błąd: {e}")

2. Utwórz tabele w Supabase:

-- W Supabase SQL Editor
CREATE TABLE IF NOT EXISTS users (
    id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE IF NOT EXISTS business_processes (
    id SERIAL PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    title VARCHAR(500) NOT NULL,
    description TEXT NOT NULL,
    ai_analysis TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Dodaj użytkowników testowych
INSERT INTO users (id, email) VALUES 
('550e8400-e29b-41d4-a716-446655440001', '[email protected]'),
('550e8400-e29b-41d4-a716-446655440002', '[email protected]'),
('550e8400-e29b-41d4-a716-446655440003', '[email protected]')
ON CONFLICT (email) DO NOTHING;

3. Sprawdź RLS (Row Level Security):

-- Wyłącz RLS dla testów
ALTER TABLE users DISABLE ROW LEVEL SECURITY;
ALTER TABLE business_processes DISABLE ROW LEVEL SECURITY;

Weryfikacja:

• ✅ Tabele istnieją w Supabase
• ✅ Użytkownicy testowi są dodani
• ✅ Aplikacja zapisuje procesy

Objaw:

Nie można znaleźć user_id dla [email protected]

Przyczyna: Błędny email lub brak użytkownika w bazie

Rozwiązanie:

1. Użyj poprawnych emaili testowych:

✅ [email protected]
✅ [email protected]  
✅ [email protected]
❌ [email protected] (błędny)

2. Sprawdź mapowanie użytkowników:

# W streamlit_app.py
test_user_mapping = {
    "[email protected]": "550e8400-e29b-41d4-a716-446655440001",
    "[email protected]": "550e8400-e29b-41d4-a716-446655440002", 
    "[email protected]": "550e8400-e29b-41d4-a716-446655440003"
}

3. Dodaj nowego użytkownika:

-- W Supabase
INSERT INTO users (email) VALUES ('[email protected]');

Weryfikacja:

• ✅ Logowanie działa
• ✅ Procesy są zapisywane
• ✅ Lista procesów się wyświetla

Objaw:

IndentationError: expected an indented block after 'if' statement
IndentationError: unexpected indent

Przyczyna: Nieprawidłowe wcięcia w kodzie Python

Rozwiązanie:

1. Sprawdź wcięcia w edytorze:

# ❌ Błędne wcięcia
if condition:
prompt = f"""  # Brak wcięcia

# ✅ Poprawne wcięcia  
if condition:
    prompt = f"""  # 4 spacje wcięcia

2. Użyj narzędzi do sprawdzania:

# Sprawdź składnię
python -m py_compile streamlit_app.py

# Użyj autopep8
pip install autopep8
autopep8 --in-place --aggressive streamlit_app.py

3. Konfiguracja edytora:

// VS Code settings.json
{
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "editor.tabSize": 4,
    "editor.insertSpaces": true
}

Weryfikacja:

# Brak błędów składni
python -c "import streamlit_app; print('OK')"

Objaw:

Warning: the config option 'server.enableCORS=false' is not compatible with 'server.enableXsrfProtection=true'

Przyczyna: Konflikt konfiguracji bezpieczeństwa Streamlit

Rozwiązanie:

1. Utwórz plik konfiguracyjny:

# .streamlit/config.toml
[server]
enableCORS = true
enableXsrfProtection = true

2. Lub wyłącz XSRF:

[server]
enableCORS = false
enableXsrfProtection = false

Wpływ: Tylko ostrzeżenie, nie wpływa na działanie

Objaw:

OpenAI API error: Rate limit exceeded
OpenAI API error: Invalid API key

Rozwiązanie:

1. Sprawdź limit API:

# Dodaj retry logic
import time
from openai import OpenAI

def analyze_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(...)
            return response
        except Exception as e:
            if "rate_limit" in str(e).lower():
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            raise e

2. Sprawdź saldo konta:

• Zaloguj się na platform.openai.com
• Sprawdź Usage & Billing
• Dodaj środki jeśli potrzeba

Objaw:

UnicodeEncodeError: 'latin-1' codec can't encode character

Rozwiązanie:

1. Użyj konwersji znaków:

def safe_text(text):
    """Konwertuje polskie znaki na ASCII"""
    replacements = {
        'ą': 'a', 'ć': 'c', 'ę': 'e', 'ł': 'l', 'ń': 'n', 
        'ó': 'o', 'ś': 's', 'ź': 'z', 'ż': 'z',
        'Ą': 'A', 'Ć': 'C', 'Ę': 'E', 'Ł': 'L', 'Ń': 'N', 
        'Ó': 'O', 'Ś': 'S', 'Ź': 'Z', 'Ż': 'Z'
    }
    for polish, ascii_char in replacements.items():
        text = text.replace(polish, ascii_char)
    return text

2. Użyj fpdf2 z Unicode:

from fpdf import FPDF

pdf = FPDF()
pdf.add_font('DejaVu', '', 'DejaVuSansCondensed.ttf', uni=True)
pdf.set_font('DejaVu', '', 14)

Objaw: Stare dane, brak odświeżania

Rozwiązanie:

# Wyczyść cache Streamlit
st.cache_data.clear()
st.cache_resource.clear()

# Lub restart aplikacji
# Ctrl+C, potem streamlit run streamlit_app.py

Objaw: Nieprawidłowe wyświetlanie, brak stylów

Rozwiązanie:

# Wymuś odświeżenie
st.rerun()

# Sprawdź wersję Streamlit
import streamlit as st
print(st.__version__)  # Powinno być >= 1.28.0

Przed zgłoszeniem problemu:

1. Środowisko:

   • Python 3.11+ zainstalowany
   • Środowisko wirtualne aktywne
   • Wszystkie zależności zainstalowane
   • Klucze API skonfigurowane

2. Konfiguracja:

   • Plik .streamlit/secrets.toml istnieje
   • Klucze Supabase są poprawne
   • Klucz OpenAI jest aktywny
   • Baza danych zainicjalizowana

3. Funkcjonalność:

   • Aplikacja uruchamia się
   • Logowanie działa
   • Analiza AI odpowiada
   • Procesy są zapisywane

1. Test połączenia:

# test_connection.py
import streamlit as st
from supabase import create_client
from openai import OpenAI

def test_supabase():
    try:
        url = st.secrets["SUPABASE_URL"]
        key = st.secrets["SUPABASE_ANON_KEY"]
        supabase = create_client(url, key)
        result = supabase.table('users').select('*').limit(1).execute()
        print("✅ Supabase OK")
        return True
    except Exception as e:
        print(f"❌ Supabase Error: {e}")
        return False

def test_openai():
    try:
        client = OpenAI(api_key=st.secrets["OPENAI_API_KEY"])
        response = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": "Test"}],
            max_tokens=10
        )
        print("✅ OpenAI OK")
        return True
    except Exception as e:
        print(f"❌ OpenAI Error: {e}")
        return False

if __name__ == "__main__":
    test_supabase()
    test_openai()

2. Sprawdzenie logów:

# Uruchom z logowaniem
streamlit run streamlit_app.py --logger.level=debug

# Sprawdź logi systemowe
tail -f ~/.streamlit/logs/streamlit.log

3. Test środowiska:

# test_environment.py
import sys
import pkg_resources

print(f"Python: {sys.version}")
print(f"Platform: {sys.platform}")

required_packages = [
    'streamlit>=1.28.0',
    'supabase>=2.0.0', 
    'openai>=1.0.0',
    'fpdf2>=2.7.6'
]

for package in required_packages:
    try:
        pkg_resources.require(package)
        print(f"✅ {package}")
    except:
        print(f"❌ {package}")

Skontaktuj się z supportem gdy:

• Problem występuje mimo wykonania wszystkich kroków
• Błąd nie jest opisany w tym przewodniku
• Potrzebujesz pomocy z konfiguracją enterprise
• Masz pytania o bezpieczeństwo danych

Szablon zgłoszenia:

🐛 OPIS PROBLEMU:
[Krótki opis co się dzieje]

💻 ŚRODOWISKO:
- OS: Windows/macOS/Linux
- Python: [wersja]
- Streamlit: [wersja]
- Przeglądarka: [nazwa i wersja]

🔄 KROKI DO REPRODUKCJI:
1. [Krok 1]
2. [Krok 2] 
3. [Błąd występuje]

📋 OCZEKIWANY REZULTAT:
[Co powinno się stać]

❌ AKTUALNY REZULTAT:
[Co się dzieje zamiast tego]

📊 LOGI/BŁĘDY:

[Wklej pełny komunikat błędu]

🔧 PRÓBOWANE ROZWIĄZANIA:
[Co już próbowałeś]

Dokumentacja:

• Streamlit Docs
• Supabase Docs
• OpenAI API Docs

Community:

• GitHub Issues
• Discord Server
• Stack Overflow

Status:

• Supabase Status
• OpenAI Status

Q: Aplikacja nie uruchamia się po instalacji A: Sprawdź czy:

1. Python 3.11+ jest zainstalowany
2. Środowisko wirtualne jest aktywne
3. Wszystkie zależności są zainstalowane: pip install -r requirements.txt
4. Plik .streamlit/secrets.toml istnieje i ma poprawne klucze

Q: Gdzie znaleźć klucze Supabase? A:

1. Zaloguj się na supabase.com
2. Wybierz swój projekt
3. Idź do Settings → API
4. Skopiuj URL i anon key

Q: Jak sprawdzić czy klucz OpenAI działa? A: Wykonaj test:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Q: Tabela "processes" nie istnieje A: Uruchom skrypt inicjalizacji bazy:

-- W Supabase SQL Editor
CREATE TABLE business_processes (
    id SERIAL PRIMARY KEY,
    user_id UUID,
    title VARCHAR(500),
    description TEXT,
    ai_analysis TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

Q: Nie mogę się zalogować na konto testowe A: Użyj dokładnie tych danych:

• Email: [email protected] (nie .pl!)
• Hasło: test123456

Q: Procesy nie zapisują się A: Sprawdź:

1. Czy jesteś zalogowany
2. Czy tabele istnieją w bazie
3. Czy RLS nie blokuje zapisu
4. Logi w konsoli przeglądarki (F12)

Q: Analiza AI nie działa A: Sprawdź:

1. Klucz OpenAI w secrets.toml
2. Saldo konta OpenAI
3. Połączenie internetowe
4. Logi błędów w aplikacji

Q: Analiza trwa bardzo długo A: To normalne dla głębokiej analizy (60-90s). Dla szybszej analizy wybierz "Podstawowa (szybka)".

Q: Błąd "Rate limit exceeded" A: OpenAI ma limity API. Poczekaj chwilę lub zwiększ limit na platform.openai.com.

Q: PDF nie generuje się A: Sprawdź czy fpdf2 jest zainstalowane:

pip install fpdf2

Q: Polskie znaki w PDF są błędne A: To ograniczenie fpdf. Aplikacja automatycznie konwertuje polskie znaki na ASCII.

Q: Nie mogę pobrać PDF A: Sprawdź:

1. Czy masz procesy do eksportu
2. Czy przeglądarka nie blokuje pobierania
3. Czy masz miejsce na dysku

Q: Czy moje dane są bezpieczne? A: Tak:

• Dane przechowywane w Supabase (PostgreSQL)
• Połączenia szyfrowane (HTTPS)
• Klucze API nie są udostępniane
• RLS (Row Level Security) w bazie

Q: Czy mogę używać własnej bazy danych? A: Tak, zmień konfigurację Supabase na własną instancję.

Q: Jak usunąć wszystkie moje dane? A: W aplikacji usuń procesy pojedynczo lub skontaktuj się z supportem.

Q: Aplikacja działa wolno A: Sprawdź:

1. Połączenie internetowe
2. Czy nie masz zbyt wielu procesów
3. Czy cache nie jest przepełniony: st.cache_data.clear()

Q: Ile kosztuje analiza AI? A: ~$0.01-0.03 za analizę (zależnie od głębokości)

Q: Czy mogę używać lokalnego AI? A: Obecnie tylko OpenAI API. Lokalne modele w przyszłych wersjach.

Q: Jak zaktualizować aplikację? A:

git pull origin main
pip install -r requirements.txt --upgrade
streamlit run streamlit_app.py

Q: Czy stracę dane po aktualizacji? A: Nie, dane są w Supabase i pozostają bezpieczne.

Q: Jak sprawdzić wersję? A: Sprawdź w pliku README.md lub na GitHub.

🎉 Nie znalazłeś rozwiązania? Skontaktuj się z nami!

📧 Email: [email protected]
💬 Discord: SmartFlowAI Community
🐛 GitHub: Zgłoś błąd

Następny krok: Testowanie - dowiedz się jak testować aplikację przed wdrożeniem.