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.