# 🏗️ Logic Spec: P0 EPIC - i18n JSONB Database Migration (Phase 1)

**Gitea Issue:** [#399](https://gitea.profibot.hu/kincses/service-finder/issues/399)
**Státusz:** Tervezés alatt (Architect Review)
**Dátum:** 2026-07-07
**Architect:** Rendszer-Architect

---

## 1. Cél és Masterbook 2.0 Illeszkedés

### 1.1 Cél
A 24 EU nyelv támogatásához egységes JSONB-alapú lokalizációs architektúra bevezetése. A jelenlegi gyakorlat, ahol minden nyelvhez külön VARCHAR oszlop tartozik (`name_hu`, `name_en`), nem skálázható. Helyette egyetlen JSONB oszlopot (`name_i18n`) használunk, ahol a kulcsok a nyelvi kódok (pl. `{"hu": "Szedán", "en": "Sedan", "de": "Limousine"}`).

### 1.2 Masterbook 2.0 Illeszkedés
- **2A Elv:** A kód a mérvadó → a Wiki frissítése a migráció után kötelező.
- **DDD szeparáció:** Minden érintett tábla külön schema-ban van (`marketplace`, `vehicle`, `system`).
- **Soft-delete:** Nem releváns (dictionary táblák, nincs soft-delete).

---

## 2. Hatáselemzés (Impact Analysis)

### 2.1 Érintett Táblák (Database)

| Schema | Tábla | Jelenlegi Oszlopok | Cél Oszlopok | Megjegyzés |
|--------|-------|-------------------|--------------|------------|
| `marketplace` | `expertise_tags` | `name_hu VARCHAR`, `name_en VARCHAR`, `name_translations JSONB`, `description TEXT` | `name_i18n JSONB`, `description_i18n JSONB` | `name_translations` megmarad opcionális kiegészítőként |
| `vehicle` | `dict_body_types` | `name_hu VARCHAR` | `name_i18n JSONB` | Egyszerű csere |
| `system` | `service_catalog` | `name VARCHAR`, `description VARCHAR` | `name_i18n JSONB`, `description_i18n JSONB` | Teljesen új oszlopok |

### 2.2 Érintett Modell Fájlok (SQLAlchemy)

| Fájl | Osztály | Művelet |
|------|---------|---------|
| `backend/app/models/marketplace/service.py` | `ExpertiseTag` | Add `name_i18n`, `description_i18n`; Remove `name_hu`, `name_en`; Keep `name_translations` |
| `backend/app/models/vehicle/vehicle_definitions.py` | `BodyTypeDictionary` | Replace `name_hu` with `name_i18n` |
| `backend/app/models/core_logic.py` | `ServiceCatalog` | Replace `name` with `name_i18n`, `description` with `description_i18n` |

### 2.3 Érintett Schema Fájlok (Pydantic)

| Fájl | Osztály | Művelet |
|------|---------|---------|
| `backend/app/schemas/provider.py` | `CategoryTreeNode`, `CategoryAutocompleteItem`, `ExpertiseCategoryOut`, `CategoryInfo` | Replace `name_hu`/`name_en` with `name_i18n` |
| `backend/app/schemas/service_catalog.py` | `ServiceCatalogCreate`, `ServiceCatalogUpdate`, `ServiceCatalogResponse` | Replace `name`/`description` with `name_i18n`/`description_i18n` |

### 2.4 Érintett Végpontok (API)

| Fájl | Végpont | Művelet |
|------|---------|---------|
| `backend/app/api/v1/endpoints/providers.py` | `GET /categories/tree` | Frissíteni `name_hu`/`name_en` → `name_i18n` |
| `backend/app/api/v1/endpoints/providers.py` | `GET /categories/autocomplete` | Frissíteni a keresést `name_i18n`-re (JSONB contains) |
| `backend/app/api/v1/endpoints/providers.py` | `GET /categories` | Frissíteni a response-öt |
| `backend/app/api/v1/endpoints/catalog.py` | `GET /catalog/body-types` | Frissíteni `name_hu` → `name_i18n` |
| `backend/app/api/v1/endpoints/admin_services.py` | `GET/POST/PATCH /admin/services` | Frissíteni ServiceCatalog schema-t |

### 2.5 Érintett Seed Szkriptek

| Fájl | Művelet |
|------|---------|
| `backend/scripts/seed_body_types.py` | Frissíteni `name_hu` → `name_i18n` |
| `backend/app/scripts/seed_services.py` | Frissíteni `name`/`description` → `name_i18n`/`description_i18n` |

---

## 3. Adatmodell Terv

### 3.1 JSONB Oszlop Formátum

```json
{
  "hu": "Magyar név",
  "en": "English name",
  "de": "Deutscher Name"
}
```

**Kötelező mező:** Minden `name_i18n` oszlopban a `"hu"` kulcs kötelező (`server_default='{"hu": ""}'::jsonb`).

### 3.2 GIN Index

```sql
CREATE INDEX idx_expertise_tags_name_i18n ON marketplace.expertise_tags USING GIN (name_i18n);
CREATE INDEX idx_dict_body_types_name_i18n ON vehicle.dict_body_types USING GIN (name_i18n);
CREATE INDEX idx_service_catalog_name_i18n ON system.service_catalog USING GIN (name_i18n);
```

### 3.3 Részletes Oszlop Tervek

#### `marketplace.expertise_tags`

```python
# ÚJ oszlopok (ADD)
name_i18n: Mapped[dict] = mapped_column(JSONB, nullable=False, server_default=text("'{\"hu\": \"\"}'::jsonb"))
description_i18n: Mapped[Optional[dict]] = mapped_column(JSONB, nullable=True)

# MEGTARTVA (a meglévő name_translations továbbra is használható bővített fordításokhoz)
name_translations: Mapped[Any] = mapped_column(JSONB, server_default=text("'{}'::jsonb"))

# TÖRLENDŐ oszlopok (DROP)
# name_hu: Mapped[Optional[str]] = mapped_column(String(100))
# name_en: Mapped[Optional[str]] = mapped_column(String(100))
# description: Mapped[Optional[str]] = mapped_column(Text)
```

> **Döntés:** A `name_translations` oszlop MEGMARAD, mivel a `name_i18n` csak az alap 24 EU nyelvet tartalmazza, a `name_translations` pedig extra (nem EU) nyelvekhez vagy bővített lokalizációhoz használható.

#### `vehicle.dict_body_types`

```python
# ÚJ oszlop (ADD)
name_i18n: Mapped[dict] = mapped_column(JSONB, nullable=False, server_default=text("'{\"hu\": \"\"}'::jsonb"))

# TÖRLENDŐ oszlop (DROP)
# name_hu: Mapped[str] = mapped_column(String(100), nullable=False)
```

#### `system.service_catalog`

```python
# ÚJ oszlopok (ADD)
name_i18n: Mapped[dict] = mapped_column(JSONB, nullable=False, server_default=text("'{\"hu\": \"\"}'::jsonb"))
description_i18n: Mapped[Optional[dict]] = mapped_column(JSONB, nullable=True)

# TÖRLENDŐ oszlopok (DROP)
# name: Mapped[str] = mapped_column(String, nullable=False)
# description: Mapped[Optional[str]] = mapped_column(String)
```

---

## 4. Admin Kontroll (Global/Country/Region/User)

Nem releváns — ezek dictionary táblák, a tartalmat seed szkriptek vagy admin CRUD kezeli. A jövőben az admin felületen JSON-szerkesztő mezővel lehet majd szerkeszteni a `name_i18n` tartalmát.

---

## 5. Migrációs Terv (Execution Sequence)

### 5.1 Fázisok

```
FÁZIS 1: Add új oszlopok (sync_engine)
FÁZIS 2: Adatmigráció (migrate_i18n_jsonb.py script)
FÁZIS 3: Modell és kód frissítése
FÁZIS 4: Régi oszlopok eltávolítása (sync_engine)
FÁZIS 5: Seed szkriptek frissítése
FÁZIS 6: Tesztelés
```

### 5.2 Részletes Lépések

#### FÁZIS 1: Séma Bővítés
1. Módosítani a 3 modellt: hozzáadni az új `name_i18n` és `description_i18n` JSONB oszlopokat (a régiek megtartása mellett).
2. Futtatni: `docker exec sf_api python3 -m app.scripts.sync_engine`
3. Ellenőrizni: `SELECT column_name FROM information_schema.columns WHERE table_name IN ('expertise_tags', 'dict_body_types', 'service_catalog') AND column_name LIKE '%i18n%'`

#### FÁZIS 2: Adatmigráció
1. Létrehozni: `backend/app/scripts/migrate_i18n_jsonb.py`
2. A script logikája:
   - **ExpertiseTag:** `name_i18n = {"hu": name_hu, "en": name_en} ++ name_translations`
   - **BodyTypeDictionary:** `name_i18n = {"hu": name_hu}`
   - **ServiceCatalog:** `name_i18n = {"hu": name}`, `description_i18n = {"hu": description}`
3. Futtatni: `docker exec sf_api python3 /app/backend/app/scripts/migrate_i18n_jsonb.py`
4. Ellenőrizni: `SELECT id, name_i18n FROM marketplace.expertise_tags LIMIT 5`

#### FÁZIS 3: Kód Frissítés
1. Módosítani a 3 SQLAlchemy modellt:
   - Eltávolítani a régi `name_hu`, `name_en` oszlopokat a modellből
   - Hozzáadni az új `name_i18n` mezőt
2. Módosítani a Pydantic schemákat
3. Módosítani az API végpontokat
4. Módosítani a seed szkripteket

#### FÁZIS 4: Régi Oszlopok Eltávolítása
1. A modell frissítése után a `sync_engine` automatikusan eltávolítja a régi oszlopokat (ha a `sync_engine` támogatja a DROP COLUMN-t)
2. VAGY manuális SQL: `ALTER TABLE marketplace.expertise_tags DROP COLUMN name_hu, DROP COLUMN name_en;`

> **FIGYELEM:** A DROP COLUMN művelet VISSZAFORDÍTHATATLAN! A script lefuttatása ELŐTT adatbázis mentés KÖTELEZŐ!

#### FÁZIS 5: Seed Szkriptek Frissítése
1. `seed_body_types.py`: `name_hu="Szedán"` → `name_i18n={"hu": "Szedán"}`
2. `seed_services.py`: `name="Adat Export"` → `name_i18n={"hu": "Adat Export"}`

#### FÁZIS 6: Tesztelés
1. Ellenőrizni a GET /categories/tree végpontot
2. Ellenőrizni a GET /catalog/body-types végpontot
3. Ellenőrizni a GET/POST /admin/services végpontokat
4. Ellenőrizni az autocomplete keresést

---

## 6. Adatmigrációs Script Terve

A `backend/app/scripts/migrate_i18n_jsonb.py` script az alábbi logikát követi:

```python
"""
i18n JSONB Migration Script (Phase 1)
Migrates old name_hu/name_en columns to name_i18n JSONB format.
Run INSIDE the sf_api container:
    docker exec sf_api python3 /app/backend/app/scripts/migrate_i18n_jsonb.py

IMPORTANT: Run this AFTER the new JSONB columns have been added by sync_engine.
"""

import asyncio
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent.parent.parent))

from sqlalchemy import text
from app.db.session import AsyncSessionLocal

TABLES = [
    {
        "schema": "marketplace",
        "table": "expertise_tags",
        "name_cols": ["name_hu", "name_en"],
        "name_translations_col": "name_translations",
        "desc_cols": ["description"],
        "target_name_col": "name_i18n",
        "target_desc_col": "description_i18n",
    },
    {
        "schema": "vehicle",
        "table": "dict_body_types",
        "name_cols": ["name_hu"],
        "name_translations_col": None,
        "desc_cols": [],
        "target_name_col": "name_i18n",
        "target_desc_col": None,
    },
    {
        "schema": "system",
        "table": "service_catalog",
        "name_cols": ["name"],
        "name_translations_col": None,
        "desc_cols": ["description"],
        "target_name_col": "name_i18n",
        "target_desc_col": "description_i18n",
    },
]


async def migrate_table(config: dict):
    schema = config["schema"]
    table = config["table"]
    target_name = config["target_name_col"]
    target_desc = config["target_desc_col"]
    name_cols = config["name_cols"]
    desc_cols = config["desc_cols"]
    trans_col = config["name_translations_col"]

    print(f"\nMigrating: {schema}.{table}")

    async with AsyncSessionLocal() as db:
        select_cols = ["id"] + name_cols + desc_cols
        if trans_col:
            select_cols.append(trans_col)

        stmt = text(
            f"SELECT {', '.join(select_cols)} FROM {schema}.{table} "
            f"WHERE {target_name} IS NULL OR {target_name} = '{{\"hu\": \"\"}}'::jsonb"
        )
        result = await db.execute(stmt)
        rows = result.fetchall()

        if not rows:
            print(f"   No rows need migration in {schema}.{table}")
            return

        updated = 0
        for row in rows:
            row_dict = row._mapping

            # Build name_i18n
            name_i18n = {}
            if len(name_cols) >= 1 and row_dict.get(name_cols[0]):
                name_i18n["hu"] = row_dict[name_cols[0]]
            if len(name_cols) >= 2 and row_dict.get(name_cols[1]):
                name_i18n["en"] = row_dict[name_cols[1]]

            # Merge with existing name_translations
            if trans_col and row_dict.get(trans_col):
                if isinstance(row_dict[trans_col], dict):
                    name_i18n.update(row_dict[trans_col])

            # Build description_i18n
            desc_i18n = None
            if desc_cols and row_dict.get(desc_cols[0]):
                desc_i18n = {"hu": row_dict[desc_cols[0]]}

            # Update
            update_cols = [f"{target_name} = :name_val"]
            params = {"name_val": name_i18n, "row_id": row_dict["id"]}

            if target_desc and desc_i18n:
                update_cols.append(f"{target_desc} = :desc_val")
                params["desc_val"] = desc_i18n

            update_sql = f"UPDATE {schema}.{table} SET {', '.join(update_cols)} WHERE id = :row_id"
            await db.execute(text(update_sql), params)
            updated += 1

        await db.commit()
        print(f"   Migrated {updated} rows in {schema}.{table}")


async def main():
    print("=" * 70)
    print("  i18n JSONB Migration Script (Phase 1)")
    print("=" * 70)

    for table_config in TABLES:
        await migrate_table(table_config)

    print("\n" + "=" * 70)
    print("  Migration complete!")
    print("=" * 70)


if __name__ == "__main__":
    asyncio.run(main())
```

---

## 7. Kockázatok és Megjegyzések

### 7.1 Kockázatok
1. **Adatvesztés:** A DROP COLUMN visszafordíthatatlan. Minden fázis előtt adatbázis mentés kell!
2. **API kompatibilitás:** A frontend `name_hu` és `name_en` mezőket használ. A migration során ezeket IDEIGLENESEN meg kell tartani backward compatibility miatt, majd a frontendet is át kell állítani.
3. **Teljesítmény:** A JSONB keresés (`ILIKE` helyett `jsonb_extract_path_text`) eltérő lehet. Az autocomplete endpointot át kell írni.

### 7.2 Backward Compatibility Terv
- **Phase 1 (jelenlegi):** Add `name_i18n`, migrate data, keep old columns temporarily
- **Phase 2:** Update frontend to use `name_i18n`
- **Phase 3:** Drop old columns

### 7.3 JSONB Keresési Példák

```sql
-- Magyar név alapján keresés (ILIKE helyett)
SELECT * FROM marketplace.expertise_tags 
WHERE name_i18n->>'hu' ILIKE '%szerelő%';

-- Angol név alapján keresés
SELECT * FROM marketplace.expertise_tags 
WHERE name_i18n->>'en' ILIKE '%mechanic%';

-- Bármely nyelvben keresés (drága, használj GIN indexet)
SELECT * FROM marketplace.expertise_tags 
WHERE name_i18n::text ILIKE '%mechanic%';
```

### 7.4 GIN Index Teljesítmény
A GIN index a `jsonb_path_ops` operátor osztállyal gyorsítja a `@>`, `?`, `?|`, `?&` operátorokat.

```sql
-- GIN-hatékony keresés: pontosan "mechanic" bármely kulcson
SELECT * FROM marketplace.expertise_tags 
WHERE name_i18n @> '{"en": "mechanic"}'::jsonb;
```

---

## 8. Összefoglaló és Jóváhagyási Kérelem

A terv 3 tábla, 5 fájl (3 model + 2 schema) módosítását, 1 új adatmigrációs script létrehozását, valamint 5 API végpont és 2 seed szkript frissítését tartalmazza.

**A jóváhagyás után:**
1. Code módba váltás
2. Modell fájlok módosítása (add new columns)
3. `sync_engine` futtatás
4. Adatmigrációs script futtatás
5. Kód frissítés (schemák, végpontok, seed szkriptek)
6. Tesztelés

**Architect:** Jóváhagyásra vár. Kérem a visszajelzést a tervvel kapcsolatban!