admin_szolgáltatók_

2026-07-01 02:27:38 +00:00
parent 189cbfd7ca
commit 6e627d0ebe
491 changed files with 20965 additions and 9703 deletions
--- a/docs/p0_service_provider_gamification_audit_report.md
+++ b/docs/p0_service_provider_gamification_audit_report.md
@@ -0,0 +1,336 @@
+# 🔍 P0 RECONNAISSANCE — Service Provider & Gamification State Audit Report
+
+**Date:** 2026-06-30  
+**Auditor:** Rendszer-Architect (DeepSeek Reasoner)  
+**Mode:** READ-ONLY — NO FILES MODIFIED  
+**Status:** COMPLETE
+
+---
+
+## Executive Summary
+
+This report documents the deep-dive reconnaissance audit of the Service Provider ecosystem, Ratings/Validations, and Gamification modules. The audit covered 3 database schemas (`marketplace`, `identity`, `gamification`), 6 model files, 4 service files, 5 API endpoint files, and 12 router registrations.
+
+**CRITICAL GAP FOUND:** No `admin_providers.py` router exists — the admin provider approval workflow is completely missing from the API layer. Admin UI for `/providers` pages cannot be built without this foundational layer.
+
+---
+
+## 1. Database Model Map
+
+### 1.1 Marketplace Schema (`marketplace`)
+
+| Table | File | Purpose |
+|-------|------|---------|
+| `service_profiles` | `backend/app/models/marketplace/service.py:21` | Rich service profile linked to orgs or providers |
+| `expertise_tags` | `backend/app/models/marketplace/service.py:97` | 4-level category hierarchy (L0-L3) |
+| `service_expertises` | `backend/app/models/marketplace/service.py:147` | Junction table: ServiceProfile ↔ ExpertiseTag |
+| `service_staging` | `backend/app/models/marketplace/service.py:159` | Robot-collected service data (pre-moderation) |
+| `service_staging` | `backend/app/models/marketplace/staged_data.py:1` | Extended staging model (extend_existing=True) |
+| `discovery_parameters` | `backend/app/models/marketplace/service.py:191` | Robot discovery parameters |
+| `cost` | `backend/app/models/marketplace/service.py:205` | Service cost structure |
+
+### 1.2 Identity Schema (`identity` — Social)
+
+| Table | File | Purpose |
+|-------|------|---------|
+| `service_providers` | `backend/app/models/identity/social.py:133` | Crowdsourced provider submissions (P0 refactor) |
+| `votes` | `backend/app/models/identity/social.py:186` | Community validation (+1/-1 per user/provider) |
+| `competitions` | `backend/app/models/identity/social.py:209` | Social competitions |
+| `user_scores` | `backend/app/models/identity/social.py:243` | User competition scores |
+| `service_reviews` | `backend/app/models/identity/social.py:266` | Verified reviews tied to financial transactions |
+
+### 1.3 Gamification Schema (`gamification`)
+
+| Table | File | Purpose |
+|-------|------|---------|
+| `point_rules` | `backend/app/models/gamification/gamification.py:31` | Dynamic point rules (action_key → points) |
+| `points_ledger` | `backend/app/models/gamification/gamification.py:89` | Point transaction log |
+| `user_stats` | `backend/app/models/gamification/gamification.py:103` | User gamification stats |
+| `user_contributions` | `backend/app/models/gamification/gamification.py:137` | Contribution tracking + moderation |
+| `level_configs` | `backend/app/models/gamification/gamification.py:179` | Level definitions (positive + penalty) |
+| `seasonal_competitions` | `backend/app/models/gamification/gamification.py:213` | Seasonal events |
+| `badges` | `backend/app/models/gamification/gamification.py:252` | Achievement badges |
+| `user_badges` | `backend/app/models/gamification/gamification.py:275` | User-badge assignments |
+| `seasons` | `backend/app/models/gamification/gamification.py:296` | Competition seasons |
+
+---
+
+## 2. Trust & Validation Score Architecture
+
+### 2.1 Score Fields on Models
+
+| Field | Model | Default | Purpose |
+|-------|-------|---------|---------|
+| `validation_score` | `ServiceProvider` | `0` | Community validation aggregate (+1/-1 from Votes) |
+| `trust_score` | `ServiceProfile` | `30` | Trust engine score (Gondos Gazda Index) |
+| `is_verified` | `ServiceProfile` | `False` | Admin/manual verification flag |
+| `rating_*_avg` | `ServiceProfile` | `NULL` | Aggregated verified review ratings (4 dimensions) |
+| `rating_overall` | `ServiceProfile` | `NULL` | Overall rating from verified reviews |
+
+### 2.2 CRITICAL: `provider_validations` Table NEVER Created
+
+The Masterbook 2.0 spec mentioned a `provider_validations` table for XP farming prevention, **but it was never created in the codebase**. No model file, no Alembic migration, no sync_engine artifact exists for this table.
+
+**Impact:** XP farming prevention for provider submissions relies solely on:
+- `UserContribution` status (pending/approved/rejected) — exists
+- `UserStats.providers_added_count` — exists  
+- `Vote` table duplicate prevention (UniqueConstraint on user_id + provider_id) — exists
+
+The dedicated anti-farming table was spec-only and never implemented.
+
+### 2.3 Review Validation Rules
+
+`ServiceReview` (from `backend/app/models/identity/social.py:266`):
+- Mandatory FK to `audit.financial_ledger.transaction_id` (UniqueConstraint)
+- 4 rating dimensions: `price_rating`, `quality_rating`, `time_rating`, `communication_rating` (1-10 scale)
+- Only users with verified financial transaction can review
+- `ServiceProfile.rating_*_avg` fields aggregate these values
+
+---
+
+## 3. Gamification Engine Analysis
+
+### 3.1 Dynamic Point Rules
+
+The gamification engine uses **dynamic rules** from `gamification.point_rules` table (not hardcoded):
+
+| Action Key | Points | Description |
+|------------|--------|-------------|
+| `ADD_NEW_PROVIDER` | 500 | Adding a new service provider |
+| `USE_UNVERIFIED_PROVIDER` | 200 | Using an unverified provider |
+| `RATE_PROVIDER` | 250 | Rating a provider |
+| `UPDATE_PROVIDER` | 100 | Updating provider info |
+
+Seeded by `backend/app/scripts/seed_gamification_rules.py`.
+
+### 3.2 GamificationService Flow
+
+From `backend/app/services/gamification_service.py`:
+1. `process_activity(user_id, action_key, ...)` — Main entry point
+2. Reads `PointRule` from DB by action_key
+3. Applies level multiplier via `_calculate_multiplier()`
+4. Penalty system: 4 levels (L0=100%, L1=50%, L2=10%, L3=0%)
+5. Calls `_handle_level_up()` for cross-level logic
+6. Social points → credits conversion at configurable rate
+7. Config loaded from `GAMIFICATION_MASTER_CONFIG` system parameter
+
+### 3.3 Provider Service Gamification Integration
+
+From `backend/app/services/provider_service.py`:
+- `_award_provider_points()` — Reads PointRule from DB, awards through GamificationService
+- Called on: `quick_add_provider()` and `update_provider()`
+- `UserContribution` records created with status "pending" for admin review
+
+---
+
+## 4. API Endpoint Inventory
+
+### 4.1 User-Facing Provider Endpoints (`/providers` prefix)
+
+From `backend/app/api/v1/endpoints/providers.py`:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/providers/categories/tree` | Full hierarchical category tree (4-level) |
+| GET | `/providers/categories/autocomplete` | Text search for L2-L3 tags |
+| GET | `/providers/categories` | Flat list of expertise categories |
+| GET | `/providers/search` | Unified provider search (3 sources) |
+| POST | `/providers/quick-add` | Quick provider submission (crowdsourced) |
+| PUT | `/providers/{provider_id}` | Update provider details (hybrid save) |
+
+### 4.2 Admin Gamification Endpoints (`/admin/gamification` prefix)
+
+From `backend/app/api/v1/endpoints/admin_gamification.py`:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET/POST | `/admin/gamification/point-rules` | List/Create point rules |
+| GET/PUT/DELETE | `/admin/gamification/point-rules/{id}` | CRUD single rule |
+| GET/POST | `/admin/gamification/levels` | List/Create level configs |
+| PUT | `/admin/gamification/levels/{id}` | Update level config |
+| GET/POST | `/admin/gamification/badges` | List/Create badges |
+| GET/PUT | `/admin/gamification/user-stats` | List/Update user stats |
+| GET | `/admin/gamification/user-stats/{id}` | Get user stat detail |
+| POST | `/admin/gamification/user-stats/{id}/penalty` | Apply penalty |
+| POST | `/admin/gamification/user-stats/{id}/reward` | Apply reward |
+| GET | `/admin/gamification/contributions` | List contributions |
+| PUT | `/admin/gamification/contributions/{id}/review` | Approve/reject contribution |
+| GET/POST | `/admin/gamification/seasons` | List/Create seasons |
+| PUT/DELETE | `/admin/gamification/seasons/{id}` | Update/Delete season |
+| GET/POST | `/admin/gamification/competitions` | List/Create competitions |
+| PUT/DELETE | `/admin/gamification/competitions/{id}` | Update/Delete competition |
+| GET | `/admin/gamification/leaderboard` | Admin leaderboard |
+| GET | `/admin/gamification/dashboard` | Dashboard summary |
+| GET/PUT | `/admin/gamification/master-config` | Master config CRUD |
+
+### 4.3 User-Facing Gamification Endpoints (`/gamification` prefix)
+
+From `backend/app/api/v1/endpoints/gamification.py`:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/gamification/my-stats` | Current user stats |
+| GET | `/gamification/leaderboard` | Public leaderboard |
+| GET | `/gamification/seasons` | List seasons |
+| GET | `/gamification/my-contributions` | User contributions |
+| POST | `/gamification/submit-service` | Submit service (gamified) |
+| GET | `/gamification/quiz/daily` | Daily quiz |
+| POST | `/gamification/quiz/answer` | Answer quiz |
+| GET/POST | `/gamification/badges` | Badge listing/awarding |
+| GET | `/gamification/achievements` | Achievement list |
+
+### 4.4 Existing Admin Routers
+
+| Router File | Prefix | Module |
+|-------------|--------|--------|
+| `admin.py` | `/admin` | General admin (health, params, pending actions) |
+| `admin_gamification.py` | `/admin/gamification` | Gamification admin CRUD |
+| `admin_organizations.py` | `/admin/organizations` | Organization CRM |
+| `admin_users.py` | `/admin/users` | User management |
+| `admin_persons.py` | `/admin/persons` | Person management |
+| `admin_packages.py` | `/admin/packages` | Package management |
+| `admin_services.py` | `/admin/services` | Service catalog |
+| `admin_permissions.py` | `(root)` | Permission/RBAC management |
+
+---
+
+## 5. GAP ANALYSIS — Missing Admin Provider API
+
+### 5.1 CRITICAL GAP: No `admin_providers.py` Router
+
+**There is NO `/admin/providers` router.** The file `admin_providers.py` does not exist in the endpoints directory. The following router files DO exist:
+- `admin_gamification.py`, `admin_organizations.py`, `admin_users.py`, `admin_persons.py`, `admin_packages.py`, `admin_services.py`, `admin_permissions.py`
+- `admin.py` (general admin)
+
+**Impact:** Admin users cannot manage providers through the API. The Nuxt Admin Frontend cannot build `/providers` pages without this backend layer.
+
+### 5.2 Complete List of Missing Endpoints
+
+| # | Method | Path | Purpose |
+|---|--------|------|---------|
+| 1 | GET | `/admin/providers` | List all providers from 3 sources (orgs, staging, crowd) |
+| 2 | GET | `/admin/providers/pending` | List pending providers awaiting approval |
+| 3 | GET | `/admin/providers/{id}` | Get detailed provider info (merged from all sources) |
+| 4 | PUT | `/admin/providers/{id}/approve` | Approve provider → set status, award submitter XP |
+| 5 | PUT | `/admin/providers/{id}/reject` | Reject provider with reason → flag UserContribution |
+| 6 | GET | `/admin/providers/staging` | List robot-collected staging entries |
+| 7 | PUT | `/admin/providers/staging/{id}/promote` | Promote staging → ServiceProfile (verify & create org) |
+| 8 | PUT | `/admin/providers/staging/{id}/reject` | Reject staging entry with reason |
+| 9 | GET | `/admin/providers/{id}/votes` | List community validation votes for a provider |
+| 10 | GET | `/admin/providers/{id}/reviews` | List service reviews for a provider |
+| 11 | PUT | `/admin/providers/{provider_id}/verify` | Toggle verified status on ServiceProfile |
+| 12 | PUT | `/admin/providers/{provider_id}/trust-score` | Manually adjust trust_score |
+| 13 | GET | `/admin/providers/validations` | List pending community validations (Votes table) |
+| 14 | PUT | `/admin/providers/staging/{id}` | Update staging entry (edit robot-collected data) |
+
+### 5.3 Dependencies for Building These Endpoints
+
+| Dependency | Current Status | Notes |
+|------------|---------------|-------|
+| `ServiceProvider` model (`social.py:133`) | Complete | Includes validation_score, status, source |
+| `ServiceProfile` model (`service.py:21`) | Complete | Includes trust_score, is_verified, verification_log |
+| `ServiceStaging` model (`service.py:159`) | Complete | Includes status, validation_level, audit_trail |
+| `Vote` model (`social.py:186`) | Complete | Includes weight, user_id, provider_id |
+| `ServiceReview` model (`social.py:266`) | Complete | Verified reviews with financial transaction linkage |
+| `GamificationService` (`gamification_service.py`) | Complete | Can award XP when admin approves |
+| `UserContribution` model (`gamification.py:137`) | Complete | Status field for pending/approved/rejected |
+| Permission `providers:manage` | Unknown | Needs to exist in RBAC or be created |
+| Schemas for admin provider endpoints | MISSING | Need `ProviderAdminOut`, `ProviderAdminList`, etc. |
+
+### 5.4 Provider Data Flow (Current State)
+
+```
+-------------------+     +-------------------+     +-------------------+
+|  Robot (Staging)  |     |  Crowdsourced     |     |  Verified Org      |
+|  service_staging  |     |  service_providers |     |  fleet.orgs        |
+|  status: pending  |     |  status: pending   |     |  is_verified: T    |
+--------+----------+     +--------+----------+     +--------+----------+
+         |                        |                        |
+         v                        v                        v
+---------------------------------------------------------------+
+|               User-Facing API (providers.py)                   |
+|  GET /providers/search  --  UNION of all 3 sources            |
+|  POST /providers/quick-add  --  Creates ServiceProvider       |
+|  PUT /providers/{id}  --  Update with migration logic         |
+---------------------------------------------------------------+
+         |                        |                        |
+         |              ** NO ADMIN LAYER EXISTS **              |
+         v                        v                        v
+---------------------------------------------------------------+
+|              MISSING: Admin Provider Workflow                  |
+|  - No approval/rejection for pending providers                |
+|  - No staging promotion to verified org                       |
+|  - No trust_score manual adjustment                           |
+|  - No community validation vote review                        |
+|  - No service review moderation                               |
+---------------------------------------------------------------+
+```
+
+---
+
+## 6. Gitea Task Breakdown (Required for Implementation)
+
+Based on the 3A granularity principle, the implementation of the admin provider layer requires these Gitea tasks:
+
+### Epic: Admin Provider Management
+
+| # | Task | Priority | Dependencies |
+|---|------|----------|-------------|
+| 1 | Create schemas for admin provider endpoints | P0 | None |
+| 2 | Implement `admin_providers.py` - List/Get providers | P0 | Schema |
+| 3 | Implement approve/reject provider logic | P0 | GamificationService |
+| 4 | Implement staging management (list/promote/reject) | P0 | None |
+| 5 | Implement community validation vote review | P1 | #4 |
+| 6 | Implement service review moderation | P1 | #5 |
+| 7 | Register router in `api.py` at `/admin/providers` | P0 | #2 |
+| 8 | Implement manual trust_score adjustment endpoint | P1 | #6 |
+| 9 | Create RBAC permission `providers:manage` | P0 | None |
+| 10 | E2E tests for admin provider workflow | P1 | #2-#9 |
+
+---
+
+## 7. Gamification Gaps & Observations
+
+### 7.1 No Admin-Triggered Gamification Rewards
+
+When an admin approves a provider submission, there is **no endpoint** to trigger `GamificationService.process_activity()` for the submitter. The `UserContribution` record exists but there's no automated XP award upon approval.
+
+**Fix:** The `PUT /admin/providers/{id}/approve` endpoint must call:
+```python
+await gamification_service.process_activity(
+    db=db,
+    user_id=submitter_user_id,
+    action_key="ADD_NEW_PROVIDER",
+    source_type="provider_approval",
+    source_id=provider_id
+)
+```
+
+### 7.2 No Rejected Contribution Feedback Loop
+
+When a provider is rejected, the `UserContribution.status` should be set to `rejected` with a rejection reason, but there's no endpoint to trigger this for admin workflows.
+
+### 7.3 Gamification Config is Dynamic but Has No Validation
+
+The `GAMIFICATION_MASTER_CONFIG` system parameter can be edited freely via the admin gamification API, but there's **no schema validation** on the JSONB structure. A malformed config could break the gamification engine.
+
+---
+
+## 8. Summary of Findings
+
+| Category | Status | Details |
+|----------|--------|---------|
+| Database Models | COMPLETE | All 15+ models across 3 schemas |
+| User-Facing Provider API | COMPLETE | 6 endpoints in providers.py |
+| User-Facing Gamification API | COMPLETE | 15+ endpoints in gamification.py |
+| Admin Gamification API | COMPLETE | 25+ endpoints in admin_gamification.py |
+| Gamification Service | COMPLETE | Full engine with dynamic rules, penalties |
+| Provider Service | COMPLETE | P0 hybrid vendor refactor applied |
+| **Admin Provider API** | **MISSING** | **No admin_providers.py - 14 endpoints missing** |
+| **provider_validations table** | **NEVER CREATED** | Spec-only, not in codebase |
+| **Trust Engine** | **STUB** | trust_score exists but no active scoring logic |
+| **Admin Rejection Gamification** | **MISSING** | No endpoint to award/reject XP on moderation |
+
+---
+
+*End of P0 Reconnaissance Report. This is a READ-ONLY analysis - no files were modified.*