docs: dịch 22 file Markdown còn lại sang tiếng Việt có dấu (TEC-2881)
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
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>
This commit is contained in:
@@ -1,26 +1,26 @@
|
||||
# GoodGo Platform — Quick Start Reference
|
||||
# GoodGo Platform — Tham Khảo Nhanh
|
||||
|
||||
**Status:** MVP Complete (Phase 7 Wave 14) ✅
|
||||
**Generated:** April 12, 2026
|
||||
**Trạng thái:** MVP Hoàn Tất (Phase 7 Wave 14) ✅
|
||||
**Ngày tạo:** 12 tháng 4, 2026
|
||||
|
||||
---
|
||||
|
||||
## 📊 PROJECT MATURITY AT A GLANCE
|
||||
## 📊 MỨC ĐỘ HOÀN THIỆN DỰ ÁN
|
||||
|
||||
| Category | Rating | Details |
|
||||
| Hạng mục | Đánh giá | Chi tiết |
|
||||
|----------|--------|---------|
|
||||
| **Feature Completeness** | 🟢 95% | All MVP features done; 3 edge cases remaining |
|
||||
| **Code Quality** | 🟢 High | 242 tests, ESLint pass, DDD architecture |
|
||||
| **Security** | 🟢 Hardened | JWT/MFA, encryption, rate limiting, CSRF protection |
|
||||
| **Documentation** | 🟢 Comprehensive | 80+ audit files, runbooks, API reference |
|
||||
| **Performance** | 🟢 Optimized | Caching, indexing, K6 load tests baseline |
|
||||
| **Ops Readiness** | 🟢 Ready | Docker/Kubernetes, monitoring, backup strategy |
|
||||
| **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 |
|
||||
|
||||
**Overall:** ✅ **Production Ready** — Ready to launch with 3 minor fixes
|
||||
**Tổng thể:** ✅ **Sẵn sàng Production** — Sẵn sàng launch với 3 fix nhỏ
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ ARCHITECTURE AT A GLANCE
|
||||
## 🏗️ KIẾN TRÚC TỔNG QUAN
|
||||
|
||||
```
|
||||
Frontend Backend Database
|
||||
@@ -44,312 +44,312 @@ ioredis Full-text + geo Pre-signed URLs
|
||||
|
||||
---
|
||||
|
||||
## 📦 KEY STATISTICS
|
||||
## 📦 THỐNG KÊ CHÍNH
|
||||
|
||||
```
|
||||
Code: ~50,000 LOC
|
||||
Backend: 845 TypeScript files (18 modules)
|
||||
Frontend: 245 TypeScript/TSX files
|
||||
Database: 31 models, 30+ indexes, 7+ migrations
|
||||
Tests: 242 files (unit + E2E + load)
|
||||
API: 100+ endpoints (Swagger documented)
|
||||
Deployment: Docker + Kubernetes ready
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 QUICK START COMMANDS
|
||||
## 🚀 LỆNH KHỞI ĐỘNG NHANH
|
||||
|
||||
### Local Development
|
||||
### Phát Triển Local
|
||||
```bash
|
||||
# Install & start everything
|
||||
# Cài đặt và khởi động tất cả
|
||||
docker-compose up -d
|
||||
|
||||
# API development
|
||||
# Phát triển API
|
||||
cd apps/api
|
||||
pnpm dev # Watch mode on :3001
|
||||
pnpm dev # Chế độ watch ở :3001
|
||||
|
||||
# Frontend development
|
||||
# Phát triển frontend
|
||||
cd apps/web
|
||||
pnpm dev # Dev server on :3000
|
||||
pnpm dev # Dev server ở :3000
|
||||
|
||||
# Both together (from root)
|
||||
pnpm dev # All apps via Turbo
|
||||
# Cả hai cùng lúc (từ root)
|
||||
pnpm dev # Tất cả app qua Turbo
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
pnpm test # All unit tests
|
||||
pnpm test:e2e # All E2E tests (Playwright)
|
||||
pnpm test:e2e:web # Just web E2E
|
||||
pnpm test:e2e:api # Just API E2E
|
||||
pnpm test:e2e:report # View Playwright report
|
||||
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 # Regenerate Prisma client
|
||||
pnpm db:migrate:dev # Create & apply migration
|
||||
pnpm db:push # Push schema (dev only)
|
||||
pnpm db:seed # Seed test data
|
||||
pnpm db:studio # Prisma Studio UI (localhost:5555)
|
||||
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)
|
||||
```
|
||||
|
||||
### Quality
|
||||
### Chất Lượng
|
||||
```bash
|
||||
pnpm lint # ESLint check
|
||||
pnpm format:check # Prettier check
|
||||
pnpm format # Auto-format all files
|
||||
pnpm typecheck # TypeScript check
|
||||
pnpm dep-cruise # Architecture validation
|
||||
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 # Start production server
|
||||
pnpm start # Chạy production server
|
||||
|
||||
# Production Docker
|
||||
# Docker production
|
||||
docker-compose -f docker-compose.prod.yml up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 KEY FILES TO KNOW
|
||||
## 📁 FILE QUAN TRỌNG CẦN BIẾT
|
||||
|
||||
### Planning & Status
|
||||
- **PROJECT_TRACKER.md** — All 7 phases, 40+ issues, current status
|
||||
- **IMPLEMENTATION_PLAN.md** — Feature roadmap with priority
|
||||
- **CODEBASE_OVERVIEW.md** — Comprehensive guide (this was just created!)
|
||||
### 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!)
|
||||
|
||||
### Architecture & Design
|
||||
- **docs/architecture.md** — DDD layers, module boundaries, CQRS
|
||||
- **docs/api-endpoints.md** — All endpoints with examples
|
||||
- **docs/api-error-codes.md** — Error taxonomy & handling
|
||||
### 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ý
|
||||
|
||||
### Technical
|
||||
- **prisma/schema.prisma** — Full database model (31 entities)
|
||||
- **apps/api/src/modules/** — 18 feature modules (auth, listings, payments, etc.)
|
||||
- **apps/web/app/** — Next.js routes & page groups
|
||||
- **apps/web/components/** — UI components (16 directories)
|
||||
### 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)
|
||||
|
||||
### Operations
|
||||
- **docs/deployment.md** — Docker, Kubernetes, CI/CD steps
|
||||
- **docs/RUNBOOK.md** — Operational procedures, troubleshooting
|
||||
- **docker-compose.yml** — Local dev stack
|
||||
- **docker-compose.prod.yml** — Production stack
|
||||
### 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
|
||||
|
||||
---
|
||||
|
||||
## 🔧 API MODULES OVERVIEW
|
||||
## 🔧 TỔNG QUAN MODULE API
|
||||
|
||||
### Authentication (1)
|
||||
```
|
||||
auth/
|
||||
├── JWT + OAuth (Google, Zalo)
|
||||
├── MFA/TOTP + backup codes
|
||||
├── Passport strategies
|
||||
└── Session management
|
||||
├── MFA/TOTP + backup code
|
||||
├── Passport strategy
|
||||
└── Quản lý session
|
||||
```
|
||||
|
||||
### Business Logic (5)
|
||||
```
|
||||
listings/ Properties + media upload + moderation
|
||||
search/ Typesense + PostGIS geo-search
|
||||
inquiries/ Buyer-to-seller messages
|
||||
leads/ Agent CRM & lead scoring
|
||||
reviews/ User ratings & reviews
|
||||
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 + webhooks
|
||||
subscriptions/ 4 tiers (FREE, AGENT_PRO, INVESTOR, ENTERPRISE)
|
||||
payments/ VNPay, MoMo, ZaloPay + webhook
|
||||
subscriptions/ 4 tier (FREE, AGENT_PRO, INVESTOR, ENTERPRISE)
|
||||
```
|
||||
|
||||
### Operations (5)
|
||||
```
|
||||
agents/ Agent profiles & verification
|
||||
admin/ Moderation, KYC, audit logs
|
||||
agents/ Hồ sơ agent và xác minh
|
||||
admin/ Moderation, KYC, audit log
|
||||
notifications/ Email, SMS, Push, Zalo OA
|
||||
analytics/ Market reports, AI valuations
|
||||
metrics/ Prometheus + HTTP metrics
|
||||
analytics/ Báo cáo thị trường, định giá AI
|
||||
metrics/ Prometheus + metric HTTP
|
||||
```
|
||||
|
||||
### Infrastructure (4)
|
||||
```
|
||||
health/ Kubernetes liveness/readiness
|
||||
shared/ DI, encryption, logger, events
|
||||
health/ Liveness/readiness Kubernetes
|
||||
shared/ DI, mã hóa, logger, event
|
||||
mcp/ Model Context Protocol server
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💾 DATABASE MODELS (31 TOTAL)
|
||||
## 💾 MODEL DATABASE (TỔNG 31)
|
||||
|
||||
### Core (13)
|
||||
```
|
||||
User Main profile + KYC + MFA
|
||||
Agent Extended agent profile
|
||||
Property Address + geolocation
|
||||
PropertyMedia Images/videos
|
||||
Listing Sale/rent listing instance
|
||||
SavedSearch User search preferences
|
||||
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 Inquiry → completed flow
|
||||
Inquiry Buyer question on listing
|
||||
Payment All payment methods + history
|
||||
Plan Subscription tier definition
|
||||
Subscription User's active plan
|
||||
Order Auction settlement
|
||||
Escrow Payment holding & release
|
||||
Lead Agent CRM lead
|
||||
Review User ratings
|
||||
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 JWT refresh chain
|
||||
OAuthAccount OAuth provider links
|
||||
MfaChallenge TOTP verification tracking
|
||||
NotificationLog Sent notifications
|
||||
NotificationPref User opt-in/out
|
||||
AdminAuditLog Admin action audit trail
|
||||
MarketIndex District/city statistics
|
||||
Valuation AI price estimates
|
||||
UsageRecord Subscription usage tracking
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 TESTING BREAKDOWN
|
||||
## 🧪 PHÂN TÍCH TESTING
|
||||
|
||||
### Unit Tests (Vitest)
|
||||
- Payment gateways (VNPay, MoMo, ZaloPay) — ~30 specs
|
||||
- Value objects (Money, PlatformFee) — ~10 specs
|
||||
- Stores & utilities (Auth, Currency) — ~20 specs
|
||||
### Unit Test (Vitest)
|
||||
- Payment gateway (VNPay, MoMo, ZaloPay) — ~30 spec
|
||||
- Value object (Money, PlatformFee) — ~10 spec
|
||||
- Store và utility (Auth, Currency) — ~20 spec
|
||||
|
||||
### E2E Tests (Playwright)
|
||||
- **Web (15 tests):** auth, listings, search, admin, responsive
|
||||
- **API (16 tests):** all major endpoints
|
||||
- **Load (K6):** baseline benchmarks, 1000 VU stress tests
|
||||
### 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
|
||||
|
||||
**Total: 242 test files**
|
||||
**Tổng cộng: 242 file test**
|
||||
|
||||
---
|
||||
|
||||
## 🔐 SECURITY FEATURES
|
||||
## 🔐 TÍNH NĂNG BẢO MẬT
|
||||
|
||||
✅ JWT authentication with refresh tokens
|
||||
✅ OAuth2 (Google, Zalo)
|
||||
✅ TOTP/MFA with backup codes
|
||||
✅ Field-level encryption (PII)
|
||||
✅ CSRF protection middleware
|
||||
✅ Rate limiting (global + per-user)
|
||||
✅ HMAC-SHA256 for payment verification
|
||||
✅ Helmet security headers
|
||||
✅ CORS configured
|
||||
✅ Input validation & sanitization
|
||||
✅ 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
|
||||
|
||||
```
|
||||
Metrics Prometheus + Grafana (dashboards)
|
||||
Logs Pino (structured) + Loki (aggregated)
|
||||
Tracing Sentry (error tracking)
|
||||
Alerts AlertManager (configured)
|
||||
APM Core Web Vitals tracking
|
||||
Health Checks /health (liveness), /ready (readiness)
|
||||
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)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚢 DEPLOYMENT OPTIONS
|
||||
## 🚢 LỰA CHỌN DEPLOYMENT
|
||||
|
||||
### Option 1: Docker Compose (Development)
|
||||
### Lựa chọn 1: Docker Compose (Development)
|
||||
```bash
|
||||
docker-compose up -d
|
||||
# Runs: API (3001), Web (3000), DB, Redis, Typesense, etc.
|
||||
# Chạy: API (3001), Web (3000), DB, Redis, Typesense, v.v.
|
||||
```
|
||||
|
||||
### Option 2: Docker Compose Production
|
||||
### Lựa chọn 2: Docker Compose Production
|
||||
```bash
|
||||
docker-compose -f docker-compose.prod.yml up -d
|
||||
# Runs: Full stack with monitoring, logging, connection pooling
|
||||
# Chạy: Stack đầy đủ với monitoring, logging, connection pooling
|
||||
```
|
||||
|
||||
### Option 3: Kubernetes
|
||||
- ConfigMaps for env variables
|
||||
- Secrets for credentials
|
||||
- PersistentVolumes for database
|
||||
- HPA for auto-scaling
|
||||
- Ingress for traffic routing
|
||||
### 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
|
||||
|
||||
**See:** `docs/deployment.md` for detailed steps
|
||||
**Xem:** `docs/deployment.md` để biết các bước chi tiết
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ KNOWN ISSUES (Phase 7 Wave 14)
|
||||
## ⚠️ ISSUE ĐÃ BIẾT (Phase 7 Wave 14)
|
||||
|
||||
| ID | Title | Priority | Status |
|
||||
| ID | Tiêu đề | Ưu tiên | Trạng thái |
|
||||
|----|-------|----------|--------|
|
||||
| TEC-1650 | Listing detail 404 error handling | High | todo |
|
||||
| TEC-1652 | Full E2E test suite validation | High | todo |
|
||||
| TEC-1657 | Comprehensive audit logging | High | todo |
|
||||
| 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 |
|
||||
|
||||
**Impact:** Minimal (edge cases only)
|
||||
**Fix ETA:** <2 hours each
|
||||
**Ảnh hưởng:** Tối thiểu (chỉ edge case)
|
||||
**ETA fix:** <2 giờ mỗi cái
|
||||
|
||||
---
|
||||
|
||||
## 📚 DOCUMENTATION STRUCTURE
|
||||
## 📚 CẤU TRÚC TÀI LIỆU
|
||||
|
||||
```
|
||||
/
|
||||
├── PROJECT_TRACKER.md ← START HERE for status
|
||||
├── IMPLEMENTATION_PLAN.md ← Feature roadmap
|
||||
├── CODEBASE_OVERVIEW.md ← Comprehensive guide
|
||||
├── ARCHITECTURE_SUMMARY.txt ← Visual overview
|
||||
└── QUICK_START_REFERENCE.md ← This file
|
||||
├── 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 ← Technical deep dive
|
||||
├── api-endpoints.md ← All endpoints (Swagger)
|
||||
├── api-error-codes.md ← Error taxonomy
|
||||
├── deployment.md ← Deploy instructions
|
||||
├── dev-environment.md ← Local setup
|
||||
├── RUNBOOK.md ← Operations guide
|
||||
├── PRODUCTION_READINESS.md ← Compliance checklist
|
||||
└── /audits/ ← 80+ implementation audits
|
||||
├── 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 NEXT STEPS
|
||||
## 🎯 BƯỚC TIẾP THEO
|
||||
|
||||
1. **Understand:** Read `PROJECT_TRACKER.md` (5 min)
|
||||
2. **Setup:** Run `docker-compose up` (2 min)
|
||||
3. **Explore:** Visit `http://localhost:3000` (web) & `http://localhost:3001` (API)
|
||||
4. **Test:** Run `pnpm test:e2e` to validate (5 min)
|
||||
5. **Deploy:** Use `docker-compose.prod.yml` or Kubernetes manifests
|
||||
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 already in use
|
||||
### Port đang được dùng
|
||||
```bash
|
||||
# Find process using port 3000/3001
|
||||
# Tìm process đang dùng port 3000/3001
|
||||
lsof -i :3000
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
### Database connection failed
|
||||
### Kết nối database thất bại
|
||||
```bash
|
||||
# Reset database
|
||||
pnpm db:reset
|
||||
@@ -357,69 +357,69 @@ pnpm db:reset
|
||||
pnpm db:seed
|
||||
```
|
||||
|
||||
### Tests failing
|
||||
### Test thất bại
|
||||
```bash
|
||||
# Clear cache
|
||||
# Xóa cache
|
||||
rm -rf .turbo
|
||||
# Reinstall
|
||||
# Cài lại
|
||||
pnpm install
|
||||
# Run again
|
||||
# Chạy lại
|
||||
pnpm test
|
||||
```
|
||||
|
||||
### Docker issues
|
||||
### Vấn đề Docker
|
||||
```bash
|
||||
# Complete reset
|
||||
# Reset hoàn toàn
|
||||
docker-compose down -v
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎓 LEARNING PATHS
|
||||
## 🎓 LỘ TRÌNH HỌC
|
||||
|
||||
### Backend Development
|
||||
1. Read: `docs/architecture.md`
|
||||
2. Explore: `apps/api/src/modules/auth` (simplest module)
|
||||
3. Understand: DDD layers (presentation → application → domain → infrastructure)
|
||||
4. Practice: Add a new endpoint following the pattern
|
||||
### 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
|
||||
|
||||
### Frontend Development
|
||||
1. Review: `apps/web/app` (route structure)
|
||||
2. Study: `components/listings` (complex component)
|
||||
3. Learn: React Query patterns in `lib/*-api.ts`
|
||||
4. Practice: Create a new feature page
|
||||
### 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. Review: `docker-compose.yml` (architecture)
|
||||
2. Study: `.github/workflows` (CI/CD)
|
||||
3. Learn: `docs/deployment.md` (production)
|
||||
4. Practice: Deploy to staging environment
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## 💡 PRO TIPS
|
||||
## 💡 MẸO HAY
|
||||
|
||||
- Use `pnpm dev` (from root) to develop all apps simultaneously
|
||||
- ESLint is configured to catch module boundary violations
|
||||
- Prisma Studio (`pnpm db:studio`) is great for exploring data
|
||||
- Playwright reports are interactive and very helpful
|
||||
- PROJECT_TRACKER.md is the source of truth for status
|
||||
- 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
|
||||
|
||||
---
|
||||
|
||||
## 📞 QUICK REFERENCE
|
||||
## 📞 THAM KHẢO NHANH
|
||||
|
||||
| Need | Command | Where |
|
||||
| Nhu cầu | Lệnh | Vị trí |
|
||||
|------|---------|-------|
|
||||
| Check status | `cat PROJECT_TRACKER.md` | Root |
|
||||
| Run tests | `pnpm test:e2e` | Root |
|
||||
| View API docs | `http://localhost:3001/api` | After startup |
|
||||
| See database | `pnpm db:studio` | Root |
|
||||
| Check logs | Grafana/Loki | Docker |
|
||||
| Monitor errors | Sentry dashboard | Configured |
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** April 12, 2026
|
||||
**Project Status:** MVP Complete ✅ — Production Ready 🚀
|
||||
**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 🚀
|
||||
|
||||
Reference in New Issue
Block a user