# 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.
