docs: consolidate exploration & audit reports under docs/ (TEC-3094)
- Move 8 stray .md (+5 .txt) from ~/Desktop into docs/explorations/from-desktop/ - Reorganize 27 .md/.txt at workspace root: - audit reports -> docs/audits/ - exploration reports -> docs/explorations/ - design system -> docs/design-system/ - Keep only README/CHANGELOG/CONTRIBUTING/CLAUDE at repo root - Refresh docs/README.md as canonical index with links to all groups - Note: pre-existing docs/audits/AUDIT_INDEX.md and AUDIT_SUMMARY.md were overwritten by the newer root-level versions during the move Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Ho Ngoc Hai
136
docs/audits/BACKEND_API_AUDIT_QUICK_REFERENCE.txt
Normal file
136
docs/audits/BACKEND_API_AUDIT_QUICK_REFERENCE.txt
Normal file
@@ -0,0 +1,136 @@
|
||||
╔════════════════════════════════════════════════════════════════════════════════╗
|
||||
║ 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)
|
||||
Reference in New Issue
Block a user