# 🔍 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.*