admin/goodgo-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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
Details
CI / E2E Tests (push) Has been skipped
Details
CodeQL Analysis / CodeQL (javascript-typescript) (push) Failing after 2m15s
Details
Deploy / Build API Image (push) Failing after 28s
Details
Deploy / Build Web Image (push) Failing after 16s
Details
Deploy / Build AI Services Image (push) Failing after 17s
Details
E2E Tests / Playwright E2E (push) Failing after 31s
Details
Security Scanning / Dependency Audit (pnpm) (push) Failing after 3s
Details
Security Scanning / Trivy Scan — API Image (push) Failing after 1m46s
Details
Security Scanning / Trivy Scan — Web Image (push) Failing after 1m7s
Details
Security Scanning / Trivy Scan — AI Services Image (push) Failing after 53s
Details
Security Scanning / Trivy Filesystem Scan (push) Failing after 35s
Details
Deploy / Deploy to Staging (push) Has been skipped
Details
Deploy / Smoke Test Staging (push) Has been skipped
Details
Deploy / Deploy to Production (push) Has been skipped
Details
Deploy / Smoke Test Production (push) Has been skipped
Details
Security Scanning / Security Gate (push) Failing after 0s
Details
Deploy / Rollback Staging (push) Has been skipped
Details
Deploy / Rollback Production (push) Has been skipped
Details

Browse Source 
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:
Ho Ngoc Hai
2026-04-19 03:26:14 +07:00
parent 11f2bf26e6
commit d8b409a9ab
22 changed files with 3697 additions and 3703 deletions
Download Patch File Download Diff File Expand all files Collapse all files

418
docs/PRODUCTION_READINESS.md
View File

@@ -1,332 +1,332 @@
# GoodGo Platform — Production Readiness Checklist # GoodGo Platform — Checklist Sẵn Sàng Production
> **Last updated:** 2026-04-12 > **Cập nhật lần cuối:** 2026-04-12
> **Status:** NOT READY — 5 critical blockers remain > **Trạng thái:** CHƯA SẴN SÀNG — còn 5 blocker quan trọng
> **Target launch:** TBD (pending blocker resolution) > **Mục tiêu launch:** TBD (chờ giải quyết blocker)
> **Sign-off required from:** SRE Engineer, DevOps Engineer, CTO > **Cần sign-off từ:** SRE Engineer, DevOps Engineer, CTO
--- ---
## Summary ## Tóm Tắt
| Category | Pass | Fail | Blocked | Total | | Hạng mục | Pass | Fail | Blocked | Tổng |
|----------|------|------|---------|-------| |----------|------|------|---------|-------|
| Infrastructure | 1 | 3 | 0 | 4 | | Hạ tầng | 1 | 3 | 0 | 4 |
| Application Quality | 2 | 1 | 0 | 3 | | Chất lượng ứng dụng | 2 | 1 | 0 | 3 |
| Operations | 3 | 0 | 0 | 3 | | Vận hành | 3 | 0 | 0 | 3 |
| Security | 0 | 1 | 0 | 1 | | Bảo mật | 0 | 1 | 0 | 1 |
| Performance | 0 | 0 | 1 | 1 | | Hiệu năng | 0 | 0 | 1 | 1 |
| **Total** | **6** | **5** | **1** | **12** | | **Tổng** | **6** | **5** | **1** | **12** |
--- ---
## Checklist ## Checklist
### 1. Load Testing Results (K6 Baseline) ### 1. Kết Quả Load Test (K6 Baseline)
| Field | Value | | Trường | Giá trị |
|-------|-------| |-------|-------|
| **Status** | PARTIAL PASS | | **Trạng thái** | PARTIAL PASS |
| **Owner** | SRE Engineer | | **Owner** | SRE Engineer |
| **Evidence** | [`load-tests/results/BASELINE-REPORT.md`](../load-tests/results/BASELINE-REPORT.md) | | **Bằng chứng** | [`load-tests/results/BASELINE-REPORT.md`](../load-tests/results/BASELINE-REPORT.md) |
| **Date tested** | 2026-04-09 | | **Ngày test** | 2026-04-09 |
**Findings:** **Phát hiện:**
- K6 v1.7.1 baseline run completed against local dev environment - Đã hoàn thành chạy baseline K6 v1.7.1 với môi trường dev local
- 4 test suites executed: Auth, Listings, Search, Payments - 4 bộ test được chạy: Auth, Listings, Search, Payments
- Latency SLAs met at framework level (p50 < 3ms, p95 < 6ms, p99 < 19ms) - SLA latency đạt yêu cầu ở mức framework (p50 < 3ms, p95 < 6ms, p99 < 19ms)
- Error rate SLA **FAILED** — auth/listings/payments return HTTP 500 due to dev-environment dependency issues (Prisma/DB not fully configured) - SLA error rate **THẤT BẠI** — auth/listings/payments trả về HTTP 500 do vấn đề dependency môi trường dev (Prisma/DB chưa được cấu hình đầy đủ)
- Search tests skipped (Typesense unavailable in dev) - Bỏ qua test search (Typesense không khả dụng trong dev)
**Blocker:** Load tests must be re-run against a staging environment with fully operational backend dependencies (PostgreSQL, Redis, Typesense, VNPay sandbox). Framework-level latency is validated; business logic performance is not. **Blocker:** Load test phải được chạy lại với môi trường staging có đầy đủ các dependency backend hoạt động (PostgreSQL, Redis, Typesense, sandbox VNPay). Latency ở mức framework đã được validate; hiệu năng business logic thì chưa.
**Required action:** **Hành động cần thiết:**
- [ ] Provision staging environment with all dependencies - [ ] Provision môi trường staging với tất cả dependency
- [ ] Re-run K6 suites against staging - [ ] Chạy lại bộ test K6 với staging
- [ ] Validate error rate < 1% across all critical paths - [ ] Validate error rate < 1% trên tất cả critical path
- [ ] Document production-equivalent load test results - [ ] Tài liệu hóa kết quả load test tương đương production
--- ---
### 2. Security Penetration Test Sign-off ### 2. Sign-off Penetration Test Bảo Mật
| Field | Value | | Trường | Giá trị |
|-------|-------| |-------|-------|
| **Status** | FAIL | | **Trạng thái** | FAIL |
| **Owner** | CTO / DevOps Engineer | | **Owner** | CTO / DevOps Engineer |
| **Evidence** | None — no formal pen-test report exists | | **Bằng chứng** | Không có — chưa có báo cáo pen-test chính thức |
**Findings:** **Phát hiện:**
- Automated security scanning exists (`.github/workflows/security.yml`, `.github/workflows/codeql.yml`) - Có scanning bảo mật tự động (`.github/workflows/security.yml`, `.github/workflows/codeql.yml`)
- No formal third-party or manual penetration test has been conducted - Chưa có penetration test chính thức từ bên thứ ba hoặc thủ công
- No security sign-off document exists - Chưa có tài liệu sign-off bảo mật
**Blocker:** Production launch requires a formal security assessment covering OWASP Top 10, authentication flows (JWT, OAuth, CSRF), payment endpoint security, and API authorization boundaries. **Blocker:** Launch production yêu cầu đánh giá bảo mật chính thức bao quát OWASP Top 10, các luồng xác thực (JWT, OAuth, CSRF), bảo mật endpoint thanh toán, và ranh giới authorization API.
**Required action:** **Hành động cần thiết:**
- [ ] Schedule penetration test (internal or third-party) - [ ] Lên lịch penetration test (nội bộ hoặc bên thứ ba)
- [ ] Scope: auth flows, payment callbacks (VNPay/MoMo/ZaloPay), admin endpoints, file upload, geospatial API - [ ] Phạm vi: luồng auth, callback thanh toán (VNPay/MoMo/ZaloPay), endpoint admin, file upload, API geospatial
- [ ] Remediate critical/high findings - [ ] Khắc phục các phát hiện critical/high
- [ ] Obtain signed pen-test report and remediation confirmation - [ ] Lấy báo cáo pen-test có chữ ký và xác nhận khắc phục
--- ---
### 3. Monitoring Alert Thresholds Configured ### 3. Cấu Hình Ngưỡng Alert Monitoring
| Field | Value | | Trường | Giá trị |
|-------|-------| |-------|-------|
| **Status** | PASS | | **Trạng thái** | PASS |
| **Owner** | SRE Engineer | | **Owner** | SRE Engineer |
| **Evidence** | [`monitoring/prometheus/alert-rules.yml`](../monitoring/prometheus/alert-rules.yml) | | **Bằng chứng** | [`monitoring/prometheus/alert-rules.yml`](../monitoring/prometheus/alert-rules.yml) |
**Findings:** **Phát hiện:**
- 15+ Prometheus alert rules configured across multiple groups: - 15+ alert rule Prometheus đã cấu hình trên nhiều nhóm:
- `goodgo_api_latency` — p99 latency warnings (>1s), critical SLO breach (>3s), per-endpoint latency - `goodgo_api_latency` — cảnh báo latency p99 (>1s), critical SLO breach (>3s), latency theo từng endpoint
- `goodgo_api_errors` — 5xx error rate alerts - `goodgo_api_errors` — alert tỷ lệ lỗi 5xx
- `goodgo_database` — connection pool exhaustion, query latency - `goodgo_database` — cạn kiệt connection pool, latency truy vấn
- `goodgo_infrastructure` — disk, memory, CPU, container health - `goodgo_infrastructure` — disk, memory, CPU, sức khỏe container
- Alert severity levels: `warning` and `critical` - Mức độ severity alert: `warning` và `critical`
- Runbook URLs linked in alert annotations - URL runbook được link trong annotation alert
- Grafana dashboards referenced for investigation - Dashboard Grafana được tham chiếu cho việc điều tra
- AlertManager integration configured - AlertManager đã được tích hợp
**Status: READY** — Alert thresholds are well-defined and follow best practices. **Trạng thái: SẴN SÀNG** — Ngưỡng alert được định nghĩa rõ ràng và theo best practice.
--- ---
### 4. Backup/Restore Verification Completed ### 4. Hoàn Tất Verify Backup/Restore
| Field | Value | | Trường | Giá trị |
|-------|-------| |-------|-------|
| **Status** | PASS | | **Trạng thái** | PASS |
| **Owner** | SRE Engineer / DevOps Engineer | | **Owner** | SRE Engineer / DevOps Engineer |
| **Evidence** | [`docs/backup-restore.md`](backup-restore.md), [`.github/workflows/backup-verify.yml`](../.github/workflows/backup-verify.yml) | | **Bằng chứng** | [`docs/backup-restore.md`](backup-restore.md), [`.github/workflows/backup-verify.yml`](../.github/workflows/backup-verify.yml) |
**Findings:** **Phát hiện:**
- Daily automated PostgreSQL backups (02:00 UTC) via `pg_dump` custom format - Backup PostgreSQL hằng ngày tự động (02:00 UTC) qua `pg_dump` định dạng custom
- 7-day retention policy (configurable via `BACKUP_RETENTION_DAYS`) - Chính sách giữ 7 ngày (có thể cấu hình qua `BACKUP_RETENTION_DAYS`)
- Automated weekly backup verification via GitHub Actions workflow - Tự động verify backup hằng tuần qua GitHub Actions workflow
- RTO target: ≤ 30 minutes | RPO target: ≤ 24 hours - Mục tiêu RTO: ≤ 30 phút | Mục tiêu RPO: ≤ 24 giờ
- Manual backup/restore procedures documented - Quy trình backup/restore thủ công đã được tài liệu hóa
- Restore tested and documented with step-by-step runbook - Restore đã được test và tài liệu hóa với runbook từng bước
**Status: READY** — Backup procedures are automated, verified, and documented. **Trạng thái: SẴN SÀNG** — Quy trình backup được tự động hóa, đã verify và tài liệu hóa.
**Recommendation:** Consider WAL archiving for continuous point-in-time recovery to reduce RPO below 24 hours. **Khuyến nghị:** Cân nhắc WAL archiving cho point-in-time recovery liên tục để giảm RPO xuống dưới 24 giờ.
--- ---
### 5. Incident Response Runbook Reviewed ### 5. Đã Review Runbook Phản Ứng Sự Cố
| Field | Value | | Trường | Giá trị |
|-------|-------| |-------|-------|
| **Status** | PASS | | **Trạng thái** | PASS |
| **Owner** | SRE Engineer | | **Owner** | SRE Engineer |
| **Evidence** | [`docs/RUNBOOK.md`](RUNBOOK.md) | | **Bằng chứng** | [`docs/RUNBOOK.md`](RUNBOOK.md) |
**Findings:** **Phát hiện:**
- Comprehensive 41KB runbook covering: - Runbook 41KB toàn diện bao quát:
- Service inventory and health checks - Danh mục dịch vụ và health check
- 10 common incident scenarios (DB pool exhaustion, Redis failure, Typesense unavailable, high latency, payment callback failures, disk alerts, MinIO failure, AI service outage, log pipeline failure, 5xx spikes) - 10 kịch bản sự cố thường gặp (cạn DB pool, Redis fail, Typesense không khả dụng, latency cao, lỗi callback thanh toán, alert disk, MinIO fail, AI service mất, lỗi pipeline log, đột biến 5xx)
- 6 recovery procedures (DB restore, Redis flush, rolling restart, rollback, Typesense reindex, full host recovery) - 6 quy trình recovery (restore DB, flush Redis, rolling restart, rollback, reindex Typesense, recovery toàn host)
- Escalation matrix - Ma trận escalation
- Monitoring dashboard links - Link đến dashboard monitoring
- Useful PromQL queries - Các truy vấn PromQL hữu ích
- Environment quick reference - Tham khảo nhanh môi trường
- Last updated: 2026-04-11 - Cập nhật lần cuối: 2026-04-11
**Status: READY** — Runbook is thorough and up to date. **Trạng thái: SẴN SÀNG** — Runbook đầy đủ và cập nhật.
--- ---
### 6. Database Schema Frozen (Migration Lockdown) ### 6. Đóng Băng Schema Database (Migration Lockdown)
| Field | Value | | Trường | Giá trị |
|-------|-------| |-------|-------|
| **Status** | PASS (conditional) | | **Trạng thái** | PASS (có điều kiện) |
| **Owner** | DevOps Engineer / CTO | | **Owner** | DevOps Engineer / CTO |
| **Evidence** | `prisma/migrations/` (16 migrations), `prisma/migrations/migration_lock.toml` | | **Bằng chứng** | `prisma/migrations/` (16 migration), `prisma/migrations/migration_lock.toml` |
**Findings:** **Phát hiện:**
- 16 sequential Prisma migrations exist - 16 migration Prisma tuần tự đã có
- Latest migration: `20260411200000_add_mfa_totp_support` (2026-04-11) - Migration mới nhất: `20260411200000_add_mfa_totp_support` (2026-04-11)
- Migration lock file present (`migration_lock.toml`) - Có file migration lock (`migration_lock.toml`)
- 22 database models defined (User, Property, Listing, Payment, Subscription, etc.) - 22 model database đã được định nghĩa (User, Property, Listing, Payment, Subscription, v.v.)
- PostGIS extension configured for geospatial queries - PostGIS extension đã cấu hình cho truy vấn geospatial
**Condition:** Schema must be formally frozen before launch. Recent migrations (4 on 2026-04-10/11) indicate active schema changes. A freeze date must be declared and no new migrations accepted after that date without CTO sign-off. **Điều kiện:** Schema phải được đóng băng chính thức trước khi launch. Các migration gần đây (4 cái vào 2026-04-10/11) cho thấy schema đang được thay đổi tích cực. Phải khai báo ngày freeze và không chấp nhận migration mới sau ngày đó nếu không có sign-off của CTO.
**Required action:** **Hành động cần thiết:**
- [ ] Declare schema freeze date (recommended: 48 hours before launch) - [ ] Khai báo ngày freeze schema (khuyến nghị: 48 giờ trước launch)
- [ ] Communicate freeze to all developers - [ ] Thông báo freeze đến tất cả developer
- [ ] CTO approval required for any post-freeze schema changes - [ ] Cần phê duyệt CTO cho mọi thay đổi schema sau freeze
--- ---
### 7. CI/CD Pipeline Green (Lint, Typecheck, Test, Build) ### 7. CI/CD Pipeline Xanh (Lint, Typecheck, Test, Build)
| Field | Value | | Trường | Giá trị |
|-------|-------| |-------|-------|
| **Status** | PASS | | **Trạng thái** | PASS |
| **Owner** | DevOps Engineer | | **Owner** | DevOps Engineer |
| **Evidence** | `.github/workflows/` (7 workflows) | | **Bằng chứng** | `.github/workflows/` (7 workflow) |
**Findings:** **Phát hiện:**
- **ci.yml** — Full pipeline: lint → typecheck → test → build - **ci.yml** — Pipeline đầy đủ: lint → typecheck → test → build
- **deploy.yml** — Deployment automation - **deploy.yml** — Tự động hóa deployment
- **e2e.yml** — Playwright E2E test suite - **e2e.yml** — Bộ test E2E Playwright
- **security.yml** — Automated security scanning - **security.yml** — Scan bảo mật tự động
- **codeql.yml** — GitHub CodeQL analysis - **codeql.yml** — Phân tích GitHub CodeQL
- **load-test.yml** — K6 load test automation - **load-test.yml** — Tự động hóa load test K6
- **backup-verify.yml** — Weekly backup verification - **backup-verify.yml** — Verify backup hằng tuần
**Status: READY** — CI/CD pipeline is comprehensive and covers the full quality gate (lint, typecheck, unit tests, build, E2E, security, load testing). **Trạng thái: SẴN SÀNG** — Pipeline CI/CD toàn diện và bao quát đầy đủ quality gate (lint, typecheck, unit test, build, E2E, security, load test).
--- ---
### 8. E2E Test Results ### 8. Kết Quả Test E2E
| Field | Value | | Trường | Giá trị |
|-------|-------| |-------|-------|
| **Status** | FAIL | | **Trạng thái** | FAIL |
| **Owner** | DevOps Engineer / Backend Engineers | | **Owner** | DevOps Engineer / Backend Engineer |
| **Evidence** | `e2e/` (31 test spec files across `api/`, `web/`, `load/`) | | **Bằng chứng** | `e2e/` (31 file test spec trên `api/`, `web/`, `load/`) |
**Findings:** **Phát hiện:**
- 31 E2E test spec files covering API and Web surfaces - 31 file test spec E2E bao quát surface API và Web
- Test infrastructure: Playwright with global setup/teardown - Hạ tầng test: Playwright với global setup/teardown
- Organized by domain: `api/` (backend API tests), `web/` (frontend browser tests), `load/` (load scenario tests) - Tổ chức theo domain: `api/` (test API backend), `web/` (test browser frontend), `load/` (test kịch bản tải)
- **2 tests currently failing** (per last Playwright run) - **2 test hiện đang fail** (theo lần chạy Playwright cuối)
- No saved `test-results/.last-run.json` available for detailed failure analysis - Không có file `test-results/.last-run.json` được lưu lại để phân tích chi tiết lỗi
**Blocker:** All E2E tests must pass before production launch. **Blocker:** Tất cả test E2E phải pass trước khi launch production.
**Required action:** **Hành động cần thiết:**
- [ ] Run full E2E suite: `pnpm test:e2e` - [ ] Chạy bộ test E2E đầy đủ: `pnpm test:e2e`
- [ ] Fix 2 failing tests - [ ] Sửa 2 test đang fail
- [ ] Achieve 100% pass rate on the full suite - [ ] Đạt 100% pass rate trên bộ test đầy đủ
- [ ] Archive passing test results as evidence - [ ] Lưu trữ kết quả test pass làm bằng chứng
--- ---
### 9. Performance Benchmarks Documented ### 9. Tài Liệu Hóa Benchmark Hiệu Năng
| Field | Value | | Trường | Giá trị |
|-------|-------| |-------|-------|
| **Status** | BLOCKED | | **Trạng thái** | BLOCKED |
| **Owner** | SRE Engineer | | **Owner** | SRE Engineer |
| **Evidence** | [`load-tests/results/BASELINE-REPORT.md`](../load-tests/results/BASELINE-REPORT.md) (partial) | | **Bằng chứng** | [`load-tests/results/BASELINE-REPORT.md`](../load-tests/results/BASELINE-REPORT.md) (một phần) |
**Findings:** **Phát hiện:**
- Framework-level latency benchmarks documented (p50/p95/p99) - Benchmark latency mức framework đã được tài liệu hóa (p50/p95/p99)
- Business logic benchmarks not available (auth returns 500, search unavailable) - Benchmark business logic không khả dụng (auth trả 500, search không khả dụng)
- No production-equivalent performance profile exists - Chưa có profile hiệu năng tương đương production
- Blocked on staging environment availability - Bị chặn vì chưa có môi trường staging
**Blocker:** Cannot establish meaningful performance benchmarks without a staging environment running all dependencies. **Blocker:** Không thể thiết lập benchmark hiệu năng có ý nghĩa nếu không có môi trường staging chạy đầy đủ dependency.
**Required action:** **Hành động cần thiết:**
- [ ] Provision staging environment - [ ] Provision môi trường staging
- [ ] Run K6 suites with real database, Redis, Typesense - [ ] Chạy bộ test K6 với database, Redis, Typesense thật
- [ ] Document per-endpoint latency baselines (auth, listings CRUD, search, payments) - [ ] Tài liệu hóa baseline latency theo từng endpoint (auth, CRUD listing, search, payment)
- [ ] Establish throughput capacity (max concurrent users per instance) - [ ] Thiết lập sức chứa throughput (số user đồng thời tối đa mỗi instance)
- [ ] Document resource utilization under load (CPU, memory, connections) - [ ] Tài liệu hóa mức sử dụng tài nguyên dưới tải (CPU, memory, connection)
--- ---
### 10. SSL/TLS Certificates Ready ### 10. Sẵn Sàng Chứng Chỉ SSL/TLS
| Field | Value | | Trường | Giá trị |
|-------|-------| |-------|-------|
| **Status** | FAIL | | **Trạng thái** | FAIL |
| **Owner** | DevOps Engineer | | **Owner** | DevOps Engineer |
| **Evidence** | `docs/deployment.md` (line ~146, unchecked item) | | **Bằng chứng** | `docs/deployment.md` (dòng ~146, mục chưa tích) |
**Findings:** **Phát hiện:**
- No reverse proxy (nginx/Caddy/Traefik) configured in `docker-compose.prod.yml` - Chưa có reverse proxy (nginx/Caddy/Traefik) cấu hình trong `docker-compose.prod.yml`
- No SSL/TLS certificate provisioning (Let's Encrypt, manual, or cloud-managed) - Chưa có cấp chứng chỉ SSL/TLS (Let's Encrypt, thủ công, hay cloud-managed)
- Deployment doc lists SSL/TLS as an unchecked to-do item - Tài liệu deployment liệt kê SSL/TLS như một mục to-do chưa tích
- API and web services currently exposed on plain HTTP - API và web service hiện đang exposed trên HTTP thường
**Blocker:** All production traffic must be encrypted via HTTPS. **Blocker:** Tất cả lưu lượng production phải được mã hóa qua HTTPS.
**Required action:** **Hành động cần thiết:**
- [ ] Add reverse proxy service (nginx or Traefik) to `docker-compose.prod.yml` - [ ] Thêm dịch vụ reverse proxy (nginx hoặc Traefik) vào `docker-compose.prod.yml`
- [ ] Configure Let's Encrypt auto-renewal (certbot or Traefik ACME) - [ ] Cấu hình tự động gia hạn Let's Encrypt (certbot hoặc Traefik ACME)
- [ ] Enforce HTTPS redirect (HTTP → HTTPS) - [ ] Bắt buộc redirect HTTPS (HTTP → HTTPS)
- [ ] Configure HSTS headers - [ ] Cấu hình HSTS header
- [ ] Verify certificate chain validity - [ ] Verify tính hợp lệ của chuỗi chứng chỉ
--- ---
### 11. DNS Configuration Verified ### 11. Verify Cấu Hình DNS
| Field | Value | | Trường | Giá trị |
|-------|-------| |-------|-------|
| **Status** | FAIL | | **Trạng thái** | FAIL |
| **Owner** | DevOps Engineer / CTO | | **Owner** | DevOps Engineer / CTO |
| **Evidence** | None — no DNS configuration documented | | **Bằng chứng** | Không có — chưa có cấu hình DNS được tài liệu hóa |
**Findings:** **Phát hiện:**
- No domain names registered or documented (e.g., goodgo.vn, api.goodgo.vn) - Chưa có domain nào được đăng ký hoặc tài liệu hóa (vd: goodgo.vn, api.goodgo.vn)
- No DNS zone files or configuration in `infra/` - Không có DNS zone file hay cấu hình trong `infra/`
- No documentation for DNS provider setup - Không có tài liệu cho cấu hình DNS provider
- Deployment doc does not reference DNS configuration - Tài liệu deployment không tham chiếu cấu hình DNS
**Blocker:** Production requires domain names with proper DNS records. **Blocker:** Production yêu cầu domain với DNS record phù hợp.
**Required action:** **Hành động cần thiết:**
- [ ] Register production domain(s) (e.g., goodgo.vn) - [ ] Đăng ký domain production (vd: goodgo.vn)
- [ ] Configure DNS A/CNAME records for web (goodgo.vn) and API (api.goodgo.vn) - [ ] Cấu hình DNS A/CNAME record cho web (goodgo.vn) và API (api.goodgo.vn)
- [ ] Set up DNS monitoring/health checks - [ ] Cài đặt monitoring/health check cho DNS
- [ ] Document DNS provider and record configuration in `docs/` - [ ] Tài liệu hóa nhà cung cấp DNS và cấu hình record trong `docs/`
- [ ] Configure appropriate TTL values - [ ] Cấu hình giá trị TTL phù hợp
--- ---
### 12. CDN Setup for Static Assets ### 12. Cài Đặt CDN Cho Static Asset
| Field | Value | | Trường | Giá trị |
|-------|-------| |-------|-------|
| **Status** | FAIL | | **Trạng thái** | FAIL |
| **Owner** | DevOps Engineer | | **Owner** | DevOps Engineer |
| **Evidence** | `docs/deployment.md` (line ~167, unchecked item) | | **Bằng chứng** | `docs/deployment.md` (dòng ~167, mục chưa tích) |
**Findings:** **Phát hiện:**
- No CDN (Cloudflare, CloudFront, or similar) configured - Chưa cấu hình CDN (Cloudflare, CloudFront hay tương tự)
- Next.js static assets served directly from origin - Static asset của Next.js phục vụ trực tiếp từ origin
- No edge caching for images, JS bundles, or CSS - Không có edge caching cho ảnh, JS bundle hay CSS
- Deployment doc lists CDN as an unchecked to-do item - Tài liệu deployment liệt kê CDN như một mục to-do chưa tích
**Blocker:** CDN improves Vietnamese user experience (latency, availability) and protects origin from DDoS. **Blocker:** CDN cải thiện trải nghiệm người dùng Việt Nam (latency, tính sẵn sàng) và bảo vệ origin khỏi DDoS.
**Required action:** **Hành động cần thiết:**
- [ ] Select CDN provider (Cloudflare recommended for ease; CloudFront if on AWS) - [ ] Chọn nhà cung cấp CDN (khuyến nghị Cloudflare để dễ; CloudFront nếu trên AWS)
- [ ] Configure CDN for Next.js static assets (`_next/static/`) - [ ] Cấu hình CDN cho static asset Next.js (`_next/static/`)
- [ ] Set cache headers for immutable assets - [ ] Đặt cache header cho asset bất biến
- [ ] Configure CDN for image optimization (property photos) - [ ] Cấu hình CDN cho tối ưu hình ảnh (ảnh bất động sản)
- [ ] Set up DDoS protection rules - [ ] Cài đặt rule bảo vệ DDoS
--- ---
## Critical Blockers Summary ## Tóm Tắt Blocker Quan Trọng
| # | Blocker | Owner | Priority | Dependency | | # | Blocker | Owner | Ưu tiên | Phụ thuộc |
|---|---------|-------|----------|------------| |---|---------|-------|----------|------------|
| B1 | Security penetration test not conducted | CTO / DevOps | **P0 — Critical** | External scheduling | | B1 | Chưa có penetration test bảo mật | CTO / DevOps | **P0 — Critical** | Sắp lịch bên ngoài |
| B2 | 2 E2E tests failing | DevOps / Backend | **P0 — Critical** | Code fix required | | B2 | 2 test E2E đang fail | DevOps / Backend | **P0 — Critical** | Cần fix code |
| B3 | SSL/TLS not configured | DevOps | **P0 — Critical** | Requires reverse proxy setup | | B3 | Chưa cấu hình SSL/TLS | DevOps | **P0 — Critical** | Cần setup reverse proxy |
| B4 | DNS not configured | DevOps / CTO | **P0 — Critical** | Requires domain registration | | B4 | Chưa cấu hình DNS | DevOps / CTO | **P0 — Critical** | Cần đăng ký domain |
| B5 | Performance benchmarks blocked on staging | SRE | **P1 — High** | Requires staging environment | | B5 | Benchmark hiệu năng bị chặn vì staging | SRE | **P1 — High** | Cần môi trường staging |
| B6 | CDN not set up | DevOps | **P1 — High** | Requires CDN provider decision | | B6 | Chưa setup CDN | DevOps | **P1 — High** | Cần quyết định nhà cung cấp CDN |
--- ---
## Sign-off ## Sign-off
Production launch requires sign-off from all listed roles after all checklist items pass. Launch production yêu cầu sign-off từ tất cả vai trò được liệt kê sau khi tất cả mục checklist pass.
| Role | Name | Status | Date | Signature | | Vai trò | Tên | Trạng thái | Ngày | Chữ ký |
|------|------|--------|------|-----------| |------|------|--------|------|-----------|
| SRE Engineer | — | Pending | — | — | | SRE Engineer | — | Pending | — | — |
| DevOps Engineer | — | Pending | — | — | | DevOps Engineer | — | Pending | — | — |
@@ -334,8 +334,8 @@ Production launch requires sign-off from all listed roles after all checklist it
--- ---
## Revision History ## Lịch Sử Sửa Đổi
| Date | Author | Changes | | Ngày | Tác giả | Thay đổi |
|------|--------|---------| |------|--------|---------|
| 2026-04-12 | SRE Engineer | Initial checklist created, 12 items assessed | | 2026-04-12 | SRE Engineer | Tạo checklist ban đầu, đánh giá 12 mục |

96
docs/QUICK_REFERENCE.md
View File

@@ -1,8 +1,8 @@
# GoodGo Platform - Authentication Quick Reference # GoodGo Platform - Tham chiếu nhanh Authentication
## 🔑 Key Points at a Glance ## 🔑 Các điểm chính trong nháy mắt
### Password Hashing ### Hash mật khẩu
``` ```
Algorithm: bcrypt Algorithm: bcrypt
Salt Rounds: 12 (env: BCRYPT_ROUNDS) Salt Rounds: 12 (env: BCRYPT_ROUNDS)
@@ -10,7 +10,7 @@ Min Length: 8 characters
Example: bcrypt.hash('password', 12) Example: bcrypt.hash('password', 12)
``` ```
### Phone Numbers (Vietnamese) ### Số điện thoại (Việt Nam)
``` ```
Valid Formats: 0900000001, 84900000001, +84900000001 Valid Formats: 0900000001, 84900000001, +84900000001
Normalized: +84900000001 Normalized: +84900000001
@@ -25,7 +25,7 @@ Normalization: lowercase + trim
Storage: admin@goodgo.vn Storage: admin@goodgo.vn
``` ```
### PII Encryption ### Mã hoá PII
``` ```
Algorithm: AES-256-GCM Algorithm: AES-256-GCM
Key: 32 bytes (64 hex chars) Key: 32 bytes (64 hex chars)
@@ -35,7 +35,7 @@ Searchable: email → emailHash (HMAC-SHA256)
Env Var: FIELD_ENCRYPTION_KEY Env Var: FIELD_ENCRYPTION_KEY
``` ```
### User Login ### Đăng nhập User
``` ```
Username: phone (normalized) Username: phone (normalized)
Password: plain text Password: plain text
@@ -44,7 +44,7 @@ Required: isActive = true, passwordHash ≠ null
Response: tokens (or MFA challenge) Response: tokens (or MFA challenge)
``` ```
### User Roles ### Vai trò người dùng
``` ```
BUYER - Search, inquire, offer (default) BUYER - Search, inquire, offer (default)
SELLER - Create listings SELLER - Create listings
@@ -63,33 +63,33 @@ Hashing: HMAC-SHA256 (not bcrypt)
--- ---
## 📋 Creating a Login-Capable Admin User ## 📋 Tạo người dùng Admin có thể đăng nhập
### 5-Step Process ### Quy trình 5 bước
**1. Normalize phone** **1. Chuẩn hoá số điện thoại**
```typescript ```typescript
phone = '0900000001' → '+84900000001' phone = '0900000001' → '+84900000001'
``` ```
**2. Derive HMAC key** **2. Tạo HMAC key**
```typescript ```typescript
hmacKey = crypto.hkdfSync('sha256', Buffer.from(encryptionKey, 'hex'), hmacKey = crypto.hkdfSync('sha256', Buffer.from(encryptionKey, 'hex'),
Buffer.alloc(0), Buffer.from('goodgo-field-hash', 'utf8'), 32) Buffer.alloc(0), Buffer.from('goodgo-field-hash', 'utf8'), 32)
``` ```
**3. Compute hashes** **3. Tính các hash**
```typescript ```typescript
phoneHash = crypto.createHmac('sha256', hmacKey).update('+84900000001').digest('hex') phoneHash = crypto.createHmac('sha256', hmacKey).update('+84900000001').digest('hex')
emailHash = crypto.createHmac('sha256', hmacKey).update('admin@goodgo.vn').digest('hex') emailHash = crypto.createHmac('sha256', hmacKey).update('admin@goodgo.vn').digest('hex')
``` ```
**4. Hash password** **4. Hash mật khẩu**
```typescript ```typescript
passwordHash = await bcrypt.hash('AdminPassword123', 12) passwordHash = await bcrypt.hash('AdminPassword123', 12)
``` ```
**5. Create user** **5. Tạo user**
```typescript ```typescript
await prisma.user.create({ await prisma.user.create({
data: { data: {
@@ -111,7 +111,7 @@ await prisma.user.create({
--- ---
## 🧪 Test Login ## 🧪 Test đăng nhập
```bash ```bash
curl -X POST http://localhost:3000/auth/login \ curl -X POST http://localhost:3000/auth/login \
@@ -122,7 +122,7 @@ curl -X POST http://localhost:3000/auth/login \
}' }'
``` ```
**Success Response:** **Response thành công:**
```json ```json
{ {
"requiresMfa": false, "requiresMfa": false,
@@ -136,42 +136,42 @@ curl -X POST http://localhost:3000/auth/login \
--- ---
## ⚠️ Common Issues ## ⚠️ Vấn đề thường gặp
| Issue | Fix | | Vấn đề | Cách sửa |
|-------|-----| |-------|-----|
| User can't login | Check: `passwordHash` ≠ null, `isActive` = true | | User không đăng nhập được | Kiểm tra: `passwordHash` ≠ null, `isActive` = true |
| "Invalid phone" | Phone must match regex (mobile only) | | "Invalid phone" | Phone phải khớp regex (chỉ mobile) |
| Hash mismatch | Verify `FIELD_ENCRYPTION_KEY` is consistent | | Hash không khớp | Xác minh `FIELD_ENCRYPTION_KEY` nhất quán |
| MFA issue | Verify `MFA_BACKUP_CODE_SECRET` env var | | Vấn đề MFA | Xác minh biến môi trường `MFA_BACKUP_CODE_SECRET` |
| PII not encrypted | Verify key is exactly 32 bytes (64 hex chars) | | PII không được mã hoá | Xác minh key đúng 32 bytes (64 ký tự hex) |
--- ---
## 📁 Key Files ## 📁 Các file chính
| File | Purpose | | File | Mục đích |
|------|---------| |------|---------|
| `hashed-password.vo.ts` | bcrypt hashing | | `hashed-password.vo.ts` | Hash bcrypt |
| `vietnam-phone.validator.ts` | Phone validation | | `vietnam-phone.validator.ts` | Validation số điện thoại |
| `field-encryption.ts` | AES-256-GCM encryption | | `field-encryption.ts` | Mã hoá AES-256-GCM |
| `local.strategy.ts` | Login endpoint | | `local.strategy.ts` | Endpoint đăng nhập |
| `mfa.service.ts` | TOTP / backup codes | | `mfa.service.ts` | TOTP / backup code |
| `user.entity.ts` | User domain model | | `user.entity.ts` | Domain model User |
| `prisma-user.repository.ts` | User persistence | | `prisma-user.repository.ts` | Persistence User |
| `seed.ts` | Seed script | | `seed.ts` | Script seed |
--- ---
## 🔐 Checklist for Seed User ## 🔐 Checklist cho Seed User
- [ ] Password ≥ 8 chars - [ ] Mật khẩu ≥ 8 ký tự
- [ ] Phone matches regex - [ ] Phone khớp regex
- [ ] Phone normalized: +84... - [ ] Phone đã chuẩn hoá: +84...
- [ ] Phone hashed: HMAC-SHA256 - [ ] Phone đã hash: HMAC-SHA256
- [ ] Email lowercased - [ ] Email đã chuyển lowercase
- [ ] Email hashed: HMAC-SHA256 - [ ] Email đã hash: HMAC-SHA256
- [ ] Password hashed: bcrypt (12 rounds) - [ ] Password đã hash: bcrypt (12 rounds)
- [ ] `isActive: true` - [ ] `isActive: true`
- [ ] `passwordHash` ≠ null - [ ] `passwordHash` ≠ null
- [ ] `totpEnabled: false` - [ ] `totpEnabled: false`
@@ -179,14 +179,14 @@ curl -X POST http://localhost:3000/auth/login \
--- ---
## 📚 Full Documentation Files ## 📚 Các file tài liệu đầy đủ
1. **AUTHENTICATION_GUIDE.md** - Complete technical reference 1. **AUTHENTICATION_GUIDE.md** - Tham chiếu kỹ thuật đầy đủ
2. **AUTH_IMPLEMENTATION_CHECKLIST.md** - Implementation checklist & troubleshooting 2. **AUTH_IMPLEMENTATION_CHECKLIST.md** - Checklist triển khai & troubleshoot
3. **SEED_GENERATION_SCRIPT.ts** - Ready-to-use seed script 3. **SEED_GENERATION_SCRIPT.ts** - Script seed sẵn sàng dùng
4. **QUICK_REFERENCE.md** - This file 4. **QUICK_REFERENCE.md** - File này
--- ---
**Last Updated:** April 12, 2026 **Cập nhật cuối:** 12 tháng 4, 2026
**Status:** ✅ Production-Ready **Trạng thái:** ✅ Sẵn sàng Production

426
docs/QUICK_START_REFERENCE.md
View File

@@ -1,26 +1,26 @@
# GoodGo Platform — Quick Start Reference # GoodGo Platform — Tham Khảo Nhanh
**Status:** MVP Complete (Phase 7 Wave 14) ✅ **Trạng thái:** MVP Hoàn Tất (Phase 7 Wave 14) ✅
**Generated:** April 12, 2026 **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 | | **Hoàn thiện tính năng** | 🟢 95% | Tất cả tính năng MVP xong; còn 3 edge case |
| **Code Quality** | 🟢 High | 242 tests, ESLint pass, DDD architecture | | **Chất lượng code** | 🟢 Cao | 242 test, ESLint pass, kiến trúc DDD |
| **Security** | 🟢 Hardened | JWT/MFA, encryption, rate limiting, CSRF protection | | **Bảo mật** | 🟢 Hardened | JWT/MFA, mã hóa, rate limiting, bảo vệ CSRF |
| **Documentation** | 🟢 Comprehensive | 80+ audit files, runbooks, API reference | | **Tài liệu** | 🟢 Toàn diện | 80+ file audit, runbook, tham khảo API |
| **Performance** | 🟢 Optimized | Caching, indexing, K6 load tests baseline | | **Hiệu năng** | 🟢 Đã tối ưu | Cache, indexing, K6 load test baseline |
| **Ops Readiness** | 🟢 Ready | Docker/Kubernetes, monitoring, backup strategy | | **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 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 Code: ~50,000 LOC
Backend: 845 TypeScript files (18 modules) Backend: 845 file TypeScript (18 module)
Frontend: 245 TypeScript/TSX files Frontend: 245 file TypeScript/TSX
Database: 31 models, 30+ indexes, 7+ migrations Database: 31 model, 30+ index, 7+ migration
Tests: 242 files (unit + E2E + load) Tests: 242 file (unit + E2E + load)
API: 100+ endpoints (Swagger documented) API: 100+ endpoint (đã tài liệu Swagger)
Deployment: Docker + Kubernetes ready Deployment: Sẵn sàng Docker + Kubernetes
``` ```
--- ---
## 🚀 QUICK START COMMANDS ## 🚀 LỆNH KHỞI ĐỘNG NHANH
### Local Development ### Phát Triển Local
```bash ```bash
# Install & start everything # Cài đặt và khởi động tất cả
docker-compose up -d docker-compose up -d
# API development # Phát triển API
cd apps/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 cd apps/web
pnpm dev # Dev server on :3000 pnpm dev # Dev server ở :3000
# Both together (from root) # Cả hai cùng lúc (từ root)
pnpm dev # All apps via Turbo pnpm dev # Tất cả app qua Turbo
``` ```
### Testing ### Testing
```bash ```bash
pnpm test # All unit tests pnpm test # Tất cả unit test
pnpm test:e2e # All E2E tests (Playwright) pnpm test:e2e # Tất cả E2E test (Playwright)
pnpm test:e2e:web # Just web E2E pnpm test:e2e:web # Chỉ E2E web
pnpm test:e2e:api # Just API E2E pnpm test:e2e:api # Chỉ E2E API
pnpm test:e2e:report # View Playwright report pnpm test:e2e:report # Xem report Playwright
``` ```
### Database ### Database
```bash ```bash
pnpm db:generate # Regenerate Prisma client pnpm db:generate # Sinh lại Prisma client
pnpm db:migrate:dev # Create & apply migration pnpm db:migrate:dev # Tạo và áp dụng migration
pnpm db:push # Push schema (dev only) pnpm db:push # Push schema (chỉ dev)
pnpm db:seed # Seed test data pnpm db:seed # Seed dữ liệu test
pnpm db:studio # Prisma Studio UI (localhost:5555) pnpm db:studio # UI Prisma Studio (localhost:5555)
``` ```
### Quality ### Chất Lượng
```bash ```bash
pnpm lint # ESLint check pnpm lint # Kiểm tra ESLint
pnpm format:check # Prettier check pnpm format:check # Kiểm tra Prettier
pnpm format # Auto-format all files pnpm format # Tự format tất cả file
pnpm typecheck # TypeScript check pnpm typecheck # Kiểm tra TypeScript
pnpm dep-cruise # Architecture validation pnpm dep-cruise # Validate kiến trúc
``` ```
### Build & Deployment ### Build & Deployment
```bash ```bash
pnpm build # Build API + frontend 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 docker-compose -f docker-compose.prod.yml up -d
``` ```
--- ---
## 📁 KEY FILES TO KNOW ## 📁 FILE QUAN TRỌNG CẦN BIẾT
### Planning & Status ### Lập Kế Hoạch & Trạng Thái
- **PROJECT_TRACKER.md** — All 7 phases, 40+ issues, current status - **PROJECT_TRACKER.md** — Cả 7 phase, 40+ issue, trạng thái hiện tại
- **IMPLEMENTATION_PLAN.md** — Feature roadmap with priority - **IMPLEMENTATION_PLAN.md** — Roadmap tính năng theo ưu tiên
- **CODEBASE_OVERVIEW.md** — Comprehensive guide (this was just created!) - **CODEBASE_OVERVIEW.md** — Hướng dẫn toàn diện (vừa được tạo!)
### Architecture & Design ### Kiến Trúc & Thiết Kế
- **docs/architecture.md** — DDD layers, module boundaries, CQRS - **docs/architecture.md** — Tầng DDD, ranh giới module, CQRS
- **docs/api-endpoints.md** — All endpoints with examples - **docs/api-endpoints.md** — Tất cả endpoint kèm ví dụ
- **docs/api-error-codes.md** — Error taxonomy & handling - **docs/api-error-codes.md** — Phân loại lỗi và xử lý
### Technical ### Kỹ Thuật
- **prisma/schema.prisma** — Full database model (31 entities) - **prisma/schema.prisma** — Model database đầy đủ (31 entity)
- **apps/api/src/modules/** — 18 feature modules (auth, listings, payments, etc.) - **apps/api/src/modules/** — 18 module tính năng (auth, listings, payments, v.v.)
- **apps/web/app/** — Next.js routes & page groups - **apps/web/app/** — Route và group page Next.js
- **apps/web/components/** — UI components (16 directories) - **apps/web/components/** — UI component (16 thư mục)
### Operations ### Vận Hành
- **docs/deployment.md** — Docker, Kubernetes, CI/CD steps - **docs/deployment.md** — Bước Docker, Kubernetes, CI/CD
- **docs/RUNBOOK.md** — Operational procedures, troubleshooting - **docs/RUNBOOK.md** — Quy trình vận hành, troubleshooting
- **docker-compose.yml** — Local dev stack - **docker-compose.yml** — Stack dev local
- **docker-compose.prod.yml** — Production stack - **docker-compose.prod.yml** — Stack production
--- ---
## 🔧 API MODULES OVERVIEW ## 🔧 TỔNG QUAN MODULE API
### Authentication (1) ### Authentication (1)
``` ```
auth/ auth/
├── JWT + OAuth (Google, Zalo) ├── JWT + OAuth (Google, Zalo)
├── MFA/TOTP + backup codes ├── MFA/TOTP + backup code
├── Passport strategies ├── Passport strategy
└── Session management └── Quản lý session
``` ```
### Business Logic (5) ### Business Logic (5)
``` ```
listings/ Properties + media upload + moderation listings/ Bất động sản + upload media + moderation
search/ Typesense + PostGIS geo-search search/ Typesense + tìm kiếm địa lý PostGIS
inquiries/ Buyer-to-seller messages inquiries/ Tin nhắn buyer-to-seller
leads/ Agent CRM & lead scoring leads/ CRM agent và lead scoring
reviews/ User ratings & reviews reviews/ Đánh giá và review của user
``` ```
### Monetization (2) ### Monetization (2)
``` ```
payments/ VNPay, MoMo, ZaloPay + webhooks payments/ VNPay, MoMo, ZaloPay + webhook
subscriptions/ 4 tiers (FREE, AGENT_PRO, INVESTOR, ENTERPRISE) subscriptions/ 4 tier (FREE, AGENT_PRO, INVESTOR, ENTERPRISE)
``` ```
### Operations (5) ### Operations (5)
``` ```
agents/ Agent profiles & verification agents/ Hồ sơ agent và xác minh
admin/ Moderation, KYC, audit logs admin/ Moderation, KYC, audit log
notifications/ Email, SMS, Push, Zalo OA notifications/ Email, SMS, Push, Zalo OA
analytics/ Market reports, AI valuations analytics/ Báo cáo thị trường, định giá AI
metrics/ Prometheus + HTTP metrics metrics/ Prometheus + metric HTTP
``` ```
### Infrastructure (4) ### Infrastructure (4)
``` ```
health/ Kubernetes liveness/readiness health/ Liveness/readiness Kubernetes
shared/ DI, encryption, logger, events shared/ DI, mã hóa, logger, event
mcp/ Model Context Protocol server mcp/ Model Context Protocol server
``` ```
--- ---
## 💾 DATABASE MODELS (31 TOTAL) ## 💾 MODEL DATABASE (TỔNG 31)
### Core (13) ### Core (13)
``` ```
User Main profile + KYC + MFA User Hồ sơ chính + KYC + MFA
Agent Extended agent profile Agent Hồ sơ agent mở rộng
Property Address + geolocation Property Địa chỉ + vị trí địa lý
PropertyMedia Images/videos PropertyMedia Hình ảnh/video
Listing Sale/rent listing instance Listing Instance tin đăng bán/cho thuê
SavedSearch User search preferences SavedSearch Tùy chọn tìm kiếm của user
``` ```
### Commerce (9) ### Commerce (9)
``` ```
Transaction Inquiry → completed flow Transaction Luồng từ inquiry đến hoàn tất
Inquiry Buyer question on listing Inquiry Câu hỏi buyer trên tin đăng
Payment All payment methods + history Payment Tất cả phương thức thanh toán + lịch sử
Plan Subscription tier definition Plan Định nghĩa tier subscription
Subscription User's active plan Subscription Plan đang active của user
Order Auction settlement Order Settlement đấu giá
Escrow Payment holding & release Escrow Giữ và giải phóng thanh toán
Lead Agent CRM lead Lead Lead CRM agent
Review User ratings Review Đánh giá user
``` ```
### Operations (9) ### Operations (9)
``` ```
RefreshToken JWT refresh chain RefreshToken Chuỗi refresh JWT
OAuthAccount OAuth provider links OAuthAccount Liên kết OAuth provider
MfaChallenge TOTP verification tracking MfaChallenge Theo dõi xác minh TOTP
NotificationLog Sent notifications NotificationLog Thông báo đã gửi
NotificationPref User opt-in/out NotificationPref Opt-in/out của user
AdminAuditLog Admin action audit trail AdminAuditLog Audit trail hành động admin
MarketIndex District/city statistics MarketIndex Thống kê quận/thành phố
Valuation AI price estimates Valuation Ước tính giá AI
UsageRecord Subscription usage tracking UsageRecord Theo dõi sử dụng subscription
``` ```
--- ---
## 🧪 TESTING BREAKDOWN ## 🧪 PHÂN TÍCH TESTING
### Unit Tests (Vitest) ### Unit Test (Vitest)
- Payment gateways (VNPay, MoMo, ZaloPay) — ~30 specs - Payment gateway (VNPay, MoMo, ZaloPay) — ~30 spec
- Value objects (Money, PlatformFee) — ~10 specs - Value object (Money, PlatformFee) — ~10 spec
- Stores & utilities (Auth, Currency) — ~20 specs - Store và utility (Auth, Currency) — ~20 spec
### E2E Tests (Playwright) ### E2E Test (Playwright)
- **Web (15 tests):** auth, listings, search, admin, responsive - **Web (15 test):** auth, listings, search, admin, responsive
- **API (16 tests):** all major endpoints - **API (16 test):** tất cả endpoint chính
- **Load (K6):** baseline benchmarks, 1000 VU stress tests - **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 ✅ JWT authentication với refresh token
✅ OAuth2 (Google, Zalo) ✅ OAuth2 (Google, Zalo)
✅ TOTP/MFA with backup codes ✅ TOTP/MFA với backup code
✅ Field-level encryption (PII) ✅ Mã hóa cấp field (PII)
✅ CSRF protection middleware ✅ Middleware bảo vệ CSRF
✅ Rate limiting (global + per-user) ✅ Rate limiting (toàn cục + theo user)
✅ HMAC-SHA256 for payment verification ✅ HMAC-SHA256 cho verify thanh toán
✅ Helmet security headers ✅ Header bảo mật Helmet
✅ CORS configured ✅ CORS đã cấu hình
✅ Input validation & sanitization ✅ Validate và sanitize input
--- ---
## 📊 MONITORING & OBSERVABILITY ## 📊 MONITORING & OBSERVABILITY
``` ```
Metrics Prometheus + Grafana (dashboards) Metric Prometheus + Grafana (dashboard)
Logs Pino (structured) + Loki (aggregated) Log Pino (structured) + Loki (tổng hợp)
Tracing Sentry (error tracking) Tracing Sentry (theo dõi lỗi)
Alerts AlertManager (configured) Alert AlertManager (đã cấu hình)
APM Core Web Vitals tracking APM Theo dõi Core Web Vitals
Health Checks /health (liveness), /ready (readiness) 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 ```bash
docker-compose up -d 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 ```bash
docker-compose -f docker-compose.prod.yml up -d 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 ### Lựa chọn 3: Kubernetes
- ConfigMaps for env variables - ConfigMap cho biến env
- Secrets for credentials - Secret cho credential
- PersistentVolumes for database - PersistentVolume cho database
- HPA for auto-scaling - HPA cho auto-scaling
- Ingress for traffic routing - 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-1650 | Xử lý lỗi 404 chi tiết tin đăng | High | todo |
| TEC-1652 | Full E2E test suite validation | High | todo | | TEC-1652 | Validate bộ test E2E đầy đủ | High | todo |
| TEC-1657 | Comprehensive audit logging | High | todo | | TEC-1657 | Audit logging toàn diện | High | todo |
**Impact:** Minimal (edge cases only) **Ảnh hưởng:** Tối thiểu (chỉ edge case)
**Fix ETA:** <2 hours each **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 ├── PROJECT_TRACKER.md ← BẮT ĐẦU TỪ ĐÂY cho trạng thái
├── IMPLEMENTATION_PLAN.md ← Feature roadmap ├── IMPLEMENTATION_PLAN.md ← Roadmap tính năng
├── CODEBASE_OVERVIEW.md ← Comprehensive guide ├── CODEBASE_OVERVIEW.md ← Hướng dẫn toàn diện
├── ARCHITECTURE_SUMMARY.txt ← Visual overview ├── ARCHITECTURE_SUMMARY.txt ← Tổng quan trực quan
└── QUICK_START_REFERENCE.md ← This file └── QUICK_START_REFERENCE.md ← File này
/docs/ /docs/
├── architecture.md ← Technical deep dive ├── architecture.md ← Sâu về kỹ thuật
├── api-endpoints.md ← All endpoints (Swagger) ├── api-endpoints.md ← Tất cả endpoint (Swagger)
├── api-error-codes.md ← Error taxonomy ├── api-error-codes.md ← Phân loại lỗi
├── deployment.md ← Deploy instructions ├── deployment.md ← Hướng dẫn deploy
├── dev-environment.md ← Local setup ├── dev-environment.md ← Setup local
├── RUNBOOK.md ← Operations guide ├── RUNBOOK.md ← Hướng dẫn vận hành
├── PRODUCTION_READINESS.md ← Compliance checklist ├── PRODUCTION_READINESS.md ← Checklist tuân thủ
└── /audits/ ← 80+ implementation audits └── /audits/ ← 80+ audit triển khai
``` ```
--- ---
## 🎯 NEXT STEPS ## 🎯 BƯỚC TIẾP THEO
1. **Understand:** Read `PROJECT_TRACKER.md` (5 min) 1. **Hiểu:** Đọc `PROJECT_TRACKER.md` (5 phút)
2. **Setup:** Run `docker-compose up` (2 min) 2. **Setup:** Chạy `docker-compose up` (2 phút)
3. **Explore:** Visit `http://localhost:3000` (web) & `http://localhost:3001` (API) 3. **Khám phá:** Truy cập `http://localhost:3000` (web) & `http://localhost:3001` (API)
4. **Test:** Run `pnpm test:e2e` to validate (5 min) 4. **Test:** Chạy `pnpm test:e2e` để validate (5 phút)
5. **Deploy:** Use `docker-compose.prod.yml` or Kubernetes manifests 5. **Deploy:** Dùng `docker-compose.prod.yml` hoặc manifest Kubernetes
--- ---
## 🆘 TROUBLESHOOTING ## 🆘 TROUBLESHOOTING
### Port already in use ### Port đang được dùng
```bash ```bash
# Find process using port 3000/3001 # Tìm process đang dùng port 3000/3001
lsof -i :3000 lsof -i :3000
kill -9 <PID> kill -9 <PID>
``` ```
### Database connection failed ### Kết nối database thất bại
```bash ```bash
# Reset database # Reset database
pnpm db:reset pnpm db:reset
@@ -357,69 +357,69 @@ pnpm db:reset
pnpm db:seed pnpm db:seed
``` ```
### Tests failing ### Test thất bại
```bash ```bash
# Clear cache # Xóa cache
rm -rf .turbo rm -rf .turbo
# Reinstall # Cài lại
pnpm install pnpm install
# Run again # Chạy lại
pnpm test pnpm test
``` ```
### Docker issues ### Vấn đề Docker
```bash ```bash
# Complete reset # Reset hoàn toàn
docker-compose down -v docker-compose down -v
docker-compose up --build docker-compose up --build
``` ```
--- ---
## 🎓 LEARNING PATHS ## 🎓 LỘ TRÌNH HỌC
### Backend Development ### Phát Triển Backend
1. Read: `docs/architecture.md` 1. Đọc: `docs/architecture.md`
2. Explore: `apps/api/src/modules/auth` (simplest module) 2. Khám phá: `apps/api/src/modules/auth` (module đơn giản nhất)
3. Understand: DDD layers (presentation → application → domain → infrastructure) 3. Hiểu: Tầng DDD (presentation → application → domain → infrastructure)
4. Practice: Add a new endpoint following the pattern 4. Thực hành: Thêm endpoint mới theo pattern
### Frontend Development ### Phát Triển Frontend
1. Review: `apps/web/app` (route structure) 1. Xem lại: `apps/web/app` (cấu trúc route)
2. Study: `components/listings` (complex component) 2. Nghiên cứu: `components/listings` (component phức tạp)
3. Learn: React Query patterns in `lib/*-api.ts` 3. Học: Pattern React Query trong `lib/*-api.ts`
4. Practice: Create a new feature page 4. Thực hành: Tạo trang tính năng mới
### DevOps ### DevOps
1. Review: `docker-compose.yml` (architecture) 1. Xem lại: `docker-compose.yml` (kiến trúc)
2. Study: `.github/workflows` (CI/CD) 2. Nghiên cứu: `.github/workflows` (CI/CD)
3. Learn: `docs/deployment.md` (production) 3. Học: `docs/deployment.md` (production)
4. Practice: Deploy to staging environment 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 - Dùng `pnpm dev` (từ root) để phát triển tất cả app cùng lúc
- ESLint is configured to catch module boundary violations - ESLint được cấu hình để bắt vi phạm ranh giới module
- Prisma Studio (`pnpm db:studio`) is great for exploring data - Prisma Studio (`pnpm db:studio`) rất tuyệt để khám phá dữ liệu
- Playwright reports are interactive and very helpful - Report Playwright có tính tương tác và rất hữu ích
- PROJECT_TRACKER.md is the source of truth for status - 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 | | Kiểm tra trạng thái | `cat PROJECT_TRACKER.md` | Root |
| Run tests | `pnpm test:e2e` | Root | | Chạy test | `pnpm test:e2e` | Root |
| View API docs | `http://localhost:3001/api` | After startup | | Xem tài liệu API | `http://localhost:3001/api` | Sau khi khởi động |
| See database | `pnpm db:studio` | Root | | Xem database | `pnpm db:studio` | Root |
| Check logs | Grafana/Loki | Docker | | Kiểm tra log | Grafana/Loki | Docker |
| Monitor errors | Sentry dashboard | Configured | | Theo dõi lỗi | Sentry dashboard | Đã cấu hình |
--- ---
**Last Updated:** April 12, 2026 **Cập nhật lần cuối:** 12 tháng 4, 2026
**Project Status:** MVP Complete ✅ — Production Ready 🚀 **Trạng thái dự án:** MVP Hoàn Tất ✅ — Sẵn sàng Production 🚀

469
docs/README_NEW_DOCUMENTATION.md
View File

@@ -1,347 +1,346 @@
# 📚 NEW DOCUMENTATION — Complete Codebase Analysis # 📚 TÀI LIỆU MỚI — Phân Tích Toàn Diện Codebase
**Generated:** April 12, 2026 **Ngày tạo:** 12 tháng 4, 2026
**Purpose:** Comprehensive overview of the GoodGo Platform codebase **Mục đích:** Tổng quan toàn diện về codebase GoodGo Platform
**Status:** ✅ Ready for team onboarding **Trạng thái:** ✅ Sẵn sàng để onboard team
--- ---
## 🎯 WHY THIS DOCUMENTATION EXISTS ## 🎯 VÌ SAO CÓ TÀI LIỆU NÀY
The GoodGo Platform is a sophisticated, enterprise-grade real estate marketplace with: GoodGo Platform là một sàn giao dịch bất động sản cấp doanh nghiệp, tinh vi với:
- 18 backend modules (NestJS) - 18 module backend (NestJS)
- Modern frontend (Next.js 15) - Frontend hiện đại (Next.js 15)
- 31 database models (PostgreSQL 16) - 31 model database (PostgreSQL 16)
- 242 test files - 242 file test
- Complete monitoring & DevOps setup - Hệ thống monitoring & DevOps đầy đủ
**This documentation makes it easy to understand how far along the project is and what to work on next.** **Tài liệu này giúp dễ dàng hiểu được tiến độ dự án và những việc cần làm tiếp theo.**
--- ---
## 📖 DOCUMENTATION FILES CREATED ## 📖 CÁC FILE TÀI LIỆU ĐÃ TẠO
### 1. **EXPLORATION_COMPLETE.md** ← **START HERE** ### 1. **EXPLORATION_COMPLETE.md** ← **BẮT ĐẦU TỪ ĐÂY**
**Best for:** Getting the executive summary **Tốt nhất cho:** Nhận tóm tắt cấp điều hành
**Length:** 2-3 min read **Độ dài:** Đọc trong 2-3 phút
**Contains:** **Nội dung:**
- Project maturity at a glance (95% complete) - Mức độ hoàn thiện dự án (95% hoàn thành)
- What was explored (8 areas) - Những gì đã được khám phá (8 lĩnh vực)
- Key findings with evidence - Các phát hiện chính kèm bằng chứng
- Code statistics - Thống kê code
- Immediate next steps - Các bước tiếp theo cần làm ngay
- New files overview - Tổng quan các file mới
**👉 Read this first to get oriented.** **👉 Đọc file này trước để định hướng.**
--- ---
### 2. **QUICK_START_REFERENCE.md** ### 2. **QUICK_START_REFERENCE.md**
**Best for:** Developers who need quick answers **Tốt nhất cho:** Developer cần câu trả lời nhanh
**Length:** 5-10 min read **Độ dài:** Đọc trong 5-10 phút
**Contains:** **Nội dung:**
- Project maturity table - Bảng đánh giá mức độ hoàn thiện dự án
- Architecture diagram - Sơ đồ kiến trúc
- All common commands (dev, test, deploy) - Tất cả lệnh thông dụng (dev, test, deploy)
- Key files to know - Các file quan trọng cần biết
- Database models overview - Tổng quan các model database
- Troubleshooting guide - Hướng dẫn troubleshooting
- Learning paths by role - Lộ trình học theo vai trò
**👉 Bookmark this for daily reference.** **👉 Bookmark file này để tham khảo hằng ngày.**
--- ---
### 3. **CODEBASE_OVERVIEW.md** ### 3. **CODEBASE_OVERVIEW.md**
**Best for:** Deep technical understanding **Tốt nhất cho:** Hiểu sâu về kỹ thuật
**Length:** 15-20 min read **Độ dài:** Đọc trong 15-20 phút
**Contains:** **Nội dung:**
- 12 comprehensive sections - 12 phần toàn diện
- Top-level directory structure - Cấu trúc thư mục cấp cao
- All 18 API modules documented - Tài liệu cho cả 18 module API
- Frontend structure & components - Cấu trúc và component frontend
- Complete Prisma schema explanation - Giải thích đầy đủ schema Prisma
- Dependencies breakdown - Phân tích dependency
- Test coverage details - Chi tiết test coverage
- Implementation status by phase - Trạng thái triển khai theo từng phase
- Key statistics & metrics - Thống kê và metric chính
**👉 Read this to fully understand the system.** **👉 Đọc file này để hiểu hệ thống một cách trọn vẹn.**
--- ---
### 4. **ARCHITECTURE_SUMMARY.txt** ### 4. **ARCHITECTURE_SUMMARY.txt**
**Best for:** Visual learners, presentations **Tốt nhất cho:** Người học bằng hình ảnh, làm thuyết trình
**Length:** 10-15 min read **Độ dài:** Đọc trong 10-15 phút
**Contains:** **Nội dung:**
- ASCII art architecture diagrams - Sơ đồ kiến trúc bằng ASCII art
- Technology stack visualization - Trực quan hóa tech stack
- API layer organization - Tổ chức tầng API
- Database model breakdown - Phân tích model database
- Frontend layer structure - Cấu trúc tầng frontend
- Testing & QA breakdown - Phân tích testing & QA
- Observability stack - Stack observability
- Implementation progress by phase - Tiến độ triển khai theo phase
- Key metrics - Các metric chính
**👉 Use for presentations or quick visual reference.** **👉 Dùng cho thuyết trình hoặc tham khảo nhanh bằng hình ảnh.**
--- ---
## 🗺️ NAVIGATION GUIDE ## 🗺️ HƯỚNG DẪN ĐIỀU HƯỚNG
### "I need a quick overview" ### "Tôi cần tổng quan nhanh"
→ **EXPLORATION_COMPLETE.md** (2 min) → **EXPLORATION_COMPLETE.md** (2 phút)
### "I'm starting development" ### "Tôi đang bắt đầu phát triển"
→ **QUICK_START_REFERENCE.md** (first 3 sections) → **QUICK_START_REFERENCE.md** (3 phần đầu tiên)
### "I need to understand the architecture" ### "Tôi cần hiểu kiến trúc"
→ **CODEBASE_OVERVIEW.md** (Section 1-3) → **CODEBASE_OVERVIEW.md** (Phần 1-3)
### "I need to understand the API" ### "Tôi cần hiểu API"
→ **CODEBASE_OVERVIEW.md** (Section 2 + docs/api-endpoints.md) → **CODEBASE_OVERVIEW.md** (Phần 2 + docs/api-endpoints.md)
### "I need to understand the database" ### "Tôi cần hiểu database"
→ **CODEBASE_OVERVIEW.md** (Section 4) → **CODEBASE_OVERVIEW.md** (Phần 4)
### "I need deployment steps" ### "Tôi cần các bước deploy"
→ **QUICK_START_REFERENCE.md** (deployment section) or docs/deployment.md → **QUICK_START_REFERENCE.md** (phần deployment) hoặc docs/deployment.md
### "I need to run tests" ### "Tôi cần chạy test"
→ **QUICK_START_REFERENCE.md** (testing section) → **QUICK_START_REFERENCE.md** (phần testing)
### "I need to troubleshoot an issue" ### "Tôi cần troubleshoot một vấn đề"
→ **QUICK_START_REFERENCE.md** (troubleshooting section) → **QUICK_START_REFERENCE.md** (phần troubleshooting)
### "I'm giving a technical presentation" ### "Tôi đang làm bài thuyết trình kỹ thuật"
→ **ARCHITECTURE_SUMMARY.txt** (visual reference) → **ARCHITECTURE_SUMMARY.txt** (tham khảo trực quan)
--- ---
## 📊 PROJECT STATUS SNAPSHOT ## 📊 TÌNH TRẠNG DỰ ÁN
| Metric | Value | Status | | Chỉ số | Giá trị | Trạng thái |
|--------|-------|--------| |--------|-------|--------|
| **Feature Completeness** | 95% | ✅ Nearly done | | **Mức hoàn thiện tính năng** | 95% | ✅ Gần xong |
| **Code Quality** | High | ✅ 242 tests, DDD architecture | | **Chất lượng code** | Cao | ✅ 242 test, kiến trúc DDD |
| **Backend Files** | 845 | ✅ Well organized | | **File backend** | 845 | ✅ Tổ chức tốt |
| **Frontend Files** | 245 | ✅ Modern React setup | | **File frontend** | 245 | ✅ Setup React hiện đại |
| **Database Models** | 31 | ✅ Fully normalized | | **Model database** | 31 | ✅ Chuẩn hóa đầy đủ |
| **API Endpoints** | 100+ | ✅ Documented | | **API endpoint** | 100+ | ✅ Đã tài liệu hóa |
| **Test Files** | 242 | ✅ Comprehensive | | **File test** | 242 | ✅ Toàn diện |
| **Security** | Hardened | ✅ JWT, MFA, encryption | | **Bảo mật** | Đã hardened | ✅ JWT, MFA, mã hóa |
| **DevOps** | Production-Ready | ✅ Docker, Kubernetes | | **DevOps** | Sẵn sàng production | ✅ Docker, Kubernetes |
| **Documentation** | Excellent | ✅ 80+ audit files | | **Tài liệu** | Xuất sắc | ✅ 80+ file audit |
**Overall Status:** ✅ **Production Ready** — Only 3 edge cases remain **Trạng thái tổng thể:** ✅ **Sẵn sàng Production** — Chỉ còn 3 edge case
--- ---
## 🚀 IMMEDIATE ACTIONS ## 🚀 HÀNH ĐỘNG NGAY
### For Team Leads ### Dành cho Team Lead
1. Read **EXPLORATION_COMPLETE.md** (understand status) 1. Đọc **EXPLORATION_COMPLETE.md** (hiểu tình trạng)
2. Share **QUICK_START_REFERENCE.md** with team 2. Chia sẻ **QUICK_START_REFERENCE.md** với team
3. Review **docs/deployment.md** for go-live checklist 3. Xem lại **docs/deployment.md** để chuẩn bị go-live
### For Backend Developers ### Dành cho Backend Developer
1. Read **QUICK_START_REFERENCE.md** (architecture section) 1. Đọc **QUICK_START_REFERENCE.md** (phần kiến trúc)
2. Study **apps/api/src/modules/auth** (simplest module) 2. Nghiên cứu **apps/api/src/modules/auth** (module đơn giản nhất)
3. Review **docs/architecture.md** (design patterns) 3. Xem lại **docs/architecture.md** (design pattern)
### For Frontend Developers ### Dành cho Frontend Developer
1. Read **QUICK_START_REFERENCE.md** (architecture section) 1. Đọc **QUICK_START_REFERENCE.md** (phần kiến trúc)
2. Review **apps/web/app** (route structure) 2. Xem lại **apps/web/app** (cấu trúc route)
3. Study **components/listings** (complex component) 3. Nghiên cứu **components/listings** (component phức tạp)
### For DevOps/Platform Engineers ### Dành cho DevOps/Platform Engineer
1. Read **QUICK_START_REFERENCE.md** (deployment section) 1. Đọc **QUICK_START_REFERENCE.md** (phần deployment)
2. Study **docker-compose.yml** and **docker-compose.prod.yml** 2. Nghiên cứu **docker-compose.yml** và **docker-compose.prod.yml**
3. Review **docs/deployment.md** and **docs/RUNBOOK.md** 3. Xem lại **docs/deployment.md** và **docs/RUNBOOK.md**
--- ---
## 📋 WHAT EACH FILE COVERS ## 📋 NỘI DUNG CỦA TỪNG FILE
### EXPLORATION_COMPLETE.md ### EXPLORATION_COMPLETE.md
``` ```
✓ What was explored (8 areas) ✓ Những gì đã được khám phá (8 lĩnh vực)
✓ Project maturity breakdown ✓ Phân tích mức độ hoàn thiện
✓ Key findings with metrics ✓ Phát hiện chính kèm metric
✓ Remaining work (3 items) ✓ Công việc còn lại (3 mục)
✓ New documentation overview ✓ Tổng quan tài liệu mới
✓ Next steps for team ✓ Các bước tiếp theo cho team
✓ Key insights & recommendations ✓ Insight và khuyến nghị chính
``` ```
### QUICK_START_REFERENCE.md ### QUICK_START_REFERENCE.md
``` ```
✓ Project maturity snapshot ✓ Tổng quan mức hoàn thiện dự án
✓ Architecture at a glance ✓ Kiến trúc tổng quan
✓ Quick commands (dev, test, deploy) ✓ Lệnh nhanh (dev, test, deploy)
✓ Key files to know ✓ File quan trọng cần biết
✓ API modules overview (18 modules) ✓ Tổng quan API module (18 module)
✓ Database models (31 total) ✓ Model database (tổng 31)
✓ Testing breakdown ✓ Phân tích testing
✓ Security features ✓ Tính năng bảo mật
✓ Deployment options (3) ✓ Lựa chọn deploy (3 cách)
✓ Troubleshooting ✓ Troubleshooting
✓ Learning paths by role ✓ Lộ trình học theo vai trò
``` ```
### CODEBASE_OVERVIEW.md ### CODEBASE_OVERVIEW.md
``` ```
✓ Top-level directory structure ✓ Cấu trúc thư mục cấp cao
✓ All 18 API modules detailed ✓ Chi tiết cho cả 18 module API
✓ Frontend structure (routes + components) ✓ Cấu trúc frontend (route + component)
✓ Database schema (31 models) ✓ Schema database (31 model)
✓ Documentation & tracking ✓ Tài liệu và theo dõi
✓ Dependencies breakdown ✓ Phân tích dependency
✓ Test coverage details (242 files) ✓ Chi tiết test coverage (242 file)
✓ Implementation status (all 7 phases) ✓ Trạng thái triển khai (cả 7 phase)
✓ Project maturity indicators ✓ Chỉ số mức hoàn thiện dự án
✓ Statistics & metrics ✓ Thống kê và metric
✓ Tech stack summary ✓ Tóm tắt tech stack
✓ Next steps ✓ Bước tiếp theo
``` ```
### ARCHITECTURE_SUMMARY.txt ### ARCHITECTURE_SUMMARY.txt
``` ```
✓ Tech stack visual ✓ Trực quan tech stack
✓ API layer diagram ✓ Sơ đồ tầng API
✓ Database entity diagram ✓ Sơ đồ entity database
✓ Frontend layer diagram ✓ Sơ đồ tầng frontend
✓ Testing breakdown ✓ Phân tích testing
✓ Observability stack ✓ Stack observability
✓ Implementation progress ✓ Tiến độ triển khai
✓ Key metrics ✓ Các metric chính
✓ Project maturity assessment ✓ Đánh giá mức hoàn thiện dự án
``` ```
--- ---
## 🎓 LEARNING SEQUENCES ## 🎓 LỘ TRÌNH HỌC
### Backend Developer Onboarding (2-3 hours) ### Onboarding Backend Developer (2-3 giờ)
1. **EXPLORATION_COMPLETE.md** (5 min) — Understand status 1. **EXPLORATION_COMPLETE.md** (5 phút) — Hiểu tình trạng
2. **QUICK_START_REFERENCE.md** architecture section (10 min) — Visual overview 2. **QUICK_START_REFERENCE.md** phần kiến trúc (10 phút) — Tổng quan trực quan
3. `pnpm dev` (5 min) — Get environment running 3. `pnpm dev` (5 phút) — Khởi động môi trường
4. **docs/architecture.md** (30 min) — Learn DDD/CQRS patterns 4. **docs/architecture.md** (30 phút) — Học pattern DDD/CQRS
5. `apps/api/src/modules/auth` (30 min) — Study simplest module 5. `apps/api/src/modules/auth` (30 phút) — Nghiên cứu module đơn giản nhất
6. **CODEBASE_OVERVIEW.md** section 2 (20 min) — Understand all modules 6. **CODEBASE_OVERVIEW.md** phần 2 (20 phút) — Hiểu tất cả module
7. Add a simple feature (60 min) — Hands-on learning 7. Thêm một tính năng đơn giản (60 phút) — Học thực hành
### Frontend Developer Onboarding (2-3 hours) ### Onboarding Frontend Developer (2-3 giờ)
1. **EXPLORATION_COMPLETE.md** (5 min) — Understand status 1. **EXPLORATION_COMPLETE.md** (5 phút) — Hiểu tình trạng
2. **QUICK_START_REFERENCE.md** architecture section (10 min) — Visual overview 2. **QUICK_START_REFERENCE.md** phần kiến trúc (10 phút) — Tổng quan trực quan
3. `pnpm dev` (5 min) — Get environment running 3. `pnpm dev` (5 phút) — Khởi động môi trường
4. `apps/web/app` (20 min) — Learn route structure 4. `apps/web/app` (20 phút) — Học cấu trúc route
5. **CODEBASE_OVERVIEW.md** section 3 (20 min) — Understand components 5. **CODEBASE_OVERVIEW.md** phần 3 (20 phút) — Hiểu các component
6. `components/listings` (30 min) — Study complex component 6. `components/listings` (30 phút) — Nghiên cứu component phức tạp
7. Create a simple page (60 min) — Hands-on learning 7. Tạo một trang đơn giản (60 phút) — Học thực hành
### DevOps/Platform Engineer Onboarding (2-3 hours) ### Onboarding DevOps/Platform Engineer (2-3 giờ)
1. **EXPLORATION_COMPLETE.md** (5 min) — Understand status 1. **EXPLORATION_COMPLETE.md** (5 phút) — Hiểu tình trạng
2. **QUICK_START_REFERENCE.md** deployment section (15 min) — Overview 2. **QUICK_START_REFERENCE.md** phần deployment (15 phút) — Tổng quan
3. `docker-compose up` (5 min) — Get environment running 3. `docker-compose up` (5 phút) — Khởi động môi trường
4. **docs/deployment.md** (30 min) — Learn deployment steps 4. **docs/deployment.md** (30 phút) — Học các bước deploy
5. **docs/RUNBOOK.md** (30 min) — Learn operations 5. **docs/RUNBOOK.md** (30 phút) — Học vận hành
6. Study Kubernetes manifests (20 min) — Production setup 6. Nghiên cứu manifest Kubernetes (20 phút) — Setup production
7. Test deployment to staging (60 min) — Hands-on learning 7. Test deploy lên staging (60 phút) — Học thực hành
--- ---
## ✅ VERIFICATION CHECKLIST ## ✅ CHECKLIST KIỂM TRA
Use this to verify you have everything you need: Dùng để xác nhận bạn đã có đầy đủ những gì cần thiết:
- [ ] Read EXPLORATION_COMPLETE.md - [ ] Đã đọc EXPLORATION_COMPLETE.md
- [ ] Found QUICK_START_REFERENCE.md in root - [ ] Đã tìm thấy QUICK_START_REFERENCE.md ở thư mục gốc
- [ ] Found CODEBASE_OVERVIEW.md in root - [ ] Đã tìm thấy CODEBASE_OVERVIEW.md ở thư mục gốc
- [ ] Found ARCHITECTURE_SUMMARY.txt in root - [ ] Đã tìm thấy ARCHITECTURE_SUMMARY.txt ở thư mục gốc
- [ ] Can run `docker-compose up` - [ ] Có thể chạy `docker-compose up`
- [ ] Can run `pnpm test:e2e` - [ ] Có thể chạy `pnpm test:e2e`
- [ ] Can access `http://localhost:3000` (frontend) - [ ] Truy cập được `http://localhost:3000` (frontend)
- [ ] Can access `http://localhost:3001` (API) - [ ] Truy cập được `http://localhost:3001` (API)
- [ ] Understand PROJECT_TRACKER.md status - [ ] Hiểu trạng thái trong PROJECT_TRACKER.md
- [ ] Know the 3 remaining Phase 7 issues - [ ] Biết 3 issue còn lại của Phase 7
--- ---
## 🔗 RELATED DOCUMENTATION ## 🔗 TÀI LIỆU LIÊN QUAN
These pre-existing files contain additional valuable information: Các file đã có sẵn dưới đây chứa thêm thông tin giá trị:
**Planning & Status:** **Lập kế hoạch & Trạng thái:**
- `PROJECT_TRACKER.md` — All phases, issues, and current status - `PROJECT_TRACKER.md` — Tất cả phase, issue và trạng thái hiện tại
- `IMPLEMENTATION_PLAN.md` — Feature roadmap - `IMPLEMENTATION_PLAN.md` — Roadmap tính năng
**Technical:** **Kỹ thuật:**
- `docs/architecture.md` — DDD/CQRS patterns - `docs/architecture.md` — Pattern DDD/CQRS
- `docs/api-endpoints.md` — All endpoints (Swagger) - `docs/api-endpoints.md` — Tất cả endpoint (Swagger)
- `docs/api-error-codes.md` — Error taxonomy - `docs/api-error-codes.md` — Phân loại lỗi
- `prisma/schema.prisma` — Database schema - `prisma/schema.prisma` — Schema database
**Operations:** **Vận hành:**
- `docs/deployment.md` — Deployment procedures - `docs/deployment.md` — Quy trình deploy
- `docs/RUNBOOK.md` — Troubleshooting guide - `docs/RUNBOOK.md` — Hướng dẫn troubleshoot
- `docker-compose.yml` — Local development - `docker-compose.yml` — Phát triển local
- `docker-compose.prod.yml` — Production stack - `docker-compose.prod.yml` — Stack production
**Audits:** **Audit:**
- `docs/audits/` — 80+ implementation audits - `docs/audits/` — 80+ audit triển khai
--- ---
## 💡 PRO TIPS ## 💡 MẸO HAY
1. **Bookmark QUICK_START_REFERENCE.md** for daily reference 1. **Bookmark QUICK_START_REFERENCE.md** để tham khảo hằng ngày
2. **Keep PROJECT_TRACKER.md** handy for status updates 2. **Giữ PROJECT_TRACKER.md** sẵn sàng cho cập nhật trạng thái
3. **Use Prisma Studio** (`pnpm db:studio`) to explore the database 3. **Dùng Prisma Studio** (`pnpm db:studio`) để khám phá database
4. **Review docs/RUNBOOK.md** before going on-call 4. **Xem lại docs/RUNBOOK.md** trước khi trực on-call
5. **Check docs/architecture.md** before proposing changes 5. **Kiểm tra docs/architecture.md** trước khi đề xuất thay đổi
6. **Run tests frequently** (`pnpm test:e2e`) to catch issues early 6. **Chạy test thường xuyên** (`pnpm test:e2e`) để phát hiện sớm vấn đề
--- ---
## 📞 QUESTIONS? ## 📞 CÂU HỎI?
| Question | Answer Location | | Câu hỏi | Vị trí trả lời |
|----------|-----------------| |----------|-----------------|
| "What's the current status?" | EXPLORATION_COMPLETE.md | | "Tình trạng hiện tại thế nào?" | EXPLORATION_COMPLETE.md |
| "How do I start development?" | QUICK_START_REFERENCE.md | | "Làm sao để bắt đầu phát triển?" | QUICK_START_REFERENCE.md |
| "How does the system work?" | CODEBASE_OVERVIEW.md | | "Hệ thống hoạt động ra sao?" | CODEBASE_OVERVIEW.md |
| "What's the tech stack?" | ARCHITECTURE_SUMMARY.txt | | "Tech stack là gì?" | ARCHITECTURE_SUMMARY.txt |
| "How do I deploy?" | docs/deployment.md | | "Làm sao để deploy?" | docs/deployment.md |
| "How do I troubleshoot?" | docs/RUNBOOK.md | | "Làm sao để troubleshoot?" | docs/RUNBOOK.md |
| "What's the database model?" | prisma/schema.prisma | | "Model database là gì?" | prisma/schema.prisma |
| "What are the remaining tasks?" | PROJECT_TRACKER.md | | "Còn task nào chưa làm?" | PROJECT_TRACKER.md |
--- ---
## 📈 NEXT REVIEW DATE ## 📈 NGÀY REVIEW TIẾP THEO
**Recommended Review:** May 1, 2026 **Đề xuất review:** 1 tháng 5, 2026
**Update Trigger:** When Phase 7 completes or major features ship **Trigger cập nhật:** Khi Phase 7 hoàn tất hoặc có tính năng lớn được ship
--- ---
## 📝 DOCUMENT MANIFEST ## 📝 DANH MỤC TÀI LIỆU
| File | Size | Purpose | Audience | | File | Kích thước | Mục đích | Đối tượng |
|------|------|---------|----------| |------|------|---------|----------|
| EXPLORATION_COMPLETE.md | 9 KB | Executive summary | Everyone | | EXPLORATION_COMPLETE.md | 9 KB | Tóm tắt điều hành | Mọi người |
| QUICK_START_REFERENCE.md | 12 KB | Developer guide | Developers | | QUICK_START_REFERENCE.md | 12 KB | Hướng dẫn developer | Developer |
| CODEBASE_OVERVIEW.md | 15 KB | Technical reference | Tech leads | | CODEBASE_OVERVIEW.md | 15 KB | Tham khảo kỹ thuật | Tech lead |
| ARCHITECTURE_SUMMARY.txt | 24 KB | Visual overview | Presenters | | ARCHITECTURE_SUMMARY.txt | 24 KB | Tổng quan trực quan | Người thuyết trình |
**Total:** 60 KB of new documentation **Tổng cộng:** 60 KB tài liệu mới
**Generated:** April 12, 2026 **Ngày tạo:** 12 tháng 4, 2026
**Time to Read:** 30-45 minutes (all four) **Thời gian đọc:** 30-45 phút (cả bốn file)
**Value:** Foundation for team onboarding **Giá trị:** Nền tảng cho onboarding team
--- ---
**Start with EXPLORATION_COMPLETE.md — you'll understand the project in 2 minutes! 🚀** **Bắt đầu với EXPLORATION_COMPLETE.md — bạn sẽ hiểu dự án trong 2 phút! 🚀**

1014
docs/RUNBOOK.md
View File

File diff suppressed because it is too large Load Diff

266
docs/api-endpoints.md
View File

@@ -1,252 +1,252 @@
# API Endpoints Reference # Tham Khảo API Endpoint
All routes are prefixed with `/api/v1/` except health checks. Authentication uses Bearer JWT tokens. Tất cả route được prefix với `/api/v1/` ngoại trừ health check. Authentication dùng Bearer JWT token.
> **Interactive docs**: Swagger UI is available at `http://localhost:3001/api/v1/docs` when running the API locally. > **Tài liệu tương tác**: Swagger UI có sẵn tại `http://localhost:3001/api/v1/docs` khi chạy API local.
## Auth (`/auth`) ## Auth (`/auth`)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| POST | `/auth/register` | Public | Register a new user | | POST | `/auth/register` | Public | Đăng ký user mới |
| POST | `/auth/login` | Public | Login with phone and password | | POST | `/auth/login` | Public | Đăng nhập bằng số điện thoại và mật khẩu |
| POST | `/auth/refresh` | Cookie | Refresh access token using httpOnly refresh cookie | | POST | `/auth/refresh` | Cookie | Làm mới access token bằng cookie refresh httpOnly |
| POST | `/auth/logout` | JWT | Logout and clear auth cookies | | POST | `/auth/logout` | JWT | Đăng xuất và xóa cookie auth |
| POST | `/auth/exchange-token` | Public | Exchange OAuth token pair for httpOnly cookies | | POST | `/auth/exchange-token` | Public | Trao đổi cặp token OAuth lấy cookie httpOnly |
| GET | `/auth/profile` | JWT | Get current user profile | | GET | `/auth/profile` | JWT | Lấy hồ sơ user hiện tại |
| GET | `/auth/profile/agent` | JWT | Get agent profile for current user | | GET | `/auth/profile/agent` | JWT | Lấy hồ sơ agent của user hiện tại |
| PATCH | `/auth/kyc` | Admin | Verify user KYC status | | PATCH | `/auth/kyc` | Admin | Verify trạng thái KYC của user |
### OAuth ### OAuth
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| GET | `/auth/google` | Public | Initiate Google OAuth2 login | | GET | `/auth/google` | Public | Khởi tạo đăng nhập Google OAuth2 |
| GET | `/auth/google/callback` | Public | Google OAuth2 callback | | GET | `/auth/google/callback` | Public | Callback Google OAuth2 |
| GET | `/auth/zalo` | Public | Initiate Zalo OAuth2 login | | GET | `/auth/zalo` | Public | Khởi tạo đăng nhập Zalo OAuth2 |
| GET | `/auth/zalo/callback` | Public | Zalo OAuth2 callback | | GET | `/auth/zalo/callback` | Public | Callback Zalo OAuth2 |
### User Data (GDPR) ### Dữ Liệu User (GDPR)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| DELETE | `/users/me` | JWT | Request account deletion (30-day grace period) | | DELETE | `/users/me` | JWT | Yêu cầu xóa tài khoản (thời hạn 30 ngày) |
| POST | `/users/me/cancel-deletion` | JWT | Cancel pending account deletion | | POST | `/users/me/cancel-deletion` | JWT | Hủy yêu cầu xóa tài khoản đang chờ |
| GET | `/users/me/export` | JWT | Export user data (GDPR Article 20) | | GET | `/users/me/export` | JWT | Export dữ liệu user (GDPR Điều 20) |
| DELETE | `/users/:id/force` | Admin | Force-delete user immediately | | DELETE | `/users/:id/force` | Admin | Force-delete user ngay lập tức |
--- ---
## Listings (`/listings`) ## Listings (`/listings`)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| POST | `/listings` | JWT + Quota | Create a new property listing | | POST | `/listings` | JWT + Quota | Tạo tin đăng bất động sản mới |
| GET | `/listings` | Public | Search and filter property listings | | GET | `/listings` | Public | Tìm kiếm và lọc tin đăng |
| GET | `/listings/pending` | Admin | Get listings pending moderation | | GET | `/listings/pending` | Admin | Lấy tin đăng đang chờ duyệt |
| GET | `/listings/:id` | Public | Get listing details by ID | | GET | `/listings/:id` | Public | Lấy chi tiết tin đăng theo ID |
| PATCH | `/listings/:id/status` | JWT | Update listing status | | PATCH | `/listings/:id/status` | JWT | Cập nhật trạng thái tin đăng |
| POST | `/listings/:id/media` | JWT | Upload media (multipart file upload) | | POST | `/listings/:id/media` | JWT | Upload media (multipart file upload) |
| PATCH | `/listings/:id/moderate` | Admin | Moderate a listing | | PATCH | `/listings/:id/moderate` | Admin | Duyệt một tin đăng |
--- ---
## Search (`/search`) ## Search (`/search`)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| GET | `/search` | Public | Full-text and faceted property search | | GET | `/search` | Public | Tìm kiếm bất động sản full-text và faceted |
| GET | `/search/geo` | Public | Geographic radius search | | GET | `/search/geo` | Public | Tìm kiếm theo bán kính địa lý |
| POST | `/search/reindex` | Admin | Reindex all properties in Typesense | | POST | `/search/reindex` | Admin | Reindex tất cả bất động sản trong Typesense |
### Saved Searches (`/saved-searches`) ### Saved Search (`/saved-searches`)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| POST | `/saved-searches` | JWT | Save search filters | | POST | `/saved-searches` | JWT | Lưu bộ lọc tìm kiếm |
| GET | `/saved-searches` | JWT | List saved searches | | GET | `/saved-searches` | JWT | Liệt kê các tìm kiếm đã lưu |
| GET | `/saved-searches/:id` | JWT | Get saved search details | | GET | `/saved-searches/:id` | JWT | Lấy chi tiết tìm kiếm đã lưu |
| PATCH | `/saved-searches/:id` | JWT | Update saved search | | PATCH | `/saved-searches/:id` | JWT | Cập nhật tìm kiếm đã lưu |
| DELETE | `/saved-searches/:id` | JWT | Delete saved search | | DELETE | `/saved-searches/:id` | JWT | Xóa tìm kiếm đã lưu |
--- ---
## Payments (`/payments`) ## Payments (`/payments`)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| POST | `/payments` | JWT | Create a new payment | | POST | `/payments` | JWT | Tạo thanh toán mới |
| GET | `/payments` | JWT | List transactions for authenticated user | | GET | `/payments` | JWT | Liệt kê giao dịch của user đã xác thực |
| GET | `/payments/:id` | JWT | Get payment status by ID | | GET | `/payments/:id` | JWT | Lấy trạng thái thanh toán theo ID |
| POST | `/payments/:id/refund` | Admin | Refund a payment | | POST | `/payments/:id/refund` | Admin | Hoàn tiền một thanh toán |
| POST | `/payments/callback/:provider` | Public | Payment provider webhook (VNPay, MoMo, ZaloPay) | | POST | `/payments/callback/:provider` | Public | Webhook nhà cung cấp thanh toán (VNPay, MoMo, ZaloPay) |
--- ---
## Subscriptions (`/subscriptions`) ## Subscriptions (`/subscriptions`)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| GET | `/subscriptions/plans` | Public | List all subscription plans | | GET | `/subscriptions/plans` | Public | Liệt kê tất cả plan subscription |
| GET | `/subscriptions/plans/:tier` | Public | Get subscription plan by tier | | GET | `/subscriptions/plans/:tier` | Public | Lấy plan subscription theo tier |
| POST | `/subscriptions` | JWT | Create a new subscription | | POST | `/subscriptions` | JWT | Tạo subscription mới |
| PUT | `/subscriptions/upgrade` | JWT | Upgrade existing subscription | | PUT | `/subscriptions/upgrade` | JWT | Nâng cấp subscription hiện tại |
| DELETE | `/subscriptions` | JWT | Cancel active subscription | | DELETE | `/subscriptions` | JWT | Hủy subscription đang hoạt động |
| POST | `/subscriptions/usage` | JWT | Record metered usage | | POST | `/subscriptions/usage` | JWT | Ghi nhận lượng sử dụng metered |
| GET | `/subscriptions/quota/:metric` | JWT | Check remaining quota for a metric | | GET | `/subscriptions/quota/:metric` | JWT | Kiểm tra quota còn lại theo metric |
| GET | `/subscriptions/billing` | JWT | Get billing history | | GET | `/subscriptions/billing` | JWT | Lấy lịch sử thanh toán |
--- ---
## Admin (`/admin`) ## Admin (`/admin`)
### User Management ### Quản Lý User
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| GET | `/admin/users` | Admin | List users with optional filters | | GET | `/admin/users` | Admin | Liệt kê user với bộ lọc tùy chọn |
| GET | `/admin/users/:id` | Admin | Get user details by ID | | GET | `/admin/users/:id` | Admin | Lấy chi tiết user theo ID |
| PATCH | `/admin/users/status` | Admin | Update user active status | | PATCH | `/admin/users/status` | Admin | Cập nhật trạng thái active của user |
| POST | `/admin/users/ban` | Admin | Ban or unban a user | | POST | `/admin/users/ban` | Admin | Ban hoặc unban user |
| POST | `/admin/subscriptions/adjust` | Admin | Adjust user subscription plan | | POST | `/admin/subscriptions/adjust` | Admin | Điều chỉnh plan subscription của user |
| GET | `/admin/dashboard` | Admin | Get admin dashboard statistics | | GET | `/admin/dashboard` | Admin | Lấy thống kê dashboard admin |
| GET | `/admin/revenue` | Admin | Get revenue statistics by date range | | GET | `/admin/revenue` | Admin | Lấy thống kê doanh thu theo khoảng ngày |
| GET | `/admin/audit-logs` | Admin | Get admin audit logs | | GET | `/admin/audit-logs` | Admin | Lấy audit log admin |
### Moderation ### Moderation
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| GET | `/admin/moderation` | Admin | Get listing moderation queue | | GET | `/admin/moderation` | Admin | Lấy hàng đợi duyệt tin đăng |
| POST | `/admin/moderation/approve` | Admin | Approve a listing | | POST | `/admin/moderation/approve` | Admin | Duyệt một tin đăng |
| POST | `/admin/moderation/reject` | Admin | Reject a listing | | POST | `/admin/moderation/reject` | Admin | Từ chối một tin đăng |
| POST | `/admin/moderation/bulk` | Admin | Bulk approve or reject listings | | POST | `/admin/moderation/bulk` | Admin | Duyệt hoặc từ chối tin đăng hàng loạt |
| GET | `/admin/kyc` | Admin | Get KYC verification queue | | GET | `/admin/kyc` | Admin | Lấy hàng đợi xác minh KYC |
| POST | `/admin/kyc/approve` | Admin | Approve KYC verification | | POST | `/admin/kyc/approve` | Admin | Duyệt xác minh KYC |
| POST | `/admin/kyc/reject` | Admin | Reject KYC verification | | POST | `/admin/kyc/reject` | Admin | Từ chối xác minh KYC |
--- ---
## Notifications (`/notifications`) ## Notifications (`/notifications`)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| GET | `/notifications/history` | JWT | Get notification history | | GET | `/notifications/history` | JWT | Lấy lịch sử thông báo |
| GET | `/notifications/preferences` | JWT | Get notification preferences | | GET | `/notifications/preferences` | JWT | Lấy tùy chọn thông báo |
| PUT | `/notifications/preferences` | JWT | Update notification preferences | | PUT | `/notifications/preferences` | JWT | Cập nhật tùy chọn thông báo |
| GET | `/notifications/unread` | JWT | Get unread notifications | | GET | `/notifications/unread` | JWT | Lấy thông báo chưa đọc |
| PATCH | `/notifications/:id/read` | JWT | Mark notification as read | | PATCH | `/notifications/:id/read` | JWT | Đánh dấu thông báo đã đọc |
| PATCH | `/notifications/read-all` | JWT | Mark all notifications as read | | PATCH | `/notifications/read-all` | JWT | Đánh dấu tất cả thông báo đã đọc |
| GET | `/notifications/templates` | JWT | Get available notification templates | | GET | `/notifications/templates` | JWT | Lấy các template thông báo có sẵn |
--- ---
## Analytics (`/analytics`) ## Analytics (`/analytics`)
All analytics endpoints require JWT and are quota-guarded. Tất cả endpoint analytics yêu cầu JWT và được giới hạn theo quota.
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| GET | `/analytics/market-report` | JWT + Quota | Get market report for a city | | GET | `/analytics/market-report` | JWT + Quota | Lấy báo cáo thị trường cho một thành phố |
| GET | `/analytics/price-trend` | JWT + Quota | Get price trend for a district | | GET | `/analytics/price-trend` | JWT + Quota | Lấy xu hướng giá cho một quận |
| GET | `/analytics/heatmap` | JWT + Quota | Get price heatmap for a city | | GET | `/analytics/heatmap` | JWT + Quota | Lấy heatmap giá cho một thành phố |
| GET | `/analytics/district-stats` | JWT + Quota | Get statistics by district | | GET | `/analytics/district-stats` | JWT + Quota | Lấy thống kê theo quận |
| GET | `/analytics/valuation` | JWT + Quota | Get automated property valuation (AVM) | | GET | `/analytics/valuation` | JWT + Quota | Lấy định giá bất động sản tự động (AVM) |
--- ---
## Agents (`/agents`) ## Agents (`/agents`)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| GET | `/agents/me/dashboard` | Agent | Get agent dashboard stats | | GET | `/agents/me/dashboard` | Agent | Lấy thống kê dashboard agent |
| POST | `/agents/:agentId/recalculate-score` | Admin | Recalculate agent quality score | | POST | `/agents/:agentId/recalculate-score` | Admin | Tính lại điểm chất lượng agent |
--- ---
## Inquiries (`/inquiries`) ## Inquiries (`/inquiries`)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| POST | `/inquiries` | JWT | Create inquiry for a listing | | POST | `/inquiries` | JWT | Tạo inquiry cho một tin đăng |
| GET | `/inquiries/listing/:listingId` | JWT | List inquiries by listing | | GET | `/inquiries/listing/:listingId` | JWT | Liệt kê inquiry theo tin đăng |
| GET | `/inquiries/agent/me` | Agent | List inquiries for current agent | | GET | `/inquiries/agent/me` | Agent | Liệt kê inquiry cho agent hiện tại |
| PATCH | `/inquiries/:id/read` | Agent | Mark inquiry as read | | PATCH | `/inquiries/:id/read` | Agent | Đánh dấu inquiry đã đọc |
--- ---
## Leads (`/leads`) ## Leads (`/leads`)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| POST | `/leads` | Agent | Create lead | | POST | `/leads` | Agent | Tạo lead |
| GET | `/leads` | Agent | List leads for agent | | GET | `/leads` | Agent | Liệt kê lead cho agent |
| GET | `/leads/stats` | Agent | Get lead statistics | | GET | `/leads/stats` | Agent | Lấy thống kê lead |
| PATCH | `/leads/:id/status` | Agent | Update lead status | | PATCH | `/leads/:id/status` | Agent | Cập nhật trạng thái lead |
| DELETE | `/leads/:id` | Agent | Delete lead | | DELETE | `/leads/:id` | Agent | Xóa lead |
--- ---
## Reviews (`/reviews`) ## Reviews (`/reviews`)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| POST | `/reviews` | JWT | Create a review | | POST | `/reviews` | JWT | Tạo một review |
| GET | `/reviews` | Public | List reviews by target | | GET | `/reviews` | Public | Liệt kê review theo target |
| GET | `/reviews/stats` | Public | Get aggregate rating stats for a target | | GET | `/reviews/stats` | Public | Lấy thống kê đánh giá tổng hợp cho một target |
| GET | `/reviews/me` | JWT | Get reviews by authenticated user | | GET | `/reviews/me` | JWT | Lấy review của user đã xác thực |
| DELETE | `/reviews/:id` | JWT | Delete own review | | DELETE | `/reviews/:id` | JWT | Xóa review của chính mình |
--- ---
## Health (`/health`) ## Health (`/health`)
Health endpoints are **not** prefixed with `/api/v1/`. Endpoint health **không** prefix với `/api/v1/`.
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| GET | `/health` | Public | Liveness probe | | GET | `/health` | Public | Liveness probe |
| GET | `/health/ready` | Public | Readiness probe (DB + Redis) | | GET | `/health/ready` | Public | Readiness probe (DB + Redis) |
| GET | `/health/db` | Public | Database connectivity check | | GET | `/health/db` | Public | Kiểm tra kết nối database |
| GET | `/health/redis` | Public | Redis connectivity check | | GET | `/health/redis` | Public | Kiểm tra kết nối Redis |
--- ---
## MCP (`/mcp`) ## MCP (`/mcp`)
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| GET | `/mcp/servers` | JWT | List available MCP servers | | GET | `/mcp/servers` | JWT | Liệt kê các MCP server có sẵn |
| GET | `/mcp/:serverName/sse` | JWT | Open SSE connection to MCP server | | GET | `/mcp/:serverName/sse` | JWT | Mở kết nối SSE đến MCP server |
| POST | `/mcp/:serverName/messages` | JWT | Send message to MCP server session | | POST | `/mcp/:serverName/messages` | JWT | Gửi message tới session MCP server |
--- ---
## Metrics ## Metrics
| Method | Path | Auth | Description | | Method | Path | Auth | Mô tả |
|--------|------|------|-------------| |--------|------|------|-------------|
| POST | `/web-vitals` | Public | Ingest Core Web Vitals metrics | | POST | `/web-vitals` | Public | Ingest metric Core Web Vitals |
--- ---
## Authentication Summary ## Tóm Tắt Authentication
| Auth Type | Description | | Loại Auth | Mô tả |
|-----------|-------------| |-----------|-------------|
| **Public** | No authentication required | | **Public** | Không yêu cầu authentication |
| **JWT** | Requires `Authorization: Bearer <token>` header | | **JWT** | Yêu cầu header `Authorization: Bearer <token>` |
| **Admin** | JWT + `ADMIN` role required | | **Admin** | JWT + role `ADMIN` |
| **Agent** | JWT + `AGENT` role required | | **Agent** | JWT + role `AGENT` |
| **Quota** | JWT + subscription quota enforcement | | **Quota** | JWT + giới hạn quota subscription |
| **Cookie** | Uses httpOnly refresh token cookie | | **Cookie** | Dùng cookie refresh token httpOnly |
## Rate Limiting ## Rate Limiting
The following endpoints have stricter rate limits: Các endpoint sau có rate limit nghiêm ngặt hơn:
- Auth endpoints (register, login, refresh): `10 req/60s` - Endpoint Auth (register, login, refresh): `10 req/60s`
- OAuth callbacks: `10 req/60s` - OAuth callback: `10 req/60s`
- Payment callbacks: `60 req/60s` - Payment callback: `60 req/60s`
- MCP endpoints: `30 req/60s` - Endpoint MCP: `30 req/60s`
- Default: `60 req/60s` - Mặc định: `60 req/60s`

347
docs/architecture/CODEBASE_OVERVIEW.md
View File

@@ -1,11 +1,11 @@
# GoodGo Platform — Comprehensive Codebase Overview # Nền tảng GoodGo — Tổng quan toàn diện về Codebase
**Generated:** April 12, 2026 **Được tạo:** Ngày 12 tháng 4 năm 2026
**Project Status:** MVP Complete — Phase 7 Wave 14 ✅ Build Green **Trạng thái dự án:** MVP hoàn thành — Phase 7 Wave 14 ✅ Build Green
--- ---
## 1. TOP-LEVEL DIRECTORY STRUCTURE ## 1. CẤU TRÚC THƯ MỤC CẤP CAO NHẤT
``` ```
goodgo-platform-ai/ goodgo-platform-ai/
@@ -39,69 +39,69 @@ goodgo-platform-ai/
--- ---
## 2. API MODULES (`apps/api/src/modules/`) — 18 MODULES ## 2. CÁC MODULE API (`apps/api/src/modules/`) — 18 MODULE
### Core Authentication & Authorization ### Xác thực & Phân quyền cốt lõi
- **auth/** — JWT, OAuth (Google/Zalo), MFA, TOTP backup codes - **auth/** — JWT, OAuth (Google/Zalo), MFA, mã dự phòng TOTP
- Subdirs: application, domain, infrastructure, presentation, __tests__ - Thư mục con: application, domain, infrastructure, presentation, __tests__
- Key: JWT guards, passport strategies, role-based access - Chính: JWT guards, passport strategies, phân quyền dựa trên vai trò
### Listings & Properties ### Listings & Bất động sản
- **listings/** — CRUD, status management, media, AI price estimates - **listings/** — CRUD, quản lý trạng thái, media, AI ước tính giá
- Moderation scoring, featured listings, expiration logic - Chấm điểm kiểm duyệt, listing nổi bật, logic hết hạn
- Media upload with pre-signed URLs (AWS S3) - Upload media với pre-signed URL (AWS S3)
### Search & Discovery ### Search & Khám phá
- **search/** — Typesense integration (full-text), geospatial (PostGIS) - **search/** — Tích hợp Typesense (full-text), geospatial (PostGIS)
- Resilient repository with fallback to PostgreSQL - Repository có khả năng phục hồi với fallback về PostgreSQL
- Filters: location, price, property type, bedrooms - Bộ lọc: vị trí, giá, loại bất động sản, số phòng ngủ
### Transactions & Inquiries ### Giao dịch & Inquiry
- **inquiries/** — Buyer-to-seller messages for specific listings - **inquiries/** — Tin nhắn người mua-người bán cho listing cụ thể
- **leads/** — Agent CRM (lead scoring, status tracking, notes) - **leads/** — CRM dành cho agent (chấm điểm lead, theo dõi trạng thái, ghi chú)
### Monetization ### Kiếm tiền
- **payments/** — VNPay, MoMo, ZaloPay, Bank Transfer - **payments/** — VNPay, MoMo, ZaloPay, Chuyển khoản ngân hàng
- Idempotency keys, webhook callbacks, refund handling - Khóa idempotency, webhook callback, xử lý hoàn tiền
- 4 payment types: subscription, listing fee, deposit, featured - 4 loại thanh toán: subscription, phí listing, đặt cọc, nổi bật
- **subscriptions/** — Plans (FREE, AGENT_PRO, INVESTOR, ENTERPRISE) - **subscriptions/** — Các gói (FREE, AGENT_PRO, INVESTOR, ENTERPRISE)
- Usage tracking, quota management, billing cycles - Theo dõi sử dụng, quản lý hạn ngạch, chu kỳ thanh toán
### Operations ### Vận hành
- **agents/** — Agent profiles, quality scores, service areas, verification - **agents/** — Hồ sơ agent, điểm chất lượng, khu vực phục vụ, xác minh
- **admin/** — User bans, KYC approval, listing moderation, audit logs - **admin/** — Cấm người dùng, duyệt KYC, kiểm duyệt listing, audit log
- **notifications/** — Email, SMS, Push (FCM), Zalo OA - **notifications/** — Email, SMS, Push (FCM), Zalo OA
- Preferences per user/channel, template system - Tùy chọn theo người dùng/kênh, hệ thống template
### Analytics & Intelligence ### Analytics & Trí tuệ
- **analytics/** — Market reports, price index by district/city/type - **analytics/** — Báo cáo thị trường, chỉ số giá theo quận/thành phố/loại
- Valuation engine integration (AI/ML service) - Tích hợp engine định giá (dịch vụ AI/ML)
### Infrastructure & System ### Hạ tầng & Hệ thống
- **health/** — Liveness/readiness probes, Kubernetes hooks - **health/** — Probe liveness/readiness, hook Kubernetes
- **metrics/** — Prometheus metrics, HTTP latency, error rates - **metrics/** — Metrics Prometheus, độ trễ HTTP, tỷ lệ lỗi
- **mcp/** — Model Context Protocol server for AI tools - **mcp/** — Model Context Protocol server cho công cụ AI
- **shared/** — Domain primitives, encryption, logging, error handling - **shared/** — Domain primitives, mã hóa, logging, xử lý lỗi
**Code Metrics:** **Số liệu code:**
- ~845 TypeScript files - ~845 file TypeScript
- Layered DDD architecture: presentation → application → domain → infrastructure - Kiến trúc DDD phân lớp: presentation → application → domain → infrastructure
- Uses NestJS modules, CQRS pattern for complex operations - Sử dụng module NestJS, pattern CQRS cho các thao tác phức tạp
--- ---
## 3. FRONTEND STRUCTURE (`apps/web/`) ## 3. CẤU TRÚC FRONTEND (`apps/web/`)
### Root Layout ### Root Layout
- **app/layout.tsx** — Root wrapper - **app/layout.tsx** — Root wrapper
- **app/[locale]/** — i18n routing (Vietnamese + English) - **app/[locale]/** — Định tuyến i18n (Tiếng Việt + Tiếng Anh)
### Page Groups (Route Groups with Shared Layouts) ### Nhóm trang (Route Groups với Layout dùng chung)
- **(public)/** — Landing, listings, search (no auth required) - **(public)/** — Landing, listings, search (không yêu cầu xác thực)
- **(auth)/** — Login, register, OAuth callbacks - **(auth)/** — Login, register, OAuth callback
- **(dashboard)/** — Seller/agent dashboard - **(dashboard)/** — Dashboard người bán/agent
- **(admin)/** — Admin moderation, KYC review, user management - **(admin)/** — Kiểm duyệt admin, duyệt KYC, quản lý người dùng
### Components (`components/`) ### Components (`components/`)
``` ```
@@ -132,81 +132,81 @@ goodgo-platform-ai/
``` ```
### i18n (`i18n/`) ### i18n (`i18n/`)
- Vietnamese & English message files - File messages tiếng Việt & tiếng Anh
- next-intl integration - Tích hợp next-intl
**Frontend Metrics:** **Số liệu Frontend:**
- ~245 TypeScript/TSX files - ~245 file TypeScript/TSX
- Built on: Next.js 15, React 18, Tailwind CSS, Shadcn/ui - Xây dựng trên: Next.js 15, React 18, Tailwind CSS, Shadcn/ui
- State: Zustand + React Query - State: Zustand + React Query
- Forms: React Hook Form + Zod validation - Forms: React Hook Form + validation Zod
--- ---
## 4. PRISMA SCHEMA — DATA MODEL ## 4. PRISMA SCHEMA — MÔ HÌNH DỮ LIỆU
**Database:** PostgreSQL 16 + PostGIS extension **Database:** PostgreSQL 16 + extension PostGIS
### Total Models: 31 ### Tổng số Model: 31
#### Authentication (5) #### Xác thực (5)
| Model | Purpose | | Model | Mục đích |
|-------|---------| |-------|---------|
| User | Main user profile + KYC status, MFA fields | | User | Hồ sơ người dùng chính + trạng thái KYC, các trường MFA |
| RefreshToken | JWT refresh token chain management | | RefreshToken | Quản lý chuỗi JWT refresh token |
| OAuthAccount | Google/Zalo OAuth linkage | | OAuthAccount | Liên kết OAuth Google/Zalo |
| Agent | Seller/Agent extended profile | | Agent | Hồ sơ mở rộng cho người bán/Agent |
| MfaChallenge | TOTP/backup code verification tracking | | MfaChallenge | Theo dõi xác minh TOTP/mã dự phòng |
#### Listings & Properties (4) #### Listings & Bất động sản (4)
| Model | Purpose | | Model | Mục đích |
|-------|---------| |-------|---------|
| Property | Physical property details + geolocation | | Property | Chi tiết bất động sản vật lý + định vị địa lý |
| PropertyMedia | Images/videos per property | | PropertyMedia | Hình ảnh/video cho mỗi bất động sản |
| Listing | Listing instance (sale/rent) + status | | Listing | Phiên bản listing (bán/cho thuê) + trạng thái |
| SavedSearch | User's saved search preferences | | SavedSearch | Tùy chọn tìm kiếm đã lưu của người dùng |
#### Transactions (4) #### Giao dịch (4)
| Model | Purpose | | Model | Mục đích |
|-------|---------| |-------|---------|
| Transaction | Buyer-seller transaction flow (inquiry → completed) | | Transaction | Luồng giao dịch người mua-người bán (inquiry → hoàn thành) |
| Inquiry | Buyer questions on specific listings | | Inquiry | Câu hỏi người mua về listing cụ thể |
| Lead | Agent CRM lead records | | Lead | Bản ghi lead CRM của agent |
| Review | User reviews of agents/transactions | | Review | Đánh giá người dùng về agent/giao dịch |
#### Payments (2) #### Thanh toán (2)
| Model | Purpose | | Model | Mục đích |
|-------|---------| |-------|---------|
| Payment | Payment records (all providers) | | Payment | Bản ghi thanh toán (tất cả nhà cung cấp) |
| Plan | Subscription tier definitions | | Plan | Định nghĩa cấp subscription |
#### Orders & Escrow (3) #### Đơn hàng & Escrow (3)
| Model | Purpose | | Model | Mục đích |
|-------|---------| |-------|---------|
| Order | Auction settlement order | | Order | Lệnh thanh toán đấu giá |
| Escrow | Escrow holding for transactions | | Escrow | Giữ ký quỹ cho giao dịch |
| Subscription | User's active subscription | | Subscription | Subscription đang hoạt động của người dùng |
#### Analytics (2) #### Analytics (2)
| Model | Purpose | | Model | Mục đích |
|-------|---------| |-------|---------|
| Valuation | AI-generated property valuations | | Valuation | Định giá bất động sản do AI tạo |
| MarketIndex | Market statistics per district/city | | MarketIndex | Thống kê thị trường theo quận/thành phố |
#### Operations (6) #### Vận hành (6)
| Model | Purpose | | Model | Mục đích |
|-------|---------| |-------|---------|
| NotificationLog | Sent notification records | | NotificationLog | Bản ghi thông báo đã gửi |
| NotificationPreference | User notification opt-in/out | | NotificationPreference | Tùy chọn nhận thông báo của người dùng |
| AdminAuditLog | Admin action audit trail | | AdminAuditLog | Audit trail hành động admin |
| UsageRecord | Subscription usage tracking | | UsageRecord | Theo dõi sử dụng subscription |
**Index Strategy:** **Chiến lược Index:**
- Single-column indexes on foreign keys, status fields, dates - Index một cột trên foreign key, các trường trạng thái, ngày tháng
- Compound indexes for common query patterns (e.g., `[role, isActive, createdAt DESC]`) - Index ghép cho các pattern truy vấn phổ biến (ví dụ: `[role, isActive, createdAt DESC]`)
- GIST index on PostGIS location geometry - Index GIST trên hình học vị trí PostGIS
**Key Enums:** **Các Enum chính:**
- UserRole: BUYER, SELLER, AGENT, ADMIN - UserRole: BUYER, SELLER, AGENT, ADMIN
- PropertyType: APARTMENT, VILLA, TOWNHOUSE, LAND, OFFICE, SHOPHOUSE - PropertyType: APARTMENT, VILLA, TOWNHOUSE, LAND, OFFICE, SHOPHOUSE
- TransactionType: SALE, RENT - TransactionType: SALE, RENT
@@ -215,32 +215,32 @@ goodgo-platform-ai/
--- ---
## 5. DOCUMENTATION & TRACKING ## 5. TÀI LIỆU & THEO DÕI
### Root-Level Planning Docs ### Tài liệu lập kế hoạch ở cấp Root
- **PROJECT_TRACKER.md** — 7 phases, 40+ issues, current status (Phase 7 Wave 14) - **PROJECT_TRACKER.md** — 7 phase, 40+ issue, trạng thái hiện tại (Phase 7 Wave 14)
- **IMPLEMENTATION_PLAN.md** — Feature roadmap with priority/status - **IMPLEMENTATION_PLAN.md** — Lộ trình tính năng với ưu tiên/trạng thái
- **COMPREHENSIVE_AUDIT_2026-04-12.md** — Full system audit with implementation notes - **COMPREHENSIVE_AUDIT_2026-04-12.md** — Audit toàn hệ thống với ghi chú triển khai
### Technical Docs (`docs/`) ### Tài liệu kỹ thuật (`docs/`)
- **architecture.md** — DDD layering, CQRS, module boundaries - **architecture.md** — Phân lớp DDD, CQRS, ranh giới module
- **api-endpoints.md** — Swagger-generated endpoint reference - **api-endpoints.md** — Tham chiếu endpoint do Swagger tạo
- **api-error-codes.md** — Structured error code taxonomy - **api-error-codes.md** — Phân loại mã lỗi có cấu trúc
- **deployment.md** — Docker, K8s, CI/CD pipeline steps - **deployment.md** — Docker, K8s, các bước CI/CD
- **RUNBOOK.md** — Operational procedures, troubleshooting - **RUNBOOK.md** — Quy trình vận hành, xử lý sự cố
- **PRODUCTION_READINESS.md** — Security, compliance, performance checklist - **PRODUCTION_READINESS.md** — Checklist bảo mật, tuân thủ, hiệu năng
### Audit Directory (`docs/audits/`) ### Thư mục Audit (`docs/audits/`)
- 80+ audit files documenting feature implementations - 80+ file audit tài liệu hóa các triển khai tính năng
- Pricing audit, checkout flow, KYC, payment gateway testing - Audit pricing, luồng checkout, KYC, test cổng thanh toán
--- ---
## 6. DEPENDENCIES & TOOLING ## 6. PHỤ THUỘC & CÔNG CỤ
### Monorepo Setup ### Thiết lập Monorepo
- **pnpm** v10.27.0 (workspace) — faster, strict peer deps - **pnpm** v10.27.0 (workspace) — nhanh hơn, peer deps nghiêm ngặt
- **Turbo** v2.9.4 — task orchestration & caching - **Turbo** v2.9.4 — điều phối tác vụ & cache
- **Node** ≥22.0.0 - **Node** ≥22.0.0
### Backend (NestJS) ### Backend (NestJS)
@@ -269,7 +269,7 @@ Maps: mapbox-gl ^3.21
Monitoring: @sentry/nextjs Monitoring: @sentry/nextjs
``` ```
### Testing & Quality ### Testing & Chất lượng
``` ```
Test: vitest ^4.1.3, @playwright/test ^1.59 Test: vitest ^4.1.3, @playwright/test ^1.59
Lint: eslint ^9.39, prettier ^3.8, typescript-eslint Lint: eslint ^9.39, prettier ^3.8, typescript-eslint
@@ -278,20 +278,20 @@ Dependencies: dependency-cruiser (architecture validation)
--- ---
## 7. TEST COVERAGE & QUALITY ## 7. ĐỘ BAO PHỦ TEST & CHẤT LƯỢNG
### Test Files: 242 total ### Tổng số file Test: 242
#### API Tests #### API Tests
- **Unit tests:** Payment gateways (VNPay, MoMo, ZaloPay), Money value objects, Platform fee logic - **Unit tests:** Cổng thanh toán (VNPay, MoMo, ZaloPay), Money value objects, logic phí nền tảng
- **Integration tests:** Auth flows, health checks, notifications - **Integration tests:** Luồng auth, health check, notifications
- Located in `__tests__` subdirs within each module - Nằm trong các thư mục con `__tests__` trong từng module
#### Frontend Tests #### Frontend Tests
- **Unit tests:** Auth store, comparison store, currency formatting, validations - **Unit tests:** Auth store, comparison store, định dạng tiền tệ, validation
- **E2E tests (Playwright):** 15+ web tests, 16+ API tests - **E2E tests (Playwright):** 15+ web test, 16+ API test
#### E2E Test Coverage #### Độ bao phủ E2E Test
**Web Tests (15):** **Web Tests (15):**
- auth-login, auth-register, auth-oauth-callback - auth-login, auth-register, auth-oauth-callback
- homepage, navigation, responsive - homepage, navigation, responsive
@@ -310,57 +310,57 @@ Dependencies: dependency-cruiser (architecture validation)
- mcp, admin - mcp, admin
**Load Tests (K6):** **Load Tests (K6):**
- Baseline benchmarks for search, listings, auth endpoints - Benchmark cơ sở cho các endpoint search, listings, auth
- Concurrency testing up to 1000 virtual users - Test đồng thời lên đến 1000 virtual users
--- ---
## 8. IMPLEMENTATION STATUS ## 8. TRẠNG THÁI TRIỂN KHAI
### ✅ COMPLETE (Phase 7 MVP) ### ✅ HOÀN THÀNH (Phase 7 MVP)
1. **Foundation** — Monorepo, Docker, Prisma schema, CI/CD 1. **Foundation** — Monorepo, Docker, schema Prisma, CI/CD
2. **Auth** — JWT, OAuth, MFA/TOTP, session management 2. **Auth** — JWT, OAuth, MFA/TOTP, quản lý phiên
3. **Listings** — Full CRUD, media upload, status workflow 3. **Listings** — CRUD đầy đủ, upload media, workflow trạng thái
4. **Search** — Typesense + PostGIS geo-search 4. **Search** — Typesense + tìm kiếm địa lý PostGIS
5. **Payments** — 3 VN payment gateways, webhook handling 5. **Payments** — 3 cổng thanh toán VN, xử lý webhook
6. **Subscriptions** — 4 tiers, quota tracking 6. **Subscriptions** — 4 cấp, theo dõi quota
7. **Notifications** — Email, SMS, Push, Zalo OA 7. **Notifications** — Email, SMS, Push, Zalo OA
8. **Admin Panel** — Moderation, user management, audit logs 8. **Admin Panel** — Kiểm duyệt, quản lý người dùng, audit log
9. **Agents** — Portal, inquiries, lead CRM, quality metrics 9. **Agents** — Portal, inquiries, lead CRM, chỉ số chất lượng
10. **Analytics** — Market reports, AI valuation service 10. **Analytics** — Báo cáo thị trường, dịch vụ định giá AI
11. **Security** — Rate limiting, CSRF, field encryption, PII masking 11. **Security** — Rate limiting, CSRF, mã hóa trường, che PII
12. **Monitoring** — Prometheus, Grafana, Sentry, log aggregation 12. **Monitoring** — Prometheus, Grafana, Sentry, tổng hợp log
13. **Testing** — Unit tests, E2E tests (Playwright), load tests (K6) 13. **Testing** — Unit test, E2E test (Playwright), load test (K6)
### 🔄 IN PROGRESS / REMAINING ### 🔄 ĐANG TIẾN HÀNH / CÒN LẠI
- Per Wave 14: - Theo Wave 14:
- TEC-1650: Listing detail non-existent ID error handling - TEC-1650: Xử lý lỗi ID không tồn tại trên trang chi tiết listing
- TEC-1652: Full E2E test suite validation - TEC-1652: Xác thực bộ test E2E đầy đủ
- TEC-1657: Comprehensive audit logging - TEC-1657: Audit logging toàn diện
### Database Migrations ### Migration Database
- 7+ migrations applied - 7+ migration đã được áp dụng
- Connection pooling (PgBouncer) - Connection pooling (PgBouncer)
- PostGIS extension enabled - Đã bật extension PostGIS
--- ---
## 9. PROJECT MATURITY INDICATORS ## 9. CHỈ SỐ TRƯỞNG THÀNH DỰ ÁN
| Dimension | Status | Evidence | | Khía cạnh | Trạng thái | Bằng chứng |
|-----------|--------|----------| |-----------|--------|----------|
| **Architecture** | Production-Ready | DDD, CQRS, layered modules, clear boundaries | | **Kiến trúc** | Sẵn sàng Production | DDD, CQRS, các module phân lớp, ranh giới rõ ràng |
| **Code Quality** | High | 242 tests, ESLint enforcement, module cruiser | | **Chất lượng code** | Cao | 242 test, ESLint thực thi, module cruiser |
| **Security** | Hardened | JWT, MFA, encryption, rate limiting, CSRF, PII masking | | **Bảo mật** | Đã được củng cố | JWT, MFA, mã hóa, rate limiting, CSRF, che PII |
| **Documentation** | Comprehensive | 80+ audit files, runbooks, error codes, architecture | | **Tài liệu** | Toàn diện | 80+ file audit, runbook, mã lỗi, kiến trúc |
| **Performance** | Optimized | Redis caching, Typesense search, query optimization, load tests | | **Hiệu năng** | Đã tối ưu | Cache Redis, tìm kiếm Typesense, tối ưu truy vấn, load test |
| **Monitoring** | Complete | Prometheus, Grafana, Sentry, structured logging | | **Monitoring** | Hoàn chỉnh | Prometheus, Grafana, Sentry, structured logging |
| **DevOps** | Mature | Docker, Kubernetes config, CI/CD pipelines, smoke tests | | **DevOps** | Trưởng thành | Docker, cấu hình Kubernetes, pipeline CI/CD, smoke test |
| **Scaling** | Prepared | Connection pooling, caching layer, resilient services | | **Khả năng mở rộng** | Đã chuẩn bị | Connection pooling, lớp cache, dịch vụ có khả năng phục hồi |
--- ---
## 10. KEY STATISTICS ## 10. THỐNG KÊ CHÍNH
``` ```
Backend Files: ~845 TypeScript files Backend Files: ~845 TypeScript files
@@ -378,9 +378,9 @@ Lines of Code: ~50,000+ (excluding node_modules)
--- ---
## 11. TECH STACK SUMMARY ## 11. TÓM TẮT TECH STACK
| Layer | Technology | | Lớp | Công nghệ |
|-------|-----------| |-------|-----------|
| **Frontend** | Next.js 15, React 18, Tailwind CSS, Shadcn/ui | | **Frontend** | Next.js 15, React 18, Tailwind CSS, Shadcn/ui |
| **Backend** | NestJS 11, TypeScript 6 | | **Backend** | NestJS 11, TypeScript 6 |
@@ -397,16 +397,15 @@ Lines of Code: ~50,000+ (excluding node_modules)
| **Package Manager** | pnpm 10.27 | | **Package Manager** | pnpm 10.27 |
| **Orchestration** | Turbo | | **Orchestration** | Turbo |
| **Containerization** | Docker + Docker Compose | | **Containerization** | Docker + Docker Compose |
| **i18n** | next-intl (Vietnamese + English) | | **i18n** | next-intl (Tiếng Việt + Tiếng Anh) |
--- ---
## 12. NEXT STEPS FOR DEVELOPERS ## 12. CÁC BƯỚC TIẾP THEO CHO LẬP TRÌNH VIÊN
1. **Local Setup:** `docker-compose up` → database + API + frontend
2. **Run Tests:** `pnpm test` (unit), `pnpm test:e2e` (E2E)
3. **Check Status:** Review PROJECT_TRACKER.md for ongoing issues
4. **Architecture:** Read docs/architecture.md for module boundaries
5. **API:** Browse docs/api-endpoints.md (Swagger-generated)
6. **Deploy:** Follow docs/deployment.md for production setup
1. **Thiết lập cục bộ:** `docker-compose up` → database + API + frontend
2. **Chạy Test:** `pnpm test` (unit), `pnpm test:e2e` (E2E)
3. **Kiểm tra trạng thái:** Xem PROJECT_TRACKER.md để biết các issue đang diễn ra
4. **Kiến trúc:** Đọc docs/architecture.md để biết ranh giới module
5. **API:** Duyệt docs/api-endpoints.md (do Swagger tạo)
6. **Deploy:** Theo dõi docs/deployment.md để thiết lập production

274
docs/architecture/FILE_MAPPING_GUIDE.md
View File

@@ -1,16 +1,16 @@
# GoodGo Frontend: File-by-File i18n & A11y Implementation Guide # GoodGo Frontend: Hướng dẫn triển khai i18n & A11y theo từng file
## 📋 Complete File Mapping ## 📋 Ánh xạ file đầy đủ
### PHASE 1: INFRASTRUCTURE SETUP ### GIAI ĐOẠN 1: THIẾT LẬP HẠ TẦNG
#### 1. `middleware.ts` (CRITICAL) #### 1. `middleware.ts` (QUAN TRỌNG)
**Current:** Auth routing only **Hiện tại:** Chỉ định tuyến xác thực
**Changes:** **Thay đổi:**
- Add locale detection from URL pathname - Thêm phát hiện locale từ pathname URL
- Add cookie-based locale storage - Thêm lưu trữ locale dựa trên cookie
- Redirect `/en/*` and `/vi/*` paths appropriately - Chuyển hướng các đường dẫn `/en/*` và `/vi/*` một cách phù hợp
- Add Accept-Language header fallback - Thêm dự phòng dựa trên header Accept-Language
**Pseudo-code:** **Pseudo-code:**
```typescript ```typescript
@@ -32,15 +32,15 @@ export function middleware(request: NextRequest) {
} }
``` ```
#### 2. `app/layout.tsx` (CRITICAL) #### 2. `app/layout.tsx` (QUAN TRỌNG)
**Current:** Thai providers, hardcoded Vietnamese metadata **Hiện tại:** Các provider chính, metadata tiếng Việt được hardcode
**Changes:** **Thay đổi:**
- Change `lang="vi"` to dynamic locale - Thay đổi `lang="vi"` thành locale động
- Update metadata to be i18n-aware - Cập nhật metadata để hỗ trợ i18n
- Wrap with `NextIntlClientProvider` from next-intl - Bao bọc bằng `NextIntlClientProvider` từ next-intl
- Keep existing providers (ThemeProvider, QueryProvider, AuthProvider) - Giữ nguyên các provider hiện có (ThemeProvider, QueryProvider, AuthProvider)
**Key changes:** **Các thay đổi chính:**
```typescript ```typescript
import { getLocale, getTranslations } from 'next-intl/server'; import { getLocale, getTranslations } from 'next-intl/server';
@@ -59,8 +59,8 @@ export async function generateMetadata(): Promise<Metadata> {
} }
``` ```
#### 3. `i18n/config.ts` (NEW) #### 3. `i18n/config.ts` (MỚI)
**Create new file** with i18n configuration: **Tạo file mới** với cấu hình i18n:
```typescript ```typescript
export const locales = ['en', 'vi'] as const; export const locales = ['en', 'vi'] as const;
export const defaultLocale = 'vi'; export const defaultLocale = 'vi';
@@ -68,8 +68,8 @@ export const defaultLocale = 'vi';
export const timeZone = 'Asia/Ho_Chi_Minh'; export const timeZone = 'Asia/Ho_Chi_Minh';
``` ```
#### 4. `public/locales/en.json` (NEW - LARGE FILE) #### 4. `public/locales/en.json` (MỚI - FILE LỚN)
**Structure:** **Cấu trúc:**
```json ```json
{ {
"common": { "common": {
@@ -179,16 +179,16 @@ export const timeZone = 'Asia/Ho_Chi_Minh';
} }
``` ```
#### 5. `public/locales/vi.json` (NEW - LARGE FILE) #### 5. `public/locales/vi.json` (MỚI - FILE LỚN)
Same structure as en.json but with Vietnamese translations. Cấu trúc giống en.json nhưng với bản dịch tiếng Việt.
--- ---
### PHASE 2: CORE COMPONENT UPDATES ### GIAI ĐOẠN 2: CẬP NHẬT COMPONENT CỐT LÕI
#### Files Requiring Translation Hook Integration #### Các file cần tích hợp Translation Hook
##### Layout Files ##### Các file Layout
1. **`app/(public)/layout.tsx`** 1. **`app/(public)/layout.tsx`**
```typescript ```typescript
@@ -220,20 +220,20 @@ const toggleLabel = theme === 'light'
``` ```
3. **`app/(auth)/layout.tsx`** 3. **`app/(auth)/layout.tsx`**
Update any error messages or labels to use translations. Cập nhật mọi thông báo lỗi hoặc nhãn để sử dụng bản dịch.
##### Page Files ##### Các file Page
1. **`app/(public)/page.tsx` (LARGE FILE)** 1. **`app/(public)/page.tsx` (FILE LỚN)**
**Areas to update:** **Các phần cần cập nhật:**
- Hero section (title, subtitle) - Phần hero (tiêu đề, phụ đề)
- Search form (placeholder) - Form tìm kiếm (placeholder)
- Property type badges - Các badge loại bất động sản
- Price ranges - Các khoảng giá
- City options - Tùy chọn thành phố
- Section headings - Tiêu đề các phần
- Stats labels - Nhãn thống kê
- CTA buttons - Các nút CTA
```typescript ```typescript
export default function LandingPage() { export default function LandingPage() {
@@ -268,32 +268,32 @@ const OAUTH_ERROR_MESSAGES = {
``` ```
3. **`app/(auth)/register/page.tsx`** 3. **`app/(auth)/register/page.tsx`**
Same pattern as login page. Tương tự như trang login.
4. **`app/(dashboard)/dashboard/page.tsx`** and all other dashboard pages 4. **`app/(dashboard)/dashboard/page.tsx`** và tất cả các trang dashboard khác
Update section titles, empty states, button labels. Cập nhật tiêu đề các phần, trạng thái rỗng, nhãn các nút.
##### Search & Listing Pages ##### Các trang Search & Listing
1. **`app/(public)/search/page.tsx`** 1. **`app/(public)/search/page.tsx`**
Update search results headings, empty states, filter labels. Cập nhật tiêu đề kết quả tìm kiếm, trạng thái rỗng, nhãn bộ lọc.
2. **`app/(public)/listings/[id]/page.tsx`** 2. **`app/(public)/listings/[id]/page.tsx`**
Update property detail labels. Cập nhật nhãn chi tiết bất động sản.
3. **`app/(dashboard)/listings/page.tsx`** 3. **`app/(dashboard)/listings/page.tsx`**
Update table headers, status labels, action labels. Cập nhật tiêu đề bảng, nhãn trạng thái, nhãn hành động.
4. **`app/(dashboard)/listings/new/page.tsx`** 4. **`app/(dashboard)/listings/new/page.tsx`**
Uses listing-form-steps component (see below). Sử dụng component listing-form-steps (xem bên dưới).
--- ---
#### Component Files #### Các file Component
##### Critical Components (Do First) ##### Các component quan trọng (Làm trước)
1. **`components/search/filter-bar.tsx` (HIGH PRIORITY)** 1. **`components/search/filter-bar.tsx` (ƯU TIÊN CAO)**
```typescript ```typescript
// Current: Hardcoded arrays // Current: Hardcoded arrays
const CITIES = ['Hồ Chí Minh', 'Hà Nội', 'Đà Nẵng', ...]; const CITIES = ['Hồ Chí Minh', 'Hà Nội', 'Đà Nẵng', ...];
@@ -310,14 +310,14 @@ const PRICE_RANGES = [
]; ];
``` ```
2. **`components/listings/listing-form-steps.tsx` (HIGH PRIORITY - LARGE FILE)** 2. **`components/listings/listing-form-steps.tsx` (ƯU TIÊN CAO - FILE LỚN)**
This multi-step form has many labels to translate: Form đa bước này có nhiều nhãn cần dịch:
- Step 1: Transaction type, property type, title, description - Bước 1: Loại giao dịch, loại bất động sản, tiêu đề, mô tả
- Step 2: Address fields, location - Bước 2: Các trường địa chỉ, vị trí
- Step 3: Area, rooms, bathrooms, direction, year built, etc. - Bước 3: Diện tích, phòng, phòng tắm, hướng, năm xây dựng, v.v.
- Step 4: Pricing - Bước 4: Giá
All field labels should use `t('form.field_name')` pattern. Tất cả nhãn các trường nên sử dụng pattern `t('form.field_name')`.
3. **`components/auth/oauth-buttons.tsx`** 3. **`components/auth/oauth-buttons.tsx`**
```typescript ```typescript
@@ -330,7 +330,7 @@ All field labels should use `t('form.field_name')` pattern.
</Button> </Button>
``` ```
##### Medium Priority Components ##### Các component ưu tiên trung bình
1. **`components/search/property-card.tsx`** 1. **`components/search/property-card.tsx`**
```typescript ```typescript
@@ -361,21 +361,21 @@ const LISTING_STATUSES = {
``` ```
3. **`components/valuation/valuation-form.tsx`** 3. **`components/valuation/valuation-form.tsx`**
Update form labels and buttons. Cập nhật nhãn form và các nút.
4. **`components/listings/image-upload.tsx`** 4. **`components/listings/image-upload.tsx`**
Update button text and error messages. Cập nhật văn bản nút và thông báo lỗi.
5. **All `components/ui/*.tsx` files with text** 5. **Tất cả các file `components/ui/*.tsx` có văn bản**
- Button: any default text - Button: bất kỳ văn bản mặc định nào
- Dialog: Close button aria-label - Dialog: aria-label nút Đóng
- Input: placeholder attrs if hardcoded - Input: thuộc tính placeholder nếu được hardcode
- Label: any default text - Label: bất kỳ văn bản mặc định nào
- Others: similar - Khác: tương tự
--- ---
### PHASE 3: VALIDATION & ERROR MESSAGES ### GIAI ĐOẠN 3: VALIDATION & THÔNG BÁO LỖI
#### 1. `lib/validations/auth.ts` #### 1. `lib/validations/auth.ts`
```typescript ```typescript
@@ -394,21 +394,21 @@ const schema = z.object({
}); });
``` ```
#### 2. `lib/validations/listings.ts` (LARGE FILE) #### 2. `lib/validations/listings.ts` (FILE LỚN)
Update all Zod validation error messages: Cập nhật tất cả thông báo lỗi validation Zod:
- "Vui lòng chọn loại giao dịch" → `t('validation.transaction_required')` - "Vui lòng chọn loại giao dịch" → `t('validation.transaction_required')`
- "Tiêu đề tối thiểu 5 ký tự" → `t('validation.title_min_length')` - "Tiêu đề tối thiểu 5 ký tự" → `t('validation.title_min_length')`
- All other validation messages - Tất cả các thông báo validation khác
#### 3. `lib/validations/valuation.ts` #### 3. `lib/validations/valuation.ts`
Similar pattern to listings. Mẫu tương tự như listings.
--- ---
### PHASE 4: UTILITY UPDATES ### GIAI ĐOẠN 4: CẬP NHẬT TIỆN ÍCH
#### 1. `lib/utils.ts` #### 1. `lib/utils.ts`
No changes (already minimal). Không thay đổi (đã tối giản).
#### 2. `lib/auth-store.ts` #### 2. `lib/auth-store.ts`
```typescript ```typescript
@@ -417,17 +417,17 @@ No changes (already minimal).
``` ```
#### 3. `lib/api-client.ts` #### 3. `lib/api-client.ts`
Check if error messages from API need i18n wrapping. Kiểm tra xem các thông báo lỗi từ API có cần bao bọc i18n hay không.
#### 4. All `lib/*-api.ts` files #### 4. Tất cả các file `lib/*-api.ts`
Update error message handling if needed. Cập nhật xử lý thông báo lỗi nếu cần.
--- ---
### PHASE 5: ACCESSIBILITY UPDATES ### GIAI ĐOẠN 5: CẬP NHẬT KHẢ NĂNG TIẾP CẬN
#### 1. `components/ui/dialog.tsx` (CRITICAL A11y) #### 1. `components/ui/dialog.tsx` (A11y QUAN TRỌNG)
**Add focus management:** **Thêm quản lý focus:**
```typescript ```typescript
// Add focus trap // Add focus trap
// Save initial focus element // Save initial focus element
@@ -466,7 +466,7 @@ function Dialog() {
``` ```
#### 2. `components/ui/input.tsx` #### 2. `components/ui/input.tsx`
Add aria-describedby for error messages: Thêm aria-describedby cho thông báo lỗi:
```typescript ```typescript
export function Input({ error, ...props }) { export function Input({ error, ...props }) {
const errorId = `${props.id}-error`; const errorId = `${props.id}-error`;
@@ -484,8 +484,8 @@ export function Input({ error, ...props }) {
``` ```
#### 3. `components/ui/button.tsx` #### 3. `components/ui/button.tsx`
Ensure all buttons have visible focus indicator (already in CSS likely). Đảm bảo tất cả các nút có chỉ báo focus rõ ràng (có thể đã có trong CSS).
Add aria-busy for loading state if used: Thêm aria-busy cho trạng thái loading nếu được sử dụng:
```typescript ```typescript
export function Button({ disabled, isLoading, ...props }) { export function Button({ disabled, isLoading, ...props }) {
return ( return (
@@ -500,15 +500,15 @@ export function Button({ disabled, isLoading, ...props }) {
} }
``` ```
#### 4. Form Components #### 4. Các component Form
Update all forms to use aria-describedby for error messages: Cập nhật tất cả các form để sử dụng aria-describedby cho thông báo lỗi:
- `app/(auth)/login/page.tsx` — Already has role="alert" ✓ but could use aria-describedby - `app/(auth)/login/page.tsx` — Đã có role="alert" ✓ nhưng có thể dùng aria-describedby
- `app/(auth)/register/page.tsx` — Same - `app/(auth)/register/page.tsx` — Tương tự
- `components/listings/listing-form-steps.tsx` — Add aria-describedby - `components/listings/listing-form-steps.tsx` — Thêm aria-describedby
- `components/search/filter-bar.tsx` — Ensure accessible labels - `components/search/filter-bar.tsx` — Đảm bảo nhãn dễ tiếp cận
#### 5. All Icon-Only Buttons #### 5. Tất cả các nút chỉ có biểu tượng
Find all buttons with only icons and add aria-label: Tìm tất cả các nút chỉ có biểu tượng và thêm aria-label:
```typescript ```typescript
// Search in components for: <Button> with only SVG children // Search in components for: <Button> with only SVG children
// Add aria-label={t('...')} // Add aria-label={t('...')}
@@ -524,7 +524,7 @@ Find all buttons with only icons and add aria-label:
``` ```
#### 6. Loading Spinners #### 6. Loading Spinners
Add aria-busy and aria-label: Thêm aria-busy và aria-label:
```typescript ```typescript
// In app/(public)/page.tsx and similar: // In app/(public)/page.tsx and similar:
<div aria-busy={loadingFeatured} aria-label={t('common.loading')}> <div aria-busy={loadingFeatured} aria-label={t('common.loading')}>
@@ -533,7 +533,7 @@ Add aria-busy and aria-label:
``` ```
#### 7. `components/listings/image-gallery.tsx` #### 7. `components/listings/image-gallery.tsx`
Add keyboard navigation (arrow keys): Thêm điều hướng bằng bàn phím (phím mũi tên):
```typescript ```typescript
// Add keyboard event handler for arrow keys // Add keyboard event handler for arrow keys
// Left/Right arrows to navigate images // Left/Right arrows to navigate images
@@ -541,7 +541,7 @@ Add keyboard navigation (arrow keys):
--- ---
### PHASE 6: TEST SETUP UPDATES ### GIAI ĐOẠN 6: CẬP NHẬT THIẾT LẬP TEST
#### 1. `vitest.setup.ts` #### 1. `vitest.setup.ts`
```typescript ```typescript
@@ -564,35 +564,35 @@ vi.mock('next-intl', () => ({
``` ```
#### 2. `vitest.config.ts` #### 2. `vitest.config.ts`
May need to add path aliases or test environment setup. Có thể cần thêm path alias hoặc thiết lập môi trường test.
#### 3. Update all test files in `__tests__/` folders #### 3. Cập nhật tất cả các file test trong thư mục `__tests__/`
- Add locale prop to component renders - Thêm prop locale khi render component
- Test both English and Vietnamese if applicable - Test cả tiếng Anh và tiếng Việt nếu có thể
- Mock i18n translations - Mock các bản dịch i18n
--- ---
## 📊 Summary: Files by Update Complexity ## 📊 Tóm tắt: Các file theo độ phức tạp cập nhật
### Trivial (5 min each) ### Đơn giản (5 phút mỗi file)
- `app/robots.ts` - `app/robots.ts`
- `app/sitemap.ts` - `app/sitemap.ts`
- `components/ui/badge.tsx` - `components/ui/badge.tsx`
- `components/ui/card.tsx` - `components/ui/card.tsx`
- `components/ui/tabs.tsx` - `components/ui/tabs.tsx`
### Simple (15-30 min each) ### Đơn giản (15-30 phút mỗi file)
- `app/(admin)/*.tsx` files (3 files) - Các file `app/(admin)/*.tsx` (3 file)
- `app/(dashboard)/analytics/page.tsx` - `app/(dashboard)/analytics/page.tsx`
- `app/(dashboard)/profile/page.tsx` - `app/(dashboard)/profile/page.tsx`
- `app/(dashboard)/subscription/page.tsx` - `app/(dashboard)/subscription/page.tsx`
- `app/(dashboard)/payments/page.tsx` - `app/(dashboard)/payments/page.tsx`
- `components/ui/*.tsx` (8 files) - `components/ui/*.tsx` (8 file)
- `components/auth/oauth-buttons.tsx` - `components/auth/oauth-buttons.tsx`
- `components/listings/listing-status-badge.tsx` - `components/listings/listing-status-badge.tsx`
### Medium (30-60 min each) ### Trung bình (30-60 phút mỗi file)
- `app/(public)/layout.tsx` - `app/(public)/layout.tsx`
- `app/(auth)/login/page.tsx` - `app/(auth)/login/page.tsx`
- `app/(auth)/register/page.tsx` - `app/(auth)/register/page.tsx`
@@ -602,47 +602,47 @@ May need to add path aliases or test environment setup.
- `components/search/property-card.tsx` - `components/search/property-card.tsx`
- `components/search/filter-bar.tsx` - `components/search/filter-bar.tsx`
- `components/listings/image-upload.tsx` - `components/listings/image-upload.tsx`
- `components/valuation/*.tsx` (3 files) - `components/valuation/*.tsx` (3 file)
### Complex (1-2 hours each) ### Phức tạp (1-2 giờ mỗi file)
- `app/(public)/page.tsx` (landing page - many sections) - `app/(public)/page.tsx` (trang landing - nhiều phần)
- `components/listings/listing-form-steps.tsx` (multi-step form) - `components/listings/listing-form-steps.tsx` (form đa bước)
- `components/map/listing-map.tsx` (if has labels) - `components/map/listing-map.tsx` (nếu có nhãn)
- `components/charts/*.tsx` (3 files - chart labels) - `components/charts/*.tsx` (3 file - nhãn biểu đồ)
### Critical Infrastructure ### Hạ tầng quan trọng
- `middleware.ts` (30-45 min) - `middleware.ts` (30-45 phút)
- `app/layout.tsx` (30 min) - `app/layout.tsx` (30 phút)
- `lib/validations/*.ts` (3 files - 45 min) - `lib/validations/*.ts` (3 file - 45 phút)
--- ---
## ✅ Validation Checklist ## ✅ Checklist xác minh
Before considering i18n + A11y complete: Trước khi xem xét i18n + A11y hoàn tất:
### i18n Verification ### Xác minh i18n
- [ ] Both `/en/*` and `/vi/*` routes work - [ ] Cả route `/en/*` và `/vi/*` đều hoạt động
- [ ] All text from messages files, not hardcoded - [ ] Tất cả văn bản từ file messages, không hardcode
- [ ] Metadata changes with locale - [ ] Metadata thay đổi theo locale
- [ ] Cookies/headers work for locale selection - [ ] Cookie/header hoạt động cho việc chọn locale
- [ ] Validation messages use i18n - [ ] Thông báo validation sử dụng i18n
- [ ] All enums use translations - [ ] Tất cả các enum sử dụng bản dịch
- [ ] Tests mock i18n correctly - [ ] Test mock i18n đúng cách
### A11y Verification ### Xác minh A11y
- [ ] Focus trap works in dialogs - [ ] Focus trap hoạt động trong dialog
- [ ] Focus indicator visible on all inputs - [ ] Chỉ báo focus hiển thị trên tất cả input
- [ ] Form errors linked with aria-describedby - [ ] Lỗi form được liên kết với aria-describedby
- [ ] Icon buttons all have aria-labels - [ ] Tất cả nút biểu tượng có aria-label
- [ ] Color contrast >= 4.5:1 for text (AA standard) - [ ] Tỷ lệ tương phản màu >= 4.5:1 cho văn bản (chuẩn AA)
- [ ] Keyboard navigation works everywhere - [ ] Điều hướng bàn phím hoạt động ở mọi nơi
- [ ] Screen reader testing (NVDA/JAWS) - [ ] Test với screen reader (NVDA/JAWS)
- [ ] Loading spinners have aria-busy - [ ] Loading spinner có aria-busy
- [ ] All tables have proper headers - [ ] Tất cả các bảng có header phù hợp
--- ---
**Generated:** April 9, 2026 **Được tạo:** Ngày 9 tháng 4 năm 2026
**Confidence:** High **Độ tin cậy:** Cao
**Total Estimated Files to Update:** 50-60 files **Tổng số file ước tính cần cập nhật:** 50-60 file

344
docs/architecture/IMPLEMENTATION_PLAN.md
View File

@@ -1,22 +1,22 @@
# GoodGo Platform AI — Implementation Plan # Nền tảng GoodGo AI — Kế hoạch triển khai
**Last Updated:** 2026-04-12 **Cập nhật lần cuối:** 2026-04-12
--- ---
## Milestones ## Các Milestone
### Milestone 1: Walking Skeleton (Phase 0) ### Milestone 1: Walking Skeleton (Phase 0)
**Goal:** Any engineer can clone, install, and start developing. **Mục tiêu:** Bất kỳ kỹ sư nào cũng có thể clone, cài đặt và bắt đầu phát triển.
**Execution Order:** **Thứ tự thực hiện:**
1. **[TEC-1415] Monorepo Scaffolding** + **[TEC-1416] Docker Compose** (parallel — no deps) 1. **[TEC-1415] Monorepo Scaffolding** + **[TEC-1416] Docker Compose** (song song — không có dependency)
2. **[TEC-1420] ESLint/Prettier** (after F1) 2. **[TEC-1420] ESLint/Prettier** (sau F1)
3. **[TEC-1417] Prisma Schema** (after F1 + F2) 3. **[TEC-1417] Prisma Schema** (sau F1 + F2)
4. **[TEC-1418] Shared Module** (after F1) 4. **[TEC-1418] Shared Module** (sau F1)
5. **[TEC-1419] CI/CD Pipeline** (after F1) 5. **[TEC-1419] CI/CD Pipeline** (sau F1)
``` ```
F1 (Monorepo) ──┬── F6 (Lint/Prettier) F1 (Monorepo) ──┬── F6 (Lint/Prettier)
@@ -28,17 +28,17 @@ F2 (Docker) ─────┘
### Milestone 2: Core Product (Phase 1) ### Milestone 2: Core Product (Phase 1)
**Goal:** Users can register, post listings, and search properties. **Mục tiêu:** Người dùng có thể đăng ký, đăng tin và tìm kiếm bất động sản.
**Execution Order:** **Thứ tự thực hiện:**
1. **[TEC-1421] Auth Backend** (after F3, F4) 1. **[TEC-1421] Auth Backend** (sau F3, F4)
2. **[TEC-1425] Security Hardening** + **[TEC-1426] Error Handling** (parallel, after F1/F4) 2. **[TEC-1425] Security Hardening** + **[TEC-1426] Error Handling** (song song, sau F1/F4)
3. **[TEC-1422] Auth Frontend** (after C1) 3. **[TEC-1422] Auth Frontend** (sau C1)
4. **[TEC-1423] Listings Backend** (after C1) 4. **[TEC-1423] Listings Backend** (sau C1)
5. **[TEC-1424] Search Backend** (after C3) 5. **[TEC-1424] Search Backend** (sau C3)
6. **[TEC-1427] Listings Frontend** (after C3) 6. **[TEC-1427] Listings Frontend** (sau C3)
7. **[TEC-1428] Search + Landing Frontend** (after C5) 7. **[TEC-1428] Search + Landing Frontend** (sau C5)
``` ```
F3 + F4 ──→ C1 (Auth BE) ──┬── C2 (Auth FE) F3 + F4 ──→ C1 (Auth BE) ──┬── C2 (Auth FE)
@@ -50,7 +50,7 @@ F3 + F4 ──→ C1 (Auth BE) ──┬── C2 (Auth FE)
### Milestone 3: Monetization (Phase 2) ### Milestone 3: Monetization (Phase 2)
**Goal:** Revenue-generating MVP with payments, subscriptions, and admin tools. **Mục tiêu:** MVP tạo doanh thu với thanh toán, subscription và công cụ admin.
``` ```
C1 ──→ M1 (Payments) ──→ M2 (Subscriptions) C1 ──→ M1 (Payments) ──→ M2 (Subscriptions)
@@ -61,7 +61,7 @@ Phase 1 ──→ X4 (E2E Tests)
### Milestone 4: AI-Powered (Phase 3) ### Milestone 4: AI-Powered (Phase 3)
**Goal:** Differentiated product with AI features. **Mục tiêu:** Sản phẩm khác biệt với các tính năng AI.
``` ```
F2 ──→ A1 (AI/ML Container) ──→ A2 (Analytics) F2 ──→ A1 (AI/ML Container) ──→ A2 (Analytics)
@@ -70,12 +70,12 @@ C5 + A2 ──→ A3 (MCP Servers)
--- ---
## Dependency Map ## Bản đồ phụ thuộc
| Task | Depends On | | Task | Phụ thuộc vào |
| ------------- | ---------- | | ------------- | ---------- |
| TEC-1415 (F1) | None | | TEC-1415 (F1) | Không |
| TEC-1416 (F2) | None | | TEC-1416 (F2) | Không |
| TEC-1417 (F3) | F1, F2 | | TEC-1417 (F3) | F1, F2 |
| TEC-1418 (F4) | F1 | | TEC-1418 (F4) | F1 |
| TEC-1419 (F5) | F1 | | TEC-1419 (F5) | F1 |
@@ -96,15 +96,15 @@ C5 + A2 ──→ A3 (MCP Servers)
### Milestone 5: Production Hardening (Phase 4) ### Milestone 5: Production Hardening (Phase 4)
**Goal:** Fix all critical security issues. Establish production deployment capability. **Mục tiêu:** Sửa tất cả các vấn đề bảo mật quan trọng. Thiết lập khả năng triển khai production.
**Execution Order:** **Thứ tự thực hiện:**
1. **[TEC-1449] JWT Secret Fix** + **[TEC-1451] HMAC Timing Fix** + **[TEC-1452] MinIO Fix** + **[TEC-1453] CSRF** (parallel — no deps between them) 1. **[TEC-1449] JWT Secret Fix** + **[TEC-1451] HMAC Timing Fix** + **[TEC-1452] MinIO Fix** + **[TEC-1453] CSRF** (song song — không có dependency giữa chúng)
2. **[TEC-1455] DB Index** (independent — can run parallel with above) 2. **[TEC-1455] DB Index** (độc lập — có thể chạy song song với các task trên)
3. **[TEC-1450] Deployment Pipeline** (after security fixes verified) 3. **[TEC-1450] Deployment Pipeline** (sau khi đã xác minh các bản sửa lỗi bảo mật)
4. **[TEC-1457] Backups + Logs** (after deployment infra exists) 4. **[TEC-1457] Backups + Logs** (sau khi hạ tầng deployment đã có)
5. **[TEC-1456] Test Coverage** (parallel — independent of infra) 5. **[TEC-1456] Test Coverage** (song song — độc lập với hạ tầng)
``` ```
TEC-1449 (JWT) ──────┐ TEC-1449 (JWT) ──────┐
@@ -117,7 +117,7 @@ TEC-1456 (Tests) ─────────────────────
### Milestone 6: Quality & Polish (Phase 5) ### Milestone 6: Quality & Polish (Phase 5)
**Goal:** Production-quality UX, documentation, and performance. **Mục tiêu:** UX, tài liệu và hiệu năng đạt chất lượng production.
``` ```
Phase 4 done ──→ TEC-1458 (Redis Caching) Phase 4 done ──→ TEC-1458 (Redis Caching)
@@ -128,47 +128,47 @@ Phase 4 done ──→ TEC-1458 (Redis Caching)
--- ---
## Dependency Map (Phase 4-5) ## Bản đồ phụ thuộc (Phase 4-5)
| Task | Depends On | | Task | Phụ thuộc vào |
| --------------- | ----------------- | | --------------- | ----------------- |
| TEC-1449 | None | | TEC-1449 | Không |
| TEC-1450 | TEC-1449 (security first) | | TEC-1450 | TEC-1449 (bảo mật trước) |
| TEC-1451 | None | | TEC-1451 | Không |
| TEC-1452 | None | | TEC-1452 | Không |
| TEC-1453 | None | | TEC-1453 | Không |
| TEC-1455 | None | | TEC-1455 | Không |
| TEC-1456 | None | | TEC-1456 | Không |
| TEC-1457 | TEC-1450 | | TEC-1457 | TEC-1450 |
| TEC-1458 | Phase 4 | | TEC-1458 | Phase 4 |
| TEC-1459 | None | | TEC-1459 | Không |
| TEC-1460 | None | | TEC-1460 | Không |
| TEC-1461 | None | | TEC-1461 | Không |
### Milestone 7: MVP Feature Completion & Audit (Phase 6) ### Milestone 7: Hoàn thành tính năng MVP & Audit (Phase 6)
**Goal:** Complete remaining MVP features (Agent Portal, AI, Payments), clean up tech debt from audit. **Mục tiêu:** Hoàn thành các tính năng MVP còn lại (Agent Portal, AI, Payments), dọn dẹp tech debt từ audit.
**Sprint 1 — Stabilize (Week 1):** **Sprint 1 — Ổn định (Tuần 1):**
1. **[TEC-1592] Commit untracked files** (P0, no deps) 1. **[TEC-1592] Commit các file chưa được track** (P0, không có dependency)
2. **[TEC-1593] Fix Architect agent** (P0, no deps) 2. **[TEC-1593] Sửa Architect agent** (P0, không có dependency)
3. **[TEC-1594] i18n consolidation** (P1, no deps) 3. **[TEC-1594] Hợp nhất i18n** (P1, không có dependency)
**Sprint 2 — Agent Portal + Payments (Weeks 2-3):** **Sprint 2 — Agent Portal + Payments (Tuần 2-3):**
4. **[TEC-1595] Agent Portal** (P1, after TEC-1592) 4. **[TEC-1595] Agent Portal** (P1, sau TEC-1592)
5. **[TEC-1597] Payment flow** (P1, after TEC-1592) 5. **[TEC-1597] Luồng thanh toán** (P1, sau TEC-1592)
6. **[TEC-1598] Smoke tests** (P1, independent) 6. **[TEC-1598] Smoke test** (P1, độc lập)
**Sprint 3 — AI & Quality (Weeks 4-5):** **Sprint 3 — AI & Chất lượng (Tuần 4-5):**
7. **[TEC-1596] AI/ML integration** (P1, after TEC-1592) 7. **[TEC-1596] Tích hợp AI/ML** (P1, sau TEC-1592)
8. **[TEC-1599] Test coverage** (P2, independent) 8. **[TEC-1599] Độ bao phủ test** (P2, độc lập)
9. **[TEC-1600] OpenAPI docs** (P2, independent) 9. **[TEC-1600] Tài liệu OpenAPI** (P2, độc lập)
**Sprint 4 — Hardening (Weeks 5-6):** **Sprint 4 — Củng cố (Tuần 5-6):**
10. **[TEC-1601] K6 baselines** (P2, independent) 10. **[TEC-1601] Baseline K6** (P2, độc lập)
11. **[TEC-1602] Security audit** (P2, after Phase 4 security fixes) 11. **[TEC-1602] Audit bảo mật** (P2, sau các bản sửa bảo mật Phase 4)
12. **[TEC-1603] DB index optimization** (P2, independent) 12. **[TEC-1603] Tối ưu DB index** (P2, độc lập)
13. **[TEC-1604] Sentry integration** (P2, independent) 13. **[TEC-1604] Tích hợp Sentry** (P2, độc lập)
``` ```
TEC-1592 (Commit) ──┬── TEC-1595 (Agent Portal) TEC-1592 (Commit) ──┬── TEC-1595 (Agent Portal)
@@ -182,51 +182,51 @@ TEC-1599..1604 (P2 quality) ── (all independent, parallel)
--- ---
## Dependency Map (Phase 6) ## Bản đồ phụ thuộc (Phase 6)
| Task | Depends On | | Task | Phụ thuộc vào |
| --------------- | ----------------- | | --------------- | ----------------- |
| TEC-1592 | None | | TEC-1592 | Không |
| TEC-1593 | None | | TEC-1593 | Không |
| TEC-1594 | None | | TEC-1594 | Không |
| TEC-1595 | TEC-1592 | | TEC-1595 | TEC-1592 |
| TEC-1596 | TEC-1592 | | TEC-1596 | TEC-1592 |
| TEC-1597 | TEC-1592 | | TEC-1597 | TEC-1592 |
| TEC-1598 | None | | TEC-1598 | Không |
| TEC-1599 | None | | TEC-1599 | Không |
| TEC-1600 | None | | TEC-1600 | Không |
| TEC-1601 | None | | TEC-1601 | Không |
| TEC-1602 | Phase 4 security | | TEC-1602 | Bảo mật Phase 4 |
| TEC-1603 | None | | TEC-1603 | Không |
| TEC-1604 | None | | TEC-1604 | Không |
### Milestone 8: Post-MVP Improvements (Phase 7) ### Milestone 8: Cải tiến sau MVP (Phase 7)
**Goal:** Fix remaining bugs, harden for production, improve UX and DX. **Mục tiêu:** Sửa các bug còn lại, củng cố cho production, cải thiện UX và DX.
**Wave 1 — Critical Bug Fixes (1-2 days):** **Wave 1 — Sửa lỗi quan trọng (1-2 ngày):**
1. **[TEC-1647] Fix Reviews routing** (P0, no deps) 1. **[TEC-1647] Sửa định tuyến Reviews** (P0, không có dependency)
2. **[TEC-1648] Fix Health endpoints** (P0, no deps) 2. **[TEC-1648] Sửa các Health endpoint** (P0, không có dependency)
3. **[TEC-1649] Fix Login error handling** (P0, needs DB) 3. **[TEC-1649] Sửa xử lý lỗi Login** (P0, cần DB)
4. **[TEC-1650] Fix Listing 404** (P1, needs DB) 4. **[TEC-1650] Sửa Listing 404** (P1, cần DB)
**Wave 2 — Production Readiness (3-5 days):** **Wave 2 — Sẵn sàng Production (3-5 ngày):**
5. **[TEC-1651] E2E CI environment** (P1, no deps) 5. **[TEC-1651] Môi trường E2E CI** (P1, không có dependency)
6. **[TEC-1652] Run E2E tests** (P1, after Wave 1 fixes) 6. **[TEC-1652] Chạy E2E test** (P1, sau các fix Wave 1)
7. **[TEC-1653] Security headers audit** (P1, no deps) 7. **[TEC-1653] Audit security header** (P1, không có dependency)
8. **[TEC-1658] PgBouncer pooling** (P1, no deps) 8. **[TEC-1658] PgBouncer pooling** (P1, không có dependency)
**Wave 3 — User-Facing Quality (1-2 weeks):** **Wave 3 — Chất lượng hướng tới người dùng (1-2 tuần):**
9. **[TEC-1654] Mobile responsive** (P1, no deps) 9. **[TEC-1654] Mobile responsive** (P1, không có dependency)
10. **[TEC-1655] SEO optimization** (P1, no deps) 10. **[TEC-1655] Tối ưu SEO** (P1, không có dependency)
11. **[TEC-1656] Per-user rate limiting** (P1, no deps) 11. **[TEC-1656] Rate limiting theo người dùng** (P1, không có dependency)
12. **[TEC-1657] Admin audit logging** (P1, no deps) 12. **[TEC-1657] Audit logging cho admin** (P1, không có dependency)
**Wave 4 — Engineering Excellence (2-3 weeks):** **Wave 4 — Xuất sắc về Engineering (2-3 tuần):**
13. **[TEC-1659] Graceful degradation** (P2, no deps) 13. **[TEC-1659] Graceful degradation** (P2, không có dependency)
14. **[TEC-1660] Error codes documentation** (P2, no deps) 14. **[TEC-1660] Tài liệu mã lỗi** (P2, không có dependency)
15. **[TEC-1661] RUM + Web Vitals** (P2, no deps) 15. **[TEC-1661] RUM + Web Vitals** (P2, không có dependency)
16. **[TEC-1662] Update QA Tracker** (P2, after Wave 2) 16. **[TEC-1662] Cập nhật QA Tracker** (P2, sau Wave 2)
``` ```
TEC-1647 (Reviews) ──┐ TEC-1647 (Reviews) ──┐
@@ -242,39 +242,39 @@ TEC-1659..1661 (Wave 4) ── (all independent, parallel)
--- ---
## Dependency Map (Phase 7) ## Bản đồ phụ thuộc (Phase 7)
| Task | Depends On | | Task | Phụ thuộc vào |
| --------------- | ----------------- | | --------------- | ----------------- |
| TEC-1647 | None | | TEC-1647 | Không |
| TEC-1648 | None | | TEC-1648 | Không |
| TEC-1649 | None | | TEC-1649 | Không |
| TEC-1650 | None | | TEC-1650 | Không |
| TEC-1651 | None | | TEC-1651 | Không |
| TEC-1652 | TEC-1647, TEC-1648 | | TEC-1652 | TEC-1647, TEC-1648 |
| TEC-1653 | None | | TEC-1653 | Không |
| TEC-1654 | None | | TEC-1654 | Không |
| TEC-1655 | None | | TEC-1655 | Không |
| TEC-1656 | None | | TEC-1656 | Không |
| TEC-1657 | None | | TEC-1657 | Không |
| TEC-1658 | None | | TEC-1658 | Không |
| TEC-1659 | None | | TEC-1659 | Không |
| TEC-1660 | None | | TEC-1660 | Không |
| TEC-1661 | None | | TEC-1661 | Không |
| TEC-1662 | TEC-1652 | | TEC-1662 | TEC-1652 |
### Milestone 9: CEO Audit Wave 5 — Security & Features (Phase 7 continued) ### Milestone 9: Audit của CEO Wave 5 — Bảo mật & Tính năng (Phase 7 tiếp)
**Goal:** Address security vulnerabilities, improve test coverage, implement missing Sprint 3 feature. **Mục tiêu:** Xử lý các lỗ hổng bảo mật, cải thiện độ bao phủ test, triển khai tính năng còn thiếu của Sprint 3.
**Wave 5a — Security (DAY 1-2, parallel):** **Wave 5a — Bảo mật (NGÀY 1-2, song song):**
1. **[TEC-1684] Fix npm vulnerabilities** (P0, Security Engineer) 1. **[TEC-1684] Sửa lỗ hổng npm** (P0, Security Engineer)
2. **[TEC-1685] Fix lint error** (P1, QA Engineer) 2. **[TEC-1685] Sửa lỗi lint** (P1, QA Engineer)
**Wave 5b — Quality & Features (WEEK 1-2):** **Wave 5b — Chất lượng & Tính năng (TUẦN 1-2):**
3. **[TEC-1686] Test coverage push** (P1, QA Engineer, after 5a) 3. **[TEC-1686] Đẩy mạnh độ bao phủ test** (P1, QA Engineer, sau 5a)
4. **[TEC-1688] Saved Searches + Alerts** (P1, Architect) 4. **[TEC-1688] Saved Searches + Alerts** (P1, Architect)
5. **[TEC-1687] Dependabot setup** (P2, DevOps Engineer) 5. **[TEC-1687] Thiết lập Dependabot** (P2, DevOps Engineer)
``` ```
TEC-1684 (NPM Vuln) ─────── (independent, P0) TEC-1684 (NPM Vuln) ─────── (independent, P0)
@@ -285,43 +285,43 @@ TEC-1687 (Dependabot) ────── (independent, P2)
--- ---
## Dependency Map (Wave 5) ## Bản đồ phụ thuộc (Wave 5)
| Task | Depends On | | Task | Phụ thuộc vào |
| --------------- | ----------------- | | --------------- | ----------------- |
| TEC-1684 | None | | TEC-1684 | Không |
| TEC-1685 | None | | TEC-1685 | Không |
| TEC-1686 | TEC-1685 | | TEC-1686 | TEC-1685 |
| TEC-1687 | None | | TEC-1687 | Không |
| TEC-1688 | None | | TEC-1688 | Không |
--- ---
## Rollout Notes ## Ghi chú triển khai
- **Phase 0-6 complete** — 51/51 tasks done, MVP feature-complete - **Phase 0-6 đã hoàn thành** — 51/51 task xong, MVP hoàn chỉnh tính năng
- **Phase 7 is current priority** — bug fixes and production hardening - **Phase 7 là ưu tiên hiện tại** — sửa bug và củng cố production
- **Wave 13 is current sprint** — 6 tasks (TEC-1918 through TEC-1923) - **Wave 13 là sprint hiện tại** — 6 task (TEC-1918 đến TEC-1923)
- **Total project status** (from Paperclip, 2026-04-12): 219 done / 3 in progress / 9 todo / 3 cancelled out of 234 issues - **Tổng trạng thái dự án** (từ Paperclip, 2026-04-12): 219 done / 3 in progress / 9 todo / 3 cancelled trên tổng số 234 issue
- **Critical path:** TEC-1918 (TS errors) → TEC-1919 (E2E unblock) → production readiness checklist (TEC-1922) - **Đường găng:** TEC-1918 (TS errors) → TEC-1919 (E2E unblock) → checklist sẵn sàng production (TEC-1922)
- **Priorities:** CI green (TEC-1918), E2E (TEC-1919), backlog grooming (TEC-1920), /pricing page (TEC-1921) - **Ưu tiên:** CI green (TEC-1918), E2E (TEC-1919), grooming backlog (TEC-1920), trang /pricing (TEC-1921)
- **Production path:** Wave 13 fixes → production readiness checklist → go-live decision - **Lộ trình production:** Các fix Wave 13 → checklist sẵn sàng production → quyết định go-live
### Milestone 13: CEO Audit Wave 13 (Phase 7 continued) ### Milestone 13: Audit của CEO Wave 13 (Phase 7 tiếp)
**Goal:** Fix remaining TS errors, unblock E2E, groom backlog, complete pricing page, production readiness checklist. **Mục tiêu:** Sửa các lỗi TS còn lại, gỡ chặn E2E, grooming backlog, hoàn thành trang pricing, checklist sẵn sàng production.
**Wave 13A — CI Fix (Day 1):** **Wave 13A — Sửa CI (Ngày 1):**
1. **[TEC-1918] Fix 7 TS compile errors in web test files** (P0, Senior Backend Engineer) 1. **[TEC-1918] Sửa 7 lỗi biên dịch TS trong các file test web** (P0, Senior Backend Engineer)
**Wave 13B — Features & Quality (Days 2-3):** **Wave 13B — Tính năng & Chất lượng (Ngày 2-3):**
2. **[TEC-1919] Unblock E2E test environment** (P1, DevOps Engineer) 2. **[TEC-1919] Gỡ chặn môi trường E2E test** (P1, DevOps Engineer)
3. **[TEC-1920] Backlog grooming — deduplicate and close resolved** (P1, QA Engineer) 3. **[TEC-1920] Grooming backlog — loại bỏ trùng lặp và đóng các task đã giải quyết** (P1, QA Engineer)
4. **[TEC-1921] Complete /pricing page** (P1, Senior Frontend Engineer) 4. **[TEC-1921] Hoàn thành trang /pricing** (P1, Senior Frontend Engineer)
**Wave 13C — Documentation & Readiness (Days 3-5):** **Wave 13C — Tài liệu & Sẵn sàng (Ngày 3-5):**
5. **[TEC-1922] Production readiness checklist** (P2, SRE Engineer) 5. **[TEC-1922] Checklist sẵn sàng production** (P2, SRE Engineer)
6. **[TEC-1923] Update PROJECT_TRACKER.md** (P2, Technical Writer) 6. **[TEC-1923] Cập nhật PROJECT_TRACKER.md** (P2, Technical Writer)
``` ```
TEC-1918 (TS Errors) ──→ TEC-1919 (E2E Unblock) TEC-1918 (TS Errors) ──→ TEC-1919 (E2E Unblock)
@@ -333,31 +333,31 @@ TEC-1923 (Tracker) ────── (independent)
--- ---
## Dependency Map (Wave 13) ## Bản đồ phụ thuộc (Wave 13)
| Task | Depends On | | Task | Phụ thuộc vào |
| --------------- | ----------------- | | --------------- | ----------------- |
| TEC-1918 | None | | TEC-1918 | Không |
| TEC-1919 | TEC-1918 | | TEC-1919 | TEC-1918 |
| TEC-1920 | None | | TEC-1920 | Không |
| TEC-1921 | None | | TEC-1921 | Không |
| TEC-1922 | TEC-1918, TEC-1919| | TEC-1922 | TEC-1918, TEC-1919|
| TEC-1923 | None | | TEC-1923 | Không |
### Milestone 12: CEO Audit — CI Pipeline Fix (Phase 7 Wave 12) ### Milestone 12: Audit của CEO — Sửa CI Pipeline (Phase 7 Wave 12)
**Goal:** Restore CI pipeline to green. Fix all TypeScript, ESLint, and test failures. Commit outstanding work. **Mục tiêu:** Khôi phục CI pipeline về trạng thái xanh. Sửa tất cả các lỗi TypeScript, ESLint và test. Commit công việc còn tồn đọng.
**Wave 12A — Fix CI (Day 1, parallel):** **Wave 12A — Sửa CI (Ngày 1, song song):**
1. **[TEC-1898] Fix Prisma 7 migration** (P0, Senior Backend Engineer) 1. **[TEC-1898] Sửa migration Prisma 7** (P0, Senior Backend Engineer)
2. **[TEC-1899] Fix 31 failing unit tests** (P0, QA Engineer) 2. **[TEC-1899] Sửa 31 unit test thất bại** (P0, QA Engineer)
3. **[TEC-1900] Fix ESLint errors + commit files** (P0, Senior Backend Engineer, after TEC-1898) 3. **[TEC-1900] Sửa lỗi ESLint + commit file** (P0, Senior Backend Engineer, sau TEC-1898)
**Wave 12B — Bug Fixes (Days 2-3):** **Wave 12B — Sửa lỗi (Ngày 2-3):**
4. **[TEC-1649] Login 500→401 fix** (P1, in progress) 4. **[TEC-1649] Fix Login 500→401** (P1, đang tiến hành)
5. **[TEC-1657] Admin audit logging** (P1, todo) 5. **[TEC-1657] Audit logging cho admin** (P1, todo)
6. **[TEC-1878] E2E environment** (P1, DevOps Engineer) 6. **[TEC-1878] Môi trường E2E** (P1, DevOps Engineer)
7. **[TEC-1847] React component tests** (P1, QA Engineer) 7. **[TEC-1847] Test component React** (P1, QA Engineer)
``` ```
TEC-1898 (Prisma Fix) ──┬── TEC-1900 (ESLint + Commit) TEC-1898 (Prisma Fix) ──┬── TEC-1900 (ESLint + Commit)
@@ -370,14 +370,14 @@ TEC-1847 (RTL Tests) ──── (independent)
--- ---
## Dependency Map (Wave 12) ## Bản đồ phụ thuộc (Wave 12)
| Task | Depends On | | Task | Phụ thuộc vào |
| --------------- | ----------------- | | --------------- | ----------------- |
| TEC-1898 | None | | TEC-1898 | Không |
| TEC-1899 | None | | TEC-1899 | Không |
| TEC-1900 | TEC-1898 | | TEC-1900 | TEC-1898 |
| TEC-1649 | None | | TEC-1649 | Không |
| TEC-1657 | None | | TEC-1657 | Không |
| TEC-1878 | None | | TEC-1878 | Không |
| TEC-1847 | None | | TEC-1847 | Không |

292
docs/architecture/IMPLEMENTATION_QUICK_REFERENCE.md
View File

@@ -1,19 +1,19 @@
# GoodGo Frontend: i18n + A11y Implementation Quick Reference # GoodGo Frontend: Tham chiếu nhanh triển khai i18n + A11y
## 🎯 Key Findings at a Glance ## 🎯 Những phát hiện chính trong nháy mắt
### Current State ### Trạng thái hiện tại
- ✅ **Next.js 15** with App Router (well-structured) - ✅ **Next.js 15** với App Router (cấu trúc tốt)
- ✅ **React 18** + TypeScript (type-safe) - ✅ **React 18** + TypeScript (an toàn kiểu)
- ✅ **Tailwind CSS** with dark mode support (HSL-based theme) - ✅ **Tailwind CSS** với hỗ trợ dark mode (theme dựa trên HSL)
- ✅ **Good component library** (~35 components) - ✅ **Thư viện component tốt** (~35 component)
- ✅ **Some A11y basics** in place (semantic HTML, ARIA labels, skip link) - ✅ **Một số kiến thức cơ bản về A11y** đã có (HTML ngữ nghĩa, ARIA labels, skip link)
- ❌ **NO i18n setup** (everything hardcoded Vietnamese) - ❌ **CHƯA thiết lập i18n** (tất cả tiếng Việt được hardcode)
- ❌ **A11y gaps** (focus management, some ARIA missing, color contrast TBD) - ❌ **Thiếu sót A11y** (quản lý focus, một số ARIA còn thiếu, tương phản màu chưa xác định)
### Strategic Entry Points for Implementation ### Điểm vào chiến lược cho việc triển khai
#### 1. **i18n Entry Points** (Priority 1) #### 1. **Điểm vào i18n** (Ưu tiên 1)
``` ```
Files to modify for i18n: Files to modify for i18n:
├── app/layout.tsx → Add i18n provider ├── app/layout.tsx → Add i18n provider
@@ -29,7 +29,7 @@ Files to modify for i18n:
Total files to update: ~25-30 files with hardcoded strings Total files to update: ~25-30 files with hardcoded strings
``` ```
#### 2. **A11y Critical Fixes** (Priority 1.5) #### 2. **Sửa lỗi A11y quan trọng** (Ưu tiên 1.5)
``` ```
Components needing A11y updates: Components needing A11y updates:
├── components/ui/dialog.tsx → Focus trapping + focus restoration ├── components/ui/dialog.tsx → Focus trapping + focus restoration
@@ -46,7 +46,7 @@ Tasks:
- Link form errors to inputs with aria-describedby - Link form errors to inputs with aria-describedby
``` ```
#### 3. **Message File Structure for i18n** #### 3. **Cấu trúc file Message cho i18n**
``` ```
public/locales/ public/locales/
├── en.json ├── en.json
@@ -64,142 +64,142 @@ public/locales/
--- ---
## 📋 Implementation Checklist ## 📋 Checklist triển khai
### Phase 1: Setup (2-3 hours) ### Giai đoạn 1: Thiết lập (2-3 giờ)
- [ ] Install `next-intl` package - [ ] Cài đặt gói `next-intl`
- [ ] Create message files (en.json, vi.json) - [ ] Tạo các file message (en.json, vi.json)
- [ ] Update next.config.js for i18n routing - [ ] Cập nhật next.config.js cho routing i18n
- [ ] Create i18n config (config.ts) - [ ] Tạo cấu hình i18n (config.ts)
- [ ] Update middleware.ts for locale detection - [ ] Cập nhật middleware.ts để phát hiện locale
- [ ] Wrap root layout with i18n provider - [ ] Bao bọc root layout bằng provider i18n
### Phase 2: Core Refactoring (6-8 hours) ### Giai đoạn 2: Tái cấu trúc cốt lõi (6-8 giờ)
- [ ] Update root layout & metadata - [ ] Cập nhật root layout & metadata
- [ ] Refactor all validations (Zod) to use messages - [ ] Tái cấu trúc tất cả validation (Zod) để sử dụng messages
- [ ] Extract component strings to useTranslations() - [ ] Trích xuất chuỗi component sang useTranslations()
- [ ] Update all enums (TRANSACTION_TYPES, PROPERTY_TYPES, etc.) to use i18n - [ ] Cập nhật tất cả các enum (TRANSACTION_TYPES, PROPERTY_TYPES, v.v.) để sử dụng i18n
- [ ] Update page layouts (public, auth, dashboard) - [ ] Cập nhật các page layout (public, auth, dashboard)
- [ ] Update all page content - [ ] Cập nhật toàn bộ nội dung trang
### Phase 3: Component Updates (4-6 hours) ### Giai đoạn 3: Cập nhật component (4-6 giờ)
- [ ] Update all UI components - [ ] Cập nhật tất cả các component UI
- [ ] Update form components - [ ] Cập nhật các component form
- [ ] Update navigation components - [ ] Cập nhật các component navigation
- [ ] Update search/filter components - [ ] Cập nhật các component search/filter
- [ ] Update listing form - [ ] Cập nhật form đăng tin (listing form)
### Phase 4: A11y Fixes (4-6 hours) ### Giai đoạn 4: Sửa lỗi A11y (4-6 giờ)
- [ ] Fix focus management in dialogs - [ ] Sửa quản lý focus trong dialog
- [ ] Add focus trapping - [ ] Thêm focus trapping
- [ ] Update form error linking (aria-describedby) - [ ] Cập nhật liên kết lỗi form (aria-describedby)
- [ ] Add aria-busy to loading states - [ ] Thêm aria-busy cho trạng thái loading
- [ ] Add aria-labels to icon buttons - [ ] Thêm aria-label cho các nút biểu tượng
- [ ] Verify color contrast - [ ] Xác minh tương phản màu
- [ ] Update test setup for i18n - [ ] Cập nhật thiết lập test cho i18n
### Phase 5: Testing & QA (3-4 hours) ### Giai đoạn 5: Test & QA (3-4 giờ)
- [ ] Test both locales on all pages - [ ] Test cả hai locale trên tất cả các trang
- [ ] Run axe DevTools accessibility audit - [ ] Chạy kiểm tra khả năng tiếp cận bằng axe DevTools
- [ ] Test keyboard navigation - [ ] Test điều hướng bằng bàn phím
- [ ] Test screen reader compatibility - [ ] Test tương thích screen reader
- [ ] Update unit tests for i18n - [ ] Cập nhật unit test cho i18n
--- ---
## 🗣️ Text Content Inventory ## 🗣️ Kiểm kê nội dung văn bản
### Navigation & Layout (~15 items) ### Navigation & Layout (~15 mục)
| Location | Text | Status | | Vị trí | Văn bản | Trạng thái |
|----------|------|--------| |----------|------|--------|
| Public header | Trang chủ, Tìm kiếm, Đăng nhập, Đăng ký | ❌ Hardcoded | | Public header | Trang chủ, Tìm kiếm, Đăng nhập, Đăng ký | ❌ Hardcoded |
| Dashboard nav | 8 nav items | ❌ Hardcoded | | Dashboard nav | 8 mục nav | ❌ Hardcoded |
| Footer | 4 sections | ❌ Hardcoded | | Footer | 4 phần | ❌ Hardcoded |
### Forms & Validation (~40+ items) ### Forms & Validation (~40+ mục)
| Location | Type | Count | Status | | Vị trí | Loại | Số lượng | Trạng thái |
|----------|------|-------|--------| |----------|------|-------|--------|
| Login form | Labels + errors | 8 | ❌ Hardcoded | | Login form | Nhãn + lỗi | 8 | ❌ Hardcoded |
| Register form | Labels + errors | 10 | ❌ Hardcoded | | Register form | Nhãn + lỗi | 10 | ❌ Hardcoded |
| Listing form | Multi-step labels | 25+ | ❌ Hardcoded | | Listing form | Nhãn đa bước | 25+ | ❌ Hardcoded |
| Search filters | Option labels | 30+ | ❌ Hardcoded | | Search filters | Nhãn tùy chọn | 30+ | ❌ Hardcoded |
| Zod validation | Error messages | 20+ | ❌ Hardcoded | | Zod validation | Thông báo lỗi | 20+ | ❌ Hardcoded |
### Enums & Constants (~50+ items) ### Enum & Hằng số (~50+ mục)
| File | Items | Status | | File | Mục | Trạng thái |
|------|-------|--------| |------|-------|--------|
| TRANSACTION_TYPES | 2 labels | ❌ Hardcoded | | TRANSACTION_TYPES | 2 nhãn | ❌ Hardcoded |
| PROPERTY_TYPES | 6 labels | ❌ Hardcoded | | PROPERTY_TYPES | 6 nhãn | ❌ Hardcoded |
| LISTING_STATUSES | 8 labels | ❌ Hardcoded | | LISTING_STATUSES | 8 nhãn | ❌ Hardcoded |
| DIRECTIONS | 8 labels | ❌ Hardcoded | | DIRECTIONS | 8 nhãn | ❌ Hardcoded |
| CITIES | 13 names | ❌ Hardcoded | | CITIES | 13 tên | ❌ Hardcoded |
| PRICE_RANGES | 6 ranges | ❌ Hardcoded | | PRICE_RANGES | 6 khoảng | ❌ Hardcoded |
### Page Content (~30 items) ### Nội dung trang (~30 mục)
| Page | Sections | Status | | Trang | Phần | Trạng thái |
|------|----------|--------| |------|----------|--------|
| Landing page | Hero, search, stats, CTA | ❌ Hardcoded | | Trang landing | Hero, search, stats, CTA | ❌ Hardcoded |
| Search results | No results, loading, headers | ❌ Hardcoded | | Kết quả tìm kiếm | Không có kết quả, loading, header | ❌ Hardcoded |
| Dashboard | Section titles, empty states | ❌ Hardcoded | | Dashboard | Tiêu đề phần, trạng thái rỗng | ❌ Hardcoded |
--- ---
## 🔑 Critical Files for i18n ## 🔑 Các file quan trọng cho i18n
### Must-Update Files (Blockers) ### Các file phải cập nhật (Blocker)
1. **middleware.ts** — Locale routing 1. **middleware.ts** — Định tuyến locale
2. **app/layout.tsx** — i18n provider setup 2. **app/layout.tsx** — Thiết lập provider i18n
3. **lib/validations/*.ts** — Message integration 3. **lib/validations/*.ts** — Tích hợp messages
4. **lib/*.ts** — Any API error message handling 4. **lib/*.ts** — Bất kỳ xử lý thông báo lỗi API nào
### High-Priority Files ### Các file ưu tiên cao
1. **app/(public)/layout.tsx** — Navigation 1. **app/(public)/layout.tsx** — Navigation
2. **app/(auth)/login/page.tsx** — Auth forms 2. **app/(auth)/login/page.tsx** — Form xác thực
3. **components/listings/listing-form-steps.tsx** — Forms 3. **components/listings/listing-form-steps.tsx** — Forms
4. **components/search/filter-bar.tsx** — Filters 4. **components/search/filter-bar.tsx** — Bộ lọc
### Medium-Priority Files ### Các file ưu tiên trung bình
1. All page components 1. Tất cả các component trang
2. All UI components with text 2. Tất cả các component UI có văn bản
3. Error boundary components 3. Các component error boundary
--- ---
## ♿ A11y Implementation Priority ## ♿ Ưu tiên triển khai A11y
### WCAG 2.1 AA Critical Fixes ### Sửa lỗi quan trọng WCAG 2.1 AA
1. **Focus Management** (Level A) 1. **Quản lý focus** (Cấp A)
- Add focus trap in `dialog.tsx` - Thêm focus trap trong `dialog.tsx`
- Restore focus on dialog close - Khôi phục focus khi đóng dialog
- Visible focus indicator on all buttons - Chỉ báo focus rõ ràng trên tất cả các nút
2. **Color Contrast** (Level AA) 2. **Tương phản màu** (Cấp AA)
- Run axe DevTools audit - Chạy kiểm tra axe DevTools
- Fix any < 4.5:1 ratio text - Sửa văn bản có tỷ lệ < 4.5:1
- Fix < 3:1 ratio graphics - Sửa đồ họa có tỷ lệ < 3:1
3. **Form Accessibility** (Level A) 3. **Khả năng tiếp cận form** (Cấp A)
- Link all error messages with aria-describedby - Liên kết tất cả thông báo lỗi với aria-describedby
- Proper labeling with htmlFor - Gắn nhãn đúng cách với htmlFor
- Fieldset grouping for complex forms - Nhóm fieldset cho các form phức tạp
4. **Loading States** (Level A) 4. **Trạng thái Loading** (Cấp A)
- Add aria-busy to spinners - Thêm aria-busy cho spinner
- Add aria-label with context - Thêm aria-label kèm ngữ cảnh
5. **Icon Buttons** (Level A) 5. **Nút biểu tượng** (Cấp A)
- All icon-only buttons need aria-label - Tất cả các nút chỉ có biểu tượng cần aria-label
- Theme toggle button already has label ✓ - Nút bật/tắt theme đã có nhãn ✓
### Nice-to-Have A11y Enhancements ### Các cải tiến A11y nên có
- Skip link already present ✓ - Skip link đã có sẵn ✓
- Semantic HTML already used ✓ - HTML ngữ nghĩa đã được sử dụng ✓
- Role="alert" on errors ✓ - Role="alert" trên lỗi ✓
- aria-invalid on form fields ✓ - aria-invalid trên các trường form ✓
--- ---
## 📦 Dependencies to Add ## 📦 Các phụ thuộc cần thêm
```bash ```bash
npm install next-intl npm install next-intl
@@ -208,11 +208,11 @@ npm install next-intl
# Testing with mocked i18n available # Testing with mocked i18n available
``` ```
**Total installation footprint:** ~500KB minified **Tổng kích thước cài đặt:** ~500KB đã minify
--- ---
## 🧪 Testing Strategy ## 🧪 Chiến lược test
### Unit Tests ### Unit Tests
```typescript ```typescript
@@ -241,43 +241,43 @@ describe('LoginForm', () => {
--- ---
## 📊 Estimated Timeline ## 📊 Lộ trình ước tính
| Phase | Duration | Effort | | Giai đoạn | Thời gian | Công sức |
|-------|----------|--------| |-------|----------|--------|
| Setup | 2-3h | Low | | Thiết lập | 2-3h | Thấp |
| Core Refactoring | 6-8h | Medium | | Tái cấu trúc cốt lõi | 6-8h | Trung bình |
| Components | 4-6h | Medium | | Components | 4-6h | Trung bình |
| A11y Fixes | 4-6h | Low-Medium | | Sửa lỗi A11y | 4-6h | Thấp-Trung bình |
| Testing | 3-4h | Medium | | Testing | 3-4h | Trung bình |
| **Total** | **19-27h** | **~3-4 days** | | **Tổng** | **19-27h** | **~3-4 ngày** |
--- ---
## 🚀 Implementation Order (Recommended) ## 🚀 Thứ tự triển khai (Khuyến nghị)
1. **Setup i18n infrastructure** (creates foundation) 1. **Thiết lập hạ tầng i18n** (tạo nền tảng)
2. **Update middleware + root layout** (enables routing) 2. **Cập nhật middleware + root layout** (kích hoạt routing)
3. **Extract & centralize all text** (main work) 3. **Trích xuất & tập trung tất cả văn bản** (công việc chính)
4. **Fix A11y issues** (parallelize with #3) 4. **Sửa các vấn đề A11y** (song song với #3)
5. **Test thoroughly** (final verification) 5. **Test kỹ lưỡng** (xác minh cuối cùng)
--- ---
## 💡 Quick Win Opportunities ## 💡 Cơ hội thắng nhanh
These can be done immediately: Những việc có thể làm ngay:
1. Create message file structure (30 min) 1. Tạo cấu trúc file message (30 phút)
2. Add focus trap to dialog (30 min) 2. Thêm focus trap cho dialog (30 phút)
3. Add aria-busy to spinners (20 min) 3. Thêm aria-busy cho spinner (20 phút)
4. Color contrast audit (1 hour) 4. Kiểm tra tương phản màu (1 giờ)
5. Icon button aria-labels (30 min) 5. Aria-label cho nút biểu tượng (30 phút)
--- ---
## 📝 Notes for Implementation ## 📝 Ghi chú khi triển khai
### Locale Detection (middleware) ### Phát hiện locale (middleware)
```typescript ```typescript
// Check in order: URL > cookie > header > default // Check in order: URL > cookie > header > default
function getLocale(request) { function getLocale(request) {
@@ -288,19 +288,19 @@ function getLocale(request) {
} }
``` ```
### Message Fallback Strategy ### Chiến lược dự phòng Message
```typescript ```typescript
// If translation missing, use English as fallback // If translation missing, use English as fallback
// Otherwise fallback to Vietnamese (primary) // Otherwise fallback to Vietnamese (primary)
``` ```
### Performance Considerations ### Cân nhắc về hiệu năng
- Keep message files < 100KB each - Giữ các file message < 100KB mỗi file
- Lazy load per-page messages if needed - Lazy load message theo trang nếu cần
- Static generation for SEO-critical pages - Static generation cho các trang quan trọng về SEO
--- ---
**Last Updated:** April 9, 2026 **Cập nhật lần cuối:** Ngày 9 tháng 4 năm 2026
**Version:** 1.0 - Pre-Implementation **Phiên bản:** 1.0 - Trước triển khai
**Confidence:** High **Độ tin cậy:** Cao

346
docs/audits/AUDIT_INDEX.md
View File

@@ -1,80 +1,80 @@
# GoodGo Platform AI — Audit Reports Index # GoodGo Platform AI — Mục lục báo cáo Audit
**Generated**: 2026-04-11 | **Status**: Wave 10 (Active Development) **Tạo ngày**: 2026-04-11 | **Trạng thái**: Wave 10 (Đang phát triển)
--- ---
## Quick Links ## Liên kết nhanh
### 📋 Main Audit Reports ### 📋 Báo cáo Audit chính
1. **[COMPREHENSIVE_AUDIT_2026-04-11.md](COMPREHENSIVE_AUDIT_2026-04-11.md)** (768 lines) 1. **[COMPREHENSIVE_AUDIT_2026-04-11.md](COMPREHENSIVE_AUDIT_2026-04-11.md)** (768 dòng)
- Complete codebase analysis with all 10 required sections - Phân tích toàn bộ mã nguồn với cả 10 phần yêu cầu
- Detailed module inventory, architecture breakdown, metrics - Kiểm kê module chi tiết, phân tích kiến trúc, số liệu
- Strengths, weaknesses, and actionable recommendations - Điểm mạnh, điểm yếu và các khuyến nghị hành động
2. **[AUDIT_SUMMARY_2026-04-11.txt](AUDIT_SUMMARY_2026-04-11.txt)** (Quick Reference) 2. **[AUDIT_SUMMARY_2026-04-11.txt](AUDIT_SUMMARY_2026-04-11.txt)** (Tham chiếu nhanh)
- Executive summary with key metrics and scores - Tóm tắt điều hành với các số liệu và điểm số chính
- Visual breakdown of codebase structure - Sơ đồ trực quan cấu trúc mã nguồn
- Priority recommendations at a glance - Khuyến nghị ưu tiên trong nháy mắt
--- ---
## Audit Scope (All 10 Requirements Covered) ## Phạm vi Audit (Bao phủ cả 10 yêu cầu)
### ✅ 1. Top-Level Structure ### ✅ 1. Cấu trúc cấp cao nhất
- **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 1 - **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 1
- **Coverage**: All root directories, 10 config files, monorepo setup - **Phạm vi**: Tất cả thư mục gốc, 10 file config, thiết lập monorepo
- **Status**: Complete - **Trạng thái**: Hoàn tất
### ✅ 2. Apps/API Module Analysis ### ✅ 2. Phân tích Module Apps/API
- **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 2 - **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 2
- **Coverage**: 16 API modules, layer analysis, 788 TypeScript files, 229 tests - **Phạm vi**: 16 module API, phân tích theo lớp, 788 file TypeScript, 229 test
- **Findings**: 13 full-stack modules, 3 incomplete (health, metrics, mcp) - **Phát hiện**: 13 module full-stack, 3 module chưa hoàn chỉnh (health, metrics, mcp)
### ✅ 3. Apps/Web Frontend ### ✅ 3. Frontend Apps/Web
- **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 3 - **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 3
- **Coverage**: 28 routes across 4 layout groups, 66 components, 16,568 LOC - **Phạm vi**: 28 route trên 4 nhóm layout, 66 component, 16.568 LOC
- **Findings**: Full Next.js 15 implementation, limited unit tests (6 only) - **Phát hiện**: Triển khai đầy đủ Next.js 15, ít unit test (chỉ 6)
### ✅ 4. Prisma Database Layer ### ✅ 4. Tầng Database Prisma
- **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 4 - **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 4
- **Coverage**: 21 models, 18 enums, 12 migrations, 78 indexes - **Phạm vi**: 21 model, 18 enum, 12 migration, 78 index
- **Findings**: Production-ready schema with GDPR compliance, audit logging - **Phát hiện**: Schema sẵn sàng production với tuân thủ GDPR, audit logging
### ✅ 5. Shared Libraries (libs/) ### ✅ 5. Shared Libraries (libs/)
- **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 5 - **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 5
- **Coverage**: AI services (21 Python files), MCP servers (12 TypeScript files) - **Phạm vi**: AI services (21 file Python), MCP servers (12 file TypeScript)
- **Findings**: AI services minimal, MCP servers are stubs needing implementation - **Phát hiện**: AI services còn tối thiểu, MCP servers mới chỉ là stub cần triển khai
### ✅ 6. E2E Testing ### ✅ 6. Testing E2E
- **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 6 - **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 6
- **Coverage**: 31 Playwright specs (16 API, 15 Web), test organization - **Phạm vi**: 31 Playwright spec (16 API, 15 Web), tổ chức test
- **Findings**: Good E2E coverage, global setup/teardown configured - **Phát hiện**: Độ phủ E2E tốt, đã cấu hình global setup/teardown
### ✅ 7. Configuration Files ### ✅ 7. File cấu hình
- **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 7 - **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 7
- **Coverage**: 10 root config files, 178-line .env.example, Docker stacks - **Phạm vi**: 10 file config gốc, .env.example 178 dòng, Docker stack
- **Findings**: Comprehensive configuration documentation - **Phát hiện**: Tài liệu cấu hình đầy đủ
### ✅ 8. Test Coverage Analysis ### ✅ 8. Phân tích độ phủ Test
- **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 8 - **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 8
- **Coverage**: 745 total test files breakdown by layer and module - **Phạm vi**: Phân tích 745 file test theo lớp và theo module
- **Findings**: 229 API tests, 6 web tests, 31 E2E specs - **Phát hiện**: 229 API test, 6 web test, 31 E2E spec
### ✅ 9. Documentation ### ✅ 9. Tài liệu
- **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 9 - **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 9
- **Coverage**: 89 core docs + 81 audit reports in docs/audits/ - **Phạm vi**: 89 doc cốt lõi + 81 báo cáo audit trong docs/audits/
- **Findings**: Comprehensive documentation trail - **Phát hiện**: Lưu trữ tài liệu toàn diện
### ✅ 10. CI/CD Pipeline ### ✅ 10. CI/CD Pipeline
- **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 10 - **File**: COMPREHENSIVE_AUDIT_2026-04-11.md, Section 10
- **Coverage**: 7 GitHub Actions workflows, 13-service Docker stack - **Phạm vi**: 7 workflow GitHub Actions, Docker stack 13 service
- **Findings**: Production-ready DevOps, Kubernetes-ready - **Phát hiện**: DevOps sẵn sàng production, sẵn sàng Kubernetes
--- ---
## Key Findings Summary ## Tóm tắt phát hiện chính
### 📊 Codebase Metrics ### 📊 Số liệu mã nguồn
``` ```
Total Lines of Code: 76,402 LOC Total Lines of Code: 76,402 LOC
├─ API Backend: 23,926 LOC (31%) ├─ API Backend: 23,926 LOC (31%)
@@ -89,123 +89,123 @@ Documentation: 89 files + 81 audits
Git Commits: 203 Git Commits: 203
``` ```
### 🏗️ Architecture Summary ### 🏗️ Tóm tắt kiến trúc
- **16 NestJS API modules** (13 full-stack with ADIP layers) - **16 module API NestJS** (13 full-stack với lớp ADIP)
- **28 Next.js routes** (public, auth, dashboard, admin) - **28 route Next.js** (public, auth, dashboard, admin)
- **21 Prisma models** (comprehensive domain model) - **21 model Prisma** (mô hình domain đầy đủ)
- **12 database migrations** (schema evolution tracked) - **12 migration database** (theo dõi tiến hoá schema)
- **7 GitHub Actions workflows** (CI/CD complete) - **7 workflow GitHub Actions** (CI/CD hoàn chỉnh)
### 📈 Quality Scores ### 📈 Điểm chất lượng
| Aspect | Score | Status | | Khía cạnh | Điểm | Trạng thái |
|--------|-------|--------| |--------|-------|--------|
| Architecture | 9/10 | ✅ Excellent | | Kiến trúc | 9/10 | ✅ Xuất sắc |
| Code Quality | 8/10 | ✅ Good | | Chất lượng mã | 8/10 | ✅ Tốt |
| Test Coverage | 7/10 | ⚠️ Needs web tests | | Độ phủ test | 7/10 | ⚠️ Cần thêm web test |
| Documentation | 8/10 | ✅ Comprehensive | | Tài liệu | 8/10 | ✅ Đầy đủ |
| CI/CD | 9/10 | ✅ Excellent | | CI/CD | 9/10 | ✅ Xuất sắc |
| Database | 9/10 | ✅ Excellent | | Database | 9/10 | ✅ Xuất sắc |
| Error Handling | 8/10 | ⚠️ Some gaps | | Xử lý lỗi | 8/10 | ⚠️ Còn vài thiếu sót |
| Performance | 8/10 | ✅ Good | | Performance | 8/10 | ✅ Tốt |
| Security | 7/10 | ⚠️ Add MFA | | Bảo mật | 7/10 | ⚠️ Thêm MFA |
| DevOps | 9/10 | ✅ Excellent | | DevOps | 9/10 | ✅ Xuất sắc |
| **OVERALL** | **8.2/10** | **✅ Production-Ready** | | **TỔNG THỂ** | **8.2/10** | **✅ Sẵn sàng Production** |
### 🎯 Key Strengths ### 🎯 Điểm mạnh chính
1. ✅ Mature DDD + CQRS architecture 1. ✅ Kiến trúc DDD + CQRS trưởng thành
2. ✅ 76K LOC of real implementation 2. ✅ 76K LOC triển khai thực sự
3. ✅ 745+ test files (229 API, 31 E2E) 3. ✅ 745+ file test (229 API, 31 E2E)
4. ✅ Modern tech stack (NestJS 11, Next.js 15, PostgreSQL 16) 4. ✅ Tech stack hiện đại (NestJS 11, Next.js 15, PostgreSQL 16)
5. ✅ Strong DevOps (Docker, K8s, GitHub Actions) 5. ✅ DevOps vững chắc (Docker, K8s, GitHub Actions)
6. ✅ Excellent documentation (89 docs + 81 audits) 6. ✅ Tài liệu xuất sắc (89 doc + 81 audit)
7. ✅ Type-safe TypeScript (strict mode) 7. ✅ TypeScript type-safe (strict mode)
8. ✅ 21 models with 78 indexes (optimized) 8. ✅ 21 model với 78 index (đã tối ưu)
### ⚠️ Areas for Improvement ### ⚠️ Các điểm cần cải thiện
1. ⚠️ Incomplete modules (3): health, metrics, mcp 1. ⚠️ Module chưa hoàn chỉnh (3): health, metrics, mcp
2. ⚠️ Web unit tests: only 6 (needs 50% coverage) 2. ⚠️ Web unit test: chỉ 6 (cần đạt 50% coverage)
3. ⚠️ MCP servers: stubs only (~50 lines each) 3. ⚠️ MCP servers: chỉ là stub (~50 dòng mỗi file)
4. ⚠️ Error handling: some CQRS handlers incomplete 4. ⚠️ Xử lý lỗi: một số CQRS handler chưa hoàn chỉnh
5. ⚠️ Security: add field encryption, MFA, rate limiting 5. ⚠️ Bảo mật: thêm mã hoá field, MFA, rate limiting
--- ---
## Recommendations Priority Matrix ## Ma trận ưu tiên khuyến nghị
### 🔴 High Priority (DO NOW) — 30-40 hours ### 🔴 Ưu tiên cao (LÀM NGAY) — 30-40 giờ
1. **Complete incomplete modules** (health, metrics, mcp) 1. **Hoàn thiện các module chưa xong** (health, metrics, mcp)
- Implement full ADIP layers for health/metrics - Triển khai đầy đủ các lớp ADIP cho health/metrics
- Real MCP server implementations - Triển khai MCP server thực sự
- Effort: 5-10 hours - Công sức: 5-10 giờ
2. **Expand web unit tests to 50% coverage** 2. **Mở rộng web unit test lên 50% coverage**
- Focus on critical components (auth, listings, search) - Tập trung vào các component quan trọng (auth, listings, search)
- Effort: 10-15 hours - Công sức: 10-15 giờ
3. **Audit & complete error handling** 3. **Audit & hoàn thiện xử lý lỗi**
- Review remaining CQRS handlers - Rà soát các CQRS handler còn lại
- Ensure consistent error responses - Đảm bảo response lỗi nhất quán
- Effort: 5 hours - Công sức: 5 giờ
### 🟡 Medium Priority (DO SOON) — 40-60 hours ### 🟡 Ưu tiên trung bình (LÀM SỚM) — 40-60 giờ
1. **Add field-level encryption** (PII, payments) 1. **Thêm field-level encryption** (PII, payments)
2. **Implement API rate limiting** (per-endpoint quotas) 2. **Triển khai rate limiting API** (quota theo endpoint)
3. **Add OpenTelemetry tracing** (distributed tracing) 3. **Thêm OpenTelemetry tracing** (distributed tracing)
4. **Expand monitoring dashboards** (Grafana) 4. **Mở rộng dashboard monitoring** (Grafana)
5. **Performance optimization** (query analysis) 5. **Tối ưu hoá performance** (phân tích query)
### 🟢 Low Priority (DO LATER) — Future phases ### 🟢 Ưu tiên thấp (LÀM SAU) — Các giai đoạn sau
1. GraphQL API (optional) 1. GraphQL API (tuỳ chọn)
2. Mobile app (React Native/Flutter) 2. Mobile app (React Native/Flutter)
3. Advanced ML features 3. Tính năng ML nâng cao
4. Multi-tenant support 4. Hỗ trợ multi-tenant
--- ---
## Development Status ## Trạng thái phát triển
### Current Milestone: Wave 10 (Beta Phase) ### Cột mốc hiện tại: Wave 10 (Giai đoạn Beta)
- **MVP Phase**: ✅ COMPLETE (Core modules, DDD architecture) - **Giai đoạn MVP**: ✅ HOÀN TẤT (Các module cốt lõi, kiến trúc DDD)
- **Beta Phase**: 🔄 IN PROGRESS (Testing, refinement, monitoring) - **Giai đoạn Beta**: 🔄 ĐANG TIẾN HÀNH (Test, tinh chỉnh, monitoring)
- **Production Phase**: ⏳ READY (Pending validation) - **Giai đoạn Production**: ⏳ SẴN SÀNG (Chờ kiểm định)
- **Scale Phase**: 📋 PLANNED - **Giai đoạn Scale**: 📋 ĐÃ LÊN KẾ HOẠCH
### Recent Progress (Last 10 commits) ### Tiến độ gần đây (10 commit gần nhất)
- ✅ Added comprehensive alerting rules (Alertmanager) - ✅ Thêm alerting rule đầy đủ (Alertmanager)
- ✅ K6 load testing coverage expanded - ✅ Mở rộng độ phủ load test K6
- ✅ Error handling added to 51 CQRS handlers - ✅ Thêm xử lý lỗi cho 51 CQRS handler
- ✅ Login endpoint fixed (prevented 500 errors) - ✅ Sửa endpoint login (tránh lỗi 500)
- ✅ Email alert templates for saved searches - ✅ Mẫu email alert cho saved searches
- ✅ Unit tests added for MCP, Inquiries, Leads modules - ✅ Thêm unit test cho module MCP, Inquiries, Leads
### Development Velocity ### Vận tốc phát triển
- 203 total commits on master - 203 commit tổng trên master
- ~2 commits/day average - Trung bình ~2 commit/ngày
- Consistent feature delivery & bug fixes - Delivery tính năng & sửa lỗi đều đặn
--- ---
## Deployment Status ## Trạng thái triển khai
### Ready for: ### Sẵn sàng cho:
✅ **MVP Launch** — All core features implemented ✅ **MVP Launch** — Đã triển khai tất cả tính năng cốt lõi
✅ **Staging Deployment** — Full CI/CD pipeline configured ✅ **Staging Deployment** — Pipeline CI/CD đã cấu hình đầy đủ
⏳ **Production** — Pending final validation & load testing ⏳ **Production** — Chờ validation cuối cùng & load test
### Infrastructure Status ### Trạng thái hạ tầng
✅ Local development (docker-compose.yml, 13 services) ✅ Local development (docker-compose.yml, 13 service)
✅ CI environment (docker-compose.ci.yml) ✅ CI environment (docker-compose.ci.yml)
✅ Production stack (docker-compose.prod.yml) ✅ Production stack (docker-compose.prod.yml)
✅ Kubernetes manifests (infra/) ✅ Kubernetes manifest (infra/)
✅ Monitoring (Prometheus + Grafana) ✅ Monitoring (Prometheus + Grafana)
✅ Backup/restore (pg-backup + verification) ✅ Backup/restore (pg-backup + verification)
✅ Load testing (K6 suite) ✅ Load testing (bộ K6)
--- ---
## Technology Stack Summary ## Tóm tắt Technology Stack
| Layer | Technology | Version | | Tầng | Công nghệ | Phiên bản |
|-------|-----------|---------| |-------|-----------|---------|
| Backend | NestJS | 11 | | Backend | NestJS | 11 |
| Frontend | Next.js | 15 | | Frontend | Next.js | 15 |
@@ -224,68 +224,68 @@ Git Commits: 203
--- ---
## How to Use These Reports ## Cách sử dụng các báo cáo này
### For Project Managers ### Dành cho Project Managers
- Read: **AUDIT_SUMMARY_2026-04-11.txt** (quick overview) - Đọc: **AUDIT_SUMMARY_2026-04-11.txt** (tổng quan nhanh)
- Then: **COMPREHENSIVE_AUDIT_2026-04-11.md** sections 1, 8-10 - Sau đó: **COMPREHENSIVE_AUDIT_2026-04-11.md** các phần 1, 8-10
### For Developers ### Dành cho Developers
- Read: **COMPREHENSIVE_AUDIT_2026-04-11.md** entire document - Đọc: toàn bộ **COMPREHENSIVE_AUDIT_2026-04-11.md**
- Reference: **AUDIT_SUMMARY_2026-04-11.txt** for quick stats - Tham khảo: **AUDIT_SUMMARY_2026-04-11.txt** để xem số liệu nhanh
### For Architects ### Dành cho Architects
- Focus: Sections 1-5, 7 of comprehensive audit - Tập trung: Các phần 1-5, 7 của audit toàn diện
- Review: Module completeness, architecture patterns - Rà soát: Mức độ hoàn thiện module, pattern kiến trúc
### For QA/Testers ### Dành cho QA/Testers
- Focus: Sections 6, 8 of comprehensive audit - Tập trung: Các phần 6, 8 của audit toàn diện
- Review: Test coverage, E2E test organization - Rà soát: Độ phủ test, tổ chức E2E test
### For DevOps/Infrastructure ### Dành cho DevOps/Infrastructure
- Focus: Sections 7, 10 of comprehensive audit - Tập trung: Các phần 7, 10 của audit toàn diện
- Review: CI/CD workflows, Docker stack, monitoring - Rà soát: Workflow CI/CD, Docker stack, monitoring
--- ---
## Additional Resources ## Tài nguyên bổ sung
### In Repository ### Trong Repository
- `docs/architecture.md` — Detailed system design - `docs/architecture.md` — Thiết kế hệ thống chi tiết
- `docs/api-endpoints.md` — REST API reference - `docs/api-endpoints.md` — Tham chiếu REST API
- `docs/api-error-codes.md` — Error handling guide - `docs/api-error-codes.md` — Hướng dẫn xử lý lỗi
- `docs/deployment.md` — Production deployment guide - `docs/deployment.md` — Hướng dẫn deploy production
- `IMPLEMENTATION_PLAN.md` — Remaining work - `IMPLEMENTATION_PLAN.md` — Công việc còn lại
- `PROJECT_TRACKER.md` — Development roadmap - `PROJECT_TRACKER.md` — Lộ trình phát triển
- `docs/audits/` — 81 specialized audit reports - `docs/audits/` — 81 báo cáo audit chuyên biệt
### Key Files ### File quan trọng
- `README.md` — Project overview & quick start - `README.md` — Tổng quan dự án & quick start
- `CONTRIBUTING.md` — Development conventions - `CONTRIBUTING.md` — Quy ước phát triển
- `CHANGELOG.md` — Version history - `CHANGELOG.md` — Lịch sử phiên bản
--- ---
## Audit Verification Checklist ## Checklist xác minh Audit
- [x] Top-level structure reviewed (all root directories) - [x] Đã rà soát cấu trúc cấp cao nhất (tất cả thư mục gốc)
- [x] apps/api module analysis complete (16 modules, 788 files) - [x] Hoàn tất phân tích module apps/api (16 module, 788 file)
- [x] apps/web frontend mapped (28 routes, 66 components) - [x] Đã map frontend apps/web (28 route, 66 component)
- [x] prisma schema analyzed (21 models, 12 migrations) - [x] Đã phân tích schema prisma (21 model, 12 migration)
- [x] libs/ libraries reviewed (AI + MCP servers) - [x] Đã rà soát libs/ (AI + MCP servers)
- [x] E2E testing evaluated (31 Playwright specs) - [x] Đã đánh giá E2E testing (31 Playwright spec)
- [x] Configuration files documented (10 root configs) - [x] Đã tài liệu hoá file cấu hình (10 config gốc)
- [x] Test coverage analyzed (745 total files) - [x] Đã phân tích độ phủ test (tổng 745 file)
- [x] Documentation surveyed (89 docs + 81 audits) - [x] Đã khảo sát tài liệu (89 doc + 81 audit)
- [x] CI/CD pipeline reviewed (7 workflows, 13 services) - [x] Đã rà soát CI/CD pipeline (7 workflow, 13 service)
--- ---
**Audit Conducted**: 2026-04-11 **Audit tiến hành**: 2026-04-11
**Status**: ✅ COMPLETE **Trạng thái**: ✅ HOÀN TẤT
**Quality Score**: 8.2/10 (Production-Ready) **Điểm chất lượng**: 8.2/10 (Sẵn sàng Production)
**Next Review**: Recommend after Wave 10 completion **Lần rà soát tiếp theo**: Khuyến nghị sau khi hoàn tất Wave 10
--- ---
*For questions or clarifications, refer to the comprehensive audit document or contact the development team.* *Nếu có thắc mắc hoặc cần làm rõ, vui lòng tham khảo tài liệu audit toàn diện hoặc liên hệ nhóm phát triển.*

236
docs/audits/AUDIT_QUICK_REFERENCE_2026-04-12.md
View File

@@ -1,119 +1,119 @@
# GoodGo Platform AI — QUICK REFERENCE AUDIT (1-Pager) # GoodGo Platform AI — TÀI LIỆU AUDIT THAM CHIẾU NHANH (1 trang)
**Date:** April 12, 2026 | **Status:** 🟢 **PRODUCTION-READY** | **Confidence:** 95% **Ngày:** 12 tháng 4, 2026 | **Trạng thái:** 🟢 **SẴN SÀNG PRODUCTION** | **Mức độ tin cậy:** 95%
--- ---
## TL;DR — THE ESSENTIALS ## TÓM TẮT — NHỮNG ĐIỂM CỐT LÕI
| Aspect | Rating | Summary | | Khía cạnh | Đánh giá | Tóm tắt |
|--------|--------|---------| |--------|--------|---------|
| **Overall Score** | 8.3/10 | Production-quality code with minor gaps | | **Điểm tổng thể** | 8.3/10 | Mã nguồn chất lượng production với một vài lỗ hổng nhỏ |
| **Architecture** | 9/10 | Excellent DDD + CQRS implementation | | **Kiến trúc** | 9/10 | Triển khai DDD + CQRS xuất sắc |
| **Testing** | 8/10 | 307+ test files, 28% coverage | | **Testing** | 8/10 | 307+ file test, độ phủ 28% |
| **Security** | 8.5/10 | JWT/MFA, no exposed secrets, audit logs | | **Bảo mật** | 8.5/10 | JWT/MFA, không lộ secret, có audit log |
| **DevOps** | 9/10 | 8 automated GitHub Actions workflows | | **DevOps** | 9/10 | 8 workflow GitHub Actions tự động |
| **Documentation** | 7/10 | Comprehensive but some gaps | | **Tài liệu** | 7/10 | Đầy đủ nhưng còn vài thiếu sót |
--- ---
## CODEBASE SNAPSHOT ## TỔNG QUAN MÃ NGUỒN
**Size:** 815 (API TS) + 241 (Web TS) + 21 (Python AI) files **Kích thước:** 815 (API TS) + 241 (Web TS) + 21 (Python AI) file
**Modules:** 16 API modules (13 fully DDD-compliant) **Modules:** 16 module API (13 tuân thủ DDD đầy đủ)
**Database:** 22 models + 18 enums + 60+ indexes **Database:** 22 model + 18 enum + 60+ index
**Routes:** 31+ frontend routes **Routes:** 31+ route frontend
**Components:** 87 organized React components **Components:** 87 component React được tổ chức gọn gàng
**Tests:** 307+ test files **Tests:** 307+ file test
**Commits:** 207 **Commits:** 207
**Docs:** 60+ files **Docs:** 60+ file
--- ---
## WHAT'S GREAT ✅ ## ĐIỂM MẠNH ✅
1. **DDD Architecture** — 13/16 modules fully layered (domain → app → infra → presentation) 1. **Kiến trúc DDD** — 13/16 module phân lớp đầy đủ (domain → app → infra → presentation)
2. **Type Safety** — Strict TypeScript throughout, no `any` escapes 2. **An toàn kiểu** — TypeScript strict mode toàn bộ, không có `any` lọt qua
3. **Testing** — Unit, integration, and E2E tests across the stack 3. **Testing** — Có unit, integration, và E2E test trên toàn stack
4. **Security** — TOTP MFA, OAuth2, no hardcoded secrets, audit trail 4. **Bảo mật** — TOTP MFA, OAuth2, không hardcode secret, có audit trail
5. **DevOps** — CI/CD pipeline fully automated (lint → test → build → deploy) 5. **DevOps** — Pipeline CI/CD tự động hoàn toàn (lint → test → build → deploy)
6. **Database** — Well-indexed, cascade rules defined, PostGIS support 6. **Database** — Đánh index tốt, định nghĩa cascade rule, hỗ trợ PostGIS
7. **Scalability** — Turbo builds, Redis caching, horizontal scaling ready 7. **Khả năng mở rộng** — Turbo build, Redis cache, sẵn sàng scale ngang
8. **Git Hygiene** — Linting hooks, conventional commits, 207 commits 8. **Git Hygiene** — Linting hooks, conventional commit, 207 commit
--- ---
## WHAT NEEDS WORK ⚠️ ## NHỮNG ĐIỂM CẦN CẢI THIỆN ⚠️
1. **Load Testing Thresholds** — K6 tests exist but SLAs not fully documented 1. **Ngưỡng load test** — Có K6 test nhưng SLA chưa được tài liệu hoá đầy đủ
2. **Payment Error Cases** — Mock providers need more edge-case failure tests 2. **Trường hợp lỗi thanh toán** — Provider mock cần thêm test edge case
3. **Agents Module** — Infrastructure layer light (2 files vs. 12+ in other modules) 3. **Module Agents** — Lớp infrastructure mỏng (2 file so với 12+ ở các module khác)
4. **Disaster Recovery** — Playbooks missing, though backup verification works 4. **Disaster Recovery** — Thiếu playbook, dù xác minh backup vẫn hoạt động
5. **Search Edge Cases** — Complex filters need fuzz testing coverage 5. **Search Edge Cases** — Bộ lọc phức tạp cần thêm fuzz test
--- ---
## KEY MODULES (16 TOTAL) ## CÁC MODULE CHÍNH (TỔNG 16)
**Most Complex (Testing-heavy):** **Phức tạp nhất (nặng test):**
- `auth` (124 files) — JWT, TOTP MFA, OAuth, CSRF, rate limiting - `auth` (124 file) — JWT, TOTP MFA, OAuth, CSRF, rate limiting
- `listings` (81 files) — Core marketplace CRUD + featured listings - `listings` (81 file) — CRUD marketplace cốt lõi + featured listings
- `payments` (49 files) — VNPay, MoMo, ZaloPay integration - `payments` (49 file) — Tích hợp VNPay, MoMo, ZaloPay
**Solid Implementation:** **Triển khai vững chắc:**
- `search`, `admin`, `analytics`, `subscriptions`, `notifications`, `inquiries`, `leads`, `reviews` - `search`, `admin`, `analytics`, `subscriptions`, `notifications`, `inquiries`, `leads`, `reviews`
**Infrastructure-only (by design):** **Chỉ có infrastructure (theo thiết kế):**
- `health` (4 files) — k8s health checks - `health` (4 file) — Health check k8s
- `metrics` (8 files) — Prometheus metrics - `metrics` (8 file) — Prometheus metrics
- `mcp` (12 files) — Model Context Protocol server - `mcp` (12 file) — Model Context Protocol server
--- ---
## DATABASE (22 MODELS) ## DATABASE (22 MODEL)
| Group | Models | Highlights | | Nhóm | Models | Điểm nổi bật |
|-------|--------|-----------| |-------|--------|-----------|
| **Auth** | User, Agent, MfaChallenge, RefreshToken, OAuthAccount | TOTP, OAuth, token rotation | | **Auth** | User, Agent, MfaChallenge, RefreshToken, OAuthAccount | TOTP, OAuth, xoay vòng token |
| **Marketplace** | Property, Listing, PropertyMedia, SavedSearch, Valuation | Geo-indexed, AI valuation | | **Marketplace** | Property, Listing, PropertyMedia, SavedSearch, Valuation | Index địa lý, định giá AI |
| **Commerce** | Transaction, Inquiry, Lead, Payment, Subscription | 6+ status enums, audit trail | | **Commerce** | Transaction, Inquiry, Lead, Payment, Subscription | 6+ enum trạng thái, audit trail |
| **Admin** | Plan, UsageRecord, NotificationLog, AdminAuditLog, Review, MarketIndex | GDPR-ready, quota tracking | | **Admin** | Plan, UsageRecord, NotificationLog, AdminAuditLog, Review, MarketIndex | Sẵn sàng GDPR, theo dõi quota |
**Indexes:** 60+ (including compound indexes for common queries) **Indexes:** 60+ (gồm cả compound index cho các truy vấn phổ biến)
**PostGIS:** Enabled for geospatial searches **PostGIS:** Đã bật cho tìm kiếm theo vị trí địa lý
**Cascade Rules:** Properly defined (Cascade, SetNull, Restrict) **Cascade Rules:** Định nghĩa đúng (Cascade, SetNull, Restrict)
--- ---
## FRONTEND (31+ ROUTES, 87 COMPONENTS) ## FRONTEND (31+ ROUTE, 87 COMPONENT)
**Public:** **Public:**
- Homepage, search, listing detail, agent profiles, pricing, comparison - Trang chủ, tìm kiếm, chi tiết tin đăng, hồ sơ môi giới, bảng giá, so sánh
**Dashboard (Auth):** **Dashboard (Auth):**
- Manage listings, inquiries, leads, analytics, KYC, subscription, valuation - Quản lý tin đăng, inquiry, lead, analytics, KYC, subscription, định giá
**Admin:** **Admin:**
- Moderation queue, KYC verification, user management - Hàng đợi kiểm duyệt, xác minh KYC, quản lý người dùng
**Components:** **Components:**
- 22 UI kit (Shadcn/Radix) + 12 listing + 6 search + 8 valuation + 8 comparison + more - 22 UI kit (Shadcn/Radix) + 12 listing + 6 search + 8 valuation + 8 comparison + nhiều hơn
--- ---
## TESTING COVERAGE ## ĐỘ PHỦ TEST
| Type | Count | Status | | Loại | Số lượng | Trạng thái |
|------|-------|--------| |------|-------|--------|
| **API Unit Tests** | 233 files | ✅ Active | | **API Unit Tests** | 233 file | ✅ Đang dùng |
| **Frontend Unit Tests** | 66 files | ✅ Active | | **Frontend Unit Tests** | 66 file | ✅ Đang dùng |
| **E2E Tests (Playwright)** | 40+ cases | ✅ Active | | **E2E Tests (Playwright)** | 40+ case | ✅ Đang dùng |
| **Coverage Ratio** | 28% (API/Web) | ✅ Good | | **Tỉ lệ coverage** | 28% (API/Web) | ✅ Tốt |
| **Test DB** | PostgreSQL 16 + PostGIS | ✅ CI-integrated | | **Test DB** | PostgreSQL 16 + PostGIS | ✅ Tích hợp CI |
--- ---
## CI/CD PIPELINE (8 WORKFLOWS) ## CI/CD PIPELINE (8 WORKFLOW)
``` ```
Push → Lint (2m) → Typecheck (2m) → Test (4m) → Build (3m) → E2E (8m) Push → Lint (2m) → Typecheck (2m) → Test (4m) → Build (3m) → E2E (8m)
@@ -121,71 +121,71 @@ Push → Lint (2m) → Typecheck (2m) → Test (4m) → Build (3m) → E2E (8m)
``` ```
**Workflows:** **Workflows:**
1. `ci.yml` — Lint → Typecheck → Test → Build (~30 min) 1. `ci.yml` — Lint → Typecheck → Test → Build (~30 phút)
2. `deploy.yml` — Build images → DB migrations → Rollback strategy 2. `deploy.yml` — Build image → DB migration → Chiến lược rollback
3. `e2e.yml` — Playwright tests (API + Web) 3. `e2e.yml` — Playwright test (API + Web)
4. `security.yml` — CodeQL + dependency audit 4. `security.yml` — CodeQL + dependency audit
5. `load-test.yml` — Weekly K6 performance tests 5. `load-test.yml` — K6 performance test hàng tuần
6. `backup-verify.yml` — Daily backup integrity checks 6. `backup-verify.yml` — Kiểm tra tính toàn vẹn backup hàng ngày
7. `codeql.yml` — Code scanning 7. `codeql.yml` — Quét mã nguồn
8. `Dependabot` — Dependency updates 8. `Dependabot` — Cập nhật dependency
--- ---
## SECURITY SCORECARD ## BẢNG ĐIỂM BẢO MẬT
| Category | Grade | Notes | | Hạng mục | Điểm | Ghi chú |
|----------|-------|-------| |----------|-------|-------|
| **Secrets** | A+ | No exposed keys, .env properly gitignored | | **Secrets** | A+ | Không lộ key, .env đã gitignore đúng |
| **Auth** | A+ | JWT, TOTP MFA, OAuth2, CSRF, rate limiting | | **Auth** | A+ | JWT, TOTP MFA, OAuth2, CSRF, rate limiting |
| **Encryption** | B+ | Bcrypt passwords, PII hashing, no DB encryption at rest | | **Mã hoá** | B+ | Mật khẩu Bcrypt, hash PII, chưa mã hoá DB at rest |
| **Audit Trail** | A+ | AdminAuditLog, NotificationLog, IP/user-agent tracking | | **Audit Trail** | A+ | AdminAuditLog, NotificationLog, theo dõi IP/user-agent |
| **Dependencies** | B+ | pnpm overrides for CVEs, lock file locked | | **Dependencies** | B+ | pnpm overrides cho CVE, lock file đã khoá |
| **Infrastructure** | B+ | Multi-stage Docker, k8s-ready, TLS-ready | | **Infrastructure** | B+ | Docker multi-stage, sẵn sàng k8s, sẵn sàng TLS |
| **OVERALL** | **A-** | 8.5/10 — Production-grade | | **TỔNG THỂ** | **A-** | 8.5/10 — Cấp độ production |
**No Critical Issues Found** ✅ **Không phát hiện vấn đề nghiêm trọng** ✅
--- ---
## DEPLOYMENT READINESS ## MỨC ĐỘ SẴN SÀNG TRIỂN KHAI
| Item | Status | Details | | Mục | Trạng thái | Chi tiết |
|------|--------|---------| |------|--------|---------|
| Docker | ✅ Ready | Multi-stage builds, production-optimized | | Docker | ✅ Sẵn sàng | Build multi-stage, tối ưu cho production |
| Database | ✅ Ready | 15 migrations, seed script, backup verification | | Database | ✅ Sẵn sàng | 15 migration, seed script, xác minh backup |
| Secrets | ✅ Ready | GitHub Actions secrets, no hardcoded values | | Secrets | ✅ Sẵn sàng | GitHub Actions secrets, không hardcode giá trị |
| Monitoring | ✅ Ready | Prometheus, Grafana, Loki, Sentry | | Monitoring | ✅ Sẵn sàng | Prometheus, Grafana, Loki, Sentry |
| Health Checks | ✅ Ready | /health endpoint, k8s probes | | Health Checks | ✅ Sẵn sàng | Endpoint /health, k8s probe |
| Rollback | ✅ Ready | Blue-green strategy, automated | | Rollback | ✅ Sẵn sàng | Chiến lược blue-green, tự động |
| Documentation | ✅ Ready | Deployment guides, runbooks | | Tài liệu | ✅ Sẵn sàng | Hướng dẫn deploy, runbook |
| **SCORE** | **9.5/10** | **READY FOR PRODUCTION** | | **ĐIỂM** | **9.5/10** | **SẴN SÀNG CHO PRODUCTION** |
--- ---
## PRE-LAUNCH CHECKLIST ## CHECKLIST TRƯỚC KHI LAUNCH
**Critical (Must Do):** **Quan trọng (Bắt buộc):**
- [ ] Set production environment variables - [ ] Đặt biến môi trường production
- [ ] Configure PostgreSQL backup - [ ] Cấu hình backup PostgreSQL
- [ ] Enable HTTPS/TLS - [ ] Bật HTTPS/TLS
- [ ] Set up monitoring (Prometheus/Grafana) - [ ] Thiết lập monitoring (Prometheus/Grafana)
- [ ] Configure error tracking (Sentry) - [ ] Cấu hình theo dõi lỗi (Sentry)
**Important (Should Do):** **Quan trọng (Nên làm):**
- [ ] Load test with production data - [ ] Load test với dữ liệu production
- [ ] Security audit (optional but recommended) - [ ] Audit bảo mật (tuỳ chọn nhưng khuyến nghị)
- [ ] UAT with stakeholders - [ ] UAT với stakeholder
- [ ] Document runbooks - [ ] Tài liệu hoá runbook
**Nice-to-Have:** **Nên có:**
- [ ] Set up CDN for media assets - [ ] Thiết lập CDN cho media
- [ ] Database read replicas - [ ] Database read replica
- [ ] Multi-region failover - [ ] Failover đa vùng
--- ---
## TECH STACK HIGHLIGHTS ## ĐIỂM NHẤN TECH STACK
**Backend:** NestJS 11 + Prisma 7 + PostgreSQL 16 + PostGIS 3.4 **Backend:** NestJS 11 + Prisma 7 + PostgreSQL 16 + PostGIS 3.4
**Frontend:** Next.js 15 + React 18 + Tailwind CSS + Zustand **Frontend:** Next.js 15 + React 18 + Tailwind CSS + Zustand
@@ -197,24 +197,24 @@ Push → Lint (2m) → Typecheck (2m) → Test (4m) → Build (3m) → E2E (8m)
--- ---
## WHAT TO FIX THIS WEEK (P0) ## CẦN FIX TRONG TUẦN NÀY (P0)
1. Document load testing SLAs and thresholds 1. Tài liệu hoá SLA và ngưỡng load testing
2. Add payment provider failure mock tests 2. Thêm test mock lỗi cho payment provider
3. Create database maintenance playbook 3. Tạo playbook bảo trì database
--- ---
## FINAL VERDICT ## KẾT LUẬN CUỐI CÙNG
✅ **APPROVED FOR PRODUCTION** ✅ **PHÊ DUYỆT CHO PRODUCTION**
This is enterprise-quality code with proper architecture, comprehensive testing, and production-grade security. Minor gaps are non-blocking and can be addressed post-launch. Đây là mã nguồn chất lượng doanh nghiệp với kiến trúc đúng chuẩn, test toàn diện và bảo mật cấp production. Các lỗ hổng nhỏ không cản trở việc launch và có thể giải quyết sau.
**Confidence Level:** 95% **Mức độ tin cậy:** 95%
**Risk Level:** LOW **Mức độ rủi ro:** THẤP
**Go/No-Go:** 🟢 **GO** **Go/No-Go:** 🟢 **GO**
--- ---
**Report:** April 12, 2026 | **Auditor:** Claude Code | **Time:** Comprehensive (Very Thorough) **Báo cáo:** 12 tháng 4, 2026 | **Auditor:** Claude Code | **Thời lượng:** Toàn diện (Rất kỹ lưỡng)

343
docs/audits/AUDIT_README.md
View File

@@ -1,52 +1,52 @@
# GoodGo Platform AI - Audit Reports & Analysis # GoodGo Platform AI - Báo cáo Audit & Phân tích
**Complete Code Audit - April 11, 2026** **Audit mã nguồn toàn diện - 11 tháng 4, 2026**
This directory contains three comprehensive audit documents analyzing the GoodGo Platform AI codebase: Thư mục này chứa ba tài liệu audit toàn diện phân tích mã nguồn GoodGo Platform AI:
--- ---
## 📋 AUDIT DOCUMENTS ## 📋 CÁC TÀI LIỆU AUDIT
### 1. **AUDIT_EXECUTIVE_SUMMARY.md** ⭐ START HERE ### 1. **AUDIT_EXECUTIVE_SUMMARY.md** ⭐ BẮT ĐẦU TẠI ĐÂY
**Target Audience:** CEO, CTO, Product Managers, Investors **Đối tượng:** CEO, CTO, Product Manager, Nhà đầu tư
**Length:** ~8 pages (quick read) **Độ dài:** ~8 trang (đọc nhanh)
**Time to Read:** 15-20 minutes **Thời gian đọc:** 15-20 phút
**Contains:** **Nội dung:**
- Project snapshot (metrics, grades) - Tóm tắt dự án (số liệu, xếp hạng)
- Architecture quality assessment (A-grade) - Đánh giá chất lượng kiến trúc (xếp hạng A)
- Security posture (A-) - Tư thế bảo mật (A-)
- Code quality (A) - Chất lượng mã (A)
- Testing coverage (B+) - Độ phủ test (B+)
- Deployment readiness (B with conditions) - Mức độ sẵn sàng deploy (B kèm điều kiện)
- Risk matrix & Go/No-Go decision - Ma trận rủi ro & quyết định Go/No-Go
- Prioritized recommendations - Khuyến nghị theo ưu tiên
**Key Takeaway:** **Điểm mấu chốt:**
> **Production-Ready with standard pre-launch validation. Focus on operational readiness (monitoring, runbooks) rather than code quality.** > **Sẵn sàng Production với validation tiền-launch chuẩn. Tập trung vào sẵn sàng vận hành (monitoring, runbook) hơn là chất lượng mã.**
--- ---
### 2. **COMPREHENSIVE_AUDIT_REPORT_2026-04-11.md** 📊 DETAILED REFERENCE ### 2. **COMPREHENSIVE_AUDIT_REPORT_2026-04-11.md** 📊 THAM CHIẾU CHI TIẾT
**Target Audience:** Tech leads, Senior developers, Architects **Đối tượng:** Tech lead, Senior developer, Architect
**Length:** ~50 pages (comprehensive) **Độ dài:** ~50 trang (toàn diện)
**Time to Read:** 1-2 hours (full), 30 min (key sections) **Thời gian đọc:** 1-2 giờ (đầy đủ), 30 phút (các phần chính)
**Contains:** **Nội dung:**
- Complete project structure breakdown - Phân tích cấu trúc dự án đầy đủ
- 16 backend modules detailed analysis - Phân tích chi tiết 16 backend module
- Frontend architecture & routes - Kiến trúc & route frontend
- Database schema (21 models, 13 migrations) - Schema database (21 model, 13 migration)
- Docker & infrastructure setup - Thiết lập Docker & hạ tầng
- CI/CD pipelines explanation - Giải thích các pipeline CI/CD
- Code quality standards - Tiêu chuẩn chất lượng mã
- Testing framework details - Chi tiết framework testing
- Dependencies catalog - Danh mục dependencies
- Security implementation details - Chi tiết triển khai bảo mật
- Performance & scalability - Performance & khả năng mở rộng
- Compliance & governance - Tuân thủ & quản trị
**Structure:** **Cấu trúc:**
``` ```
1. Project Structure (2 pages) 1. Project Structure (2 pages)
2. Backend Deep Dive (8 pages) 2. Backend Deep Dive (8 pages)
@@ -66,122 +66,122 @@ This directory contains three comprehensive audit documents analyzing the GoodGo
--- ---
### 3. **AUDIT_TECHNICAL_REFERENCE.md** 🔧 DEVELOPER GUIDE ### 3. **AUDIT_TECHNICAL_REFERENCE.md** 🔧 HƯỚNG DẪN DEVELOPER
**Target Audience:** Developers implementing features, DevOps engineers **Đối tượng:** Developer triển khai tính năng, kỹ sư DevOps
**Length:** ~30 pages (practical) **Độ dài:** ~30 trang (thực tiễn)
**Time to Read:** 30-45 minutes (sections as needed) **Thời gian đọc:** 30-45 phút (các phần khi cần)
**Contains:** **Nội dung:**
- Backend module hierarchy & dependencies - Phân cấp module backend & dependency
- Domain model relationships - Quan hệ giữa các domain model
- Authentication flow (detailed) - Luồng xác thực (chi tiết)
- Database schema with indexing strategy - Schema database với chiến lược index
- Security layers (network → data level) - Các lớp bảo mật (network → data level)
- CQRS pattern implementation - Triển khai pattern CQRS
- Caching strategy (multi-level) - Chiến lược cache (đa cấp)
- Error handling & observability - Xử lý lỗi & observability
- Background jobs & events - Background job & event
- Frontend state management - Quản lý state frontend
- Deployment architecture - Kiến trúc deploy
- CI/CD pipeline stages - Các giai đoạn pipeline CI/CD
- Performance tuning checklist - Checklist tinh chỉnh hiệu năng
- Troubleshooting guide - Hướng dẫn troubleshoot
- Security pre-deployment checklist - Checklist bảo mật trước deploy
**Usage:** Keep this as reference while developing or debugging **Cách dùng:** Giữ làm tài liệu tham chiếu khi phát triển hoặc debug
--- ---
## 📊 KEY METRICS AT A GLANCE ## 📊 SỐ LIỆU CHÍNH TRONG NHÁY MẮT
| Metric | Value | Grade | | Chỉ số | Giá trị | Xếp hạng |
|--------|-------|-------| |--------|-------|-------|
| Codebase Size | 70,569 LOC | — | | Kích thước mã nguồn | 70.569 LOC | — |
| TypeScript Files | 992 | A | | File TypeScript | 992 | A |
| Backend Modules | 16 (all properly layered) | A | | Module Backend | 16 (đều phân lớp đúng) | A |
| Frontend Routes | 33 pages + 8 layouts | A | | Route Frontend | 33 trang + 8 layout | A |
| Database Models | 21 | B+ | | Model Database | 21 | B+ |
| Test Files | 289 | B+ | | File Test | 289 | B+ |
| Architecture Pattern | Hexagonal DDD | A | | Pattern kiến trúc | Hexagonal DDD | A |
| Code Quality | Strict TS, 0 TODOs, ESLint | A | | Chất lượng mã | TS strict, 0 TODO, ESLint | A |
| Security | Enterprise-grade | A- | | Bảo mật | Cấp doanh nghiệp | A- |
| Testing | Unit + E2E coverage | B+ | | Testing | Phủ Unit + E2E | B+ |
| DevOps Readiness | Full CI/CD pipeline | B | | Sẵn sàng DevOps | Pipeline CI/CD đầy đủ | B |
--- ---
## 🎯 QUICK FINDINGS ## 🎯 PHÁT HIỆN NHANH
### ✅ WHAT'S WORKING WELL ### ✅ NHỮNG ĐIỀU HOẠT ĐỘNG TỐT
1. **Architecture** - Hexagonal pattern properly applied across all 16 modules 1. **Kiến trúc** - Pattern Hexagonal được áp dụng đúng cho cả 16 module
2. **Security** - Multiple layers (Helmet, CSRF, encryption, audit logs) 2. **Bảo mật** - Nhiều lớp (Helmet, CSRF, mã hoá, audit log)
3. **Code Quality** - Strict TypeScript, ESLint enforced, zero technical debt markers 3. **Chất lượng mã** - TypeScript strict, ESLint được enforce, không có dấu nợ kỹ thuật
4. **Testing** - 289 test files covering happy paths 4. **Testing** - 289 file test phủ happy path
5. **DevOps** - Full CI/CD automation with security scanning 5. **DevOps** - Tự động hoá CI/CD đầy đủ với security scan
6. **Type Safety** - ~100% TypeScript strict mode compliance 6. **An toàn kiểu** - ~100% tuân thủ TypeScript strict mode
### ⚠️ AREAS TO WATCH ### ⚠️ KHU VỰC CẦN CHÚ Ý
1. **Database** - 13 migrations in 4 days (schema still stabilizing) 1. **Database** - 13 migration trong 4 ngày (schema còn đang ổn định)
2. **Testing** - 70K LOC with ~0.4% test file ratio (adequate but improvable) 2. **Testing** - 70K LOC với tỉ lệ ~0.4% file test (đủ nhưng có thể cải thiện)
3. **Documentation** - README minimal, operational docs missing 3. **Tài liệu** - README tối thiểu, thiếu tài liệu vận hành
4. **Monitoring** - Stack deployed but alert rules need configuration 4. **Monitoring** - Đã deploy stack nhưng cần cấu hình alert rule
5. **Admin Security** - No 2FA implemented 5. **Bảo mật Admin** - Chưa có 2FA
### 🚀 READY FOR PRODUCTION? ### 🚀 SẴN SÀNG CHO PRODUCTION?
**Status:** **YES, with conditions** **Trạng thái:** **CÓ, kèm điều kiện**
- ✅ Code quality excellent - ✅ Chất lượng mã xuất sắc
- ✅ Security controls in place - ✅ Đã có các kiểm soát bảo mật
- ⚠️ Need: Load testing, schema lockdown, pentest - ⚠️ Cần: Load test, khoá schema, pentest
- ⚠️ Need: Runbooks, alert thresholds, incident procedures - ⚠️ Cần: Runbook, ngưỡng alert, quy trình ứng phó sự cố
--- ---
## 📑 HOW TO USE THESE DOCUMENTS ## 📑 CÁCH SỬ DỤNG CÁC TÀI LIỆU NÀY
### For Non-Technical Leadership ### Dành cho Lãnh đạo phi kỹ thuật
1. Read: **AUDIT_EXECUTIVE_SUMMARY.md** (section "GO/NO-GO DECISION") 1. Đọc: **AUDIT_EXECUTIVE_SUMMARY.md** (phần "GO/NO-GO DECISION")
2. Focus: Architecture grade, security posture, deployment readiness 2. Tập trung: Xếp hạng kiến trúc, tư thế bảo mật, mức độ sẵn sàng deploy
3. Time: 10 minutes 3. Thời gian: 10 phút
### For Technical Decision Makers (CTO, Tech Leads) ### Dành cho Người ra quyết định kỹ thuật (CTO, Tech Lead)
1. Read: **AUDIT_EXECUTIVE_SUMMARY.md** (entire) 1. Đọc: toàn bộ **AUDIT_EXECUTIVE_SUMMARY.md**
2. Reference: **COMPREHENSIVE_AUDIT_REPORT_2026-04-11.md** (sections 2-5) 2. Tham khảo: **COMPREHENSIVE_AUDIT_REPORT_2026-04-11.md** (phần 2-5)
3. Time: 1 hour 3. Thời gian: 1 giờ
### For Implementing Developers ### Dành cho Developer triển khai
1. Bookmark: **AUDIT_TECHNICAL_REFERENCE.md** 1. Đánh dấu: **AUDIT_TECHNICAL_REFERENCE.md**
2. Read: **COMPREHENSIVE_AUDIT_REPORT_2026-04-11.md** (section 2-3) 2. Đọc: **COMPREHENSIVE_AUDIT_REPORT_2026-04-11.md** (phần 2-3)
3. Use as: Daily reference for patterns & architecture 3. Sử dụng làm: Tham chiếu hàng ngày cho pattern & kiến trúc
### For DevOps/SRE ### Dành cho DevOps/SRE
1. Focus: **COMPREHENSIVE_AUDIT_REPORT_2026-04-11.md** (section 5) 1. Tập trung: **COMPREHENSIVE_AUDIT_REPORT_2026-04-11.md** (phần 5)
2. Reference: **AUDIT_TECHNICAL_REFERENCE.md** (deployment architecture, troubleshooting) 2. Tham khảo: **AUDIT_TECHNICAL_REFERENCE.md** (kiến trúc deploy, troubleshoot)
3. Checklist: Security pre-deployment checklist in Technical Reference 3. Checklist: Checklist bảo mật trước deploy trong Technical Reference
--- ---
## 🔐 SECURITY HIGHLIGHTS ## 🔐 ĐIỂM NHẤN BẢO MẬT
**Implemented Controls:** **Các kiểm soát đã triển khai:**
- ✓ Helmet security headers (CSP, HSTS, X-Frame-Options) - ✓ Helmet security header (CSP, HSTS, X-Frame-Options)
- ✓ CSRF protection (double-submit cookie pattern) - ✓ CSRF protection (pattern double-submit cookie)
- ✓ Rate limiting (global 60 req/min, auth 10 req/min) - ✓ Rate limiting (global 60 req/phút, auth 10 req/phút)
- ✓ Input sanitization (XSS prevention) - ✓ Sanitize đầu vào (chống XSS)
- ✓ PII encryption (field-level AES-256-GCM) - ✓ Mã hoá PII (field-level AES-256-GCM)
- ✓ Hash fields (email/phone searchable yet hashed) - ✓ Trường hash (email/phone vẫn search được nhưng đã hash)
- ✓ Audit logging (AdminAuditLog model) - ✓ Audit logging (model AdminAuditLog)
- ✓ JWT token rotation (refresh token families) - ✓ Xoay vòng JWT token (refresh token family)
- ✓ bcrypt password hashing (6 rounds) - ✓ Hash mật khẩu bcrypt (6 rounds)
- ✓ GDPR soft deletes (User.deletedAt) - ✓ GDPR soft delete (User.deletedAt)
**Missing (Nice-to-Have):** **Còn thiếu (Nên có):**
- 2FA for admin accounts - 2FA cho tài khoản admin
- Penetration test report - Báo cáo penetration test
- Incident response runbooks - Runbook ứng phó sự cố
--- ---
## 📈 ARCHITECTURE RATING BREAKDOWN ## 📈 PHÂN TÍCH XẾP HẠNG KIẾN TRÚC
``` ```
Code Architecture ████████████████████ A Code Architecture ████████████████████ A
@@ -195,73 +195,72 @@ Operational Readiness ████████░░░░░░░░░░░
--- ---
## 🎬 NEXT STEPS ## 🎬 CÁC BƯỚC TIẾP THEO
### Immediate (This Week) ### Ngay lập tức (Tuần này)
- [ ] Review Executive Summary with leadership - [ ] Rà soát Executive Summary với lãnh đạo
- [ ] Lock database schema (freeze migrations) - [ ] Khoá schema database (đóng băng migration)
- [ ] Schedule security penetration test - [ ] Lên lịch penetration test bảo mật
- [ ] Configure monitoring alert thresholds - [ ] Cấu hình ngưỡng alert monitoring
### Short-Term (Week 2-3) ### Ngắn hạn (Tuần 2-3)
- [ ] Run comprehensive load testing (1M+ req/day simulation) - [ ] Chạy load testing toàn diện (mô phỏng 1M+ req/ngày)
- [ ] Create incident response runbooks - [ ] Tạo runbook ứng phó sự cố
- [ ] Implement admin 2FA - [ ] Triển khai 2FA cho admin
- [ ] Expand E2E test coverage - [ ] Mở rộng độ phủ E2E test
### Medium-Term (Month 2) ### Trung hạn (Tháng 2)
- [ ] Add mutation testing to CI/CD - [ ] Thêm mutation testing vào CI/CD
- [ ] Implement GDPR data export feature - [ ] Triển khai tính năng GDPR data export
- [ ] Document scaling architecture - [ ] Tài liệu hoá kiến trúc scale
- [ ] Performance optimization pass - [ ] Đợt tối ưu hoá performance
--- ---
## 📞 QUESTIONS? ## 📞 CÂU HỎI?
**About the audit process:** **Về quy trình audit:**
- See "CODEBASE_ANALYSIS.md" for discovery notes - Xem "CODEBASE_ANALYSIS.md" để xem ghi chú khám phá
- See "CHANGELOG.md" for recent git commits - Xem "CHANGELOG.md" để xem các commit gần đây
- See "CLAUDE.md" for AI integration guidelines - Xem "CLAUDE.md" để xem hướng dẫn tích hợp AI
**About specific modules:** **Về module cụ thể:**
- Backend: Check apps/api/src/modules/[module-name]/ - Backend: Xem apps/api/src/modules/[module-name]/
- Frontend: Check apps/web/app/[locale]/ - Frontend: Xem apps/web/app/[locale]/
**About deployment:** **Về deployment:**
- Docker: See docker-compose.yml files - Docker: Xem các file docker-compose.yml
- CI/CD: See .github/workflows/ files - CI/CD: Xem các file .github/workflows/
- Kubernetes: See deployment architecture in Technical Reference - Kubernetes: Xem kiến trúc deploy trong Technical Reference
--- ---
## 📄 DOCUMENT VERSIONS ## 📄 PHIÊN BẢN TÀI LIỆU
| Document | Version | Last Updated | Pages | | Tài liệu | Phiên bản | Cập nhật cuối | Trang |
|----------|---------|--------------|-------| |----------|---------|--------------|-------|
| Executive Summary | 1.0 | Apr 11, 2026 | 8 | | Executive Summary | 1.0 | 11/4/2026 | 8 |
| Comprehensive Report | 1.0 | Apr 11, 2026 | 50 | | Comprehensive Report | 1.0 | 11/4/2026 | 50 |
| Technical Reference | 1.0 | Apr 11, 2026 | 30 | | Technical Reference | 1.0 | 11/4/2026 | 30 |
--- ---
## ✨ CONCLUSION ## ✨ KẾT LUẬN
The GoodGo Platform AI demonstrates **mature software engineering practices**: GoodGo Platform AI thể hiện **các thực hành kỹ thuật phần mềm trưởng thành**:
- Clean, maintainable architecture - Kiến trúc sạch, dễ bảo trì
- Enterprise-grade security controls - Kiểm soát bảo mật cấp doanh nghiệp
- Comprehensive automated testing - Test tự động toàn diện
- Modern technology stack - Tech stack hiện đại
- Production-ready DevOps pipeline - Pipeline DevOps sẵn sàng production
**Recommendation:** **APPROVED FOR PRODUCTION** with standard pre-launch security & performance validation. **Khuyến nghị:** **PHÊ DUYỆT CHO PRODUCTION** với validation bảo mật & hiệu năng tiền-launch tiêu chuẩn.
The team is well-equipped to maintain, scale, and extend this platform. Đội ngũ đã sẵn sàng để bảo trì, mở rộng và phát triển nền tảng này.
--- ---
**Audit Conducted By:** Claude Code **Audit thực hiện bởi:** Claude Code
**Audit Date:** April 11, 2026 **Ngày Audit:** 11 tháng 4, 2026
**Codebase Location:** `/Users/velikho/Desktop/WORKING/goodgo-platform-ai/` **Vị trí mã nguồn:** `/Users/velikho/Desktop/WORKING/goodgo-platform-ai/`
**Confidence Level:** High (full codebase reviewed) **Mức độ tin cậy:** Cao (đã rà soát toàn bộ mã nguồn)

679
docs/audits/PRICING_CHECKOUT_AUDIT.md
View File

File diff suppressed because it is too large Load Diff

336
docs/audits/WEB_AUDIT_SUMMARY.md
View File

@@ -1,6 +1,6 @@
# GoodGo Platform Web - Audit Summary # GoodGo Platform Web - Tóm tắt Audit
## 📊 Overall Grade: A+ (Production-Ready) ## 📊 Xếp hạng tổng thể: A+ (Sẵn sàng Production)
``` ```
┌─────────────────────────────────────────┐ ┌─────────────────────────────────────────┐
@@ -18,45 +18,45 @@
--- ---
## ✅ QUICK AUDIT RESULTS ## ✅ KẾT QUẢ AUDIT NHANH
| Category | Result | Score | | Hạng mục | Kết quả | Điểm |
|----------|--------|-------| |----------|--------|-------|
| **Pages Implemented** | 24/24 ✅ | 100% | | **Trang đã triển khai** | 24/24 ✅ | 100% |
| **Components** | 45+ fully typed | 100% | | **Components** | 45+ đánh kiểu đầy đủ | 100% |
| **Technical Debt** | 0 items | 100% | | **Nợ kỹ thuật** | 0 mục | 100% |
| **Test Coverage** | 25 test suites | 75% | | **Độ phủ test** | 25 test suite | 75% |
| **Type Safety** | Full TypeScript | 100% | | **An toàn kiểu** | TypeScript đầy đủ | 100% |
| **Security Headers** | 8 headers set | 90% | | **Header bảo mật** | 8 header được set | 90% |
| **Accessibility** | WCAG compliant | 80% | | **Khả năng truy cập** | Tuân thủ WCAG | 80% |
| **Mobile Responsive** | All breakpoints | 100% | | **Mobile Responsive** | Tất cả breakpoint | 100% |
--- ---
## 🎯 KEY FINDINGS ## 🎯 PHÁT HIỆN CHÍNH
### ✨ Strengths ### ✨ Điểm mạnh
- ✅ **Zero TODO/FIXME comments** - Codebase is production-clean - ✅ **Không còn TODO/FIXME** - Mã nguồn sạch sẽ ở mức production
- ✅ **24 fully implemented pages** - All blueprint features complete - ✅ **24 trang triển khai đầy đủ** - Hoàn tất tính năng theo blueprint
- ✅ **Multi-language support** - Vietnamese & English - ✅ **Hỗ trợ đa ngôn ngữ** - Tiếng Việt & tiếng Anh
- ✅ **OAuth integration** - Google & Zalo authentication - ✅ **Tích hợp OAuth** - Đăng nhập Google & Zalo
- ✅ **Modern tech stack** - Next.js 15, React 18, TypeScript 6 - ✅ **Tech stack hiện đại** - Next.js 15, React 18, TypeScript 6
- ✅ **API abstraction** - 10 specialized API clients - ✅ **Trừu tượng API** - 10 API client chuyên biệt
- ✅ **State management** - 2 Zustand stores with persistence - ✅ **Quản lý state** - 2 store Zustand có persistence
- ✅ **Comprehensive testing** - 25 test suites - ✅ **Test toàn diện** - 25 test suite
- ✅ **Error tracking** - Sentry integration - ✅ **Theo dõi lỗi** - Tích hợp Sentry
- ✅ **Security hardened** - CSP, CSRF, secure headers - ✅ **Bảo mật chắc chắn** - CSP, CSRF, secure header
### ⚠️ Minor Improvements ### ⚠️ Cải thiện nhỏ
1. **Image Optimization** - Use responsive images with sizes attribute 1. **Tối ưu hình ảnh** - Dùng responsive image với thuộc tính sizes
2. **CSP Strictness** - Enable strict CSP in production 2. **Tăng độ chặt CSP** - Bật CSP nghiêm ngặt cho production
3. **Date Handling** - Consider adding date-fns for consistency 3. **Xử lý ngày tháng** - Cân nhắc thêm date-fns để nhất quán
4. **API Retry Logic** - Add retry configuration for network errors 4. **API Retry Logic** - Thêm cấu hình retry cho lỗi mạng
5. **Logging Strategy** - Add structured logging for debugging 5. **Chiến lược logging** - Thêm structured logging cho debug
--- ---
## 📁 PROJECT STRUCTURE ## 📁 CẤU TRÚC DỰ ÁN
``` ```
156 TypeScript/TSX Files 156 TypeScript/TSX Files
@@ -76,9 +76,9 @@ TOTAL: ~12,000 lines of well-organized code
--- ---
## 🏗️ ARCHITECTURE ## 🏗️ KIẾN TRÚC
### Route Structure ### Cấu trúc Route
``` ```
Public Routes (5) Public Routes (5)
├── / (Landing) ├── / (Landing)
@@ -115,7 +115,7 @@ Admin (4)
└── /admin/moderation └── /admin/moderation
``` ```
### State Management Architecture ### Kiến trúc quản lý State
``` ```
Zustand Stores (2) Zustand Stores (2)
├── Auth Store ├── Auth Store
@@ -138,113 +138,113 @@ Context Providers (3)
--- ---
## 🔐 SECURITY OVERVIEW ## 🔐 TỔNG QUAN BẢO MẬT
**Headers Set:** 8 security headers **Header được set:** 8 header bảo mật
- ✅ X-Content-Type-Options: nosniff - ✅ X-Content-Type-Options: nosniff
- ✅ X-Frame-Options: DENY - ✅ X-Frame-Options: DENY
- ✅ X-XSS-Protection: 1; mode=block - ✅ X-XSS-Protection: 1; mode=block
- ✅ Referrer-Policy: strict-origin-when-cross-origin - ✅ Referrer-Policy: strict-origin-when-cross-origin
- ✅ Strict-Transport-Security: 1 year + preload - ✅ Strict-Transport-Security: 1 năm + preload
- ✅ Permissions-Policy: Camera/Mic disabled, Geo/Payment self-only - ✅ Permissions-Policy: Tắt Camera/Mic, Geo/Payment chỉ cho self
- ✅ Content-Security-Policy: Multi-directive policy - ✅ Content-Security-Policy: Policy đa directive
- ✅ API calls use credentials: 'include' + CSRF tokens - ✅ Các call API dùng credentials: 'include' + CSRF token
**Authentication:** **Xác thực:**
- ✅ Cookie-based sessions (goodgo_authenticated) - ✅ Cookie-based session (goodgo_authenticated)
- ✅ OAuth with Google & Zalo - ✅ OAuth với Google & Zalo
- ✅ Automatic token refresh on 401 - ✅ Tự động refresh token khi gặp 401
- ✅ Middleware route protection - ✅ Bảo vệ route bằng middleware
**Issues:** None critical. Minor CSP relaxation for development (can be tightened in production). **Vấn đề:** Không có vấn đề nghiêm trọng. Có thả lỏng CSP nhỏ cho dev (có thể siết chặt ở production).
--- ---
## 🎨 UI/UX QUALITY ## 🎨 CHẤT LƯỢNG UI/UX
### Accessibility (WCAG) ### Khả năng truy cập (WCAG)
- ✅ Semantic HTML structure - ✅ Cấu trúc HTML semantic
- ✅ ARIA labels on interactive elements - ✅ ARIA label trên các phần tử tương tác
- ✅ Focus management & keyboard navigation - ✅ Quản lý focus & điều hướng bàn phím
- ✅ Skip to main content link - ✅ Link skip to main content
- ✅ Proper heading hierarchy - ✅ Phân cấp heading đúng
- ✅ Color contrast compliance - ✅ Tuân thủ tương phản màu
### Responsive Design ### Responsive Design
- ✅ Mobile-first approach - ✅ Mobile-first approach
- ✅ All Tailwind breakpoints used (sm, md, lg, xl, 2xl) - ✅ Dùng đầy đủ breakpoint Tailwind (sm, md, lg, xl, 2xl)
- ✅ Tested on 320px - 2560px widths - ✅ Đã test trên 320px - 2560px
- ✅ Grid & Flexbox layouts - ✅ Layout Grid & Flexbox
- ✅ Aspect ratios for media - ✅ Aspect ratio cho media
### Dark Mode ### Dark Mode
- ✅ System preference detection - ✅ Phát hiện system preference
- ✅ Manual toggle - ✅ Toggle thủ công
- ✅ LocalStorage persistence - ✅ Lưu trong LocalStorage
- ✅ Smooth transitions - ✅ Chuyển đổi mượt mà
--- ---
## 📊 PERFORMANCE METRICS ## 📊 CHỈ SỐ HIỆU NĂNG
### Optimizations in Place ### Tối ưu đã có
- ✅ Dynamic imports for heavy components - ✅ Dynamic import cho component nặng
- ✅ Image optimization configuration - ✅ Cấu hình tối ưu hình ảnh
- ✅ Code splitting strategy - ✅ Chiến lược code splitting
- ✅ Web Vitals tracking (CLS, LCP, FID) - ✅ Theo dõi Web Vitals (CLS, LCP, FID)
- ✅ Sentry performance monitoring - ✅ Theo dõi performance Sentry
- ✅ React Query caching - ✅ Cache React Query
### Identified Improvements ### Cải thiện được xác định
1. Use responsive images with `sizes` attribute 1. Dùng responsive image với thuộc tính `sizes`
2. Implement retry logic in React Query 2. Triển khai retry logic trong React Query
3. Add structured logging for debugging 3. Thêm structured logging cho debug
4. Consider date-fns for date formatting 4. Cân nhắc date-fns cho định dạng ngày tháng
--- ---
## 🧪 TESTING COVERAGE ## 🧪 ĐỘ PHỦ TEST
**25 Test Suites Across:** **25 Test Suite trên:**
- 9 UI component tests (Button, Card, Input, etc.) - 9 test UI component (Button, Card, Input, v.v.)
- 7 Library tests (Stores, Validations, Utils) - 7 test thư viện (Stores, Validations, Utils)
- 9 Page tests (Landing, Search, Dashboard, Admin) - 9 test trang (Landing, Search, Dashboard, Admin)
**Testing Stack:** **Bộ công cụ Test:**
- Vitest 4.1.3 - Vitest 4.1.3
- Testing Library (React) - Testing Library (React)
- MSW (Mock Service Worker) - MSW (Mock Service Worker)
- jsdom (Virtual DOM) - jsdom (Virtual DOM)
**Coverage Areas:** **Khu vực được phủ:**
- ✅ Component rendering - ✅ Render component
- ✅ User interactions - ✅ Tương tác người dùng
- ✅ Store state management - ✅ Quản lý state store
- ✅ Form validation - ✅ Validation form
- ✅ API mocking - ✅ Mock API
--- ---
## 🚀 DEPLOYMENT READINESS ## 🚀 SẴN SÀNG TRIỂN KHAI
### Pre-Deployment Checklist ### Checklist trước deploy
- [ ] `npm run typecheck` - verify no TS errors - [ ] `npm run typecheck` - kiểm tra không có lỗi TS
- [ ] `npm run lint` - check code style - [ ] `npm run lint` - kiểm tra code style
- [ ] `npm test` - verify all tests pass - [ ] `npm test` - đảm bảo tất cả test pass
- [ ] `npm run build` - verify production build - [ ] `npm run build` - kiểm tra build production
- [ ] Set environment variables - [ ] Đặt biến môi trường
- [ ] Configure Sentry - [ ] Cấu hình Sentry
- [ ] Verify API endpoints - [ ] Xác minh các endpoint API
- [ ] Test OAuth providers - [ ] Test các provider OAuth
### Build Configuration ### Cấu hình Build
- ✅ Next.js standalone output - ✅ Next.js standalone output
- ✅ Sentry integration enabled - ✅ Đã bật tích hợp Sentry
- ✅ next-intl configured - ✅ Đã cấu hình next-intl
- ✅ Dockerfile provided - ✅ Đã cung cấp Dockerfile
- ✅ Security headers configured - ✅ Đã cấu hình security header
### Environment Variables ### Biến môi trường
```bash ```bash
NEXT_PUBLIC_API_URL= NEXT_PUBLIC_API_URL=
NEXT_PUBLIC_SITE_URL= NEXT_PUBLIC_SITE_URL=
@@ -259,43 +259,43 @@ NEXT_PUBLIC_ZALO_APP_ID=
## 📦 DEPENDENCIES ## 📦 DEPENDENCIES
### Production (17 packages) ### Production (17 package)
- Next.js 15.5.14 ✅ Latest - Next.js 15.5.14 ✅ Mới nhất
- React 18.3.0 ✅ Latest - React 18.3.0 ✅ Mới nhất
- TypeScript 6.0.2 ✅ Latest - TypeScript 6.0.2 ✅ Mới nhất
- Zustand 5.0.12 ✅ Latest - Zustand 5.0.12 ✅ Mới nhất
- React Query 5.96.2 ✅ Latest - React Query 5.96.2 ✅ Mới nhất
- Tailwind CSS 3.4.0 ✅ Latest - Tailwind CSS 3.4.0 ✅ Mới nhất
- Zod 4.3.6 ✅ Latest - Zod 4.3.6 ✅ Mới nhất
- Mapbox GL 3.21.0 ✅ Latest - Mapbox GL 3.21.0 ✅ Mới nhất
- Recharts 3.8.1 ✅ Latest - Recharts 3.8.1 ✅ Mới nhất
- Sentry 10.47.0 ✅ Latest - Sentry 10.47.0 ✅ Mới nhất
- next-intl 4.9.0 ✅ Latest - next-intl 4.9.0 ✅ Mới nhất
- React Hook Form 7.72.1 ✅ Latest - React Hook Form 7.72.1 ✅ Mới nhất
### No Security Vulnerabilities ### Không có lỗ hổng bảo mật
- ✅ All packages scanned and approved - ✅ Tất cả package đã được quét và phê duyệt
- ✅ Regular update maintenance - ✅ Bảo trì cập nhật định kỳ
- ✅ Sentry for runtime monitoring - ✅ Sentry để theo dõi runtime
--- ---
## 🌍 INTERNATIONALIZATION ## 🌍 ĐA NGÔN NGỮ
**Locales Supported:** **Locale được hỗ trợ:**
- 🇻🇳 Vietnamese (vi) - Default - 🇻🇳 Tiếng Việt (vi) - Mặc định
- 🇬🇧 English (en) - 🇬🇧 Tiếng Anh (en)
**Implementation:** **Triển khai:**
- next-intl v4.9.0 - next-intl v4.9.0
- Route-based locale handling - Xử lý locale theo route
- 10,154 bytes Vietnamese translations - 10.154 byte bản dịch tiếng Việt
- 8,698 bytes English translations - 8.698 byte bản dịch tiếng Anh
- Complete coverage of UI labels, errors, validation messages - Phủ đầy đủ nhãn UI, lỗi, thông báo validation
--- ---
## 📈 CODE METRICS SUMMARY ## 📈 TÓM TẮT CHỈ SỐ MÃ NGUỒN
``` ```
Code Organization ████████████ Excellent Code Organization ████████████ Excellent
@@ -310,55 +310,55 @@ Accessibility ██████████░░ Good
--- ---
## 🎓 RECOMMENDATIONS ## 🎓 KHUYẾN NGHỊ
### Immediate (Before Production) ### Ngay lập tức (Trước Production)
1. ✅ Verify OAuth provider credentials are configured 1. ✅ Xác minh credential OAuth provider đã được cấu hình
2. ✅ Set up Sentry account for error tracking 2. ✅ Thiết lập tài khoản Sentry để theo dõi lỗi
3. ✅ Configure API_URL environment variable 3. ✅ Cấu hình biến môi trường API_URL
4. ✅ Enable strict CSP headers for production 4. ✅ Bật CSP header nghiêm ngặt cho production
5. ✅ Test authentication flow end-to-end 5. ✅ Test luồng xác thực end-to-end
### Short Term (After Launch) ### Ngắn hạn (Sau khi launch)
1. Monitor Core Web Vitals using Sentry 1. Theo dõi Core Web Vitals qua Sentry
2. Gather user feedback on UI/UX 2. Thu thập phản hồi người dùng về UI/UX
3. Review error logs weekly 3. Rà soát log lỗi hàng tuần
4. Optimize images with responsive sizes 4. Tối ưu hình ảnh với responsive size
5. Consider implementing notifications 5. Cân nhắc triển khai notification
### Long Term (Future Enhancements) ### Dài hạn (Cải tiến tương lai)
1. Add structured logging (Pino/Winston) 1. Thêm structured logging (Pino/Winston)
2. Implement messaging system UI 2. Triển khai UI hệ thống tin nhắn
3. Create notifications center 3. Tạo trung tâm thông báo
4. Build mobile app (React Native) 4. Xây mobile app (React Native)
5. Add more admin tools 5. Thêm công cụ admin
--- ---
## ✨ FINAL VERDICT ## ✨ KẾT LUẬN CUỐI CÙNG
### Status: ✅ PRODUCTION-READY ### Trạng thái: ✅ SẴN SÀNG PRODUCTION
**The GoodGo Platform Web frontend is:** **Frontend GoodGo Platform Web là:**
- 🎯 **Feature-Complete** - All 24 pages implemented - 🎯 **Đầy đủ tính năng** - Đã triển khai cả 24 trang
- 🏗️ **Well-Architected** - Clean separation of concerns - 🏗️ **Kiến trúc tốt** - Phân tách trách nhiệm rõ ràng
- 🔐 **Secure** - Industry-standard security practices - 🔐 **Bảo mật** - Chuẩn bảo mật ngành
- ♿ **Accessible** - WCAG 2.1 AA compliant - ♿ **Truy cập được** - Tuân thủ WCAG 2.1 AA
- ⚡ **Performant** - Optimized with modern techniques - ⚡ **Hiệu năng cao** - Tối ưu bằng kỹ thuật hiện đại
- 🌍 **Global** - Multi-language support - 🌍 **Toàn cầu** - Hỗ trợ đa ngôn ngữ
- 🧪 **Tested** - 25 test suites - 🧪 **Đã test** - 25 test suite
- 📊 **Monitored** - Sentry integration ready - 📊 **Được giám sát** - Sẵn sàng tích hợp Sentry
- 🚀 **Deployable** - Docker & build configs included - 🚀 **Deploy được** - Có sẵn cấu hình Docker & build
### Confidence Level: **VERY HIGH** ### Mức độ tin cậy: **RẤT CAO**
All code is production-ready with zero critical issues. Minor recommendations are optional quality improvements. Toàn bộ mã nguồn đã sẵn sàng production với 0 vấn đề nghiêm trọng. Các khuyến nghị nhỏ chỉ là cải thiện chất lượng tuỳ chọn.
**Estimated Time to First Deploy:** 1-2 hours (after environment setup) **Thời gian dự kiến tới lần deploy đầu:** 1-2 giờ (sau khi setup môi trường)
--- ---
**Audit Completed:** April 11, 2026 **Audit hoàn tất:** 11 tháng 4, 2026
**Total Audit Time:** Comprehensive 2+ hour analysis **Tổng thời gian Audit:** Phân tích toàn diện 2+ giờ
**Files Reviewed:** 156 TypeScript/TSX files **Số file rà soát:** 156 file TypeScript/TSX
**Issues Found:** 0 Critical, 5 Minor (optional) **Vấn đề phát hiện:** 0 nghiêm trọng, 5 nhỏ (tuỳ chọn)

316
docs/deployment.md
View File

@@ -1,96 +1,96 @@
# Deployment Guide # Hướng Dẫn Deployment
## Overview ## Tổng Quan
GoodGo Platform AI consists of four deployable services: GoodGo Platform AI gồm bốn dịch vụ có thể deploy:
| Service | Technology | Default Port | | Dịch vụ | Công nghệ | Port mặc định |
|---------|-----------|-------------| |---------|-----------|-------------|
| **API** | NestJS (Node.js) | 3001 | | **API** | NestJS (Node.js) | 3001 |
| **Web** | Next.js | 3000 | | **Web** | Next.js | 3000 |
| **AI Services** | FastAPI (Python) | 8000 | | **AI Services** | FastAPI (Python) | 8000 |
| **Infrastructure** | Docker Compose | Various | | **Infrastructure** | Docker Compose | Khác nhau |
## Prerequisites ## Yêu Cầu Trước
- Docker Engine 24+ & Docker Compose v2 - Docker Engine 24+ & Docker Compose v2
- Node.js 22 LTS - Node.js 22 LTS
- pnpm 10.27+ - pnpm 10.27+
- Python 3.12 (for AI services, if running outside Docker) - Python 3.12 (cho AI services, nếu chạy ngoài Docker)
## Environment Configuration ## Cấu Hình Môi Trường
Copy `.env.example` to `.env` and configure all required values: Sao chép `.env.example` thành `.env` và cấu hình tất cả giá trị bắt buộc:
```bash ```bash
cp .env.example .env cp .env.example .env
``` ```
### Required Variables ### Biến Bắt Buộc
| Variable | Description | Example | | Biến | Mô tả | Ví dụ |
|----------|-------------|---------| |----------|-------------|---------|
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://user:pass@host:5432/goodgo` | | `DATABASE_URL` | Chuỗi kết nối PostgreSQL | `postgresql://user:pass@host:5432/goodgo` |
| `JWT_SECRET` | JWT signing key (min 32 chars) | Generate with `openssl rand -hex 32` | | `JWT_SECRET` | Khóa ký JWT (tối thiểu 32 ký tự) | Tạo bằng `openssl rand -hex 32` |
| `JWT_REFRESH_SECRET` | Refresh token signing key | Generate with `openssl rand -hex 32` | | `JWT_REFRESH_SECRET` | Khóa ký refresh token | Tạo bằng `openssl rand -hex 32` |
| `REDIS_URL` | Redis connection string | `redis://localhost:6379` | | `REDIS_URL` | Chuỗi kết nối Redis | `redis://localhost:6379` |
| `TYPESENSE_API_KEY` | Typesense admin API key | Generate a secure random key | | `TYPESENSE_API_KEY` | API key admin Typesense | Tạo một khóa ngẫu nhiên an toàn |
### Optional Variables ### Biến Tùy Chọn
| Variable | Description | Default | | Biến | Mô tả | Mặc định |
|----------|-------------|---------| |----------|-------------|---------|
| `API_PORT` | API server port | `3000` | | `API_PORT` | Port API server | `3000` |
| `WEB_PORT` | Web app port | `3001` | | `WEB_PORT` | Port web app | `3001` |
| `NODE_ENV` | Environment mode | `development` | | `NODE_ENV` | Chế độ môi trường | `development` |
| `CORS_ORIGINS` | Allowed CORS origins | — | | `CORS_ORIGINS` | Các origin CORS được phép | — |
| `CLAUDE_API_KEY` | Claude API key (for content moderation) | — | | `CLAUDE_API_KEY` | Claude API key (cho content moderation) | — |
| `NEXT_PUBLIC_MAPBOX_TOKEN` | Mapbox token (for maps) | — | | `NEXT_PUBLIC_MAPBOX_TOKEN` | Token Mapbox (cho bản đồ) | — |
| `VNPAY_*`, `MOMO_*`, `ZALOPAY_*` | Payment gateway credentials | — | | `VNPAY_*`, `MOMO_*`, `ZALOPAY_*` | Thông tin payment gateway | — |
## Infrastructure Setup (Docker Compose) ## Cài Đặt Hạ Tầng (Docker Compose)
Start all infrastructure services: Khởi động tất cả dịch vụ hạ tầng:
```bash ```bash
docker compose up -d docker compose up -d
``` ```
This starts: Lệnh này khởi động:
- **PostgreSQL 16 + PostGIS 3.4** (port 5432) - **PostgreSQL 16 + PostGIS 3.4** (port 5432)
- **Redis 7** (port 6379) - **Redis 7** (port 6379)
- **Typesense 27** (port 8108) - **Typesense 27** (port 8108)
- **MinIO** (API: 9000, Console: 9001) - **MinIO** (API: 9000, Console: 9001)
- **AI Services** (port 8000) - **AI Services** (port 8000)
- **pg-backup** — automated daily PostgreSQL backups at 02:00 UTC with verification at 04:00 UTC - **pg-backup** — backup PostgreSQL hằng ngày tự động lúc 02:00 UTC, có verify lúc 04:00 UTC
- **Loki** (port 3100) — log aggregation - **Loki** (port 3100) — tổng hợp log
- **Promtail** — log collection agent (ships container logs to Loki) - **Promtail** — agent thu thập log (chuyển log container đến Loki)
- **Prometheus** (port 9090) - **Prometheus** (port 9090)
- **Grafana** (port 3002) — dashboards for metrics and logs - **Grafana** (port 3002) — dashboard cho metric và log
Verify all services are healthy: Kiểm tra tất cả dịch vụ đang khỏe mạnh:
```bash ```bash
docker compose ps docker compose ps
``` ```
All services include health checks. Wait until all show `healthy` status. Tất cả dịch vụ đều có health check. Đợi đến khi tất cả hiển thị trạng thái `healthy`.
## Database Setup ## Cài Đặt Database
```bash ```bash
# Generate Prisma client # Sinh Prisma client
pnpm db:generate pnpm db:generate
# Apply migrations # Áp dụng migration
pnpm db:migrate:deploy pnpm db:migrate:deploy
# Seed initial data (optional) # Seed dữ liệu khởi tạo (tùy chọn)
pnpm db:seed pnpm db:seed
``` ```
## Building for Production ## Build cho Production
### API (NestJS) ### API (NestJS)
@@ -101,7 +101,7 @@ pnpm build
Output: `apps/api/dist/` Output: `apps/api/dist/`
Run in production: Chạy trong production:
```bash ```bash
NODE_ENV=production PORT=3001 node apps/api/dist/main.js NODE_ENV=production PORT=3001 node apps/api/dist/main.js
@@ -116,7 +116,7 @@ pnpm build
Output: `apps/web/.next/` Output: `apps/web/.next/`
Run in production: Chạy trong production:
```bash ```bash
NODE_ENV=production pnpm --filter web start NODE_ENV=production pnpm --filter web start
@@ -124,7 +124,7 @@ NODE_ENV=production pnpm --filter web start
### AI Services (FastAPI) ### AI Services (FastAPI)
The AI service runs in Docker via `docker compose`. To build separately: AI service chạy trong Docker qua `docker compose`. Để build riêng:
```bash ```bash
cd libs/ai-services cd libs/ai-services
@@ -132,64 +132,64 @@ docker build -t goodgo-ai-services .
docker run -p 8000:8000 --env-file ../../.env goodgo-ai-services docker run -p 8000:8000 --env-file ../../.env goodgo-ai-services
``` ```
## Production Checklist ## Checklist Production
### Security ### Bảo Mật
- [ ] Set strong, unique `JWT_SECRET` and `JWT_REFRESH_SECRET` (min 32 characters) - [ ] Đặt `JWT_SECRET` và `JWT_REFRESH_SECRET` mạnh, độc nhất (tối thiểu 32 ký tự)
- [ ] Set `NODE_ENV=production` - [ ] Đặt `NODE_ENV=production`
- [ ] Configure `CORS_ORIGINS` to only allow your domain(s) - [ ] Cấu hình `CORS_ORIGINS` chỉ cho phép domain của bạn
- [ ] Change default database passwords - [ ] Đổi mật khẩu database mặc định
- [ ] Change default MinIO credentials (`MINIO_USER`, `MINIO_PASSWORD`) - [ ] Đổi credential MinIO mặc định (`MINIO_USER`, `MINIO_PASSWORD`)
- [ ] Change default Grafana credentials (`GRAFANA_ADMIN_USER`, `GRAFANA_ADMIN_PASSWORD`) - [ ] Đổi credential Grafana mặc định (`GRAFANA_ADMIN_USER`, `GRAFANA_ADMIN_PASSWORD`)
- [ ] Use a strong, unique `TYPESENSE_API_KEY` - [ ] Dùng `TYPESENSE_API_KEY` mạnh, độc nhất
- [ ] Enable SSL/TLS termination (reverse proxy) - [ ] Bật SSL/TLS termination (reverse proxy)
- [ ] Set `MINIO_USE_SSL=true` if MinIO is exposed publicly - [ ] Đặt `MINIO_USE_SSL=true` nếu MinIO được public
### Database ### Database
- [ ] Run `pnpm db:migrate:deploy` (not `db:migrate:dev`) - [ ] Chạy `pnpm db:migrate:deploy` (không dùng `db:migrate:dev`)
- [ ] Enable PostgreSQL connection pooling (PgBouncer recommended) - [ ] Bật connection pooling cho PostgreSQL (khuyến nghị PgBouncer)
- [ ] Configure automated backups - [ ] Cấu hình backup tự động
- [ ] Set appropriate `max_connections` in PostgreSQL config - [ ] Đặt `max_connections` phù hợp trong cấu hình PostgreSQL
### Monitoring ### Monitoring
- [ ] Verify Prometheus is scraping `/metrics` endpoint - [ ] Xác nhận Prometheus đang scrape endpoint `/metrics`
- [ ] Import Grafana dashboards from `monitoring/grafana/dashboards/` - [ ] Import dashboard Grafana từ `monitoring/grafana/dashboards/`
- [ ] Set up alerting rules for error rates and latency - [ ] Cài đặt rule alerting cho error rate và latency
### Performance ### Performance
- [ ] Configure Redis `maxmemory` and eviction policy - [ ] Cấu hình Redis `maxmemory` và chính sách eviction
- [ ] Set appropriate Typesense `--memory-limit` - [ ] Đặt `--memory-limit` phù hợp cho Typesense
- [ ] Enable gzip/brotli compression in reverse proxy - [ ] Bật nén gzip/brotli ở reverse proxy
- [ ] Configure CDN for static assets (Next.js `/_next/static/`) - [ ] Cấu hình CDN cho static asset (Next.js `/_next/static/`)
## Health Checks ## Health Check
| Service | Endpoint | Expected Response | | Dịch vụ | Endpoint | Phản hồi mong đợi |
|---------|----------|-------------------| |---------|----------|-------------------|
| API | `GET /health` | `{"status": "ok"}` | | API | `GET /health` | `{"status": "ok"}` |
| API (Swagger) | `GET /api/v1/docs` | Swagger UI page | | API (Swagger) | `GET /api/v1/docs` | Trang Swagger UI |
| API (Metrics) | `GET /api/v1/metrics` | Prometheus metrics | | API (Metrics) | `GET /api/v1/metrics` | Metric Prometheus |
| AI Services | `GET /health` | `{"status": "ok"}` | | AI Services | `GET /health` | `{"status": "ok"}` |
| Typesense | `GET /health` | `{"ok": true}` | | Typesense | `GET /health` | `{"ok": true}` |
| Loki | `GET /ready` | 200 OK | | Loki | `GET /ready` | 200 OK |
| Redis | `redis-cli ping` | `PONG` | | Redis | `redis-cli ping` | `PONG` |
| PostgreSQL | `pg_isready -h host -p 5432` | Exit code 0 | | PostgreSQL | `pg_isready -h host -p 5432` | Exit code 0 |
## Scaling Considerations ## Cân Nhắc Về Scaling
### Horizontal Scaling ### Horizontal Scaling
- **API**: Stateless — scale with multiple instances behind a load balancer - **API**: Stateless — scale với nhiều instance phía sau load balancer
- **Web**: Stateless — scale with multiple instances or deploy to Vercel/Cloudflare - **Web**: Stateless — scale với nhiều instance hoặc deploy lên Vercel/Cloudflare
- **AI Services**: CPU-bound — scale based on valuation request volume - **AI Services**: CPU-bound — scale theo lượng yêu cầu định giá
- **Redis**: Use Redis Cluster for high availability - **Redis**: Dùng Redis Cluster cho tính sẵn sàng cao
- **PostgreSQL**: Read replicas for query-heavy workloads - **PostgreSQL**: Read replica cho workload nhiều truy vấn
### Recommended Architecture (Production) ### Kiến Trúc Khuyến Nghị (Production)
``` ```
┌─────────────┐ ┌─────────────┐
@@ -216,143 +216,143 @@ docker run -p 8000:8000 --env-file ../../.env goodgo-ai-services
## CI/CD Pipeline ## CI/CD Pipeline
### Branch Strategy ### Chiến Lược Branch
| Branch | Deploy Target | Trigger | Notes | | Branch | Đích deploy | Trigger | Ghi chú |
|--------|--------------|---------|-------| |--------|--------------|---------|-------|
| `develop` | Staging | Auto (push) | Every merge to `develop` auto-deploys to staging | | `develop` | Staging | Tự động (push) | Mọi merge vào `develop` đều tự deploy lên staging |
| `master` | Staging | Auto (push) | Master push also deploys to staging for verification | | `master` | Staging | Tự động (push) | Push master cũng deploy lên staging để verify |
| Manual | Staging/Production | `workflow_dispatch` | Manual trigger via GitHub Actions UI | | Manual | Staging/Production | `workflow_dispatch` | Trigger thủ công qua GitHub Actions UI |
### Staging Auto-Deploy Flow ### Quy Trình Auto-Deploy Staging
``` ```
Push to develop → Build images → Tag rollback → Deploy to staging → Smoke tests → Cleanup / Rollback Push to develop → Build images → Tag rollback → Deploy to staging → Smoke tests → Cleanup / Rollback
``` ```
1. **Build**: Docker images for API, Web, and AI Services are built and pushed to GHCR with `staging-latest` tag 1. **Build**: Docker image cho API, Web, và AI Services được build và push lên GHCR với tag `staging-latest`
2. **Tag rollback**: Current running images are tagged as `:rollback` before new images are pulled 2. **Tag rollback**: Image hiện đang chạy được tag là `:rollback` trước khi pull image mới
3. **Deploy**: New images are pulled and services are updated via rolling restart (zero-downtime) 3. **Deploy**: Image mới được pull và dịch vụ được cập nhật qua rolling restart (zero-downtime)
4. **Verify**: Health check polls `$STAGING_URL/health` for up to 100 seconds 4. **Verify**: Health check poll `$STAGING_URL/health` trong tối đa 100 giây
5. **Smoke test**: `scripts/smoke-test.sh` runs against the staging URL, checking health probes, core API endpoints, search, and auth 5. **Smoke test**: `scripts/smoke-test.sh` chạy với staging URL, kiểm tra health probe, các endpoint API cốt lõi, search và auth
6. **Cleanup**: On success, `:rollback` tags are removed and `docker image prune` cleans up old layers 6. **Cleanup**: Khi thành công, các tag `:rollback` được xóa và `docker image prune` dọn dẹp các layer cũ
7. **Notify**: Slack notification on success or failure 7. **Notify**: Thông báo Slack khi thành công hoặc thất bại
8. **Rollback**: If smoke tests fail, automatic rollback restores the `:rollback` tagged images 8. **Rollback**: Nếu smoke test thất bại, rollback tự động khôi phục image có tag `:rollback`
### Notifications ### Thông Báo
Deploy status notifications are sent to Slack via `SLACK_WEBHOOK_URL` secret: Trạng thái deploy được gửi đến Slack qua secret `SLACK_WEBHOOK_URL`:
| Event | Channel | Content | | Sự kiện | Kênh | Nội dung |
|-------|---------|---------| |-------|---------|---------|
| Staging smoke tests pass | Slack | ✅ Commit SHA, branch, link to run | | Smoke test staging pass | Slack | ✅ Commit SHA, branch, link đến run |
| Staging smoke tests fail | Slack | 🚨 Commit SHA, branch, link to run | | Smoke test staging fail | Slack | 🚨 Commit SHA, branch, link đến run |
| Staging rollback triggered | Slack | ⚠️ Commit SHA, reason, link to run | | Trigger rollback staging | Slack | ⚠️ Commit SHA, lý do, link đến run |
| Production deploy success | Slack | ✅ Commit SHA, branch | | Deploy production thành công | Slack | ✅ Commit SHA, branch |
| Production rollback triggered | Slack | ⚠️ Commit SHA, reason, link to run | | Trigger rollback production | Slack | ⚠️ Commit SHA, lý do, link đến run |
### Required Secrets ### Secret Bắt Buộc
| Secret | Environment | Description | | Secret | Môi trường | Mô tả |
|--------|-------------|-------------| |--------|-------------|-------------|
| `STAGING_HOST` | staging | Staging server hostname/IP | | `STAGING_HOST` | staging | Hostname/IP server staging |
| `STAGING_USER` | staging | SSH user for staging deploys | | `STAGING_USER` | staging | User SSH cho deploy staging |
| `STAGING_SSH_KEY` | staging | SSH private key for staging | | `STAGING_SSH_KEY` | staging | Khóa SSH private cho staging |
| `STAGING_URL` | staging | Staging base URL (e.g., `https://staging.goodgo.vn`) | | `STAGING_URL` | staging | URL gốc staging (vd: `https://staging.goodgo.vn`) |
| `PRODUCTION_HOST` | production | Production server hostname/IP | | `PRODUCTION_HOST` | production | Hostname/IP server production |
| `PRODUCTION_USER` | production | SSH user for production deploys | | `PRODUCTION_USER` | production | User SSH cho deploy production |
| `PRODUCTION_SSH_KEY` | production | SSH private key for production | | `PRODUCTION_SSH_KEY` | production | Khóa SSH private cho production |
| `PRODUCTION_URL` | production | Production base URL | | `PRODUCTION_URL` | production | URL gốc production |
| `SLACK_WEBHOOK_URL` | both | Slack incoming webhook URL | | `SLACK_WEBHOOK_URL` | cả hai | URL incoming webhook Slack |
## Rollback ## Rollback
### Rollback Safety Mechanism ### Cơ Chế An Toàn Khi Rollback
The deploy pipeline uses **explicit `:rollback` image tags** to guarantee safe rollbacks. Here's how it works: Pipeline deploy sử dụng **tag image `:rollback` rõ ràng** để bảo đảm rollback an toàn. Cách hoạt động như sau:
1. **Before pulling new images**: The current running images are tagged as `goodgo-api:rollback`, `goodgo-web:rollback`, and `goodgo-ai-services:rollback` 1. **Trước khi pull image mới**: Image hiện đang chạy được tag là `goodgo-api:rollback`, `goodgo-web:rollback`, và `goodgo-ai-services:rollback`
2. **After pulling new images**: Services are updated with the new images via rolling restart 2. **Sau khi pull image mới**: Dịch vụ được cập nhật với image mới qua rolling restart
3. **After smoke tests pass**: The `:rollback` tags are removed and `docker image prune` cleans up old layers 3. **Sau khi smoke test pass**: Tag `:rollback` được xóa và `docker image prune` dọn dẹp layer cũ
4. **If smoke tests fail**: The `:rollback` tagged images are used to restore the previous version 4. **Nếu smoke test fail**: Image có tag `:rollback` được dùng để khôi phục phiên bản trước
This ensures that `docker image prune` never deletes the images needed for rollback, because: Điều này bảo đảm `docker image prune` không bao giờ xóa image cần cho rollback, vì:
- Image pruning only happens **after** smoke tests pass - Image pruning chỉ xảy ra **sau** khi smoke test pass
- The `:rollback` tags keep the previous images pinned even if pruning were to run accidentally - Tag `:rollback` giữ image trước được pin lại ngay cả khi pruning vô tình chạy
### Automatic Rollback (Staging) ### Rollback Tự Động (Staging)
The staging pipeline includes automatic rollback when smoke tests fail: Pipeline staging có rollback tự động khi smoke test thất bại:
1. **Pre-deploy**: Current container images are tagged with `:rollback` suffix before new images are pulled 1. **Trước deploy**: Image container hiện tại được tag với hậu tố `:rollback` trước khi pull image mới
2. **Smoke test failure**: If `scripts/smoke-test.sh` exits non-zero, the `rollback-staging` job triggers 2. **Smoke test thất bại**: Nếu `scripts/smoke-test.sh` thoát non-zero, job `rollback-staging` được trigger
3. **Rollback execution**: Containers are stopped and restarted using the `:rollback` tagged images 3. **Thực hiện rollback**: Container được dừng và khởi động lại bằng image có tag `:rollback`
4. **Verification**: Health check confirms the rollback succeeded 4. **Verify**: Health check xác nhận rollback đã thành công
5. **Notification**: Slack notification reports the rollback with links to the failed run 5. **Notification**: Slack báo cáo rollback kèm link đến run thất bại
### Automatic Rollback (Production) ### Rollback Tự Động (Production)
Same mechanism as staging — smoke test failure triggers `rollback-production` using the `:rollback` tagged images. Cơ chế giống staging — smoke test thất bại sẽ trigger `rollback-production` dùng image có tag `:rollback`.
### Manual Rollback ### Rollback Thủ Công
To manually rollback a staging or production deployment: Để rollback thủ công một deployment staging hoặc production:
#### Option 1: Re-deploy a known-good commit #### Lựa chọn 1: Re-deploy một commit đã biết là tốt
```bash ```bash
# Trigger a deploy of a specific commit via GitHub Actions # Trigger deploy của một commit cụ thể qua GitHub Actions
gh workflow run deploy.yml \ gh workflow run deploy.yml \
--ref <known-good-commit-or-branch> \ --ref <known-good-commit-or-branch> \
-f environment=staging -f environment=staging
``` ```
#### Option 2: SSH rollback using :rollback tags (fastest) #### Lựa chọn 2: SSH rollback dùng tag :rollback (nhanh nhất)
```bash ```bash
# SSH into the staging/production server # SSH vào server staging/production
ssh deploy@<host> ssh deploy@<host>
cd ~/goodgo cd ~/goodgo
# Stop current services # Dừng dịch vụ hiện tại
docker compose -f docker-compose.prod.yml stop api web ai-services docker compose -f docker-compose.prod.yml stop api web ai-services
# Verify :rollback images exist # Xác nhận image :rollback tồn tại
docker image inspect goodgo-api:rollback > /dev/null 2>&1 && echo "API rollback available" docker image inspect goodgo-api:rollback > /dev/null 2>&1 && echo "API rollback available"
docker image inspect goodgo-web:rollback > /dev/null 2>&1 && echo "Web rollback available" docker image inspect goodgo-web:rollback > /dev/null 2>&1 && echo "Web rollback available"
docker image inspect goodgo-ai-services:rollback > /dev/null 2>&1 && echo "AI rollback available" docker image inspect goodgo-ai-services:rollback > /dev/null 2>&1 && echo "AI rollback available"
# Restart services (compose picks up cached/rollback images) # Khởi động lại dịch vụ (compose lấy image cache/rollback)
docker compose -f docker-compose.prod.yml up -d --wait api web ai-services docker compose -f docker-compose.prod.yml up -d --wait api web ai-services
# Verify health # Verify health
curl -sf http://localhost:3001/health && echo "Rollback successful" curl -sf http://localhost:3001/health && echo "Rollback successful"
``` ```
> **Note:** The `:rollback` tags are only available until the next successful deploy cleans them up. If you need to roll back to an older version, use Option 3 below. > **Lưu ý:** Tag `:rollback` chỉ có sẵn cho đến khi lần deploy thành công kế tiếp dọn chúng đi. Nếu cần rollback về phiên bản cũ hơn, dùng Lựa chọn 3 dưới đây.
#### Option 3: Pin to a specific image tag #### Lựa chọn 3: Pin về một image tag cụ thể
```bash ```bash
ssh deploy@<host> ssh deploy@<host>
cd ~/goodgo cd ~/goodgo
# Set IMAGE_TAG to a known-good SHA # Đặt IMAGE_TAG về một SHA đã biết là tốt
export IMAGE_TAG=<known-good-commit-sha> export IMAGE_TAG=<known-good-commit-sha>
export REGISTRY_URL=ghcr.io/<owner> export REGISTRY_URL=ghcr.io/<owner>
# Pull and restart with the pinned tag # Pull và khởi động lại với tag đã pin
docker compose -f docker-compose.prod.yml pull api web ai-services docker compose -f docker-compose.prod.yml pull api web ai-services
docker compose -f docker-compose.prod.yml up -d --no-deps --wait api web ai-services docker compose -f docker-compose.prod.yml up -d --no-deps --wait api web ai-services
``` ```
#### Option 4: Use deploy-production.sh (built-in rollback) #### Lựa chọn 4: Dùng deploy-production.sh (rollback tích hợp sẵn)
The manual deploy script (`scripts/deploy-production.sh`) has integrated rollback support: Script deploy thủ công (`scripts/deploy-production.sh`) có hỗ trợ rollback tích hợp:
- Automatically tags `:rollback` images before pulling - Tự động tag image `:rollback` trước khi pull
- Runs health checks and smoke tests - Chạy health check và smoke test
- Auto-rollbacks using `:rollback` tags if either fails - Tự rollback dùng tag `:rollback` nếu một trong hai thất bại
- Only prunes images after smoke tests pass - Chỉ prune image sau khi smoke test pass
```bash ```bash
ssh ubuntu@185.225.232.65 ssh ubuntu@185.225.232.65
@@ -360,21 +360,21 @@ cd ~/goodgo
./scripts/deploy-production.sh [image-tag] ./scripts/deploy-production.sh [image-tag]
``` ```
### Database Rollback ### Rollback Database
Prisma does not support automatic down migrations. If a migration must be reverted: Prisma không hỗ trợ down migration tự động. Nếu một migration cần được hoàn tác:
1. Identify the migration in `prisma/migrations/` 1. Xác định migration trong `prisma/migrations/`
2. Write a manual SQL rollback script 2. Viết script rollback SQL thủ công
3. Apply via `psql` or a migration tool 3. Áp dụng qua `psql` hoặc công cụ migration
4. Update `_prisma_migrations` table 4. Cập nhật bảng `_prisma_migrations`
Always test migrations against a staging database before production deployment. Luôn test migration với database staging trước khi deploy production.
### Post-Rollback Checklist ### Checklist Sau Rollback
- [ ] Verify health endpoints respond: `GET /health`, `GET /ready` - [ ] Xác nhận health endpoint phản hồi: `GET /health`, `GET /ready`
- [ ] Run smoke tests manually: `./scripts/smoke-test.sh <url>` - [ ] Chạy smoke test thủ công: `./scripts/smoke-test.sh <url>`
- [ ] Check application logs: `docker compose -f docker-compose.prod.yml logs --tail=100 api web` - [ ] Kiểm tra log ứng dụng: `docker compose -f docker-compose.prod.yml logs --tail=100 api web`
- [ ] Confirm Grafana dashboards show normal metrics - [ ] Xác nhận dashboard Grafana hiển thị metric bình thường
- [ ] Notify the team via Slack about the rollback and root cause - [ ] Thông báo cho team qua Slack về rollback và nguyên nhân gốc

344
docs/guides/AUTH_IMPLEMENTATION_CHECKLIST.md
View File

@@ -1,114 +1,114 @@
# GoodGo Platform - Authentication Implementation Checklist # GoodGo Platform - Checklist Triển Khai Authentication
**Date:** April 12, 2026 **Ngày:** 12 tháng 4, 2026
**Status:** ✅ Complete Analysis **Trạng thái:** ✅ Phân Tích Hoàn Tất
--- ---
## 📋 Authentication System Components ## 📋 Các Thành Phần Của Hệ Thống Authentication
### ✅ 1. Password Hashing ### ✅ 1. Hashing Mật Khẩu
- **Algorithm:** bcrypt - **Thuật toán:** bcrypt
- **Salt Rounds:** 12 (configurable via `BCRYPT_ROUNDS` env var) - **Salt Rounds:** 12 (có thể cấu hình qua biến env `BCRYPT_ROUNDS`)
- **Min Password:** 8 characters - **Mật khẩu tối thiểu:** 8 ký tự
- **Location:** `apps/api/src/modules/auth/domain/value-objects/hashed-password.vo.ts` - **Vị trí:** `apps/api/src/modules/auth/domain/value-objects/hashed-password.vo.ts`
- **Method Used:** `HashedPassword.fromPlain(password)` → async bcrypt.hash() - **Method dùng:** `HashedPassword.fromPlain(password)` → async bcrypt.hash()
- **Comparison:** `passwordHash.compare(plainPassword)` → bcrypt.compare() - **So sánh:** `passwordHash.compare(plainPassword)` → bcrypt.compare()
### ✅ 2. Phone Validation & Normalization ### ✅ 2. Validate & Chuẩn Hóa Số Điện Thoại
- **File:** `apps/api/src/modules/shared/utils/vietnam-phone.validator.ts` - **File:** `apps/api/src/modules/shared/utils/vietnam-phone.validator.ts`
- **Regex:** `/^(?:\+84|84|0)(3[2-9]|5[2689]|7[06-9]|8[1-9]|9[0-9])\d{7}$/` - **Regex:** `/^(?:\+84|84|0)(3[2-9]|5[2689]|7[06-9]|8[1-9]|9[0-9])\d{7}$/`
- **Accepted Formats:** - **Định dạng được chấp nhận:**
- `0900000001` (local) - `0900000001` (local)
- `84900000001` (country code, no +) - `84900000001` (mã quốc gia, không +)
- `+84900000001` (international) - `+84900000001` (quốc tế)
- **Normalized Format:** Always `+84XXX...` (country code prefix) - **Định dạng chuẩn hóa:** Luôn là `+84XXX...` (prefix mã quốc gia)
- **Carriers:** Mobile only (no landlines) - **Nhà mạng:** Chỉ di động (không có cố định)
- 32-39: Viettel/VinaPhone/MobiFone - 32-39: Viettel/VinaPhone/MobiFone
- 52, 56, 58, 59: Viettel - 52, 56, 58, 59: Viettel
- 70, 76-79: Newer carriers - 70, 76-79: Nhà mạng mới
- 81-89: VinaPhone - 81-89: VinaPhone
- 90-99: MobiFone - 90-99: MobiFone
### ✅ 3. Email Validation & Normalization ### ✅ 3. Validate & Chuẩn Hóa Email
- **File:** `apps/api/src/modules/auth/domain/value-objects/email.vo.ts` - **File:** `apps/api/src/modules/auth/domain/value-objects/email.vo.ts`
- **Regex:** `/^[^\s@]+@[^\s@]+\.[^\s@]+$/` (basic validation) - **Regex:** `/^[^\s@]+@[^\s@]+\.[^\s@]+$/` (validate cơ bản)
- **Normalization:** lowercase + trimmed - **Chuẩn hóa:** lowercase + trim
- **Example:** `ADMIN@GOODGO.VN` → stored as `admin@goodgo.vn` - **Ví dụ:** `ADMIN@GOODGO.VN` → lưu thành `admin@goodgo.vn`
### ✅ 4. PII Encryption & Hashing ### ✅ 4. Mã Hóa & Hashing PII
- **File:** `apps/api/src/modules/shared/infrastructure/field-encryption.ts` - **File:** `apps/api/src/modules/shared/infrastructure/field-encryption.ts`
- **Encryption Algorithm:** AES-256-GCM - **Thuật toán mã hóa:** AES-256-GCM
- **Key Size:** 32 bytes (64 hex characters) - **Kích thước key:** 32 byte (64 ký tự hex)
- **IV:** 12 bytes (random) - **IV:** 12 byte (ngẫu nhiên)
- **Auth Tag:** 16 bytes - **Auth Tag:** 16 byte
- **Storage Format:** `enc:v{version}:{iv}:{authTag}:{ciphertext}` (hex) - **Định dạng lưu trữ:** `enc:v{version}:{iv}:{authTag}:{ciphertext}` (hex)
- **Encrypted Fields:** - **Field được mã hóa:**
- `email` → stored encrypted + hash in `emailHash` - `email` → lưu mã hóa + hash trong `emailHash`
- `phone` → stored encrypted + hash in `phoneHash` - `phone` → lưu mã hóa + hash trong `phoneHash`
- `kycData` → stored encrypted (no separate hash) - `kycData` → lưu mã hóa (không có hash riêng)
- **Hash Function:** HMAC-SHA256 (derived from encryption key via HKDF-SHA256) - **Hàm hash:** HMAC-SHA256 (dẫn xuất từ encryption key qua HKDF-SHA256)
- **Hash Normalization:** lowercase + trimmed - **Chuẩn hóa hash:** lowercase + trim
- **Env Vars:** - **Biến env:**
- `FIELD_ENCRYPTION_KEY` (required) - hex string, 64 chars - `FIELD_ENCRYPTION_KEY` (bắt buộc) - chuỗi hex, 64 ký tự
- `FIELD_ENCRYPTION_KEY_VERSION` (optional, default: 1) - `FIELD_ENCRYPTION_KEY_VERSION` (tùy chọn, mặc định: 1)
- Fallback: `KYC_ENCRYPTION_KEY` / `KYC_ENCRYPTION_KEY_VERSION` - Fallback: `KYC_ENCRYPTION_KEY` / `KYC_ENCRYPTION_KEY_VERSION`
### ✅ 5. Login Flow ### ✅ 5. Luồng Đăng Nhập
- **File:** `apps/api/src/modules/auth/infrastructure/strategies/local.strategy.ts` - **File:** `apps/api/src/modules/auth/infrastructure/strategies/local.strategy.ts`
- **Username Field:** `phone` (Vietnamese format) - **Trường username:** `phone` (định dạng Việt Nam)
- **Password Field:** `password` (plaintext) - **Trường password:** `password` (plaintext)
- **User Lookup:** By `phoneHash` (unique index) - **Lookup user:** Theo `phoneHash` (unique index)
- **Steps:** - **Các bước:**
1. Normalize phone 1. Chuẩn hóa số điện thoại
2. Find user by phoneHash 2. Tìm user theo phoneHash
3. Check `isActive` = true 3. Kiểm tra `isActive` = true
4. Compare password (bcrypt) 4. So sánh password (bcrypt)
5. Check `totpEnabled` 5. Kiểm tra `totpEnabled`
6. Issue JWT tokens or MFA challenge 6. Cấp JWT token hoặc MFA challenge
- **MFA Response (if enabled):** `challengeId` + 5-minute TTL - **Phản hồi MFA (nếu bật):** `challengeId` + TTL 5 phút
- **No MFA Response:** `accessToken` + `refreshToken` + expiry - **Phản hồi không có MFA:** `accessToken` + `refreshToken` + thời hạn
### ✅ 6. User Roles ### ✅ 6. Vai Trò User
- **Enum:** `UserRole` (Prisma) - **Enum:** `UserRole` (Prisma)
- **Values:** - **Giá trị:**
- `BUYER` (default) - Can search, inquire, make offers - `BUYER` (mặc định) - Có thể tìm kiếm, hỏi, đặt giá
- `SELLER` - Can create listings - `SELLER` - Có thể tạo tin đăng
- `AGENT` - Professional agent with verified profile - `AGENT` - Agent chuyên nghiệp với hồ sơ đã verify
- `ADMIN` - Full platform access - `ADMIN` - Truy cập đầy đủ platform
- **Default Role:** `BUYER` - **Vai trò mặc định:** `BUYER`
- **Admin Role:** Created explicitly with `role: 'ADMIN'` - **Vai trò Admin:** Tạo rõ ràng với `role: 'ADMIN'`
### ✅ 7. MFA (Multi-Factor Authentication) ### ✅ 7. MFA (Multi-Factor Authentication)
- **TOTP:** - **TOTP:**
- Generator: otplib (RFC 6238) - Generator: otplib (RFC 6238)
- Period: 30 seconds - Period: 30 giây
- Digits: 6 - Digit: 6
- Clock Skew: ±30 seconds - Clock Skew: ±30 giây
- **Backup Codes:** - **Backup Code:**
- Count: 10 - Số lượng: 10
- Length: 8 characters each - Độ dài: 8 ký tự mỗi mã
- Charset: A-Z (no O, I), 2-9 (no 0, 1) - Charset: A-Z (không có O, I), 2-9 (không có 0, 1)
- Hashing: HMAC-SHA256 (not bcrypt) - Hashing: HMAC-SHA256 (không phải bcrypt)
- Secret Key: `MFA_BACKUP_CODE_SECRET` or fallback to `JWT_SECRET` - Secret Key: `MFA_BACKUP_CODE_SECRET` hoặc fallback về `JWT_SECRET`
- **TOTP Secret Storage:** Encrypted with AES-256-GCM - **Lưu trữ TOTP Secret:** Mã hóa với AES-256-GCM
### ✅ 8. User Model Fields (Required for Login) ### ✅ 8. Field User Model (Bắt Buộc Cho Đăng Nhập)
```typescript ```typescript
User { User {
id: string // CUID id: string // CUID
phone: string // Normalized: +84XXX... phone: string // Chuẩn hóa: +84XXX...
phoneHash: string // HMAC-SHA256 (unique index) phoneHash: string // HMAC-SHA256 (unique index)
email?: string // Lowercase, trimmed (encrypted) email?: string // Lowercase, trim (mã hóa)
emailHash?: string // HMAC-SHA256 (unique index) emailHash?: string // HMAC-SHA256 (unique index)
passwordHash?: string // bcrypt hash (nullable for OAuth) passwordHash?: string // hash bcrypt (nullable cho OAuth)
fullName: string fullName: string
role: UserRole // BUYER | SELLER | AGENT | ADMIN role: UserRole // BUYER | SELLER | AGENT | ADMIN
isActive: boolean // true = can login isActive: boolean // true = có thể đăng nhập
kycStatus: KYCStatus // NONE | PENDING | VERIFIED | REJECTED kycStatus: KYCStatus // NONE | PENDING | VERIFIED | REJECTED
totpEnabled: boolean // MFA enabled totpEnabled: boolean // MFA đã bật
totpSecret?: string // Encrypted totpSecret?: string // Mã hóa
totpBackupCodes: string[] // HMAC-SHA256 hashed codes totpBackupCodes: string[] // Mã đã hash HMAC-SHA256
createdAt: DateTime createdAt: DateTime
updatedAt: DateTime updatedAt: DateTime
} }
@@ -116,32 +116,32 @@ User {
--- ---
## 🔐 Creating Login-Capable Seed Users ## 🔐 Tạo Seed User Có Khả Năng Đăng Nhập
### Requirements Checklist ### Checklist Yêu Cầu
- [ ] Password ≥ 8 characters - [ ] Mật khẩu ≥ 8 ký tự
- [ ] Phone matches Vietnamese regex - [ ] Số điện thoại khớp regex Việt Nam
- [ ] Phone normalized to `+84...` format - [ ] Số điện thoại chuẩn hóa thành định dạng `+84...`
- [ ] Email matches basic regex `^[^\s@]+@[^\s@]+\.[^\s@]+$` - [ ] Email khớp regex cơ bản `^[^\s@]+@[^\s@]+\.[^\s@]+$`
- [ ] Email lowercased - [ ] Email lowercased
- [ ] Password hashed with bcrypt (≥12 rounds) - [ ] Mật khẩu hash với bcrypt (≥12 rounds)
- [ ] `phoneHash` computed (HMAC-SHA256) - [ ] `phoneHash` được tính (HMAC-SHA256)
- [ ] `emailHash` computed (HMAC-SHA256) - [ ] `emailHash` được tính (HMAC-SHA256)
- [ ] `isActive: true` - [ ] `isActive: true`
- [ ] `totpEnabled: false` (for seed users) - [ ] `totpEnabled: false` (cho seed user)
- [ ] `totpBackupCodes: []` - [ ] `totpBackupCodes: []`
### Implementation Steps ### Các Bước Triển Khai
**Step 1: Normalize Phone** **Bước 1: Chuẩn Hóa Số Điện Thoại**
```typescript ```typescript
const phone = '0900000001'; const phone = '0900000001';
const normalized = `+84${phone.slice(1)}`; // '+84900000001' const normalized = `+84${phone.slice(1)}`; // '+84900000001'
``` ```
**Step 2: Derive HMAC Key** **Bước 2: Dẫn Xuất HMAC Key**
```typescript ```typescript
const encryptionKey = process.env['FIELD_ENCRYPTION_KEY']; // hex string const encryptionKey = process.env['FIELD_ENCRYPTION_KEY']; // chuỗi hex
const hmacKey = crypto.hkdfSync( const hmacKey = crypto.hkdfSync(
'sha256', 'sha256',
Buffer.from(encryptionKey, 'hex'), Buffer.from(encryptionKey, 'hex'),
@@ -151,7 +151,7 @@ const hmacKey = crypto.hkdfSync(
); );
``` ```
**Step 3: Compute Hashes** **Bước 3: Tính Hash**
```typescript ```typescript
const phoneHash = crypto const phoneHash = crypto
.createHmac('sha256', hmacKey) .createHmac('sha256', hmacKey)
@@ -164,12 +164,12 @@ const emailHash = crypto
.digest('hex'); .digest('hex');
``` ```
**Step 4: Hash Password** **Bước 4: Hash Mật Khẩu**
```typescript ```typescript
const passwordHash = await bcrypt.hash('AdminPassword123', 12); const passwordHash = await bcrypt.hash('AdminPassword123', 12);
``` ```
**Step 5: Create User** **Bước 5: Tạo User**
```typescript ```typescript
await prisma.user.create({ await prisma.user.create({
data: { data: {
@@ -191,15 +191,15 @@ await prisma.user.create({
--- ---
## 🧪 Testing Login ## 🧪 Test Đăng Nhập
### Prerequisites ### Yêu Cầu Trước
- User exists in database - User tồn tại trong database
- `passwordHash` is set (not null) - `passwordHash` được set (không null)
- `isActive: true` - `isActive: true`
- No MFA enabled (or have MFA code ready) - Không bật MFA (hoặc có sẵn mã MFA)
### Test Request ### Request Test
```bash ```bash
curl -X POST http://localhost:3000/auth/login \ curl -X POST http://localhost:3000/auth/login \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
@@ -209,7 +209,7 @@ curl -X POST http://localhost:3000/auth/login \
}' }'
``` ```
### Expected Response (Success) ### Phản Hồi Mong Đợi (Thành Công)
```json ```json
{ {
"requiresMfa": false, "requiresMfa": false,
@@ -221,127 +221,127 @@ curl -X POST http://localhost:3000/auth/login \
} }
``` ```
### Error Cases ### Các Trường Hợp Lỗi
- **Invalid phone format:** "Số điện thoại không hợp lệ" - **Định dạng số điện thoại không hợp lệ:** "Số điện thoại không hợp lệ"
- **User not found:** "Số điện thoại hoặc mật khẩu không đúng" - **Không tìm thấy user:** "Số điện thoại hoặc mật khẩu không đúng"
- **User inactive:** "Tài khoản đã bị vô hiệu hóa" - **User không active:** "Tài khoản đã bị vô hiệu hóa"
- **Wrong password:** "Số điện thoại hoặc mật khẩu không đúng" - **Sai mật khẩu:** "Số điện thoại hoặc mật khẩu không đúng"
- **MFA required:** `{ "requiresMfa": true, "challengeId": "..." }` - **Yêu cầu MFA:** `{ "requiresMfa": true, "challengeId": "..." }`
--- ---
## 📁 Key Files Reference ## 📁 Tham Khảo Các File Chính
| File | Purpose | Key Functions | | File | Mục đích | Hàm chính |
|------|---------|---------------| |------|---------|---------------|
| `hashed-password.vo.ts` | Password hashing | `fromPlain()`, `compare()` | | `hashed-password.vo.ts` | Hash mật khẩu | `fromPlain()`, `compare()` |
| `phone.vo.ts` | Phone validation | `create()` | | `phone.vo.ts` | Validate số điện thoại | `create()` |
| `email.vo.ts` | Email validation | `create()` | | `email.vo.ts` | Validate email | `create()` |
| `vietnam-phone.validator.ts` | Phone regex/normalize | `isValidVietnamPhone()`, `normalizeVietnamPhone()` | | `vietnam-phone.validator.ts` | Regex/chuẩn hóa số điện thoại | `isValidVietnamPhone()`, `normalizeVietnamPhone()` |
| `field-encryption.ts` | PII encryption/hashing | `encryptField()`, `decryptField()`, `computeHash()` | | `field-encryption.ts` | Mã hóa/hash PII | `encryptField()`, `decryptField()`, `computeHash()` |
| `local.strategy.ts` | Login flow | `validate()` | | `local.strategy.ts` | Luồng đăng nhập | `validate()` |
| `mfa.service.ts` | TOTP/backup codes | `generateSetup()`, `verifyTotp()`, `generateBackupCodes()` | | `mfa.service.ts` | TOTP/backup code | `generateSetup()`, `verifyTotp()`, `generateBackupCodes()` |
| `user.entity.ts` | User domain model | `createNew()` | | `user.entity.ts` | Domain model User | `createNew()` |
| `prisma-user.repository.ts` | User persistence | `findByPhone()`, `save()` | | `prisma-user.repository.ts` | Persist user | `findByPhone()`, `save()` |
| `encrypt-pii-fields.ts` | Backfill encryption | Batch encryption migration | | `encrypt-pii-fields.ts` | Backfill mã hóa | Migration mã hóa hàng loạt |
| `schema.prisma` | Database schema | User model, enums | | `schema.prisma` | Schema database | Model User, enum |
| `seed.ts` | Seed data | Current seeds (no passwords) | | `seed.ts` | Dữ liệu seed | Seed hiện tại (không có mật khẩu) |
--- ---
## 🚀 Deployment Checklist ## 🚀 Checklist Deployment
### Environment Variables Required ### Biến Môi Trường Bắt Buộc
- [ ] `BCRYPT_ROUNDS` (optional, default: 12) - [ ] `BCRYPT_ROUNDS` (tùy chọn, mặc định: 12)
- [ ] `FIELD_ENCRYPTION_KEY` (required for PII, hex string 64 chars) - [ ] `FIELD_ENCRYPTION_KEY` (bắt buộc cho PII, chuỗi hex 64 ký tự)
- [ ] `FIELD_ENCRYPTION_KEY_VERSION` (optional, default: 1) - [ ] `FIELD_ENCRYPTION_KEY_VERSION` (tùy chọn, mặc định: 1)
- [ ] `MFA_BACKUP_CODE_SECRET` (optional, fallback to JWT_SECRET) - [ ] `MFA_BACKUP_CODE_SECRET` (tùy chọn, fallback về JWT_SECRET)
- [ ] `JWT_SECRET` (required for tokens) - [ ] `JWT_SECRET` (bắt buộc cho token)
### Database Setup ### Cài Đặt Database
- [ ] Run migrations (including `add_mfa_totp_support`) - [ ] Chạy migration (bao gồm `add_mfa_totp_support`)
- [ ] Seed users with passwords (use provided script) - [ ] Seed user với mật khẩu (dùng script đã cung cấp)
- [ ] Test login functionality - [ ] Test chức năng đăng nhập
- [ ] Verify PII encryption working - [ ] Verify mã hóa PII hoạt động
### Testing ### Testing
- [ ] Test login with various phone formats (0900..., 84900..., +84900...) - [ ] Test đăng nhập với nhiều định dạng số điện thoại (0900..., 84900..., +84900...)
- [ ] Test invalid phone numbers (rejected) - [ ] Test số điện thoại không hợp lệ (bị từ chối)
- [ ] Test password validation (min 8 chars) - [ ] Test validate mật khẩu (tối thiểu 8 ký tự)
- [ ] Test email validation - [ ] Test validate email
- [ ] Test MFA setup and verification - [ ] Test setup và verify MFA
- [ ] Test backup code generation/usage - [ ] Test sinh/dùng backup code
- [ ] Verify hashes computed correctly - [ ] Verify hash được tính đúng
--- ---
## 📝 Current Seed Data Status ## 📝 Trạng Thái Dữ Liệu Seed Hiện Tại
### Existing Seed (prisma/seed.ts) ### Seed Hiện Có (prisma/seed.ts)
**Status:** ❌ **NOT login-capable** (no passwords) **Trạng thái:** ❌ **KHÔNG có khả năng đăng nhập** (không có mật khẩu)
```typescript ```typescript
// Current seed - users created without passwords // Seed hiện tại - user được tạo không có mật khẩu
const admin = await prisma.user.upsert({ const admin = await prisma.user.upsert({
where: { id: 'seed-user-admin' }, where: { id: 'seed-user-admin' },
create: { create: {
id: 'seed-user-admin', id: 'seed-user-admin',
phone: '0900000001', // NOT normalized/hashed phone: '0900000001', // CHƯA chuẩn hóa/hash
email: 'admin@goodgo.vn', email: 'admin@goodgo.vn',
fullName: 'Admin GoodGo', fullName: 'Admin GoodGo',
role: UserRole.ADMIN, role: UserRole.ADMIN,
// passwordHash: null ← Cannot login! // passwordHash: null ← Không thể đăng nhập!
}, },
}); });
``` ```
### Recommended Enhancement ### Cải Tiến Khuyến Nghị
Use `SEED_GENERATION_SCRIPT.ts` to create users with full auth capability. Dùng `SEED_GENERATION_SCRIPT.ts` để tạo user với khả năng auth đầy đủ.
--- ---
## 🔍 Troubleshooting ## 🔍 Troubleshooting
### User Can't Login ### User Không Đăng Nhập Được
1. Verify `passwordHash` is NOT null: `SELECT id, passwordHash FROM "User" WHERE id = 'user-id';` 1. Verify `passwordHash` KHÔNG null: `SELECT id, passwordHash FROM "User" WHERE id = 'user-id';`
2. Check `isActive = true` 2. Kiểm tra `isActive = true`
3. Verify phone is normalized to `+84...` format 3. Verify số điện thoại chuẩn hóa thành định dạng `+84...`
4. Test phone normalization function directly 4. Test trực tiếp hàm chuẩn hóa số điện thoại
### Phone Hash Mismatch ### Phone Hash Không Khớp
1. Verify `FIELD_ENCRYPTION_KEY` is same across deployments 1. Verify `FIELD_ENCRYPTION_KEY` giống nhau giữa các deployment
2. Check hash computation: `HMAC-SHA256(lowercased_phone, hmacKey)` 2. Kiểm tra cách tính hash: `HMAC-SHA256(lowercased_phone, hmacKey)`
3. HKDF derivation must use exact string: `"goodgo-field-hash"` 3. Dẫn xuất HKDF phải dùng đúng chuỗi: `"goodgo-field-hash"`
### MFA Not Working ### MFA Không Hoạt Động
1. Verify `MFA_BACKUP_CODE_SECRET` is set 1. Verify `MFA_BACKUP_CODE_SECRET` đã được set
2. Check TOTP secret is encrypted properly 2. Kiểm tra TOTP secret được mã hóa đúng cách
3. Test clock skew (±30s tolerance) 3. Test clock skew (dung sai ±30s)
### Encryption/Decryption Issues ### Vấn Đề Mã Hóa/Giải Mã
1. Verify key is exactly 32 bytes (64 hex chars) 1. Verify key đúng 32 byte (64 ký tự hex)
2. Check IV length (12 bytes) 2. Kiểm tra độ dài IV (12 byte)
3. Verify auth tag (16 bytes) 3. Verify auth tag (16 byte)
4. Ensure `enc:` prefix detection working 4. Đảm bảo phát hiện prefix `enc:` hoạt động
--- ---
## 📚 Additional Resources ## 📚 Tài Nguyên Bổ Sung
### External Documentation ### Tài Liệu Bên Ngoài
- **bcrypt:** https://github.com/kelektiv/node.bcrypt.js - **bcrypt:** https://github.com/kelektiv/node.bcrypt.js
- **otplib:** https://github.com/yeojz/otplib - **otplib:** https://github.com/yeojz/otplib
- **Prisma:** https://www.prisma.io/docs - **Prisma:** https://www.prisma.io/docs
- **NestJS:** https://docs.nestjs.com - **NestJS:** https://docs.nestjs.com
### Related Files ### File Liên Quan
- Registration flow: `register-user.handler.ts` - Luồng đăng ký: `register-user.handler.ts`
- Token generation: `token.service.ts` - Sinh token: `token.service.ts`
- JWT strategy: `jwt.strategy.ts` - JWT strategy: `jwt.strategy.ts`
- Refresh token: `refresh-token.handler.ts` - Refresh token: `refresh-token.handler.ts`
--- ---
**Last Updated:** April 12, 2026 **Cập nhật lần cuối:** 12 tháng 4, 2026
**Platform:** GoodGo Real Estate Platform **Platform:** GoodGo Real Estate Platform
**Status:** ✅ Production-Ready **Trạng thái:** ✅ Sẵn sàng Production

307
docs/load-testing/K6_LOAD_TESTING_GUIDE.md
View File

@@ -1,17 +1,17 @@
# GoodGo Platform API — K6 Load Testing Guide # GoodGo Platform API — Hướng Dẫn K6 Load Testing
## 🎯 Quick Summary ## 🎯 Tóm Tắt Nhanh
**Base URL**: `http://localhost:3001/api/v1` **Base URL**: `http://localhost:3001/api/v1`
**Node Version**: >= 22.0.0 **Phiên bản Node**: >= 22.0.0
**Testing Framework**: Playwright (E2E), Vitest (Unit) **Testing Framework**: Playwright (E2E), Vitest (Unit)
**No existing K6 or load testing setup found** **Chưa có thiết lập K6 hoặc load testing nào tồn tại**
--- ---
## 📋 Project Structure ## 📋 Cấu Trúc Dự Án
### Root Directory ### Thư Mục Gốc
``` ```
goodgo-platform/ goodgo-platform/
├── apps/api # NestJS backend (port 3001) ├── apps/api # NestJS backend (port 3001)
@@ -25,7 +25,7 @@ goodgo-platform/
└── playwright.config.ts # Playwright configuration └── playwright.config.ts # Playwright configuration
``` ```
### Key Scripts (package.json) ### Các Script Chính (package.json)
```bash ```bash
pnpm dev # Start all apps (API :3001, Web :3000) pnpm dev # Start all apps (API :3001, Web :3000)
pnpm test # Unit tests via Vitest (API only) pnpm test # Unit tests via Vitest (API only)
@@ -39,11 +39,11 @@ pnpm typecheck # TypeScript checking
--- ---
## 🏗️ API Module Structure ## 🏗️ Cấu Trúc Module API
### API Base Architecture: `apps/api/src/modules/` ### Kiến Trúc Cơ Sở API: `apps/api/src/modules/`
Each module follows DDD layers: `domain/` → `application/` → `infrastructure/` → `presentation/` Mỗi module tuân theo các tầng DDD: `domain/` → `application/` → `infrastructure/` → `presentation/`
``` ```
modules/ modules/
@@ -64,22 +64,22 @@ modules/
--- ---
## 🔐 AUTH MODULE ## 🔐 MODULE AUTH
### Controllers & Endpoints ### Controllers & Endpoints
#### File: `apps/api/src/modules/auth/presentation/controllers/auth.controller.ts` #### File: `apps/api/src/modules/auth/presentation/controllers/auth.controller.ts`
| Method | Endpoint | Rate Limit | Auth | Description | | Method | Endpoint | Rate Limit | Auth | Mô tả |
|--------|----------|-----------|------|-------------| |--------|----------|-----------|------|-------------|
| POST | `/auth/register` | 5/hour | No | Register new user | | POST | `/auth/register` | 5/giờ | Không | Đăng ký người dùng mới |
| POST | `/auth/login` | 5/hour | LocalAuth | Login with phone + password | | POST | `/auth/login` | 5/giờ | LocalAuth | Đăng nhập bằng số điện thoại + mật khẩu |
| POST | `/auth/refresh` | 5/hour | No | Refresh access token | | POST | `/auth/refresh` | 5/giờ | Không | Làm mới access token |
| POST | `/auth/logout` | No limit | No | Clear auth cookies | | POST | `/auth/logout` | Không giới hạn | Không | Xóa cookie xác thực |
| POST | `/auth/exchange-token` | No limit | No | Exchange OAuth tokens for cookies | | POST | `/auth/exchange-token` | Không giới hạn | Không | Đổi OAuth token lấy cookie |
| GET | `/auth/profile` | No limit | JWT | Get current user profile | | GET | `/auth/profile` | Không giới hạn | JWT | Lấy hồ sơ người dùng hiện tại |
| GET | `/auth/profile/agent` | No limit | JWT | Get agent profile for user | | GET | `/auth/profile/agent` | Không giới hạn | JWT | Lấy hồ sơ agent của người dùng |
| PATCH | `/auth/kyc` | No limit | JWT+Admin | Verify user KYC (admin only) | | PATCH | `/auth/kyc` | Không giới hạn | JWT+Admin | Xác minh KYC người dùng (chỉ admin) |
### DTOs ### DTOs
@@ -117,50 +117,50 @@ modules/
} }
``` ```
### Cookies & Authentication ### Cookies & Xác Thực
**Access Token**: **Access Token**:
- Cookie: `access_token` - Cookie: `access_token`
- Max Age: 15 minutes (900s) - Max Age: 15 phút (900s)
- HttpOnly: true - HttpOnly: true
- Secure: true (production only) - Secure: true (chỉ production)
- SameSite: strict - SameSite: strict
- Path: / - Path: /
**Refresh Token**: **Refresh Token**:
- Cookie: `refresh_token` - Cookie: `refresh_token`
- Max Age: 30 days - Max Age: 30 ngày
- HttpOnly: true - HttpOnly: true
- Secure: true (production only) - Secure: true (chỉ production)
- SameSite: strict - SameSite: strict
- Path: `/auth` - Path: `/auth`
**Session Indicator**: **Chỉ Báo Phiên**:
- Cookie: `goodgo_authenticated` = "1" - Cookie: `goodgo_authenticated` = "1"
- HttpOnly: false (visible to frontend) - HttpOnly: false (frontend nhìn thấy được)
### OAuth Support ### Hỗ Trợ OAuth
- Google OAuth 2.0 - Google OAuth 2.0
- Zalo OAuth (Vietnamese platform) - Zalo OAuth (nền tảng Việt Nam)
- Environment: `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `ZALO_APP_ID`, `ZALO_APP_SECRET` - Environment: `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `ZALO_APP_ID`, `ZALO_APP_SECRET`
--- ---
## 🏠 LISTINGS MODULE ## 🏠 MODULE LISTINGS
### Controllers & Endpoints ### Controllers & Endpoints
#### File: `apps/api/src/modules/listings/presentation/controllers/listings.controller.ts` #### File: `apps/api/src/modules/listings/presentation/controllers/listings.controller.ts`
| Method | Endpoint | Auth | Quota | Description | | Method | Endpoint | Auth | Quota | Mô tả |
|--------|----------|------|-------|-------------| |--------|----------|------|-------|-------------|
| POST | `/listings` | JWT | Yes | Create new listing | | POST | `/listings` | JWT | Có | Tạo listing mới |
| GET | `/listings` | No | No | Search/filter listings (public) | | GET | `/listings` | Không | Không | Tìm kiếm/lọc listing (công khai) |
| GET | `/listings/:id` | No | No | Get listing detail | | GET | `/listings/:id` | Không | Không | Lấy chi tiết listing |
| GET | `/listings/pending` | JWT+Admin | No | Get listings pending moderation | | GET | `/listings/pending` | JWT+Admin | Không | Lấy listing đang chờ kiểm duyệt |
| PATCH | `/listings/:id/status` | JWT | No | Update listing status | | PATCH | `/listings/:id/status` | JWT | Không | Cập nhật trạng thái listing |
| POST | `/listings/:id/media` | JWT | No | Upload photo/video | | POST | `/listings/:id/media` | JWT | Không | Tải lên ảnh/video |
| PATCH | `/listings/:id/moderate` | JWT+Admin | No | Moderate a listing (admin) | | PATCH | `/listings/:id/moderate` | JWT+Admin | Không | Kiểm duyệt listing (admin) |
### DTOs ### DTOs
@@ -233,10 +233,10 @@ modules/
} }
``` ```
### Response Structures ### Cấu Trúc Phản Hồi
#### ListingDetailData #### ListingDetailData
Contains full listing information including: Chứa thông tin đầy đủ về listing bao gồm:
- id, title, description - id, title, description
- propertyType, transactionType - propertyType, transactionType
- address, latitude, longitude, ward, district, city - address, latitude, longitude, ward, district, city
@@ -244,7 +244,7 @@ Contains full listing information including:
- areaM2, usableAreaM2, bedrooms, bathrooms, floors - areaM2, usableAreaM2, bedrooms, bathrooms, floors
- amenities, nearbyPOIs - amenities, nearbyPOIs
- legalStatus, yearBuilt, direction - legalStatus, yearBuilt, direction
- mediaUrls (photos/videos) - mediaUrls (ảnh/video)
- agentInfo - agentInfo
- createdAt, updatedAt - createdAt, updatedAt
@@ -261,19 +261,19 @@ Contains full listing information including:
--- ---
## 💳 PAYMENTS MODULE ## 💳 MODULE PAYMENTS
### Controllers & Endpoints ### Controllers & Endpoints
#### File: `apps/api/src/modules/payments/presentation/controllers/payments.controller.ts` #### File: `apps/api/src/modules/payments/presentation/controllers/payments.controller.ts`
| Method | Endpoint | Auth | Rate Limit | Description | | Method | Endpoint | Auth | Rate Limit | Mô tả |
|--------|----------|------|-----------|-------------| |--------|----------|------|-----------|-------------|
| POST | `/payments` | JWT | No | Create payment | | POST | `/payments` | JWT | Không | Tạo thanh toán |
| GET | `/payments` | JWT | No | List user transactions | | GET | `/payments` | JWT | Không | Liệt kê giao dịch của người dùng |
| GET | `/payments/:id` | JWT | No | Get payment status | | GET | `/payments/:id` | JWT | Không | Lấy trạng thái thanh toán |
| POST | `/payments/callback/:provider` | No | 20/min | Handle payment callback (webhook) | | POST | `/payments/callback/:provider` | Không | 20/phút | Xử lý callback thanh toán (webhook) |
| POST | `/payments/:id/refund` | JWT+Admin | No | Refund payment (admin) | | POST | `/payments/:id/refund` | JWT+Admin | Không | Hoàn tiền (admin) |
### DTOs ### DTOs
@@ -306,47 +306,47 @@ Contains full listing information including:
} }
``` ```
### Payment Providers ### Nhà Cung Cấp Thanh Toán
- **VNPay** (Primary for Vietnam) - **VNPay** (Chính cho Việt Nam)
- Environment: `VNPAY_TMN_CODE`, `VNPAY_HASH_SECRET` - Environment: `VNPAY_TMN_CODE`, `VNPAY_HASH_SECRET`
- Sandbox: `https://sandbox.vnpayment.vn/paymentv2/vpcpay.html` - Sandbox: `https://sandbox.vnpayment.vn/paymentv2/vpcpay.html`
- API: `https://sandbox.vnpayment.vn/merchant_webapi/api/transaction` - API: `https://sandbox.vnpayment.vn/merchant_webapi/api/transaction`
- **MoMo** (Mobile wallet) - **MoMo** (Ví di động)
- Environment: `MOMO_PARTNER_CODE`, `MOMO_ACCESS_KEY`, `MOMO_SECRET_KEY` - Environment: `MOMO_PARTNER_CODE`, `MOMO_ACCESS_KEY`, `MOMO_SECRET_KEY`
- Endpoint: `https://test-payment.momo.vn/v2/gateway/api` - Endpoint: `https://test-payment.momo.vn/v2/gateway/api`
- **ZaloPay** (Zalo integrated) - **ZaloPay** (Tích hợp Zalo)
- Environment: `ZALOPAY_APP_ID`, `ZALOPAY_KEY1`, `ZALOPAY_KEY2` - Environment: `ZALOPAY_APP_ID`, `ZALOPAY_KEY1`, `ZALOPAY_KEY2`
- Endpoint: `https://sb-openapi.zalopay.vn/v2` - Endpoint: `https://sb-openapi.zalopay.vn/v2`
### Callback Processing ### Xử Lý Callback
**Webhook URL Pattern**: `/payments/callback/{provider}` **Mẫu URL Webhook**: `/payments/callback/{provider}`
Supports both: Hỗ trợ cả:
- Query parameters (VNPay) - Query parameters (VNPay)
- Request body (MoMo, ZaloPay) - Request body (MoMo, ZaloPay)
- Merged data handling internally - Xử lý dữ liệu hợp nhất nội bộ
--- ---
## 🔍 SEARCH MODULE ## 🔍 MODULE SEARCH
### Controllers & Endpoints ### Controllers & Endpoints
#### File: `apps/api/src/modules/search/presentation/controllers/search.controller.ts` #### File: `apps/api/src/modules/search/presentation/controllers/search.controller.ts`
| Method | Endpoint | Auth | Description | | Method | Endpoint | Auth | Mô tả |
|--------|----------|------|-------------| |--------|----------|------|-------------|
| GET | `/search` | No | Full-text search (public) | | GET | `/search` | Không | Tìm kiếm full-text (công khai) |
| GET | `/search/geo` | No | Geographic radius search (public) | | GET | `/search/geo` | Không | Tìm kiếm theo bán kính địa lý (công khai) |
| POST | `/search/reindex` | JWT+Admin | Reindex all properties (admin) | | POST | `/search/reindex` | JWT+Admin | Lập chỉ mục lại tất cả bất động sản (admin) |
### DTOs ### DTOs
#### SearchPropertiesDto (Full-text search) #### SearchPropertiesDto (Tìm kiếm full-text)
```typescript ```typescript
{ {
q?: string, // Free-text query, e.g., 'chung cu quan 7' q?: string, // Free-text query, e.g., 'chung cu quan 7'
@@ -365,7 +365,7 @@ Supports both:
} }
``` ```
#### GeoSearchDto (Geographic search) #### GeoSearchDto (Tìm kiếm địa lý)
```typescript ```typescript
{ {
lat: number, // Latitude, -90 to 90 lat: number, // Latitude, -90 to 90
@@ -383,11 +383,11 @@ Supports both:
### Search Engine ### Search Engine
**Typesense** integration for fast full-text & faceted search Tích hợp **Typesense** cho tìm kiếm full-text & faceted nhanh
- Environment: `TYPESENSE_HOST`, `TYPESENSE_PORT`, `TYPESENSE_API_KEY` - Environment: `TYPESENSE_HOST`, `TYPESENSE_PORT`, `TYPESENSE_API_KEY`
- Default: `http://localhost:8108` - Mặc định: `http://localhost:8108`
### Response Structure ### Cấu Trúc Phản Hồi
#### SearchResult #### SearchResult
```typescript ```typescript
@@ -409,7 +409,7 @@ Supports both:
## 🗄️ Database & Environment ## 🗄️ Database & Environment
### PostgreSQL with PostGIS ### PostgreSQL với PostGIS
``` ```
DB_HOST=localhost DB_HOST=localhost
@@ -426,7 +426,7 @@ DATABASE_URL=postgresql://goodgo:password@localhost:5432/goodgo?schema=public
REDIS_URL=redis://localhost:6379 REDIS_URL=redis://localhost:6379
``` ```
### Key Environment Variables ### Các Biến Môi Trường Chính
```bash ```bash
# JWT Secrets (REQUIRED) # JWT Secrets (REQUIRED)
@@ -472,9 +472,9 @@ LOG_LEVEL=info
--- ---
## 🧪 Existing Test Setup ## 🧪 Thiết Lập Test Hiện Có
### Playwright Configuration ### Cấu Hình Playwright
**File**: `playwright.config.ts` **File**: `playwright.config.ts`
@@ -490,7 +490,7 @@ Projects:
baseURL: http://localhost:3000 baseURL: http://localhost:3000
``` ```
### Playwright Scripts ### Các Script Playwright
```bash ```bash
pnpm test:e2e # Run all E2E tests pnpm test:e2e # Run all E2E tests
@@ -499,14 +499,14 @@ pnpm test:e2e:web # Web tests only
pnpm test:e2e:report # Show HTML report pnpm test:e2e:report # Show HTML report
``` ```
### Test Database ### Database Test
- CI uses `goodgo_test` database - CI sử dụng database `goodgo_test`
- Local uses `.env.test` for test database URL - Local sử dụng `.env.test` cho URL database test
- Migrations & seed run in `global-setup.ts` - Migration & seed chạy trong `global-setup.ts`
- Cleanup in `global-teardown.ts` - Dọn dẹp trong `global-teardown.ts`
### Example E2E Test ### Ví Dụ E2E Test
**File**: `e2e/api/auth-register.spec.ts` **File**: `e2e/api/auth-register.spec.ts`
@@ -536,51 +536,51 @@ pnpm test:integration # Integration tests
--- ---
## 🔄 CI/CD Setup ## 🔄 Thiết Lập CI/CD
### GitHub Actions Workflows ### Workflow GitHub Actions
#### `ci.yml` - Lint → Typecheck → Test → Build #### `ci.yml` - Lint → Typecheck → Test → Build
- Runs on: `push main` and `pull_request` - Chạy khi: `push main` và `pull_request`
- Services: PostgreSQL 16 + PostGIS - Services: PostgreSQL 16 + PostGIS
- Steps: lint → typecheck → test → build - Các bước: lint → typecheck → test → build
#### `e2e.yml` - Playwright E2E Tests #### `e2e.yml` - Playwright E2E Tests
- Runs on: `push main` and `pull_request` - Chạy khi: `push main` và `pull_request`
- Services: - Services:
- PostgreSQL 16 + PostGIS - PostgreSQL 16 + PostGIS
- Redis 7 - Redis 7
- Typesense 27.1 - Typesense 27.1
- MinIO (S3-compatible storage) - MinIO (lưu trữ tương thích S3)
- Artifacts: HTML report + traces - Artifacts: HTML report + traces
#### `security.yml` - Code Security #### `security.yml` - Bảo Mật Mã Nguồn
- Dependency scanning - Quét dependency
- SAST analysis - Phân tích SAST
#### `deploy.yml` - Production Deployment #### `deploy.yml` - Triển Khai Production
- Docker builds - Build Docker
- Registry push - Push registry
- Deployment orchestration - Điều phối triển khai
--- ---
## 📊 Architecture Patterns ## 📊 Mẫu Kiến Trúc
### NestJS CQRS Pattern ### Mẫu CQRS NestJS
Each module uses: Mỗi module sử dụng:
- **Commands** (Write operations) - **Commands** (Thao tác ghi)
- `CommandBus.execute(command)` - `CommandBus.execute(command)`
- Located in `application/commands/` - Đặt trong `application/commands/`
- Handlers in `application/commands/{command}/` - Handlers trong `application/commands/{command}/`
- **Queries** (Read operations) - **Queries** (Thao tác đọc)
- `QueryBus.execute(query)` - `QueryBus.execute(query)`
- Located in `application/queries/` - Đặt trong `application/queries/`
- Handlers in `application/queries/{query}/` - Handlers trong `application/queries/{query}/`
Example: Ví dụ:
```typescript ```typescript
// In controller // In controller
const result = await this.commandBus.execute( const result = await this.commandBus.execute(
@@ -594,17 +594,17 @@ const profile = await this.queryBus.execute(
### Guards & Interceptors ### Guards & Interceptors
- `JwtAuthGuard` - Validates JWT token - `JwtAuthGuard` - Xác thực JWT token
- `LocalAuthGuard` - Email/password validation - `LocalAuthGuard` - Xác thực email/mật khẩu
- `RolesGuard` - Role-based access control - `RolesGuard` - Kiểm soát truy cập dựa trên vai trò
- `QuotaGuard` - Subscription quota enforcement - `QuotaGuard` - Thi hành hạn ngạch subscription
- `FileValidationPipe` - File upload validation - `FileValidationPipe` - Xác thực file upload
--- ---
## 🚀 Starting the API ## 🚀 Khởi Động API
### Local Development ### Phát Triển Cục Bộ
```bash ```bash
# Install dependencies # Install dependencies
@@ -627,7 +627,7 @@ pnpm dev
# Swagger UI: http://localhost:3001/api/v1/docs # Swagger UI: http://localhost:3001/api/v1/docs
``` ```
### With Docker ### Với Docker
```bash ```bash
docker-compose up docker-compose up
@@ -636,37 +636,37 @@ docker-compose up
--- ---
## 🎯 K6 Load Testing Recommendations ## 🎯 Khuyến Nghị K6 Load Testing
### Key Endpoints to Test ### Các Endpoint Chính Cần Test
1. **Authentication** (High priority) 1. **Authentication** (Ưu tiên cao)
- Register: `POST /auth/register` - Register: `POST /auth/register`
- Login: `POST /auth/login` - Login: `POST /auth/login`
- Refresh: `POST /auth/refresh` - Refresh: `POST /auth/refresh`
- Profile: `GET /auth/profile` (authenticated) - Profile: `GET /auth/profile` (đã xác thực)
2. **Listings** (High priority) 2. **Listings** (Ưu tiên cao)
- Create: `POST /listings` (quota-gated) - Create: `POST /listings` (giới hạn quota)
- Search: `GET /listings` (public, high volume) - Search: `GET /listings` (công khai, lưu lượng cao)
- Detail: `GET /listings/:id` (public, high volume) - Detail: `GET /listings/:id` (công khai, lưu lượng cao)
3. **Search** (High priority) 3. **Search** (Ưu tiên cao)
- Full-text: `GET /search?q=...` (public, high volume) - Full-text: `GET /search?q=...` (công khai, lưu lượng cao)
- Geo: `GET /search/geo?lat=...&lng=...` (public, high volume) - Geo: `GET /search/geo?lat=...&lng=...` (công khai, lưu lượng cao)
4. **Payments** (Medium priority) 4. **Payments** (Ưu tiên trung bình)
- Create: `POST /payments` (authenticated) - Create: `POST /payments` (đã xác thực)
- List: `GET /payments` (authenticated) - List: `GET /payments` (đã xác thực)
- Webhook: `POST /payments/callback/:provider` (unthrottled) - Webhook: `POST /payments/callback/:provider` (không giới hạn throttle)
5. **Admin Endpoints** (Medium priority, restricted) 5. **Endpoint Admin** (Ưu tiên trung bình, hạn chế)
- Moderate listings: `PATCH /listings/:id/moderate` - Kiểm duyệt listing: `PATCH /listings/:id/moderate`
- List pending: `GET /listings/pending` - Liệt kê pending: `GET /listings/pending`
- Verify KYC: `PATCH /auth/kyc` - Xác minh KYC: `PATCH /auth/kyc`
- Reindex: `POST /search/reindex` - Reindex: `POST /search/reindex`
### K6 Script Structure ### Cấu Trúc Script K6
```javascript ```javascript
import http from 'k6/http'; import http from 'k6/http';
@@ -692,16 +692,16 @@ export default function() {
} }
``` ```
### Data Generation Tips ### Mẹo Tạo Dữ Liệu
- Use test fixture users from Playwright tests - Sử dụng test fixture user từ Playwright tests
- Leverage Prisma seed data (districts, property types) - Tận dụng dữ liệu Prisma seed (quận, loại bất động sản)
- Generate realistic search queries - Tạo các truy vấn tìm kiếm thực tế
- Test with various geo coordinates (Ho Chi Minh City: ~10.77°N, 106.70°E) - Test với các tọa độ địa lý khác nhau (TP.HCM: ~10.77°N, 106.70°E)
--- ---
## 📁 File Locations Quick Reference ## 📁 Tham Khảo Nhanh Vị Trí File
``` ```
apps/api/ apps/api/
@@ -768,38 +768,37 @@ playwright.config.ts # Playwright config
--- ---
## 🔗 Useful Links & References ## 🔗 Liên Kết & Tham Khảo Hữu Ích
- **API Swagger Docs**: `http://localhost:3001/api/v1/docs` - **API Swagger Docs**: `http://localhost:3001/api/v1/docs`
- **Project Root Docs**: `CLAUDE.md` - **Tài Liệu Gốc Dự Án**: `CLAUDE.md`
- **Existing Analysis**: `CODEBASE_ANALYSIS.md`, `EXPLORATION_REPORT.md` - **Phân Tích Hiện Có**: `CODEBASE_ANALYSIS.md`, `EXPLORATION_REPORT.md`
- **Frontend Docs**: `docs/audits/FRONTEND_EXPLORATION.md` - **Tài Liệu Frontend**: `docs/audits/FRONTEND_EXPLORATION.md`
--- ---
## ✅ Summary for K6 Implementation ## ✅ Tóm Tắt Triển Khai K6
**No existing K6 setup** — you have a clean slate! **Chưa có thiết lập K6 nào** — bạn có một khởi đầu hoàn toàn mới!
**Key endpoints** identified across: **Các endpoint chính** được xác định trên các module:
- Auth (register, login, refresh, profile) - Auth (register, login, refresh, profile)
- Listings (create, search, detail, moderate) - Listings (create, search, detail, moderate)
- Search (full-text, geo) - Search (full-text, geo)
- Payments (create, callback, list, refund) - Payments (create, callback, list, refund)
- Admin (moderate, KYC, reindex) - Admin (moderate, KYC, reindex)
**Rate limits** to consider: **Rate limit** cần xem xét:
- Auth: 5/hour per endpoint - Auth: 5/giờ mỗi endpoint
- Payments callback: 20/min - Payments callback: 20/phút
- Others: No limit (except quota guards on create operations) - Khác: Không giới hạn (trừ quota guard cho thao tác create)
**Infrastructure ready**: **Hạ tầng sẵn sàng**:
- Turbo monorepo for dependency management - Turbo monorepo cho quản lý dependency
- PostgreSQL + PostGIS for spatial data - PostgreSQL + PostGIS cho dữ liệu không gian
- Typesense for search indexing - Typesense cho lập chỉ mục tìm kiếm
- Redis for caching - Redis cho caching
- MinIO for media storage - MinIO cho lưu trữ media
- Prometheus metrics endpoint - Endpoint Prometheus metrics
**Tests can be integrated** into CI/CD pipeline via `.github/workflows/` (suggested: new `load-test.yml`)
**Tests có thể được tích hợp** vào CI/CD pipeline qua `.github/workflows/` (đề xuất: `load-test.yml` mới)

110
docs/load-testing/K6_QUICK_START.md
View File

@@ -1,10 +1,10 @@
# K6 Load Testing — Quick Start Guide # K6 Load Testing — Hướng Dẫn Bắt Đầu Nhanh
Get started with K6 load tests for GoodGo Platform API in minutes. Bắt đầu với K6 load tests cho GoodGo Platform API trong vài phút.
--- ---
## 1️⃣ Installation ## 1️⃣ Cài Đặt
### macOS ### macOS
```bash ```bash
@@ -21,16 +21,16 @@ apt-get install k6
docker pull grafana/k6:latest docker pull grafana/k6:latest
``` ```
### Verify Installation ### Xác Minh Cài Đặt
```bash ```bash
k6 version k6 version
``` ```
--- ---
## 2️⃣ Setup Test Environment ## 2️⃣ Thiết Lập Môi Trường Test
### Start API & Database ### Khởi Động API & Database
```bash ```bash
# Terminal 1: Start all services # Terminal 1: Start all services
pnpm dev pnpm dev
@@ -39,7 +39,7 @@ pnpm dev
pnpm db:seed pnpm db:seed
``` ```
### Verify API is Running ### Xác Minh API Đang Chạy
```bash ```bash
curl http://localhost:3001/api/v1/docs curl http://localhost:3001/api/v1/docs
# Should return Swagger UI # Should return Swagger UI
@@ -47,11 +47,11 @@ curl http://localhost:3001/api/v1/docs
--- ---
## 3️⃣ Create Your First K6 Test ## 3️⃣ Tạo Test K6 Đầu Tiên
### Simple Search Load Test ### Search Load Test Đơn Giản
Create file: `load-tests/search.k6.js` Tạo file: `load-tests/search.k6.js`
```javascript ```javascript
import http from 'k6/http'; import http from 'k6/http';
@@ -101,19 +101,19 @@ export default function() {
--- ---
## 4️⃣ Run Your First Test ## 4️⃣ Chạy Test Đầu Tiên
### Local Development ### Phát Triển Cục Bộ
```bash ```bash
k6 run load-tests/search.k6.js k6 run load-tests/search.k6.js
``` ```
### With Custom Base URL ### Với Base URL Tùy Chỉnh
```bash ```bash
BASE_URL=http://localhost:3001/api/v1 k6 run load-tests/search.k6.js BASE_URL=http://localhost:3001/api/v1 k6 run load-tests/search.k6.js
``` ```
### With Docker ### Với Docker
```bash ```bash
docker run -i grafana/k6 run - < load-tests/search.k6.js docker run -i grafana/k6 run - < load-tests/search.k6.js
``` ```
@@ -145,9 +145,9 @@ docker run -i grafana/k6 run - < load-tests/search.k6.js
--- ---
## 5️⃣ Authentication Test ## 5️⃣ Test Authentication
Create file: `load-tests/auth.k6.js` Tạo file: `load-tests/auth.k6.js`
```javascript ```javascript
import http from 'k6/http'; import http from 'k6/http';
@@ -212,16 +212,16 @@ export default function() {
} }
``` ```
### Run Auth Test ### Chạy Auth Test
```bash ```bash
k6 run load-tests/auth.k6.js k6 run load-tests/auth.k6.js
``` ```
--- ---
## 6️⃣ Listing Creation Test (Authenticated) ## 6️⃣ Test Tạo Listing (Đã Xác Thực)
Create file: `load-tests/listings.k6.js` Tạo file: `load-tests/listings.k6.js`
```javascript ```javascript
import http from 'k6/http'; import http from 'k6/http';
@@ -319,16 +319,16 @@ export default function() {
} }
``` ```
### Run Listing Test ### Chạy Listing Test
```bash ```bash
k6 run load-tests/listings.k6.js k6 run load-tests/listings.k6.js
``` ```
--- ---
## 7️⃣ Payment Test ## 7️⃣ Test Payment
Create file: `load-tests/payments.k6.js` Tạo file: `load-tests/payments.k6.js`
```javascript ```javascript
import http from 'k6/http'; import http from 'k6/http';
@@ -404,16 +404,16 @@ export default function() {
} }
``` ```
### Run Payment Test ### Chạy Payment Test
```bash ```bash
k6 run load-tests/payments.k6.js k6 run load-tests/payments.k6.js
``` ```
--- ---
## 8️⃣ Run All Tests with Results ## 8️⃣ Chạy Tất Cả Tests Với Kết Quả
Create file: `load-tests/all-scenarios.k6.js` Tạo file: `load-tests/all-scenarios.k6.js`
```javascript ```javascript
import http from 'k6/http'; import http from 'k6/http';
@@ -472,7 +472,7 @@ export default function() {
} }
``` ```
### Run with Summary ### Chạy Với Tóm Tắt
```bash ```bash
k6 run load-tests/all-scenarios.k6.js \ k6 run load-tests/all-scenarios.k6.js \
--vus=50 \ --vus=50 \
@@ -482,21 +482,21 @@ k6 run load-tests/all-scenarios.k6.js \
--- ---
## 9️⃣ Generate Reports ## 9️⃣ Tạo Báo Cáo
### JSON Report ### Báo Cáo JSON
```bash ```bash
k6 run load-tests/search.k6.js --summary-export=report.json k6 run load-tests/search.k6.js --summary-export=report.json
``` ```
### Upload to Grafana Cloud ### Tải Lên Grafana Cloud
```bash ```bash
k6 run load-tests/search.k6.js \ k6 run load-tests/search.k6.js \
--out cloud --out cloud
# Requires: k6 login or K6_CLOUD_TOKEN env var # Requires: k6 login or K6_CLOUD_TOKEN env var
``` ```
### Generate HTML Report (with extension) ### Tạo Báo Cáo HTML (với extension)
```bash ```bash
k6 run load-tests/search.k6.js \ k6 run load-tests/search.k6.js \
--out csv=results.csv --out csv=results.csv
@@ -504,9 +504,9 @@ k6 run load-tests/search.k6.js \
--- ---
## 🔟 CI Integration ## 🔟 Tích Hợp CI
Create: `.github/workflows/load-test.yml` Tạo: `.github/workflows/load-test.yml`
```yaml ```yaml
name: Load Tests name: Load Tests
@@ -576,7 +576,7 @@ jobs:
--- ---
## 📊 Common K6 Checks ## 📊 Các Check K6 Phổ Biến
```javascript ```javascript
// HTTP Status // HTTP Status
@@ -605,55 +605,55 @@ check(res, {
--- ---
## 🛠️ Debugging ## 🛠️ Debug
### Verbose Output ### Output Chi Tiết
```bash ```bash
k6 run -v load-tests/search.k6.js k6 run -v load-tests/search.k6.js
``` ```
### Show Request/Response ### Hiển Thị Request/Response
```bash ```bash
k6 run --http-debug=full load-tests/search.k6.js k6 run --http-debug=full load-tests/search.k6.js
``` ```
### Limit to Single VU ### Giới Hạn Một VU
```bash ```bash
k6 run --vus=1 --iterations=1 load-tests/search.k6.js k6 run --vus=1 --iterations=1 load-tests/search.k6.js
``` ```
--- ---
## 📚 Next Steps ## 📚 Bước Tiếp Theo
1. **Read Full Guide**: `K6_LOAD_TESTING_GUIDE.md` 1. **Đọc Hướng Dẫn Đầy Đủ**: `K6_LOAD_TESTING_GUIDE.md`
2. **Check Endpoints**: `K6_ENDPOINTS_SUMMARY.md` 2. **Kiểm Tra Endpoint**: `K6_ENDPOINTS_SUMMARY.md`
3. **Explore K6 Docs**: https://k6.io/docs 3. **Khám Phá Tài Liệu K6**: https://k6.io/docs
4. **Community Scripts**: https://github.com/grafana/k6-templates 4. **Script Cộng Đồng**: https://github.com/grafana/k6-templates
--- ---
## ✅ Troubleshooting ## ✅ Xử Lý Sự Cố
### "connection refused" ### "connection refused"
- Ensure API is running: `pnpm dev` - Đảm bảo API đang chạy: `pnpm dev`
- Check port: 3001 - Kiểm tra port: 3001
- Verify BASE_URL: `http://localhost:3001/api/v1` - Xác minh BASE_URL: `http://localhost:3001/api/v1`
### "rate limit exceeded" ### "rate limit exceeded"
- Auth endpoints: 5/hour limit - Endpoint auth: giới hạn 5/giờ
- Spread requests or use different test data - Phân tán request hoặc dùng dữ liệu test khác
- Check test database has seed data - Kiểm tra database test có dữ liệu seed
### "insufficient credits" (payments) ### "insufficient credits" (payments)
- Payments require authenticated user - Payment yêu cầu người dùng đã xác thực
- Create user session first in test - Tạo phiên người dùng trước trong test
- Use test provider credentials - Sử dụng thông tin xác thực provider test
### "timeout" ### "timeout"
- Increase K6 timeout in options - Tăng K6 timeout trong options
- Check API logs for errors - Kiểm tra log API để tìm lỗi
- Reduce number of VUs initially - Giảm số lượng VU ban đầu
--- ---

371
docs/load-testing/K6_README.md
View File

@@ -1,75 +1,75 @@
# K6 Load Testing Documentation for GoodGo Platform # Tài Liệu K6 Load Testing cho GoodGo Platform
Complete guide to understanding and implementing K6 load tests for the GoodGo Platform API. Hướng dẫn đầy đủ để hiểu và triển khai K6 load tests cho GoodGo Platform API.
--- ---
## 📚 Documentation Files ## 📚 Các File Tài Liệu
This directory contains three comprehensive guides for K6 load testing: 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** (Primary Reference) ### 1. **K6_LOAD_TESTING_GUIDE.md** (Tham Khảo Chính)
Comprehensive exploration of the GoodGo Platform API structure for load testing. Khám phá toàn diện cấu trúc GoodGo Platform API cho load testing.
**Contents:** **Nội dung:**
- API module structure (auth, listings, payments, search) - Cấu trúc module API (auth, listings, payments, search)
- Detailed endpoint documentation with HTTP methods, rate limits, and auth requirements - Tài liệu endpoint chi tiết với HTTP method, rate limit và yêu cầu auth
- Complete DTO specifications with request/response body shapes - Đặc tả DTO đầy đủ với hình dạng request/response body
- Database and environment configuration reference - Tham khảo cấu hình database và environment
- Existing test setup (Playwright, Vitest, CI/CD) - Thiết lập test hiện có (Playwright, Vitest, CI/CD)
- Architecture patterns (CQRS, DDD) - Mẫu kiến trúc (CQRS, DDD)
- File location quick reference - Tham khảo nhanh vị trí file
- K6 implementation recommendations - Khuyến nghị triển khai K6
**When to use:** Deep dives into specific endpoints, understanding authentication flows, checking environment variables **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** (Quick Reference) ### 2. **K6_ENDPOINTS_SUMMARY.md** (Tham Khảo Nhanh)
Condensed endpoint reference with data shapes for immediate lookup. Tham khảo endpoint cô đọng với hình dạng dữ liệu để tra cứu ngay lập tức.
**Contents:** **Nội dung:**
- All endpoints in table format (method, path, auth, rate limit) - Tất cả endpoint dưới dạng bảng (method, path, auth, rate limit)
- Authentication module (register, login, refresh, profile) - Module Authentication (register, login, refresh, profile)
- Listings module (CRUD, moderation, media upload) - Module Listings (CRUD, kiểm duyệt, upload media)
- Payments module (create, list, callbacks, refund) - Module Payments (create, list, callback, refund)
- Search module (full-text, geo) - Module Search (full-text, geo)
- Request/response body examples (JSON) - Ví dụ request/response body (JSON)
- K6 test scenarios (search, auth, listings, payments, webhooks) - Các kịch bản test K6 (search, auth, listings, payments, webhook)
- Rate limits summary - Tóm tắt rate limit
- Authentication flow examples (cookies vs tokens) - Ví dụ luồng xác thực (cookies vs tokens)
**When to use:** Quick lookup of endpoint details, copy-paste example payloads, understanding rate limits **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** (Executable Examples) ### 3. **K6_QUICK_START.md** (Ví Dụ Chạy Được)
Step-by-step guide with ready-to-run K6 scripts and setup instructions. 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.
**Contents:** **Nội dung:**
- Installation instructions (macOS, Linux, Docker) - Hướng dẫn cài đặt (macOS, Linux, Docker)
- Environment setup (starting API, seeding database) - Thiết lập môi trường (khởi động API, seed database)
- Five runnable K6 scripts: - Năm script K6 chạy được:
- Search load test (public, high volume) - Search load test (công khai, lưu lượng cao)
- Auth load test (rate-limited registration) - Auth load test (đăng ký bị giới hạn rate)
- Listing creation (authenticated, quota-gated) - Tạo listing (đã xác thực, giới hạn quota)
- Payment processing (authenticated) - Xử lý payment (đã xác thực)
- All scenarios combined - Tất cả kịch bản kết hợp
- CI integration with GitHub Actions - Tích hợp CI với GitHub Actions
- Report generation options (JSON, Grafana Cloud, CSV) - Tùy chọn tạo báo cáo (JSON, Grafana Cloud, CSV)
- Common K6 checks and patterns - Các check K6 và mẫu phổ biến
- Debugging and troubleshooting - Debug và xử lý sự cố
**When to use:** Getting started quickly, running tests immediately, setting up CI/CD **Khi nào sử dụng:** Bắt đầu nhanh, chạy test ngay, thiết lập CI/CD
--- ---
## 🚀 Quick Start (3 Minutes) ## 🚀 Bắt Đầu Nhanh (3 Phút)
### 1. Install K6 ### 1. Cài Đặt K6
```bash ```bash
brew install k6 # macOS brew install k6 # macOS
# or # or
apt-get install k6 # Linux apt-get install k6 # Linux
``` ```
### 2. Start API & Database ### 2. Khởi Động API & Database
```bash ```bash
pnpm install pnpm install
pnpm db:generate pnpm db:generate
@@ -78,39 +78,39 @@ pnpm db:seed
pnpm dev pnpm dev
``` ```
### 3. Run a Load Test ### 3. Chạy Load Test
```bash ```bash
# Copy this from K6_QUICK_START.md Step 3 # Copy this from K6_QUICK_START.md Step 3
k6 run load-tests/search.k6.js k6 run load-tests/search.k6.js
``` ```
### 4. View Results ### 4. Xem Kết Quả
K6 prints a summary to console. For more detailed reports, see K6_QUICK_START.md section on report generation. 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.
--- ---
## 📊 Test Scenarios Implemented ## 📊 Các Kịch Bản Test Đã Triển Khai
| Scenario | File | Focus | VUs | Duration | Key Endpoints | | Kịch Bản | File | Trọng Tâm | VUs | Thời Lượng | Endpoint Chính |
|----------|------|-------|-----|----------|--------------| |----------|------|-------|-----|----------|--------------|
| Search Load | `load-tests/search.k6.js` | Public search performance | 50 | 4m | `GET /search`, `GET /search/geo` | | 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` | Auth throughput & rate limits | 10 | 2m | `POST /auth/register`, `POST /auth/login` | | Authentication | `load-tests/auth.k6.js` | Throughput auth & rate limit | 10 | 2m | `POST /auth/register`, `POST /auth/login` |
| Listing Creation | `load-tests/listings.k6.js` | Authenticated listing CRUD | 5 | 2m | `POST /listings`, `GET /listings/:id` | | 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` | Payment initiation & status | 10 | 2m | `POST /payments`, `GET /payments/: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` | Realistic mixed load | 50 | 5m | Multiple endpoints | | Combined | `load-tests/all-scenarios.k6.js` | Tải hỗn hợp thực tế | 50 | 5m | Nhiều endpoint |
--- ---
## 🔐 Authentication Methods ## 🔐 Phương Thức Xác Thực
### Option 1: Cookie-Based (Recommended for Browser-Like Tests) ### Tùy Chọn 1: Dựa Trên Cookie (Khuyến nghị cho test giống trình duyệt)
```javascript ```javascript
const loginRes = http.post(`${BASE_URL}/auth/login`, { phone, password }); const loginRes = http.post(`${BASE_URL}/auth/login`, { phone, password });
// Cookies automatically managed by K6 // Cookies automatically managed by K6
const profileRes = http.get(`${BASE_URL}/auth/profile`); const profileRes = http.get(`${BASE_URL}/auth/profile`);
``` ```
### Option 2: Bearer Token (Recommended for API-Only Tests) ### Tùy Chọn 2: Bearer Token (Khuyến nghị cho test chỉ API)
```javascript ```javascript
const loginRes = http.post(`${BASE_URL}/auth/login`, { phone, password }); const loginRes = http.post(`${BASE_URL}/auth/login`, { phone, password });
const { accessToken } = loginRes.json(); const { accessToken } = loginRes.json();
@@ -118,40 +118,40 @@ const headers = { Authorization: `Bearer ${accessToken}` };
const profileRes = http.get(`${BASE_URL}/auth/profile`, { headers }); const profileRes = http.get(`${BASE_URL}/auth/profile`, { headers });
``` ```
See K6_ENDPOINTS_SUMMARY.md for full examples. Xem K6_ENDPOINTS_SUMMARY.md để xem ví dụ đầy đủ.
--- ---
## 🎯 Key Endpoints by Priority ## 🎯 Endpoint Chính Theo Mức Ưu Tiên
### High Priority (Core Functionality) ### Ưu Tiên Cao (Chức Năng Cốt Lõi)
| Endpoint | Priority | Why | | Endpoint | Ưu Tiên | Tại sao |
|----------|----------|-----| |----------|----------|-----|
| `GET /search` | ⭐⭐⭐ | Public, high-volume query | | `GET /search` | ⭐⭐⭐ | Công khai, truy vấn lưu lượng cao |
| `GET /search/geo` | ⭐⭐⭐ | Geospatial, frequently used | | `GET /search/geo` | ⭐⭐⭐ | Địa không gian, dùng thường xuyên |
| `GET /listings` | ⭐⭐⭐ | Public search/filter | | `GET /listings` | ⭐⭐⭐ | Tìm/lọc công khai |
| `GET /listings/:id` | ⭐⭐⭐ | Detail page load | | `GET /listings/:id` | ⭐⭐⭐ | Tải trang chi tiết |
| `POST /auth/login` | ⭐⭐ | User session creation | | `POST /auth/login` | ⭐⭐ | Tạo phiên người dùng |
| `POST /auth/register` | ⭐⭐ | Rate-limited, important | | `POST /auth/register` | ⭐⭐ | Bị giới hạn rate, quan trọng |
### Medium Priority (Feature-Specific) ### Ưu Tiên Trung Bình (Tính Năng Cụ Thể)
| Endpoint | Priority | Why | | Endpoint | Ưu Tiên | Tại sao |
|----------|----------|-----| |----------|----------|-----|
| `POST /listings` | ⭐⭐ | Quota-gated, authenticated | | `POST /listings` | ⭐⭐ | Bị giới hạn quota, đã xác thực |
| `POST /payments` | ⭐⭐ | External integrations | | `POST /payments` | ⭐⭐ | Tích hợp bên ngoài |
| `GET /payments` | ⭐⭐ | User transaction history | | `GET /payments` | ⭐⭐ | Lịch sử giao dịch người dùng |
| `POST /payments/callback/:provider` | ⭐⭐ | Webhook handler, critical | | `POST /payments/callback/:provider` | ⭐⭐ | Webhook handler, then chốt |
### Low Priority (Admin/Specialized) ### Ưu Tiên Thấp (Admin/Chuyên Biệt)
| Endpoint | Priority | Why | | Endpoint | Ưu Tiên | Tại sao |
|----------|----------|-----| |----------|----------|-----|
| `PATCH /listings/:id/moderate` | ⭐ | Admin-only | | `PATCH /listings/:id/moderate` | ⭐ | Chỉ admin |
| `GET /listings/pending` | ⭐ | Admin-only | | `GET /listings/pending` | ⭐ | Chỉ admin |
| `POST /search/reindex` | ⭐ | Admin-only, scheduled | | `POST /search/reindex` | ⭐ | Chỉ admin, có lịch |
--- ---
## 📍 API Structure at a Glance ## 📍 Tổng Quan Cấu Trúc API
``` ```
API Base: http://localhost:3001/api/v1 API Base: http://localhost:3001/api/v1
@@ -168,9 +168,9 @@ Modules:
--- ---
## 🗄️ Database Configuration ## 🗄️ Cấu Hình Database
### Local Development ### Phát Triển Cục Bộ
```bash ```bash
DATABASE_URL=postgresql://goodgo:password@localhost:5432/goodgo DATABASE_URL=postgresql://goodgo:password@localhost:5432/goodgo
REDIS_URL=redis://localhost:6379 REDIS_URL=redis://localhost:6379
@@ -178,7 +178,7 @@ TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108 TYPESENSE_PORT=8108
``` ```
### Test Environment (CI) ### Môi Trường Test (CI)
```bash ```bash
DATABASE_URL=postgresql://goodgo:goodgo_test_secret@localhost:5432/goodgo_test DATABASE_URL=postgresql://goodgo:goodgo_test_secret@localhost:5432/goodgo_test
REDIS_URL=redis://localhost:6379 REDIS_URL=redis://localhost:6379
@@ -186,23 +186,23 @@ TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108 TYPESENSE_PORT=8108
``` ```
See K6_LOAD_TESTING_GUIDE.md for full environment variables. Xem K6_LOAD_TESTING_GUIDE.md để biết đầy đủ biến môi trường.
--- ---
## ⚡ Rate Limits ## ⚡ Rate Limit
Respect these limits in your load tests: Tôn trọng các giới hạn này trong load test của bạn:
| Endpoint | Limit | Window | Action on Exceeded | | Endpoint | Limit | Cửa Sổ | Hành Động Khi Vượt |
|----------|-------|--------|-------------------| |----------|-------|--------|-------------------|
| `/auth/register` | 5 | per hour | Returns 429 | | `/auth/register` | 5 | mỗi giờ | Trả về 429 |
| `/auth/login` | 5 | per hour | Returns 429 | | `/auth/login` | 5 | mỗi giờ | Trả về 429 |
| `/auth/refresh` | 5 | per hour | Returns 429 | | `/auth/refresh` | 5 | mỗi giờ | Trả về 429 |
| `/payments/callback/*` | 20 | per minute | Returns 429 | | `/payments/callback/*` | 20 | mỗi phút | Trả về 429 |
| All others | None | N/A | Quota gates apply for writes | | Tất cả khác | Không có | N/A | Quota gate áp dụng cho thao tác ghi |
**K6 Handling:** **Xử Lý K6:**
```javascript ```javascript
check(res, { check(res, {
'status not rate limited': (r) => r.status !== 429, 'status not rate limited': (r) => r.status !== 429,
@@ -212,7 +212,7 @@ check(res, {
--- ---
## 🏗️ Recommended Test Structure ## 🏗️ Cấu Trúc Test Đề Xuất
``` ```
load-tests/ load-tests/
@@ -228,24 +228,24 @@ load-tests/
└── config.js # Base URL, env, thresholds └── config.js # Base URL, env, thresholds
``` ```
Example helper structure provided in K6_QUICK_START.md. Cấu trúc helper mẫu được cung cấp trong K6_QUICK_START.md.
--- ---
## 🧪 Integration with Existing Tests ## 🧪 Tích Hợp Với Các Test Hiện Có
### Complement, Don't Replace ### Bổ Sung, Không Thay Thế
K6 is for **load testing** (performance under concurrent load). K6 dành cho **load testing** (hiệu suất dưới tải đồng thời).
Existing tests serve different purposes: Các test hiện có phục vụ các mục đích khác:
| Test Type | Tool | Purpose | When | | Loại Test | Công Cụ | Mục Đích | Khi Nào |
|-----------|------|---------|------| |-----------|------|---------|------|
| Unit Tests | Vitest | Verify function logic | During development | | Unit Tests | Vitest | Xác minh logic hàm | Trong quá trình phát triển |
| E2E Tests | Playwright | Verify user flows work | Before deployment | | E2E Tests | Playwright | Xác minh luồng người dùng hoạt động | Trước khi triển khai |
| Load Tests | K6 | Verify performance at scale | Scheduled, on-demand | | Load Tests | K6 | Xác minh hiệu suất ở quy mô lớn | Theo lịch, theo yêu cầu |
### Running All Tests ### Chạy Tất Cả Test
```bash ```bash
# Unit tests (API only) # Unit tests (API only)
@@ -263,11 +263,11 @@ pnpm test && pnpm test:e2e && k6 run load-tests/all-scenarios.k6.js
--- ---
## 📈 CI/CD Integration ## 📈 Tích Hợp CI/CD
### GitHub Actions Workflow ### Workflow GitHub Actions
Create `.github/workflows/load-test.yml` (template in K6_QUICK_START.md section 🔟): Tạo `.github/workflows/load-test.yml` (mẫu trong K6_QUICK_START.md mục 🔟):
```bash ```bash
# Runs on schedule (daily at 2 AM) # Runs on schedule (daily at 2 AM)
@@ -275,7 +275,7 @@ Create `.github/workflows/load-test.yml` (template in K6_QUICK_START.md section
# Reports results as artifacts # Reports results as artifacts
``` ```
### Manual Reporting ### Báo Cáo Thủ Công
```bash ```bash
# Export JSON # Export JSON
@@ -290,74 +290,74 @@ K6_CLOUD_TOKEN=xxx k6 run load-tests/search.k6.js --out cloud
--- ---
## 🔗 Cross-Reference Guide ## 🔗 Hướng Dẫn Tham Chiếu Chéo
### Looking for...? ### Đang tìm kiếm...?
| Need | Find in | | Cần | Tìm trong |
|------|----------| |------|----------|
| All endpoint URLs & methods | K6_ENDPOINTS_SUMMARY.md | | Tất cả URL & method endpoint | K6_ENDPOINTS_SUMMARY.md |
| Request/response JSON shapes | K6_ENDPOINTS_SUMMARY.md (📊 Key Data Shapes) | | Hình dạng JSON request/response | K6_ENDPOINTS_SUMMARY.md (📊 Key Data Shapes) |
| DTOs & validation rules | K6_LOAD_TESTING_GUIDE.md (Controllers & DTOs) | | DTO & quy tắc validation | K6_LOAD_TESTING_GUIDE.md (Controllers & DTOs) |
| Rate limit specifics | K6_ENDPOINTS_SUMMARY.md (📌 Important Rate Limits) | | Chi tiết rate limit | K6_ENDPOINTS_SUMMARY.md (📌 Important Rate Limits) |
| Authentication flows | K6_ENDPOINTS_SUMMARY.md (🔗 Authentication Flow for K6) | | Luồng xác thực | K6_ENDPOINTS_SUMMARY.md (🔗 Authentication Flow for K6) |
| Database variables | K6_LOAD_TESTING_GUIDE.md (🗄️ Database & Environment) | | Biến database | K6_LOAD_TESTING_GUIDE.md (🗄️ Database & Environment) |
| Ready-to-run scripts | K6_QUICK_START.md (Steps 3-8️⃣) | | Script sẵn sàng chạy | K6_QUICK_START.md (Steps 3-8️⃣) |
| CI/CD setup | K6_QUICK_START.md (Step 🔟) | | Thiết lập CI/CD | K6_QUICK_START.md (Step 🔟) |
| Troubleshooting | K6_QUICK_START.md (✅ Troubleshooting) | | Xử lý sự cố | K6_QUICK_START.md (✅ Troubleshooting) |
| Architecture details | K6_LOAD_TESTING_GUIDE.md (📊 Architecture Patterns) | | Chi tiết kiến trúc | K6_LOAD_TESTING_GUIDE.md (📊 Architecture Patterns) |
| File locations | K6_LOAD_TESTING_GUIDE.md (📁 File Locations Quick Reference) | | Vị trí file | K6_LOAD_TESTING_GUIDE.md (📁 File Locations Quick Reference) |
--- ---
## 🛠️ Common Tasks ## 🛠️ Công Việc Phổ Biến
### Task: Load Test Search Endpoint ### Công Việc: Load Test Endpoint Search
1. Read: K6_ENDPOINTS_SUMMARY.md (🔍 Search section) 1. Đọc: K6_ENDPOINTS_SUMMARY.md (mục 🔍 Search)
2. Use: K6_QUICK_START.md (Step 3️⃣ - Search Load Test) 2. Sử dụng: K6_QUICK_START.md (Bước 3️⃣ - Search Load Test)
3. Run: `k6 run load-tests/search.k6.js` 3. Chạy: `k6 run load-tests/search.k6.js`
### Task: Understand Payment Flow ### Công Việc: Hiểu Luồng Payment
1. Read: K6_LOAD_TESTING_GUIDE.md (💳 PAYMENTS MODULE) 1. Đọc: K6_LOAD_TESTING_GUIDE.md (💳 PAYMENTS MODULE)
2. Check: K6_ENDPOINTS_SUMMARY.md (💳 Payments section) 2. Kiểm tra: K6_ENDPOINTS_SUMMARY.md (mục 💳 Payments)
3. Use: K6_QUICK_START.md (Step 7️⃣ - Payment Test) 3. Sử dụng: K6_QUICK_START.md (Bước 7️⃣ - Payment Test)
### Task: Add New Endpoint to Load Tests ### Công Việc: Thêm Endpoint Mới Vào Load Tests
1. Find endpoint in: K6_LOAD_TESTING_GUIDE.md or K6_ENDPOINTS_SUMMARY.md 1. Tìm endpoint trong: K6_LOAD_TESTING_GUIDE.md hoặc K6_ENDPOINTS_SUMMARY.md
2. Get data shape from: K6_ENDPOINTS_SUMMARY.md (📊 Key Data Shapes) 2. Lấy hình dạng dữ liệu từ: K6_ENDPOINTS_SUMMARY.md (📊 Key Data Shapes)
3. Check auth from: K6_LOAD_TESTING_GUIDE.md (each module section) 3. Kiểm tra auth từ: K6_LOAD_TESTING_GUIDE.md (mỗi mục module)
4. Implement using examples in: K6_QUICK_START.md 4. Triển khai sử dụng ví dụ trong: K6_QUICK_START.md
--- ---
## ✅ Verification Checklist ## ✅ Danh Sách Kiểm Tra Xác Minh
Before running load tests, verify: Trước khi chạy load test, hãy xác minh:
- [ ] API running: `pnpm dev` (port 3001) - [ ] API đang chạy: `pnpm dev` (port 3001)
- [ ] Database seeded: `pnpm db:seed` - [ ] Database đã seed: `pnpm db:seed`
- [ ] K6 installed: `k6 version` - [ ] K6 đã cài đặt: `k6 version`
- [ ] Can reach API: `curl http://localhost:3001/api/v1/docs` - [ ] Có thể truy cập API: `curl http://localhost:3001/api/v1/docs`
- [ ] ENV variables set: `JWT_SECRET`, `CORS_ORIGINS`, etc. - [ ] Biến ENV đã set: `JWT_SECRET`, `CORS_ORIGINS`, v.v.
- [ ] Load test file exists: `load-tests/*.k6.js` - [ ] File load test tồn tại: `load-tests/*.k6.js`
- [ ] Test data available: Check seed in `prisma/seed.ts` - [ ] Có sẵn dữ liệu test: Kiểm tra seed trong `prisma/seed.ts`
--- ---
## 📞 Support & References ## 📞 Hỗ Trợ & Tham Khảo
### Internal Documentation ### Tài Liệu Nội Bộ
- **Full Architecture**: K6_LOAD_TESTING_GUIDE.md - **Kiến Trúc Đầy Đủ**: K6_LOAD_TESTING_GUIDE.md
- **Endpoint Reference**: K6_ENDPOINTS_SUMMARY.md - **Tham Khảo Endpoint**: K6_ENDPOINTS_SUMMARY.md
- **Getting Started**: K6_QUICK_START.md - **Bắt Đầu**: K6_QUICK_START.md
### External Resources ### Tài Nguyên Bên Ngoài
- **K6 Official Docs**: https://k6.io/docs - **Tài Liệu Chính Thức K6**: https://k6.io/docs
- **K6 API Reference**: https://k6.io/docs/javascript-api - **Tham Khảo K6 API**: https://k6.io/docs/javascript-api
- **K6 Community**: https://community.k6.io - **Cộng Đồng K6**: https://community.k6.io
- **K6 Examples**: https://github.com/grafana/k6-templates - **Ví Dụ K6**: https://github.com/grafana/k6-templates
### Project Files ### File Dự Án
- **API Controllers**: `apps/api/src/modules/*/presentation/controllers/` - **API Controllers**: `apps/api/src/modules/*/presentation/controllers/`
- **DTOs**: `apps/api/src/modules/*/presentation/dto/` - **DTOs**: `apps/api/src/modules/*/presentation/dto/`
- **E2E Tests**: `e2e/api/` - **E2E Tests**: `e2e/api/`
@@ -365,40 +365,39 @@ Before running load tests, verify:
--- ---
## 🎓 Learning Path ## 🎓 Lộ Trình Học
### Beginner (30 minutes) ### Người Mới Bắt Đầu (30 phút)
1. Read K6_QUICK_START.md (Steps 1-4) 1. Đọc K6_QUICK_START.md (Bước 1-4)
2. Install K6 2. Cài đặt K6
3. Run: `k6 run load-tests/search.k6.js` 3. Chạy: `k6 run load-tests/search.k6.js`
### Intermediate (1-2 hours) ### Trung Cấp (1-2 giờ)
1. Read K6_ENDPOINTS_SUMMARY.md 1. Đọc K6_ENDPOINTS_SUMMARY.md
2. Understand auth flows 2. Hiểu luồng auth
3. Run auth test: `k6 run load-tests/auth.k6.js` 3. Chạy test auth: `k6 run load-tests/auth.k6.js`
4. Run listing test: `k6 run load-tests/listings.k6.js` 4. Chạy test listing: `k6 run load-tests/listings.k6.js`
### Advanced (2-4 hours) ### Nâng Cao (2-4 giờ)
1. Read K6_LOAD_TESTING_GUIDE.md completely 1. Đọc K6_LOAD_TESTING_GUIDE.md đầy đủ
2. Review controller implementations in source 2. Xem xét triển khai controller trong source
3. Create custom load test script 3. Tạo script load test tùy chỉnh
4. Set up CI/CD with GitHub Actions (K6_QUICK_START.md Step 🔟) 4. Thiết lập CI/CD với GitHub Actions (K6_QUICK_START.md Bước 🔟)
5. Generate and analyze reports 5. Tạo và phân tích báo cáo
--- ---
## 📝 Notes ## 📝 Ghi Chú
- **No existing K6 setup** — These docs provide complete guidance - **Chưa có thiết lập K6 nào** — Tài liệu này cung cấp hướng dẫn đầy đủ
- **Three complementary docs** — Explore different docs for different needs - **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
- **Executable examples** — K6_QUICK_START.md scripts work as-is - **Ví dụ chạy được** — Script K6_QUICK_START.md hoạt động ngay
- **Rate limits matter** — Consider them in test design - **Rate limit quan trọng** — Hãy xem xét chúng trong thiết kế test
- **Quota gates** — Some operations (listings, payments) are gated by subscription - **Quota gate** — Một số thao tác (listings, payments) bị giới hạn theo subscription
- **Test data** — Use seed data or generate unique test users per VU - **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
- **Production ready** — Guides follow K6 best practices - **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
--- ---
Generated: 2026-04-09 Đã tạo: 2026-04-09
Last Updated: K6_QUICK_START.md latest Cập nhật lần cuối: K6_QUICK_START.md mới nhất

22
libs/ai-services/README.md
View File

@@ -1,22 +1,22 @@
# @goodgo/ai-services # @goodgo/ai-services
Python FastAPI AI/ML microservice for the GoodGo Platform. Microservice AI/ML viết bằng Python FastAPI cho GoodGo Platform.
## Services ## Các dịch vụ
| Service | Router | Description | | Dịch vụ | Router | Mô tả |
|---------|--------|-------------| |---------|--------|-------------|
| **AVM** | `/avm` | Automated Valuation Model — XGBoost-based property price predictions | | **AVM** | `/avm` | Mô hình định giá tự động — dự đoán giá bất động sản dựa trên XGBoost |
| **Moderation** | `/moderation` | Content moderation for listings (text + image analysis) | | **Moderation** | `/moderation` | Kiểm duyệt nội dung tin đăng (phân tích văn bản + hình ảnh) |
| **NLP** | `/nlp` | Vietnamese NLP — feature extraction, search query understanding | | **NLP** | `/nlp` | NLP tiếng Việt — trích xuất đặc trưng, hiểu truy vấn tìm kiếm |
## Tech Stack ## Tech Stack
- **Python** 3.12+ - **Python** 3.12+
- **FastAPI** 0.115 + Uvicorn - **FastAPI** 0.115 + Uvicorn
- **XGBoost** 2.1 (property valuation model) - **XGBoost** 2.1 (mô hình định giá bất động sản)
- **Underthesea** 6.8 (Vietnamese NLP tokenizer) - **Underthesea** 6.8 (tokenizer NLP tiếng Việt)
- **Pydantic** 2.9 (request/response schemas) - **Pydantic** 2.9 (schema request/response)
## Quick Start ## Quick Start
@@ -30,7 +30,7 @@ pip install -e ".[dev]"
uvicorn app.main:app --reload --port 8000 uvicorn app.main:app --reload --port 8000
``` ```
## Project Structure ## Cấu trúc dự án
``` ```
libs/ai-services/ libs/ai-services/
@@ -55,7 +55,7 @@ libs/ai-services/
└── pyproject.toml # Dependencies and config └── pyproject.toml # Dependencies and config
``` ```
## Testing ## Test
```bash ```bash
cd libs/ai-services cd libs/ai-services

26
libs/mcp-servers/README.md
View File

@@ -1,23 +1,23 @@
# @goodgo/mcp-servers # @goodgo/mcp-servers
MCP (Model Context Protocol) tool server library for the GoodGo Platform. Provides structured tools that AI assistants can use to query property data, run analytics, and perform valuations. Thư viện tool server MCP (Model Context Protocol) cho GoodGo Platform. Cung cấp các công cụ có cấu trúc để trợ lý AI có thể truy vấn dữ liệu bất động sản, chạy phân tích và thực hiện định giá.
## Tool Servers ## Tool Servers
| Server | Path | Description | | Server | Đường dẫn | Mô tả |
|--------|------|-------------| |--------|------|-------------|
| **Property Search** | `property-search/` | Geo search, full-text search, filter by type/price/area | | **Property Search** | `property-search/` | Tìm kiếm theo vị trí địa lý, full-text search, lọc theo loại/giá/diện tích |
| **Market Analytics** | `market-analytics/` | Price trends, heatmaps, district comparisons | | **Market Analytics** | `market-analytics/` | Xu hướng giá, heatmap, so sánh giữa các quận |
| **Valuation** | `valuation/` | AVM property valuation requests | | **Valuation** | `valuation/` | Yêu cầu định giá bất động sản qua AVM |
## Tech Stack ## Tech Stack
- **TypeScript** 6+ - **TypeScript** 6+
- **@modelcontextprotocol/sdk** 1.12 (MCP protocol implementation) - **@modelcontextprotocol/sdk** 1.12 (triển khai giao thức MCP)
- **Zod** 3.24 (schema validation) - **Zod** 3.24 (kiểm tra schema)
- **NestJS** integration module (optional peer dependency) - **NestJS** module tích hợp (peer dependency tuỳ chọn)
## Project Structure ## Cấu trúc dự án
``` ```
libs/mcp-servers/ libs/mcp-servers/
@@ -33,21 +33,21 @@ libs/mcp-servers/
└── tsconfig.json └── tsconfig.json
``` ```
## Usage ## Cách dùng
```typescript ```typescript
import { PropertySearchServer, MarketAnalyticsServer } from '@goodgo/mcp-servers'; import { PropertySearchServer, MarketAnalyticsServer } from '@goodgo/mcp-servers';
``` ```
The MCP endpoints are exposed via the API's `apps/api/src/modules/mcp/` module. Các endpoint MCP được expose qua module `apps/api/src/modules/mcp/` của API.
## Building ## Build
```bash ```bash
pnpm --filter @goodgo/mcp-servers build pnpm --filter @goodgo/mcp-servers build
``` ```
## Testing ## Test
```bash ```bash
pnpm --filter @goodgo/mcp-servers test pnpm --filter @goodgo/mcp-servers test