goodgo-platform/docs/load-testing/K6_README.md

# Tài Liệu K6 Load Testing cho GoodGo Platform

Hướng dẫn đầy đủ để hiểu và triển khai K6 load tests cho GoodGo Platform API.

---

## 📚 Các File Tài Liệu

Thư mục này chứa ba hướng dẫn toàn diện về K6 load testing:

### 1. **K6_LOAD_TESTING_GUIDE.md** (Tham Khảo Chính)
Khám phá toàn diện cấu trúc GoodGo Platform API cho load testing.

**Nội dung:**
- Cấu trúc module API (auth, listings, payments, search)
- Tài liệu endpoint chi tiết với HTTP method, rate limit và yêu cầu auth
- Đặc tả DTO đầy đủ với hình dạng request/response body
- Tham khảo cấu hình database và environment
- Thiết lập test hiện có (Playwright, Vitest, CI/CD)
- Mẫu kiến trúc (CQRS, DDD)
- Tham khảo nhanh vị trí file
- Khuyến nghị triển khai K6

**Khi nào sử dụng:** Khi cần đào sâu vào các endpoint cụ thể, hiểu luồng xác thực, kiểm tra biến môi trường

### 2. **K6_ENDPOINTS_SUMMARY.md** (Tham Khảo Nhanh)
Tham khảo endpoint cô đọng với hình dạng dữ liệu để tra cứu ngay lập tức.

**Nội dung:**
- Tất cả endpoint dưới dạng bảng (method, path, auth, rate limit)
- Module Authentication (register, login, refresh, profile)
- Module Listings (CRUD, kiểm duyệt, upload media)
- Module Payments (create, list, callback, refund)
- Module Search (full-text, geo)
- Ví dụ request/response body (JSON)
- Các kịch bản test K6 (search, auth, listings, payments, webhook)
- Tóm tắt rate limit
- Ví dụ luồng xác thực (cookies vs tokens)

**Khi nào sử dụng:** Tra cứu nhanh chi tiết endpoint, sao chép payload mẫu, hiểu rate limit

### 3. **K6_QUICK_START.md** (Ví Dụ Chạy Được)
Hướng dẫn từng bước với script K6 sẵn sàng chạy và hướng dẫn thiết lập.

**Nội dung:**
- Hướng dẫn cài đặt (macOS, Linux, Docker)
- Thiết lập môi trường (khởi động API, seed database)
- Năm script K6 chạy được:
  - Search load test (công khai, lưu lượng cao)
  - Auth load test (đăng ký bị giới hạn rate)
  - Tạo listing (đã xác thực, giới hạn quota)
  - Xử lý payment (đã xác thực)
  - Tất cả kịch bản kết hợp
- Tích hợp CI với GitHub Actions
- Tùy chọn tạo báo cáo (JSON, Grafana Cloud, CSV)
- Các check K6 và mẫu phổ biến
- Debug và xử lý sự cố

**Khi nào sử dụng:** Bắt đầu nhanh, chạy test ngay, thiết lập CI/CD

---

## 🚀 Bắt Đầu Nhanh (3 Phút)

### 1. Cài Đặt K6
```bash
brew install k6  # macOS
# or
apt-get install k6  # Linux
```

### 2. Khởi Động API & Database
```bash
pnpm install
pnpm db:generate
pnpm db:migrate:dev
pnpm db:seed
pnpm dev
```

### 3. Chạy Load Test
```bash
# Copy this from K6_QUICK_START.md Step 3
k6 run load-tests/search.k6.js
```

### 4. Xem Kết Quả
K6 in tóm tắt ra console. Để xem báo cáo chi tiết hơn, xem mục tạo báo cáo trong K6_QUICK_START.md.

---

## 📊 Các Kịch Bản Test Đã Triển Khai

| Kịch Bản | File | Trọng Tâm | VUs | Thời Lượng | Endpoint Chính |
|----------|------|-------|-----|----------|--------------|
| Search Load | `load-tests/search.k6.js` | Hiệu suất tìm kiếm công khai | 50 | 4m | `GET /search`, `GET /search/geo` |
| Authentication | `load-tests/auth.k6.js` | Throughput auth & rate limit | 10 | 2m | `POST /auth/register`, `POST /auth/login` |
| Tạo Listing | `load-tests/listings.k6.js` | CRUD listing đã xác thực | 5 | 2m | `POST /listings`, `GET /listings/:id` |
| Payments | `load-tests/payments.k6.js` | Khởi tạo & trạng thái thanh toán | 10 | 2m | `POST /payments`, `GET /payments/:id` |
| Combined | `load-tests/all-scenarios.k6.js` | Tải hỗn hợp thực tế | 50 | 5m | Nhiều endpoint |

---

## 🔐 Phương Thức Xác Thực

### Tùy Chọn 1: Dựa Trên Cookie (Khuyến nghị cho test giống trình duyệt)
```javascript
const loginRes = http.post(`${BASE_URL}/auth/login`, { phone, password });
// Cookies automatically managed by K6
const profileRes = http.get(`${BASE_URL}/auth/profile`);
```

### Tùy Chọn 2: Bearer Token (Khuyến nghị cho test chỉ API)
```javascript
const loginRes = http.post(`${BASE_URL}/auth/login`, { phone, password });
const { accessToken } = loginRes.json();
const headers = { Authorization: `Bearer ${accessToken}` };
const profileRes = http.get(`${BASE_URL}/auth/profile`, { headers });
```

Xem K6_ENDPOINTS_SUMMARY.md để xem ví dụ đầy đủ.

---

## 🎯 Endpoint Chính Theo Mức Ưu Tiên

### Ưu Tiên Cao (Chức Năng Cốt Lõi)
| Endpoint | Ưu Tiên | Tại sao |
|----------|----------|-----|
| `GET /search` | ⭐⭐⭐ | Công khai, truy vấn lưu lượng cao |
| `GET /search/geo` | ⭐⭐⭐ | Địa không gian, dùng thường xuyên |
| `GET /listings` | ⭐⭐⭐ | Tìm/lọc công khai |
| `GET /listings/:id` | ⭐⭐⭐ | Tải trang chi tiết |
| `POST /auth/login` | ⭐⭐ | Tạo phiên người dùng |
| `POST /auth/register` | ⭐⭐ | Bị giới hạn rate, quan trọng |

### Ưu Tiên Trung Bình (Tính Năng Cụ Thể)
| Endpoint | Ưu Tiên | Tại sao |
|----------|----------|-----|
| `POST /listings` | ⭐⭐ | Bị giới hạn quota, đã xác thực |
| `POST /payments` | ⭐⭐ | Tích hợp bên ngoài |
| `GET /payments` | ⭐⭐ | Lịch sử giao dịch người dùng |
| `POST /payments/callback/:provider` | ⭐⭐ | Webhook handler, then chốt |

### Ưu Tiên Thấp (Admin/Chuyên Biệt)
| Endpoint | Ưu Tiên | Tại sao |
|----------|----------|-----|
| `PATCH /listings/:id/moderate` | ⭐ | Chỉ admin |
| `GET /listings/pending` | ⭐ | Chỉ admin |
| `POST /search/reindex` | ⭐ | Chỉ admin, có lịch |

---

## 📍 Tổng Quan Cấu Trúc API

```
API Base: http://localhost:3001/api/v1

Modules:
├── /auth               # User authentication & profiles
├── /listings           # Property CRUD & moderation
├── /search             # Full-text & geo search
├── /payments           # Payment processing & webhooks
├── /subscriptions      # Plans & quotas (not focused for load tests)
├── /admin              # Admin operations (low priority for load tests)
└── /analytics          # Market data (low priority for load tests)
```

---

## 🗄️ Cấu Hình Database

### Phát Triển Cục Bộ
```bash
DATABASE_URL=postgresql://goodgo:password@localhost:5432/goodgo
REDIS_URL=redis://localhost:6379
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
```

### Môi Trường Test (CI)
```bash
DATABASE_URL=postgresql://goodgo:goodgo_test_secret@localhost:5432/goodgo_test
REDIS_URL=redis://localhost:6379
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
```

Xem K6_LOAD_TESTING_GUIDE.md để biết đầy đủ biến môi trường.

---

## ⚡ Rate Limit

Tôn trọng các giới hạn này trong load test của bạn:

| Endpoint | Limit | Cửa Sổ | Hành Động Khi Vượt |
|----------|-------|--------|-------------------|
| `/auth/register` | 5 | mỗi giờ | Trả về 429 |
| `/auth/login` | 5 | mỗi giờ | Trả về 429 |
| `/auth/refresh` | 5 | mỗi giờ | Trả về 429 |
| `/payments/callback/*` | 20 | mỗi phút | Trả về 429 |
| Tất cả khác | Không có | N/A | Quota gate áp dụng cho thao tác ghi |

**Xử Lý K6:**
```javascript
check(res, {
  'status not rate limited': (r) => r.status !== 429,
  'status success or expected': (r) => [200, 201, 400, 404].includes(r.status),
});
```

---

## 🏗️ Cấu Trúc Test Đề Xuất

```
load-tests/
├── search.k6.js              # High-volume public search
├── auth.k6.js                # Authentication flow with rate limit handling
├── listings.k6.js            # Authenticated listing creation
├── payments.k6.js            # Payment processing
├── all-scenarios.k6.js       # Combined realistic mix
├── helpers/
│   ├── data-generators.js    # Generate test data (users, listings)
│   ├── auth-flows.js         # Reusable login/register functions
│   └── assertions.js         # Custom check functions
└── config.js                 # Base URL, env, thresholds
```

Cấu trúc helper mẫu được cung cấp trong K6_QUICK_START.md.

---

## 🧪 Tích Hợp Với Các Test Hiện Có

### Bổ Sung, Không Thay Thế

K6 dành cho **load testing** (hiệu suất dưới tải đồng thời).
Các test hiện có phục vụ các mục đích khác:

| Loại Test | Công Cụ | Mục Đích | Khi Nào |
|-----------|------|---------|------|
| Unit Tests | Vitest | Xác minh logic hàm | Trong quá trình phát triển |
| E2E Tests | Playwright | Xác minh luồng người dùng hoạt động | Trước khi triển khai |
| Load Tests | K6 | Xác minh hiệu suất ở quy mô lớn | Theo lịch, theo yêu cầu |

### Chạy Tất Cả Test

```bash
# Unit tests (API only)
pnpm test

# E2E tests (API + Web)
pnpm test:e2e

# Load tests (new)
k6 run load-tests/search.k6.js

# All in sequence
pnpm test && pnpm test:e2e && k6 run load-tests/all-scenarios.k6.js
```

---

## 📈 Tích Hợp CI/CD

### Workflow GitHub Actions

Tạo `.github/workflows/load-test.yml` (mẫu trong K6_QUICK_START.md mục 🔟):

```bash
# Runs on schedule (daily at 2 AM)
# Or manually via workflow_dispatch
# Reports results as artifacts
```

### Báo Cáo Thủ Công

```bash
# Export JSON
k6 run load-tests/search.k6.js --summary-export=results.json

# View CSV (with extension)
k6 run load-tests/search.k6.js --out csv=results.csv

# Upload to Grafana Cloud
K6_CLOUD_TOKEN=xxx k6 run load-tests/search.k6.js --out cloud
```

---

## 🔗 Hướng Dẫn Tham Chiếu Chéo

### Đang tìm kiếm...?

| Cần | Tìm trong |
|------|----------|
| Tất cả URL & method endpoint | K6_ENDPOINTS_SUMMARY.md |
| Hình dạng JSON request/response | K6_ENDPOINTS_SUMMARY.md (📊 Key Data Shapes) |
| DTO & quy tắc validation | K6_LOAD_TESTING_GUIDE.md (Controllers & DTOs) |
| Chi tiết rate limit | K6_ENDPOINTS_SUMMARY.md (📌 Important Rate Limits) |
| Luồng xác thực | K6_ENDPOINTS_SUMMARY.md (🔗 Authentication Flow for K6) |
| Biến database | K6_LOAD_TESTING_GUIDE.md (🗄️ Database & Environment) |
| Script sẵn sàng chạy | K6_QUICK_START.md (Steps 3-8️⃣) |
| Thiết lập CI/CD | K6_QUICK_START.md (Step 🔟) |
| Xử lý sự cố | K6_QUICK_START.md (✅ Troubleshooting) |
| Chi tiết kiến trúc | K6_LOAD_TESTING_GUIDE.md (📊 Architecture Patterns) |
| Vị trí file | K6_LOAD_TESTING_GUIDE.md (📁 File Locations Quick Reference) |

---

## 🛠️ Công Việc Phổ Biến

### Công Việc: Load Test Endpoint Search
1. Đọc: K6_ENDPOINTS_SUMMARY.md (mục 🔍 Search)
2. Sử dụng: K6_QUICK_START.md (Bước 3️⃣ - Search Load Test)
3. Chạy: `k6 run load-tests/search.k6.js`

### Công Việc: Hiểu Luồng Payment
1. Đọc: K6_LOAD_TESTING_GUIDE.md (💳 PAYMENTS MODULE)
2. Kiểm tra: K6_ENDPOINTS_SUMMARY.md (mục 💳 Payments)
3. Sử dụng: K6_QUICK_START.md (Bước 7️⃣ - Payment Test)

### Công Việc: Thêm Endpoint Mới Vào Load Tests
1. Tìm endpoint trong: K6_LOAD_TESTING_GUIDE.md hoặc K6_ENDPOINTS_SUMMARY.md
2. Lấy hình dạng dữ liệu từ: K6_ENDPOINTS_SUMMARY.md (📊 Key Data Shapes)
3. Kiểm tra auth từ: K6_LOAD_TESTING_GUIDE.md (mỗi mục module)
4. Triển khai sử dụng ví dụ trong: K6_QUICK_START.md

---

## ✅ Danh Sách Kiểm Tra Xác Minh

Trước khi chạy load test, hãy xác minh:

- [ ] API đang chạy: `pnpm dev` (port 3001)
- [ ] Database đã seed: `pnpm db:seed`
- [ ] K6 đã cài đặt: `k6 version`
- [ ] Có thể truy cập API: `curl http://localhost:3001/api/v1/docs`
- [ ] Biến ENV đã set: `JWT_SECRET`, `CORS_ORIGINS`, v.v.
- [ ] File load test tồn tại: `load-tests/*.k6.js`
- [ ] Có sẵn dữ liệu test: Kiểm tra seed trong `prisma/seed.ts`

---

## 📞 Hỗ Trợ & Tham Khảo

### Tài Liệu Nội Bộ
- **Kiến Trúc Đầy Đủ**: K6_LOAD_TESTING_GUIDE.md
- **Tham Khảo Endpoint**: K6_ENDPOINTS_SUMMARY.md
- **Bắt Đầu**: K6_QUICK_START.md

### Tài Nguyên Bên Ngoài
- **Tài Liệu Chính Thức K6**: https://k6.io/docs
- **Tham Khảo K6 API**: https://k6.io/docs/javascript-api
- **Cộng Đồng K6**: https://community.k6.io
- **Ví Dụ K6**: https://github.com/grafana/k6-templates

### File Dự Án
- **API Controllers**: `apps/api/src/modules/*/presentation/controllers/`
- **DTOs**: `apps/api/src/modules/*/presentation/dto/`
- **E2E Tests**: `e2e/api/`
- **Seed Data**: `prisma/seed.ts`

---

## 🎓 Lộ Trình Học

### Người Mới Bắt Đầu (30 phút)
1. Đọc K6_QUICK_START.md (Bước 1-4)
2. Cài đặt K6
3. Chạy: `k6 run load-tests/search.k6.js`

### Trung Cấp (1-2 giờ)
1. Đọc K6_ENDPOINTS_SUMMARY.md
2. Hiểu luồng auth
3. Chạy test auth: `k6 run load-tests/auth.k6.js`
4. Chạy test listing: `k6 run load-tests/listings.k6.js`

### Nâng Cao (2-4 giờ)
1. Đọc K6_LOAD_TESTING_GUIDE.md đầy đủ
2. Xem xét triển khai controller trong source
3. Tạo script load test tùy chỉnh
4. Thiết lập CI/CD với GitHub Actions (K6_QUICK_START.md Bước 🔟)
5. Tạo và phân tích báo cáo

---

## 📝 Ghi Chú

- **Chưa có thiết lập K6 nào** — Tài liệu này cung cấp hướng dẫn đầy đủ
- **Ba tài liệu bổ sung cho nhau** — Khám phá các tài liệu khác nhau cho các nhu cầu khác nhau
- **Ví dụ chạy được** — Script K6_QUICK_START.md hoạt động ngay
- **Rate limit quan trọng** — Hãy xem xét chúng trong thiết kế test
- **Quota gate** — Một số thao tác (listings, payments) bị giới hạn theo subscription
- **Dữ liệu test** — Sử dụng dữ liệu seed hoặc tạo người dùng test duy nhất cho mỗi VU
- **Sẵn sàng cho production** — Hướng dẫn tuân theo các thực hành tốt nhất của K6

---

Đã tạo: 2026-04-09
Cập nhật lần cuối: K6_QUICK_START.md mới nhất