chore: Backend codebase cleanup and archiving of legacy scripts

2026-03-22 20:07:37 +00:00
parent 5d96b00f81
commit 309a72cc0b
19 changed files with 530 additions and 184 deletions
--- a/docs/audits/admin_gap_analysis.md
+++ b/docs/audits/admin_gap_analysis.md
@@ -0,0 +1,135 @@
+# Admin System Gap Analysis Report
+*Generated: 2026-03-21 12:14:33*
+
+## 📊 Executive Summary
+
+- **Total hardcoded business values found:** 149
+- **API modules analyzed:** 22
+- **Modules missing admin endpoints:** 20
+
+## 🔍 Hardcoded Business Values
+
+These values should be moved to `system_parameters` table for dynamic configuration.
+
+| File | Line | Variable | Value | Context |
+|------|------|----------|-------|---------|
+| `seed_discovery.py` | 8 | `url` | `"https://opendata.rdw.nl/resource/m9d7-ebf2.json?$s..."` | `url = "https://opendata.rdw.nl/resource/m9d7-ebf2.json?$select=distinct%20merk&$limit=50000"` |
+| `create_sandbox_user.py` | 28 | `API_BASE` | `"http://localhost:8000..."` | `API_BASE = "http://localhost:8000"` |
+| `create_sandbox_user.py` | 29 | `MAILPIT_API` | `"http://sf_mailpit:8025/api/v1/messages..."` | `MAILPIT_API = "http://sf_mailpit:8025/api/v1/messages"` |
+| `create_sandbox_user.py` | 30 | `MAILPIT_DELETE_ALL` | `"http://sf_mailpit:8025/api/v1/messages..."` | `MAILPIT_DELETE_ALL = "http://sf_mailpit:8025/api/v1/messages"` |
+| `create_sandbox_user.py` | 35 | `SANDBOX_PASSWORD` | `"Sandbox123!..."` | `SANDBOX_PASSWORD = "Sandbox123!"` |
+| `create_sandbox_user.py` | 138 | `max_attempts` | `5` | `max_attempts = 5` |
+| `create_sandbox_user.py` | 139 | `wait_seconds` | `3` | `wait_seconds = 3` |
+| `app/test_billing_engine.py` | 32 | `base_amount` | `100.0` | `base_amount = 100.0` |
+| `app/test_billing_engine.py` | 133 | `file_path` | `"backend/app/services/billing_engine.py..."` | `file_path = "backend/app/services/billing_engine.py"` |
+| `app/api/v1/endpoints/providers.py` | 11 | `user_id` | `2` | `user_id = 2` |
+| `app/api/v1/endpoints/services.py` | 68 | `new_level` | `80` | `new_level = 80` |
+| `app/api/v1/endpoints/social.py` | 15 | `user_id` | `2` | `user_id = 2` |
+| `app/models/core_logic.py` | 17 | `__tablename__` | `"subscription_tiers..."` | `__tablename__ = "subscription_tiers"` |
+| `app/models/core_logic.py` | 29 | `__tablename__` | `"org_subscriptions..."` | `__tablename__ = "org_subscriptions"` |
+| `app/models/core_logic.py` | 48 | `__tablename__` | `"credit_logs..."` | `__tablename__ = "credit_logs"` |
+| `app/models/core_logic.py` | 64 | `__tablename__` | `"service_specialties..."` | `__tablename__ = "service_specialties"` |
+| `app/models/reference_data.py` | 7 | `__tablename__` | `"reference_lookup..."` | `__tablename__ = "reference_lookup"` |
+| `app/models/identity/identity.py` | 25 | `region_admin` | `"region_admin..."` | `region_admin = "region_admin"` |
+| `app/models/identity/identity.py` | 26 | `country_admin` | `"country_admin..."` | `country_admin = "country_admin"` |
+| `app/models/identity/identity.py` | 28 | `sales_agent` | `"sales_agent..."` | `sales_agent = "sales_agent"` |
+| `app/models/identity/identity.py` | 30 | `service_owner` | `"service_owner..."` | `service_owner = "service_owner"` |
+| `app/models/identity/identity.py` | 31 | `fleet_manager` | `"fleet_manager..."` | `fleet_manager = "fleet_manager"` |
+| `app/models/identity/identity.py` | 204 | `__tablename__` | `"verification_tokens..."` | `__tablename__ = "verification_tokens"` |
+| `app/models/identity/identity.py` | 217 | `__tablename__` | `"social_accounts..."` | `__tablename__ = "social_accounts"` |
+| `app/models/identity/identity.py` | 235 | `__tablename__` | `"active_vouchers..."` | `__tablename__ = "active_vouchers"` |
+| `app/models/identity/identity.py` | 249 | `__tablename__` | `"user_trust_profiles..."` | `__tablename__ = "user_trust_profiles"` |
+| `app/models/identity/address.py` | 14 | `__tablename__` | `"geo_postal_codes..."` | `__tablename__ = "geo_postal_codes"` |
+| `app/models/identity/address.py` | 24 | `__tablename__` | `"geo_streets..."` | `__tablename__ = "geo_streets"` |
+| `app/models/identity/address.py` | 33 | `__tablename__` | `"geo_street_types..."` | `__tablename__ = "geo_street_types"` |
+| `app/models/identity/social.py` | 24 | `__tablename__` | `"service_providers..."` | `__tablename__ = "service_providers"` |
+| `app/models/identity/social.py` | 61 | `__tablename__` | `"competitions..."` | `__tablename__ = "competitions"` |
+| `app/models/identity/social.py` | 73 | `__tablename__` | `"user_scores..."` | `__tablename__ = "user_scores"` |
+| `app/models/identity/social.py` | 91 | `__tablename__` | `"service_reviews..."` | `__tablename__ = "service_reviews"` |
+| `app/models/identity/security.py` | 24 | `__tablename__` | `"pending_actions..."` | `__tablename__ = "pending_actions"` |
+| `app/models/vehicle/vehicle.py` | 24 | `__tablename__` | `"cost_categories..."` | `__tablename__ = "cost_categories"` |
+| `app/models/vehicle/vehicle.py` | 114 | `__tablename__` | `"vehicle_odometer_states..."` | `__tablename__ = "vehicle_odometer_states"` |
+| `app/models/vehicle/vehicle.py` | 145 | `__tablename__` | `"vehicle_user_ratings..."` | `__tablename__ = "vehicle_user_ratings"` |
+| `app/models/vehicle/vehicle.py` | 196 | `__tablename__` | `"gb_catalog_discovery..."` | `__tablename__ = "gb_catalog_discovery"` |
+| `app/models/vehicle/vehicle_definitions.py` | 19 | `__tablename__` | `"vehicle_types..."` | `__tablename__ = "vehicle_types"` |
+| `app/models/vehicle/vehicle_definitions.py` | 35 | `__tablename__` | `"feature_definitions..."` | `__tablename__ = "feature_definitions"` |
+| `app/models/vehicle/vehicle_definitions.py` | 53 | `__tablename__` | `"vehicle_model_definitions..."` | `__tablename__ = "vehicle_model_definitions"` |
+| `app/models/vehicle/vehicle_definitions.py` | 147 | `__tablename__` | `"model_feature_maps..."` | `__tablename__ = "model_feature_maps"` |
+| `app/models/vehicle/external_reference.py` | 7 | `__tablename__` | `"external_reference_library..."` | `__tablename__ = "external_reference_library"` |
+| `app/models/vehicle/external_reference_queue.py` | 7 | `__tablename__` | `"auto_data_crawler_queue..."` | `__tablename__ = "auto_data_crawler_queue"` |
+| `app/models/vehicle/asset.py` | 14 | `__tablename__` | `"vehicle_catalog..."` | `__tablename__ = "vehicle_catalog"` |
+| `app/models/vehicle/asset.py` | 91 | `__tablename__` | `"asset_financials..."` | `__tablename__ = "asset_financials"` |
+| `app/models/vehicle/asset.py` | 107 | `__tablename__` | `"asset_costs..."` | `__tablename__ = "asset_costs"` |
+| `app/models/vehicle/asset.py` | 125 | `__tablename__` | `"vehicle_logbook..."` | `__tablename__ = "vehicle_logbook"` |
+| `app/models/vehicle/asset.py` | 154 | `__tablename__` | `"asset_inspections..."` | `__tablename__ = "asset_inspections"` |
+| `app/models/vehicle/asset.py` | 169 | `__tablename__` | `"asset_reviews..."` | `__tablename__ = "asset_reviews"` |
+
+*... and 99 more findings*
+
+## 🏗️ Admin Endpoints Analysis
+
+### Modules with Admin Prefix
+
+*No modules have `/admin` prefix*
+
+### Modules with Admin Routes (but no prefix)
+
+*No mixed admin routes found*
+
+## ⚠️ Critical Gaps: Missing Admin Endpoints
+
+These core business modules lack dedicated admin endpoints:
+
+- **users** - No `/admin` prefix and no admin routes
+- **vehicles** - No `/admin` prefix and no admin routes
+- **services** - No `/admin` prefix and no admin routes
+- **assets** - No `/admin` prefix and no admin routes
+- **organizations** - No `/admin` prefix and no admin routes
+- **billing** - No `/admin` prefix and no admin routes
+- **gamification** - No `/admin` prefix and no admin routes
+- **analytics** - No `/admin` prefix and no admin routes
+- **security** - No `/admin` prefix and no admin routes
+- **documents** - No `/admin` prefix and no admin routes
+- **evidence** - No `/admin` prefix and no admin routes
+- **expenses** - No `/admin` prefix and no admin routes
+- **finance_admin** - No `/admin` prefix and no admin routes
+- **notifications** - No `/admin` prefix and no admin routes
+- **reports** - No `/admin` prefix and no admin routes
+- **catalog** - No `/admin` prefix and no admin routes
+- **providers** - No `/admin` prefix and no admin routes
+- **search** - No `/admin` prefix and no admin routes
+- **social** - No `/admin` prefix and no admin routes
+- **system_parameters** - No `/admin` prefix and no admin routes
+
+### Recommended Actions:
+1. Create `/admin` prefixed routers for each missing module
+2. Implement CRUD endpoints for administrative operations
+3. Add audit logging and permission checks
+
+## 🚀 Recommendations
+
+### Phase 1: Hardcode Elimination
+1. Create `system_parameters` migration if not exists
+2. Move identified hardcoded values to database
+3. Implement `ConfigService` for dynamic value retrieval
+
+### Phase 2: Admin Endpoint Expansion
+1. Prioritize modules with highest business impact:
+   - `users` (user management)
+   - `billing` (financial oversight)
+   - `security` (access control)
+2. Follow consistent pattern: `/admin/{module}/...`
+3. Implement RBAC with `admin` and `superadmin` roles
+
+### Phase 3: Monitoring & Audit
+1. Add admin action logging to `SecurityAuditLog`
+2. Implement admin dashboard with real-time metrics
+3. Create automated health checks for admin endpoints
+
+## 🔧 Technical Details
+
+### Scan Parameters
+- Project root: `/app`
+- Files scanned: Python files in `/app`
+- Business patterns: 25
+- Trivial values excluded: None, False, 0, '', "", True, 1, [], {}
--- a/docs/audits/audit_report_robots.md
+++ b/docs/audits/audit_report_robots.md
@@ -0,0 +1,60 @@
+# 🤖 Robot Integrity Audit Report
+Generated: 2026-03-19T19:40:29.528087
+Total robots discovered: 40
+
+## Service Robots
+**Count:** 6
+- Import successful: 6/6
+- Syntax clean: 6/6
+- Interface OK: 2/6
+
+**Problematic robots:**
+- `app.workers.service.service_robot_1_scout_osm`: Interface issues
+- `app.workers.service.service_robot_2_researcher`: Interface issues
+- `app.workers.service.service_robot_3_enricher`: Interface issues
+- `app.workers.service.service_robot_5_auditor`: Interface issues
+
+## Vehicle General
+**Count:** 28
+- Import successful: 28/28
+- Syntax clean: 28/28
+- Interface OK: 13/28
+
+**Problematic robots:**
+- `app.workers.vehicle.R0_brand_hunter`: Interface issues
+- `app.workers.vehicle.R1_model_scout`: Interface issues
+- `app.workers.vehicle.R2_generation_scout`: Interface issues
+- `app.workers.vehicle.R3_engine_scout`: Interface issues
+- `app.workers.vehicle.bike.bike_R0_brand_hunter`: Interface issues
+- `app.workers.vehicle.bike.bike_R1_model_scout`: Interface issues
+- `app.workers.vehicle.bike.bike_R2_generation_scout`: Interface issues
+- `app.workers.vehicle.bike.bike_R3_engine_scout`: Interface issues
+- `app.workers.vehicle.bike.bike_R4_final_extractor`: Interface issues
+- `app.workers.vehicle.ultimatespecs.vehicle_ultimate_r0_spider`: Interface issues
+- `app.workers.vehicle.ultimatespecs.vehicle_ultimate_r1_scraper`: Interface issues
+- `app.workers.vehicle.ultimatespecs.vehicle_ultimate_r2_enricher`: Interface issues
+- `app.workers.vehicle.ultimatespecs.vehicle_ultimate_r3_finalizer`: Interface issues
+- `app.workers.vehicle.vehicle_robot_2_auto_data_net`: Interface issues
+- `app.workers.vehicle.vehicle_robot_2_researcher`: Interface issues
+
+## System & OCR
+**Count:** 3
+- Import successful: 3/3
+- Syntax clean: 3/3
+- Interface OK: 3/3
+
+## Uncategorized
+**Count:** 3
+- Import successful: 3/3
+- Syntax clean: 3/3
+- Interface OK: 1/3
+
+**Problematic robots:**
+- `app.workers.vehicle.r5_test`: Interface issues
+- `app.workers.vehicle.vehicle_data_loader`: Interface issues
+
+## 📊 Summary
+- **Total robots:** 40
+- **Import successful:** 40/40
+- **Syntax clean:** 40/40
+- **Interface OK:** 19/40
--- a/docs/audits/audit_report_vehicle_robots.md
+++ b/docs/audits/audit_report_vehicle_robots.md
@@ -0,0 +1,105 @@
+# Vehicle Robot Ecosystem - Teljes technikai audit jelentés
+
+**Audit dátum:** 2026-03-12  
+**Gitea kártya:** #69  
+**Auditáló:** Főmérnök / Rendszerauditőr  
+
+## 1. Áttekintés
+A `backend/app/workers/vehicle/` könyvtárban 15 fájl található, melyek egy 5 szintű (0–4) robot‑csővezetéket alkotnak. A pipeline célja a járművek technikai adatainak automatikus felfedezése, gyűjtése, kutatása, AI‑alapú dúsítása és végül a valós eszközök (Asset) VIN‑alapú hitelesítése. A robotok önállóan, aszinkron üzemmódban futnak, és az adatbázis rekordjainak státuszmezőin keresztül kommunikálnak (status‑driven pipeline).
+
+## 2. Fájllista
+| Fájl | Szint | Rövid leírás |
+|------|------|--------------|
+| `vehicle_robot_0_discovery_engine.py` | 0 | Őrkutya (watchdog), differenciális RDW szinkron, havonta teljes adatbázis letöltés |
+| `vehicle_robot_0_gb_discovery.py` | 0 | Brit (GB) CSV feldolgozás, `gb_catalog_discovery` tábla feltöltése |
+| `vehicle_robot_0_strategist.py` | 0 | Piaci priorítás számítása (RDW darabszám alapján) |
+| `vehicle_robot_1_catalog_hunter.py` | 1 | RDW API‑ból technikai adatok kinyerése, `vehicle_model_definitions` táblába írás |
+| `vehicle_robot_1_gb_hunter.py` | 1 | DVLA API (GB) lekérdezés, `vehicle_model_definitions` táblába írás |
+| `vehicle_robot_1_2_nhtsa_fetcher.py` | 1.2 | NHTSA API (USA) – csak EU márkákra szűrve |
+| `vehicle_robot_1_4_bike_hunter.py` | 1.4 | NHTSA API – motorok |
+| `vehicle_robot_1_5_heavy_eu.py` | 1.5 | RDW API – nehézgépjárművek (teher, busz, lakóautó) |
+| `vehicle_robot_2_researcher.py` | 2 | DuckDuckGo keresés, strukturált kontextus előállítása AI számára |
+| `vehicle_robot_3_alchemist_pro.py` | 3 | AI‑alapú adategyesítés (RDW + AI), validáció, `gold_enriched` státusz |
+| `vehicle_robot_4_vin_auditor.py` | 4 | Asset VIN hitelesítés AI segítségével |
+| `mapping_rules.py` | – | Forrásmezők leképezése (jelenleg **nincs használatban**) |
+| `mapping_dictionary.py` | – | Szinonimák normalizálása (jelenleg **nincs használatban**) |
+| `vehicle_data_loader.py` | – | Külső JSON források betöltése `vehicle.reference_lookup` táblába |
+| `robot_report.py` | – | Diagnosztikai dashboard, statisztikák megjelenítése |
+
+## 3. Állapotgép (State Machine) térkép
+A következő táblázat a robotok által keresett és beállított státuszokat összegzi. A sorrend a pipeline természetes folyását tükrözi.
+
+### 3.1. `vehicle.catalog_discovery` tábla
+| Robot (fájl) | Keresett státusz (`WHERE`) | Beállított státusz (`SET` / `INSERT`) | Megjegyzés |
+|--------------|----------------------------|---------------------------------------|------------|
+| `0_discovery_engine` | `processing` | `pending` | Őrkutya: beragadt feladatok visszaállítása |
+| `0_discovery_engine` | – | `pending` (új rekord) | Differenciális szinkron: csak ha nincs `gold_enriched` a `vehicle_model_definitions`‑ben |
+| `0_strategist` | `NOT IN ('processed', 'in_progress')` | `pending` (prioritás frissítés) | Csak még nem feldolgozott rekordok |
+| `1_catalog_hunter` | `pending` | `processing` → `processed` | Atomizált zárolás (`SKIP LOCKED`) |
+| `1_gb_hunter` | `pending` (gb_catalog_discovery) | `processing` → `processed` / `invalid_vrm` | DVLA API kvótakezeléssel |
+| `1_2_nhtsa_fetcher` | – | `pending` (új rekord) | Csak EU márkákhoz, `USA_IMPORT` piac |
+| `1_4_bike_hunter` | – | `pending` (új rekord) | Motorok, `USA_IMPORT` piac |
+| `1_5_heavy_eu` | – | `pending` (új rekord) | Nehézgépjárművek, `EU` piac |
+
+### 3.2. `vehicle.vehicle_model_definitions` tábla
+| Robot (fájl) | Keresett státusz (`WHERE`) | Beállított státusz (`SET` / `INSERT`) | Megjegyzés |
+|--------------|----------------------------|---------------------------------------|------------|
+| `0_discovery_engine` | `research_in_progress`, `ai_synthesis_in_progress` (2 órás timeout) | `unverified`, `awaiting_ai_synthesis` | Őrkutya: beragadt AI feladatok visszaállítása |
+| `1_catalog_hunter` | – | `ACTIVE` (új rekord) | `ON CONFLICT DO NOTHING` (make, normalized_name, variant_code, version_code, fuel_type) |
+| `1_gb_hunter` | – | `ACTIVE` (új rekord) | `ON CONFLICT DO NOTHING` |
+| `2_researcher` | `unverified`, `awaiting_research`, `ACTIVE` | `research_in_progress` → `awaiting_ai_synthesis` (siker) / `unverified` (újra) / `suspended_research` (max próbálkozás) | Atomizált zárolás, kvótakezelés (DVLA) |
+| `3_alchemist_pro` | `awaiting_ai_synthesis`, `ACTIVE` | `ai_synthesis_in_progress` → `gold_enriched` (siker) / `manual_review_needed` (max próbálkozás) / `unverified` (vissza) | AI hívás, hibrid merge (RDW + AI), validáció |
+| `0_discovery_engine` (diff sync) | `gold_enriched` | – | **Védelem:** a `gold_enriched` rekordok kihagyása a felfedezésből |
+
+### 3.3. `vehicle.gb_catalog_discovery` tábla
+| Robot (fájl) | Keresett státusz (`WHERE`) | Beállított státusz (`SET` / `INSERT`) |
+|--------------|----------------------------|---------------------------------------|
+| `0_gb_discovery` | – | `pending` (új rekord) – csak ha nincs `gold_enriched` a `vehicle_model_definitions`‑ben |
+| `1_gb_hunter` | `pending` | `processing` → `processed` / `invalid_vrm` |
+
+### 3.4. `vehicle.assets` tábla
+| Robot (fájl) | Keresett állapot (`WHERE`) | Beállított státusz (`SET`) |
+|--------------|----------------------------|----------------------------|
+| `4_vin_auditor` | `is_verified = false AND vin IS NOT NULL` | `audit_in_progress` → `active` (siker) / `audit_failed` (hiba) |
+
+## 4. Logikai összefüggések
+### 4.1. Orchestráció
+Nincs központi orchestrator. A robotok **párhuzamosan futnak**, és az adatbázis rekordjainak státuszait **közös munka‑memóriaként** használják. A folyamat láncolata:
+```
+catalog_discovery (pending) 
+    → robot 1.x hunter (processed) 
+        → vehicle_model_definitions (ACTIVE) 
+            → robot 2 researcher (awaiting_ai_synthesis) 
+                → robot 3 alchemist (gold_enriched)
+```
+A `gold_enriched` státuszú rekordok **védettek**: a `0_discovery_engine` és `0_gb_discovery` nem veszi őket fel újra.
+                
+### 4.2. Mapping réteg
+A `mapping_rules.py` és `mapping_dictionary.py` fájlok **nincsenek integrálva** a robotokba. A `vehicle_data_loader.py` saját, forrásspecifikus leképezést alkalmaz, de a mapping fájlokat nem importálja. Ez a réteg jelenleg kihasználatlan.
+
+### 4.3. Atomizált zárolás és kvótakezelés
+A hunterek és kutatók `FOR UPDATE SKIP LOCKED` zárolást használnak, így elkerülhető a race condition. A külső API‑k (DVLA, DuckDuckGo) kvótakezeléssel rendelkeznek (`QuotaManager` osztály).
+
+## 5. Biztonsági és integritási ellenőrzés
+### 5.1. `is_manual` védelem hiánya
+A **teljes kódbázisban egyetlen fájlban sem** található `is_manual` mezőre vagy „manual” kulcsszóra épülő védelem. A robotok csak a `gold_enriched` státusz alapján kerülik a felülírást. **Kockázat:** manuálisan bevitt adatok (pl. admin által javított technikai specifikációk) felülírhatók, ha a rekord státusza nem `gold_enriched`.
+
+### 5.2. Egyéb védelmi mechanizmusok
+- `ON CONFLICT DO NOTHING` / `ON CONFLICT DO UPDATE` csak bizonyos egyedi kulcsokon (pl. make, normalized_name, …).
+- `0_discovery_engine` differenciális szinkronja kihagyja a `gold_enriched` rekordokat.
+- `0_strategist` nem módosít `processed` vagy `in_progress` státuszú rekordokat.
+
+## 6. Következtetések
+1. **A robot‑ökoszisztéma jól strukturált**, atomizált zárolással, kvótakezeléssel és hibatűréssel.
+2. **A mapping réteg hiányzik** – a `mapping_rules.py` és `mapping_dictionary.py` fájlok nincsenek használatban.
+3. **Kritikus biztonsági rés:** nincs `is_manual` védelem. A #27, #28, #29 kártyákhoz kapcsolódó beavatkozásoknál ezt figyelembe kell venni.
+4. **Állapotgép áttekinthető**, a státuszok logikusan lépnek egymás után. A `gold_enriched` státusz jelenti a végső védelmet.
+
+## 7. Javaslatok a #27, #28, #29 kártyákhoz
+- **#27 (Mapping integráció):** Kapcsoljuk be a `mapping_rules.py`‑t a `vehicle_data_loader`‑ben, majd terjeszszük ki a hunterekre.
+- **#28 (Manual védelem):** Vezessünk be egy `is_manual` (boolean) mezőt a `vehicle_model_definitions` táblában, és a robotok minden írása előtt ellenőrizzük (`WHERE is_manual = false`).
+- **#29 (Pipeline monitorozás):** A `robot_report.py` kiegészítése valós‑idejű státusz‑átmenetek grafikonjával és riasztásokkal.
+
+---
+
+*Jelentés készült a `backend/app/workers/vehicle/` könyvtár 15 fájljának teljes kódauditja alapján. Minden állítás kódrészletekre támaszkodik.*