kincses/service-finder

Fork 0

Files

Kincses d574d3297d feat: v1.7 overhaul - identity hash, triple wallet, financial ledger, and security audit system

2026-02-16 00:42:49 +00:00

10 KiB

Raw Blame History

🗄️ 06_DATABASE_GUIDE & DATA INTEGRITY (v1.4)

Ez a dokumentum az adatbázis-architektúra alapelveit és az adatintegritási szabályokat tartalmazza.

1. Soft Delete & Újraregisztráció Logika

A rendszerben nincs fizikai törlés. A data.users tábla speciális indexeléssel kezeli a törölt és visszatérő felhasználókat.

Indexelés: Az email mezőn egy Partial Unique Index (idx_user_email_active_only) található.
Működés: - Ha is_deleted = FALSE, az email foglalt, nem használható újra.
- Ha a felhasználó törli magát (is_deleted = TRUE), az email felszabadul.
Identitás megőrzése: Új regisztrációkor a rendszer új user_id-t generál, de ha a KYC (személyazonosító) adatok egyeznek, az új technikai User a régi person_id-hoz kapcsolódik.

2. Person (Identitás) - KYC & Safety

A data.persons tábla a valós, banki szintű személyazonosságot tárolja.

2.1. JSONB struktúrák

Rugalmas adatszerkezet az okmányok és orvosi adatok kezelésére:

identity_docs:
- id_card: szám és lejárati dátum.
- driver_license: szám, lejárat és kategóriák (pl. ["A", "B", "C"]).
- special_permits: hajó- vagy repülőgép-vezetői engedélyek.
medical_emergency: Vércsoport, allergiák, krónikus betegségek.

2.2. Jutalom Trigger

A profil 100%-os kitöltése (név, születési adatok, okmányok) után automatikusan aktiválódik a system_settings-ben meghatározott PRÉMIUM időszak (alapértelmezett: 14 nap).

3. Technikai Integritás és Séma

3.1. Adatbázis sémák

public: Csak technikai metaadatok (pl. alembic_version).
data: Az üzleti logika összes táblája (55+ tábla).

3.2. Fejlesztői megjegyzések

Enum Case Sensitivity: A Postgres userrole típusa kisbetűérzékeny. A Python kódból érkező értékeket (pl. user, admin) kényszerítve kisbetűvel kell rögzíteni.
Séma Frissítés: A metadata.create_all nem frissíti a meglévő táblákat. Új oszlopok esetén manuális ALTER TABLE vagy Alembic migráció szükséges.
Audit: Minden státuszmódosítás és adatváltozás snapshot-olva kerül az audit_logs táblába.

4. Economy, Regionalizáció és Valuta

A rendszer EU-s piacra optimalizált multi-currency logikát használ.

data.regional_settings: Országkódok (ISO 3166-1), alapértelmezett nyelvek és pénznemek.
data.exchange_rates: Napi frissítésű váltószámok (Bázis: EUR).
Valuta Logika: Minden költséget elmentünk helyi pénznemben (currency_code) és a rögzítéskori váltószámmal átszámított EUR-ban is.
Képlet: Cost_{EUR} = Cost_{Local} \cdot ExchangeRate

4.1. Wallet & Economy

Wallets: Minden regisztrációkor létrejön egy rekord a data.wallets táblában (0 Coin, 0 XP).
Referral Snapshot: Jutalék kifizetésekor a rendszer rögzíti a tranzakció pillanatában érvényes %-ot (commission_percentage), védve az adatot a későbbi módosításoktól.

5. Flotta és Tulajdonjog Szabályok

A flották (Organization) és járművek tulajdonjogi logikája:

Átruházhatóság (Transferability):
- INDIVIDUAL flotta: Nem átruházható, a felhasználóhoz kötött.
- FLEET_OWNER / SERVICE flotta: Átruházható, új tulajdonoshoz (owner_id) rendelhető.
Cég Megszűnése: Soft delete (is_active: False). A járművek életútja (history) megmarad a visszakövethetőség miatt.
Opcionális Járművek: Egy flotta létezhet jármű rögzítése nélkül is (pl. tisztán menedzseri kör).

6. Szervezeti Egységek és CRM

A flottákhoz tartozó humán és üzleti kapcsolatok kezelése.

data.organizations: Bővítve: tax_number, reg_number, headquarters_address, notification_settings (JSONB).
data.organization_contacts: Mini-CRM funkciók (kapcsolattartók típusai: billing, primary, operational).
Kapcsolódás: external_crm_id mező biztosítja az API kapcsolatot külső ERP rendszerekkel.

7. Gazdasági Izoláció és Rating

Gamification Korlát: Csak INDIVIDUAL típusú flottákhoz tartozó Person-ok gyűjthetnek XP-t. A cégek (Company) nem kapnak XP_Ledger-t és Coin_Wallet-et.
Validáció: Cég nem validálhat szervizpontot, csak a hozzárendelt, azonosított Person (technikus).
Rating Rendszer: Külön értékelést kap a Person (megbízhatóság), a Service (minőség) és a Vehicle (műszaki állapot). A cég hírneve ezekből adódik össze.

8. Dinamikus Paraméterezés (`data.system_settings`)

Minden üzleti változó az Admin UI-ról állítható:

auth.reward_days: Regisztrációs prémium hossza (default: 14).
auth.reward_tier: Kapott csomag típusa (default: PREMIUM).
referral.l1: Első szintű jutalék mértéke (default: 10%).

9. Kulcs Táblacsoportok

Fleet: vehicles, user_vehicles, vehicle_events, engine_specs.
Marketplace: service_providers, service_specialties, organization_locations.
Economy: wallets, transactions, shop_items.
Identity: users, persons, companies.

10. Migrációs Állapot (Dev Info)

Eszköz: Alembic
Current Head: 10b73fee8967
Hiányzó láncszem: A persons tábla véglegesítése és a meglévő users tábla adatintegrációs migrációja folyamatban.

4.2 Dokumentum és Irattár (Vault Logic)

Központi tárolás: A data.documents tábla kezeli az összes csatolmányt (parent_type: 'org', 'asset', 'person').
Metadata: Tároljuk a dokumentum kibocsátóját (issuer_id) és tárgyát (subject_id) a szervizstatisztikákhoz.
Verifikáció: status mező (pending, verified, rejected).

4.3 Crowdsourced Szervezetek

Lifecycle: draft_user -> draft_bot -> community_verified -> official.
Gamification: XP/Kredit jóváírás csak sikeres Bot vagy Owner validáció után.

6. Service & Organization Extensions (V2)

6.1 `data.system_configs` (Dinamikus Beállítások)

Kódba égetett értékek helyett adatbázisból vezérelt működés.

key (VARCHAR): Pl. referral_bonus_L1, exchange_rate_EUR, payout_threshold.
value (JSONB): Pl. {"amount": 10, "unit": "percent"}, {"rate": 400.0}.
is_active (BOOLEAN).

6.2 `data.service_reviews` (Okos Értékelés)

user_id, organization_id.
rating (1-5).
proof_url (Számla/Munkalap fotó URL).
is_active (BOOLEAN): Csak az aktív számít bele az átlagba (lásd Gamification logika).

6.3 `data.wallet_transactions`

original_currency: (HUF, EUR, USD).
exchange_rate: Az adott pillanatban érvényes váltószám.

7. Referrals & Invitations

data.referrals: Hierarchikus fa szerkezet (inviter_id, invitee_id, level).
data.invitations:
- code: Random string (pl. X7K9P2).
- type: 'private' (72h) vagy 'company' (168h).
- target_role: A meghívott jogosultsága (Driver, Manager).

8. Virtual Goods & Inventory (Digitális Javak)

8.1 `data.user_inventory`

Ez a tábla tárolja a felhasználó által megszerzett vagy vásárolt kozmetikai elemeket (NEM jogosultságok, hanem vagyontárgyak).

id (UUID): Egyedi azonosító.
user_id (FK): A tulajdonos.
item_id (VARCHAR): A katalógusban lévő azonosító (pl. avatar_frame_neon).
metadata (JSONB): Opcionális egyedi tulajdonságok (pl. sorszámozott NFT-szerű elemknél: {"serial": 42}).
acquired_at (TIMESTAMP): Mikor szerezte.
is_equipped (BOOLEAN): Éppen használja-e (pl. ez az aktív avatar kerete).

8.2 Shop Catalog Configuration (`system_configs`)

A key = 'shop_catalog' alatt tároljuk a bolt kínálatát JSON formátumban.

Példa JSON struktúra:

{
  "categories": ["avatars", "badges", "profile_themes"],
  "items": {
    "badge_early_adopter": {
      "name": "Korai Felfedező",
      "price": 0,
      "currency": "free",
      "condition": "reg_date < '2025-01-01'",
      "image_url": "/assets/badges/early.png"
    },
    "frame_gold_mechanic": {
      "name": "Arany Szerelő Keret",
      "price": 5000,
      "currency": "credit",
      "rarity": "legendary",
      "effect": "shine_animation",
      "image_url": "/assets/frames/gold.png"
    }
  }
}

## 5. Geo-Location and Address Master Data
A rendszer normalizált címkezelést alkalmaz az adatminőség biztosítása érdekében.

### 5.1 Geo Adattáblák
- `data.geo_postal_codes`: ZIP és Település kapcsolata (Unique: country + zip + city).
- `data.geo_streets`: Utcanevek listája, ZIP azonosítóhoz kötve.
- `data.geo_street_types`: Közterület típusok szótára (út, utca, tér...).

### 5.2 GIS Adatok
Minden telephely koordinátája `GEOGRAPHY(POINT, 4326)` típusként van tárolva, amely lehetővé teszi a PostGIS alapú távolságmérést.

### 5. Hibrid Címkezelési Modell
A rendszer az adatintegritás és a sebesség érdekében hibrid modellt használ.

- **Centralizált adattárolás**: A `data.addresses` tábla tárolja a normalizált címeket (UUID alapú).
- **Öntanuló szótárak**: A `data.geo_postal_codes` és `data.geo_streets` táblák automatikusan bővülnek minden új rögzítésnél.
- **Denormalizált GPS adatok**: Az `organization_locations` tábla közvetlenül tárolja a koordinátákat a JOIN-nélküli PostGIS lekérdezésekhez.

| Tábla | Funkció |
| :--- | :--- |
| `data.addresses` | Konkrét házszám szintű címek (Hibrid hivatkozási pont). |
| `data.geo_postal_codes` | Irányítószám és város kapcsolata (HU/EU támogatás). |
| `data.user_stats` | Felhasználói XP, szintek és strike-ok tárolása. |

## 2.4 Financial & Enrichment Tables
- **data.organization_financials:** Éves gazdasági adatok (árbevétel, profit, létszám) tárolása historikus elemzéshez.
- **data.service_profiles.specialization_tags:** JSONB mező a szigorú szakmai szűréshez (pl. márkák, specifikus javítási típusok).
- **data.service_profiles.google_place_id:** Külső validációs kulcs a Google Places API-hoz.


### Identity & Economy Module (v1.6+)
* **`data.persons`**: Természetes személyek, Identity Hash, Örök XP/Büntetés.
* **`data.users`**: Login fiókok, Előfizetési idő, Sales kapcsolatok.
* **`data.wallets`**: 3-as osztású egyenleg (`earned`, `purchased`, `coins`).
* **`data.financial_ledger`**: Pénzügyi tranzakciók főkönyve.
* **`data.security_audit_logs`**: Biztonsági események és 4-szem jóváhagyások.
* **`data.org_sales_assignments`**: Cég-Üzletkötő kapcsolat (Farming jog).

10 KiB Raw Blame History