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
421
docs/explorations/API_DOCUMENTATION_INDEX.md
Normal file
421
docs/explorations/API_DOCUMENTATION_INDEX.md
Normal file
@@ -0,0 +1,421 @@
|
||||
# GoodGo Platform API Documentation Index
|
||||
|
||||
Complete reference suite for mapping UI components to real API data.
|
||||
|
||||
**Generated**: April 21, 2026 | **Status**: ✅ Complete
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation Suite
|
||||
|
||||
### 1. **API_ENDPOINTS_REFERENCE.md** — The Complete Reference
|
||||
**Best for**: Developers implementing API integrations
|
||||
**Length**: ~800 lines
|
||||
**Contains**:
|
||||
- All 15+ API endpoints with full signatures
|
||||
- Request parameters (query, body, path)
|
||||
- Response schemas in TypeScript
|
||||
- Caching behavior per endpoint
|
||||
- Rate limits
|
||||
- Auth requirements
|
||||
- Prisma model definitions
|
||||
- Enum values
|
||||
|
||||
**When to use**:
|
||||
- "What fields does the valuation response have?"
|
||||
- "What query parameters does the heatmap endpoint accept?"
|
||||
- "What's the database schema for Property?"
|
||||
|
||||
### 2. **UI_MAPPING_QUICK_GUIDE.md** — Fast Integration Reference
|
||||
**Best for**: Frontend developers building UI components
|
||||
**Length**: ~400 lines
|
||||
**Contains**:
|
||||
- Visual mockups with field labels
|
||||
- Pre-formatted UI examples (property card, market snapshot, etc.)
|
||||
- Direct field mappings from API → UI display
|
||||
- Format conversion functions (price, confidence, distance)
|
||||
- Status color schemes
|
||||
- Engagement metric displays
|
||||
|
||||
**When to use**:
|
||||
- "How should I display the market snapshot widget?"
|
||||
- "What data goes in this property card?"
|
||||
- "How do I convert the confidence score to stars?"
|
||||
|
||||
### 3. **API_EXPLORATION_SUMMARY.md** — Executive Overview
|
||||
**Best for**: Project leads, architects, QA teams
|
||||
**Length**: ~300 lines
|
||||
**Contains**:
|
||||
- High-level findings by module
|
||||
- Field count & complexity metrics
|
||||
- Quick integration checklist
|
||||
- Data quality notes
|
||||
- Next steps & action items
|
||||
- Source files analyzed
|
||||
|
||||
**When to use**:
|
||||
- Project planning
|
||||
- Sprint estimation
|
||||
- Quality assurance review
|
||||
- Team onboarding
|
||||
|
||||
---
|
||||
|
||||
## 🗺️ Module-by-Module Breakdown
|
||||
|
||||
### Analytics Module
|
||||
- **15+ Endpoints**: Market data, valuations, scores, POIs
|
||||
- **Key Files**: See API_ENDPOINTS_REFERENCE.md → Analytics Module
|
||||
- **UI Components to Build**:
|
||||
- Market snapshot widget
|
||||
- Price trend chart
|
||||
- Heatmap display
|
||||
- District stats table
|
||||
- Trending areas carousel
|
||||
- Valuation card
|
||||
- Neighborhood score card
|
||||
- POI map
|
||||
|
||||
**Quick Field Map**:
|
||||
| Feature | Endpoint | Key Fields |
|
||||
|---------|----------|-----------|
|
||||
| Market Overview | `GET /analytics/market-snapshot` | activeCount, avgPrice, medianPrice, priceChangePct |
|
||||
| Price History | `GET /analytics/price-trend` | trend[].{period, medianPrice, avgPriceM2} |
|
||||
| Heatmap | `GET /analytics/heatmap` | dataPoints[].{district, avgPriceM2} |
|
||||
| District Stats | `GET /analytics/district-stats` | districts[].{medianPrice, totalListings, yoyChange} |
|
||||
| Hot Areas | `GET /analytics/trending-areas` | areas[].{listings, inquiries, views, scoreRank} |
|
||||
| Property Value | `GET/POST /analytics/valuation` | estimatedPrice, confidence, comparables[] |
|
||||
| Scores | `GET /analytics/neighborhoods/:district/score` | educationScore, totalScore, poiCounts |
|
||||
| POIs | `GET /analytics/pois/nearby` | pois[].{name, type, distance} |
|
||||
|
||||
### Listings Module
|
||||
- **2 Core Entities**: Property (45 fields), Listing (25 fields)
|
||||
- **Key Files**: See API_ENDPOINTS_REFERENCE.md → Listings Module
|
||||
- **UI Components**:
|
||||
- Property card (search results)
|
||||
- Property detail page
|
||||
- Listing editor
|
||||
- Status badges
|
||||
|
||||
**Quick Field Map**:
|
||||
| Display | Source | Field Path |
|
||||
|---------|--------|-----------|
|
||||
| Price | Listing | listing.priceVND |
|
||||
| Beds/Baths | Property | property.bedrooms, property.bathrooms |
|
||||
| Area | Property | property.areaM2 |
|
||||
| Status | Listing | listing.status |
|
||||
| Views | Listing | listing.viewCount |
|
||||
| Agent | Listing | listing.agent.user.fullName |
|
||||
| Address | Property | property.address, property.district |
|
||||
|
||||
### Agents Module
|
||||
- **Key Fields**: Profile, credentials, performance metrics
|
||||
- **Key Files**: See API_ENDPOINTS_REFERENCE.md → Agents Module
|
||||
- **UI Components**:
|
||||
- Agent card
|
||||
- Agent profile page
|
||||
- Agent rating badge
|
||||
|
||||
**Quick Field Map**:
|
||||
| Display | Field | Type |
|
||||
|---------|-------|------|
|
||||
| Name | user.fullName | string |
|
||||
| Rating | qualityScore | 0-100 → convert to stars |
|
||||
| License | licenseNumber | string (nullable) |
|
||||
| Verified | isVerified | boolean |
|
||||
| Service Areas | serviceAreas[] | array of district IDs |
|
||||
| Response Time | responseTimeAvg | seconds → hours |
|
||||
|
||||
### Search Module
|
||||
- **31 Indexed Fields**: ListingDocument structure
|
||||
- **Key Files**: See API_ENDPOINTS_REFERENCE.md → Search Module
|
||||
- **UI Components**:
|
||||
- Search bar
|
||||
- Filter sidebar
|
||||
- Results list with pagination
|
||||
- Geo-search on map
|
||||
|
||||
**Quick Field Map**:
|
||||
| Filter | Field | Values |
|
||||
|--------|-------|--------|
|
||||
| Type | propertyType | APARTMENT, VILLA, TOWNHOUSE, LAND, OFFICE, SHOPHOUSE |
|
||||
| Transaction | transactionType | SALE, RENT |
|
||||
| Price Range | priceVND | numeric range |
|
||||
| Area Range | areaM2 | numeric range |
|
||||
| Bedrooms | bedrooms | >= operator |
|
||||
| Location | district, city | equality match |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Common Integration Patterns
|
||||
|
||||
### Pattern 1: Display Property Card
|
||||
```
|
||||
1. Fetch from search index or detail endpoint
|
||||
2. Map fields:
|
||||
- listing.priceVND → format as VND string
|
||||
- property.bedrooms → display or show "Studio" if null
|
||||
- listing.status → map to color & icon
|
||||
- listing.featuredUntil → show "Featured" badge if > now
|
||||
3. Fetch agent data via listing.agent.id
|
||||
4. Render with caching indicator
|
||||
```
|
||||
|
||||
### Pattern 2: Display Market Snapshot
|
||||
```
|
||||
1. GET /analytics/market-snapshot?city=HCMC
|
||||
2. Map response fields to widgets
|
||||
3. Show priceChangePct.d1/d7/d30 as trend indicators
|
||||
4. Display nextRefreshAt for cache status
|
||||
5. Poll again at nextRefreshAt or use web socket
|
||||
```
|
||||
|
||||
### Pattern 3: Implement Property Valuation
|
||||
```
|
||||
1. For existing property: GET /analytics/valuation?propertyId=X
|
||||
2. For manual input: POST /analytics/valuation with form data
|
||||
3. Display estimatedPrice (format as VND)
|
||||
4. Convert confidence (0.0-1.0) to percentage
|
||||
5. Show comparables[] in carousel
|
||||
6. Cache for 24 hours
|
||||
```
|
||||
|
||||
### Pattern 4: Build District Search
|
||||
```
|
||||
1. Get districts from heatmap or district-stats endpoint
|
||||
2. Render as map overlay or list
|
||||
3. Allow filtering by avgPriceM2 (color intensity)
|
||||
4. Show tooltip with medianPrice, totalListings, daysOnMarket
|
||||
5. Update heatmap as user changes period
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Field Type Quick Reference
|
||||
|
||||
### Prices (all VND)
|
||||
- **Type**: `string` (in API DTOs) | `BigInt` (database)
|
||||
- **Display**: Format with thousand separators + currency symbol
|
||||
- **Range**: 0 to 9,223,372,036,854,775,807 (BigInt max)
|
||||
- **Example**: `"2500000000"` → `"2.5B"` or `"2,500,000,000 ₫"`
|
||||
|
||||
### Confidence Scores
|
||||
- **Valuation**: 0.0-1.0 (multiply by 100 for %)
|
||||
- **Moderation**: 0-100 (direct use)
|
||||
- **Quality (Agent)**: 0.0-100.0 (divide by 20 for stars: 0-5)
|
||||
|
||||
### Distances
|
||||
- **Storage**: meters (int/float)
|
||||
- **Display**: `< 1000m` → show "XXXm", `>= 1000m` → show "X.Xkm"
|
||||
|
||||
### Timestamps
|
||||
- **Format**: ISO 8601 strings
|
||||
- **Cache**: `cachedAt`, `nextRefreshAt`, `calculatedAt`, `valuedAt`, `publishedAt`
|
||||
- **Type**: Most are `Date` in entities, `string` in API responses
|
||||
|
||||
### Enums (Map to Display Labels)
|
||||
```typescript
|
||||
PropertyType: {
|
||||
APARTMENT: "Căn hộ",
|
||||
VILLA: "Biệt thự",
|
||||
TOWNHOUSE: "Nhà phố",
|
||||
LAND: "Đất",
|
||||
OFFICE: "Văn phòng",
|
||||
SHOPHOUSE: "Nhà mặt phố"
|
||||
}
|
||||
|
||||
ListingStatus: {
|
||||
DRAFT: "Nháp" (Gray),
|
||||
PENDING_REVIEW: "Chờ duyệt" (Yellow),
|
||||
ACTIVE: "Hoạt động" (Green),
|
||||
RESERVED: "Đặt" (Blue),
|
||||
SOLD: "Đã bán" (Dark),
|
||||
RENTED: "Đã thuê" (Dark),
|
||||
EXPIRED: "Hết hạn" (Orange),
|
||||
REJECTED: "Từ chối" (Red)
|
||||
}
|
||||
|
||||
Direction: {
|
||||
NORTH: "Hướng Bắc",
|
||||
SOUTH: "Hướng Nam",
|
||||
EAST: "Hướng Đông",
|
||||
WEST: "Hướng Tây",
|
||||
NORTHEAST: "Hướng Đông Bắc",
|
||||
// ... etc
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Performance Considerations
|
||||
|
||||
### Caching Strategy
|
||||
```
|
||||
Market Snapshot: 30 minutes
|
||||
Price Trend: 1 hour
|
||||
Heatmap: 1 hour
|
||||
District Stats: 6 hours
|
||||
Trending Areas: 30 minutes
|
||||
Valuation: 24 hours
|
||||
Neighborhood: 24 hours
|
||||
```
|
||||
→ Check `nextRefreshAt` in response to avoid redundant calls
|
||||
|
||||
### Rate Limits (Per User)
|
||||
```
|
||||
Valuation POST: 10 req/min
|
||||
Search: 200 req/min
|
||||
Analytics Queries: 100 req/min
|
||||
Batch Operations: Limited to 50 items
|
||||
```
|
||||
→ Implement exponential backoff for 429 responses
|
||||
|
||||
### Pagination
|
||||
```
|
||||
Search results include: page, perPage, totalPages, totalFound
|
||||
Implement: Lazy loading or infinite scroll
|
||||
Typical perPage: 20-50 listings
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Field Validation Rules
|
||||
|
||||
### Required Fields (Cannot be null)
|
||||
- Listing: `priceVND`, `transactionType`, `status`, `sellerId`
|
||||
- Property: `propertyType`, `title`, `location`, `areaM2`
|
||||
- Agent: `userId`, `isVerified`
|
||||
|
||||
### Nullable Fields (Default to null)
|
||||
- `property.bedrooms` → null means studio/no specific bedroom count
|
||||
- `property.bathrooms` → null if not specified
|
||||
- `listing.agentId` → null means direct seller (no agent)
|
||||
- `listing.aiPriceEstimate` → null if valuation not run
|
||||
- Agent `bio`, `licenseNumber` → optional fields
|
||||
|
||||
### String Length Limits
|
||||
- Description fields: typically `@db.Text` (no limit imposed)
|
||||
- Titles: reasonable limit (~200 chars implied)
|
||||
- Enum values: fixed options (no arbitrary strings)
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing & Mock Data
|
||||
|
||||
### Mock Market Snapshot Response
|
||||
```json
|
||||
{
|
||||
"city": "HCMC",
|
||||
"activeCount": 2345,
|
||||
"avgPrice": 2800000000,
|
||||
"medianPrice": 2500000000,
|
||||
"priceChangePct": {"d1": 2, "d7": 5, "d30": 12},
|
||||
"avgPricePerM2": 35000000,
|
||||
"daysOnMarket": 45,
|
||||
"newListings24h": 12,
|
||||
"cachedAt": "2026-04-21T10:30:00Z",
|
||||
"nextRefreshAt": "2026-04-21T11:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Mock Valuation Response
|
||||
```json
|
||||
{
|
||||
"estimatedPrice": "2500000000",
|
||||
"confidence": 0.82,
|
||||
"pricePerM2": 33300000,
|
||||
"comparables": [
|
||||
{
|
||||
"propertyId": "prop-1",
|
||||
"address": "123 Nguyen Hue",
|
||||
"priceVND": "2340000000",
|
||||
"pricePerM2": 31200000,
|
||||
"distanceMeters": 450,
|
||||
"soldAt": "2026-04-15T00:00:00Z"
|
||||
}
|
||||
],
|
||||
"modelVersion": "v2"
|
||||
}
|
||||
```
|
||||
|
||||
### Mock Property Card Fields
|
||||
```json
|
||||
{
|
||||
"listing": {
|
||||
"id": "list-1",
|
||||
"priceVND": "2500000000",
|
||||
"transactionType": "SALE",
|
||||
"status": "ACTIVE",
|
||||
"viewCount": 342,
|
||||
"saveCount": 28,
|
||||
"inquiryCount": 12,
|
||||
"featuredUntil": null,
|
||||
"publishedAt": "2026-04-15T08:30:00Z"
|
||||
},
|
||||
"property": {
|
||||
"id": "prop-1",
|
||||
"title": "Căn hộ sang trọng Quận 1",
|
||||
"propertyType": "APARTMENT",
|
||||
"areaM2": 75,
|
||||
"bedrooms": 2,
|
||||
"bathrooms": 1,
|
||||
"district": "Quận 1",
|
||||
"ward": "Phường Bến Nghé",
|
||||
"city": "Hồ Chí Minh"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Quick Start by Role
|
||||
|
||||
### Frontend Developer
|
||||
1. Start with **UI_MAPPING_QUICK_GUIDE.md**
|
||||
2. Reference **API_ENDPOINTS_REFERENCE.md** for exact field names
|
||||
3. Use mock data above for testing
|
||||
4. Implement price formatting utilities
|
||||
|
||||
### Backend/Full-Stack Developer
|
||||
1. Read **API_EXPLORATION_SUMMARY.md** for overview
|
||||
2. Use **API_ENDPOINTS_REFERENCE.md** as API contract
|
||||
3. Reference Prisma models for database design
|
||||
4. Review rate limits & caching strategy
|
||||
|
||||
### QA / Test Automation
|
||||
1. Start with **API_EXPLORATION_SUMMARY.md**
|
||||
2. Review rate limits & error handling
|
||||
3. Test edge cases (null values, precision, bounds)
|
||||
4. Verify caching behavior using `cachedAt`/`nextRefreshAt`
|
||||
|
||||
### Product / Project Lead
|
||||
1. Read **API_EXPLORATION_SUMMARY.md**
|
||||
2. Review integration checklist
|
||||
3. Identify potential blockers
|
||||
4. Estimate component complexity
|
||||
|
||||
---
|
||||
|
||||
## 📝 Document Update Protocol
|
||||
|
||||
These documents were generated by scanning source code on **April 21, 2026**.
|
||||
|
||||
**To update**:
|
||||
1. Re-scan source modules if API changes
|
||||
2. Update DTOs → API_ENDPOINTS_REFERENCE.md
|
||||
3. Update Prisma schema → Prisma Schema section
|
||||
4. Verify UI mappings → UI_MAPPING_QUICK_GUIDE.md
|
||||
5. Update this index with changelog
|
||||
|
||||
**Changelog**:
|
||||
- v1.0 (2026-04-21): Initial complete documentation
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: April 21, 2026
|
||||
**Status**: ✅ Complete
|
||||
**Maintainer**: Generated by API exploration task
|
||||
|
||||
For questions or updates, reference the source files in:
|
||||
- `apps/api/src/modules/` (API layer)
|
||||
- `prisma/schema.prisma` (Database)
|
||||
Reference in New Issue
Block a user