chore: update project documentation, audit reports, and initialize IDE configuration files

report/AUDIT_CTO_2026-04-18.md

@@ -1,129 +1,129 @@
-# AUDIT REPORT — GoodGo Platform AI
-**Date**: 2026-04-18  
-**CTO Audit Wave**: TEC-1915 (Wave 13)  
-**Language**: English (technical terms), Vietnamese OK  
-**Status**: Clean master branch, 1454 unit tests passing, all builds successful
+# BÁO CÁO KIỂM TOÁN — GoodGo Platform AI
+**Ngày**: 2026-04-18  
+**Đợt kiểm toán CTO**: TEC-1915 (Wave 13)  
+**Ngôn ngữ**: Tiếng Anh (thuật ngữ kỹ thuật), tiếng Việt OK  
+**Trạng thái**: Nhánh master sạch, 1454 unit test đang chạy thành công, tất cả bản build thành công
 
 ---
 
 ## 1. TỔNG QUAN DỰ ÁN (Project Overview)
 
-### Mission
-GoodGo Platform AI is Vietnam's intelligent real estate platform enabling:
-- **Property search & discovery** with AI-powered valuation (Automated Valuation Model)
-- **End-to-end transaction management** (KYC, payments, subscriptions, leads)
-- **Multi-stakeholder support**: Buyers, sellers, agents, admins
-- **AI/ML integration**: Claude API moderation, FastAPI XGBoost valuation, Underthesea NLP
-- **Developer-friendly**: MCP (Model Context Protocol) servers for AI tool integration
+### Sứ mệnh
+GoodGo Platform AI là nền tảng bất động sản thông minh của Việt Nam, cho phép:
+- **Tìm kiếm & khám phá bất động sản** với định giá hỗ trợ bởi AI (Automated Valuation Model)
+- **Quản lý giao dịch toàn diện** (KYC, thanh toán, đăng ký, leads)
+- **Hỗ trợ đa bên liên quan**: Người mua, người bán, môi giới, quản trị viên
+- **Tích hợp AI/ML**: Kiểm duyệt nội dung Claude API, định giá XGBoost FastAPI, NLP Underthesea
+- **Thân thiện với nhà phát triển**: Máy chủ MCP (Model Context Protocol) cho tích hợp công cụ AI
 
-### Market Focus
-- **Geographic**: Vietnam (Ho Chi Minh City, districts/wards in database)
-- **Currency**: Vietnamese Dong (VND)
-- **Payment partners**: VNPay, MoMo, ZaloPay
-- **Notifications**: Email (Nodemailer), SMS (Stringee), Push (FCM), In-App WebSocket
+### Phạm vi thị trường
+- **Địa lý**: Việt Nam (Thành phố Hồ Chí Minh, quận/phường trong cơ sở dữ liệu)
+- **Tiền tệ**: Đồng Việt Nam (VND)
+- **Đối tác thanh toán**: VNPay, MoMo, ZaloPay
+- **Thông báo**: Email (Nodemailer), SMS (Stringee), Push (FCM), Trong ứng dụng WebSocket
 
-### Project Maturity
-- **Version**: 1.4.0 (released 2026-04-08)
-- **Launch phase**: MVP complete, production-ready infrastructure in place
-- **Team**: Full-stack monorepo with clear module separation
-- **Timeline**: Started ~Q1 2026, 20+ commits/week acceleration in final sprints
+### Mức độ trưởng thành của dự án
+- **Phiên bản**: 1.4.0 (phát hành 2026-04-08)
+- **Giai đoạn ra mắt**: MVP hoàn chỉnh, hạ tầng sẵn sàng cho môi trường production
+- **Nhóm phát triển**: Monorepo full-stack với phân tách module rõ ràng
+- **Lịch trình**: Bắt đầu ~Q1 2026, tốc độ 20+ commit/tuần trong các sprint cuối
 
 ---
 
 ## 2. TIẾN ĐỘ PHÁT TRIỂN (Development Progress)
 
-### Version History & Completion Estimate
-| Phase | Version | Date | Key Features | Estimate |
-|-------|---------|------|--------------|----------|
-| **Foundation** | 1.0.0 | 2026-03-01 | Auth, listings CRUD, payments, search, notifications, MCP servers | ✓ 100% |
-| **Growth** | 1.1.0 | 2026-03-12 | Duplicate detection, subscriptions quota, OAuth, unit tests (58) | ✓ 100% |
-| **Maturity** | 1.2.0 | 2026-03-20 | React Query, dark mode, Redis cache, NLP pipeline, Prometheus, 200+ tests | ✓ 100% |
-| **Stability** | 1.3.0 | 2026-03-28 | Notifications delivery (multi-channel), reviews, reviews/ratings, district heatmap, 1200+ tests | ✓ 100% |
-| **Polish** | 1.4.0 | 2026-04-08 | Health checks, domain tests, property valuation UI, 1454 tests all passing | ✓ 100% |
-| **Current** | Unreleased | 2026-04-18 | Wave 13 CEO audit, industrial projects, messaging (WebSocket), transfer features, NeighborhoodScore AI service | ~85% |
+### Lịch sử phiên bản & Ước tính hoàn thành
+| Giai đoạn | Phiên bản | Ngày | Tính năng chính | Ước tính |
+|-----------|-----------|------|-----------------|----------|
+| **Nền tảng** | 1.0.0 | 2026-03-01 | Auth, listings CRUD, payments, search, notifications, MCP servers | ✓ 100% |
+| **Tăng trưởng** | 1.1.0 | 2026-03-12 | Phát hiện trùng lặp, hạn mức subscription, OAuth, unit tests (58) | ✓ 100% |
+| **Trưởng thành** | 1.2.0 | 2026-03-20 | React Query, dark mode, Redis cache, NLP pipeline, Prometheus, 200+ tests | ✓ 100% |
+| **Ổn định** | 1.3.0 | 2026-03-28 | Gửi thông báo (đa kênh), reviews, đánh giá/xếp hạng, heatmap quận, 1200+ tests | ✓ 100% |
+| **Hoàn thiện** | 1.4.0 | 2026-04-08 | Health checks, domain tests, giao diện định giá bất động sản, 1454 tests đều pass | ✓ 100% |
+| **Hiện tại** | Chưa phát hành | 2026-04-18 | Kiểm toán CEO Wave 13, dự án công nghiệp, messaging (WebSocket), tính năng chuyển nhượng, dịch vụ AI NeighborhoodScore | ~85% |
 
-### Changelog Highlights (Last 30 Days)
-- ✅ 725 ESLint errors fixed (712 auto-fixable) — Wave 11D
-- ✅ TypeScript strict mode applied, 7 web test type errors resolved
-- ✅ 27 rate-limit guard tests fixed — guard retry logic verified
-- ✅ Health/metrics/mcp modules completed (were stubs)
-- ✅ MCP servers property search + valuation fully implemented
-- ✅ Industrial parks & industrial listings modules added
-- ✅ Messaging module (conversations, WebSocket) added
-- ✅ Transfer/escrow management for transactions
-- ✅ Neighborhood score ML service (Python FastAPI)
-- ✅ Featured listings feature flag + admin promotion workflow
-- ✅ KYC presigned uploads with validation
+### Điểm nổi bật Changelog (30 ngày qua)
+- ✅ 725 lỗi ESLint đã sửa (712 tự động sửa) — Wave 11D
+- ✅ Áp dụng TypeScript strict mode, giải quyết 7 lỗi kiểu trong web tests
+- ✅ Sửa 27 bài kiểm thử guard rate-limit — xác minh logic retry của guard
+- ✅ Hoàn thành các module health/metrics/mcp (trước đó là stub)
+- ✅ MCP servers property search + valuation được triển khai đầy đủ
+- ✅ Thêm module khu công nghiệp & danh sách bất động sản công nghiệp
+- ✅ Thêm module messaging (conversations, WebSocket)
+- ✅ Quản lý chuyển nhượng/ký quỹ cho giao dịch
+- ✅ Dịch vụ ML điểm số khu dân cư (Python FastAPI)
+- ✅ Feature flag danh sách nổi bật + quy trình quản lý quảng bá
+- ✅ Tải lên KYC có presigned URL với xác thực
 
-### Development Velocity
-- **Commits/week**: 8-12 (increasing toward launch)
-- **Bug fix rate**: ~15-20% of commits are fixes
-- **Feature/fix ratio**: ~70% features, 30% bug fixes + tech debt
-- **Zero breaking changes** in changelog (backward-compatible releases)
+### Tốc độ phát triển
+- **Commit/tuần**: 8-12 (tăng dần về phía ra mắt)
+- **Tỷ lệ sửa lỗi**: ~15-20% commit là bản vá lỗi
+- **Tỷ lệ tính năng/vá lỗi**: ~70% tính năng mới, 30% sửa lỗi + nợ kỹ thuật
+- **Không có breaking change** trong changelog (phát hành tương thích ngược)
 
 ---
 
 ## 3. TECH STACK & ARCHITECTURE
 
-### Runtime & Package Management
-- **Node.js**: ≥ 22.0.0 LTS (verified in .nvmrc, package.json engines)
-- **Package Manager**: pnpm 10.27.0 (strict lockfile, workspace hoisting)
-- **Monorepo**: Turborepo + pnpm workspaces (3 app dirs, 2 lib dirs)
+### Runtime & Quản lý gói
+- **Node.js**: ≥ 22.0.0 LTS (đã xác minh trong .nvmrc, package.json engines)
+- **Package Manager**: pnpm 10.27.0 (lockfile nghiêm ngặt, workspace hoisting)
+- **Monorepo**: Turborepo + pnpm workspaces (3 thư mục app, 2 thư mục lib)
 
-### Workspace Structure (pnpm-workspace.yaml)
+### Cấu trúc Workspace (pnpm-workspace.yaml)
 ```
 packages:
   - 'apps/*'          # API (NestJS) + Web (Next.js)
-  - 'packages/*'      # (empty, reserved for future shared packages)
+  - 'packages/*'      # (trống, dành cho các shared packages trong tương lai)
   - 'libs/*'          # AI services (Python), MCP servers (TypeScript)
 ```
 
 ### Backend — NestJS 11 (apps/api)
-- **Architecture**: CQRS (Commands/Queries), DDD (Domain-Driven Design)
-- **Key patterns**: Domain exceptions (no NestJS exceptions), Result<T, E> pattern, Redis cache service
-- **Modules**: 20 modules (auth, listings, search, payments, admin, analytics, notifications, etc.)
-- **Controllers**: 28 controllers, 162+ HTTP endpoints (GET, POST, PUT, PATCH, DELETE)
-- **Logging**: Pino structured JSON with PII masking
+- **Kiến trúc**: CQRS (Commands/Queries), DDD (Domain-Driven Design)
+- **Pattern chính**: Domain exceptions (không dùng NestJS exceptions), pattern Result<T, E>, Redis cache service
+- **Module**: 20 module (auth, listings, search, payments, admin, analytics, notifications, v.v.)
+- **Controller**: 28 controller, 162+ HTTP endpoint (GET, POST, PUT, PATCH, DELETE)
+- **Logging**: Pino structured JSON với che giấu PII
 
 ### Frontend — Next.js 15 (apps/web)
 - **Framework**: App Router (SSR + SSG)
 - **UI**: React 18 + Tailwind CSS 3
-- **State**: Zustand for global auth/filter state
-- **Data fetching**: React Query 5 with retry logic
-- **Maps**: Mapbox GL for geo-visualization
-- **Testing**: Vitest + Playwright E2E
+- **State**: Zustand cho trạng thái auth/filter toàn cục
+- **Lấy dữ liệu**: React Query 5 với logic retry
+- **Bản đồ**: Mapbox GL cho trực quan hóa địa lý
+- **Kiểm thử**: Vitest + Playwright E2E
 
 ### Database — PostgreSQL 16 + PostGIS 3.4
-- **Models**: 38 Prisma models (User, Property, Listing, Payment, Subscription, etc.)
-- **Migrations**: Versioned in `prisma/migrations/`
-- **Geospatial**: PostGIS GIST indexes on location geometry (lat/long radius queries)
+- **Model**: 38 Prisma model (User, Property, Listing, Payment, Subscription, v.v.)
+- **Migration**: Versioned trong `prisma/migrations/`
+- **Không gian địa lý**: GIST index PostGIS trên cột geometry vị trí (truy vấn bán kính lat/long)
 - **ORM**: Prisma 7.7.0 (type-safe, generated client)
-- **Connection pooling**: PgBouncer 1.18 for production
+- **Connection pooling**: PgBouncer 1.18 cho môi trường production
 
 ### Search — Typesense 27
-- **Features**: Full-text search (Vietnamese tokenizer), faceting, geo-distance filters
-- **Integration**: Event-driven (listing approved/updated/sold → re-index)
-- **Performance**: Sub-100ms p95 for typical queries
+- **Tính năng**: Tìm kiếm full-text (tokenizer tiếng Việt), faceting, bộ lọc khoảng cách địa lý
+- **Tích hợp**: Hướng sự kiện (listing approved/updated/sold → re-index)
+- **Hiệu suất**: p95 dưới 100ms cho các truy vấn thông thường
 
 ### Cache — Redis 7
-- **Use cases**: Quota tracking, search result caching, session data, rate limiting
-- **Persistence**: AOF (appendonly) enabled
-- **Strategy**: Prefix-based cache invalidation on listing changes
+- **Trường hợp sử dụng**: Theo dõi hạn mức, cache kết quả tìm kiếm, dữ liệu phiên, rate limiting
+- **Persistence**: AOF (appendonly) được bật
+- **Chiến lược**: Cache invalidation dựa trên prefix khi thay đổi listing
 
-### Storage — MinIO (S3-compatible)
-- **API**: Port 9000, Console: Port 9001
-- **Setup**: Auto-init bucket on startup
-- **Features**: Presigned URLs for secure uploads (no leaked credentials)
+### Storage — MinIO (tương thích S3)
+- **API**: Cổng 9000, Console: Cổng 9001
+- **Thiết lập**: Tự động khởi tạo bucket khi khởi động
+- **Tính năng**: Presigned URL cho tải lên an toàn (không rò rỉ thông tin xác thực)
 
-### AI Services — Python FastAPI (libs/ai-services)
-| Endpoint | Purpose | Tech |
-|----------|---------|------|
-| `/avm/v1/estimate` | Residential valuation | XGBoost |
-| `/avm/v2/*` | Enhanced valuation + feature importance | XGBoost v2 |
-| `/avm/industrial/*` | Industrial property valuation | XGBoost |
-| `/moderation/score` | Content moderation | Claude API |
-| `/nlp/analyze` | Vietnamese NLP | Underthesea |
-| `/neighborhood/score` | Neighborhood quality scoring | ML model |
+### Dịch vụ AI — Python FastAPI (libs/ai-services)
+| Endpoint | Mục đích | Công nghệ |
+|----------|----------|-----------|
+| `/avm/v1/estimate` | Định giá bất động sản dân cư | XGBoost |
+| `/avm/v2/*` | Định giá nâng cao + tầm quan trọng đặc trưng | XGBoost v2 |
+| `/avm/industrial/*` | Định giá bất động sản công nghiệp | XGBoost |
+| `/moderation/score` | Kiểm duyệt nội dung | Claude API |
+| `/nlp/analyze` | NLP tiếng Việt | Underthesea |
+| `/neighborhood/score` | Chấm điểm chất lượng khu dân cư | ML model |
 
 ### MCP Servers (libs/mcp-servers)
 - **Property Search**: search_properties, compare_properties, get_property_details
@@ -131,83 +131,83 @@ packages:
 - **Valuation**: estimate_valuation, extract_features, compare_valuations
 - **Industrial Parks**: list_parks, get_park_details, search_available_units
 
-### Monitoring Stack
-- **Prometheus** (port 9090): Metrics scraping (HTTP latency, errors, requests/sec)
-- **Grafana** (port 3002): Dashboards (request volume, error rates, API p95)
-- **Loki** (port 3100): Log aggregation (JSON structured logs)
-- **Sentry**: Error tracking & performance monitoring
+### Stack giám sát
+- **Prometheus** (cổng 9090): Thu thập metrics (độ trễ HTTP, lỗi, requests/giây)
+- **Grafana** (cổng 3002): Dashboard (lưu lượng request, tỷ lệ lỗi, API p95)
+- **Loki** (cổng 3100): Tổng hợp log (JSON structured logs)
+- **Sentry**: Theo dõi lỗi & giám sát hiệu suất
 
 ---
 
 ## 4. MODULES CHI TIẾT (Detailed Module Breakdown)
 
-### API Modules (20 modules, 28 controllers, 145+ CQRS handlers)
+### API Modules (20 module, 28 controller, 145+ CQRS handler)
 
-| Module | Purpose | Key Features |
-|--------|---------|--------------|
-| **auth** | User registration, login, JWT + refresh tokens, OAuth, MFA, KYC | 4 controllers, phone/password + Google/Zalo OAuth, TOTP 2FA, KYC workflow |
-| **listings** | Property CRUD, status workflow, media management | Quota-gated creation, AI moderation, event-driven search indexing, featured listings |
-| **search** | Full-text + geo-spatial search, saved searches | Typesense integration, PostGIS radius queries, prefix-based caching, Vietnamese tokenizer |
-| **payments** | VNPay, MoMo, ZaloPay integration with idempotent webhooks | Order creation, webhook verification, refund support, event emission |
-| **subscriptions** | Plans, quotas, usage tracking, feature flags | Tiered plans (JSON features), Redis-backed quota metering, plan upgrades |
-| **admin** | Moderation, user management, KYC approval, audit logs | Dashboard stats, listing moderation queue, user ban/unban, revenue analytics |
-| **analytics** | Market reports, price trends, district heatmaps, AVM | PostGIS spatial aggregation, trend analysis, district heatmap visualization |
-| **notifications** | Multi-channel delivery (email, SMS, push, in-app) | 8 event listeners, Handlebars templates, user preferences, WebSocket real-time |
-| **reviews** | Property/agent reviews with 1-5 star ratings | Polymorphic target (property OR agent), average rating aggregation |
-| **inquiries** | Buyer interest in property, seller response workflow | Status: NEW → RESPONDED → ACCEPTED/DECLINED, quota-gated |
-| **leads** | Lead tracking, agent assignment, quality scoring | Status: OPEN → CONTACTED → CONVERTED/LOST, auto-scoring |
-| **agents** | Agent profile, license, service areas, quality score | Verification, metrics tracking (deals, response time), dashboard |
-| **messaging** | Real-time conversations, messages, typing indicators | WebSocket gateway, persistence in database, media support |
-| **transfer** | Escrow management, transaction workflow | Buyer → escrow → seller verification → release, status tracking |
-| **industrial** | Industrial parks & listings, industrial AVM | Park CRUD, available units tracking, separate industrial valuation model |
-| **projects** | Project developments (master plans, unit availability) | Status: PLANNING → UNDER_CONSTRUCTION → COMPLETED → HANDOVER, amenities JSON |
-| **health** | Liveness/readiness probes | Endpoints: /health, /health/db, /health/redis, /health/search |
-| **metrics** | Prometheus metrics, web vitals collection | HTTP latency histogram, error counter, custom business metrics |
-| **mcp** | MCP HTTP bridge, tool server registry | JWT auth, tool discovery, rate limiting (20 req/min) |
-| **shared** | Cross-cutting concerns | Guards (auth, roles, rate limiting), pipes, exception filter, DDD value objects |
+| Module | Mục đích | Tính năng chính |
+|--------|----------|-----------------|
+| **auth** | Đăng ký người dùng, đăng nhập, JWT + refresh token, OAuth, MFA, KYC | 4 controller, số điện thoại/mật khẩu + Google/Zalo OAuth, TOTP 2FA, quy trình KYC |
+| **listings** | CRUD bất động sản, quy trình trạng thái, quản lý media | Tạo theo hạn mức, kiểm duyệt AI, đánh chỉ mục tìm kiếm hướng sự kiện, danh sách nổi bật |
+| **search** | Tìm kiếm full-text + địa lý, tìm kiếm đã lưu | Tích hợp Typesense, truy vấn bán kính PostGIS, cache dựa trên prefix, tokenizer tiếng Việt |
+| **payments** | Tích hợp VNPay, MoMo, ZaloPay với idempotent webhooks | Tạo đơn hàng, xác minh webhook, hỗ trợ hoàn tiền, phát sự kiện |
+| **subscriptions** | Gói dịch vụ, hạn mức, theo dõi sử dụng, feature flag | Gói phân cấp (JSON features), đo lường hạn mức dựa trên Redis, nâng cấp gói |
+| **admin** | Kiểm duyệt, quản lý người dùng, phê duyệt KYC, nhật ký kiểm toán | Thống kê dashboard, hàng đợi kiểm duyệt listing, ban/unban người dùng, phân tích doanh thu |
+| **analytics** | Báo cáo thị trường, xu hướng giá, heatmap quận, AVM | Tổng hợp không gian PostGIS, phân tích xu hướng, trực quan hóa heatmap quận |
+| **notifications** | Gửi đa kênh (email, SMS, push, trong ứng dụng) | 8 event listener, template Handlebars, tùy chọn người dùng, thời gian thực WebSocket |
+| **reviews** | Đánh giá bất động sản/môi giới với xếp hạng 1-5 sao | Đích polymorphic (bất động sản HOẶC môi giới), tổng hợp xếp hạng trung bình |
+| **inquiries** | Quan tâm của người mua đến bất động sản, quy trình phản hồi của người bán | Trạng thái: NEW → RESPONDED → ACCEPTED/DECLINED, giới hạn theo hạn mức |
+| **leads** | Theo dõi lead, phân công môi giới, chấm điểm chất lượng | Trạng thái: OPEN → CONTACTED → CONVERTED/LOST, tự động chấm điểm |
+| **agents** | Hồ sơ môi giới, giấy phép, khu vực dịch vụ, điểm chất lượng | Xác minh, theo dõi metrics (giao dịch, thời gian phản hồi), dashboard |
+| **messaging** | Cuộc trò chuyện thời gian thực, tin nhắn, chỉ báo đang gõ | WebSocket gateway, lưu trữ trong database, hỗ trợ media |
+| **transfer** | Quản lý ký quỹ, quy trình giao dịch | Người mua → ký quỹ → xác minh người bán → giải phóng, theo dõi trạng thái |
+| **industrial** | Khu công nghiệp & danh sách, AVM công nghiệp | CRUD khu công nghiệp, theo dõi đơn vị sẵn có, mô hình định giá công nghiệp riêng |
+| **projects** | Dự án phát triển (quy hoạch tổng thể, tình trạng căn hộ) | Trạng thái: PLANNING → UNDER_CONSTRUCTION → COMPLETED → HANDOVER, JSON tiện ích |
+| **health** | Probe liveness/readiness | Endpoint: /health, /health/db, /health/redis, /health/search |
+| **metrics** | Prometheus metrics, thu thập web vitals | HTTP latency histogram, bộ đếm lỗi, business metrics tùy chỉnh |
+| **mcp** | MCP HTTP bridge, registry công cụ máy chủ | JWT auth, khám phá công cụ, rate limiting (20 req/min) |
+| **shared** | Mối quan tâm xuyên suốt | Guard (auth, roles, rate limiting), pipes, exception filter, DDD value objects |
 
-### Frontend Pages (apps/web/app/)
-- `/` — Homepage (solutions, featured listings, featured projects)
-- `/search` — Advanced search (map, filters, saved searches)
-- `/properties/[id]` — Listing detail (gallery, price, agent, reviews, map)
-- `/agents/[id]` — Agent profile (listings, reviews, inquiries, quality score)
-- `/dashboard` — User dashboard (listings, inquiries, reviews, KYC status)
-- `/admin` — Admin panel (moderation queue, user management, revenue stats)
-- `/auth/login` — Login (phone + password or OAuth)
-- `/auth/register` — Registration
-- `/auth/kyc` — KYC verification (doc upload, presigned URLs)
-- `/valuation` — AVM property valuation UI (form input, model output, feature importance)
-- `/projects` — Residential projects showcase (`residential_projects` feature flag)
-- `/du-an` — Project details (units available, pricing, timeline)
-- `/chat` — Messaging (conversations list, message thread)
+### Trang Frontend (apps/web/app/)
+- `/` — Trang chủ (giải pháp, danh sách nổi bật, dự án nổi bật)
+- `/search` — Tìm kiếm nâng cao (bản đồ, bộ lọc, tìm kiếm đã lưu)
+- `/properties/[id]` — Chi tiết listing (thư viện ảnh, giá, môi giới, đánh giá, bản đồ)
+- `/agents/[id]` — Hồ sơ môi giới (danh sách, đánh giá, yêu cầu, điểm chất lượng)
+- `/dashboard` — Dashboard người dùng (danh sách, yêu cầu, đánh giá, trạng thái KYC)
+- `/admin` — Bảng quản trị (hàng đợi kiểm duyệt, quản lý người dùng, thống kê doanh thu)
+- `/auth/login` — Đăng nhập (số điện thoại + mật khẩu hoặc OAuth)
+- `/auth/register` — Đăng ký
+- `/auth/kyc` — Xác minh KYC (tải lên tài liệu, presigned URL)
+- `/valuation` — Giao diện định giá bất động sản AVM (nhập form, đầu ra mô hình, tầm quan trọng đặc trưng)
+- `/projects` — Trình bày dự án dân cư (feature flag `residential_projects`)
+- `/du-an` — Chi tiết dự án (căn hộ sẵn có, giá, lịch trình)
+- `/chat` — Nhắn tin (danh sách cuộc trò chuyện, chuỗi tin nhắn)
 
-### Database Schema (38 models)
-**Core entities**: User (with MFA), Listing, Property, Payment, Subscription, Inquiry, Lead, Review, Transaction, Escrow, TransferListing, ProjectDevelopment, IndustrialPark, Conversation, Message, and more.
+### Schema Database (38 model)
+**Thực thể cốt lõi**: User (với MFA), Listing, Property, Payment, Subscription, Inquiry, Lead, Review, Transaction, Escrow, TransferListing, ProjectDevelopment, IndustrialPark, Conversation, Message, và nhiều hơn nữa.
 
-**Key patterns**:
-- **Geospatial**: PostGIS geometry columns on Property, ProjectDevelopment (GIST indexes)
-- **JSON columns**: Amenities, features (subscription plans), nearbyPOIs, tags
-- **Status workflows**: ListingStatus (DRAFT → PENDING_REVIEW → ACTIVE → SOLD/RENTED)
-- **Polymorphism**: Review.targetId + targetType (property OR agent)
-- **Audit trail**: AdminAuditLog (who, what, when, before/after JSON)
+**Pattern chính**:
+- **Địa lý không gian**: Cột geometry PostGIS trên Property, ProjectDevelopment (GIST index)
+- **Cột JSON**: Amenities, features (gói subscription), nearbyPOIs, tags
+- **Quy trình trạng thái**: ListingStatus (DRAFT → PENDING_REVIEW → ACTIVE → SOLD/RENTED)
+- **Đa hình**: Review.targetId + targetType (bất động sản HOẶC môi giới)
+- **Dấu vết kiểm toán**: AdminAuditLog (ai, làm gì, khi nào, JSON trước/sau)
 
 ---
 
 ## 5. API HIỆN HÀNH (Current API Endpoints)
 
-### Endpoint Summary
-- **Total**: 162+ HTTP endpoints
-- **Commands**: 83 (write operations)
-- **Queries**: 62 (read operations)
-- **Prefix**: `/api/v1/`
+### Tóm tắt Endpoint
+- **Tổng cộng**: 162+ HTTP endpoint
+- **Command**: 83 (thao tác ghi)
+- **Query**: 62 (thao tác đọc)
+- **Tiền tố**: `/api/v1/`
 
 ### Rate Limiting
-- **Default**: 60 req/min per IP
-- **Auth**: 10 req/min (login, register)
-- **Payments**: 20 req/min (webhook callbacks)
-- **MCP**: 20 req/min (AI service backend)
+- **Mặc định**: 60 req/min mỗi IP
+- **Auth**: 10 req/min (đăng nhập, đăng ký)
+- **Payments**: 20 req/min (webhook callback)
+- **MCP**: 20 req/min (backend dịch vụ AI)
 
-### Response Format
+### Định dạng phản hồi
 ```json
 {
   "status": "success" | "error",
@@ -223,17 +223,17 @@ packages:
 ## 6. DATABASE & SCHEMA
 
 ### PostgreSQL 16 + PostGIS 3.4
-- **Models**: 38 Prisma models
-- **Migrations**: Versioned in `prisma/migrations/`
-- **Indexing**: Strategic indexes on status, user relationships, geospatial queries
-- **Seed data**: Districts, sample properties, subscription plans, test users
+- **Model**: 38 Prisma model
+- **Migration**: Versioned trong `prisma/migrations/`
+- **Indexing**: Index chiến lược trên status, quan hệ người dùng, truy vấn địa lý
+- **Dữ liệu seed**: Quận, bất động sản mẫu, gói subscription, người dùng kiểm thử
 
-### Key Models
-**Auth**: User (with MFA: TOTP, backup codes), RefreshToken, OAuthAccount, MfaChallenge
+### Model chính
+**Auth**: User (với MFA: TOTP, mã dự phòng), RefreshToken, OAuthAccount, MfaChallenge
 
-**Listings**: Property (title, description, geolocation, amenities), Listing (status workflow), PropertyMedia, PriceHistory, SavedSearch
+**Listings**: Property (tiêu đề, mô tả, vị trí địa lý, tiện ích), Listing (quy trình trạng thái), PropertyMedia, PriceHistory, SavedSearch
 
-**Marketplace**: Inquiry, Lead, Review (polymorphic: property OR agent), Agent
+**Marketplace**: Inquiry, Lead, Review (đa hình: bất động sản HOẶC môi giới), Agent
 
 **Payments**: Payment (VNPay/MoMo/ZaloPay), Order, Escrow, Transaction, TransferListing
 
@@ -241,7 +241,7 @@ packages:
 
 **Projects**: ProjectDevelopment, IndustrialPark, IndustrialListing
 
-**Analytics**: Valuation (AVM results), MarketIndex, NeighborhoodScore
+**Analytics**: Valuation (kết quả AVM), MarketIndex, NeighborhoodScore
 
 **Messaging**: Conversation, ConversationParticipant, Message
 
@@ -252,207 +252,206 @@ packages:
 ## 7. AI FEATURES
 
 ### 1. Automated Valuation Model (AVM)
-- **Model**: XGBoost (residential, v2, industrial variants)
-- **Input**: Property attributes (type, bedrooms, area), location (district, proximity to metro), market data
-- **Output**: Estimated price (VND), confidence interval (±15%), feature importance
-- **Integration**: FastAPI at `/avm/v1/estimate` → NestJS proxy at `/api/v1/avm/valuation`
-- **Performance**: p95 < 500ms
-- **Web UI**: Property valuation form + result visualization
+- **Mô hình**: XGBoost (dân cư, v2, biến thể công nghiệp)
+- **Đầu vào**: Thuộc tính bất động sản (loại, số phòng ngủ, diện tích), vị trí (quận, khoảng cách đến metro), dữ liệu thị trường
+- **Đầu ra**: Giá ước tính (VND), khoảng tin cậy (±15%), tầm quan trọng đặc trưng
+- **Tích hợp**: FastAPI tại `/avm/v1/estimate` → NestJS proxy tại `/api/v1/avm/valuation`
+- **Hiệu suất**: p95 < 500ms
+- **Giao diện web**: Form định giá bất động sản + trực quan hóa kết quả
 
-### 2. Content Moderation (Claude API)
-- **Purpose**: Scan listing descriptions for prohibited content (spam, offensive, fake promises)
-- **Scoring**: 0-100 (reject > 75)
-- **Triggered**: On listing creation/update (before PENDING_REVIEW status)
-- **Result**: Stored in Valuation model (for admin review)
-- **Fallback**: Default to PENDING_REVIEW if Claude API fails
+### 2. Kiểm duyệt nội dung (Claude API)
+- **Mục đích**: Quét mô tả listing để tìm nội dung bị cấm (spam, xúc phạm, hứa hẹn giả)
+- **Chấm điểm**: 0-100 (từ chối > 75)
+- **Kích hoạt**: Khi tạo/cập nhật listing (trước trạng thái PENDING_REVIEW)
+- **Kết quả**: Lưu trong model Valuation (để admin xem xét)
+- **Dự phòng**: Mặc định về PENDING_REVIEW nếu Claude API thất bại
 
-### 3. Vietnamese NLP Pipeline (Underthesea)
-- **Tasks**: Tokenization, POS tagging, named entity recognition, sentiment analysis
-- **Integration**: POST `/nlp/analyze` → FastAPI routes
-- **Use cases**: Auto-tag amenities, detect suspicious language, search enhancement
+### 3. NLP Pipeline tiếng Việt (Underthesea)
+- **Tác vụ**: Tách từ, gán nhãn từ loại, nhận dạng thực thể có tên, phân tích cảm xúc
+- **Tích hợp**: POST `/nlp/analyze` → FastAPI routes
+- **Trường hợp sử dụng**: Tự động gắn thẻ tiện ích, phát hiện ngôn ngữ đáng ngờ, cải thiện tìm kiếm
 
-### 4. Neighborhood Quality Scoring
-- **Features**: Metro/bus distance, POI density, crime stats, market activity
-- **Output**: Score 0-100 per category (walkability, safety, amenities, market)
-- **Integration**: POST `/neighborhood/score` → FastAPI
-- **Caching**: Cached by location (rounded lat/long) for 1 hour
+### 4. Chấm điểm chất lượng khu dân cư
+- **Đặc trưng**: Khoảng cách metro/xe buýt, mật độ POI, thống kê tội phạm, hoạt động thị trường
+- **Đầu ra**: Điểm 0-100 mỗi danh mục (khả năng đi bộ, an toàn, tiện ích, thị trường)
+- **Tích hợp**: POST `/neighborhood/score` → FastAPI
+- **Cache**: Cache theo vị trí (lat/long làm tròn) trong 1 giờ
 
 ### 5. MCP (Model Context Protocol) Tools
-- **Tools**: search_properties, estimate_valuation, get_market_report, analyze_trends, get_price_indices
-- **Transport**: HTTP controller at `/api/v1/mcp/tools/*` (requires JWT)
-- **Use case**: LLMs can autonomously search properties + analyze market via MCP protocol
+- **Công cụ**: search_properties, estimate_valuation, get_market_report, analyze_trends, get_price_indices
+- **Transport**: HTTP controller tại `/api/v1/mcp/tools/*` (yêu cầu JWT)
+- **Trường hợp sử dụng**: LLM có thể tự động tìm kiếm bất động sản + phân tích thị trường qua giao thức MCP
 
 ---
 
 ## 8. QUALITY POSTURE
 
-### Testing Coverage
-| Test Type | Count | Status |
-|-----------|-------|--------|
-| **Unit tests (API)** | 290 spec.ts files | ✅ All pass (1454 total) |
-| **Unit tests (Web)** | 7 spec.tsx files | ⚠️ Need 50+ for 60% coverage |
-| **Unit tests (MCP)** | 4 test files | ✅ All pass |
-| **E2E tests (API)** | 17 files | ✅ All pass |
-| **E2E tests (Web)** | 16 files | ✅ All pass |
+### Độ phủ kiểm thử
+| Loại kiểm thử | Số lượng | Trạng thái |
+|---------------|----------|------------|
+| **Unit tests (API)** | 290 file spec.ts | ✅ Tất cả pass (tổng 1454) |
+| **Unit tests (Web)** | 7 file spec.tsx | ⚠️ Cần 50+ để đạt 60% coverage |
+| **Unit tests (MCP)** | 4 file test | ✅ Tất cả pass |
+| **E2E tests (API)** | 17 file | ✅ Tất cả pass |
+| **E2E tests (Web)** | 16 file | ✅ Tất cả pass |
 
-### QA Results (2026-04-12)
+### Kết quả QA (2026-04-12)
 ```
-✓ ESLint: PASS (0 errors, 725 fixed)
-✓ TypeScript: 7 warnings (web test types)
-✓ Unit Tests: 1454 passing, 0 failing
-✓ Build: All 3 packages build successfully
-✓ Git: Clean working tree
+✓ ESLint: PASS (0 lỗi, 725 đã sửa)
+✓ TypeScript: 7 cảnh báo (kiểu web test)
+✓ Unit Tests: 1454 pass, 0 fail
+✓ Build: Tất cả 3 gói build thành công
+✓ Git: Working tree sạch
 ```
 
 ### CI/CD Pipeline
-1. **Lint** (ESLint on all .ts/.tsx)
-2. **TypeScript** type checking
+1. **Lint** (ESLint trên tất cả .ts/.tsx)
+2. Kiểm tra kiểu **TypeScript**
 3. **Unit tests** (Vitest)
-4. **Build** (Turborepo, all packages)
-5. **Additional**: Backup verification, load testing, dependency scanning
+4. **Build** (Turborepo, tất cả gói)
+5. **Bổ sung**: Xác minh sao lưu, kiểm thử tải, quét phụ thuộc
 
 ### Load Testing (K6)
-- **Suites**: 7 critical paths (auth, listings, search, admin, mcp, payments, advanced search)
-- **SLA thresholds**: p50 < 200ms, p95 < 500ms, p99 < 1000ms, error rate < 1%
-- **Status**: ✅ All thresholds met
+- **Bộ kiểm thử**: 7 đường dẫn quan trọng (auth, listings, search, admin, mcp, payments, advanced search)
+- **Ngưỡng SLA**: p50 < 200ms, p95 < 500ms, p99 < 1000ms, tỷ lệ lỗi < 1%
+- **Trạng thái**: ✅ Tất cả ngưỡng đạt yêu cầu
 
 ---
 
 ## 9. ROADMAP ĐỀ XUẤT
 
-### Phase 1: MVP Hardening (2 weeks) — IMMEDIATE
-1. ✅ Fix TypeScript warnings in web tests
-2. ✅ Add 50+ unit tests for web components (60% coverage)
-3. ✅ Implement field-level PII encryption (phone, email)
-4. ✅ Enable MFA for agent/admin accounts (TOTP required)
-5. ✅ Complete E2E test coverage (33/50 critical paths)
+### Giai đoạn 1: Củng cố MVP (2 tuần) — NGAY LẬP TỨC
+1. ✅ Sửa cảnh báo TypeScript trong web tests
+2. ✅ Thêm 50+ unit test cho web component (60% coverage)
+3. ✅ Triển khai mã hóa PII cấp trường (số điện thoại, email)
+4. ✅ Bật MFA cho tài khoản agent/admin (bắt buộc TOTP)
+5. ✅ Hoàn thiện độ phủ E2E test (33/50 đường dẫn quan trọng)
 
-### Phase 2: Security Hardening (2 weeks)
-1. API rate limiting per endpoint (not just global)
-2. Request signing for MCP tool calls (HMAC-SHA256)
-3. Input validation for GeoJSON coordinates
-4. Comprehensive audit logging (all data access)
-5. Secrets rotation (JWT secret → 90-day rotation)
-6. WAF rules in Nginx (SQL injection, XSS prevention)
+### Giai đoạn 2: Tăng cường bảo mật (2 tuần)
+1. Rate limiting API theo từng endpoint (không chỉ toàn cục)
+2. Ký yêu cầu cho lời gọi công cụ MCP (HMAC-SHA256)
+3. Xác thực đầu vào cho tọa độ GeoJSON
+4. Ghi nhật ký kiểm toán toàn diện (tất cả truy cập dữ liệu)
+5. Luân chuyển secret (JWT secret → luân chuyển 90 ngày)
+6. WAF rules trong Nginx (ngăn chặn SQL injection, XSS)
 
-### Phase 3: Feature Expansion (4 weeks)
-1. Live offer/counter-offer chat (WebSocket)
-2. ML-powered property recommendations
-3. React Native mobile app
-4. Property video upload + HLS streaming
-5. Virtual staging (AR renovations with AI image generation)
+### Giai đoạn 3: Mở rộng tính năng (4 tuần)
+1. Chat đề nghị/phản đề nghị trực tiếp (WebSocket)
+2. Gợi ý bất động sản dựa trên ML
+3. Ứng dụng di động React Native
+4. Tải lên video bất động sản + HLS streaming
+5. Dàn dựng ảo (cải tạo AR với AI tạo ảnh)
 
-### Phase 4: Operations & Scale (4 weeks)
-1. Multi-region deployment (Vietnam + Singapore failover)
-2. Database read replicas
-3. CDN integration (Cloudflare)
-4. SMS gateway redundancy
-5. Automated backups → S3
+### Giai đoạn 4: Vận hành & Mở rộng quy mô (4 tuần)
+1. Triển khai đa vùng (Việt Nam + Singapore failover)
+2. Read replica database
+3. Tích hợp CDN (Cloudflare)
+4. Dự phòng cổng SMS
+5. Sao lưu tự động → S3
 
-### Phase 5: Intelligence (2 months)
-1. Predictive pricing (LLM-powered negotiation suggestions)
-2. Fraud detection (XGBoost classifier)
-3. Buyer/seller auto-matching (NLP preferences)
-4. Market forecasting (ARIMA + LLM trend analysis)
-5. Vietnamese chatbot (customer support)
+### Giai đoạn 5: Thông minh hóa (2 tháng)
+1. Định giá dự đoán (gợi ý đàm phán dựa trên LLM)
+2. Phát hiện gian lận (bộ phân loại XGBoost)
+3. Ghép đôi người mua/người bán tự động (tùy chọn NLP)
+4. Dự báo thị trường (ARIMA + phân tích xu hướng LLM)
+5. Chatbot tiếng Việt (hỗ trợ khách hàng)
 
 ---
 
 ## 10. RISKS & ISSUES
 
-### Critical Issues
-| Issue | Severity | Status | Mitigation |
-|-------|----------|--------|-----------|
-| **No field-level PII encryption** | 🔴 HIGH | Open | Implement cell-level encryption (phone, email) |
-| **MFA not enforced for agents/admins** | 🔴 HIGH | Open | Require TOTP on first admin login |
-| **Web unit test coverage < 10%** | 🟡 MEDIUM | Open | Target 50+ unit tests + 60% coverage |
-| **Per-endpoint rate limiting missing** | 🟡 MEDIUM | Open | Fine-grained rate limits (register 3/min, login 5/min) |
-| **Load test baseline outdated** | 🟡 MEDIUM | Open | Re-establish post-industrial-avm features |
-| **Industrial AVM model may be overfitting** | 🟡 MEDIUM | Open | Collect 1000+ industrial property records |
+### Vấn đề quan trọng
+| Vấn đề | Mức độ | Trạng thái | Biện pháp giảm thiểu |
+|--------|--------|------------|----------------------|
+| **Không có mã hóa PII cấp trường** | 🔴 CAO | Mở | Triển khai mã hóa cấp ô (số điện thoại, email) |
+| **MFA chưa bắt buộc cho agent/admin** | 🔴 CAO | Mở | Yêu cầu TOTP khi đăng nhập admin lần đầu |
+| **Độ phủ unit test web < 10%** | 🟡 TRUNG BÌNH | Mở | Mục tiêu 50+ unit test + 60% coverage |
+| **Thiếu rate limiting theo từng endpoint** | 🟡 TRUNG BÌNH | Mở | Rate limit chi tiết (đăng ký 3/min, đăng nhập 5/min) |
+| **Baseline load test đã lỗi thời** | 🟡 TRUNG BÌNH | Mở | Tái thiết lập sau các tính năng industrial-avm |
+| **Mô hình AVM công nghiệp có thể overfitting** | 🟡 TRUNG BÌNH | Mở | Thu thập 1000+ bản ghi bất động sản công nghiệp |
 
-### Technical Debt
-| Item | Effort | Impact | Action |
-|------|--------|--------|--------|
-| Refactor large modules (search, admin) | Medium | Low | Split into sub-modules for clarity |
-| Reduce Prisma query duplication | Medium | Medium | Extract common WHERE clauses |
-| Upgrade Node.js to 24 LTS | Small | Medium | Update package.json + tests |
-| Consolidate Docker Compose files | Small | Low | Merge dev + prod into single config |
-| Extract shared React hooks | Medium | Low | Create libs/ui-hooks |
+### Nợ kỹ thuật
+| Mục | Công sức | Tác động | Hành động |
+|-----|----------|----------|-----------|
+| Tái cấu trúc module lớn (search, admin) | Trung bình | Thấp | Chia thành sub-module để rõ ràng hơn |
+| Giảm trùng lặp Prisma query | Trung bình | Trung bình | Trích xuất mệnh đề WHERE chung |
+| Nâng cấp Node.js lên 24 LTS | Nhỏ | Trung bình | Cập nhật package.json + tests |
+| Hợp nhất các file Docker Compose | Nhỏ | Thấp | Gộp dev + prod vào một cấu hình duy nhất |
+| Trích xuất React hook dùng chung | Trung bình | Thấp | Tạo libs/ui-hooks |
 
-### Operational Issues
-| Issue | Impact | Mitigation |
-|-------|--------|-----------|
-| **No staging environment** | Prod bugs possible | Deploy to staging branch before prod |
-| **Backup testing manual** | Data loss risk | Automate weekly restore test (CI) |
-| **Monitoring alerts missing** | Incident response delay | Configure AlertManager rules |
-| **No incident runbook** | Team confusion | Create runbook in docs/runbooks/ |
-| **Single PostgreSQL instance** | Single point of failure | Set up read replica + failover |
+### Vấn đề vận hành
+| Vấn đề | Tác động | Biện pháp giảm thiểu |
+|--------|----------|----------------------|
+| **Không có môi trường staging** | Có thể xảy ra lỗi production | Triển khai lên nhánh staging trước production |
+| **Kiểm tra sao lưu thủ công** | Nguy cơ mất dữ liệu | Tự động hóa kiểm thử restore hàng tuần (CI) |
+| **Thiếu cảnh báo giám sát** | Chậm phản ứng sự cố | Cấu hình quy tắc AlertManager |
+| **Không có runbook xử lý sự cố** | Nhóm lúng túng | Tạo runbook trong docs/runbooks/ |
+| **PostgreSQL instance đơn** | Điểm lỗi duy nhất | Thiết lập read replica + failover |
 
 ---
 
 ## 11. RECOMMENDATIONS
 
-### Immediate Actions (This Week)
-1. **🔴 Encryption**: Add `@encrypted` decorator to User (phone, email) via `@prisma/field-encrypt`
-2. **🔴 MFA Enforcement**: Set `REQUIRE_MFA_FOR_ADMIN=true` in production env
-3. **🔴 Web Tests**: Add 50 unit tests targeting 60% coverage
-4. **🟡 Rate Limits**: Add `@Throttle()` decorator to auth endpoints
-5. **🟡 Audit Logging**: Extend AdminAuditLog to track data access
+### Hành động ngay lập tức (Tuần này)
+1. **🔴 Mã hóa**: Thêm decorator `@encrypted` vào User (phone, email) qua `@prisma/field-encrypt`
+2. **🔴 Bắt buộc MFA**: Đặt `REQUIRE_MFA_FOR_ADMIN=true` trong môi trường production
+3. **🔴 Web Tests**: Thêm 50 unit test hướng đến 60% coverage
+4. **🟡 Rate Limits**: Thêm decorator `@Throttle()` vào các endpoint auth
+5. **🟡 Audit Logging**: Mở rộng AdminAuditLog để theo dõi truy cập dữ liệu
 
-### Short-term (1-2 weeks)
-1. Database read replica setup (AWS RDS, GCP CloudSQL)
-2. AlertManager rules (error_rate > 1%, p95_latency > 2s)
-3. Incident response runbook
-4. Load test baseline re-establishment
-5. Secrets rotation (JWT secret → 90-day cycle)
+### Ngắn hạn (1-2 tuần)
+1. Thiết lập read replica database (AWS RDS, GCP CloudSQL)
+2. Quy tắc AlertManager (error_rate > 1%, p95_latency > 2s)
+3. Runbook phản ứng sự cố
+4. Tái thiết lập baseline load test
+5. Luân chuyển secret (JWT secret → chu kỳ 90 ngày)
 
-### Medium-term (1 month)
-1. Refactor large modules (search, admin) into sub-modules
-2. Cache market reports (1h TTL) + Redis layer before Typesense
-3. Multi-region setup (Vietnam + Singapore with failover DNS)
-4. Feature flags framework (10+ flags for gradual rollout)
-5. CLI tool for local setup (Docker, Prisma, seed automation)
+### Trung hạn (1 tháng)
+1. Tái cấu trúc module lớn (search, admin) thành sub-module
+2. Cache báo cáo thị trường (TTL 1h) + lớp Redis trước Typesense
+3. Thiết lập đa vùng (Việt Nam + Singapore với failover DNS)
+4. Framework feature flag (10+ flag để triển khai dần dần)
+5. Công cụ CLI cho thiết lập cục bộ (Docker, Prisma, tự động hóa seed)
 
-### Long-term (2-3 months)
-1. LLM-powered recommendation engine
-2. React Native mobile app
-3. Optional blockchain escrow automation
-4. GDPR audit + data residency certification
-5. SaaS platform for agents (white-label API + MCP tools)
+### Dài hạn (2-3 tháng)
+1. Engine gợi ý dựa trên LLM
+2. Ứng dụng di động React Native
+3. Tự động hóa ký quỹ blockchain tùy chọn
+4. Kiểm toán GDPR + chứng nhận lưu trú dữ liệu
+5. Nền tảng SaaS cho môi giới (white-label API + MCP tools)
 
 ---
 
 ## 12. SUMMARY & GO-LIVE READINESS
 
-### Project Health: ✅ GREEN
-- **Code Quality**: 0 ESLint errors, TypeScript strict mode, 1454 unit tests passing
-- **Documentation**: 54K lines (architecture, API, deployment, runbooks)
-- **Infrastructure**: Docker-based, production-ready, monitoring active
-- **Security**: JWT + CSRF, rate limiting, PII masking (needs encryption)
-- **Operations**: CI/CD working, automated backups, health checks on all services
+### Tình trạng dự án: ✅ XANH
+- **Chất lượng code**: 0 lỗi ESLint, TypeScript strict mode, 1454 unit test pass
+- **Tài liệu**: 54K dòng (kiến trúc, API, triển khai, runbook)
+- **Hạ tầng**: Dựa trên Docker, sẵn sàng production, giám sát hoạt động
+- **Bảo mật**: JWT + CSRF, rate limiting, che giấu PII (cần mã hóa)
+- **Vận hành**: CI/CD hoạt động, sao lưu tự động, health check trên tất cả dịch vụ
 
-### Velocity
-- **Commits/week**: 8-12 (accelerating toward launch)
-- **Bug density**: ~15% of commits (healthy)
-- **Modules**: 20 API modules (well-organized)
-- **Test count**: 1454 tests passing (290 API unit tests, 33 E2E tests)
+### Tốc độ
+- **Commit/tuần**: 8-12 (tăng tốc về phía ra mắt)
+- **Mật độ lỗi**: ~15% commit (lành mạnh)
+- **Module**: 20 API module (được tổ chức tốt)
+- **Số lượng test**: 1454 test pass (290 API unit test, 33 E2E test)
 
-### Top 3 Priorities for Next Sprint
-1. **🔴 Security**: PII encryption + MFA enforcement
-2. **🟡 Quality**: Web unit tests to 60% coverage
-3. **🟡 Operations**: Incident runbook + staging environment
+### 3 Ưu tiên hàng đầu cho Sprint tiếp theo
+1. **🔴 Bảo mật**: Mã hóa PII + bắt buộc MFA
+2. **🟡 Chất lượng**: Web unit test đạt 60% coverage
+3. **🟡 Vận hành**: Runbook xử lý sự cố + môi trường staging
 
-### Go-Live Readiness: ✅ 95%
-- ✅ Core features complete (auth, listings, search, payments, subscriptions, notifications)
-- ✅ Admin capabilities ready (moderation, KYC, audit)
-- ✅ Analytics + AVM integration complete
-- ✅ Infrastructure tested (Docker, monitoring, backups)
-- ⚠️ TODO: PII encryption, MFA enforcement, incident runbook
+### Mức độ sẵn sàng ra mắt: ✅ 95%
+- ✅ Tính năng cốt lõi hoàn chỉnh (auth, listings, search, payments, subscriptions, notifications)
+- ✅ Khả năng admin sẵn sàng (kiểm duyệt, KYC, kiểm toán)
+- ✅ Tích hợp Analytics + AVM hoàn chỉnh
+- ✅ Hạ tầng đã kiểm thử (Docker, giám sát, sao lưu)
+- ⚠️ TODO: Mã hóa PII, bắt buộc MFA, runbook xử lý sự cố
 
 ---
 
-**Report generated**: 2026-04-18T10:30:00Z  
-**Auditor**: CTO (TechBi)  
-**Scope**: Full codebase review (read-only)  
-**Status**: ✅ COMPLETE
-
+**Báo cáo được tạo**: 2026-04-18T10:30:00Z  
+**Kiểm toán viên**: CTO (TechBi)  
+**Phạm vi**: Xem xét toàn bộ codebase (chỉ đọc)  
+**Trạng thái**: ✅ HOÀN THÀNH

report/audit-2026-04-19.md

@@ -0,0 +1,398 @@
+# BÁO CÁO AUDIT — Goodgo Platform AI
+
+- **Ngày**: 2026-04-19
+- **Ticket**: [TEC-2878](/TEC/issues/TEC-2878) (parent: [TEC-2877](/TEC/issues/TEC-2877))
+- **Phạm vi**: Read-only audit toàn bộ monorepo tại `/Users/velikho/Desktop/WORKING/goodgo-platform-ai`
+- **Ngôn ngữ**: Tiếng Việt (giữ nguyên thuật ngữ kỹ thuật tiếng Anh)
+- **Ràng buộc**: Không chỉnh sửa code, không chạy test — chỉ đọc nguồn và phân tích
+
+---
+
+## 1. TỔNG QUAN & TRẠNG THÁI HIỆN TẠI
+
+### 1.1 Mô tả dự án
+Goodgo Platform AI là nền tảng bất động sản tại Việt Nam theo mô hình monorepo (pnpm workspaces + Turborepo) với:
+
+- **apps/api** — NestJS 11 backend (CQRS + DDD + clean architecture, 22 module)
+- **apps/web** — Next.js 15 frontend (App Router, i18n `[locale]`, Tailwind, Zustand, Mapbox)
+- **libs/ai-services** — Python FastAPI (AVM, moderation, NLP Vietnamese, neighborhood scoring)
+- **libs/mcp-servers** — TypeScript MCP tool server (property search, analytics, valuation)
+- **prisma** — PostgreSQL 16 + PostGIS với **39 model**
+- **e2e** — Playwright (API + Web projects)
+
+### 1.2 Phiên bản & mốc thời gian
+- Phiên bản hiện tại: **v1.4.0** (phát hành 2026-04-08, branch `Unreleased` đang tích lũy cho Wave 13)
+- Node.js ≥ 22 LTS, pnpm `10.27.0`
+- QA baseline (2026-04-12): **1454 unit tests PASS**, 0 lỗi ESLint, build 3 gói thành công
+- Đã có báo cáo audit trước đó: [report/AUDIT_CTO_2026-04-18.md](../report/AUDIT_CTO_2026-04-18.md) — báo cáo 2026-04-19 này cập nhật các module bổ sung (`favorites`, `reports`) và liệt kê endpoint đầy đủ.
+
+### 1.3 Ước tính mức độ hoàn thành
+- **Tính năng cốt lõi (auth, listings, search, payments, subscriptions, notifications, admin, analytics)**: ~100%
+- **Tính năng nâng cao (industrial, transfer/escrow, projects, messaging, neighborhood score, reports)**: ~85–90%
+- **Kiểm toán / compliance (PII encryption cấp trường, MFA bắt buộc, staging env, runbook)**: ~40–60%
+- **Độ phủ web unit test**: thấp (≈7 spec), còn cách mục tiêu 60%
+- **Tổng thể dự án**: ~**88%** — sẵn sàng ra mắt với điều kiện đóng các nút bảo mật & QA cấp cao.
+
+---
+
+## 2. TIẾN ĐỘ PHÁT TRIỂN
+
+### 2.1 Các giai đoạn đã hoàn thành (theo CHANGELOG)
+| Giai đoạn | Phiên bản | Nội dung chính |
+|---|---|---|
+| Nền tảng | 1.0.0 (2026-03-01) | Auth, listings CRUD, payments, search, notifications, MCP stubs |
+| Tăng trưởng | 1.1.0 (2026-03-12) | Dedupe, subscription quota, OAuth, 58 unit tests |
+| Trưởng thành | 1.2.0 (2026-03-20) | React Query, dark mode, Redis cache, NLP, Prometheus, 200+ tests |
+| Ổn định | 1.3.0 (2026-03-28) | Multi-channel notifications, reviews, heatmap, 1200+ tests |
+| Hoàn thiện | 1.4.0 (2026-04-08) | Health/metrics/mcp hoàn chỉnh, AVM UI, 1454 tests |
+| Wave 13 (Unreleased) | — | Audit CEO Wave 13, industrial module, messaging, transfer/escrow, NeighborhoodScore, report module |
+
+### 2.2 Điểm nổi bật 30 ngày gần nhất
+- ✅ MCP servers (property-search, market-analytics, valuation, industrial-parks) được triển khai đầy đủ thay cho stub
+- ✅ Module **industrial** (khu công nghiệp) và **industrial AVM** riêng biệt
+- ✅ Module **messaging** thời gian thực qua WebSocket + persist DB
+- ✅ **transfer/escrow** workflow cho giao dịch (escrow hold / release)
+- ✅ **NeighborhoodScore** service (Python FastAPI) với cache theo lat/long
+- ✅ **reports** module (generate, list, macro-data, status, delete)
+- ✅ Feature-flag `residential_projects` và promotion workflow listing
+- ✅ KYC upload với presigned S3/MinIO URL
+- ✅ 725 ESLint lỗi được giải quyết (auto-fix 712), TypeScript strict mode
+- ✅ GDPR: endpoint xóa dữ liệu người dùng (`DELETE /users/me`), cancel deletion, data export
+
+### 2.3 Velocity
+- ~8–12 commits/tuần trong các sprint cuối
+- 70% tính năng mới, 30% bug fix / tech debt
+- Không có breaking change trong các release gần đây
+
+---
+
+## 3. KIẾN TRÚC & TECH STACK
+
+### 3.1 Stack tổng quan
+| Layer | Công nghệ |
+|---|---|
+| Runtime | Node.js ≥ 22, Python 3 (ai-services) |
+| Package manager | pnpm 10.27.0 + Turborepo |
+| Backend | NestJS 11, CQRS, DDD, Pino, Zod |
+| Frontend | Next.js 15 (App Router), React 18, Tailwind 3, Zustand, React Query 5, Mapbox GL, next-intl |
+| DB | PostgreSQL 16 + PostGIS 3.4, Prisma 7.7 |
+| Cache | Redis 7 (AOF), PgBouncer 1.18 cho prod pool |
+| Search | Typesense 27 (Vietnamese tokenizer) |
+| Storage | MinIO (S3 compatible, presigned URLs) |
+| AI / ML | XGBoost (AVM v1/v2/industrial), Claude API (moderation), Underthesea (NLP VI), custom neighborhood scorer |
+| Observability | Prometheus, Grafana, Loki, Sentry, Pino JSON logs, OpenTelemetry |
+| Testing | Vitest (unit), Playwright (E2E API+Web), k6 (load) |
+| CI/CD | GitHub Actions (lint → typecheck → test → build) |
+
+### 3.2 Domain layering (API)
+Mỗi module tuân thủ: `domain/` → `application/` (commands, queries, handlers CQRS) → `infrastructure/` (Prisma, adapters) → `presentation/` (controllers, DTOs, guards).
+
+### 3.3 Convention dự án (trích từ CLAUDE.md)
+- Import order do `eslint-plugin-import-x` ép (external → internal → relative)
+- Path alias `@modules/*` (API), `@/*` (Web)
+- UI dùng tiếng Việt; currency VND
+- Handler trả về `Result<T>` hoặc ném `DomainException`
+- Commit theo conventional commits
+
+---
+
+## 4. MODULES CHI TIẾT (API — 22 module)
+
+| Module | Controllers | Mục đích & điểm nổi bật |
+|---|---|---|
+| **auth** | auth, oauth, mfa, user-data | Đăng ký/đăng nhập phone+password, Google/Zalo OAuth, JWT + refresh, MFA TOTP, KYC upload, GDPR export/delete |
+| **listings** | listings | CRUD listing, quota-aware, AI moderation, event-driven indexing, promote/feature, QR code, price history |
+| **search** | search, saved-search | Full-text Typesense, `/search/geo` PostGIS radius, saved searches CRUD, admin reindex |
+| **payments** | payments, orders, admin-payments | VNPay/MoMo/ZaloPay, callback webhook idempotent, refund, confirm bank transfer, orders+escrow |
+| **subscriptions** | subscriptions | Plans tier, quotas Redis, upgrade/cancel, usage tracking, billing |
+| **admin** | admin, admin-moderation | Dashboard, moderation queue, KYC approve/reject, user ban, revenue, audit logs, listing feature |
+| **analytics** | analytics, avm | Market report, price trend, heatmap, district stats, AVM single/batch/history/compare, neighborhood score |
+| **notifications** | notifications, zalo-oa-webhook | Email/SMS/push/in-app, templates Handlebars, preferences, unread, Zalo OA inbound webhook |
+| **reviews** | reviews | Đánh giá property/agent (polymorphic), stats, my-reviews |
+| **inquiries** | inquiries | Buyer→Seller flow, read state |
+| **leads** | leads | Lead CRUD + stats + status workflow |
+| **agents** | agents | Dashboard agent, profile public, upgrade role, recalculate quality score |
+| **messaging** | messaging | Conversations & messages (WebSocket gateway + persistence), read receipts, message delete |
+| **transfer** | transfer | Sang nhượng (photos-based estimate, escrow listings) |
+| **industrial** | industrial-parks, industrial-listings | Khu công nghiệp + listing, compare parks, stats, market, estimate rent, analyze location |
+| **projects** | projects | Dự án dân cư (PLANNING→HANDOVER), chi tiết theo slug/id |
+| **favorites** | favorites | Save/unsave listing, list favorites, check state |
+| **reports** | reports | Generate async report, list, status, macro-data, delete |
+| **health** | health | Liveness / readiness / db / redis |
+| **metrics** | web-vitals | Thu thập Web Vitals từ frontend |
+| **mcp** | mcp-transport | Bridge MCP servers qua HTTP/SSE (JWT + rate limit) |
+| **shared** | — | Guards (auth, roles, rate limit, CSRF), pipes, filters, value objects, logging |
+
+### Frontend (apps/web) — App Router với i18n `[locale]`
+- Route groups: `(public)` (homepage, search, listings, agents, pricing, payment, compare, reports `bao-cao`, transfer `chuyen-nhuong`, industrial `khu-cong-nghiep`, projects `du-an`), `(auth)`, `(dashboard)`, `(admin)`
+- API proxy / BFF ở `apps/web/app/api`
+- Trang nổi bật: `/valuation` (AVM UI), `/chat` (messaging), `/dashboard` (user area), `/admin`
+
+### AI services (libs/ai-services — FastAPI)
+Routers có mặt: `avm.py`, `avm_v2.py`, `avm_industrial.py`, `moderation.py`, `nlp.py`, `neighborhood.py`.
+
+### MCP servers (libs/mcp-servers)
+Tools: property search, market analytics, valuation, industrial parks.
+
+---
+
+## 5. API HIỆN HÀNH (REST endpoints)
+
+- **Tổng số route handler**: **178** (đếm decorator `@Get/@Post/@Put/@Patch/@Delete`)
+- **Prefix**: `/api/v1/` (áp dụng toàn cục); mọi path dưới đây là **tương đối** với prefix đó
+- **Auth mặc định**: JWT Bearer; webhook dùng signature verification riêng
+- **Rate limit mặc định**: 60/min/IP (auth 10/min, payments 20/min, MCP 20/min)
+
+### 5.1 Auth & User
+
+| Method | Path | Auth | Mô tả |
+|---|---|---|---|
+| POST | `/auth/register` | public | Đăng ký user |
+| POST | `/auth/login` | public | Đăng nhập |
+| POST | `/auth/refresh` | refresh token | Làm mới access token |
+| POST | `/auth/logout` | JWT | Đăng xuất |
+| POST | `/auth/forgot-password` | public | Yêu cầu reset password |
+| POST | `/auth/reset-password` | token | Xác nhận đổi password |
+| POST | `/auth/exchange-token` | OAuth code | Exchange token |
+| GET | `/auth/profile` | JWT | Lấy profile |
+| PATCH | `/auth/profile` | JWT | Cập nhật profile |
+| POST | `/auth/profile/verify-phone` | JWT | Bắt đầu OTP phone |
+| POST | `/auth/profile/verify-email` | JWT | Bắt đầu verify email |
+| POST | `/auth/resend-otp` | JWT | Gửi lại OTP |
+| GET | `/auth/profile/agent` | JWT | Profile agent của user |
+| POST | `/auth/kyc/upload-urls` | JWT | Lấy presigned URL |
+| POST | `/auth/kyc/submit` | JWT | Submit hồ sơ KYC |
+| PATCH | `/auth/kyc` | JWT | Cập nhật trạng thái KYC |
+| GET | `/auth/google` · `/auth/google/callback` | public | Google OAuth |
+| GET | `/auth/zalo` · `/auth/zalo/callback` | public | Zalo OAuth |
+| POST | `/auth/mfa/setup` · `/verify-setup` · `/challenge` · `/backup-codes` | JWT | MFA TOTP |
+| GET | `/auth/mfa/status` | JWT | Trạng thái MFA |
+| DELETE | `/auth/mfa` | JWT | Tắt MFA |
+| DELETE | `/users/me` | JWT | Yêu cầu xóa tài khoản (GDPR) |
+| POST | `/users/me/cancel-deletion` | JWT | Hủy yêu cầu xóa |
+| GET | `/users/me/export` | JWT | Xuất dữ liệu cá nhân |
+| DELETE | `/users/:id/force` | admin | Xóa cưỡng bức |
+
+### 5.2 Listings & Favorites
+
+| Method | Path | Auth | Mô tả |
+|---|---|---|---|
+| POST | `/listings` | JWT | Tạo listing |
+| GET | `/listings` | public | Danh sách |
+| GET | `/listings/pending` | admin | Queue chờ duyệt |
+| GET | `/listings/:id` · `/listings/:id/qr-code` · `/listings/:id/price-history` | public | Chi tiết, QR, lịch sử giá |
+| PATCH | `/listings/:id` · `/listings/:id/status` · `/listings/:id/moderate` | JWT/admin | Cập nhật / đổi trạng thái / moderate |
+| POST | `/listings/:id/media` · `/listings/:id/feature` · `/listings/:id/promote` | JWT | Upload media, feature, promote |
+| POST · DELETE · GET | `/favorites/:listingId` · `/favorites` · `/favorites/:listingId/check` | JWT | Yêu thích |
+
+### 5.3 Search
+
+| Method | Path | Auth | Mô tả |
+|---|---|---|---|
+| GET | `/search` | public | Full-text search |
+| GET | `/search/geo` | public | Radius / bbox PostGIS |
+| POST | `/search/reindex` | admin | Reindex Typesense |
+| POST · GET · GET/:id · PATCH · DELETE | `/saved-searches` | JWT | CRUD saved searches |
+
+### 5.4 Payments & Orders
+
+| Method | Path | Auth | Mô tả |
+|---|---|---|---|
+| POST | `/payments` | JWT | Khởi tạo thanh toán |
+| POST | `/payments/callback/:provider` | webhook | VNPay/MoMo/ZaloPay callback |
+| GET | `/payments/:id` · `/payments` | JWT | Chi tiết / list |
+| POST | `/payments/:id/refund` | admin | Hoàn tiền |
+| POST | `/payments/:id/confirm-transfer` · `/admin/payments/:id/confirm-transfer` | admin | Xác nhận chuyển khoản |
+| POST | `/orders` | JWT | Tạo order |
+| GET | `/orders/:id` | JWT | Chi tiết order |
+| POST | `/orders/:id/cancel` · `/escrow/hold` · `/escrow/release` | JWT | Escrow workflow |
+
+### 5.5 Subscriptions & Plans
+
+| Method | Path | Auth | Mô tả |
+|---|---|---|---|
+| GET | `/subscriptions/plans` · `/plans/:tier` | public | Danh sách plan |
+| POST | `/subscriptions` | JWT | Subscribe plan |
+| PUT | `/subscriptions/upgrade` | JWT | Nâng cấp plan |
+| DELETE | `/subscriptions` | JWT | Hủy |
+| POST | `/subscriptions/usage` | JWT | Ghi nhận usage |
+| GET | `/subscriptions/quota/:metric` · `/billing` | JWT | Quota & billing |
+
+### 5.6 Analytics & AVM
+
+| Method | Path | Auth | Mô tả |
+|---|---|---|---|
+| GET | `/analytics/market-report` · `/price-trend` · `/heatmap` · `/district-stats` | JWT | Báo cáo thị trường |
+| GET | `/analytics/valuation` · `/valuation/history/:propertyId` | JWT | AVM |
+| POST | `/analytics/valuation/batch` · `/valuation/compare` | JWT | Batch / compare AVM |
+| GET | `/analytics/neighborhoods/:district/score` | JWT | Điểm khu dân cư |
+| POST | `/avm/batch` · `/avm/industrial` | JWT | Batch định giá, định giá KCN |
+| GET | `/avm/history/:propertyId` · `/avm/compare` | JWT | Lịch sử & so sánh |
+
+### 5.7 Admin
+
+| Method | Path | Auth | Mô tả |
+|---|---|---|---|
+| GET | `/admin/moderation` · `/kyc` · `/users` · `/users/:id` · `/dashboard` · `/revenue` · `/audit-logs` | admin | Dashboard & moderation views |
+| POST | `/admin/moderation/approve` · `/reject` · `/bulk` · `/listings/:id/feature` · `/kyc/approve` · `/kyc/reject` · `/users/ban` · `/subscriptions/adjust` | admin | Actions |
+| PATCH | `/admin/users/status` | admin | Đổi status user |
+
+### 5.8 Agents / Inquiries / Leads / Reviews
+
+| Method | Path | Auth | Mô tả |
+|---|---|---|---|
+| GET | `/agents/me/dashboard` · `/agents/:agentId/profile` | JWT/public | Dashboard agent / profile |
+| POST | `/agents/me/upgrade` · `/agents/:agentId/recalculate-score` | JWT/admin | Upgrade agent / tính lại điểm |
+| POST · GET · PATCH | `/inquiries` · `/listing/:listingId` · `/agent/me` · `/:id/read` | JWT | Inquiry flow |
+| POST · GET · PATCH · DELETE | `/leads` · `/leads/stats` · `/leads/:id/status` · `/leads/:id` | JWT | Lead |
+| POST · GET · DELETE | `/reviews` · `/reviews/stats` · `/reviews/me` · `/reviews/:id` | JWT | Review |
+
+### 5.9 Messaging · Transfer · Industrial · Projects · Reports
+
+| Method | Path | Auth | Mô tả |
+|---|---|---|---|
+| POST · GET · PATCH · DELETE | `/messaging/conversations*` · `/messages*` · `/read` | JWT | Conversation & message |
+| GET · POST · PATCH · DELETE | `/transfer/listings*` · `/transfer/stats` · `/estimate` · `/estimate-from-photos` | JWT | Sang nhượng + ảnh → định giá |
+| GET · POST · PATCH | `/industrial/parks*` · `/industrial/market` · `/industrial/analyze-location` · `/industrial/estimate-rent` · `/industrial/listings*` | JWT | KCN |
+| GET · POST · PATCH | `/projects` · `/projects/:slugOrId` · `/projects` · `/projects/:id` | JWT/admin | Dự án |
+| POST · GET · DELETE | `/reports/generate` · `/reports` · `/reports/:id` · `/reports/:id/status` · `/reports/macro-data` | JWT | Báo cáo thị trường |
+
+### 5.10 Notifications · MCP · Health · Metrics · Webhooks
+
+| Method | Path | Auth | Mô tả |
+|---|---|---|---|
+| GET · PUT · PATCH | `/notifications/history` · `/preferences` · `/unread-count` · `/unread` · `/:id/read` · `/read-all` · `/templates` | JWT | Notifications |
+| GET · POST | `/webhooks/zalo-oa` | signature | Zalo OA inbound |
+| GET · POST | `/mcp/servers` · `/mcp/:serverName/sse` · `/mcp/:serverName/messages` | JWT + rate limit | MCP bridge |
+| GET | `/health` · `/health/ready` · `/health/db` · `/health/redis` | public | Probes |
+| POST | `/web-vitals` | public | Thu thập CWV |
+
+### 5.11 AI service (Python FastAPI, internal)
+
+| Path | Mô tả |
+|---|---|
+| `/avm/v1/estimate`, `/avm/v2/*` | AVM residential XGBoost |
+| `/avm/industrial/*` | AVM công nghiệp |
+| `/moderation/score` | Moderation (Claude API) |
+| `/nlp/analyze` | NLP tiếng Việt (Underthesea) |
+| `/neighborhood/score` | Neighborhood scorer |
+
+> Ghi chú: AI service được NestJS proxy qua `/analytics/*`, `/avm/*`, `/reports/*` — không expose trực tiếp ra public.
+
+---
+
+## 6. DATABASE — 39 MODEL PRISMA
+
+Các nhóm chính:
+
+- **Auth**: `User`, `MfaChallenge`, `RefreshToken`, `OAuthAccount`
+- **Directory**: `Agent`
+- **Property & Listing**: `Property`, `PropertyMedia`, `Listing`, `PriceHistory`, `SavedSearch`, `SavedListing`, `POI`
+- **Transaction**: `Transaction`, `Order`, `Payment`, `Escrow`
+- **CRM**: `Inquiry`, `Lead`, `Review`
+- **Billing**: `Plan`, `Subscription`, `UsageRecord`
+- **Project / Industrial**: `ProjectDevelopment`, `IndustrialPark`, `IndustrialListing`, `InfrastructureProject`
+- **Transfer**: `TransferListing`, `TransferItem`
+- **Analytics**: `Valuation`, `MarketIndex`, `NeighborhoodScore`, `MacroeconomicData`, `Report`
+- **Messaging**: `Conversation`, `ConversationParticipant`, `Message`
+- **Admin & Notifications**: `AdminAuditLog`, `NotificationLog`, `NotificationPreference`
+
+Pattern nổi bật: PostGIS geometry + GIST index, JSON cột (amenities, features), polymorphic target cho Review, audit log (before/after JSON), state machine cho Listing/Transfer/Escrow.
+
+---
+
+## 7. AI / ML
+
+1. **AVM** (XGBoost v1 / v2 / industrial) — định giá residential & industrial, trả khoảng tin cậy & feature importance; p95 < 500ms.
+2. **Content moderation** — Claude API chấm điểm spam/giả/cấm; ngưỡng 75; fallback về `PENDING_REVIEW` khi Claude lỗi.
+3. **NLP Vietnamese** (Underthesea) — tokenize, POS, NER, sentiment; hỗ trợ auto-tag amenities.
+4. **Neighborhood scoring** — đánh giá walkability, safety, amenities, market; cache theo (lat,lng) làm tròn trong 1h.
+5. **MCP tool server** — expose property search, market analytics, valuation, industrial parks cho LLM qua HTTP/SSE có JWT.
+
+---
+
+## 8. CHẤT LƯỢNG, CI/CD, OPS
+
+- **Unit test**: API 290 spec (1454 case ✅), MCP 4 ✅, Web **chỉ 7** spec ⚠️
+- **E2E**: API 17, Web 16 — PASS
+- **Load**: k6 7 kịch bản — đạt SLA p50<200ms / p95<500ms / p99<1s / error<1%
+- **CI**: Lint → typecheck → test → build + backup verify + deps audit
+- **Monitoring**: Prometheus/Grafana/Loki/Sentry, health probes, web vitals collector
+- **Secrets**: `.env` bắt buộc `DATABASE_URL`, `JWT_SECRET`, `JWT_REFRESH_SECRET`, `VNPAY_*`, `MAPBOX_TOKEN`, `REDIS_URL`
+- **Deploy**: Docker Compose (dev/ci/prod), Nginx, PgBouncer — nhưng chưa có **staging environment** độc lập
+
+---
+
+## 9. RỦI RO & NỢ KỸ THUẬT
+
+### 9.1 Rủi ro cao (cần đóng trước GA)
+| Hạng mục | Mức | Ghi chú |
+|---|---|---|
+| Không có PII encryption cấp trường (phone/email) | 🔴 | Cần decorator `@encrypted` hoặc pgcrypto |
+| MFA chưa bắt buộc cho admin/agent | 🔴 | Bật `REQUIRE_MFA_FOR_ADMIN` |
+| Web unit test coverage < 10% | 🟡 | Đặt mục tiêu 60% |
+| Rate limit chưa phân biệt endpoint nhạy cảm | 🟡 | Thêm `@Throttle()` cho `/auth/register`, `/auth/login` |
+| Load test baseline đã cũ sau các tính năng industrial/AVM | 🟡 | Chạy lại trước GA |
+| Mô hình AVM industrial có thể overfit vì ít dữ liệu | 🟡 | Cần mở rộng dataset |
+
+### 9.2 Nợ kỹ thuật
+- Tách `search`, `admin` thành sub-module nhỏ hơn
+- Dedupe Prisma where-clauses
+- Nâng Node 24 LTS khi ổn định
+- Gộp file Docker Compose dev+prod
+- Extract React hooks dùng chung thành `libs/ui-hooks`
+
+### 9.3 Ops / Compliance
+- Chưa có staging env, chưa có incident runbook (`docs/runbooks/`)
+- Backup chưa restore-test tự động
+- Single PostgreSQL instance — cần read replica + failover
+- Chưa có AlertManager rules (error_rate > 1%, p95 > 2s)
+
+---
+
+## 10. ROADMAP ĐỀ XUẤT
+
+### 10.1 Tuần này (tập trung GA-readiness)
+1. 🔴 PII encryption cấp trường (User.phone/email) + rotate JWT secret 90 ngày
+2. 🔴 Bắt buộc MFA cho admin & agent (TOTP)
+3. 🟡 Thêm ≥ 50 unit test cho web (target 60% coverage)
+4. 🟡 Rate limit per-endpoint (`/auth/register` 3/min, `/auth/login` 5/min)
+5. 🟡 Mở rộng `AdminAuditLog` cho mọi truy cập dữ liệu nhạy cảm
+
+### 10.2 1–2 tuần
+1. Read replica DB (AWS RDS / GCP CloudSQL)
+2. AlertManager + incident runbook
+3. Re-baseline load test sau industrial/AVM
+4. Hoàn thiện staging environment
+
+### 10.3 1 tháng
+1. Sub-module hóa `search`, `admin`
+2. Cache layer Redis trước Typesense cho market report
+3. Multi-region (VN + SG failover DNS)
+4. Feature-flag framework cho gradual rollout
+5. CLI setup (Docker + Prisma + seed tự động)
+
+### 10.4 Trung hạn (2–3 tháng)
+1. Recommendation engine dựa trên LLM
+2. Mobile app React Native
+3. Offer / counter-offer chat trực tiếp
+4. Video listing + HLS streaming
+5. Fraud detection (XGBoost classifier)
+6. SaaS white-label cho môi giới (API + MCP tools)
+
+---
+
+## 11. KẾT LUẬN
+
+- **Tình trạng**: ✅ Xanh — MVP hoàn chỉnh, 178 REST endpoint đang vận hành, 1454 unit test PASS.
+- **Top 3 ưu tiên sprint kế**:
+  1. 🔴 Bảo mật: PII encryption + MFA bắt buộc
+  2. 🟡 Chất lượng: Web unit test coverage 60%
+  3. 🟡 Vận hành: Staging env + incident runbook
+- **Go-live readiness**: ≈**95%** (chặn bởi các nút rủi ro cao ở mục 9.1).
+
+---
+
+**Deliverable**: file này tại `/Users/velikho/Desktop/WORKING/goodgo-platform-ai/report/audit-2026-04-19.md`.
+**Auditor**: CRO (Paperclip agent `05c27101`).
+**Scope**: read-only, không chạm code/test.