# NordaBiz - Dokumentacja deweloperska

Ten dokument zawiera szczegółowe informacje techniczne dla deweloperów.
Główne instrukcje znajdują się w [CLAUDE.md](../CLAUDE.md).

---

## SearchService (search_service.py)

Unified search dla chatbota AI i wyszukiwarki `/search`.

### Funkcje
- **NIP/REGON lookup** - bezpośrednie wyszukiwanie po identyfikatorach
- **Synonym expansion** - rozszerzenie słów kluczowych (np. "strony" → www, web, portal)
- **PostgreSQL FTS** - full-text search z tsvector (DEV i PROD)
- **SQLite fallback** - keyword scoring (tylko jako fallback, nieużywane)
- **Fuzzy matching** - pg_trgm dla literówek (gdy dostępne)

### Scoring
| Pole | Punkty |
|------|--------|
| Nazwa firmy | +10 |
| Opis | +5 |
| Usługi | +8 |
| Kompetencje | +7 |
| Miasto | +3 |

### Użycie
```python
from search_service import search_companies
results = search_companies(db, "strony www", limit=10)
# Zwraca List[SearchResult] z company, score, match_type
```

### UWAGA (PostgreSQL)
- Gdy FTS się nie powiedzie, wykonywany jest `db.rollback()` przed fallbackiem
- Bez tego następuje błąd `InFailedSqlTransaction`

---

## Chatbot AI (nordabiz_chat.py)

### Konfiguracja
- **Limit firm do AI:** 8 (zmienne w `_build_conversation_context`, linia ~312)
- **Historia wiadomości:** 10 ostatnich
- **Search:** używa `search_companies()` z SearchService

---

## Testy jakości AI

### Uruchomienie
```bash
python run_ai_quality_tests.py -v        # Verbose output
python run_ai_quality_tests.py -v -s     # Verbose + save report
python run_ai_quality_tests.py -q        # Quick (tylko high-priority)
```

### Przypadki testowe (`tests/ai_quality_test_cases.json`)
- 15 przypadków w 8 kategoriach
- Próg zaliczenia: 70%
- Kategorie: IT/Web, Services/Legal, Services/Accounting, Production/Metal, Construction, HVAC, Energy/Renewable, IT/Security

---

## News Monitoring

### Brave Search API Integration

**Konfiguracja:**
- API Key w `.env`: `BRAVE_SEARCH_API_KEY`
- Endpoint: `https://api.search.brave.com/res/v1/news/search`
- Limit: 2000 req/miesiąc (free tier)

**Parametry wyszukiwania:**
```python
params = {
    "q": f'"{company_name}" OR "{nip}"',
    "count": 10,
    "freshness": "pw",  # past week
    "country": "pl",
    "search_lang": "pl"
}
```

### AI Filtering (Gemini)

Filtracja wyników przez Google Gemini:
- Ocena relevance_score (0.0-1.0)
- Kategoryzacja news_type
- Wykrywanie duplikatów/spamu
- Automatyczne odrzucanie wyników < 0.3 relevance

**Prompt systemu:**
```
Oceń czy artykuł dotyczy działalności firmy {company_name}.
Zwróć JSON: {"relevance": 0.0-1.0, "type": "news_mention|press_release|award", "reason": "..."}
```

### Panel admina /admin/news

**URL:** `/admin/news`
**Wymaga:** Zalogowany użytkownik z `is_admin=True`

**Funkcje:**
- Lista newsów pending do moderacji
- Filtrowanie po firmie, statusie, dacie
- Zatwierdzanie/odrzucanie z powodem
- Podgląd oryginalnego artykułu
- Bulk actions (zatwierdź wszystkie z relevance > 0.8)

### Sekcja Aktualności na profilu firmy

**Lokalizacja:** `templates/company_detail.html`
**Warunek:** Tylko newsy ze statusem `approved`
**Sortowanie:** Po `published_at` DESC
**Limit:** 5 ostatnich newsów

**Struktura wyświetlania:**
```
AKTUALNOŚCI
├── [data] Tytuł artykułu (źródło)
│   Krótki opis...
│   [Czytaj więcej →]
└── [data] Kolejny artykuł...
```

### System powiadomień

**Endpoint:** `/api/notifications`
**Zwraca:** JSON z listą powiadomień użytkownika

**Typy powiadomień:**
- `new_news` - nowy news o obserwowanej firmie (dla zalogowanych)
- `news_approved` - news firmy użytkownika został zatwierdzony
- `news_rejected` - news firmy użytkownika został odrzucony

**Struktura odpowiedzi:**
```json
{
  "notifications": [
    {
      "id": 1,
      "type": "new_news",
      "message": "Nowa wzmianka o PIXLAB",
      "url": "/company/pixlab-sp-z-o-o#news",
      "created_at": "2025-12-29T10:30:00",
      "read": false
    }
  ],
  "unread_count": 3
}
```

---

## Audyt SEO (Panel /admin/seo)

### Opis

System audytu SEO stron internetowych firm członkowskich Norda Biznes.
Wykorzystuje Google PageSpeed Insights API do analizy wydajności i jakości stron.

**URL panelu:** `/admin/seo`
**Wymaga:** Zalogowany użytkownik z `is_admin=True`

### Konfiguracja API

**Google PageSpeed Insights API:**
- API Key w `.env`: `GOOGLE_PAGESPEED_API_KEY`
- Projekt Google Cloud: NORDABIZNES (`gen-lang-client-0540794446`)
- Limit: 25,000 zapytań/dzień (free tier)
- Endpoint: `https://www.googleapis.com/pagespeedonline/v5/runPagespeed`

**Klucz API:**
- **Nazwa w Google Cloud:** `Page SPEED SEO Audit v2`
- **Wartość:** Przechowywany w `.env` (GOOGLE_PAGESPEED_API_KEY)

### Metryki audytu

| Metryka | Źródło | Skala |
|---------|--------|-------|
| WYNIK SEO | PageSpeed Insights | 0-100 |
| PERFORMANCE | PageSpeed Insights | 0-100 |
| DOSTĘPNOŚĆ | PageSpeed Insights | 0-100 |
| BEST PRACTICES | PageSpeed Insights | 0-100 |

**Interpretacja wyników:**
- 90-100 (zielony) - Doskonały
- 50-89 (żółty) - Wymaga poprawy
- 0-49 (czerwony) - Słaby

### Skrypty SEO

```bash
# Audyt pojedynczej firmy
cd /var/www/nordabiznes/scripts
python seo_audit.py --company-id 26

# Audyt wsadowy (batch)
python seo_audit.py --batch 1-10

# Audyt wszystkich firm
python seo_audit.py --all

# Tryb testowy (bez zapisu)
python seo_audit.py --company-id 26 --dry-run
```

### WAŻNE - Połączenie z bazą danych

Skrypty w `scripts/` muszą używać **localhost (127.0.0.1)** do połączenia z PostgreSQL:

```python
# PRAWIDŁOWO (hasło z .env):
DATABASE_URL = 'postgresql://nordabiz_app:<PASSWORD_FROM_ENV>@127.0.0.1:5432/nordabiz'

# BŁĘDNIE (PostgreSQL nie akceptuje zewnętrznych połączeń):
DATABASE_URL = 'postgresql://nordabiz_app:<PASSWORD>@57.128.200.27:5432/nordabiz'
```

**Pliki z konfiguracją bazy:**
- `scripts/seo_audit.py` (linia ~79)
- `scripts/seo_report_generator.py` (linia ~47)
- `scripts/social_media_audit.py` (linia ~53)

### UI - Stylizowane modale

Panel SEO używa niestandardowych modali (zamiast natywnych `confirm()`/`alert()`):
- Modal potwierdzenia audytu z ikoną ostrzeżenia
- Modal informacyjny o błędach
- Animacje CSS (fade in/out)

**Lokalizacja kodu:** `templates/admin_seo_dashboard.html`

---

## Social Media

### Skrypty aktualizacji

```bash
# Aktualizacja Social Media z pliku JSON
cd /var/www/nordabiznes
sudo -u www-data /var/www/nordabiznes/venv/bin/python3 update_social_media.py --dry-run  # Test
sudo -u www-data /var/www/nordabiznes/venv/bin/python3 update_social_media.py            # Produkcja
```

**Pliki:**
- `social_media_found.json` - wyniki wyszukiwania (źródło danych)
- `update_social_media.py` - skrypt aktualizujący bazę

**Platformy:** facebook, instagram, youtube, linkedin, tiktok, twitter

---

## Skrypty danych

### Import (wykonywać kolejno)
```bash
python import_norda_companies.py      # Batch 1 (56 firm)
python import_norda_batch2.py         # Batch 2
python import_norda_batch3.py         # Batch 3
python import_norda_batch4.py         # Batch 4 (9 firm)
python import_norda_batch5.py         # Batch 5 (8 firm)
```

### Weryfikacja
```bash
python verify_all_companies_data.py   # Raport jakości danych
python fix_krs_verification.py        # Weryfikacja KRS
```