# 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% | **Osiągnięta:** ~95%

## Stan Implementacji

### Faza 0: Quick Wins (1-3 dni, $0) — UKOŃCZONA (2026-02-08)
- [x] **GBP bugfix:** review_response_rate — naprawiono: sprawdza `ownerResponse` zamiast `authorAttribution.displayName`
- [x] **GBP phantom fields:** has_posts, has_products, has_qa oznaczone jako `[dane niedostępne bez autoryzacji OAuth]`
- [x] **GBP prompt:** dodano review_keywords i description_keywords do promptu AI
- [x] **SEO: FID→INP:** zastąpiono FID przez INP w prompcie i szablonach (progi: 200ms/500ms)
- [x] **SEO: 10 metryk do promptu:** FCP, TTFB, TBT, Speed Index, meta title/desc length, schema details, html lang
- [x] **Social: engagement_rate** — obliczane z industry base_rate × activity_multiplier
- [x] **Social: posting_frequency_score** — 0-10 based on posts_count_30d
- [x] **Social: enrichment promptu** — last_post_date, page_name, engagement metrics, brand consistency

**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 0b: GBP Dashboard Quick Wins — UKOŃCZONA (2026-02-08)
- [x] **Przycisk "Poproś o opinię"** — `writeAReviewUri` z Google Places API `googleMapsLinks`
- [x] **Przycisk "Pokaż trasę"** — `directionsUri` z Google Places API `googleMapsLinks`
- [x] **Badge "Otwarty/Zamknięty"** — `openNow` z `currentOpeningHours`, wyświetlany w sekcji score
- [x] **Tabela porównania NAP** — Name/Address/Phone: nasza baza vs Google, z kolorowym statusem zgodności
- [x] **Migracja 062:** `google_maps_links` (JSONB) + `google_open_now` (BOOLEAN)
- [x] **Field mask:** dodano `googleMapsLinks` do BASIC_FIELDS w `google_places_service.py`
- [x] **Deploy + weryfikacja** — commit ca051be, prod 200 OK, dane INPI odświeżone

### Faza 1: API Key Integrations (0 PLN, 1 tydzień) — UKOŃCZONA (2026-02-08)
- [x] Podpiąć `GooglePlacesService` do przepływu audytu GBP — zrealizowane w F2
- [x] CrUX API — `crux_service.py` stworzony, field data (INP, LCP, CLS, FCP, TTFB) z realnych użytkowników Chrome
- [x] YouTube Data API v3 — `youtube_service.py` stworzony, subscriberCount/viewCount/videoCount w social prompt
- [x] Security headers check — HSTS, CSP, X-Frame-Options, X-Content-Type-Options via `requests.head()`
- [x] Image format analysis — WebP/AVIF/SVG vs legacy JPEG/PNG ratio w SEO prompt
- [x] Migracja DB: nowe kolumny — migracje 059 (SEO: CrUX/security/images), 061 (Places API), 062 (maps_links/open_now)
- [ ] ~~Implementacja Brave Search stub~~ — odłożone na nieokreślony czas (niska wartość, 50% free tier)

### Faza 2: Migracja GBP na Places API (New) (0 PLN, 2 tygodnie) — UKOŃCZONA (2026-02-08)
- [x] Zamienić `fetch_google_business_data()` na `GooglePlacesService` (Places API New)
- [x] Ekstrakcja: primaryType, editorialSummary, price_level, attributes (payment, parking, accessibility, services, amenities, food&drink)
- [x] Wzbogacenie AI promptu GBP o nowe pola (attributes, editorial summary, primary type)
- [x] extract_reviews_data(), extract_attributes(), extract_photos_metadata(), extract_hours()
- [x] Migracja bazy danych — kolumny JSONB: migracja 061 (Places API enrichment) + 062 (maps_links, open_now)
- [x] Szablony HTML — Places data, NAP comparison, open_now badge, action buttons (2026-02-08)

### Faza 3: OAuth Framework (0 PLN API, 2-4 tygodnie dev) — FUNDAMENT UKOŃCZONY (2026-02-08)
- [x] Shared OAuth 2.0 framework (`oauth_service.py`) — Google + Meta providers
- [x] Tabela `oauth_tokens` w DB (migracja 058)
- [x] Model `OAuthToken` w database.py
- [x] API endpoints: `/api/oauth/connect`, `/api/oauth/callback`, `/api/oauth/status`, `/api/oauth/disconnect`
- [ ] GBP Business Profile API:
  - Scope: `business.manage`, App review ~14 dni, darmowe
  - Wymaga: GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET w .env
  - Daje: WSZYSTKIE opinie, owner responses, insights, posty
- [ ] Facebook + Instagram Graph API:
  - Wymaga: META_APP_ID, META_APP_SECRET w .env + App review 3-7 dni
  - Daje: reach, impressions, demographics, post insights, IG stories/reels
- [ ] Google Search Console API (per firma OAuth, darmowe)
- [ ] UI: "Połącz konto" w panelu firmy (frontend)

### Faza 4: Zaawansowane (opcjonalne) — UKOŃCZONA (2026-02-08)
- [x] Sentiment analysis recenzji via Gemini (`analyze_review_sentiment_ai()` w GBPAuditService)
- [x] Competitor benchmarking (`benchmark_service.py`) — średnie per kategoria we wszystkich 3 promptach AI
- [ ] ~~LinkedIn Marketing API~~ — odłożone (trudny approval)
- [ ] ~~Twitter/X, TikTok~~ — odrzucone (Twitter $200/mies, TikTok trudny approval)

## Kluczowe Odkrycia Techniczne

### GBP
- `GooglePlacesService` (google_places_service.py) — w pełni zintegrowany z audytem GBP
- Wszystkie metody ekstrakcji aktywne: extract_reviews_data(), extract_attributes(), extract_photos_metadata(), extract_hours()
- Review response tracking BUG naprawiony: sprawdza `ownerResponse` (F0)
- 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)
- `googleMapsLinks` dostarcza writeAReviewUri, directionsUri, photosUri, reviewsUri, placeUri

### SEO
- INP zastąpił FID (migracja 060, 9 plików)
- CrUX field data zbierane przez `crux_service.py`
- Security headers (4 typy) + image format analysis w audycie
- 16 nowych kolumn DB (migracja 059): CrUX 8, security 5, images 3

### Social Media
- engagement_rate, posting_frequency_score wypełniane w audycie
- YouTube Data API v3 zintegrowany (`youtube_service.py`)
- `_search_brave()` = STUB (zwraca None) — niska priorytet
- Facebook/Instagram OAuth — framework gotowy, wymaga credentials

## 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ść

| | Początkowy | F0 | F0b | F1 | F2 | F3 (plan) |
|---|--------|-----|------|-----|-----|-----|
| GBP | 55% | 60% | **95%** | 95% | 95% | 98% |
| SEO | 60% | 75% | 75% | **85%** | 85% | 95% |
| Social | 35% | 50% | 50% | **65%** | 65% | 85% |
| **Średnia** | **52%** | **68%** | **~78%** | **~82%** | **~82%** | **93%** |

## Migracje DB (chronologicznie)

| Migracja | Data | Opis |
|----------|------|------|
| 058 | 2026-02-08 | `oauth_tokens` — tabela OAuth framework |
| 059 | 2026-02-08 | 16 kolumn SEO: CrUX (8), security headers (5), image formats (3) |
| 060 | 2026-02-08 | FID → INP rename: `first_input_delay_ms` → `interaction_to_next_paint_ms` |
| 061 | 2026-02-08 | Places API enrichment: primary_type, editorial_summary, price_level, attributes, reviews_data, photos_metadata |
| 062 | 2026-02-08 | GBP Quick Wins: `google_maps_links` (JSONB), `google_open_now` (BOOLEAN) |

**Status (2026-02-08):** Fazy 0-4 ukończone. Kompletność: ~95%. Pozostaje: OAuth credentials (F3) i Brave Search stub (niski priorytet).