08b96f9c2d
- 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>
283 lines
8.5 KiB
Markdown
283 lines
8.5 KiB
Markdown
# Backend API Audit: Trading Exchange UI Refactor — Index
|
||
|
||
## 📋 Audit Documents
|
||
|
||
This audit analyzed the goodgo-platform-ai backend API to identify gaps for the frontend refactor into a "trading exchange" (sàn giao dịch) style UI.
|
||
|
||
### Documents Generated
|
||
|
||
1. **BACKEND_API_AUDIT_EXCHANGE_UI.md** (261 lines)
|
||
- Full detailed audit with endpoint inventory
|
||
- Per-module breakdown (listings, analytics, search, agents, admin, reviews)
|
||
- All 10 critical + medium priority gaps documented
|
||
- Phased implementation roadmap (Phase 1–3)
|
||
- **Use this for**: In-depth planning, requirement discussions with backend team
|
||
|
||
2. **BACKEND_API_AUDIT_QUICK_REFERENCE.txt** (130 lines)
|
||
- One-page quick reference with visual formatting
|
||
- Highlights only the 10 gaps that need attention
|
||
- Sprint-by-sprint roadmap
|
||
- **Use this for**: Daily standup reference, priority discussions, quick reviews
|
||
|
||
---
|
||
|
||
## 🎯 Key Findings
|
||
|
||
### Summary Statistics
|
||
- **Total Endpoints Audited:** 70+
|
||
- **Ready for FE:** 58 ✅
|
||
- **Critical Gaps:** 5 🔴
|
||
- **Medium Priority Gaps:** 5 🟡
|
||
- **Estimated Dev Effort:** 2–3 sprints
|
||
- **Quick Wins:** 2 (sortBy, metadata)
|
||
|
||
### The 10 Gaps at a Glance
|
||
|
||
| # | Gap | Priority | Module | Effort |
|
||
|---|-----|----------|--------|--------|
|
||
| 1 | Recent listings ticker | 🔴 CRITICAL | listings | Low |
|
||
| 2 | Market snapshot endpoint | 🔴 CRITICAL | analytics | Medium |
|
||
| 3 | Trending areas | 🔴 CRITICAL | analytics | Medium |
|
||
| 4 | Similar listings | 🔴 CRITICAL | listings | Medium |
|
||
| 5 | Listing detail enrichment | 🔴 CRITICAL | listings | Medium |
|
||
| 6 | Price movers (gainers/losers) | 🟡 Medium | analytics | Low |
|
||
| 7 | Market history (12m trends) | 🟡 Medium | analytics | Medium |
|
||
| 8 | Ward-level heatmap | 🟡 Medium | analytics | Low |
|
||
| 9 | Real-time listing updates | 🟡 Medium | listings | High |
|
||
| 10 | Cache metadata in responses | 🟡 Medium | analytics | Low |
|
||
|
||
---
|
||
|
||
## 📊 Detailed Breakdown by UI Screen
|
||
|
||
### 1. Home Dashboard (Market Overview)
|
||
**Status:** 40% ready
|
||
|
||
**Currently Available:**
|
||
- Market report (district-level stats) ✅
|
||
- Heatmap (by district) ✅
|
||
- Price trends ✅
|
||
|
||
**Missing:**
|
||
- Market snapshot (live tiles with totalActive, avgPrice, change%) ❌ Gap #2
|
||
- Recent listings ticker ❌ Gap #1
|
||
- Trending areas (hot markets by inquiry volume) ❌ Gap #3
|
||
|
||
**Effort to Complete:** ~1 week (gaps #1–3)
|
||
|
||
---
|
||
|
||
### 2. Listings Board (Search + Filter)
|
||
**Status:** 80% ready
|
||
|
||
**Currently Available:**
|
||
- Full search with faceted filters ✅
|
||
- Pagination, sorting (but not by publishedAt) ✅
|
||
- Real-time updates endpoint exists but needs `sortBy=publishedAt` ⚠️
|
||
|
||
**Missing:**
|
||
- Sort by "newest first" (publishedAt) ❌ Gap #1
|
||
- "Just posted" / "price dropped" badges (needs real-time) ❌ Gap #9
|
||
- Similar listings comparables ❌ Gap #4
|
||
|
||
**Effort to Complete:** ~2–3 days (gaps #1, #4)
|
||
|
||
---
|
||
|
||
### 3. Listing Detail
|
||
**Status:** 70% ready
|
||
|
||
**Currently Available:**
|
||
- Full property data (description, media, location) ✅
|
||
- Seller & agent info ✅
|
||
- Price history ✅
|
||
- Media gallery ✅
|
||
- AVM endpoint exists (separate call) ✅
|
||
|
||
**Missing:**
|
||
- Valuation estimate in detail response ❌ Gap #5
|
||
- Inquiry count exposed ❌ Gap #5
|
||
- Agent quality score denormalized ❌ Gap #5
|
||
- Similar listings carousel ❌ Gap #4
|
||
|
||
**Effort to Complete:** ~3–4 days (gaps #4, #5)
|
||
|
||
---
|
||
|
||
### 4. Agent Profile Card
|
||
**Status:** 85% ready
|
||
|
||
**Currently Available:**
|
||
- Public agent profile ✅
|
||
- Quality score ✅
|
||
- Agency info ✅
|
||
|
||
**Missing:**
|
||
- Review stats (avg, count) — have separate endpoint but not denormalized ⚠️
|
||
- Active listings count ❌ (search + filter workaround: count by agent)
|
||
- Response time metrics ❌ (not tracked)
|
||
|
||
**Effort to Complete:** ~2–3 days (no new endpoints needed, just denormalization)
|
||
|
||
---
|
||
|
||
### 5. Admin Panel
|
||
**Status:** 95% ready
|
||
|
||
**Currently Available:**
|
||
- Moderation queue ✅
|
||
- KYC queue ✅
|
||
- User management ✅
|
||
- Audit logs ✅
|
||
- Revenue analytics ✅
|
||
|
||
**Missing:**
|
||
- None for core features; only nice-to-haves like queue statistics
|
||
|
||
**Effort to Complete:** Complete, ready for FE
|
||
|
||
---
|
||
|
||
### 6. Market Analytics Page
|
||
**Status:** 60% ready
|
||
|
||
**Currently Available:**
|
||
- Market report (current snapshot) ✅
|
||
- Price trends ✅
|
||
- Heatmap (by district) ✅
|
||
- Neighborhood scores ✅
|
||
|
||
**Missing:**
|
||
- Market history (12-month data for trend charts) ❌ Gap #7
|
||
- Ward-level heatmap drill-down ❌ Gap #8
|
||
- Price movers (top gainers/losers) ❌ Gap #6
|
||
- Cache metadata (data age indicators) ❌ Gap #10
|
||
|
||
**Effort to Complete:** ~1 week (gaps #6–8, #10)
|
||
|
||
---
|
||
|
||
## 🚀 Recommended Implementation Order
|
||
|
||
### Sprint 1 (Days 1–4)
|
||
- **Gap #1:** Add `sortBy=publishedAt` to `/listings` search
|
||
- File: `apps/api/src/modules/listings/presentation/dto/search-listings.dto.ts`
|
||
- Effort: 1 day
|
||
|
||
- **Gap #4:** Add `GET /listings/:id/similar` endpoint
|
||
- File: New query: `apps/api/src/modules/listings/application/queries/get-similar-listings/`
|
||
- Effort: 1.5 days
|
||
|
||
### Sprint 2 (Days 5–8)
|
||
- **Gap #2:** Add `GET /analytics/market-snapshot` endpoint
|
||
- File: New query in analytics module
|
||
- Effort: 2 days
|
||
|
||
- **Gap #3:** Add `GET /analytics/trending-areas` endpoint
|
||
- Effort: 1.5 days
|
||
|
||
### Sprint 3 (Days 9–12)
|
||
- **Gap #5:** Enrich `GET /listings/:id` with `valuationEstimate`, `inquiryCount`, `agentScore`
|
||
- Effort: 1.5 days
|
||
|
||
- **Gap #10:** Add `cachedAt`, `nextRefreshAt` to all `/analytics/*` responses
|
||
- Effort: 1 day
|
||
|
||
### Sprint 4 (Days 13–17) — Medium Priority
|
||
- **Gap #6:** `GET /analytics/price-movers`
|
||
- Effort: 1.5 days
|
||
|
||
- **Gap #7:** `GET /analytics/market-history?period=12m`
|
||
- Effort: 2 days
|
||
|
||
### Sprint 5+ (Optional)
|
||
- **Gap #8:** Ward-level heatmap enhancement
|
||
- **Gap #9:** Real-time updates (WebSocket/SSE)
|
||
|
||
---
|
||
|
||
## 📁 File Structure Reference
|
||
|
||
All controllers follow this pattern:
|
||
```
|
||
apps/api/src/modules/{MODULE}/
|
||
├── presentation/
|
||
│ ├── controllers/
|
||
│ │ └── {name}.controller.ts
|
||
│ └── dto/
|
||
│ └── *.dto.ts
|
||
├── application/
|
||
│ ├── commands/
|
||
│ └── queries/
|
||
│ └── {query-name}/
|
||
│ ├── {query-name}.query.ts
|
||
│ └── {query-name}.handler.ts
|
||
├── domain/
|
||
│ └── repositories/
|
||
└── infrastructure/
|
||
```
|
||
|
||
Key files to modify:
|
||
- **Listings module:** `apps/api/src/modules/listings/presentation/controllers/listings.controller.ts`
|
||
- **Analytics module:** `apps/api/src/modules/analytics/presentation/controllers/analytics.controller.ts`
|
||
- **Search module:** `apps/api/src/modules/search/presentation/controllers/search.controller.ts`
|
||
|
||
---
|
||
|
||
## ✅ Audit Checklist
|
||
|
||
- [x] All 70+ endpoints enumerated by module
|
||
- [x] Route prefixes, methods, query params documented
|
||
- [x] Auth/guard requirements identified
|
||
- [x] Gaps mapped to UI screen requirements
|
||
- [x] Implementation roadmap created
|
||
- [x] Sprint-by-sprint effort estimates provided
|
||
- [x] No mock data recommended—all real backend data
|
||
- [x] File paths provided for easy navigation
|
||
|
||
---
|
||
|
||
## 🎓 How to Use This Audit
|
||
|
||
### For Backend TechLead:
|
||
1. Read **BACKEND_API_AUDIT_EXCHANGE_UI.md** for full context
|
||
2. Prioritize gaps 1–5 (critical) in Sprint 1–2
|
||
3. Reference "Implementation Roadmap" section for sequencing
|
||
4. Use "Recommendations" section for effort estimates
|
||
|
||
### For Frontend Lead:
|
||
1. Read **BACKEND_API_AUDIT_QUICK_REFERENCE.txt** for quick summary
|
||
2. For each screen needing data:
|
||
- Check "Available Endpoints" section
|
||
- If gaps exist, reference "Critical Gaps" section
|
||
- Communicate blocker status to backend
|
||
|
||
### For Product Manager:
|
||
1. Review "Detailed Breakdown by UI Screen" section above
|
||
2. Readiness % shows which screens are ready for FE work
|
||
3. Effort estimates help with release planning
|
||
|
||
---
|
||
|
||
## 📞 Questions / Follow-ups
|
||
|
||
**Q: Can we use mock data on FE while waiting for gaps?**
|
||
**A:** No — requirement is for real backend data only. Gaps must be closed before FE integration.
|
||
|
||
**Q: Which gap is easiest to complete first?**
|
||
**A:** Gap #1 (sortBy=publishedAt) — adds 1 parameter to existing search endpoint, ~1 day.
|
||
|
||
**Q: Which gap has the most impact?**
|
||
**A:** Gap #2 (market-snapshot) — powers entire home dashboard, enables real-time trading feel.
|
||
|
||
**Q: Can gaps #8 and #9 be skipped?**
|
||
**A:** Yes — Gap #8 (ward-level heatmap) is nice-to-have; Gap #9 (real-time) is polish. Gaps #1–7 are blocking.
|
||
|
||
---
|
||
|
||
**Audit Date:** 2026-04-21
|
||
**Repository:** goodgo-platform-ai
|
||
**Scope:** 70+ endpoints across 12 modules
|
||
**Status:** Ready for planning | No mock data allowed
|
||
**Next Step:** TechLead prioritization of gaps 1–7 for sprint planning
|