╔════════════════════════════════════════════════════════════════════════════════╗ ║ BACKEND API GAPS FOR TRADING EXCHANGE UI (QUICK REFERENCE) ║ ║ goodgo-platform-ai | 2026-04-21 ║ ╚════════════════════════════════════════════════════════════════════════════════╝ ┌─ 🔴 HIGH PRIORITY GAPS ─────────────────────────────────────────────────────┐ │ │ │ 1. RECENT LISTINGS TICKER │ │ ├─ Endpoint needed: GET /listings?sortBy=publishedAt │ │ ├─ Used by: Home dashboard, listings board │ │ ├─ Data: Last 24h/7d ACTIVE listings with publishedAt timestamp │ │ └─ Priority: CRITICAL │ │ │ │ 2. MARKET SNAPSHOT (Live Indicators) │ │ ├─ Endpoint needed: GET /analytics/market-snapshot?city=HCMC │ │ ├─ Used by: Home dashboard tiles │ │ ├─ Returns: activeCount, avgPrice, medianPrice, priceChange%, │ │ │ inventoryM2, daysOnMarket, byType breakdown │ │ └─ Priority: CRITICAL │ │ │ │ 3. TRENDING AREAS (Hot Markets) │ │ ├─ Endpoint needed: GET /analytics/trending-areas?period=7d&limit=10 │ │ ├─ Used by: Home dashboard heatmap │ │ ├─ Sorted by: Inquiry/view volume per district │ │ └─ Priority: CRITICAL │ │ │ │ 4. SIMILAR LISTINGS / COMPARABLES │ │ ├─ Endpoint needed: GET /listings/:id/similar?limit=5 │ │ ├─ Used by: Listing detail page │ │ ├─ Filter: Same district, ±10% price, same property type, last 3m │ │ └─ Priority: CRITICAL │ │ │ │ 5. LISTING DETAIL ENRICHMENT │ │ ├─ Add to listing detail response: │ │ │ - valuationEstimate (from AVM) │ │ │ - inquiryCount (exposed, currently hidden) │ │ │ - agentQualityScore (denormalized from agent profile) │ │ │ - priceChangePercent (vs market avg for area) │ │ └─ Priority: HIGH (depends on gap #1–4) │ │ │ └───────────────────────────────────────────────────────────────────────────────┘ ┌─ 🟡 MEDIUM PRIORITY GAPS ───────────────────────────────────────────────────┐ │ │ │ 6. PRICE MOVERS (Gainers/Losers) │ │ ├─ Endpoint needed: GET /analytics/price-movers?direction=up|down&limit=5│ │ ├─ Used by: Exchange ticker, market alerts │ │ └─ Data: Top 5 price increases/decreases by district this week │ │ │ │ 7. MARKET HISTORY (12-Month Trends) │ │ ├─ Endpoint needed: GET /analytics/market-history?city=HCMC&period=12m │ │ ├─ Used by: Analytics page, trend charts │ │ ├─ Returns: Monthly snapshots of market indicators │ │ └─ Depends on: Market snapshot implementation │ │ │ │ 8. WARD-LEVEL HEATMAP DRILL-DOWN │ │ ├─ Enhance: GET /analytics/heatmap?city=HCMC&level=ward │ │ ├─ Used by: Market analytics page (zoom feature) │ │ └─ Current: District only; need phường-level granularity │ │ │ │ 9. REAL-TIME LISTING UPDATES │ │ ├─ Enhance: GET /listings?newSince=TIMESTAMP&limit=20 │ │ ├─ Used by: Listings board auto-refresh │ │ └─ Optional: WebSocket/SSE for live status badges │ │ │ │ 10. CACHE METADATA IN ANALYTICS │ │ ├─ Add fields to all /analytics/* responses: │ │ │ - cachedAt (ISO timestamp) │ │ │ - nextRefreshAt (when data will refresh) │ │ │ - dataAge (minutes since update) │ │ └─ Used by: FE to show data freshness badges │ │ │ └───────────────────────────────────────────────────────────────────────────────┘ ┌─ ✅ ALREADY AVAILABLE (No Changes Needed) ───────────────────────────────────┐ │ │ │ • Listing search & filter (GET /listings) │ │ • Listing detail + media (GET /listings/:id) │ │ • Price history (GET /listings/:id/price-history) │ │ • Market report by district (GET /analytics/market-report) │ │ • Price trends (GET /analytics/price-trend) │ │ • Heatmap (GET /analytics/heatmap) │ │ • AVM/Valuation (GET|POST /analytics/valuation) │ │ • Agent public profile (GET /agents/:agentId/profile) │ │ • Reviews & ratings (GET /reviews/*, POST /reviews) │ │ • Admin moderation queue (GET /admin/moderation) │ │ • Admin KYC queue (GET /admin/kyc) │ │ • Admin users management (GET /admin/users) │ │ • Favorites (POST /favorites/:id, GET /favorites) │ │ • Inquiries (POST /inquiries, GET /inquiries/*) │ │ │ └───────────────────────────────────────────────────────────────────────────────┘ ┌─ 📊 IMPLEMENTATION ROADMAP ─────────────────────────────────────────────────┐ │ │ │ SPRINT 1–2 (Weeks 1–2): │ │ □ Gap #1: Recent listings (sortBy=publishedAt) │ │ □ Gap #2: Market snapshot endpoint │ │ □ Gap #3: Trending areas endpoint │ │ □ Gap #4: Similar listings endpoint │ │ □ Gap #5: Listing detail enrichment │ │ │ │ SPRINT 3 (Week 3): │ │ □ Gap #6: Price movers endpoint │ │ □ Gap #7: Market history (monthly data aggregation) │ │ □ Gap #10: Add cache metadata to analytics responses │ │ │ │ SPRINT 4+ (Optional): │ │ □ Gap #8: Ward-level heatmap (if needed for zoom) │ │ □ Gap #9: Real-time updates (WebSocket/SSE) │ │ □ Extra: Most-saved listings analytics (admin) │ │ │ └───────────────────────────────────────────────────────────────────────────────┘ ┌─ 📁 CONTROLLER FILE LOCATIONS ──────────────────────────────────────────────┐ │ │ │ Listings: apps/api/src/modules/listings/presentation/controllers/ │ │ Analytics: apps/api/src/modules/analytics/presentation/controllers/ │ │ Search: apps/api/src/modules/search/presentation/controllers/ │ │ Agents: apps/api/src/modules/agents/presentation/controllers/ │ │ Admin: apps/api/src/modules/admin/presentation/controllers/ │ │ Reviews: apps/api/src/modules/reviews/presentation/controllers/ │ │ Inquiries: apps/api/src/modules/inquiries/presentation/controllers/ │ │ │ └───────────────────────────────────────────────────────────────────────────────┘ SUMMARY: Total Endpoints Audited: 70+ Ready for FE: 58 Critical Gaps: 5 Medium Priority Gaps: 5 No-Brainer Wins: ~2 (sortBy, metadata) Estimated Dev Effort: 2–3 sprints (gaps 1–7) PREPARED BY: Backend API Audit FOR: TechLead (Frontend Refactor → Trading Exchange UI)