11f2bf26e6
Some checks failed
CI / Lint → Typecheck → Test → Build (22) (push) Failing after 29s
CI / E2E Tests (push) Has been skipped
CodeQL Analysis / CodeQL (javascript-typescript) (push) Failing after 2m42s
Deploy / Build Web Image (push) Failing after 27s
Deploy / Build AI Services Image (push) Failing after 29s
E2E Tests / Playwright E2E (push) Failing after 43s
Deploy / Build API Image (push) Failing after 1m31s
Security Scanning / Dependency Audit (pnpm) (push) Failing after 6s
Security Scanning / Trivy Scan — API Image (push) Failing after 5m35s
Security Scanning / Trivy Scan — AI Services Image (push) Failing after 3m45s
Deploy / Deploy to Staging (push) Has been skipped
Deploy / Smoke Test Staging (push) Has been skipped
Deploy / Deploy to Production (push) Has been skipped
Deploy / Smoke Test Production (push) Has been skipped
Deploy / Rollback Staging (push) Has been skipped
Deploy / Rollback Production (push) Has been skipped
Security Scanning / Trivy Scan — Web Image (push) Failing after 13m51s
Security Scanning / Trivy Filesystem Scan (push) Failing after 14m46s
Security Scanning / Security Gate (push) Has been cancelled
194 lines
7.9 KiB
Markdown
194 lines
7.9 KiB
Markdown
# 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 <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
|
|
|
|
```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.
|