From a63e6c8facb0349729a98f1c1b818da985c514ab Mon Sep 17 00:00:00 2001 From: Kincses Date: Tue, 10 Feb 2026 21:11:44 +0000 Subject: [PATCH] MasterBook update --- docs/V01_gemini/03_Dev_Environment_Runbook.md | 35 +++++++++++++++++++ docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md | 22 +++++++++++- docs/V01_gemini/15_Changelog.md | 19 +++++++++- .../17_DEVELOPER_NOTES_AND_PITFALLS.md | 20 ++++++++++- .../18_ASSET_AND_FLEET_SPECIFICATION.md | 19 +++++++++- .../19_ADMIN_AND_PERMISSIONS_SPEC.md | 13 ++++++- 6 files changed, 123 insertions(+), 5 deletions(-) diff --git a/docs/V01_gemini/03_Dev_Environment_Runbook.md b/docs/V01_gemini/03_Dev_Environment_Runbook.md index fa66869..b460a4e 100644 --- a/docs/V01_gemini/03_Dev_Environment_Runbook.md +++ b/docs/V01_gemini/03_Dev_Environment_Runbook.md @@ -22,3 +22,38 @@ docker compose up -d OpenAPI 404: A helyes cím /api/v2/openapi.json. +# 03. Development Environment Runbook + +## 3.1. System Initialization (Bootstrap) +Ha az adatbázis üres (vagy törölve lett), az első SuperAdmin felhasználót manuálisan kell létrehozni, mivel a regisztrációs végpontok védettek vagy nem adnak admin jogot. + +### 3.1.1. SuperAdmin Létrehozása (Recommended) +A jelszó hash-elési eltérések elkerülése érdekében használjuk a Python scriptet a konténeren belül: + +```bash +docker exec -it service_finder_api python3 -c " +import bcrypt +import asyncio +from sqlalchemy import text +from app.db.session import SessionLocal + +async def bootstrap_admin(): + # 1. Jelszó generálás + password = 'InitialPassword123'.encode('utf-8') + hashed = bcrypt.hashpw(password, bcrypt.gensalt()).decode('utf-8') + + async with SessionLocal() as db: + # 2. Person és User létrehozása/Frissítése + # (A script feltételezi, hogy a Person rekord már létezik vagy itt hozod létre) + sql = text(\"\"\" + UPDATE data.users + SET hashed_password = :h, role = 'superadmin', is_active = true, preferred_language = 'hu' + WHERE email = 'admin@servicefinder.hu' + \"\"\") + await db.execute(sql, {'h': hashed}) + await db.commit() + print('✅ SuperAdmin Ready') + +if __name__ == '__main__': + asyncio.run(bootstrap_admin()) +" diff --git a/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md b/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md index 8598c30..0dd19a2 100644 --- a/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md +++ b/docs/V01_gemini/05_AUTH_AND_IDENTITY_SPEC.md @@ -106,4 +106,24 @@ A felhasználók több e-mail címet is csatolhatnak egyetlen profilhoz, hogy k 2. `Settings -> Linked Accounts -> Add New`. 3. Rendszer küld egy megerősítő linket az új címre. 4. Ha a linkre kattint, az új cím hozzáadódik a `user_identities` táblához. -5. Ha az új címen már volt regisztráció: A rendszer felajánlja az **Account Merge** (Fiókegyesítés) lehetőségét (biztonsági kérdések után). \ No newline at end of file +5. Ha az új címen már volt regisztráció: A rendszer felajánlja az **Account Merge** (Fiókegyesítés) lehetőségét (biztonsági kérdések után). + +```markdown +# 05. Authentication & Identity Specification + +## 5.2. Data Models (Identity) + +### 5.2.1. User Entity (`data.users`) +A technikai belépési pont. +- **id**: Integer (PK) +- **email**: String (Unique) +- **hashed_password**: String (Bcrypt) +- **role**: Enum (superadmin, admin, user, service, driver) +- **person_id**: FK -> `data.persons.id` (A TWINS kapcsolat) +- **preferred_language**: String (Default: 'hu') [ÚJ v1.2.5] +- **region_code**: String (Default: 'HU') [ÚJ v1.2.5] +- **is_active**: Boolean + +### 5.2.2. TWINS Concept Update +- A `User` (User) és `Person` (Shadow Identity) szétválasztása szigorú. +- Belépéskor a rendszer a `User` táblából olvassa ki a `preferred_language` és `region_code` beállításokat, és ezeket a Token válaszban visszaadja a Frontendnek. \ No newline at end of file diff --git a/docs/V01_gemini/15_Changelog.md b/docs/V01_gemini/15_Changelog.md index e4fd6c9..26b8f73 100644 --- a/docs/V01_gemini/15_Changelog.md +++ b/docs/V01_gemini/15_Changelog.md @@ -286,4 +286,21 @@ A rendszer most már képes egyetlen KYC folyamat alatt aktiválni a felhasznál ### Javítva - **Circular Import Fix:** A modellek importálási rendjének optimalizálása a `app.db.base_class` közvetlen használatával, megszüntetve a hurok-importokat. - **Függőségkezelés:** `deps.py` bővítve a `get_current_active_user` függőséggel a biztonsági zárolások érvényesítéséhez. -- **Soft-Delete Logika:** A felhasználói fiók törlése mostantól felszabadítja az eredeti e-mail címet a TWINS-elvű újra-regisztrációhoz. \ No newline at end of file +- **Soft-Delete Logika:** A felhasználói fiók törlése mostantól felszabadítja az eredeti e-mail címet a TWINS-elvű újra-regisztrációhoz. + +# 15. Changelog & Version History + +## [v1.2.5] - 2026-02-10 (The "SuperAdmin" Update) +### 🚀 New Features +- **Admin Bootstrap:** Implementáltuk a "vészhelyzeti" Admin létrehozási folyamatot (Python script alapú hash generálással). +- **i18n Sync:** Élesítettük a `/api/v1/admin/translations/sync` végpontot, amely JSON fájlokba exportálja az adatbázis fordításait. +- **Identity Expansion:** A `User` modell bővült a `preferred_language` és `region_code` mezőkkel a perszonalizáció érdekében. + +### 🐛 Bug Fixes +- **ORM Crash:** Javítva az `AssetAssignment` és `AssetCost` modellek hiányzó `organization` kapcsolatai, amelyek blokkolták a rendszer indulását (`InvalidRequestError`). +- **Config Error:** Javítva a `Settings` osztályból hiányzó `STATIC_DIR` definíció, ami 500-as hibát okozott a fordítások szinkronizálásakor. +- **Login Crash:** Javítva az `AttributeError` a Login végponton (a hiányzó `region_code` miatt). + +### 🛠 Technical Changes +- **Migrations:** Új Alembic migráció (`add_lang_and_region_to_user`) generálva és lefuttatva. +- **Environment:** A `static/locales` mappa jogosultságai beállítva a Docker konténer számára. \ No newline at end of file diff --git a/docs/V01_gemini/17_DEVELOPER_NOTES_AND_PITFALLS.md b/docs/V01_gemini/17_DEVELOPER_NOTES_AND_PITFALLS.md index 8ff361f..2f2c361 100644 --- a/docs/V01_gemini/17_DEVELOPER_NOTES_AND_PITFALLS.md +++ b/docs/V01_gemini/17_DEVELOPER_NOTES_AND_PITFALLS.md @@ -16,4 +16,22 @@ ### Üres Swagger (OpenAPI) felület * **Ok:** Ha az SQLAlchemy Mapper vagy egy Pydantic séma importja hibás, a FastAPI nem tudja legenerálni a dokumentációt. -* **Javítás:** Ellenőrizd a `docker logs` kimenetét indításkor, keresd a `MapperConfigurationError` vagy `ImportError` sorokat. \ No newline at end of file +* **Javítás:** Ellenőrizd a `docker logs` kimenetét indításkor, keresd a `MapperConfigurationError` vagy `ImportError` sorokat. + +# 17. Developer Notes & Pitfalls + +## 17.1. SQLAlchemy & Circular Imports +**Hiba:** `InvalidRequestError: Mapper has no property 'organization'` +**Ok:** Ha egy modellben definiálsz egy `ForeignKey`-t, de nem adod hozzá a `relationship`-et, a SQLAlchemy mapper inicializáláskor összeomolhat, ha egy másik modell próbál hivatkozni rá (back_populates). +**Megoldás:** Mindig párban definiáld a kapcsolatokat (FK + relationship). +**Példa javítás (AssetAssignment):** +```python +organization_id = Column(Integer, ForeignKey("data.organizations.id")) +organization = relationship("Organization") # Ez hiányzott! + +17.2. Configuration Missing + +Hiba: AttributeError: 'Settings' object has no attribute 'STATIC_DIR' Tanulság: Ha fájlrendszer műveleteket végzel (pl. JSON export), mindig a core/config.py-ban definiáld az abszolút útvonalakat (BASE_DIR, STATIC_DIR), ne hardkódolj útvonalakat a service fájlokban. +17.3. Database Migrations + +Best Practice: Ha mezőt adsz hozzá egy modellhez (pl. User.region_code), azonnal generálj Alembic migrációt (alembic revision --autogenerate), különben az API 500-as hibát dob, mert a Python objektum attribútuma létezik, de az SQL lekérdezés nem adja vissza az oszlopot. \ No newline at end of file diff --git a/docs/V01_gemini/18_ASSET_AND_FLEET_SPECIFICATION.md b/docs/V01_gemini/18_ASSET_AND_FLEET_SPECIFICATION.md index 7850f81..3e39a77 100644 --- a/docs/V01_gemini/18_ASSET_AND_FLEET_SPECIFICATION.md +++ b/docs/V01_gemini/18_ASSET_AND_FLEET_SPECIFICATION.md @@ -201,4 +201,21 @@ A járművek kezelése "Single Responsibility" elv alapján 4 modulra bomlott: A teljesítmény optimalizálása érdekében a \`Full Profile\` helyett 3 dedikált végpontot használunk: - \`GET /api/v1/assets/{id}\`: Csak identitás és katalógus (Gyors nézet). - \`GET /api/v1/assets/{id}/costs\`: Csak pénzügyi történet és grafikonok. -- \`GET /api/v1/assets/{id}/telemetry\`: Csak élő adatok (Dashboard). \ No newline at end of file +- \`GET /api/v1/assets/{id}/telemetry\`: Csak élő adatok (Dashboard). + +*A javított AssetAssignment logika dokumentálása.* + +```markdown +# 18. Asset & Fleet Management Specification + +## 18.2. Asset Assignment Logic +A járművek és eszközök hozzárendelése a rendszer egyik legkritikusabb része. + +### 18.2.1. Assignment Model (`AssetAssignment`) +Kapcsolatot teremt egy Jármű (`Asset`) és egy Szervezet (`Organization`) között. +- **asset_id**: UUID (Melyik jármű?) +- **organization_id**: Integer (Melyik cég használja?) +- **status**: Active / Released +- **Validáció:** Egy jármű egyszerre csak egy szervezetnél lehet `active` státuszban. + +*(Megjegyzés: A v1.2.5 frissítés javította az ORM kapcsolatokat, így a lekérdezések most már közvetlenül elérik az `assignment.organization` objektumot.)* \ No newline at end of file diff --git a/docs/V01_gemini/19_ADMIN_AND_PERMISSIONS_SPEC.md b/docs/V01_gemini/19_ADMIN_AND_PERMISSIONS_SPEC.md index c72a30a..cdc739c 100644 --- a/docs/V01_gemini/19_ADMIN_AND_PERMISSIONS_SPEC.md +++ b/docs/V01_gemini/19_ADMIN_AND_PERMISSIONS_SPEC.md @@ -118,4 +118,15 @@ A `GAMIFICATION_MASTER_CONFIG` struktúrája: - `xp_logic`: Alap XP és kitevő a nehezedő szintezéshez. - `penalty_logic`: Küszöbértékek, szorzók és ledolgozási ráta. - `conversion_logic`: Social-to-Credit váltási arány. -- `level_rewards`: Szintlépési bónuszok mértéke. \ No newline at end of file +- `level_rewards`: Szintlépési bónuszok mértéke. + +## 19.1. SuperAdmin Capabilities +A `rank: 100` szintű felhasználó (SuperAdmin) az egyetlen, aki: +1. **Translation Sync:** Írási joga van a szerver fájlrendszerére a `/api/v1/admin/translations/sync` végponton keresztül. +2. **Sentinel Override:** Felülbírálhatja az automatikus biztonsági zárolásokat. + +## 19.2. Admin API Endpoints +- `POST /admin/translations/sync`: + - **Trigger:** Manuális (Gombnyomás a Dashboardon). + - **Action:** `data.translations` -> `static/locales/*.json`. + - **Permission:** SuperAdmin ONLY. \ No newline at end of file