# GoodGo Platform AI - Báo Cáo Kiểm Toán Codebase Toàn Diện
**Ngày Kiểm Toán:** 11 tháng 4, 2026

---

## 1. TỔNG QUAN CẤU TRÚC DỰ ÁN

### Tổ Chức Thư Mục
```
goodgo-platform-ai/
├── apps/                    # Các ứng dụng trong Monorepo
│   ├── api/                # NestJS Backend (cổng 3001)
│   └── web/                # Next.js Frontend (cổng 3000)
├── libs/                    # Thư viện dùng chung
│   ├── mcp-servers/        # Máy chủ Model Context Protocol
│   └── ai-services/        # Dịch vụ AI Python (FastAPI)
├── prisma/                 # Schema & migrations cơ sở dữ liệu
│   ├── schema.prisma       # 641 dòng
│   └── migrations/         # 13 migrations
├── e2e/                    # Kiểm thử end-to-end
│   ├── api/               # Kiểm thử E2E API (16 tệp spec)
│   ├── web/               # Kiểm thử E2E Web (15 tệp spec)
│   └── fixtures/          # Dữ liệu kiểm thử mẫu
├── infra/                 # Cấu hình hạ tầng
├── monitoring/            # Prometheus, Grafana, Loki, AlertManager
└── scripts/              # Scripts tiện ích
```

### Số Lượng Tệp
- **Tổng số tệp TypeScript/TSX:** 992 tệp
- **Tổng dòng code (apps/):** 70.569 LOC
- **Quản lý cấu hình:** Turbo monorepo với pnpm

---

## 2. BACKEND (apps/api)

### Ngăn Xếp Công Nghệ
- **Framework:** NestJS 11.0.0
- **Runtime:** Node.js 22+
- **Ngôn ngữ:** TypeScript 6.0.2 (bật chế độ strict)
- **Cơ sở dữ liệu:** PostgreSQL 16 + extension PostGIS
- **ORM:** Prisma 7.7.0
- **Tài liệu API:** Swagger/OpenAPI

### Kiến Trúc Module (16 module)

| Module | Số tệp | Cấu trúc | Trạng thái |
|--------|--------|-----------|------------|
| **auth** | 108 | Domain ✓ / App ✓ / Infra ✓ / Presentation ✓ | Phân lớp đầy đủ |
| **admin** | 93 | Domain ✓ / App ✓ / Infra ✓ / Presentation ✓ | Phân lớp đầy đủ |
| **listings** | 83 | Domain ✓ / App ✓ / Infra ✓ / Presentation ✓ | Phân lớp đầy đủ |
| **analytics** | 67 | Domain ✓ / App ✓ / Infra ✓ / Presentation ✓ | Phân lớp đầy đủ |
| **search** | 66 | Domain ✓ / App ✓ / Infra ✓ / Presentation ✓ | Phân lớp đầy đủ |
| **notifications** | 49 | Domain ✓ / App ✓ / Infra ✓ / Presentation ✓ | Phân lớp đầy đủ |
| **payments** | 51 | Domain ✓ / App ✓ / Infra ✓ | Phân lớp đầy đủ |
| **subscriptions** | 48 | Domain ✓ / App ✓ / Infra ✓ | Phân lớp đầy đủ |
| **leads** | 41 | Domain ✓ / App ✓ / Infra ✓ | Phân lớp đầy đủ |
| **reviews** | 38 | Domain ✓ / App ✓ / Infra ✓ | Phân lớp đầy đủ |
| **inquiries** | 34 | Domain ✓ / App ✓ / Infra ✓ | Phân lớp đầy đủ |
| **agents** | 29 | Domain ✓ / App ✓ / Infra ✓ | Phân lớp đầy đủ |
| **metrics** | - | Module chỉ có Infra | Chuyên biệt |
| **health** | - | Dựa trên controller đơn giản | Kiểm tra trạng thái |
| **mcp** | - | Chỉ có Presentation | Tích hợp MCP |
| **shared** | - | Hạ tầng xuyên suốt | Tiện ích |

### Kết Nối Module Cốt Lõi (app.module.ts)

**Tất cả 16 module được import và đăng ký đúng cách:**
- SharedModule, HealthModule, AuthModule
- AgentsModule, InquiriesModule, LeadsModule, ListingsModule
- ReviewsModule, SearchModule, NotificationsModule, PaymentsModule
- SubscriptionsModule, AdminModule, AnalyticsModule, MetricsModule, McpIntegrationModule

### Các Lớp Kiến Trúc

Tất cả các module chính tuân theo **Kiến Trúc Lục Giác (Hexagonal Architecture)**:
```
Domain/
├── Entities (mô hình domain)
├── Value Objects
├── Interfaces (hợp đồng repository)
└── Specifications (quy tắc nghiệp vụ)

Application/
├── Commands (trình xử lý lệnh)
├── Queries (trình xử lý truy vấn)
├── DTOs (đối tượng truyền dữ liệu)
└── Services (điều phối use case)

Infrastructure/
├── Database (Prisma repositories)
├── Cache (Redis)
├── Services (tích hợp bên ngoài)
├── Subscribers (trình xử lý sự kiện)
└── Specifications (truy vấn Prisma)

Presentation/
├── Controllers (REST endpoints)
├── Guards (phân quyền)
└── Interceptors (mối quan tâm xuyên suốt)
```

### Các Dịch Vụ Hạ Tầng Chính (shared/infrastructure)

- **PrismaService** - Trình bao ORM cơ sở dữ liệu
- **RedisService** - Caching & giới hạn tốc độ
- **LoggerService** - Ghi log có cấu trúc (Pino)
- **CacheService** - Caching đa chiến lược
- **FieldEncryptionService** - Mã hóa trường PII
- **CircuitBreakerService** - Khả năng chịu lỗi
- **EventBusService** - Phân phối sự kiện CQRS

### Cấu Hình Toàn Cục

**app.module.ts cung cấp:**
- CQRS Module (mẫu lệnh/truy vấn)
- Schedule Module (tác vụ nền)
- Throttler Module (giới hạn tốc độ)
  - Mặc định: 60 yêu cầu/phút
  - Xác thực: 10 yêu cầu/phút
  - Thanh toán: 20 yêu cầu/phút
- Tích hợp Sentry (theo dõi lỗi)

**main.ts khởi động:**
- Pipe xác thực toàn cục (whitelist + transform)
- Header bảo mật (Helmet)
- Cấu hình CORS (dựa trên môi trường)
- Bảo vệ CSRF (double-submit cookies)
- Cookie parser
- Ghi log yêu cầu
- Hook tắt máy nhẹ nhàng
- Tài liệu Swagger

### Phiên Bản API
- **Tiền tố toàn cục:** `/api/v1/`
- **Endpoint sức khoẻ:** `/health` (loại trừ khỏi versioning)
- **Tài liệu Swagger:** `/api/v1/docs`

### Độ Phủ Kiểm Thử

**Kiểm Thử Backend:**
- **Kiểm thử đơn vị:** 229 tệp .spec.ts
- **Tổng LOC kiểm thử:** 23.886 dòng
- **Framework kiểm thử:** Vitest
- **Kiểm thử tích hợp:** Cấu hình vitest riêng
- **Kiểm thử E2E:** 16 bộ kiểm thử endpoint API

---

## 3. FRONTEND (apps/web)

### Ngăn Xếp Công Nghệ
- **Framework:** Next.js 15.5.14 (App Router)
- **Ngôn ngữ:** TypeScript 6.0.2 (strict)
- **UI Framework:** React 18.3.0
- **Tạo kiểu:** Tailwind CSS 3.4.0
- **Quản lý trạng thái:** Zustand 5.0.12
- **Lấy dữ liệu:** React Query 5.96.2
- **Biểu mẫu:** React Hook Form 7.72.1 + xác thực Zod
- **Đa ngôn ngữ:** next-intl 4.9.0
- **Bản đồ:** Mapbox GL 3.21.0

### Các Route Trang (33 trang + 8 layout)

**Route Xác Thực:**
- `/[locale]/(auth)/login` - Đăng nhập người dùng
- `/[locale]/(auth)/register` - Đăng ký người dùng
- `/[locale]/auth/callback/google` - Callback OAuth
- `/[locale]/auth/callback/zalo` - Callback OAuth

**Route Công Khai:**
- `/[locale]/(public)` - Trang đích
- `/[locale]/(public)/pricing` - Trang giá
- `/[locale]/(public)/search` - Tìm kiếm bất động sản
- `/[locale]/(public)/compare` - So sánh bất động sản
- `/[locale]/(public)/listings/[id]` - Chi tiết tin đăng
- `/[locale]/(public)/agents/[id]` - Hồ sơ môi giới

**Route Dashboard (Đã xác thực):**
- `/[locale]/(dashboard)/dashboard` - Dashboard chính
- `/[locale]/(dashboard)/dashboard/profile` - Hồ sơ người dùng
- `/[locale]/(dashboard)/dashboard/kyc` - Xác minh KYC
- `/[locale]/(dashboard)/dashboard/subscription` - Quản lý gói đăng ký
- `/[locale]/(dashboard)/dashboard/payments` - Lịch sử thanh toán
- `/[locale]/(dashboard)/dashboard/saved-searches` - Tìm kiếm đã lưu
- `/[locale]/(dashboard)/dashboard/valuation` - Định giá bất động sản

**Route Tin Đăng:**
- `/[locale]/(dashboard)/listings` - Tin đăng của tôi
- `/[locale]/(dashboard)/listings/new` - Tạo tin đăng
- `/[locale]/(dashboard)/listings/[id]/edit` - Chỉnh sửa tin đăng

**Route Môi Giới:**
- `/[locale]/(dashboard)/leads` - Quản lý khách hàng tiềm năng
- `/[locale]/(dashboard)/inquiries` - Quản lý yêu cầu tư vấn
- `/[locale]/(dashboard)/analytics` - Dashboard phân tích

**Route Admin:**
- `/[locale]/(admin)/admin` - Dashboard quản trị
- `/[locale]/(admin)/admin/users` - Quản lý người dùng
- `/[locale]/(admin)/admin/kyc` - Hàng chờ KYC
- `/[locale]/(admin)/admin/moderation` - Kiểm duyệt nội dung

### Cấu Trúc Component (68 component)

**Theo Domain:**
| Danh mục | Số lượng | Mục đích |
|----------|----------|----------|
| **UI Components** | 21 | Hệ thống thiết kế (buttons, forms, modals, v.v.) |
| **Listings** | 7 | Card tin đăng, bộ lọc, biểu mẫu |
| **Comparison** | 7 | Giao diện so sánh bất động sản |
| **Valuation** | 6 | Giao diện máy tính định giá |
| **Search** | 4 | Bộ lọc tìm kiếm, kết quả |
| **Charts** | 4 | Trực quan hóa phân tích |
| **Inquiries** | 3 | Biểu mẫu & danh sách yêu cầu |
| **Auth** | 2 | Biểu mẫu đăng nhập/đăng ký |
| **Leads** | 4 | Giao diện quản lý khách hàng tiềm năng |
| **Providers** | 4 | Provider Auth, Query, Theme |
| **Map** | 1 | Tích hợp Mapbox |
| **Agents** | 1 | Hiển thị môi giới |
| **SEO** | 2 | Meta tags & OG |

### Quản Lý Trạng Thái

**Zustand Stores:**
- `auth-store.ts` - Trạng thái xác thực người dùng (3,3 KB)
- `comparison-store.ts` - Trạng thái so sánh bất động sản (3,9 KB)

**Lớp API (lib/*.ts):**
- `admin-api.ts` - Các thao tác admin
- `agents-api.ts` - Dữ liệu môi giới
- `analytics-api.ts` - Truy vấn phân tích
- `auth-api.ts` - Endpoint xác thực
- `payment-api.ts` - Thao tác thanh toán
- `subscription-api.ts` - Quản lý gói đăng ký
- `listings-api.ts` - CRUD tin đăng
- `leads-api.ts` - Quản lý khách hàng tiềm năng
- `inquiries-api.ts` - Quản lý yêu cầu tư vấn
- `valuation-api.ts` - Truy vấn định giá
- `saved-search-api.ts` - Tìm kiếm đã lưu
- `comparison-api.ts` - Dữ liệu so sánh

### Provider & Tích Hợp

**Provider Tùy Chỉnh:**
- `auth-provider.tsx` - Quản lý phiên đăng nhập
- `theme-provider.tsx` - Chế độ tối (nếu được bật)
- `query-provider.tsx` - Thiết lập React Query

### Độ Phủ Kiểm Thử

**Kiểm Thử Frontend:**
- **Kiểm thử component:** 45 tệp .spec.tsx
- **Tổng LOC kiểm thử:** 3.864 dòng
- **Framework kiểm thử:** Vitest + React Testing Library
- **Kiểm thử E2E:** 15 bộ kiểm thử Playwright

---

## 4. CƠ SỞ DỮ LIỆU

### Tổng Quan Schema

**21 Model trong prisma schema.prisma (641 dòng):**

**Xác Thực & Người Dùng:**
- User (vai trò: BUYER, SELLER, AGENT, ADMIN)
- RefreshToken
- OAuthAccount (nhà cung cấp: GOOGLE, ZALO)
- Agent

**Tin Đăng & Bất Động Sản:**
- Property (chỉ mục địa lý với PostGIS)
- PropertyMedia (hình ảnh/media)
- Listing (tin đăng bất động sản với theo dõi trạng thái)
- SavedSearch (tìm kiếm đã lưu của người dùng)

**Giao Dịch & Yêu Cầu:**
- Transaction (giao dịch người mua-người bán)
- Inquiry (yêu cầu tư vấn bất động sản)
- Lead (khách hàng tiềm năng của môi giới)

**Thanh Toán & Gói Đăng Ký:**
- Payment (bản ghi thanh toán với tích hợp VNPay)
- Plan (gói đăng ký dịch vụ)
- Subscription (gói đăng ký đang hoạt động)
- UsageRecord (đo lường mức sử dụng)

**Phân Tích:**
- Valuation (định giá bất động sản)
- MarketIndex (dữ liệu phân tích thị trường)

**Ghi Log & Tuân Thủ:**
- NotificationLog (lịch sử thông báo)
- NotificationPreference (cài đặt thông báo của người dùng)
- AdminAuditLog (nhật ký kiểm toán hành động admin)

**Đánh Giá:**
- Review (đánh giá & xếp hạng bất động sản)

### Các Tính Năng Cơ Sở Dữ Liệu Chính

- **Tích Hợp PostGIS:** Truy vấn địa lý (vị trí bất động sản)
- **Indexes:** 30+ indexes tối ưu hóa truy vấn
- **Compound Indexes:** Tối ưu cho các mẫu truy vấn phổ biến
- **Cascade Delete:** Toàn vẹn tham chiếu đúng đắn
- **Soft Deletes:** User.deletedAt, User.deletionScheduledAt
- **Timestamps:** createdAt, updatedAt trên tất cả các thực thể

### Migrations

**13 migrations đã triển khai (từ ngày 7 - 11 tháng 4):**
1. Schema ban đầu (`20260407165528_init`)
2. Indexes khóa ngoại (`20260407210149_add_missing_fk_indexes`)
3. Idempotency thanh toán (`20260408000000_add_idempotency_key_to_payment`)
4. Sửa toàn vẹn schema (`20260408061200_fix_schema_integrity`)
5. Hạn mức analytics/media (`20260408080000_add_analytics_media_quota_fields`)
6. Index đánh giá (`20260408160000_add_review_userid_index`)
7. Trạng thái đọc thông báo (`20260409000000_add_notification_read_at`)
8. Compound indexes (`20260409100000_add_compound_indexes_query_optimization`)
9. Tối ưu truy vấn (`20260409120000_add_missing_query_indexes`)
10. Soft deletes (`20260410000000_add_user_soft_delete_fields`)
11. Nhật ký kiểm toán admin (`20260410100000_add_admin_audit_log`)
12. Cascade deletes (`20260411000000_add_cascade_delete_strategies`)
13. Mã hóa PII (`20260411100000_add_pii_encryption_hash_columns`)

### Seeding Cơ Sở Dữ Liệu

- Script seed tùy chỉnh tại `prisma/seed.ts`
- Lệnh seeding: `pnpm db:seed`
- Hỗ trợ tạo dữ liệu kiểm thử

---

## 5. HẠ TẦNG & TRIỂN KHAI

### Các Dịch Vụ Docker Compose

**Stack Phát Triển (docker-compose.yml):**
- PostgreSQL 16 + PostGIS
- Redis 7
- Typesense 27.1 (tìm kiếm toàn văn)
- MinIO (lưu trữ tương thích S3)
- PgBouncer (connection pooling)

**Stack Sản Xuất (docker-compose.prod.yml):**
- Container được điều phối
- Volumes bền vững
- Kiểm tra sức khỏe
- Cô lập mạng

**Stack CI (docker-compose.ci.yml):**
- Môi trường kiểm thử

### Stack Giám Sát (monitoring/)

- **Prometheus** - Thu thập metrics
- **Grafana** - Trực quan hóa dashboard
- **Loki** - Tổng hợp log
- **Promtail** - Chuyển tiếp log
- **AlertManager** - Định tuyến cảnh báo

### Pipeline CI/CD (.github/workflows)

**ci.yml** (Pipeline Chính)
- Chạy khi: push lên master, PRs
- Dịch vụ: PostgreSQL, Redis, Typesense, MinIO
- Các bước:
  1. Lint (ESLint)
  2. Kiểm tra kiểu (tsc)
  3. Kiểm thử đơn vị (pnpm test)
  4. Build (pnpm build)
- Phiên bản Node: 22

**e2e.yml** (Kiểm Thử E2E)
- Phụ thuộc vào: CI đạt
- Dịch vụ: PostgreSQL, Redis, Typesense, MinIO
- Trình duyệt: Chromium (Playwright)
- Tạo báo cáo artifact

**deploy.yml** (Triển Khai)
- Triển khai có điều kiện dựa trên nhánh
- Build & push Docker image
- Triển khai Kubernetes
- Thông báo trạng thái

**security.yml** (Quét Bảo Mật)
- Phân tích CodeQL
- Quét phụ thuộc
- SAST

**load-test.yml** (Hiệu Năng)
- Pipeline kiểm thử tải
- Đo điểm chuẩn hiệu năng

**backup-verify.yml** (Bảo Vệ Dữ Liệu)
- Xác minh sao lưu cơ sở dữ liệu
- Kiểm thử phục hồi

---

## 6. CHẤT LƯỢNG CODE & TIÊU CHUẨN

### Cấu Hình TypeScript

**tsconfig.base.json:**
```
- Strict mode: BẬT ✓
- Target: ES2022
- Module Resolution: NodeNext
- Các cờ strict chính:
  - noUncheckedIndexedAccess: true
  - noImplicitOverride: true
  - noPropertyAccessFromIndexSignature: true
  - declaration: true (phát sinh .d.ts)
  - sourceMap: true
```

### Cấu Hình ESLint

**eslint.config.mjs:**
- **Framework:** ESLint 9 với hỗ trợ TypeScript
- **Import Plugin:** Sắp xếp import với các quy tắc đóng gói module
- **Tích Hợp Prettier:** Định dạng không xung đột

**Các Quy Tắc:**
- Biến không sử dụng: Lỗi (cho phép dấu _ ở đầu)
- Explicit any: Cảnh báo
- Nhập kiểu nhất quán: Lỗi (inline-type-imports)
- Không có console trong ứng dụng web: Lỗi
- Không import nội bộ chéo module: Lỗi (ngoại trừ kiểm thử)
- Đóng gói module: Bắt buộc (chỉ có thể import từ barrel exports)

### Cấu Hình Prettier

```
- Single quotes: true
- Trailing comma: all
- Tab width: 2
- Semi-colons: true
- Line width: 100
- Arrow parens: always
```

### Sự Sạch Sẽ của Code

- **Comment TODO/FIXME/HACK:** Tìm thấy 0
- **Không Có Dấu Nợ Kỹ Thuật:** Codebase sạch
- **Đặt Tên Nhất Quán:** Pascal case (Classes), camelCase (functions)
- **Barrel Exports Module:** Bắt buộc qua ESLint

---

## 7. FRAMEWORK KIỂM THỬ

### Kiểm Thử Đơn Vị

**Backend:**
- Framework: Vitest 4.1.3
- Định dạng: Tệp .spec.ts cùng vị trí với source
- Độ phủ: 229 tệp spec
- Thiết lập: Supertest cho kiểm thử HTTP

**Frontend:**
- Framework: Vitest 4.1.3
- Định dạng: Tệp .spec.tsx trong thư mục __tests__
- Độ phủ: 45 tệp spec
- Thiết lập: React Testing Library + jsdom

### Kiểm Thử Tích Hợp

**Backend:**
- Cấu hình riêng: `vitest.integration.config.ts`
- Lệnh: `pnpm test:integration`
- Sử dụng cơ sở dữ liệu kiểm thử

### Kiểm Thử E2E

**Công cụ:** Playwright 1.59.1
- **Kiểm thử Web:** 15 tệp kiểm thử
- **Kiểm thử API:** 16 tệp kiểm thử
- **Fixtures:** Dữ liệu kiểm thử dùng chung
- **Thiết lập toàn cục:** Seeding cơ sở dữ liệu
- **Dọn dẹp toàn cục:** Xóa dữ liệu
- **Trình duyệt:** Chromium
- **Báo cáo:** HTML + trace artifacts

**Phạm Vi E2E:**
- Xác thực (đăng nhập, đăng ký, OAuth)
- Tin đăng (CRUD, media, kiểm duyệt)
- Tìm kiếm & lọc
- Thanh toán & callbacks
- Gói đăng ký
- Thao tác admin
- Khả năng đáp ứng
- Luồng điều hướng

---

## 8. THƯ VIỆN & PHỤ THUỘC

### Phụ Thuộc Chính Backend

**Framework & Lõi:**
- @nestjs/common@11.0.0
- @nestjs/core@11.0.0
- @nestjs/cqrs@11.0.0
- reflect-metadata@0.2.0
- rxjs@7.8.0

**Cơ Sở Dữ Liệu:**
- @prisma/client@7.7.0
- @prisma/adapter-pg@7.7.0
- pg@8.20.0

**API & Tài Liệu:**
- @nestjs/swagger@11.2.7
- swagger-ui-express@5.0.1

**Xác Thực:**
- passport@0.7.0
- passport-jwt@4.0.1
- passport-google-oauth20@2.0.0
- @nestjs/jwt@11.0.2
- bcrypt@6.0.0

**Caching & Tác Vụ Nền:**
- ioredis@5.4.0
- @nestjs/schedule@6.1.1
- @nestjs/event-emitter@3.0.0

**Tìm Kiếm:**
- typesense@3.0.5

**Lưu Trữ:**
- @aws-sdk/client-s3@3.1026.0
- @aws-sdk/s3-request-presigner@3.1026.0

**Xác Thực Dữ Liệu:**
- class-validator@0.15.1
- class-transformer@0.5.1

**Bảo Mật:**
- helmet@8.1.0
- sanitize-html@2.17.2
- cookie-parser@1.4.7

**Giám Sát & Ghi Log:**
- @sentry/nestjs@10.47.0
- @sentry/profiling-node@10.47.0
- pino@10.3.1
- pino-pretty@13.0.0
- @willsoto/nestjs-prometheus@6.1.0
- prom-client@15.1.3

**Email:**
- nodemailer@8.0.5
- handlebars@4.7.9

**Cloud:**
- firebase-admin@13.7.0

### Phụ Thuộc Chính Frontend

**Lõi:**
- react@18.3.0
- react-dom@18.3.0
- next@15.5.14

**Quản Lý Trạng Thái:**
- zustand@5.0.12
- @tanstack/react-query@5.96.2

**Biểu Mẫu:**
- react-hook-form@7.72.1
- @hookform/resolvers@5.2.2
- zod@4.3.6

**UI & Tạo Kiểu:**
- tailwindcss@3.4.0
- tailwind-merge@3.5.0
- class-variance-authority@0.7.1
- clsx@2.1.1
- lucide-react@1.7.0

**Đa Ngôn Ngữ:**
- next-intl@4.9.0

**Bản Đồ:**
- mapbox-gl@3.21.0

**Biểu Đồ:**
- recharts@3.8.1

**Giám Sát:**
- @sentry/nextjs@10.47.0

**Hiệu Năng:**
- web-vitals@5.2.0

---

## 9. CÁC MẪU HẠ TẦNG

### Kiến Trúc Module Dùng Chung

**Tiện Ích Domain:**
- Hằng số, enums, kiểu
- Decorators (auth, cache, idempotency)

**Dịch Vụ Hạ Tầng:**
- Truy cập cơ sở dữ liệu (PrismaService)
- Caching (CacheService, RedisService)
- Mã hóa (FieldEncryptionService)
- Ghi log (LoggerService)
- Circuit breaker (khả năng chịu lỗi)
- Che giấu PII
- Event bus

**Middleware:**
- Bảo vệ CSRF
- Làm sạch đầu vào
- Middleware mã hóa

**Guards:**
- Xác thực JWT
- Kiểm soát truy cập dựa trên vai trò (RBAC)
- Throttler đằng sau proxy

**Filters:**
- Xử lý exception toàn cục
- Tích hợp Sentry

**Pipes:**
- Pipes xác thực

### Xác Thực & Phân Quyền

**Phương Thức Hỗ Trợ:**
- JWT (Bearer tokens)
- Cục bộ (email/mật khẩu)
- OAuth 2.0 (Google, Zalo)

**Quản Lý Token:**
- Access token (15 phút)
- Refresh token (7 ngày)
- Token families (xoay vòng refresh token)
- Theo dõi thu hồi

**Phân Quyền:**
- Kiểm soát truy cập dựa trên vai trò (BUYER, SELLER, AGENT, ADMIN)
- Decorators guard
- Hạn chế ở cấp endpoint

### Tích Hợp Bên Ngoài

- **Cổng Thanh Toán:** VNPay (Việt Nam)
- **Công Cụ Tìm Kiếm:** Typesense (toàn văn, geo-search)
- **Lưu Trữ Đối Tượng:** MinIO / AWS S3
- **Email:** Nodemailer + Handlebars
- **Thông Báo Đẩy:** Firebase Cloud Messaging
- **Nhà Cung Cấp OAuth:** Google, Zalo
- **Giám Sát:** Sentry, Prometheus, Grafana, Loki

---

## 10. TÌNH TRẠNG BẢO MẬT

### Tính Năng Bảo Mật Tích Hợp

✓ **Helmet** - Header bảo mật (CSP, X-Frame-Options, HSTS, v.v.)
✓ **CORS** - Danh sách trắng dựa trên môi trường
✓ **CSRF** - Mẫu double-submit cookie
✓ **Rate Limiting** - Điều tiết theo từng route
✓ **Làm Sạch Đầu Vào** - Ngăn chặn XSS
✓ **SQL Injection** - Truy vấn tham số hóa (Prisma)
✓ **Mã Hóa Trường** - Trường PII được mã hóa lúc lưu trữ
✓ **Trường Hash** - Email/số điện thoại được hash để tra cứu
✓ **Soft Deletes** - Lưu trữ tuân thủ GDPR
✓ **Audit Logging** - Theo dõi hành động admin
✓ **Circuit Breaker** - Cuộc gọi bên ngoài an toàn khi thất bại
✓ **Hash Mật Khẩu** - bcrypt (6 vòng)
✓ **Ký JWT** - HS256 (có thể cấu hình)

### Quét Bảo Mật

- CodeQL (GitHub Actions)
- Quét lỗ hổng phụ thuộc
- Phân tích SAST

---

## 11. HIỆU NĂNG & KHẢ NĂNG MỞ RỘNG

### Chiến Lược Caching

- **Redis:** Cache phiên, bộ đếm giới hạn tốc độ, caching dữ liệu
- **Cấp ứng dụng:** Caching khóa mã hóa trường
- **Cấp truy vấn:** Caching truy vấn Prisma

### Tối Ưu Cơ Sở Dữ Liệu

- **Connection Pooling:** PgBouncer (pool size 20, 200 max clients)
- **Indexes:** 30+ bao gồm compound indexes
- **Lập kế hoạch truy vấn:** Tối ưu cho các mẫu phổ biến
- **PostGIS:** Indexing địa lý-không gian cho truy vấn vị trí

### Tối Ưu Tìm Kiếm

- **Typesense:** Công cụ tìm kiếm toàn văn
- **Geo-search:** Tích hợp Mapbox GL
- **Lọc:** Hỗ trợ tìm kiếm theo facet

### Cân Bằng Tải

- **Sau Proxy:** Cấu hình tin tưởng proxy
- **Rate Limiting:** Điều tiết theo từng endpoint
- **Circuit Breaker:** Giảm cấp nhẹ nhàng

---

## 12. TÓM TẮT METRICS KIỂM THỬ

### Độ Phủ Code Theo Lớp

| Khía Cạnh | Backend | Frontend |
|-----------|---------|----------|
| Kiểm Thử Đơn Vị | 229 tệp | 45 tệp |
| LOC Kiểm Thử | 23.886 | 3.864 |
| Kiểm Thử E2E | 16 bộ | 15 bộ |
| **Tổng Kiểm Thử** | **~261** | **~60** |

### Thực Thi Kiểm Thử

- **Cục bộ:** `pnpm test`
- **Tích hợp:** `pnpm test:integration`
- **E2E:** `pnpm test:e2e`
- **Báo cáo:** `pnpm test:e2e:report`

---

## 13. QUY TRÌNH PHÁT TRIỂN

### Các Script Có Sẵn

**Phát Triển:**
```bash
pnpm dev           # Khởi động tất cả ứng dụng ở chế độ dev
pnpm dev:api       # Chỉ API
pnpm dev:web       # Chỉ Web
```

**Build:**
```bash
pnpm build         # Build tất cả ứng dụng
pnpm build:api     # Chỉ API
pnpm build:web     # Chỉ Web
```

**Kiểm Thử:**
```bash
pnpm test          # Tất cả kiểm thử đơn vị
pnpm test:integration  # Kiểm thử tích hợp
pnpm test:e2e      # Kiểm thử E2E
pnpm test:e2e:report  # Xem báo cáo
```

**Chất Lượng Code:**
```bash
pnpm lint          # ESLint
pnpm format        # Prettier
pnpm format:check  # Kiểm tra Prettier
pnpm typecheck     # Kiểm tra TypeScript
pnpm dep-cruise    # Phân tích phụ thuộc
```

**Cơ Sở Dữ Liệu:**
```bash
pnpm db:generate   # Tạo Prisma client
pnpm db:migrate:dev    # Migrations cho dev
pnpm db:migrate:deploy # Migrations cho sản xuất
pnpm db:seed       # Seed cơ sở dữ liệu
pnpm db:push       # Đồng bộ lên DB
pnpm db:reset      # Reset hoàn toàn
pnpm db:studio     # Giao diện Prisma Studio
```

### Git Hooks

- **Husky:** Hook trước khi commit
- **Lint-staged:** Chạy linters trên các tệp đã stage
- **Pre-push:** Kiểm tra kiểu & xác thực build

---

## 14. TÀI LIỆU & QUY ƯỚC

### Tài Liệu Có Sẵn

- `CLAUDE.md` - Hướng dẫn tích hợp AI
- `CONTRIBUTING.md` - Hướng dẫn đóng góp
- `.env.example` - Mẫu thiết lập môi trường
- Tài liệu Swagger API tại `/api/v1/docs`

### Quy Ước Đặt Tên

**TypeScript/Tệp:**
- Classes: PascalCase (UserService, ListingRepository)
- Functions: camelCase (createUser, getListings)
- Tệp: kebab-case (user.service.ts, create-user.command.ts)
- Thư mục: kebab-case (src/modules/auth)

**Cơ Sở Dữ Liệu:**
- Bảng: PascalCase (User, Listing, Payment)
- Cột: camelCase (firstName, phoneHash)
- Indexes: Đặt tên tường minh (ví dụ: idx_user_role_active)

---

## 15. DỊCH VỤ AI PYTHON (libs/ai-services)

### Cấu Trúc

- **Framework:** FastAPI
- **Ngôn ngữ:** Python
- **Vị trí:** `/libs/ai-services/`
- **Kiểm thử:** pytest trong thư mục `tests/`
- **Docker:** Container hóa

### Khả Năng

- Định giá/phân tích bất động sản
- Phân tích thị trường
- Tăng cường tìm kiếm bất động sản bằng AI

---

## KẾT QUẢ KIỂM TOÁN - TÓM TẮT ĐIỀU HÀNH

### ✓ ĐIỂM MẠNH

1. **Kiến Trúc Được Cấu Trúc Tốt**
   - Kiến trúc lục giác được áp dụng nhất quán
   - Tách biệt mối quan tâm rõ ràng (domain/application/infrastructure/presentation)
   - Đóng gói module được bắt buộc qua ESLint

2. **Bảo Mật Cấp Doanh Nghiệp**
   - Nhiều lớp bảo mật (CSRF, CSP, giới hạn tốc độ, làm sạch đầu vào)
   - Mã hóa cấp trường cho PII
   - Audit logging để tuân thủ
   - Quét SAST/CodeQL trong CI/CD

3. **Kiểm Thử Toàn Diện**
   - 229 kiểm thử đơn vị backend (23.886 LOC)
   - 45 kiểm thử component frontend (3.864 LOC)
   - 31 bộ kiểm thử E2E (API + Web)
   - Hỗ trợ kiểm thử tích hợp

4. **Ngăn Xếp Công Nghệ Hiện Đại**
   - NestJS 11 với mẫu CQRS
   - Next.js 15 App Router
   - Prisma ORM với PostGIS
   - Typesense cho tìm kiếm
   - Zustand cho quản lý trạng thái

5. **DevOps & Giám Sát**
   - Hỗ trợ Docker đa môi trường
   - Stack giám sát đầy đủ (Prometheus, Grafana, Loki)
   - Pipeline CI/CD với quét bảo mật
   - Khả năng kiểm thử tải

6. **Chất Lượng Code**
   - Chế độ TypeScript strict
   - ESLint + Prettier bắt buộc
   - Không có comment TODO/FIXME/HACK
   - Phân tích dependency cruiser

### ⚠ NHẬN XÉT

1. **Cơ Sở Dữ Liệu**
   - 13 migrations trong 4 ngày cho thấy sự không ổn định của schema trong quá trình phát triển
   - Cân nhắc chiến lược migration dữ liệu cho môi trường sản xuất

2. **Độ Phủ Kiểm Thử**
   - 70.569 LOC với 229+45 tệp kiểm thử (~tỷ lệ tệp kiểm thử 0,4%)
   - Kiểm thử E2E bao gồm đường dẫn hạnh phúc, các trường hợp biên có thể cần mở rộng
   - Cân nhắc thêm mutation testing

3. **Tài Liệu**
   - README hạn chế
   - Tài liệu cấp module có thể được mở rộng
   - Có thể thêm ví dụ API vào tài liệu

4. **Giám Sát**
   - Stack giám sát đã triển khai nhưng các quy tắc cảnh báo cần xác minh
   - Mục tiêu SLO chưa được ghi lại tường minh

5. **Xác Thực**
   - Nhà cung cấp OAuth (Google, Zalo) đã được cấu hình nhưng logic làm mới token có thể cần thêm xác thực
   - Cân nhắc thêm hỗ trợ 2FA cho tài khoản admin

### KHUYẾN NGHỊ

1. **Danh Sách Kiểm Tra Trước Khi Sản Xuất**
   - Hoàn thiện schema cơ sở dữ liệu (dừng migrations mới)
   - Kiểm thử tải ở quy mô
   - Diễn tập khôi phục thảm họa
   - Kiểm thử xâm nhập bảo mật

2. **Điều Chỉnh Hiệu Năng**
   - Chiến lược warm-up cache
   - Phân tích truy vấn cơ sở dữ liệu (slow log)
   - Phân tích bundle frontend

3. **Sẵn Sàng Vận Hành**
   - Tạo runbook
   - Tài liệu lịch trực trực tuyến
   - Quy trình phản ứng sự cố
   - Chính sách lưu giữ log

4. **Tuân Thủ**
   - Xác minh tuân thủ GDPR (soft deletes, xuất dữ liệu)
   - Triển khai chính sách lưu giữ dữ liệu
   - Điều khoản dịch vụ / Chính sách bảo mật

---

## TRẠNG THÁI TRIỂN KHAI

**Trạng Thái Hiện Tại:** Phát triển/Staging
**Docker Compose:** ✓ Đã cấu hình đầy đủ
**CI/CD:** ✓ Pipeline GitHub Actions sẵn sàng
**Cơ Sở Dữ Liệu:** ✓ 13 migrations đã triển khai
**Giám Sát:** ✓ Stack đầy đủ có sẵn
**Quét Bảo Mật:** ✓ CodeQL + kiểm tra phụ thuộc

**Sẵn Sàng Cho Sản Xuất:** Chờ kiểm toán bảo mật cuối cùng & kiểm thử tải

---

**Báo Cáo Được Tạo:** 11 tháng 4, 2026
**Kiểm Toán Viên:** Claude Code
**Phạm Vi:** Phân tích codebase hoàn chỉnh