service-finder/docs/p0_service_provider_gamification_audit_report.md

🔍 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:

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.