goodgo-platform/docs/audits/INFRASTRUCTURE_QUICK_REFERENCE.md

# GoodGo Platform — Tài Liệu Tham Khảo Nhanh về Cơ Sở Hạ Tầng

## 🚀 Khởi Động Nhanh

```bash
# Phát triển
docker compose up -d --wait

# Sản xuất
docker compose -f docker-compose.prod.yml up -d --wait

# CI/E2E
docker compose -f docker-compose.ci.yml up -d --wait
```

## 📊 Bản Đồ Dịch Vụ (Dev)

| Dịch Vụ | Cổng | Kiểm Tra Sức Khỏe | Trạng Thái |
|---------|------|--------|--------|
| **API (NestJS)** | 3001 | GET /health | 🟢 |
| **Web (Next.js)** | 3000 | GET / | 🟢 |
| **AI Services (Python)** | 8000 | GET /health | 🟢 |
| **PostgreSQL + PostGIS** | 5432 | pg_isready | 🟢 |
| **Redis** | 6379 | PING | 🟢 |
| **Typesense** | 8108 | GET /health | 🟢 |
| **MinIO** | 9000 | mc ready local | 🟢 |
| **Prometheus** | 9090 | GET /-/healthy | 🟢 |
| **Grafana** | 3002 | GET /api/health | 🟢 |
| **Loki** | 3100 | GET /ready | 🟢 |
| **Promtail** | 9080 | (thụ động) | 🟢 |

## 📊 Bản Đồ Dịch Vụ (Prod)

Giống như dev, cộng thêm **PgBouncer** (6432) để gộp kết nối.

## 🗄️ Cơ Sở Dữ Liệu

- **Loại:** PostgreSQL 16 + PostGIS
- **Schema:** 22 mô hình Prisma
- **Sao lưu:** Hằng ngày lúc 02:00 UTC, lưu giữ 7 ngày
- **Gộp Kết Nối (Prod):** PgBouncer (chế độ giao dịch, 20 kết nối)
- **Xác minh:** Kiểm tra khôi phục tự động hàng tuần

**Các Bảng Chính:**
- User, RefreshToken, OAuthAccount, Agent
- Property, PropertyMedia, Listing
- SavedSearch, Transaction, Inquiry, Lead
- Payment (VNPAY/MOMO/ZALOPAY/BANK_TRANSFER)
- Plan, Subscription, UsageRecord
- Valuation, MarketIndex, NotificationLog, AdminAuditLog, Review

## 💾 Bộ Nhớ Đệm & Tìm Kiếm

- **Redis:** 512MB (prod), 256MB (dev), lưu trữ AOF, loại bỏ LRU
- **Typesense:** Tìm kiếm toàn văn bản trên các danh sách, hỗ trợ lập chỉ mục địa lý

## 📈 Giám Sát

- **Prometheus:** Lưu giữ 30 ngày (prod), 15 ngày (dev)
- **Grafana:** Bảng điều khiển được cấu hình sẵn (7 bảng)
- **Loki:** Lưu giữ nhật ký 15 ngày, phân tích cú pháp JSON Pino
- **Cảnh báo:** Độ trễ p99 > 1s (cảnh báo), > 3s (nghiêm trọng), 5xx > 1%

## 💳 Tích Hợp Thanh Toán

| Cổng Thanh Toán | Nhà Cung Cấp | Theo Dõi Trạng Thái | Xác Minh Callback |
|---------|----------|-----------------|----------------------|
| VNPay | VNPAY | ✅ | HMAC SHA-256 |
| MoMo | MOMO | ✅ | HMAC |
| ZaloPay | ZALOPAY | ✅ | Key 1/2 |
| Bank Transfer | BANK_TRANSFER | Thủ công | N/A |

**Trình Xử Lý Callback:**
- Idempotent (mẫu updateIfStatus)
- Chuyển trạng thái nguyên tử (PENDING → COMPLETED/FAILED)
- Xuất bản sự kiện miền (kích hoạt các hành động tiếp theo)

## 🏥 Kiểm Tra Sức Khỏe

```bash
GET /health          # Liveness (luôn 200)
GET /health/ready    # Readiness (kiểm tra DB + Redis)
GET /health/db       # Chỉ cơ sở dữ liệu
GET /health/redis    # Chỉ Redis
```

## 🔐 Biến Môi Trường (Quan Trọng)

```env
# Cơ sở dữ liệu
DB_USER=goodgo
DB_PASSWORD=<required>
DATABASE_URL_DIRECT=postgresql://...  # For migrations

# Redis (Prod yêu cầu mật khẩu)
REDIS_PASSWORD=<required-in-prod>

# Typesense API Key
TYPESENSE_API_KEY=<required>

# JWT Secrets (BẮT BUỘC, tối thiểu 32 ký tự)
JWT_SECRET=<openssl rand -base64 48>
JWT_REFRESH_SECRET=<openssl rand -base64 48>

# KYC Encryption (Chỉ Prod)
KYC_ENCRYPTION_KEY=<openssl rand -hex 32>  # 64 hex chars

# Cổng Thanh Toán (tùy chọn nếu bị tắt)
VNPAY_TMN_CODE=
MOMO_PARTNER_CODE=
ZALOPAY_APP_ID=
```

## 📦 Triển Khai

**Container:**
- `goodgo-api:${IMAGE_TAG}` — NestJS API
- `goodgo-web:${IMAGE_TAG}` — Next.js Frontend
- `goodgo-ai-services:${IMAGE_TAG}` — Python FastAPI

**Registry:** `ghcr.io/goodgo/`

**CI/CD:** GitHub Actions
- **ci.yml** — Kiểm tra, build, lint khi push
- **deploy.yml** — Build image, triển khai lên staging (tự động) hoặc prod (thủ công)
- **backup-verify.yml** — Xác minh khôi phục hàng tuần
- **e2e.yml** — Bộ kiểm thử đầu cuối

## 🆘 Khắc Phục Sự Cố

**API không hoạt động bình thường?**
```bash
docker compose exec api curl http://localhost:3001/health/ready
docker compose logs api --tail=50
```

**Gộp kết nối cơ sở dữ liệu đầy?**
```bash
docker compose exec pgbouncer psql -h 127.0.0.1 -p 6432 -U pgbouncer_stats -c "SHOW stats"
```

**Redis ngừng hoạt động?**
```bash
docker compose exec redis redis-cli ping
# Ứng dụng vẫn tiếp tục chạy (dự phòng DB), nhưng chậm hơn
```

**Typesense không lập chỉ mục?**
```bash
curl http://localhost:8108/collections/listings -H "X-TYPESENSE-API-KEY: ${KEY}"
# Lập chỉ mục lại: docker compose exec api npx ts-node scripts/reindex-listings.ts
```

**Callback thanh toán thất bại?**
```bash
docker compose logs api | grep -i callback
# Kiểm tra VNPAY_HASH_SECRET / MOMO_SECRET_KEY / ZALOPAY_KEY1
```

**Sao lưu bị kẹt?**
```bash
docker compose exec pg-backup bash -c "tail -f /var/log/pg-backup.log"
docker compose exec postgres psql -U goodgo -d goodgo -c "SELECT * FROM pg_stat_activity WHERE wait_event_type IS NOT NULL;"
```

## 📝 Các Tệp Quan Trọng

| Đường Dẫn | Mục Đích |
|------|---------|
| `docker-compose.yml` | Dev (không giới hạn tài nguyên, tất cả dịch vụ) |
| `docker-compose.prod.yml` | Prod (PgBouncer, giới hạn, bí mật) |
| `docker-compose.ci.yml` | Kiểm thử (tmpfs, dịch vụ tối thiểu) |
| `INFRASTRUCTURE_RUNBOOK.md` | Tài liệu đầy đủ (tệp đồng hành) |
| `prisma/schema.prisma` | Mô hình dữ liệu hoàn chỉnh |
| `infra/pgbouncer/pgbouncer.ini` | Cấu hình gộp kết nối |
| `monitoring/prometheus/alert-rules.yml` | Định nghĩa cảnh báo |
| `scripts/backup/pg-backup.sh` | Tự động hóa sao lưu hàng ngày |
| `scripts/backup/pg-verify-backup.sh` | Xác minh khôi phục |
| `.github/workflows/*.yml` | Pipeline CI/CD |

## 🔗 Liên Kết

- **Grafana:** http://localhost:3002 (admin/admin)
- **Prometheus:** http://localhost:9090
- **MinIO Console:** http://localhost:9001
- **API Docs:** http://localhost:3001/api (nếu Swagger được bật)
- **Frontend:** http://localhost:3000

## 📞 Lệnh Thường Dùng

```bash
# Xem tất cả dịch vụ
docker compose ps

# Theo dõi nhật ký
docker compose logs -f api web postgres redis

# Thực thi lệnh trong container
docker compose exec api npx prisma db push
docker compose exec postgres psql -U goodgo -d goodgo

# Khởi động lại một dịch vụ
docker compose restart api

# Dọn dẹp hoàn toàn (chỉ dev!)
docker compose down -v && docker compose up -d --wait

# Sao lưu & khôi phục cơ sở dữ liệu
docker compose exec postgres pg_dump -U goodgo -d goodgo | gzip > backup.sql.gz
docker compose exec postgres pg_restore -U goodgo -d goodgo backup.sql.gz

# Kiểm tra endpoint sức khỏe
curl http://localhost:3001/health/ready | jq
curl http://localhost:3001/health/db | jq
curl http://localhost:3001/health/redis | jq
```

---

**Để biết thêm thông tin chi tiết, xem `INFRASTRUCTURE_RUNBOOK.md`**

Cập nhật lần cuối: ngày 11 tháng 4 năm 2026