admin/goodgo-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
goodgo-platform/docs/architecture/CODEBASE_OVERVIEW.md
Ho Ngoc Hai d8b409a9ab
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
docs: dịch 22 file Markdown còn lại sang tiếng Việt có dấu (TEC-2881) 
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>
2026-04-19 03:26:14 +07:00

412 lines
16 KiB
Markdown
Raw Permalink Blame History

# Nền tảng GoodGo — Tổng quan toàn diện về Codebase
**Được tạo:** Ngày 12 tháng 4 năm 2026
**Trạng thái dự án:** MVP hoàn thành — Phase 7 Wave 14 ✅ Build Green
---
## 1. CẤU TRÚC THƯ MỤC CẤP CAO NHẤT
```
goodgo-platform-ai/
├── apps/ # Monorepo applications
│ ├── api/ # NestJS backend
│ └── web/ # Next.js frontend
├── libs/ # Shared libraries
│ ├── mcp-servers/ # MCP server implementations
│ └── ai-services/ # AI/ML services (Python FastAPI)
├── prisma/ # Database schema & migrations
│ ├── schema.prisma # Complete data model
│ └── migrations/ # 7+ migration files
├── docs/ # Technical documentation
├── e2e/ # End-to-end tests (Playwright)
├── monitoring/ # Observability stack
│ ├── grafana/ # Dashboards
│ ├── loki/ # Log aggregation
│ ├── alertmanager/ # Alerts
│ └── promtail/ # Log forwarding
├── load-tests/ # K6 performance tests
├── scripts/ # DevOps & automation
├── infra/ # Infrastructure config
│ └── pgbouncer/ # DB connection pooling
├── .github/workflows/ # CI/CD pipelines
├── docker-compose.yml # Local development
├── docker-compose.prod.yml # Production stack
├── PROJECT_TRACKER.md # Issue & phase tracking
├── IMPLEMENTATION_PLAN.md # Feature roadmap
└── package.json # Monorepo config (pnpm workspaces)
```
---
## 2. CÁC MODULE API (`apps/api/src/modules/`) — 18 MODULE
### Xác thực & Phân quyền cốt lõi
- **auth/** — JWT, OAuth (Google/Zalo), MFA, mã dự phòng TOTP
- Thư mục con: application, domain, infrastructure, presentation, __tests__
- Chính: JWT guards, passport strategies, phân quyền dựa trên vai trò
### Listings & Bất động sản
- **listings/** — CRUD, quản lý trạng thái, media, AI ước tính giá
- Chấm điểm kiểm duyệt, listing nổi bật, logic hết hạn
- Upload media với pre-signed URL (AWS S3)
### Search & Khám phá
- **search/** — Tích hợp Typesense (full-text), geospatial (PostGIS)
- Repository có khả năng phục hồi với fallback về PostgreSQL
- Bộ lọc: vị trí, giá, loại bất động sản, số phòng ngủ
### Giao dịch & Inquiry
- **inquiries/** — Tin nhắn người mua-người bán cho listing cụ thể
- **leads/** — CRM dành cho agent (chấm điểm lead, theo dõi trạng thái, ghi chú)
### Kiếm tiền
- **payments/** — VNPay, MoMo, ZaloPay, Chuyển khoản ngân hàng
- Khóa idempotency, webhook callback, xử lý hoàn tiền
- 4 loại thanh toán: subscription, phí listing, đặt cọc, nổi bật
- **subscriptions/** — Các gói (FREE, AGENT_PRO, INVESTOR, ENTERPRISE)
- Theo dõi sử dụng, quản lý hạn ngạch, chu kỳ thanh toán
### Vận hành
- **agents/** — Hồ sơ agent, điểm chất lượng, khu vực phục vụ, xác minh
- **admin/** — Cấm người dùng, duyệt KYC, kiểm duyệt listing, audit log
- **notifications/** — Email, SMS, Push (FCM), Zalo OA
- Tùy chọn theo người dùng/kênh, hệ thống template
### Analytics & Trí tuệ
- **analytics/** — Báo cáo thị trường, chỉ số giá theo quận/thành phố/loại
- Tích hợp engine định giá (dịch vụ AI/ML)
### Hạ tầng & Hệ thống
- **health/** — Probe liveness/readiness, hook Kubernetes
- **metrics/** — Metrics Prometheus, độ trễ HTTP, tỷ lệ lỗi
- **mcp/** — Model Context Protocol server cho công cụ AI
- **shared/** — Domain primitives, mã hóa, logging, xử lý lỗi
**Số liệu code:**
- ~845 file TypeScript
- Kiến trúc DDD phân lớp: presentation → application → domain → infrastructure
- Sử dụng module NestJS, pattern CQRS cho các thao tác phức tạp
---
## 3. CẤU TRÚC FRONTEND (`apps/web/`)
### Root Layout
- **app/layout.tsx** — Root wrapper
- **app/[locale]/** — Định tuyến i18n (Tiếng Việt + Tiếng Anh)
### Nhóm trang (Route Groups với Layout dùng chung)
- **(public)/** — Landing, listings, search (không yêu cầu xác thực)
- **(auth)/** — Login, register, OAuth callback
- **(dashboard)/** — Dashboard người bán/agent
- **(admin)/** — Kiểm duyệt admin, duyệt KYC, quản lý người dùng
### Components (`components/`)
```
├── agents/ — Agent profiles, cards
├── auth/ — Login forms, OAuth buttons
├── charts/ — Market analytics, performance graphs (Recharts)
├── comparison/ — Property comparison tool
├── inquiries/ — Message threads
├── leads/ — Lead management UI
├── listings/ — List, create, edit, detail views
├── map/ — Mapbox integration
├── search/ — Filters, saved searches
├── subscription/ — Plan selection, billing
├── valuation/ — AI price estimates
├── ui/ — Shadcn/ui components (button, card, modal, etc.)
└── providers/ — Context providers (auth, query, etc.)
```
### Libraries (`lib/`)
```
├── *-api.ts — React Query API clients (6 main ones)
├── *-store.ts — Zustand state stores (auth, comparison)
├── hooks/ — Custom React hooks (8 hooks)
├── validations/ — Zod schemas (listing, auth, search)
├── currency.ts — VND formatting & exchange rates
├── image-blur.ts — Blur hash for image placeholders
└── web-vitals.ts — Core Web Vitals tracking
```
### i18n (`i18n/`)
- File messages tiếng Việt & tiếng Anh
- Tích hợp next-intl
**Số liệu Frontend:**
- ~245 file TypeScript/TSX
- Xây dựng trên: Next.js 15, React 18, Tailwind CSS, Shadcn/ui
- State: Zustand + React Query
- Forms: React Hook Form + validation Zod
---
## 4. PRISMA SCHEMA — MÔ HÌNH DỮ LIỆU
**Database:** PostgreSQL 16 + extension PostGIS
### Tổng số Model: 31
#### Xác thực (5)
| Model | Mục đích |
|-------|---------|
| User | Hồ sơ người dùng chính + trạng thái KYC, các trường MFA |
| RefreshToken | Quản lý chuỗi JWT refresh token |
| OAuthAccount | Liên kết OAuth Google/Zalo |
| Agent | Hồ sơ mở rộng cho người bán/Agent |
| MfaChallenge | Theo dõi xác minh TOTP/mã dự phòng |
#### Listings & Bất động sản (4)
| Model | Mục đích |
|-------|---------|
| Property | Chi tiết bất động sản vật lý + định vị địa lý |
| PropertyMedia | Hình ảnh/video cho mỗi bất động sản |
| Listing | Phiên bản listing (bán/cho thuê) + trạng thái |
| SavedSearch | Tùy chọn tìm kiếm đã lưu của người dùng |
#### Giao dịch (4)
| Model | Mục đích |
|-------|---------|
| Transaction | Luồng giao dịch người mua-người bán (inquiry → hoàn thành) |
| Inquiry | Câu hỏi người mua về listing cụ thể |
| Lead | Bản ghi lead CRM của agent |
| Review | Đánh giá người dùng về agent/giao dịch |
#### Thanh toán (2)
| Model | Mục đích |
|-------|---------|
| Payment | Bản ghi thanh toán (tất cả nhà cung cấp) |
| Plan | Định nghĩa cấp subscription |
#### Đơn hàng & Escrow (3)
| Model | Mục đích |
|-------|---------|
| Order | Lệnh thanh toán đấu giá |
| Escrow | Giữ ký quỹ cho giao dịch |
| Subscription | Subscription đang hoạt động của người dùng |
#### Analytics (2)
| Model | Mục đích |
|-------|---------|
| Valuation | Định giá bất động sản do AI tạo |
| MarketIndex | Thống kê thị trường theo quận/thành phố |
#### Vận hành (6)
| Model | Mục đích |
|-------|---------|
| NotificationLog | Bản ghi thông báo đã gửi |
| NotificationPreference | Tùy chọn nhận thông báo của người dùng |
| AdminAuditLog | Audit trail hành động admin |
| UsageRecord | Theo dõi sử dụng subscription |
**Chiến lược Index:**
- Index một cột trên foreign key, các trường trạng thái, ngày tháng
- Index ghép cho các pattern truy vấn phổ biến (ví dụ: `[role, isActive, createdAt DESC]`)
- Index GIST trên hình học vị trí PostGIS
**Các Enum chính:**
- UserRole: BUYER, SELLER, AGENT, ADMIN
- PropertyType: APARTMENT, VILLA, TOWNHOUSE, LAND, OFFICE, SHOPHOUSE
- TransactionType: SALE, RENT
- PaymentProvider: VNPAY, MOMO, ZALOPAY, BANK_TRANSFER
- PaymentStatus: PENDING, PROCESSING, COMPLETED, FAILED, REFUNDED
---
## 5. TÀI LIỆU & THEO DÕI
### Tài liệu lập kế hoạch ở cấp Root
- **PROJECT_TRACKER.md** — 7 phase, 40+ issue, trạng thái hiện tại (Phase 7 Wave 14)
- **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** — Audit toàn hệ thống với ghi chú triển khai
### Tài liệu kỹ thuật (`docs/`)
- **architecture.md** — Phân lớp DDD, CQRS, ranh giới module
- **api-endpoints.md** — Tham chiếu endpoint do Swagger tạo
- **api-error-codes.md** — Phân loại mã lỗi có cấu trúc
- **deployment.md** — Docker, K8s, các bước CI/CD
- **RUNBOOK.md** — Quy trình vận hành, xử lý sự cố
- **PRODUCTION_READINESS.md** — Checklist bảo mật, tuân thủ, hiệu năng
### Thư mục Audit (`docs/audits/`)
- 80+ file audit tài liệu hóa các triển khai tính năng
- Audit pricing, luồng checkout, KYC, test cổng thanh toán
---
## 6. PHỤ THUỘC & CÔNG CỤ
### Thiết lập Monorepo
- **pnpm** v10.27.0 (workspace) — nhanh hơn, peer deps nghiêm ngặt
- **Turbo** v2.9.4 — điều phối tác vụ & cache
- **Node** ≥22.0.0
### Backend (NestJS)
```
Core: @nestjs/core ^11.0, @nestjs/common ^11.0
DB: @prisma/client ^7.7, pg ^8.20
Auth: @nestjs/jwt, @nestjs/passport, passport-jwt, passport-google-oauth20
Cache: ioredis ^5.4
Search: typesense ^3.0.5
File Upload: @aws-sdk/client-s3, @aws-sdk/s3-request-presigner
Payments: (custom integrations for VNPay, MoMo, ZaloPay)
Monitoring: @sentry/nestjs, pino, prom-client
Email: nodemailer
2FA: otplib, qrcode
```
### Frontend (Next.js)
```
Core: next ^15.5, react ^18.3, react-dom ^18.3
Forms: react-hook-form ^7.72, @hookform/resolvers
Validation: zod ^4.3
State: zustand ^5.0, @tanstack/react-query ^5.96
UI: tailwindcss ^3.4, lucide-react ^1.7, recharts ^3.8
i18n: next-intl ^4.9
Maps: mapbox-gl ^3.21
Monitoring: @sentry/nextjs
```
### Testing & Chất lượng
```
Test: vitest ^4.1.3, @playwright/test ^1.59
Lint: eslint ^9.39, prettier ^3.8, typescript-eslint
Dependencies: dependency-cruiser (architecture validation)
```
---
## 7. ĐỘ BAO PHỦ TEST & CHẤT LƯỢNG
### Tổng số file Test: 242
#### API Tests
- **Unit tests:** Cổng thanh toán (VNPay, MoMo, ZaloPay), Money value objects, logic phí nền tảng
- **Integration tests:** Luồng auth, health check, notifications
- Nằm trong các thư mục con `__tests__` trong từng module
#### Frontend Tests
- **Unit tests:** Auth store, comparison store, định dạng tiền tệ, validation
- **E2E tests (Playwright):** 15+ web test, 16+ API test
#### Độ bao phủ E2E Test
**Web Tests (15):**
- auth-login, auth-register, auth-oauth-callback
- homepage, navigation, responsive
- create-listing, listing-detail
- search, analytics
- admin dashboard, KYC, moderation, users
- dashboard
**API Tests (16):**
- auth (login, register, profile, refresh, KYC)
- listings, listing media, moderation
- search
- payments, payment callbacks
- subscriptions
- inquiries
- mcp, admin
**Load Tests (K6):**
- Benchmark cơ sở cho các endpoint search, listings, auth
- Test đồng thời lên đến 1000 virtual users
---
## 8. TRẠNG THÁI TRIỂN KHAI
### ✅ HOÀN THÀNH (Phase 7 MVP)
1. **Foundation** — Monorepo, Docker, schema Prisma, CI/CD
2. **Auth** — JWT, OAuth, MFA/TOTP, quản lý phiên
3. **Listings** — CRUD đầy đủ, upload media, workflow trạng thái
4. **Search** — Typesense + tìm kiếm địa lý PostGIS
5. **Payments** — 3 cổng thanh toán VN, xử lý webhook
6. **Subscriptions** — 4 cấp, theo dõi quota
7. **Notifications** — Email, SMS, Push, Zalo OA
8. **Admin Panel** — Kiểm duyệt, quản lý người dùng, audit log
9. **Agents** — Portal, inquiries, lead CRM, chỉ số chất lượng
10. **Analytics** — Báo cáo thị trường, dịch vụ định giá AI
11. **Security** — Rate limiting, CSRF, mã hóa trường, che PII
12. **Monitoring** — Prometheus, Grafana, Sentry, tổng hợp log
13. **Testing** — Unit test, E2E test (Playwright), load test (K6)
### 🔄 ĐANG TIẾN HÀNH / CÒN LẠI
- Theo Wave 14:
- TEC-1650: Xử lý lỗi ID không tồn tại trên trang chi tiết listing
- TEC-1652: Xác thực bộ test E2E đầy đủ
- TEC-1657: Audit logging toàn diện
### Migration Database
- 7+ migration đã được áp dụng
- Connection pooling (PgBouncer)
- Đã bật extension PostGIS
---
## 9. CHỈ SỐ TRƯỞNG THÀNH DỰ ÁN
| Khía cạnh | Trạng thái | Bằng chứng |
|-----------|--------|----------|
| **Kiến trúc** | Sẵn sàng Production | DDD, CQRS, các module phân lớp, ranh giới rõ ràng |
| **Chất lượng code** | Cao | 242 test, ESLint thực thi, module cruiser |
| **Bảo mật** | Đã được củng cố | JWT, MFA, mã hóa, rate limiting, CSRF, che PII |
| **Tài liệu** | Toàn diện | 80+ file audit, runbook, mã lỗi, kiến trúc |
| **Hiệu năng** | Đã tối ưu | Cache Redis, tìm kiếm Typesense, tối ưu truy vấn, load test |
| **Monitoring** | Hoàn chỉnh | Prometheus, Grafana, Sentry, structured logging |
| **DevOps** | Trưởng thành | Docker, cấu hình Kubernetes, pipeline CI/CD, smoke test |
| **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. THỐNG KÊ CHÍNH
```
Backend Files: ~845 TypeScript files
Frontend Files: ~245 TypeScript/TSX files
Total Test Files: 242 (unit + E2E + load)
API Modules: 18 feature modules + 1 shared
Database Models: 31 (fully normalized)
Migrations: 7+ applied to PostgreSQL 16
API Endpoints: 100+ documented
E2E Test Cases: 31 (web + API)
Load Test Scenarios: 5+ K6 scripts
Documentation: 80+ audit files + runbooks
Lines of Code: ~50,000+ (excluding node_modules)
```
---
## 11. TÓM TẮT TECH STACK
| Lớp | Công nghệ |
|-------|-----------|
| **Frontend** | Next.js 15, React 18, Tailwind CSS, Shadcn/ui |
| **Backend** | NestJS 11, TypeScript 6 |
| **Database** | PostgreSQL 16 + PostGIS |
| **Cache** | Redis (ioredis) |
| **Search** | Typesense 3.0 |
| **File Storage** | AWS S3 |
| **Payments** | VNPay, MoMo, ZaloPay |
| **Auth** | JWT + OAuth2 (Google, Zalo) |
| **Notifications** | Email (Nodemailer), SMS, FCM, Zalo OA |
| **Monitoring** | Prometheus, Grafana, Sentry |
| **Logs** | Pino + Loki |
| **Testing** | Playwright (E2E), Vitest (unit), K6 (load) |
| **Package Manager** | pnpm 10.27 |
| **Orchestration** | Turbo |
| **Containerization** | Docker + Docker Compose |
| **i18n** | next-intl (Tiếng Việt + Tiếng Anh) |
---
## 12. CÁC BƯỚC TIẾP THEO CHO LẬP TRÌNH VIÊN
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
Reference in New Issue View Git Blame Copy Permalink