╔════════════════════════════════════════════════════════════════════════════════╗
║         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)
