912121cf09
apiClient.get returns the raw JSON body { data, cacheMeta }, so callers
were storing the envelope in state and reading totalScore as undefined,
crashing ListingDetailClient via undefined.toFixed(1).
Unwrap .data inside getNeighborhoodScore so consumers receive the bare
NeighborhoodScoreResult as the existing type expects.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
GoodGo Platform AI
Nền tảng bất động sản thông minh của Việt Nam — tìm kiếm nhà đất, định giá bằng AI và quản lý giao dịch toàn trình.
Công Nghệ Sử Dụng
| Tầng | Công nghệ |
|---|---|
| Backend | NestJS 11, TypeScript, Prisma ORM, CQRS |
| Frontend | Next.js 15, React 18, Tailwind CSS, Zustand |
| Cơ sở dữ liệu | PostgreSQL 16 + PostGIS 3.4 |
| Tìm kiếm | Typesense 27 |
| Cache/Queue | Redis 7 |
| AI/ML | FastAPI, XGBoost, Claude API, Underthesea |
| MCP | Model Context Protocol servers (tìm kiếm nhà đất, định giá, phân tích) |
| Lưu trữ | MinIO (tương thích S3) |
| Giám sát | Prometheus, Grafana, Loki + Promtail |
| Thanh toán | VNPay, MoMo, ZaloPay |
Tổng Quan Kiến Trúc
┌─────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Next.js 15 │────▶│ NestJS API │────▶│ PostgreSQL + │
│ (Web App) │ │ (REST) │ │ PostGIS │
└─────────────┘ └──────┬───────┘ └──────────────────┘
│
┌────────────┼────────────┐
│ │ │
┌─────▼──┐ ┌──────▼───┐ ┌────▼─────┐
│ Redis │ │Typesense │ │ MinIO │
│ Cache │ │ Search │ │ Storage │
└────────┘ └──────────┘ └──────────┘
│
┌─────▼──────────────────────────┐
│ MCP Servers │
│ ├─ Property Search │
│ ├─ Market Analytics │
│ └─ Valuation │
└─────────────┬─────────────────┘
│
┌───────▼────────┐
│ AI Services │
│ (FastAPI) │
│ ├─ AVM │
│ └─ Moderation │
└────────────────┘
Cấu Trúc Monorepo
goodgo-platform-ai/
├── apps/
│ ├── api/ # NestJS backend (port 3001)
│ └── web/ # Next.js frontend (port 3000)
├── libs/
│ ├── ai-services/ # Python FastAPI — AVM + content moderation
│ └── mcp-servers/ # MCP server implementations
├── prisma/ # Database schema & migrations
├── e2e/ # Playwright E2E tests (API + Web)
├── monitoring/ # Prometheus, Grafana, Loki & Promtail configs
├── scripts/ # Backup, restore & utility scripts
└── docs/ # Developer documentation
Khởi Động Nhanh
Yêu Cầu Tiên Quyết
- Docker Engine 24+ & Docker Compose v2
- Node.js 22 LTS
- pnpm 10.27+ (
corepack enable && corepack prepare pnpm@latest --activate)
Cài Đặt
# 1. Clone the repository
git clone <repo-url> && cd goodgo-platform-ai
# 2. Copy environment file
cp .env.example .env
# 3. Start infrastructure services
docker compose up -d
# 4. Verify services are healthy
docker compose ps
# 5. Install dependencies
pnpm install
# 6. Generate Prisma client
pnpm db:generate
# 7. Run database migrations
pnpm db:migrate:dev
# 8. Seed the database (optional)
pnpm db:seed
# 9. Start all apps in dev mode
pnpm dev
API sẽ khả dụng tại http://localhost:3001/api/v1 và ứng dụng web tại http://localhost:3000.
Swagger UI: Mở
http://localhost:3001/api/v1/docsđể xem tài liệu API tương tác.
Các Dịch Vụ Hạ Tầng
| Dịch vụ | Cổng | Bảng điều khiển |
|---|---|---|
| PostgreSQL + PostGIS | 5432 | — |
| Redis | 6379 | — |
| Typesense | 8108 | http://localhost:8108/health |
| MinIO | 9000 / 9001 | http://localhost:9001 (console) |
| AI Services (FastAPI) | 8000 | http://localhost:8000/health |
| Loki (tổng hợp log) | 3100 | http://localhost:3100/ready |
| Prometheus | 9090 | http://localhost:9090 |
| Grafana | 3002 | http://localhost:3002 |
Phát Triển
Các Lệnh Thông Dụng
pnpm dev # Start all apps (API + Web)
pnpm build # Build all packages
pnpm lint # Run ESLint
pnpm typecheck # TypeScript type checking
pnpm format # Format with Prettier
pnpm test # Run unit/integration tests
Cơ Sở Dữ Liệu
pnpm db:generate # Regenerate Prisma client
pnpm db:migrate:dev # Create and apply migrations
pnpm db:migrate:deploy # Apply migrations (CI/production)
pnpm db:seed # Seed database
pnpm db:studio # Open Prisma Studio (visual editor)
pnpm db:reset # Reset database (destructive)
Kiểm Thử E2E
pnpm test:e2e # Run all E2E tests
pnpm test:e2e:api # API tests only
pnpm test:e2e:web # Web UI tests only
pnpm test:e2e:report # Open HTML test report
Các Module API
Tất cả route API đều có tiền tố /api/v1/. Mỗi module tuân theo Domain-Driven Design với các tầng presentation/, application/, domain/ và infrastructure/.
| Module | Mô tả |
|---|---|
| auth | Đăng ký, đăng nhập, xoay vòng JWT + refresh token, OAuth (Google/Zalo), KYC, xuất/xoá dữ liệu người dùng |
| listings | CRUD tin đăng nhà đất, quy trình trạng thái, quản lý tệp phương tiện |
| search | Tìm kiếm toàn văn bản Typesense kết hợp bộ lọc địa lý, lưu tìm kiếm |
| payments | Tích hợp VNPay, MoMo, ZaloPay kèm xác thực callback |
| subscriptions | Quản lý gói dịch vụ, theo dõi mức sử dụng, kiểm soát hạn mức |
| notifications | Lịch sử thông báo qua email và trong ứng dụng cùng tuỳ chọn cá nhân |
| admin | Kiểm duyệt tin đăng, quản lý người dùng, nhật ký kiểm tra |
| analytics | Báo cáo thị trường, chỉ số giá, tích hợp AVM |
| agents | Hồ sơ và xác minh môi giới bất động sản |
| inquiries | Quản lý yêu cầu tư vấn nhà đất |
| leads | Theo dõi và chuyển đổi khách hàng tiềm năng |
| reviews | Đánh giá và xếp hạng bất động sản |
| health | Kiểm tra liveness và readiness |
| mcp | Cầu nối MCP server (tìm kiếm nhà đất, định giá, phân tích) |
| metrics | Thu thập metrics Prometheus và web vitals |
| shared | Mối quan tâm chung: guards, pipes, filters, dịch vụ Prisma/Redis |
Tài Liệu
| Tài liệu | Mô tả |
|---|---|
| Môi trường phát triển | Cài đặt Docker và các dịch vụ cục bộ |
| Kiến trúc | Thiết kế hệ thống, luồng dữ liệu, cấu trúc module |
| API Endpoints | Tài liệu tham khảo REST API endpoint |
| Mã lỗi API | Định dạng phản hồi lỗi và toàn bộ mã lỗi |
| Triển khai | Hướng dẫn triển khai môi trường sản xuất |
| Sao lưu & Khôi phục | Quy trình sao lưu và khôi phục sau sự cố |
| Đóng góp | Quy ước xử lý lỗi và các mẫu lập trình |
Giấy Phép
Độc quyền — Bảo lưu mọi quyền.