admin/goodgo-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add project documentation — changelog, QA tracker, audit reports, and guides

Browse Source 
Add comprehensive project documentation including changelog, QA tracker,
code quality audit, implementation guide, K6 load testing guide, frontend
exploration notes, and file mapping reference.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Ho Ngoc Hai
2026-04-09 09:44:53 +07:00
parent ef47d9eb80
commit a1a44ef8fb
13 changed files with 4684 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
CHANGELOG.md Normal file
View File

@@ -0,0 +1,213 @@
# Changelog
All notable changes to the GoodGo Platform will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- Multi-stage production Dockerfile for NestJS API
- Startup-time validation for JWT secrets (rejects placeholders)
---
## [1.4.0] - 2026-04-08
### Added
- Redis caching for user quota checks with prefix-based cache invalidation
- Domain layer unit tests across all modules (auth, payments, subscriptions, admin, analytics, listings, notifications, reviews, search, metrics)
- Health check endpoints (`/health`, `/health/db`, `/health/redis`) using `@nestjs/terminus`
- Property Valuation UI with AVM (Automated Valuation Model) integration on the web frontend
### Changed
- Improved cache service with prefix-based clearing patterns
- Enhanced analytics query handlers with caching layer
### Fixed
- Lint errors resolved across codebase
---
## [1.3.0] - 2026-03-28
### Added
- Complete notification delivery system with email (Nodemailer + Handlebars), push (Firebase Cloud Messaging), and in-app channels
- Mapbox district heatmap visualization and agent performance dashboard on web frontend
- Reviews module with full CRUD endpoints, CQRS handlers, and 1-5 star rating value objects
- Unit tests for analytics, metrics, notifications, payments, and search modules
- Enhanced geo-search with PostGIS spatial queries and Typesense listing-approved event handlers
- Dedicated `/health` endpoint with timestamp response
### Changed
- Refactored cache service internals and analytics handlers for better reliability
### Fixed
- Missing `AuthState` properties in web frontend test mocks
- E2E workflow improvements: Prisma generate step, browser cache, trace artifacts
---
## [1.2.0] - 2026-03-20
### Added
- React Query integration for data fetching with error retry UX
- Dark mode toggle for web frontend
- Redis caching layer for search and analytics hot paths
- Vietnamese NLP pipeline (Underthesea) for property description analysis in AI services
- Prometheus `MetricsService`, `HttpMetricsInterceptor`, and custom metric constants
- Agent Profile, KYC verification, Subscription, and Payment dashboard pages on web frontend
- Unit tests for MCP servers (property search, market analytics, valuation)
- Unit tests for web frontend validations and utility functions
### Fixed
- Removed MinIO hardcoded credentials; added presigned URL support for media uploads
- JWT secret enforcement in all environments (not just production)
- Added missing `Review.userId` index for FK query performance
---
## [1.1.0] - 2026-03-12
### Added
- Listing duplicate detection service to prevent redundant property submissions
- Subscription quota enforcement with per-plan feature limits and usage metering
- Google and Zalo OAuth backend strategies for social login
- 58 unit tests covering critical auth, payment, and subscription paths
- Loading skeletons, error boundaries, and accessibility improvements on web frontend
- Sentry error tracking integration for both API and web apps
### Fixed
- Hardened production Docker deployment configuration for all services
---
## [1.0.0] - 2026-03-01
### Added
#### Authentication & Security
- User registration and login with phone number and password
- JWT access tokens (15-minute expiry) with refresh token rotation (7-day expiry)
- Token family-based rotation detection to prevent replay attacks
- OAuth social login support (Google, Zalo)
- KYC (Know Your Customer) verification workflow (NONE -> PENDING -> VERIFIED/REJECTED)
- Role-based access control with `@Roles()` decorator (USER, AGENT, ADMIN)
- Rate limiting: 60 req/min default, 10 req/min auth, 20 req/min payment callbacks
- `ThrottlerBehindProxyGuard` for X-Forwarded-For-aware IP tracking
- Helmet security headers, CORS configuration
- Input validation (class-validator) and content sanitization (sanitize-html)
- CSRF protection with double-submit cookie pattern
- PII masking in structured logs (Pino)
- Bcrypt password hashing
#### Property Listings
- Full CRUD for property listings with status state machine (DRAFT -> PENDING_REVIEW -> ACTIVE -> RESERVED -> SOLD/RENTED)
- Media upload support (S3/MinIO) with file validation
- AI-assisted moderation scoring via Claude API
- Admin moderation queue with bulk approve/reject
- Quota-gated listing creation tied to subscription plans
#### Search & Discovery
- Full-text property search via Typesense with Vietnamese language support
- Geo-spatial search using PostGIS (lat/long + radius queries)
- Faceted filtering by price, property type, bedrooms, district
- Event-driven search index updates (listing approved/updated/sold -> re-index)
- Prefix-based cache invalidation for search results
#### Payments
- Payment processing with VNPay, MoMo, and ZaloPay provider integration
- Idempotent webhook callback handling with signature verification
- Payment refund support
- Atomic status transitions (PENDING -> COMPLETED/FAILED)
- Event emission on payment completion/failure for downstream processing
#### Subscriptions & Billing
- Subscription plans with tiered feature flags (JSON columns)
- Usage metering and quota enforcement (Redis-backed)
- Plan upgrades and cancellations
- Billing history tracking
- Event-driven usage tracking (`listing.created` -> meter usage)
#### Admin Panel
- Dashboard with system-wide statistics
- User management (list, view, ban/unban)
- KYC approval queue with approve/reject actions
- Listing moderation queue with bulk moderation
- Revenue statistics and analytics
- Subscription adjustment for individual users
#### Analytics & Market Data
- District-level market reports with PostGIS spatial aggregation
- Price trend analysis by property type and district
- District heatmap data (geo aggregates)
- Market index tracking and updates
- Cache-based report delivery
#### Notifications
- Multi-channel notification delivery: EMAIL, SMS, PUSH (FCM), IN_APP
- 8 event-driven listeners: welcome email, KYC approval, listing approval/rejection, payment confirmation/failure, subscription expiry, quota exceeded
- Handlebars email templates with Vietnamese localization
- User notification preferences (opt-out per channel/type)
#### Reviews
- Property and agent reviews with 1-5 star ratings
- Review CRUD with target polymorphism (agent or property)
- Average rating calculation per target
#### MCP (Model Context Protocol) Servers
- Property Search Server: `search_properties`, `compare_properties`, `get_property_details`
- Market Analytics Server: `get_market_report`, `analyze_trends`, `get_price_indices`
- Valuation Server: `estimate_valuation`, `extract_features`, `compare_valuations` (XGBoost via FastAPI)
- HTTP transport controller with `McpRegistryService`
#### AI Services
- FastAPI microservice with XGBoost property valuation model
- Claude API-powered content moderation for listing descriptions
- Vietnamese NLP preprocessing with Underthesea
#### Infrastructure
- PostgreSQL 16 with PostGIS extension (22 models, spatial indexes)
- Redis caching layer for search, analytics, quota, and session data
- Typesense search engine with Vietnamese language support
- Prometheus metrics endpoint with HTTP request duration histograms and error rate counters
- Grafana dashboards auto-provisioned from `monitoring/` directory
- Pino structured JSON logging with correlation IDs
- Prisma ORM with migration system and seed data (Ho Chi Minh City districts/wards, sample properties, subscription plans)
#### Frontend (Next.js 14)
- App Router with Tailwind CSS and Zustand state management
- Property search page with Mapbox GL map integration
- Listing detail pages with media gallery
- Agent dashboard with KYC, subscription, and payment management
- District heatmap visualization
- Property valuation UI with AVM integration
- Dark mode toggle
- Loading skeletons and error boundaries
- Vietnamese UI text throughout (property types, districts, currency in VND)
#### Developer Experience
- Monorepo with pnpm workspaces and Turborepo
- ESLint with import ordering rules
- Prettier code formatting
- Husky git hooks
- E2E tests with Playwright (14 web test files)
- GitHub Actions CI pipeline (lint -> typecheck -> test -> build)
### Security
- httpOnly cookie-based token storage with CSRF hardening
- Idempotency keys on payment flows with amount validation
- Magic byte file validation for media uploads
- Admin audit logging
- JWT audience/issuer validation
- Production environment variable validation
- Sanitized `.env.example` (no leaked secrets)
- Graceful shutdown hooks for clean process termination
[Unreleased]: https://github.com/goodgo/platform-ai/compare/v1.4.0...HEAD
[1.4.0]: https://github.com/goodgo/platform-ai/compare/v1.3.0...v1.4.0
[1.3.0]: https://github.com/goodgo/platform-ai/compare/v1.2.0...v1.3.0
[1.2.0]: https://github.com/goodgo/platform-ai/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/goodgo/platform-ai/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/goodgo/platform-ai/releases/tag/v1.0.0