201 előtti mentés

docs/audits/backend_endpoint_audit_gap_analysis.md

@@ -0,0 +1,119 @@
+# 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.*