d8b409a9ab
Some checks failed
CI / Lint → Typecheck → Test → Build (22) (push) Failing after 18s
CI / E2E Tests (push) Has been skipped
CodeQL Analysis / CodeQL (javascript-typescript) (push) Failing after 2m15s
Deploy / Build API Image (push) Failing after 28s
Deploy / Build Web Image (push) Failing after 16s
Deploy / Build AI Services Image (push) Failing after 17s
E2E Tests / Playwright E2E (push) Failing after 31s
Security Scanning / Dependency Audit (pnpm) (push) Failing after 3s
Security Scanning / Trivy Scan — API Image (push) Failing after 1m46s
Security Scanning / Trivy Scan — Web Image (push) Failing after 1m7s
Security Scanning / Trivy Scan — AI Services Image (push) Failing after 53s
Security Scanning / Trivy Filesystem Scan (push) Failing after 35s
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
Security Scanning / Security Gate (push) Failing after 0s
Deploy / Rollback Staging (push) Has been skipped
Deploy / Rollback Production (push) Has been skipped
Hoàn tất đợt cuối của nhiệm vụ chuyển toàn bộ tài liệu sang tiếng Việt. Đã dịch 22 file `.md` còn sót (~9.7k dòng) — gồm RUNBOOK, audits, docs/architecture, docs/load-testing, libs READMEs và các quick references. Giữ nguyên code blocks, đường dẫn, identifier kỹ thuật, URL và biến môi trường. Co-Authored-By: Paperclip <noreply@paperclip.ing>
426 lines
13 KiB
Markdown
426 lines
13 KiB
Markdown
# GoodGo Platform — Tham Khảo Nhanh
|
|
|
|
**Trạng thái:** MVP Hoàn Tất (Phase 7 Wave 14) ✅
|
|
**Ngày tạo:** 12 tháng 4, 2026
|
|
|
|
---
|
|
|
|
## 📊 MỨC ĐỘ HOÀN THIỆN DỰ ÁN
|
|
|
|
| Hạng mục | Đánh giá | Chi tiết |
|
|
|----------|--------|---------|
|
|
| **Hoàn thiện tính năng** | 🟢 95% | Tất cả tính năng MVP xong; còn 3 edge case |
|
|
| **Chất lượng code** | 🟢 Cao | 242 test, ESLint pass, kiến trúc DDD |
|
|
| **Bảo mật** | 🟢 Hardened | JWT/MFA, mã hóa, rate limiting, bảo vệ CSRF |
|
|
| **Tài liệu** | 🟢 Toàn diện | 80+ file audit, runbook, tham khảo API |
|
|
| **Hiệu năng** | 🟢 Đã tối ưu | Cache, indexing, K6 load test baseline |
|
|
| **Sẵn sàng vận hành** | 🟢 Sẵn sàng | Docker/Kubernetes, monitoring, chiến lược backup |
|
|
|
|
**Tổng thể:** ✅ **Sẵn sàng Production** — Sẵn sàng launch với 3 fix nhỏ
|
|
|
|
---
|
|
|
|
## 🏗️ KIẾN TRÚC TỔNG QUAN
|
|
|
|
```
|
|
Frontend Backend Database
|
|
───────── ──────── ────────
|
|
Next.js 15 NestJS 11 PostgreSQL 16
|
|
React 18 (18 modules) + PostGIS
|
|
Tailwind CSS DDD/CQRS pattern 31 entities
|
|
Shadcn/ui 100+ endpoints 30+ indexes
|
|
|
|
┌──────────────────┐
|
|
│ Shared Layer │
|
|
│ (Encryption, │
|
|
│ Logger, Events) │
|
|
└──────────────────┘
|
|
|
|
Cache Search File Storage
|
|
───── ────── ────────────
|
|
Redis 5.4 Typesense 3.0 AWS S3
|
|
ioredis Full-text + geo Pre-signed URLs
|
|
```
|
|
|
|
---
|
|
|
|
## 📦 THỐNG KÊ CHÍNH
|
|
|
|
```
|
|
Code: ~50,000 LOC
|
|
Backend: 845 file TypeScript (18 module)
|
|
Frontend: 245 file TypeScript/TSX
|
|
Database: 31 model, 30+ index, 7+ migration
|
|
Tests: 242 file (unit + E2E + load)
|
|
API: 100+ endpoint (đã tài liệu Swagger)
|
|
Deployment: Sẵn sàng Docker + Kubernetes
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 LỆNH KHỞI ĐỘNG NHANH
|
|
|
|
### Phát Triển Local
|
|
```bash
|
|
# Cài đặt và khởi động tất cả
|
|
docker-compose up -d
|
|
|
|
# Phát triển API
|
|
cd apps/api
|
|
pnpm dev # Chế độ watch ở :3001
|
|
|
|
# Phát triển frontend
|
|
cd apps/web
|
|
pnpm dev # Dev server ở :3000
|
|
|
|
# Cả hai cùng lúc (từ root)
|
|
pnpm dev # Tất cả app qua Turbo
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
pnpm test # Tất cả unit test
|
|
pnpm test:e2e # Tất cả E2E test (Playwright)
|
|
pnpm test:e2e:web # Chỉ E2E web
|
|
pnpm test:e2e:api # Chỉ E2E API
|
|
pnpm test:e2e:report # Xem report Playwright
|
|
```
|
|
|
|
### Database
|
|
```bash
|
|
pnpm db:generate # Sinh lại Prisma client
|
|
pnpm db:migrate:dev # Tạo và áp dụng migration
|
|
pnpm db:push # Push schema (chỉ dev)
|
|
pnpm db:seed # Seed dữ liệu test
|
|
pnpm db:studio # UI Prisma Studio (localhost:5555)
|
|
```
|
|
|
|
### Chất Lượng
|
|
```bash
|
|
pnpm lint # Kiểm tra ESLint
|
|
pnpm format:check # Kiểm tra Prettier
|
|
pnpm format # Tự format tất cả file
|
|
pnpm typecheck # Kiểm tra TypeScript
|
|
pnpm dep-cruise # Validate kiến trúc
|
|
```
|
|
|
|
### Build & Deployment
|
|
```bash
|
|
pnpm build # Build API + frontend
|
|
pnpm start # Chạy production server
|
|
|
|
# Docker production
|
|
docker-compose -f docker-compose.prod.yml up -d
|
|
```
|
|
|
|
---
|
|
|
|
## 📁 FILE QUAN TRỌNG CẦN BIẾT
|
|
|
|
### Lập Kế Hoạch & Trạng Thái
|
|
- **PROJECT_TRACKER.md** — Cả 7 phase, 40+ issue, trạng thái hiện tại
|
|
- **IMPLEMENTATION_PLAN.md** — Roadmap tính năng theo ưu tiên
|
|
- **CODEBASE_OVERVIEW.md** — Hướng dẫn toàn diện (vừa được tạo!)
|
|
|
|
### Kiến Trúc & Thiết Kế
|
|
- **docs/architecture.md** — Tầng DDD, ranh giới module, CQRS
|
|
- **docs/api-endpoints.md** — Tất cả endpoint kèm ví dụ
|
|
- **docs/api-error-codes.md** — Phân loại lỗi và xử lý
|
|
|
|
### Kỹ Thuật
|
|
- **prisma/schema.prisma** — Model database đầy đủ (31 entity)
|
|
- **apps/api/src/modules/** — 18 module tính năng (auth, listings, payments, v.v.)
|
|
- **apps/web/app/** — Route và group page Next.js
|
|
- **apps/web/components/** — UI component (16 thư mục)
|
|
|
|
### Vận Hành
|
|
- **docs/deployment.md** — Bước Docker, Kubernetes, CI/CD
|
|
- **docs/RUNBOOK.md** — Quy trình vận hành, troubleshooting
|
|
- **docker-compose.yml** — Stack dev local
|
|
- **docker-compose.prod.yml** — Stack production
|
|
|
|
---
|
|
|
|
## 🔧 TỔNG QUAN MODULE API
|
|
|
|
### Authentication (1)
|
|
```
|
|
auth/
|
|
├── JWT + OAuth (Google, Zalo)
|
|
├── MFA/TOTP + backup code
|
|
├── Passport strategy
|
|
└── Quản lý session
|
|
```
|
|
|
|
### Business Logic (5)
|
|
```
|
|
listings/ Bất động sản + upload media + moderation
|
|
search/ Typesense + tìm kiếm địa lý PostGIS
|
|
inquiries/ Tin nhắn buyer-to-seller
|
|
leads/ CRM agent và lead scoring
|
|
reviews/ Đánh giá và review của user
|
|
```
|
|
|
|
### Monetization (2)
|
|
```
|
|
payments/ VNPay, MoMo, ZaloPay + webhook
|
|
subscriptions/ 4 tier (FREE, AGENT_PRO, INVESTOR, ENTERPRISE)
|
|
```
|
|
|
|
### Operations (5)
|
|
```
|
|
agents/ Hồ sơ agent và xác minh
|
|
admin/ Moderation, KYC, audit log
|
|
notifications/ Email, SMS, Push, Zalo OA
|
|
analytics/ Báo cáo thị trường, định giá AI
|
|
metrics/ Prometheus + metric HTTP
|
|
```
|
|
|
|
### Infrastructure (4)
|
|
```
|
|
health/ Liveness/readiness Kubernetes
|
|
shared/ DI, mã hóa, logger, event
|
|
mcp/ Model Context Protocol server
|
|
```
|
|
|
|
---
|
|
|
|
## 💾 MODEL DATABASE (TỔNG 31)
|
|
|
|
### Core (13)
|
|
```
|
|
User Hồ sơ chính + KYC + MFA
|
|
Agent Hồ sơ agent mở rộng
|
|
Property Địa chỉ + vị trí địa lý
|
|
PropertyMedia Hình ảnh/video
|
|
Listing Instance tin đăng bán/cho thuê
|
|
SavedSearch Tùy chọn tìm kiếm của user
|
|
```
|
|
|
|
### Commerce (9)
|
|
```
|
|
Transaction Luồng từ inquiry đến hoàn tất
|
|
Inquiry Câu hỏi buyer trên tin đăng
|
|
Payment Tất cả phương thức thanh toán + lịch sử
|
|
Plan Định nghĩa tier subscription
|
|
Subscription Plan đang active của user
|
|
Order Settlement đấu giá
|
|
Escrow Giữ và giải phóng thanh toán
|
|
Lead Lead CRM agent
|
|
Review Đánh giá user
|
|
```
|
|
|
|
### Operations (9)
|
|
```
|
|
RefreshToken Chuỗi refresh JWT
|
|
OAuthAccount Liên kết OAuth provider
|
|
MfaChallenge Theo dõi xác minh TOTP
|
|
NotificationLog Thông báo đã gửi
|
|
NotificationPref Opt-in/out của user
|
|
AdminAuditLog Audit trail hành động admin
|
|
MarketIndex Thống kê quận/thành phố
|
|
Valuation Ước tính giá AI
|
|
UsageRecord Theo dõi sử dụng subscription
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 PHÂN TÍCH TESTING
|
|
|
|
### Unit Test (Vitest)
|
|
- Payment gateway (VNPay, MoMo, ZaloPay) — ~30 spec
|
|
- Value object (Money, PlatformFee) — ~10 spec
|
|
- Store và utility (Auth, Currency) — ~20 spec
|
|
|
|
### E2E Test (Playwright)
|
|
- **Web (15 test):** auth, listings, search, admin, responsive
|
|
- **API (16 test):** tất cả endpoint chính
|
|
- **Load (K6):** baseline benchmark, stress test 1000 VU
|
|
|
|
**Tổng cộng: 242 file test**
|
|
|
|
---
|
|
|
|
## 🔐 TÍNH NĂNG BẢO MẬT
|
|
|
|
✅ JWT authentication với refresh token
|
|
✅ OAuth2 (Google, Zalo)
|
|
✅ TOTP/MFA với backup code
|
|
✅ Mã hóa cấp field (PII)
|
|
✅ Middleware bảo vệ CSRF
|
|
✅ Rate limiting (toàn cục + theo user)
|
|
✅ HMAC-SHA256 cho verify thanh toán
|
|
✅ Header bảo mật Helmet
|
|
✅ CORS đã cấu hình
|
|
✅ Validate và sanitize input
|
|
|
|
---
|
|
|
|
## 📊 MONITORING & OBSERVABILITY
|
|
|
|
```
|
|
Metric Prometheus + Grafana (dashboard)
|
|
Log Pino (structured) + Loki (tổng hợp)
|
|
Tracing Sentry (theo dõi lỗi)
|
|
Alert AlertManager (đã cấu hình)
|
|
APM Theo dõi Core Web Vitals
|
|
Health Check /health (liveness), /ready (readiness)
|
|
```
|
|
|
|
---
|
|
|
|
## 🚢 LỰA CHỌN DEPLOYMENT
|
|
|
|
### Lựa chọn 1: Docker Compose (Development)
|
|
```bash
|
|
docker-compose up -d
|
|
# Chạy: API (3001), Web (3000), DB, Redis, Typesense, v.v.
|
|
```
|
|
|
|
### Lựa chọn 2: Docker Compose Production
|
|
```bash
|
|
docker-compose -f docker-compose.prod.yml up -d
|
|
# Chạy: Stack đầy đủ với monitoring, logging, connection pooling
|
|
```
|
|
|
|
### Lựa chọn 3: Kubernetes
|
|
- ConfigMap cho biến env
|
|
- Secret cho credential
|
|
- PersistentVolume cho database
|
|
- HPA cho auto-scaling
|
|
- Ingress cho định tuyến traffic
|
|
|
|
**Xem:** `docs/deployment.md` để biết các bước chi tiết
|
|
|
|
---
|
|
|
|
## ⚠️ ISSUE ĐÃ BIẾT (Phase 7 Wave 14)
|
|
|
|
| ID | Tiêu đề | Ưu tiên | Trạng thái |
|
|
|----|-------|----------|--------|
|
|
| TEC-1650 | Xử lý lỗi 404 chi tiết tin đăng | High | todo |
|
|
| TEC-1652 | Validate bộ test E2E đầy đủ | High | todo |
|
|
| TEC-1657 | Audit logging toàn diện | High | todo |
|
|
|
|
**Ảnh hưởng:** Tối thiểu (chỉ edge case)
|
|
**ETA fix:** <2 giờ mỗi cái
|
|
|
|
---
|
|
|
|
## 📚 CẤU TRÚC TÀI LIỆU
|
|
|
|
```
|
|
/
|
|
├── PROJECT_TRACKER.md ← BẮT ĐẦU TỪ ĐÂY cho trạng thái
|
|
├── IMPLEMENTATION_PLAN.md ← Roadmap tính năng
|
|
├── CODEBASE_OVERVIEW.md ← Hướng dẫn toàn diện
|
|
├── ARCHITECTURE_SUMMARY.txt ← Tổng quan trực quan
|
|
└── QUICK_START_REFERENCE.md ← File này
|
|
|
|
/docs/
|
|
├── architecture.md ← Sâu về kỹ thuật
|
|
├── api-endpoints.md ← Tất cả endpoint (Swagger)
|
|
├── api-error-codes.md ← Phân loại lỗi
|
|
├── deployment.md ← Hướng dẫn deploy
|
|
├── dev-environment.md ← Setup local
|
|
├── RUNBOOK.md ← Hướng dẫn vận hành
|
|
├── PRODUCTION_READINESS.md ← Checklist tuân thủ
|
|
└── /audits/ ← 80+ audit triển khai
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 BƯỚC TIẾP THEO
|
|
|
|
1. **Hiểu:** Đọc `PROJECT_TRACKER.md` (5 phút)
|
|
2. **Setup:** Chạy `docker-compose up` (2 phút)
|
|
3. **Khám phá:** Truy cập `http://localhost:3000` (web) & `http://localhost:3001` (API)
|
|
4. **Test:** Chạy `pnpm test:e2e` để validate (5 phút)
|
|
5. **Deploy:** Dùng `docker-compose.prod.yml` hoặc manifest Kubernetes
|
|
|
|
---
|
|
|
|
## 🆘 TROUBLESHOOTING
|
|
|
|
### Port đang được dùng
|
|
```bash
|
|
# Tìm process đang dùng port 3000/3001
|
|
lsof -i :3000
|
|
kill -9 <PID>
|
|
```
|
|
|
|
### Kết nối database thất bại
|
|
```bash
|
|
# Reset database
|
|
pnpm db:reset
|
|
# Re-seed
|
|
pnpm db:seed
|
|
```
|
|
|
|
### Test thất bại
|
|
```bash
|
|
# Xóa cache
|
|
rm -rf .turbo
|
|
# Cài lại
|
|
pnpm install
|
|
# Chạy lại
|
|
pnpm test
|
|
```
|
|
|
|
### Vấn đề Docker
|
|
```bash
|
|
# Reset hoàn toàn
|
|
docker-compose down -v
|
|
docker-compose up --build
|
|
```
|
|
|
|
---
|
|
|
|
## 🎓 LỘ TRÌNH HỌC
|
|
|
|
### Phát Triển Backend
|
|
1. Đọc: `docs/architecture.md`
|
|
2. Khám phá: `apps/api/src/modules/auth` (module đơn giản nhất)
|
|
3. Hiểu: Tầng DDD (presentation → application → domain → infrastructure)
|
|
4. Thực hành: Thêm endpoint mới theo pattern
|
|
|
|
### Phát Triển Frontend
|
|
1. Xem lại: `apps/web/app` (cấu trúc route)
|
|
2. Nghiên cứu: `components/listings` (component phức tạp)
|
|
3. Học: Pattern React Query trong `lib/*-api.ts`
|
|
4. Thực hành: Tạo trang tính năng mới
|
|
|
|
### DevOps
|
|
1. Xem lại: `docker-compose.yml` (kiến trúc)
|
|
2. Nghiên cứu: `.github/workflows` (CI/CD)
|
|
3. Học: `docs/deployment.md` (production)
|
|
4. Thực hành: Deploy lên môi trường staging
|
|
|
|
---
|
|
|
|
## 💡 MẸO HAY
|
|
|
|
- Dùng `pnpm dev` (từ root) để phát triển tất cả app cùng lúc
|
|
- ESLint được cấu hình để bắt vi phạm ranh giới module
|
|
- Prisma Studio (`pnpm db:studio`) rất tuyệt để khám phá dữ liệu
|
|
- Report Playwright có tính tương tác và rất hữu ích
|
|
- PROJECT_TRACKER.md là nguồn sự thật cho trạng thái
|
|
|
|
---
|
|
|
|
## 📞 THAM KHẢO NHANH
|
|
|
|
| Nhu cầu | Lệnh | Vị trí |
|
|
|------|---------|-------|
|
|
| Kiểm tra trạng thái | `cat PROJECT_TRACKER.md` | Root |
|
|
| Chạy test | `pnpm test:e2e` | Root |
|
|
| Xem tài liệu API | `http://localhost:3001/api` | Sau khi khởi động |
|
|
| Xem database | `pnpm db:studio` | Root |
|
|
| Kiểm tra log | Grafana/Loki | Docker |
|
|
| Theo dõi lỗi | Sentry dashboard | Đã cấu hình |
|
|
|
|
---
|
|
|
|
**Cập nhật lần cuối:** 12 tháng 4, 2026
|
|
**Trạng thái dự án:** MVP Hoàn Tất ✅ — Sẵn sàng Production 🚀
|