maciejpi/nordabiz
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
master
nordabiz/docs/AUDIT_COMPLETENESS_PLAN.md
Maciej Pienczyn edcba4b178
Some checks are pending
NordaBiz Tests / Unit & Integration Tests (push) Waiting to run
Details
NordaBiz Tests / E2E Tests (Playwright) (push) Blocked by required conditions
Details
NordaBiz Tests / Smoke Tests (Production) (push) Blocked by required conditions
Details
NordaBiz Tests / Send Failure Notification (push) Blocked by required conditions
Details
docs: Update audit completeness plan with Phase 0b and final status 
Mark all phases (0-4) as complete (~95% completeness).
Add Phase 0b (GBP dashboard quick wins: review link, directions,
open status badge, NAP comparison). Add DB migrations table.
Update CLAUDE.md to reflect current status.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 15:17:20 +01:00

7.5 KiB
Raw Permalink Blame History

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)

  • GBP bugfix: review_response_rate — naprawiono: sprawdza ownerResponse zamiast authorAttribution.displayName
  • GBP phantom fields: has_posts, has_products, has_qa oznaczone jako [dane niedostępne bez autoryzacji OAuth]
  • GBP prompt: dodano review_keywords i description_keywords do promptu AI
  • SEO: FID→INP: zastąpiono FID przez INP w prompcie i szablonach (progi: 200ms/500ms)
  • SEO: 10 metryk do promptu: FCP, TTFB, TBT, Speed Index, meta title/desc length, schema details, html lang
  • Social: engagement_rate — obliczane z industry base_rate × activity_multiplier
  • Social: posting_frequency_score — 0-10 based on posts_count_30d
  • 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)

  • Przycisk "Poproś o opinię" — writeAReviewUri z Google Places API googleMapsLinks
  • Przycisk "Pokaż trasę" — directionsUri z Google Places API googleMapsLinks
  • Badge "Otwarty/Zamknięty" — openNow z currentOpeningHours, wyświetlany w sekcji score
  • Tabela porównania NAP — Name/Address/Phone: nasza baza vs Google, z kolorowym statusem zgodności
  • Migracja 062: google_maps_links (JSONB) + google_open_now (BOOLEAN)
  • Field mask: dodano googleMapsLinks do BASIC_FIELDS w google_places_service.py
  • 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)

  • Podpiąć GooglePlacesService do przepływu audytu GBP — zrealizowane w F2
  • CrUX API — crux_service.py stworzony, field data (INP, LCP, CLS, FCP, TTFB) z realnych użytkowników Chrome
  • YouTube Data API v3 — youtube_service.py stworzony, subscriberCount/viewCount/videoCount w social prompt
  • Security headers check — HSTS, CSP, X-Frame-Options, X-Content-Type-Options via requests.head()
  • Image format analysis — WebP/AVIF/SVG vs legacy JPEG/PNG ratio w SEO prompt
  • 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)

  • Zamienić fetch_google_business_data() na GooglePlacesService (Places API New)
  • Ekstrakcja: primaryType, editorialSummary, price_level, attributes (payment, parking, accessibility, services, amenities, food&drink)
  • Wzbogacenie AI promptu GBP o nowe pola (attributes, editorial summary, primary type)
  • extract_reviews_data(), extract_attributes(), extract_photos_metadata(), extract_hours()
  • Migracja bazy danych — kolumny JSONB: migracja 061 (Places API enrichment) + 062 (maps_links, open_now)
  • 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)

  • Shared OAuth 2.0 framework (oauth_service.py) — Google + Meta providers
  • Tabela oauth_tokens w DB (migracja 058)
  • Model OAuthToken w database.py
  • 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)

  • Sentiment analysis recenzji via Gemini (analyze_review_sentiment_ai() w GBPAuditService)
  • 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).