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)
```bash
✅ 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)
```bash
❌ 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](03_Frontend_UI_Status.md) for frontend component wiring status.