goodgo-platform/README.md

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.