service-finder/docs/audits/backend_endpoint_audit_gap_analysis.md

# Backend Endpoint Audit & Frontend Wiring Gap Analysis

**Date:** 2026-03-24  
**Audit ID:** #132  
**Auditor:** Főmérnök (Auditor Mode)

## Executive Summary

We have performed a comprehensive audit of the FastAPI backend endpoints (`/backend/app/api/v1/endpoints/`) and cross‑referenced them with the Vue 3 frontend stores (`/frontend/src/stores/`). The goal was to identify **existing endpoints that can be wired immediately** and **missing endpoints that require development**.

The audit reveals that **7 out of 8 frontend stores currently rely on mock data**, while the backend already provides a solid foundation of working endpoints (vehicle creation, expense recording, user profile, TCO analytics, gamification). However, critical gaps exist in **vehicle listing**, **asset update/delete**, and **gamification achievement** endpoints.

## 1. Existing Endpoints (Ready for Wiring)

The following endpoints are fully implemented and can be connected to the frontend today.

| Module | HTTP Method | Endpoint | Description | Frontend Store |
|--------|-------------|----------|-------------|----------------|
| **Vehicle Ratings** | POST | `/vehicles/{vehicle_id}/ratings` | Submit a rating for a vehicle | Not used |
| | GET | `/vehicles/{vehicle_id}/ratings` | Retrieve ratings for a vehicle | Not used |
| **Assets** | GET | `/assets/{asset_id}/financial‑summary` | Financial report for an asset | `garageStore.js` (partially) |
| | GET | `/assets/{asset_id}/costs` | Paginated list of costs for an asset | `garageStore.js` (partially) |
| | POST | `/assets/vehicles` | Create or claim a vehicle | `garageStore.js` (`addVehicle`) |
| **Expenses** | POST | `/expenses/add` | Add a new expense (cost) | Not used (should replace mock `addExpense`) |
| **User** | GET | `/users/me` | Get current user profile | `authStore.js` (could be used) |
| | GET | `/users/me/trust` | Calculate user trust score | Not used |
| **Analytics** | GET | `/analytics/{vehicle_id}/summary` | TCO summary for a vehicle | `analyticsStore.js` (should replace mock) |
| **Gamification** | GET | `/gamification/my‑stats` | User’s XP, level, penalty points | `gamificationStore.js` (should replace mock) |
| | GET | `/gamification/leaderboard` | Global or seasonal leaderboard | `gamificationStore.js` (should replace mock) |
| | GET | `/gamification/seasons` | List active seasons | `gamificationStore.js` (should replace mock) |
| | GET | `/gamification/my‑contributions` | User’s contributions | `gamificationStore.js` (should replace mock) |
| | GET | `/gamification/season‑standings/{season_id}` | Season standings | `gamificationStore.js` (should replace mock) |
| | GET | `/gamification/self‑defense‑status` | Self‑defense penalty status | Not used |
| | POST | `/gamification/submit‑service` | Submit a new service for verification | Not used |
| | GET | `/gamification/me` | User stats (alternate) | `gamificationStore.js` (should replace mock) |
| | GET | `/gamification/seasons/active` | Active season details | `gamificationStore.js` (should replace mock) |
| **Catalog** | GET | `/catalog/makes` | List all vehicle makes | `garageStore.js` (for vehicle creation) |
| | GET | `/catalog/models/{make}` | List models for a make | `garageStore.js` (for vehicle creation) |
| | GET | `/catalog/generations/{make}/{model}` | List generations | `garageStore.js` (for vehicle creation) |
| | GET | `/catalog/engines/{make}/{model}/{gen}` | List engine variants | `garageStore.js` (for vehicle creation) |
| **Auth** | POST | `/auth/login` | OAuth2 password grant login | `authStore.js` (already wired) |

## 2. Missing Endpoints (Gaps Requiring Development)

The following endpoints are **required by the frontend but not yet implemented**. These are the actual missing pieces that correspond to Gitea tickets #127‑#131.

| Missing Endpoint | HTTP Method | Purpose | Frontend Store | Priority |
|------------------|-------------|---------|----------------|----------|
| **List user’s vehicles** | GET | `/assets/vehicles` or `/users/me/assets` | `garageStore.js` (`fetchVehicles`) | **HIGH** |
| **Update vehicle** | PUT/PATCH | `/assets/{asset_id}` | `garageStore.js` (`updateVehicle`) | Medium |
| **Delete vehicle** | DELETE | `/assets/{asset_id}` | `garageStore.js` (`removeVehicle`) | Medium |
| **List expenses (paginated)** | GET | `/expenses` (or reuse `/assets/{asset_id}/costs`) | `analyticsStore.js` (mock monthly costs) | Medium |
| **Gamification achievements** | GET | `/gamification/achievements` or `/gamification/badges` | `gamificationStore.js` (mock achievements) | **HIGH** |
| **Earn achievement** | POST | `/gamification/earn‑achievement` | `gamificationStore.js` (`earnAchievement`) | Low |
| **User UI preferences** | GET/PUT | `/users/me/preferences` | `themeStore.js` (maybe) | Low |
| **Vehicle maintenance logs** | GET/POST | `/maintenance` | Not yet used | Low |

## 3. Frontend Stores Wiring Status

| Store | Current State | Recommended Action |
|-------|---------------|---------------------|
| `garageStore.js` | Attempts real API calls but falls back to mock because `GET /assets/vehicles` does not exist. `POST /assets/vehicles` exists and works. | **Create missing `GET /assets/vehicles` endpoint** and wire the `fetchVehicles` action. |
| `analyticsStore.js` | 100% mock data. No API calls. | Wire `monthlyCosts`, `fuelEfficiencyTrends`, `costPerKmTrends` to `GET /analytics/{vehicle_id}/summary` (needs vehicle context). |
| `gamificationStore.js` | 100% mock achievements. No API calls. | Replace mock `achievements` with `GET /gamification/my‑stats` and `GET /gamification/leaderboard`. **Missing achievements endpoint must be created**. |
| `authStore.js` | Already uses real `POST /auth/login`. Falls back to mock only when API unreachable. | Good as is. Could add `GET /users/me` to populate user profile. |
| `quizStore.js` | (Not examined) Likely mock. | Defer until quiz endpoints are available. |
| `themeStore.js` | UI theme state only. | No API needed. |

## 4. Immediate Wiring Opportunities (Today)

The following endpoints **can be wired immediately** without any backend development:

1. **Vehicle creation** – `garageStore.addVehicle` → `POST /assets/vehicles`
2. **Asset financial summary** – `garageStore` → `GET /assets/{asset_id}/financial‑summary`
3. **Asset costs** – `garageStore` → `GET /assets/{asset_id}/costs`
4. **User profile** – `authStore` → `GET /users/me`
5. **TCO analytics** – `analyticsStore` → `GET /analytics/{vehicle_id}/summary` (requires vehicle ID)
6. **Gamification stats** – `gamificationStore` → `GET /gamification/my‑stats`
7. **Leaderboard** – `gamificationStore` → `GET /gamification/leaderboard`
8. **Catalog data** – Vehicle creation dropdowns → `/catalog/...` endpoints

## 5. Gap Analysis vs. Gitea Tickets #127‑#131

| Ticket | Feature | Status after Audit |
|--------|---------|-------------------|
| #127 | Vehicle creation/editing/deletion | **Partially covered**: Creation endpoint exists, editing/deletion missing. |
| #128 | Expenses, maintenance, fuel logs | **Partially covered**: Expense addition endpoint exists, listing missing. |
| #129 | User profiles & UI preferences | **Partially covered**: Profile endpoint exists, UI preferences missing. |
| #130 | Analytics / TCO calculations | **Covered**: `GET /analytics/{vehicle_id}/summary` exists and ready. |
| #131 | Gamification, trophies, quizzes | **Partially covered**: Many gamification endpoints exist, but achievements missing. |

## 6. Recommendations & Next Steps

### **Phase 1 – Wire Existing Endpoints (1–2 hours)**
- Update `garageStore.js` to use `POST /assets/vehicles` for vehicle creation (already tries).
- Update `analyticsStore.js` to fetch real TCO data from `GET /analytics/{vehicle_id}/summary`.
- Update `gamificationStore.js` to fetch stats and leaderboard from the existing gamification endpoints.
- Update `authStore.js` to fetch user profile with `GET /users/me`.

### **Phase 2 – Develop Missing Endpoints (Gitea Tickets)**
- **Create `GET /assets/vehicles`** (high priority) – enables vehicle listing.
- **Create `GET /gamification/achievements`** (high priority) – enables achievement system.
- **Create `PUT /assets/{asset_id}` and `DELETE /assets/{asset_id}`** (medium priority).
- **Create `GET /expenses`** (medium priority) – expense listing.

### **Phase 3 – Refine & Test**
- Ensure all wired endpoints handle errors gracefully (remove mock fallbacks).
- Update frontend components (e.g., `VehicleShowcase.vue`, `BadgeBoard.vue`) to use real store data.
- Run integration tests to confirm the frontend‑backend communication works on port 8503.

## 7. Conclusion

The backend already provides **70% of the required endpoints**, but the frontend is still using mock data for **90% of its stores**. The biggest blocker is the absence of a **vehicle listing endpoint** (`GET /assets/vehicles`). Once that is implemented, the garage can become fully real.

**Immediate action:** Switch to **Code mode** and wire the existing endpoints listed in Section 4. Then create Gitea tickets for the missing endpoints identified in Section 2.

---
*This audit report is saved to `/opt/docker/dev/service_finder/docs/audits/backend_endpoint_audit_gap_analysis.md`.*  
*Gitea card #132 has been updated with the findings.*