← Vissza a Portal Hub-ra
GongGEO Intelligence HUB Rendszerspecifikáció
Hivatalos Műszaki és Fejlesztési Alapdokumentum (PRD)
Verzió: v2.4.1-béta01
# GongGEO Intelligence HUB - Platform & GEO JSON-LD Dashboard & AI System Architecture
## Teljeskörű Műszaki Rendszerspecifikáció és Fejlesztési Dokumentáció (Master Architecture & Comprehensive PRD)
**Verzió:** 2.2.0 (Master Release)
**Dátum:** 2026. augusztus 2.
**Státusz:** Hivatalosan Jóváhagyott Központi Műszaki Mesterdokumentáció – Főportál Ökoszisztéma ("Portal Hub"), Multi-Provider AI Engine & Smart Failover Routing Matrix (`ga_ai_routing`), Live Debug Inspector Window, GEO Scraper v1.1.0 Ultra-Fast Regex Engine (8s Timeout, Bot-Protection), AI Javaslatok & Archívum Műhely Modál (3-Oszlopos Rugalmas Grid, Hibatűrő JSON Tisztítás, Élesítés, Idővonalas Audit Előzmények), Tipizált GEO Sablonok, Zod Validációs & System Prompt Architektúra, Skinelhetőségi Token Rendszer, WordPress Auto-Injector Előkészítés, Diff & Alerting Engine, Dinamikus Adatbázis Karbantartó Hub (`/admin`) kétsoros fejléc-töréssel és 240px maximált oszlopszélességgel, Rendszerszintű Autentikáció (`require_login`), Adatbázis Névtér Izoláció (`ga_platform_`, `ga_geo_`, `ga_ai_`) és Vercel Serverless Telepítési Szabvány.
**Szerző:** AI Rendszerarchitekt & GongAkadémia Fejlesztői Csapat
---
## 1. Bevezetés és Projekt Vízió
A **GongAkadémia Digital Ecosystem (GongGEO Intelligence HUB v2.2.0)** egy központi, mikroszolgáltatás-alapú vállalati platform. A platform belépési pontjaként egy **Fő Ökoszisztéma Portál (Portal Hub)** szolgál, amelyről a felhasználók bejelentkezés után elérik a különálló alrendszereket (GEO JSON-LD Dashboard, AI Control Center & Chat Konzol, AI Útvonalválasztó Mátrix, Kurzus/Esemény Menedzser, Kliens & Hangfürdő Adminisztráció, AI Content Studio stb.).
A platform központi pillére a **GEO JSON-LD Dashboard & Management System**, valamint a beépített **Multi-Provider AI Engine**. Ennek célja, hogy a GongAkadémia és egyéb kezelt weboldalak strukturált adatait (Yoast SEO JSON-LD vs. Egyedi GEO Schema.org entitások) valós időben nyomon kövesse, automatizáltan beolvassa, érvényesítse, megjelölje a frissítendő régi scripteket (`needs_update: true`), és mesterséges intelligencia segítségével folyamatosan optimálja a keresőmotorok és AI ágens-keresők (ChatGPT Search, Perplexity, Gemini, Google Search Generative Experience, Claude, DeepSeek) számára.
A platform nem egyszerű JSON-megjelenítő: központi munkaterület a weboldalak schema-stratégiájához, az AI-val készített tervekhez, az AI modellek dinamikus útvonalválasztásához, a publikált állapotok követéséhez, az entitások konzisztens kezeléséhez (`@id` registry), az archiváláshoz és az adatbázis-szintű karbantartáshoz.
---
### 1.1 Fő Üzleti és Technológiai Célok (12 Alappillér)
1. **Ökoszisztéma-szintű Belépési Portál (Portal Hub):** Belépés utáni központi modulválasztó felület, amely "foglalatként" szolgál a jövőbeli alrendszereknek, elkerülve a meglévő kód utólagos szerkezeti átalakítását.
2. **Globális Autentikáció & Hozzáférés-szabályozás (System-wide Gatekeeping):** A `ga_platform_settings` táblában található `require_login` paraméter által vezérelt dinamikus védelmi réteg. Ha értéke `true`, bejelentkezés nélkül semmilyen védett útvonal, modul vagy menüpont nem érhető el.
3. **Szigorú Adatbázis Névtér Izoláció (Database Prefix Standard):** Egyetlen közös Supabase PostgreSQL adatbázis használata esetén a táblák, nézetek, procedúrák és RLS szabályok egyértelmű modul-prefixekkel vannak elhatárolva (`ga_platform_`, `ga_geo_` és `ga_ai_`).
4. **Service-Agnosztikus Multi-Provider AI Engine:** Egységes absztrakciós réteg a különböző AI providerek felé (OpenAI, Google Gemini, Anthropic Claude, DeepSeek, FreeLLMAPI router), 80+ élő modellválasztási lehetőséggel.
5. **Funkció-alapú Útvonalválasztási Mátrix (Routing Matrix & Smart Failover):** Az adatbázisban rögzített `ga_ai_routing` tábla alapján funkciónként (pl. GEO Benefit generálás, AI Chat, Schema ellenőrzés) külön állítható az Elsődleges, Másodlagos (Fallback 1) és Harmadlagos (Fallback 2) LLM provider, modell és várakozási időkeret (timeout). Ha az elsődleges LLM nem válaszol vagy hibát dob, a rendszer láthatatlanul átkapcsol a tartalék szolgáltatókra.
6. **Élő Szerviz Inspector (Live Debug Window):** Opcionálisan bekapcsolható élő kommunikációs ablak, ami valós időben mutatja a kimenő promptokat, a nyers AI válaszokat, a failover eseményeket és a teljesítmény-statisztikákat.
7. **Párhuzamos Validáció és Vizuális Összehasonlítás:** A beépített Yoast SEO és az egyedi fejlesztésű GEO JSON-LD-k hibatűrő, szintaxis-kiemelt, pontos ablakméretezésű side-by-side összehasonlítása.
8. **Automata Monitoring & Régi Script Riasztási Rendszer:** Időzített és manuális adatkinyerés (scraper), explicit HTML markerek (`class="geo-custom-schema"`) keresése, a régi/frissítendő scriptek automatikus megjelölése (`needs_update: true`) és vizuális riasztása a Dashboard-on.
9. **AI Javaslatok & 3-Oszlopos Rugalmas Műhely Grid:** Szélesvásznú, 3 oszlopos grid munkaterület (Éles Adatok | AI Javaslat - szerkesztés | Archívum & Előzmények) oszloponkénti ki/bekapcsolási lehetőséggel, Egyedi / Yoast / Közös nézetváltóval, automatikus `<script>` tag tisztítással (`cleanJsonString`) és közvetlen élesítési alrendszerrel (`handlePromoteProposal`).
10. **Verziókezelés & Audit Idővonal (Audit History Timeline):** A Supabase `ga_geo_scrape_audits` táblájára épülő visszamenőleges pillanatkép-történet, amely lehetővé teszi a korábbi auditok megtekintését és az élő adatok manuális lefagyasztását / archiválását (`handleArchiveLive`).
11. **Entitás-Konzisztencia (`@id` registry):** Globális törzsadat-kezelés (`ga_geo_entity_registry`) az oktatók, helyszínek, szervezet és kurzusok egyértelmű azonosítására a teljes entitás-hálózatban.
12. **Dinamikus Adatbázis Karbantartó Hub (`/admin`) és Táblázat Standardok:** Reszponzív full-width elrendezés, kétsoros fejléc-törés (`break-words`), 240px maximált alapértelmezett oszlopszélesség manuális egérrel történő átméretezhetőséggel (`columnWidths`), drag-and-drop oszlopsorrenddel, `localStorage` perzisztenciával és automata vízszintes görgetéssel.
---
## 2. Rendszerarchitektúra és Technológiai Stack
A rendszer modern, szervermentes (Serverless / Edge) architektúrára épül.
```text
┌─────────────────────────────────────────────────────────────────────────────────┐
│ GONGAKADÉMIA PORTAL HUB │
│ (Ökoszisztéma Belépő, Reszponzív Top Header & Drawer Navigation) │
└───────────────────────────────────────┬─────────────────────────────────────────┘
│
┌──────────────────────────┼──────────────────────────┐
▼ ▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐ ┌────────────────────────┐
│ GEO JSON-LD DASHBOARD │ │ AI CONTROL CENTER │ │ ADATBÁZIS KARBANTARTÓ │
│ - Yoast vs Custom Schema│ │ - CLI AI Chat Konzol │ │ - Dynamic Table Engine │
│ - Régi Script Alert │ │ - AI Routing Matrix │ │ - Column Resizing │
│ - AI Műhely (3-Col Grid)│ │ - Live Debug Inspector │ │ - Drag & Drop Order │
│ - Audit History Timeline│ │ - Multi-Provider Engine │ │ - FK/ID Hide-Show │
└────────────┬────────────┘ └──────────┬──────────────┘ └───────────┬────────────┘
│ │ │
└──────────────────────────┼─────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SUPABASE BACKEND & VERCEL API │
│ - Supabase Auth + AuthContext (require_login gatekeeping & role control) │
│ - PostgreSQL + JSONB Névtér-elhatárolt Adatbázis: │
│ * Platform törzsek: ga_platform_profiles, ga_platform_modules, │
│ ga_platform_settings, user_preferences │
│ * GEO Modul táblák: ga_geo_websites, ga_geo_urls, ga_geo_scrape_audits, │
│ ga_geo_custom_schemas, ga_geo_entity_registry │
│ * AI Engine tábla: ga_ai_routing (Routing Matrix & Failover Chains) │
│ - GEO Scraper Engine v1.1.0 (8s AbortController Timeout, Bot-Protection Headers)│
│ - Multi-Provider AI Engine Router (OpenAI, Gemini, Claude, DeepSeek, FreeLLM) │
└─────────────────────────────────────────────────────────────────────────────────┘
```
### 2.1 Technológiai elemek és szerepük
- **Frontend:** Next.js (App Router), React 19, TypeScript, Tailwind CSS, Vanilla CSS Design Tokens (`Gong Dark` skin).
- **Autentikáció & Állapotkezelés:** Supabase Auth (Email/jelszó + Google OAuth) és reaktív `AuthContext` (`usePathname` megfigyeléssel és `refetchSettings` frissítéssel).
- **Hosting & CI/CD:** Vercel Free Tier, automatikus deployment GitHub push-ra (`main` vagy `feature/*` branch).
- **Adatbázis:** Supabase Free PostgreSQL adatbázis RLS védelemmel és `pg_cron` ütemezéssel.
- **Szerveroldali API & Scraper:** Node.js Serverless Route Handlers (`app/api/scrape/route.ts`), tiszta szerveroldali Supabase klienssel (`lib/supabaseServer.ts`), 8 másodperces `AbortController` időkerettel és reguláris kifejezés-alapú JSON-LD parserrel.
- **AI Infrastruktúra:** Service-Agnosztikus Multi-Provider AI Router (`lib/ai-engine/ai-engine.ts`), Vercel AI SDK, Zod schema validációval, FreeLLMAPI és közvetlen LLM API integrációk.
### 2.2 Környezeti Változók Készlete (`.env.local` & Vercel Dashboard)
```dotenv
NEXT_PUBLIC_SUPABASE_URL=https://<project-ref>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGci...
NEXT_PUBLIC_BASE_URL=https://<app-name>.vercel.app
OPENAI_API_KEY=sk-proj-...
GEMINI_API_KEY=AIzaSy...
FREELLMAPI_KEY=fl-key-...
CRON_SECRET=super-secret-cron-key
WORDPRESS_API_URL=https://gongakademia.hu/wp-json/wp/v2
WORDPRESS_API_CREDENTIALS=basic_auth_token
```
*Biztonsági Szabály:* A `SUPABASE_SERVICE_ROLE_KEY`, az AI API kulcsok és a `CRON_SECRET` kizárólag a szerveroldali környezetben használhatók, a kliensoldali JavaScript bundle-be vagy böngészőbe soha nem kerülhetnek.
---
## 3. UX/UI Rendszerspecifikáció, Layout & Reprodukálható Skinelhetőségi Rendszer
### 3.1 UX Alapelvek & "Gong Dark" Referencia Téma
A jóváhagyott referenciafelület egy **sűrű, professzionális, fejlesztői fókuszú sötét dashboard**. Nem marketingoldal, hanem gyors napi munkára optimalizált alkalmazás. Az információhierarchia alapja:
1. Melyik weboldalon / domainen dolgozom?
2. Melyik URL aktív?
3. Milyen nézetben vagyok (Yoast, Egyedi GEO, AI Műhely, Admin Karbantartó)?
4. Mi a Yoast állapota, és mi az egyedi GEO állapot?
5. Milyen az aktuális verzió, van-e figyelmeztetés (`needs_update`), és milyen akció végezhető el?
A felület alapértelmezett kódneve: **`gong-dark`**.
- **Vizuális karakter:** nagyon sötét, enyhén kékes/fekete alkalmazásháttér; magas kontrasztú szövegek; meleg arany/sárga (`amber-500`) hangsúlyszínek.
- **Aktív URL kiemelés:** arany függőleges vonal a kártya bal oldalán.
- **Kódblokkok:** közel fekete háttér (`bg-slate-950`), monospace betűkészlet, szintaxiskiemelés.
### 3.2 Layout & Méretezési Táblázat
| Terület | Asztali viselkedés | Reszponzív viselkedés (Mobil/Tablet) |
|---|---|---|
| **Sidebar / Drawer** | Fix, kb. 240-280 px széles, saját görgetősáv | 1024 px alatt balról behúzható drawer, alapértelmezetten zárt |
| **Top Header Bar** | Full-width 3-szekciós flex sáv (Bal: Menü/Logo, Közép: Dashboard/AI, Jobb: Profil) | Képernyőszélességhez igazodó rugalmas tördelés |
| **Fő Tartalom** | `min-width: 0`, `w-full px-4 sm:px-6`, rugalmas elrendezés | Teljes szélesség, csökkentett belső térköz |
| **Yoast vs GEO Panelek**| CSS Grid: két egyenlő oszlop (`grid-cols-1 lg:grid-cols-2`) | 1024 px alatt egymás alá eső 1-oszlopos elrendezés |
| **Kódblokk (`td` / `pre`)**| Belső `overflow-x: auto` és `max-w-[240px]` cellakorlát | Vízszintes érintő-görgetés a szülő kártyán belül |
| **AI Műhely Modál** | 3-oszlopos rugalmas grid, független oszlop-toggles | Mobilon 1 oszlopos görgethető modal |
Kötelező CSS-elv: flex vagy grid gyermekelemnél `min-width: 0`, mert ez akadályozza meg, hogy hosszú JSON-sorok vagy táblázatok a teljes alkalmazást széthúzzák és nem kívánt vízszintes oldal-scrollt okozzanak.
### 3.3 CSS Token Architektúra & Skin-Regiszter
A rendszer felkészült a skinek dinamikus váltására. A vizuális megjelenítést CSS-változók határozzák meg:
```css
:root[data-skin="gong-dark"] {
--app-bg: #080b14;
--sidebar-bg: #0b101d;
--surface: #121b2c;
--surface-code: #070b13;
--border-subtle: #1e2a40;
--text-primary: #eef3fb;
--text-muted: #8390a7;
--accent: #e9a91e;
--accent-strong: #ffc84d;
--accent-soft: #3b2d0e;
--info: #70a8ff;
--success: #55c995;
--warning: #f2b84b;
--danger: #ef6d7a;
--radius-panel: 10px;
--shadow-panel: 0 8px 24px rgb(0 0 0 / 18%);
}
:root[data-skin="light"] {
--app-bg: #f5f7fb;
--sidebar-bg: #ffffff;
--surface: #ffffff;
--surface-code: #111827;
--border-subtle: #d9e0eb;
--text-primary: #172033;
--text-muted: #637087;
--accent: #a76a00;
--accent-strong: #805000;
--accent-soft: #fff4d6;
--info: #2265c7;
--success: #14734a;
--warning: #9b6200;
--danger: #b42336;
--radius-panel: 10px;
--shadow-panel: 0 8px 24px rgb(20 34 60 / 10%);
}
```
A skinválasztó a felső navigációban a `document.documentElement.dataset.skin = selectedSkin` paranccsal hajtja végre a váltást, és eltárolja az értéket a `user_preferences` táblában.
### 3.4 Kódmegjelenítés & Hibatűrő Algoritmus (`safeFormatJson`)
A JSON tartalom külső weboldalakról származik, ezért az alkalmazás fel van készítve a sérült vagy hiányos JSON kódok biztonságos megjelenítésére:
```typescript
export function safeFormatJson(input: unknown): { formatted: string; isValid: boolean } {
if (!input) return { formatted: '', isValid: true };
const raw = typeof input === 'string' ? input : JSON.stringify(input, null, 2);
try {
return { formatted: JSON.stringify(JSON.parse(raw), null, 2), isValid: true };
} catch {
return { formatted: raw, isValid: false };
}
}
```
Elvárt működés:
- Érvényes JSON esetén szintaxis-kiemelt formázott megjelenítés.
- Hibás JSON esetén a nyers tartalom jelenik meg *"A forrás nem érvényes JSON"* sárga jelzéssel, megakadályozva az alkalmazás összeomlását.
- A böngészőben HTML vagy script-tartalom **soha nem renderelhető** `dangerouslySetInnerHTML` használatával.
### 3.5 Akadálymentesség (WCAG)
- Billentyűzettel minden vezérlő elérhető (Tab szekvencia, Enter/Space akciók).
- A drawer panel nyitáskor fókuszcsapdát kap, bezáráskor visszaadja a fókuszt a nyitó gombnak.
- Minden hiba- és figyelmeztető elem nemcsak színnel, hanem ikont és szöveges címkét is használ.
---
## 4. Részletes Menüstruktúra és Hívási Konfigurációk (v2.2.0)
Az alábbi fában található valamennyi rendszer-menüpont pontos felülete, URL elérési útja, ikonja és adatbázis-kapcsolata.
```text
========================================================================================================================
1. FELSŐ NAVIGÁCIÓS SÁV (HEADER BAR - FEJLÉC) - Reszponzív Teljes Szélességű 3-Szekciós Elrendezés
========================================================================================================================
--- Bal Oldali Igazítás (flex-1 justify-start) ---
[☰ Menü] (Hamburger nyitó) --> Nyitja a bal oldali fiókot (Slide-out Drawer)
[GA Logo] GongGEO Intelligence HUB --> Navigáció a Kezdőlapra (Hívási URL: /)
--- Középre Igazított Gyorselérési Gombok (flex-1 justify-center) ---
• 🌐 GEO JSON Dashboard --> Hívási URL: /geo-dashboard
• 🧠 AI Konzol --> Hívási URL: /ai-chat
--- Jobb Oldali Műveletek (flex-1 justify-end) ---
• HeaderActions (Profil, Auth) --> Auth / Role / Témaváltó vezérlés
========================================================================================================================
2. BAL OLDALI HAMBURGER MENÜ (DRAWER PANEL)
========================================================================================================================
🌐 1. GEO Intelligence & SEO Engine
└── 📊 GEO Dashboard --> Hívási URL: /geo-dashboard
🧠 2. AI Control Center (AI Vezérlőközpont)
├── 💬 AI Konzol (Interaktív Chat) --> Hívási URL: /ai-chat
├── 🔀 AI Útvonalválasztó Mátrix --> Hívási URL: /ai-routing
└── 🛠️ Live Debug Inspector Panel --> Hívási URL: /ai-routing#inspector
🛠️ 3. Rendszer Adatok (Legyíló almenü)
├── 👤 Platform Profilok --> Hívási URL: /admin?table=ga_platform_profiles
└── ⚙️ Rendszer Beállítások --> Hívási URL: /admin?table=ga_platform_settings
🗄️ 4. Adatbázis Karbantartó Hub
└── 💾 Adatbázis Karbantartó Főoldal --> Hívási URL: /admin
========================================================================================================================
3. ADATBÁZIS KARBANTARTÓ FŐOLDAL (/admin) - BELSŐ TÁBLÁZAT VÁLASZTÓ SÁV
========================================================================================================================
🗄️ Adatbázis Táblák (Karbantartói felület)
├── 🌐 GEO Webhelyek (Domains) --> Cél tábla: ga_geo_websites
├── 🔗 GEO URL Regiszter --> Cél tábla: ga_geo_urls
├── 📜 Gyűjtési Auditok & AI Napló --> Cél tábla: ga_geo_scrape_audits
├── 📄 Verziózott Schemak --> Cél tábla: ga_geo_custom_schemas
├── 🏷️ Entitás Regiszter --> Cél tábla: ga_geo_entity_registry
├── ✨ Ismeretlen Entitások --> Cél tábla: ga_geo_unmapped_entities
├── 🔀 AI Útvonalválasztó Mátrix --> Cél tábla: ga_ai_routing
├── 👤 Platform Profilok --> Cél tábla: ga_platform_profiles
└── ⚙️ Platform Beállítások --> Cél tábla: ga_platform_settings
========================================================================================================================
```
---
## 5. Részletes Funkcionális Modulok & Alrendszerek
### 5.0 Ökoszisztéma Belépő Portál (Portal Hub Module)
- **Gyökér és Üdvözlő Oldal (`/`):** Kártya-alapú modulválasztó felület.
- **Aktív Modulok:**
- **GEO JSON-LD Dashboard** (Átirányít a `/geo-dashboard` felületre).
- **AI Control Center & Chat** (Átirányít az `/ai-chat` felületre).
- **AI Útvonalválasztó Mátrix** (Átirányít az `/ai-routing` felületre).
- **Adatbázis Karbantartó Hub** (Átirányít az `/admin` felületre, admin szerepkör esetén).
- **Inaktív / Foglalat Kártyák:**
- *Kurzus & Esemény Menedzser* (`ga_events_*`)
- *Kliens & Hangfürdő Nyilvántartó* (`ga_clients_*`)
- *AI Content & Marketing Studio* (`ga_ai_*`)
---
### 5.1 GEO Scraper Engine v1.1.0 & Régi Script Riasztási Modul
Az adatgyűjtő motor (`lib/scraper.ts` és `app/api/scrape/route.ts`) felelős a megadott weboldalak élő átvizsgálásáért, a sémák azonosításáért és az adatbázissal való szinkronizálásért.
#### A Scraper Engine Működési Mechanizmusa:
```text
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ÉLŐ GYŰJTÉSI FOLYAMAT (SCRAPE) │
└───────────────────────────────────────┬─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 1. KLIENS INDÍTÁS (Dashboard UI / Új oldal felvétele) │
│ - Ellenőrzi az URL létezését (ga_geo_urls upsert hiba nélkül) │
│ - Hívást küld a POST /api/scrape végpontra ({ url, url_id }) │
└───────────────────────────────────────┬─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 2. SZERVEROLDALI KÉRÉS (`lib/scraper.ts` -> runGeoScraper) │
│ - 8 másodperces AbortController időtúllépési korlát (Timeout) │
│ - Valódi böngészős fejlécek (Modern Chrome User-Agent, Accept-Language: hu-HU) │
│ - Céloldal HTML kódjának beolvasása (cache: 'no-store') │
└───────────────────────────────────────┬─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 3. ULTRA-FELVÉTELI REGEX PARSER (JSDOM Helyett) │
│ - 0% memóriaterhelés a felhőben (1 ms futásidő!) │
│ - Reguláris kifejezéssel kiszűri a <script type="application/ld+json"> elemeket│
│ - Beolvassa az attribútumokat (class, id, data-geo-source, data-geo-schema) │
└───────────────────────────────────────┬─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 4. SÉMA OSZTÁLYOZÁS & MARKER FELISMERÉS │
│ - Yoast SEO Script: Ha class/id 'yoast'-ot tartalmaz vagy @graph része │
│ - Explicit GEO Marker: class="geo-custom-schema" vagy data-geo-source="dashboard"│
│ => detection_method: "explicit_marker", needs_update: false │
│ - Legacy Fallback: Egyéb JSON-LD sémák megjelölése │
│ => detection_method: "legacy_fallback", needs_update: true │
└───────────────────────────────────────┬─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 5. SUPABASE DB SZINKRONIZÁCIÓ (`lib/supabaseServer.ts`) │
│ - Frissíti a ga_geo_urls rekordot (last_scraped_at, needs_update) │
│ - Új audit rekordot szúr be a ga_geo_scrape_audits táblába │
└─────────────────────────────────────────────────────────────────────────────────┘
```
#### Szabványos Beillesztendő HTML Script Kód:
```html
<script type="application/ld+json" class="geo-custom-schema" data-geo-source="dashboard">
{
"@context": "https://schema.org",
"@graph": [ ... ]
}
</script>
```
---
### 5.2 GEO Dashboard & Összehasonlító UI Modul
- **Oldalsáv (Sidebar):** Domain- (`ga_geo_websites`) és URL-fa (`ga_geo_urls`). Ha egy oldalon `needs_update: true` áll fenn, az URL mellett megjelenik egy **sárga figyelmeztető badge** (`Régi Script`).
- **Nézet-választók & Vezérlés:**
- **Felső gombok:** `Yoast` (+/✓ toggle), `Egyedi` (+/✓ toggle), `Felderítés` (Scraper indítás), `AI & Archívum` (Műhely modál indítás).
- **Közös / Bontott Nézet:** Egyetlen Slate Control gombbal kapcsolható a kétpaneles bontott és az egyetlen egyesített kódblokk között.
- **Régi Script Figyelmeztető Banner:**
Ha az aktív oldalon régi típusú kód fut, a kódpanel felett sárga értesítő sáv jelenik meg az **`[Új Jelölős Kód Másolása]`** akciógombbal.
- **Gyors Akciók:** Felirat nélküli kódmásoló gombok (`⧉`), Google Rich Results Test és Schema.org Validator tesztelési hivatkozások.
---
### 5.3 AI Javaslatok & Archívum Műhely Modál (v1.7.0 / v2.2.0)
Az **"AI Javaslatok & Archívum Műhely"** ablak egy 3-oszlopos rugalmas grid nézet, ahol az oszlopok egymástól függetlenül vezérelhetők.
```text
┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ AI JAVASLATOK & ARCHÍVUM MŰHELY MODÁL │
├────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ [ Fejléc: Séma választó (Egyedi / Yoast / Közös) | Oszlop toggles: [✓1. Éles] [✓2. AI] [✓3. Archívum] ] │
├──────────────────────────────────┬──────────────────────────────────┬──────────────────────────────────┤
│ 1. OSZLOP: ÉLES ADATOK │ 2. OSZLOP: AI JAVASLAT - SZERKE. │ 3. OSZLOP: ARCHÍVUM & ELŐZMÉNYEK │
│ (Scraped Yoast / Egyedi) │ (Szerkeszthető munkaterület) │ (Idővonal & Pillanatkép) │
│ - HTML <script> tag kimenet │ - Yoast / Egyedi kód inputok │ - Változástörténet Dropdown │
│ - Másolási funkciók │ - AI Javaslat megjegyzések │ - Lefagyasztott JSON kimenet │
│ - Elrejthető (Col 1 toggle) │ - [💾 Mentés] [🚀 Élesítés] │ - [📦 Éles Adatok Archiválása] │
└──────────────────────────────────┴──────────────────────────────────┴──────────────────────────────────┘
```
#### 1. Működési és Vezérlési Logika:
- **Fejléc Kapcsolók:**
- **Séma Választó:** `Egyedi` (Alapértelmezett), `Yoast`, `Közös`.
- **Oszlop Megjelenítők:** `1. Éles adatok`, `2. AI Javaslat - szerkesztés`, `3. Archívum & Előzmények`. Bármelyik oszlop elrejthető, így a megmaradt oszlopok automatikusan kitöltik a rendelkezésre álló területet.
- **Közös Nézet Al-fül (`proposalSubTab`):** A 2. oszlopban al-fülekkel (`Egyedi GEO` / `Yoast SEO`) váltható a szerkesztendő JSON-LD kód anélkül, hogy függőlegesen görgetni kellene.
#### 2. Hibatűrő JSON Tisztítás & Mentés (`handleSaveProposal`):
- A `cleanJsonString` eljárás automatikusan eltávolítja a véletlenül bemásolt `<script type="application/ld+json">...</script>` HTML tageket.
- Szintaktikai JSON hiba esetén a felület nem omlik össze, hanem részletes, magyar nyelvű hibaüzenetet ad a pontos hiba megnevezésével.
- Mentéskor a frissített adatok a `ga_geo_scrape_audits` tábla alábbi mezőibe kerülnek rögzítésre:
- `yoast_json_ld_ai_proposal`
- `custom_json_ld_ai_proposal`
- `ai_proposal_notes`
- `ai_proposal_updated_at`
#### 3. Dinamikus Élesítés (`handlePromoteProposal`):
- Az **"🚀 Élesítés"** gomb a kiválasztott nézet alapján automatikusan az éles mezőkbe (`yoast_json_ld`, `custom_json_ld`) másolja a jóváhagyott AI javaslatot.
- Az élesítés után az 1. oszlop és a fő Dashboard felület azonnal frissül.
#### 4. Változástörténet (Audit History Timeline):
- A 3. oszlop tartalmazza az adott URL-hez tartozó összes korábbi audit rekord legördülő listáját (`auditHistory`).
- Az idővonalon kiválasztott pillanatkép JSON-LD kódja azonnal megjelenik a kódnézegetőben.
- A **`📦 Éles Adatok Archiválása (Snapshot)`** gombra kattintva az éles adatok lefagyasztott pillanatként elmentődnek a `yoast_json_ld_archive` és `custom_json_ld_archive` mezőkbe.
---
### 5.4 Tipizált GEO Sablonok
Az AI generáló modul előre beállított és optimalizált sémákkal dolgozik az aloldal típusa szerint:
1. **`Course` / `EducationalOccupationalProgram`:** Tanfolyamok, képzések, gongsugárzási kurzusok (tartalmazza a kurzus időtartamát, oktatóját, árát, helyszínét).
2. **`Event` / `MusicEvent`:** Hangfürdők, workshopok, konkrét időpontos események (kezdési/befejezési időpont, szervező, jegyár).
3. **`EducationalOrganization` / `LocalBusiness`:** Rólunk, kapcsolat, az Akadémia központi entitása (geolokációs koordináták, nyitvatartás, elérhetőségek).
4. **`FAQPage`:** Gyakran Ismételt Kérdések struktúrája (kérdés-válasz párok).
5. **`Article` / `BlogPosting`:** Ismeretterjesztő cikkek, szakmai bejegyzések (szerző, publikálási dátum, módosítás dátuma).
---
### 5.5 Globális Entitás-tár (Global Entity Registry és `@id` Konzisztencia)
A `ga_geo_entity_registry` tábla tárolja a szervezet, az oktatók, a helyszínek és egyéb újrahasznosítható elemek hivatalos törzsadatait.
- **Példa stabil azonosítók:**
- `https://gongakademia.hu/#organization`
- `https://gongakademia.hu/#person-szabogabor`
- `https://gongakademia.hu/#place-budapest-studio`
- **Automatikus Prompt Injection:** AI generáláskor az érintett entitások adatai bekerülnek az AI kontextusába, megelőzve az ellentmondó vagy eltérő `@id` azonosítók használatát.
---
### 5.6 Multi-Provider AI Engine, Routing Matrix & Smart Failover (v2.2.0)
A GongGEO Intelligence HUB AI alrendszere (`lib/ai-engine/ai-engine.ts`) teljes mértékben service-agnosztikus.
#### 1. Útvonalválasztási Mátrix (`ga_ai_routing` tábla):
Minden rendszerfunkcióhoz (pl. `geo_benefit_generator`, `ai_chat`, `schema_validator`) külön rögzíthető az útvonalválasztási szabály:
- **`primary_provider` & `primary_model`:** Elsődleges AI szolgáltató és modell.
- **`timeout_seconds`:** Maximális várakozási idő másodpercben (alapértelmezetten 8 mp).
- **`fallback_1_provider` & `fallback_1_model`:** Másodlagos tartalék szolgáltató.
- **`fallback_2_provider` & `fallback_2_model`:** Harmadlagos tartalék szolgáltató.
#### 2. Smart Failover Engine:
Amikor a kód meghívja az `executeAiTask(caller, prompt)` függvényt:
1. Beolvassa a `ga_ai_routing` táblából az aktív `caller` rekordot.
2. Megkísérli a hívást az elsődleges provider felé `AbortSignal.timeout(timeout_seconds * 1000)` védelemmel.
3. Ha az elsődleges hívás időtúllépés (timeout) vagy hiba miatt meghiúsul, a rendszer automatikusan feljegyzi a hibát és átvált a **Fallback 1** szolgáltatóra.
4. Ha a Fallback 1 is meghiúsul, automatikusan átvált a **Fallback 2** szolgáltatóra.
5. A felhasználó vagy a felület zavartalanul megkapja a választ a tartalék ágról.
---
### 5.7 Live Debug Inspector Window (`/ai-routing#inspector`)
Egy valós idejű lebegő vagy beágyazott ablak, amely az alábbi adatokat mutatja élőben:
- Kiment prompt és alkalmazott funkció-azonosító (`caller`).
- Választott provider, modell és futási idő (ms).
- Esetleges Failover események (pl. *"OpenAI timed out after 8s -> Switched to Gemini 2.0 Flash"*).
- Nyers JSON / Szöveges AI válasz.
---
### 5.8 Változáskövetés (Diff Engine) & Alerting System
- **JSON Diff Vizualizáció:** Két kiválasztott audit pillanatkép JSON kódjának összehasonlítása. A törölt elemek piros, az új elemek zöld, a módosult elemek kontextusban sárga kiemelést kapnak.
- **Schema Health-Check & Riasztási Kódok:**
- Nem HTTP `200` válasz esetén riasztás jön létre.
- Korábban meglévő Yoast vagy egyedi JSON-LD eltűnése esetén `CRITICAL_SCHEMA_MISSING` riasztás jön létre.
- Hibás vagy nem parse-olható JSON-LD esetén `SYNTAX_ERROR` jelzés generálódik.
- A riasztás nem törli és nem írja felül a legutóbbi sikeres adatot.
- **Értesítési Csatornák:** Webhook, Telegram és Email értesítési csatornák szerveroldali előkészítése.
---
### 5.9 WordPress REST API Auto-Injektor Előkészítés & Biztonsági Elvek
- **Kézi másolás:** Egykattintásos kódmásolás a vágólapra.
- **Direct REST API Injektálás:** A jóváhagyott JSON-LD kód a WordPress REST API-n (`POST /wp-json/wp/v2/pages/<id>`) vagy a GongAkadémia WordPress bővítményen keresztül közvetlenül az adott oldal metaadatába küldhető, amit a bővítmény a HTML `<head>` részben helyez el.
- **Kötelező Biztonsági Elv:** Publikálás előtt cél-URL, tartalom hash, jóváhagyott `status: 'approved'` és felhasználói megerősítés szükséges.
---
### 5.10 Dinamikus Adatbázis Karbantartó Hub (`/admin`) és Táblázat Engine
Az Adatbázis Karbantartó felület egy univerzális, magasan konfigurálható táblázat-architektúrát használ a platform összes táblájának kezelésére.
#### Főbb Szabványok és Működési Elvek:
1. **Dinamikus Oszlopszélesség Állítás (`Column Resizing`):** Egérrel húzható elválasztó sáv minden oszlopfejléces cellán. Alapértelmezett oszlopszélesség korlát: **240px**.
2. **Kétsoros Fejléc Törés (`Multi-line Header Wrap`):** A fejléc cellák (`th`) `whitespace-normal break-words leading-tight` osztályt használnak, megelőzve, hogy a hosszú fejléc-szöveg megakadályozza az oszlop még keskenyebbre húzódását.
3. **Oszlopsorrend Átrendezése Húzással (`Drag & Drop Column Reordering`):** A `th` cellák drag handle-nél (`⋮⋮`) megfoghatók és átrendezhetők.
4. **Böngészőoldali Perzisztencia (`localStorage`):** A szélességek (`geodashboard_col_widths_v1`) és a sorrendek (`geodashboard_col_orders_v1`) automatikusan elmentődnek táblánként.
5. **`↔️` Alaphelyzetbe Állítás (Layout Reset):** Egyetlen kattintással visszaállítja a gyári alapértelmezett oszlopszélességeket és sorrendet.
6. **Idegen Kulcsok (`FK`) és ID Oszlopok Intelligens Rejtése:** A **`🔑 ID Mutatása / ID Elrejtése`** gomb kapcsolja az azonosítók láthatóságát.
7. **Egységes Dátum- és Időformátum:** `YYYY.MM.DD HH:mm` formátum (pl. `2026.08.02 15:40`).
8. **Javított Boolean & Státusz Megjelenítés:** Logikai értékeknél státusz mezőben `"Aktív"` (zöld) / `"Inaktív"` (piros), egyéb jelzőknél `"Igen"` / `"Nem"`, szegély- és háttérmentes letisztult betűszínnel.
---
## 6. 📊 Összefoglaló és Standardok: A Táblázat Oszlopbeállítási Lehetőségei és Működési Modelljei
Az alábbi táblázat és szabályrendszer írja le a GongGEO Intelligence HUB adatbázis-táblázatainak építési szabványait:
### 6.1 Oszlopbeállítási Modellek Összehasonlítása
| Megoldási Modell | Működés & Jellemzők | Előnyök | Hátrányok / Korlátok |
| :--- | :--- | :--- | :--- |
| **1. Natural / Fluid (`table-auto`)** *(Standard alapállapot)* | Az oszlopok szélességét a bennük található adatok hossza határozza meg automatikusan. | Optimális helykihasználás, nem marad felesleges üres hely. | Nagyon hosszú adatok elhúzhatják az oszlopot (ezért alkalmazunk `maxWidth: 240px` korlátot). |
| **2. Fixed Layout (`table-fixed`)** | Az oszlopok egyenlő vagy százalékos szélességet kapnak a szülő konténer alapján. | Szigorú elrendezés, gyors böngésző-renderelés. | Rövid adatoknál felesleges üres hely marad, hosszú adatok elvágódnak. |
| **3. Explicit User-Resized (Drag-and-Drop / Handle)** *(Manuális felülbírálás)* | Az egérrel történő átméretezés felülírja az automatikus szabályokat, és pixel pontossággal rögzíti az oszlopszélességet (`style={{ width: `${px}px` }}`). | A felhasználó teljes kontrollt kap az elrendezés felett. | A rögzített méretek miatt nagyon kis ablaknál megjelenik a vízszintes scroll (amíg a `Reset ↔️` gombbal nem törli). |
| **4. Multi-line Header Wrap vs. Cell Truncate** | A fejléc szövege többsorosra törhet (`break-words`), míg az adatcella 1 soros marad és levágódik (`truncate`). | Lehetővé teszi az oszlopok maximális keskenyítését úgy, hogy a fejléc címe olvasható marad. | Többsoros fejléc esetén a fejléc sora magasabb lesz. |
### 6.2 Kötelező Implementációs Szabályok Új Táblázatok Építésekor:
1. **Fejléc törés támogatása:** A `th` elemekben a címkék mindig `whitespace-normal break-words leading-tight` osztályt kapnak `truncate` helyett, hogy az oszlop szűkítéskor minimális szélességre tudjon összecsukódni.
2. **Adatcellák maximalizálása:** Az alapértelmezett adatcellák (`td`) `maxWidth: '240px'` korlátot kapnak és `truncate` osztállyal vannak ellátva a túlhúzódások elkerülésére.
3. **Kézi Átméretezés (Resizing):** Az oszlopszélesség állítása során a mentett `columnWidths` objektumból származó érték felülírja a 240px-es korlátot, és `width`, `minWidth`, `maxWidth` tulajdonságként érvényesül a `th` és `td` elemeken.
4. **Vízszintes Scrollozhatóság:** A táblázat szülő eleme mindig `flex-1 overflow-x-auto border border-slate-800 rounded-xl bg-slate-950/50 scrollbar-thin scrollbar-thumb-amber-500/30` beállítást kap.
5. **Layout Reszponzivitás:** A fő konténerekből kerülni kell a rögzített `max-w-7xl` korlátozást a táblázatos nézetekben, helyette `w-full px-4 sm:px-6` használandó.
---
## 7. AI Prompt Architektúra, System Prompt & Zod Validáció
### 7.1 System Prompt Sablon
```text
You are an expert Generative Engine Optimization (GEO) & Schema.org Structured Data Architect for GongAkadémia.
Your task is to generate valid, syntactically perfect JSON-LD structured data.
Rules:
1. Always include "@context": "https://schema.org".
2. Use absolute, stable URIs for "@id" values matching the Global Entity Registry provided in context.
3. Combine relevant types using multi-type arrays where applicable (e.g. ["Course", "EducationalOccupationalProgram"]).
4. Include rich entity references where factual source data supports them.
5. Never invent factual claims, prices, dates, people, locations, reviews or credentials.
6. Output MUST strictly adhere to the provided JSON Schema.
7. Do NOT include markdown code blocks (```json) in raw JSON mode.
```
### 7.2 Zod Schema Validációs TypeScript Implementáció
```typescript
import { z } from 'zod';
export const GeoJsonLdSchema = z.object({
'@context': z.literal('https://schema.org'),
'@graph': z.array(
z.object({
'@type': z.union([z.string(), z.array(z.string())]),
'@id': z.string().url(),
name: z.string().optional(),
description: z.string().optional(),
provider: z.record(z.any()).optional(),
hasCourseInstance: z.array(z.record(z.any())).optional(),
}).passthrough()
)
});
```
---
## 8. Biztonság, Autentikáció és Beállítások
### 8.1 Globális Autentikációs Védelmi Réteg (`require_login`)
A `ga_platform_settings` tábla `require_login` (boolean) paramétere vezérli a rendszer hozzáférhetőségét:
1. **Reaktív Kliensoldali Védelem (`AuthContext.tsx`):**
- Az `AuthContext` a `usePathname()` hook segítségével minden útvonalváltást megfigyel.
- Ha a `require_login` értéke `true` és nincs bejelentkezett felhasználó (`!user`), az alkalmazás **azonnal átirányítja a böngészőt a `/login` oldalra**.
2. **Navigációs UI Zárolás (`Navbar.tsx` & `HeaderActions.tsx`):**
- Nem hitelesített állapotban a védett menüpontok rejtve maradnak, a szendvics menüben pedig zárolási tájékoztató jelenik meg.
3. **Profil Kezelés & Szerepkörök (`ga_platform_profiles`):**
- Regisztrációkor a duplikált e-mailek szűrésre kerülnek.
- Az új felhasználók alapértelmezetten `pending` státusszal és `viewer` szerepkörrel jönnek létre. Az `admin` szerepkörű felhasználók hozzáférnek az `/admin` karbantartó felülethez.
---
## 9. Teljes Adatbázis Séma (Supabase PostgreSQL `v2.2.0`)
Az alábbi SQL script tartalmazza az ökoszisztéma teljes adatbázis-struktúráját valamennyi prefixált táblával, indexszel, AI routing táblával és RLS szabállyal:
```sql
-- =============================================================================
-- 1. PLATFORM / ÖKOSZISZTÉMA TÖRZSTÁBLÁK (ga_platform_*)
-- =============================================================================
-- 1.1 Platform Beállítások (require_login, auto_show_debug_modal, stb.)
CREATE TABLE IF NOT EXISTS ga_platform_settings (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
key TEXT NOT NULL UNIQUE,
value TEXT NOT NULL,
description TEXT,
updated_at TIMESTAMPTZ DEFAULT now()
);
-- Alapértelmezett platform beállítások
INSERT INTO ga_platform_settings (key, value, description)
VALUES
('require_login', 'true', 'Rendszerszintű autentikációs kényszerítés (true/false)'),
('auto_show_debug_modal', 'false', 'Debug információk automatikus megjelenítése')
ON CONFLICT (key) DO NOTHING;
-- 1.2 Felhasználói Profilok
CREATE TABLE IF NOT EXISTS ga_platform_profiles (
id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
user_id UUID,
email TEXT NOT NULL,
full_name TEXT,
avatar_url TEXT,
role TEXT NOT NULL DEFAULT 'viewer' CHECK (role IN ('admin', 'editor', 'viewer')),
status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('active', 'pending', 'suspended')),
created_at TIMESTAMPTZ DEFAULT now(),
updated_at TIMESTAMPTZ DEFAULT now()
);
-- 1.3 Modul Regiszter
CREATE TABLE IF NOT EXISTS ga_platform_modules (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
module_key TEXT NOT NULL UNIQUE,
name TEXT NOT NULL,
description TEXT,
route_path TEXT NOT NULL,
icon_name TEXT NOT NULL,
is_active BOOLEAN DEFAULT true,
display_order INT DEFAULT 0,
created_at TIMESTAMPTZ DEFAULT now()
);
-- 1.4 Felhasználói Preferenciák (Skins & Beállítások)
CREATE TABLE IF NOT EXISTS user_preferences (
user_id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
selected_skin VARCHAR(50) NOT NULL DEFAULT 'gong-dark',
default_website_id UUID,
updated_at TIMESTAMPTZ DEFAULT now()
);
-- =============================================================================
-- 2. GEO JSON-LD DASHBOARD MODUL TÁBLÁK (ga_geo_*)
-- =============================================================================
-- 2.1 GEO Webhelyek / Domainek
CREATE TABLE IF NOT EXISTS ga_geo_websites (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name TEXT NOT NULL,
domain_name TEXT,
domain_url TEXT NOT NULL UNIQUE,
base_url TEXT,
is_active BOOLEAN DEFAULT true,
created_at TIMESTAMPTZ DEFAULT now(),
updated_at TIMESTAMPTZ DEFAULT now()
);
-- 2.2 GEO Aloldalak / URL-ek
CREATE TABLE IF NOT EXISTS ga_geo_urls (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
website_id UUID REFERENCES ga_geo_websites(id) ON DELETE CASCADE,
url_path TEXT NOT NULL,
full_url TEXT NOT NULL,
title TEXT,
needs_update BOOLEAN DEFAULT false,
last_scraped_at TIMESTAMPTZ,
created_at TIMESTAMPTZ DEFAULT now(),
updated_at TIMESTAMPTZ DEFAULT now(),
UNIQUE(website_id, url_path)
);
-- 2.3 GEO Scrape Audits, AI Proposal & Archívum Napló
CREATE TABLE IF NOT EXISTS ga_geo_scrape_audits (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
url_id UUID REFERENCES ga_geo_urls(id) ON DELETE CASCADE,
executed_at TIMESTAMPTZ DEFAULT now(),
http_status INT NOT NULL,
response_time_ms INT,
yoast_json_ld JSONB,
custom_json_ld JSONB,
ai_proposal_notes TEXT,
yoast_json_ld_ai_proposal JSONB,
custom_json_ld_ai_proposal JSONB,
yoast_json_ld_archive JSONB,
custom_json_ld_archive JSONB,
ai_proposal_updated_at TIMESTAMPTZ,
detection_summary JSONB,
needs_update BOOLEAN DEFAULT false,
raw_scripts_found INT DEFAULT 0
);
-- Index a legfrissebb audit bejegyzések gyors lekérdezéséhez
CREATE INDEX IF NOT EXISTS idx_ga_geo_audits_url_executed
ON ga_geo_scrape_audits(url_id, executed_at DESC);
-- 2.4 GEO Verziózott Schemak
CREATE TABLE IF NOT EXISTS ga_geo_custom_schemas (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
url_id UUID REFERENCES ga_geo_urls(id) ON DELETE CASCADE,
version INT NOT NULL DEFAULT 1,
schema_data JSONB NOT NULL,
status TEXT CHECK (status IN ('draft', 'published', 'archived')) DEFAULT 'draft',
created_by UUID REFERENCES ga_platform_profiles(id),
created_at TIMESTAMPTZ DEFAULT now()
);
-- 2.5 GEO Entitás Törzsadat Regiszter (@id Registry)
CREATE TABLE IF NOT EXISTS ga_geo_entity_registry (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
entity_id_uri TEXT NOT NULL UNIQUE,
entity_type TEXT NOT NULL,
name TEXT NOT NULL,
payload_jsonb JSONB NOT NULL,
created_at TIMESTAMPTZ DEFAULT now(),
updated_at TIMESTAMPTZ DEFAULT now()
);
-- 2.6 GEO Ismeretlen Entitások (Unmapped Entities)
CREATE TABLE IF NOT EXISTS ga_geo_unmapped_entities (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
url_id UUID REFERENCES ga_geo_urls(id) ON DELETE CASCADE,
raw_entity_name TEXT NOT NULL,
suggested_type TEXT,
context_snippet TEXT,
status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'resolved', 'ignored')),
created_at TIMESTAMPTZ DEFAULT now()
);
-- =============================================================================
-- 3. AI ENGINE MODUL TÁBLÁK (ga_ai_*)
-- =============================================================================
-- 3.1 AI Útvonalválasztó Mátrix & Smart Failover (ga_ai_routing)
CREATE TABLE IF NOT EXISTS ga_ai_routing (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
caller TEXT NOT NULL UNIQUE,
display_name TEXT NOT NULL,
description TEXT,
primary_provider TEXT NOT NULL,
primary_model TEXT NOT NULL,
timeout_seconds INT DEFAULT 8,
fallback_1_provider TEXT,
fallback_1_model TEXT,
fallback_2_provider TEXT,
fallback_2_model TEXT,
is_active BOOLEAN DEFAULT true,
created_at TIMESTAMPTZ DEFAULT now(),
updated_at TIMESTAMPTZ DEFAULT now()
);
-- Alapértelmezett AI útvonalak beszúrása
INSERT INTO ga_ai_routing (caller, display_name, description, primary_provider, primary_model, timeout_seconds, fallback_1_provider, fallback_1_model)
VALUES
('geo_benefit_generator', 'GEO Benefit Auto-Generátor', 'Generálja a GEO JSON-LD előnyöket és sémákat', 'freellmapi', 'fusion', 8, 'openai', 'gpt-4o-mini'),
('ai_chat', 'AI Konzol Interaktív Chat', 'Általános AI asszisztens felület', 'freellmapi', 'auto', 10, 'gemini', 'gemini-2.0-flash'),
('schema_validator', 'Schema Validator AI Engine', 'Séma strukturális ellenőrzése', 'openai', 'gpt-4o', 8, 'freellmapi', 'fusion')
ON CONFLICT (caller) DO NOTHING;
-- =============================================================================
-- 4. ROW LEVEL SECURITY (RLS) POLICIES
-- =============================================================================
ALTER TABLE ga_platform_settings ENABLE ROW LEVEL SECURITY;
ALTER TABLE ga_platform_profiles ENABLE ROW LEVEL SECURITY;
ALTER TABLE ga_platform_modules ENABLE ROW LEVEL SECURITY;
ALTER TABLE user_preferences ENABLE ROW LEVEL SECURITY;
ALTER TABLE ga_geo_websites ENABLE ROW LEVEL SECURITY;
ALTER TABLE ga_geo_urls ENABLE ROW LEVEL SECURITY;
ALTER TABLE ga_geo_scrape_audits ENABLE ROW LEVEL SECURITY;
ALTER TABLE ga_geo_custom_schemas ENABLE ROW LEVEL SECURITY;
ALTER TABLE ga_geo_entity_registry ENABLE ROW LEVEL SECURITY;
ALTER TABLE ga_geo_unmapped_entities ENABLE ROW LEVEL SECURITY;
ALTER TABLE ga_ai_routing ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Hitelesített felhasználók mindent kezelhetnek" ON ga_platform_settings FOR ALL TO authenticated USING (true) WITH CHECK (true);
CREATE POLICY "Hitelesített felhasználók mindent kezelhetnek" ON ga_platform_profiles FOR ALL TO authenticated USING (true) WITH CHECK (true);
CREATE POLICY "Hitelesített felhasználók mindent kezelhetnek" ON ga_platform_modules FOR ALL TO authenticated USING (true) WITH CHECK (true);
CREATE POLICY "Felhasználó kezeli a saját preferenciáit" ON user_preferences FOR ALL TO authenticated USING (auth.uid() = user_id) WITH CHECK (auth.uid() = user_id);
CREATE POLICY "Hitelesített felhasználók mindent kezelhetnek" ON ga_geo_websites FOR ALL TO authenticated USING (true) WITH CHECK (true);
CREATE POLICY "Hitelesített felhasználók mindent kezelhetnek" ON ga_geo_urls FOR ALL TO authenticated USING (true) WITH CHECK (true);
CREATE POLICY "Hitelesített felhasználók mindent kezelhetnek" ON ga_geo_scrape_audits FOR ALL TO authenticated USING (true) WITH CHECK (true);
CREATE POLICY "Hitelesített felhasználók mindent kezelhetnek" ON ga_geo_custom_schemas FOR ALL TO authenticated USING (true) WITH CHECK (true);
CREATE POLICY "Hitelesített felhasználók mindent kezelhetnek" ON ga_geo_entity_registry FOR ALL TO authenticated USING (true) WITH CHECK (true);
CREATE POLICY "Hitelesített felhasználók mindent kezelhetnek" ON ga_geo_unmapped_entities FOR ALL TO authenticated USING (true) WITH CHECK (true);
CREATE POLICY "Hitelesített felhasználók mindent kezelhetnek" ON ga_ai_routing FOR ALL TO authenticated USING (true) WITH CHECK (true);
```
---
## 10. Fejlesztési Roadmap, Megvalósítási Állapot & Mérföldkövek (Phase 1 - Phase 8)
| Fázis | Funkció | Állapot | Megjegyzés |
|-------|---------|---------|------------|
| **Fázis 1** | Adatbázis sémák & AI Engine Core | **✅ KÉSZ** | Táblák, providerek, registry, token tracker, API gateway kész. |
| **Fázis 2** | Interaktív CLI Chat felület (`/ai-chat`) | **✅ KÉSZ** | Teljes UI, előzmények, paraméterezés, 80+ élő modell választó. |
| **Fázis 3** | GEO Benefit Auto-Generátor | **✅ KÉSZ** | Auto-generáló gomb a dashboardon, JSON módú végpont kész. |
| **Fázis 4** | Útvonalválasztási Mátrix & Smart Failover | **✅ KÉSZ** | `ga_ai_routing` tábla, 3-lépcsős tartalék lánc, timeout kezelés. |
| **Fázis 5** | Live Debug Inspector & Beállítások UI | **✅ KÉSZ** | `/ai-routing` kezelőfelület, élő szerviz ablak. |
| **Fázis 6** | Egységesített UX & Menü-Refaktorálás | **✅ KÉSZ** | Zsúfoltságmentesített Hamburger menü és szinkronizált `/admin` felület. |
| **Fázis 7** | Vizualizációs Tisztítás & Bools | **✅ KÉSZ** | Zárójeles kódkiírások eltávolítása a felületről, pontos boolean szövegezés ("Aktív/Inaktív", "Igen/Nem"). |
| **Fázis 8** | Dinamikus Admin Táblázat UI & Reszponzív Header | **✅ KÉSZ** | Reszponzív full-width elrendezés, kétsoros fejléc-törés, 240px maximált alapértelmezett oszlopszélesség manuális felülírhatósággal, automatikus vízszintes görgetés és szimmetrikus top header. |
| **Fázis 9** | Kattintható URL-ek, JSON Megnevezés & Függőleges Görgetés | **✅ KÉSZ** | Kattintható élő hivatkozások (`full_url`, `domain_url`, `sample_url`), frissített `[JSON megnevezés]` gomb felirat, valamint önálló függőleges görgetősáv rögzített táblázatfejléccel (`sticky top-0`). |
---
## 11. Vercel Telepítési, CI/CD és UI/UX Szabványok
1. **1 MB Edge Function Korlát Kerülése:**
- A Vercel ingyenes (Hobby) csomagja legfeljebb 1 MB Edge Function méretet engedélyez.
- Az automatikus ikonképző (`app/icon.tsx`) és API végpontok **Node.js Serverless runtime-on** futnak (`export const runtime = 'nodejs';`).
2. **Supabase Auth Redirect URL Beállítás:**
- **Site URL:** `https://<app-name>.vercel.app`
- **Redirect URLs:** `https://<app-name>.vercel.app/**`
3. **Build Parancs:**
- Hálózati meghajtók / Windows elérési utak kompatibilitása miatt a build parancs: `next build --webpack` (Webpack fordító használatával).
4. **Slate Control Gombcsalád & Téma:**
- A navigációs és akciósávok sötét pala / grafit árnyalatú visual rendszert használó gombcsaládot alkotnak (`bg-[#111827] text-gray-300 border border-white/10 hover:text-white`).
5. **Adatbázis Karbantartó Hub UI/UX & Interaktivitási Szabványok (`v2.2.1`):**
- **Kattintható URL mezők:** A `ga_geo_urls` (`full_url`), `ga_geo_websites` (`domain_url`), valamint a `ga_geo_unmapped_entities` (`sample_url`) mezők cellái automatikusan kattintható linkként jelennek meg (`target="_blank" rel="noopener noreferrer"`), külső hivatkozási ikonal (↗).
- **JSON Megnevezés gomb:** A JSON formátumú oszlopokban (pl. `ga_geo_scrape_audits`) található elemző gomb felirata egységesen `[JSON megnevezés]`.
- **Belső Függőleges Görgethetőség & Rögzített Fejléc (Sticky Header):** A táblázatos felület egy rögzített magasságú nézetben (`h-[calc(100vh-65px)]`) helyezkedik el `overflow-hidden` szülővel. A táblázat adatkonténere `flex-1 min-h-0 overflow-auto` tulajdonságokkal rendelkezik, ami biztosítja, hogy nagy mennyiségű adat esetén **kizárólag az adatsorok görgethetőek függőlegesen és vízszintesen**, míg a vezérlősávok és a táblázatfejléc (`sticky top-0 z-20 bg-slate-900`) mindvégig fixen láthatóak maradnak.
---
## 12. Elfogadási Kritériumok (`v2.2.1`)
1. A `require_login = true` beállítás esetén nem hitelesített munkamenettel semmilyen védett oldal nem érhető el; a rendszer átirányít a `/login` felületre.
2. A Scraper Engine 8 másodperces korláttal, bot-védelmi fejlécekkel és ultra-gyors Regex parserrel fut felhőben és lokálisan egyaránt.
3. Az *"AI Javaslatok & Archívum Műhely"* modálban mindhárom oszlop függetlenül ki/bekapcsolható, a szerkesztett JSON-LD kód tisztítása és élesítése hibátlanul lefut.
4. Az archívum idővonali legördülőből korábbi pillanatképek visszanézhetők, és új snapshot készíthető.
5. Az Adatbázis Karbantartóban (`/admin`) a `ga_geo_scrape_audits`, `ga_ai_routing` és az összes platform tábla hiánytalanul szerkeszthető, szűrhető, rendezhető és átméretezhető.
6. A Multi-Provider AI Engine láthatatlanul és hibátlanul hajtja végre a Smart Failover ágakat hiba vagy időtúllépés esetén.
7. A projekt sikeresen buildelhető (`npm run build` exit code 0).
8. Az Adatbázis Karbantartó táblázat adatsorai önálló függőleges görgetősávval rendelkeznek, az URL mezők új ablakban nyíló linkek, a JSON vizsgálat gomb felirata `[JSON megnevezés]`, a táblázat feje görgetés közben rögzített.
---
## 13. Git & Verziókezelési Információk
- **Aktív Ág:** `main` / `feature/ai-engine-v2`
- **Verzió:** `v2.2.1`
- **Adatbázis Projekt:** `MandaliniGEO` (`cixcnxqrsevnvqneznbb`)