maciejpi/nordabiz
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
b1438dd514
nordabiz/docs/AUDIT_COMPLETENESS_PLAN.md
Maciej Pienczyn b1438dd514
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
feat(audit): Phase 0 quick wins - fix bugs, enrich AI prompts, add metrics 
GBP audit:
- Fix review_response_rate bug: check ownerResponse instead of authorAttribution.displayName
- Mark has_posts/has_products/has_qa as OAuth-dependent in AI prompt
- Add review_keywords and description_keywords to AI prompt

SEO audit:
- Replace deprecated FID with INP (Core Web Vital since March 2024)
- Pass 10 additional metrics to AI prompt: FCP, TTFB, TBT, Speed Index,
  meta title/desc length, html lang, Schema.org field details
- Update templates with INP thresholds (200ms/500ms)

Social media audit:
- Calculate engagement_rate from industry base rates × activity multiplier
- Calculate posting_frequency_score (0-10 based on posts_count_30d)
- Enrich AI prompt with page_name, freq_score, engagement, last_post_date
- Add avg engagement rate and brand name consistency check to prompt

Completeness: 52% → ~68% (estimated)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 11:24:03 +01:00

6.2 KiB
Raw 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%

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%