service-finder/docs/v201/02_Database_vs_API_Status.md

02 - Database vs API Status (Master Book 2.0.1)

Version: 2.0.1
Generated: 2026-03-26
Auditor: Projekt Manager Gemini
Status: Mapping of 127+ tables to 30+ API endpoints

---

📊 Database Schema to API Endpoint Mapping

Legend

• ✅ Working: Endpoint fully functional, returns correct data
• 🔄 Partial: Endpoint exists but has issues (404, 500, incomplete logic)
• ❌ Missing: No API endpoint for this table/functionality
• ⏳ Planned: In development roadmap

---

🗄️ Identity Schema (7 Tables)

Table	API Endpoint	Method	Status	Notes
identity.persons	/api/v1/users/me	GET	✅	Returns current user's person data
identity.persons	/api/v1/users/{id}	GET	✅	User profile lookup
identity.users	/api/v1/auth/login	POST	✅	JWT token issuance
identity.users	/api/v1/auth/register	POST	✅	User registration
identity.users	/api/v1/auth/refresh	POST	✅	Token refresh
identity.user_trust_profiles	/api/v1/security/trust	GET	✅	Trust score retrieval
identity.social_accounts	/api/v1/social/accounts	GET	✅	Linked social accounts
identity.organization_members	/api/v1/organizations/members	GET	✅	Organization membership
identity.pending_actions	/api/v1/security/pending	GET/POST	✅	Dual-control approvals

API Coverage: 100% (All identity tables have working endpoints)

---

💰 Finance Schema (6 Tables)

Table	API Endpoint	Method	Status	Notes
finance.wallets	/api/v1/finance/wallets	GET	✅	Triple wallet balances
finance.wallets	/api/v1/finance/wallets/transfer	POST	✅	Inter-wallet transfers
finance.financial_ledger	/api/v1/finance/ledger	GET	✅	Transaction history
finance.financial_ledger	/api/v1/finance/transactions	POST	✅	New transaction creation
finance.currency_rates	/api/v1/finance/rates	GET	✅	Exchange rate lookup
finance.payment_methods	/api/v1/billing/methods	GET	✅	Payment methods

API Coverage: 100% (All finance tables have working endpoints)

---

🚗 Vehicle Schema (25 Tables)

Table	API Endpoint	Method	Status	Notes
vehicle.assets	/api/v1/assets/vehicles	GET/POST	🔄	Critical: Frontend calls /api/v1/vehicles/register (404)
vehicle.assets	/api/v1/assets/{id}	GET/PUT/DELETE	✅	Individual asset management
vehicle.vehicle_model_definitions	/api/v1/catalog/models	GET	❌	404 Error - Needs implementation
vehicle.vehicle_model_definitions	/api/v1/vehicles/search/brands	GET	❌	404 Error - Catalog endpoint missing
vehicle.vehicle_expenses	/api/v1/expenses	GET/POST	🔄	500 Error - Schema mismatch issues
vehicle.vehicle_costs	/api/v1/expenses/costs	GET	🔄	Relationship mapping incomplete
vehicle.vehicle_user_ratings	/api/v1/vehicles/{id}/ratings	POST	✅	Vehicle rating system
vehicle.vehicle_odometer_state	/api/v1/vehicles/{id}/odometer	GET/POST	✅	Mileage tracking
vehicle.vehicle_history	/api/v1/vehicles/{id}/history	GET	✅	Maintenance history
vehicle.motorcycle_specs	/api/v1/catalog/motorcycles	GET	❌	Missing endpoint
vehicle.external_references	/api/v1/catalog/external	GET	❌	Missing endpoint
vehicle.external_reference_queue	/api/v1/robots/queue	GET	✅	Robot queue management

API Coverage: 48% (12/25 tables have functional endpoints)

Critical Gaps:

1. Catalog endpoints (/api/v1/catalog/*) return 404
2. Vehicle creation endpoint mismatch (frontend vs backend)
3. Expense endpoints throwing 500 errors

---

🏪 Marketplace Schema (12 Tables)

Table	API Endpoint	Method	Status	Notes
marketplace.service_profiles	/api/v1/services	GET/POST	✅	Service listing and creation
marketplace.service_profiles	/api/v1/services/search	GET	✅	Geospatial service search
marketplace.service_providers	/api/v1/providers	GET	✅	Provider directory
marketplace.service_providers	/api/v1/providers/{id}	GET	✅	Provider details
marketplace.service_reviews	/api/v1/services/{id}/reviews	GET/POST	✅	Review system
marketplace.service_bookings	/api/v1/bookings	GET/POST	⏳	Planned - Booking flow incomplete
marketplace.service_specializations	/api/v1/services/specializations	GET	✅	Specialization tags
marketplace.organizations	/api/v1/organizations	GET/POST	✅	Organization management
marketplace.organization_members	/api/v1/organizations/members	GET/POST	✅	Member management

API Coverage: 75% (9/12 tables have functional endpoints)

Gap: Booking flow endpoints not fully implemented

---

🎮 Gamification Schema (11 Tables)

Table	API Endpoint	Method	Status	Notes
gamification.points_ledger	/api/v1/gamification/points	GET	✅	XP point history
gamification.badges	/api/v1/gamification/badges	GET	✅	Available badges
gamification.user_badges	/api/v1/gamification/user/badges	GET	✅	User's earned badges
gamification.leaderboards	/api/v1/gamification/leaderboard	GET	✅	Global rankings
gamification.competitions	/api/v1/gamification/competitions	GET	✅	Active competitions
gamification.daily_quizzes	/api/v1/gamification/quiz	GET/POST	✅	Daily quiz system
gamification.achievement_rules	/api/v1/admin/gamification/rules	GET/PUT	❌	Admin only - Missing

API Coverage: 86% (6/7 core tables, admin endpoints missing)

---

🚚 Fleet Schema (6 Tables)

Table	API Endpoint	Method	Status	Notes
fleet.fleets	/api/v1/fleet	GET/POST	✅	Fleet management
fleet.fleet_vehicles	/api/v1/fleet/{id}/vehicles	GET/POST	✅	Vehicle assignments
fleet.fleet_drivers	/api/v1/fleet/{id}/drivers	GET/POST	✅	Driver management
fleet.fleet_analytics	/api/v1/analytics/fleet	GET	⏳	Planned - TCO calculations needed

API Coverage: 75% (3/4 core tables functional)

---

⚙️ System Schema (15 Tables)

Table	API Endpoint	Method	Status	Notes
system.system_parameters	/api/v1/system/parameters	GET/PUT	✅	Configuration management
system.translations	/api/v1/translations	GET	✅	i18n text retrieval
system.audit_logs	/api/v1/admin/audit	GET	✅	Security audit logs
system.document_templates	/api/v1/documents/templates	GET	✅	Document templates
system.legal_documents	/api/v1/documents/legal	GET	✅	Terms & conditions

API Coverage: 100% for core tables (5/5 exposed)

---

🔍 Audit Schema (5 Tables)

Table	API Endpoint	Method	Status	Notes
audit.process_logs	/api/v1/admin/audit/process	GET	✅	Robot execution logs
audit.security_events	/api/v1/admin/audit/security	GET	✅	Security event monitoring
audit.api_audit_trail	/api/v1/admin/audit/api	GET	✅	API call tracking

API Coverage: 100% (All audit tables exposed)

---

📈 API Coverage Summary

Schema	Total Tables	Working APIs	Partial APIs	Missing APIs	Coverage
Identity	7	7	0	0	100%
Finance	6	6	0	0	100%
Vehicle	25	12	3	10	48%
Marketplace	12	9	0	3	75%
Gamification	11	6	0	5	55%
Fleet	6	3	0	3	50%
System	15	5	0	10	33%
Audit	5	3	0	2	60%
TOTAL	87	51	3	33	62%

Overall API Coverage: 62% of core business tables have functional endpoints

---

🔴 Critical API Issues (Blocking Production)

1. Vehicle Creation Endpoint Mismatch

• Frontend Calls: /api/v1/vehicles/register (404 Not Found)
• Backend Has: /api/v1/assets/vehicles (requires authentication)
• Impact: Users cannot add vehicles to their garage
• Fix Required: Update frontend or create redirect endpoint

2. Catalog Endpoints Missing

• /api/v1/catalog/brands - 404 (vehicle brand listing)
• /api/v1/catalog/models - 404 (model search)
• /api/v1/vehicles/search/brands - 404 (alternative endpoint)
• Impact: Vehicle selection UI shows empty dropdowns
• Fix Required: Implement catalog query endpoints

3. Expense API 500 Errors

• /api/v1/expenses - Returns 500 Internal Server Error
• Root Cause: Schema mismatch between vehicle.costs and vehicle.vehicle_expenses
• Impact: Users cannot log maintenance costs
• Fix Required: Align database relationships and API response models

4. Authentication Endpoint 404 ✅ FIXED

• /api/v1/auth/me - ✅ Now returns user profile (alias for /api/v1/users/me)
• Impact: Frontend can now validate user session on page load
• Fix Applied: Added /auth/me endpoint to auth.py returning UserResponse
• Verification: Real identity test with admin user confirmed both endpoints work

---

🟡 High Priority API Gaps

1. Analytics Service Missing

• Required: /api/v1/analytics/tco - Total Cost of Ownership calculations
• Required: /api/v1/analytics/fleet - Fleet-wide metrics
• Impact: Dashboard tiles show mocked data only

2. Admin Control Panels Incomplete

• Gamification rule management endpoints missing
• System parameter bulk update endpoints
• User moderation endpoints

3. Historical Data Support

• occurrence_date field not consistently implemented
• Missing endpoints for historical cost analysis
• Impact: Cannot track cost trends over time

---

🟢 Medium Priority API Gaps

1. Webhook & Notification Endpoints

• Event subscription management
• Notification preference endpoints

2. Bulk Operations

• Batch vehicle import
• Mass expense entry
• Fleet-wide updates

3. Advanced Search Endpoints

• Complex vehicle search with multiple filters
• Service provider ranking algorithms
• Geographic clustering endpoints

---

🔧 API Health Check Results

Working Endpoints (Verified)

✅ GET    /api/v1/auth/login
✅ POST   /api/v1/auth/register  
✅ GET    /api/v1/users/me
✅ GET    /api/v1/assets/vehicles
✅ GET    /api/v1/services
✅ GET    /api/v1/gamification/leaderboard
✅ GET    /api/v1/finance/wallets

Broken Endpoints (Require Fix)

❌ GET    /api/v1/vehicles/register          # 404 - Wrong endpoint
❌ GET    /api/v1/catalog/brands            # 404 - Missing implementation
❌ POST   /api/v1/expenses                  # 500 - Schema mismatch
✅ GET    /api/v1/auth/me                   # ✅ Fixed - Returns user profile

---

🎯 Immediate API Implementation Priorities

Phase 1 (Critical - Blocking)

1. Fix vehicle creation flow - Align frontend/backend endpoints
2. Implement catalog endpoints - Enable vehicle selection UI
3. Repair expense API - Fix 500 errors for cost logging

Phase 2 (High Priority)

4. Add analytics endpoints - Enable real dashboard data
5. Complete admin endpoints - Gamification and system controls
6. Implement historical data - occurrence_date support

Phase 3 (Medium Priority)

7. Webhook system - Event-driven notifications
8. Bulk operations - Data import/export
9. Advanced search - Complex query capabilities

---

Next: See 03_Frontend_UI_Status.md for frontend component wiring status.