# 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 ```bash # 1. Clone the repository git clone && 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 ```bash 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 ```bash 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 ```bash 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](docs/dev-environment.md) | Cài đặt Docker và các dịch vụ cục bộ | | [Kiến trúc](docs/architecture.md) | Thiết kế hệ thống, luồng dữ liệu, cấu trúc module | | [API Endpoints](docs/api-endpoints.md) | Tài liệu tham khảo REST API endpoint | | [Mã lỗi API](docs/api-error-codes.md) | Định dạng phản hồi lỗi và toàn bộ mã lỗi | | [Triển khai](docs/deployment.md) | Hướng dẫn triển khai môi trường sản xuất | | [Sao lưu & Khôi phục](docs/backup-restore.md) | Quy trình sao lưu và khôi phục sau sự cố | | [Đóng góp](CONTRIBUTING.md) | 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.