# Plan Kompletności Audytów NordaBiz

**Data analizy:** 2026-02-08
**Zespół:** 4 agentów specjalistów + moderator-architekt
**Obecna kompletność:** ~52% | **Cel po F3:** ~93%

## Stan Implementacji

### Faza 0: Quick Wins (1-3 dni, $0) — W TRAKCIE
- [ ] **GBP bugfix:** review_response_rate sprawdza `authorAttribution.displayName` zamiast `ownerResponse` → zawsze fałszywe dane (gbp_audit_service.py)
- [ ] **GBP phantom fields:** has_posts, has_products, has_qa nigdy nie wypełniane → oznaczyć jako "niedostępne bez OAuth" w _build_gbp_prompt()
- [ ] **SEO: FID→INP:** FID deprecated marzec 2024, INP nie zbierany. Dostępny w `loadingExperience.metrics.INTERACTION_TO_NEXT_PAINT` z PageSpeed API
- [ ] **SEO: 10 metryk do promptu:** FCP, TTFB, TBT, Speed Index, load_time_ms, meta title/desc length, schema details, html lang — JUŻ W DB ale nie w prompcie AI
- [ ] **Social: engagement_rate** — pole w DB istnieje, nigdy nie obliczane. Formuła: estimated base_rate × activity_multiplier
- [ ] **Social: posting_frequency_score** — pole w DB, nigdy nie obliczane. 0-10 based on posts_count_30d
- [ ] **Social: enrichment promptu** — dodać last_post_date, page_name, engagement metrics

**Agenci Phase 0 (team: phase0-quickwins):**
- gbp-fixer: Fix review_response_rate + GBP prompt enrichment
- seo-enricher: INP + 10 metryk SEO do promptu
- social-enricher: engagement_rate + posting_frequency_score + social prompt

### Faza 1: API Key Integrations (0 PLN, 1 tydzień)
- [ ] Podpiąć `GooglePlacesService` do przepływu audytu GBP (MIGRACJA z legacy API)
  - `GooglePlacesService` w `google_places_service.py` — gotowy kod, NIGDY nie wywoływany w audycie!
  - Daje +20 pól: primaryType, editorialSummary, generativeSummary, reviewSummary, paymentOptions, parkingOptions, accessibilityOptions
  - Koszt: $0 (150 firm mieści się w free tier Enterprise: 1000 req/mies)
- [ ] CrUX API — field data z realnych użytkowników Chrome (INP, LCP, CLS, FCP, TTFB)
  - API Key, darmowy, 150 req/min
  - Nowy plik: `crux_service.py`
- [ ] YouTube Data API v3 — subscriberCount, viewCount, videoCount
  - API Key (mamy GOOGLE_PLACES_API_KEY), włączyć w Cloud Console
  - 10k units/dzień, 150 firm = 0.15% limitu
  - Nowy plik: `youtube_service.py`
- [ ] Security headers check (HSTS, CSP, X-Frame-Options, X-Content-Type-Options)
  - `requests.head()` + sprawdzenie nagłówków
- [ ] Image format analysis (WebP/AVIF vs JPEG/PNG)
- [ ] Implementacja Brave Search stub (`_search_brave()` zwraca None — nigdy niezaimplementowany)
- [ ] Migracja DB: nowe kolumny (INP, CrUX, security headers, image formats)

### Faza 2: Migracja GBP na Places API (New) (0 PLN, 2 tygodnie)
- [ ] Zamienić `fetch_google_business_data()` (legacy `maps.googleapis.com/maps/api/place/`) na `GooglePlacesService.get_place_details()` (`places.googleapis.com/v1/`)
- [ ] Dodać ekstrakcję: primaryType, editorialSummary, attributes, generativeSummary, reviewSummary
- [ ] Zaktualizować scoring algorithm
- [ ] Zaktualizować szablony HTML
- [ ] Migracja bazy danych (primary_type, editorial_summary, payment_options, parking_options, accessibility_options)

### Faza 3: OAuth Framework (0 PLN API, 2-4 tygodnie dev)
- [ ] Shared OAuth 2.0 framework (`oauth_service.py`)
- [ ] GBP Business Profile API:
  - Scope: `business.manage`, App review ~14 dni, darmowe
  - Daje: WSZYSTKIE opinie (nie max 5), owner responses, insights (views/clicks/calls/keywords), posty
- [ ] Facebook + Instagram Graph API:
  - Wspólny OAuth via Meta, App review 3-7 dni
  - Scopes: pages_show_list, pages_read_engagement, read_insights, instagram_basic, instagram_manage_insights
  - Daje: reach, impressions, demographics, post insights, IG stories/reels
  - Token: Long-Lived (90 dni), Page Token (nigdy nie wygasa)
- [ ] Google Search Console API (per firma OAuth, darmowe)
  - Daje: zapytania wyszukiwania, CTR, pozycje, status indeksacji
- [ ] UI: "Połącz konto" w panelu firmy
- [ ] Tabela `oauth_tokens` w DB

### Faza 4: Zaawansowane (opcjonalne)
- [ ] Sentiment analysis recenzji via Gemini
- [ ] Competitor benchmarking (średnie per kategoria z 150 firm)
- [ ] LinkedIn Marketing API (trudny approval)
- [ ] NIE implementować: Twitter/X ($200/mies), TikTok (trudny approval)

## Kluczowe Odkrycia Techniczne

### GBP
- `GooglePlacesService` (google_places_service.py) — gotowy client Places API (New), ZAIMPORTOWANY w gbp_audit_service.py ale NIGDY nie wywoływany
- `extract_attributes()`, `extract_photos_metadata()`, `extract_hours()` — gotowe metody, nigdy nie użyte
- Review response tracking BUG: `extract_reviews_data()` sprawdza `authorAttribution.displayName` (autor) zamiast `ownerResponse` (właściciel)
- Places API (New) NIE zwraca owner responses — potrzebny Business Profile API z OAuth
- Logo/cover photo = czysta heurystyka (photo_count >= 1/2)
- Q&A API zdeprecjonowane (3 lis 2025)

### SEO
- FID deprecated marzec 2024, INP nie zbierany (dostępny w PageSpeed API)
- 10+ metryk JUŻ W DB ale NIE przekazywanych do promptu AI
- CrUX field data (dane z realnych użytkowników) nie zbierane — tylko lab data
- Schema.org completeness details zbierane ale nie w prompcie

### Social Media
- engagement_rate, posting_frequency_score, content_types, followers_history — pola w DB, NIGDY nie wypełniane
- `_search_brave()` = STUB (zwraca None)
- YouTube Data API v3 — darmowe, quick win, nie zintegrowane
- Facebook/Instagram OAuth — darmowe, daje pełne insights

## Koszty API (wszystkie $0 w skali 150 firm)

| API | Typ auth | Free tier | 150 firm/mies |
|-----|----------|-----------|---------------|
| PageSpeed Insights | API Key | 25k/dzień | 0.6% |
| Places API (New) | API Key | $200 credit/mies | ~$7.50 (w ramach credit) |
| CrUX API | API Key | 150 req/min | 0.1% |
| YouTube Data API v3 | API Key | 10k units/dzień | 0.15% |
| Brave Search | API Key | 2k req/mies | ~50% |
| GBP Business Profile | OAuth | unlimited | minimal |
| Facebook Graph | OAuth | 200 req/user/h | adequate |
| Google Search Console | OAuth | 20 QPS | adequate |

## Wpływ na Kompletność

| | Obecny | F0 | F1 | F2 | F3 |
|---|--------|-----|-----|-----|-----|
| GBP | 55% | 60% | 75% | 90% | 98% |
| SEO | 60% | 75% | 85% | 85% | 95% |
| Social | 35% | 50% | 65% | 65% | 85% |
| **Średnia** | **52%** | **68%** | **78%** | **83%** | **93%** |