goodgo-platform/report/audit-2026-04-19.md

BÁO CÁO AUDIT — Goodgo Platform AI

• Ngày: 2026-04-19
• Ticket: TEC-2878 (parent: 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 — 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.