goodgo-platform/CHANGELOG.md

Nhật Ký Thay Đổi

Tất cả các thay đổi đáng chú ý của GoodGo Platform sẽ được ghi lại trong tệp này.

Định dạng dựa trên Keep a Changelog, và dự án này tuân theo Semantic Versioning.

Unreleased

GOO-33 Documentation Sprint (2026-04-22)

Đã hoàn thành

• QA_TRACKER.md — cập nhật test status baseline + Sprint 1-2 test plans
• CHANGELOG.md — cập nhật changelog lần cuối (2026-04-22)
• PROJECT_TRACKER.md — cập nhật GOO-33 status → in_progress
• CONTRIBUTING.md — thêm branching strategy, PR conventions, commit message format
• docs/ci-cd.md — tài liệu đầy đủ GitHub Actions pipeline (lint → typecheck → test → build)
• docs/onboarding.md — hướng dẫn setup dành cho developer mới
• docs/mcp-servers.md — tài liệu 3 MCP servers (search, analytics, valuation)
• docs/audits/ — curate từ ~103 → 12 canonical audit reports + archive old files

GOO-2 Lead Orchestrator Audit (2026-04-22)

Audit & Planning

• Kiểm tra toàn diện codebase: 51 findings (4 blockers, 24 high, 13 medium, 10 low)
• Nghiên cứu thị trường BĐS VN: 23 findings (3 P0, 10 P1, 8 P2, 1 P3)
• Ma trận đề xuất: 25 cải thiện (Nhóm A) + 20 tính năng mới (Nhóm B) + 10 docs gaps (Nhóm C)
• Tạo 32 subtasks (GOO-3 → GOO-34) phân theo 6 sprints
• Tạo QA_TRACKER.md, cập nhật PROJECT_TRACKER.md

Đã sửa

• GOO-3: Fix double CSRF middleware — login/register/payment callbacks hoạt động (Sprint 1) ✅

Đang triển khai (Sprint 1 Blockers)

• GOO-4: UsageRecord atomic metering (fix quota bypass)
• GOO-5: Rate-limit POST /auth/exchange-token
• GOO-6: Fix MoMo IPN URL (tách ipnUrl khỏi redirectUrl)
• GOO-7: JWT validate user status (isActive + deletedAt)

Phát hiện chính (P0 — Launch Blockers)

• Thiếu Phone-OTP login (phương thức auth chính ở VN)
• legalStatus là free-text, không phải enum (tín hiệu tin cậy #1)
• Typesense không hỗ trợ tìm kiếm dấu tiếng Việt
• Thiếu phòng trọ (ROOM_RENTAL) trong PropertyType enum
• Quận 2/9 đã bị xóa (→ Thủ Đức) nhưng vẫn hardcoded trong UI

Đã thêm (CEO Audit Wave 13 — 2026-04-12)

• Quy trình kiểm tra CEO (TEC-1915) — kiểm tra toàn bộ codebase + xem xét trạng thái dự án
• Tài liệu kế hoạch với báo cáo 7 phần: tóm tắt kiểm tra, các vấn đề quan trọng, ưu tiên, khuyến nghị
• 6 subtask mới được tạo (TEC-1918 đến TEC-1923) cho Wave 13
• Cập nhật PROJECT_TRACKER với phần theo dõi Wave 13

Kết Quả QA (2026-04-12)

• Lint: PASS (0 lỗi)
• TypeScript: 7 lỗi trong các tệp test web (thiếu kiểu vitest) — TEC-1918
• Kiểm thử đơn vị: 232 tệp, 1454 bài kiểm thử, TẤT CẢ ĐỀU PASS
• Build: TẤT CẢ 3 gói build thành công
• Git: Cây làm việc sạch

Đã thêm

• Kiểm tra toàn diện CEO & kế hoạch triển khai (TEC-1882) — báo cáo 8 phần bao gồm kiến trúc, chất lượng, bảo mật
• 7 subtask mới được tạo (TEC-1888 đến TEC-1894) cho Wave 11D-13
• Cập nhật PROJECT_TRACKER với theo dõi subtask Waves 11D-13
• Cập nhật QA_TRACKER với báo cáo kiểm thử ngày 2026-04-11 (xác định 27 bài kiểm thử thất bại)
• Các báo cáo kiểm tra toàn diện: AUDIT_SUMMARY, COMPREHENSIVE_AUDIT, AUDIT_INDEX

Đã xác định (từ CEO Audit 2026-04-11)

• 725 lỗi ESLint (712 có thể tự động sửa) — TEC-1888
• Lỗi TypeScript trong các bài kiểm thử web (json-ld.spec.tsx) — TEC-1888
• 27 bài kiểm thử rate limit guard thất bại — TEC-1889
• 3 module API chưa hoàn chỉnh (health, metrics, mcp) — TEC-1890
• Các MCP server chỉ là stub (~50 dòng mỗi cái) — TEC-1891
• Chỉ có 6 bài kiểm thử đơn vị web (cần 50+) — TEC-1892
• Không có mã hóa PII ở cấp độ trường — TEC-1893
• Không có MFA cho tài khoản agent/admin — TEC-1894

Đã thêm trước đó

• Tài liệu kế hoạch kiểm tra CEO với ma trận cải tiến & tính năng đầy đủ (TEC-1682)
• Các vấn đề Wave 5: sửa lỗ hổng npm, độ phủ kiểm thử, Saved Searches, Dependabot
• Kết nối pool PgBouncer cho PostgreSQL môi trường production
• Tối ưu hóa SEO — JSON-LD, sitemap động, meta tags cho danh sách bất động sản
• Tài liệu tham khảo mã lỗi API
• Tăng cường tiêu đề bảo mật cho cả API và ứng dụng Web
• Dockerfile production đa giai đoạn cho NestJS API
• Kiểm tra giá trị JWT secret khi khởi động (từ chối giá trị giữ chỗ)
• Giới hạn kích thước tệp theo loại và phản hồi 413 cho tải lên media
• Rate limiting và auth guard cho MCP transport controller
• Xử lý lỗi bất đồng bộ cho các handler module quan trọng
• Component QueryErrorBoundary với tọa độ bản đồ thực tế (web)
• Endpoint xóa dữ liệu người dùng tuân thủ GDPR
• Cache kết quả tìm kiếm danh sách bất động sản với decorator @Cacheable
• Bản dịch i18n cho Auth + search và khả năng truy cập filter-bar

Đã sửa

• MCP transport controller hiện yêu cầu xác thực JWT (BUG-004 đã giải quyết)
• 21 lỗi lint từ các commit GDPR/logger/caching
• Thay thế new Logger() bằng DI LoggerService xuyên suốt các module
• Đã sửa nhánh đích của CI workflow từ main sang master
• Lỗi lint và typecheck để chuẩn bị ra mắt MVP

Đã thay đổi

• Tách các tệp lớn trong quá trình refactor logger

---

1.4.0 - 2026-04-08

Đã thêm

• Redis caching cho kiểm tra quota người dùng với xóa cache theo tiền tố
• Kiểm thử đơn vị tầng domain trên tất cả các module (auth, payments, subscriptions, admin, analytics, listings, notifications, reviews, search, metrics)
• Các endpoint health check (/health, /health/db, /health/redis) sử dụng @nestjs/terminus
• Giao diện Định giá Bất động sản với tích hợp AVM (Automated Valuation Model) trên web frontend

Đã thay đổi

• Cải thiện cache service với các mẫu xóa theo tiền tố
• Nâng cao các handler truy vấn analytics với tầng caching

Đã sửa

• Giải quyết các lỗi lint trên toàn bộ codebase

---

1.3.0 - 2026-03-28

Đã thêm

• Hệ thống gửi thông báo hoàn chỉnh với email (Nodemailer + Handlebars), push (Firebase Cloud Messaging), và các kênh trong ứng dụng
• Trực quan hóa heatmap quận huyện bằng Mapbox và dashboard hiệu suất agent trên web frontend
• Module đánh giá với đầy đủ các endpoint CRUD, các handler CQRS, và value object đánh giá 1-5 sao
• Kiểm thử đơn vị cho các module analytics, metrics, notifications, payments và search
• Cải thiện geo-search với truy vấn không gian PostGIS và các event handler listing-approved của Typesense
• Endpoint /health chuyên dụng với phản hồi timestamp

Đã thay đổi

• Refactor nội bộ cache service và các handler analytics để tăng độ tin cậy

Đã sửa

• Thiếu các thuộc tính AuthState trong các mock kiểm thử web frontend
• Cải thiện quy trình E2E: bước Prisma generate, cache trình duyệt, trace artifacts

---

1.2.0 - 2026-03-20

Đã thêm

• Tích hợp React Query cho data fetching với UX thử lại khi lỗi
• Nút chuyển đổi dark mode cho web frontend
• Tầng Redis caching cho các đường dẫn hot của search và analytics
• Pipeline NLP tiếng Việt (Underthesea) để phân tích mô tả bất động sản trong AI services
• MetricsService, HttpMetricsInterceptor Prometheus, và các hằng số metric tùy chỉnh
• Trang Agent Profile, xác minh KYC, Subscription, và bảng điều khiển Payment trên web frontend
• Kiểm thử đơn vị cho các MCP server (tìm kiếm bất động sản, phân tích thị trường, định giá)
• Kiểm thử đơn vị cho các hàm kiểm tra và tiện ích web frontend

Đã sửa

• Xóa thông tin xác thực MinIO được mã hóa cứng; thêm hỗ trợ presigned URL cho tải lên media
• Áp dụng kiểm tra JWT secret cho tất cả môi trường (không chỉ production)
• Thêm chỉ mục Review.userId còn thiếu để tăng hiệu suất truy vấn FK

---

1.1.0 - 2026-03-12

Đã thêm

• Dịch vụ phát hiện danh sách bất động sản trùng lặp để ngăn chặn các bài đăng dư thừa
• Giới hạn quota subscription với giới hạn tính năng theo gói và đo lường mức sử dụng
• Các chiến lược OAuth backend Google và Zalo cho đăng nhập mạng xã hội
• 58 bài kiểm thử đơn vị bao phủ các đường dẫn auth, payment và subscription quan trọng
• Skeleton loading, error boundary, và cải thiện khả năng truy cập trên web frontend
• Tích hợp theo dõi lỗi Sentry cho cả API và ứng dụng web

Đã sửa

• Tăng cường cấu hình triển khai Docker production cho tất cả các dịch vụ

---

1.0.0 - 2026-03-01

Đã thêm

Xác Thực & Bảo Mật

• Đăng ký và đăng nhập người dùng bằng số điện thoại và mật khẩu
• JWT access token (hết hạn sau 15 phút) với xoay vòng refresh token (hết hạn sau 7 ngày)
• Phát hiện xoay vòng dựa trên token family để ngăn chặn tấn công replay
• Hỗ trợ đăng nhập mạng xã hội OAuth (Google, Zalo)
• Quy trình xác minh KYC (Know Your Customer) (NONE -> PENDING -> VERIFIED/REJECTED)
• Kiểm soát truy cập theo vai trò với decorator @Roles() (USER, AGENT, ADMIN)
• Rate limiting: mặc định 60 req/phút, 10 req/phút cho auth, 20 req/phút cho payment callback
• ThrottlerBehindProxyGuard để theo dõi IP nhận biết X-Forwarded-For
• Tiêu đề bảo mật Helmet, cấu hình CORS
• Kiểm tra đầu vào (class-validator) và làm sạch nội dung (sanitize-html)
• Bảo vệ CSRF với mẫu double-submit cookie
• Che giấu PII trong structured log (Pino)
• Băm mật khẩu Bcrypt

Danh Sách Bất Động Sản

• CRUD đầy đủ cho danh sách bất động sản với máy trạng thái (DRAFT -> PENDING_REVIEW -> ACTIVE -> RESERVED -> SOLD/RENTED)
• Hỗ trợ tải lên media (S3/MinIO) với kiểm tra tệp
• Chấm điểm kiểm duyệt hỗ trợ bởi AI qua Claude API
• Hàng đợi kiểm duyệt admin với phê duyệt/từ chối hàng loạt
• Tạo danh sách bị giới hạn bởi quota gắn với gói subscription

Tìm Kiếm & Khám Phá

• Tìm kiếm bất động sản toàn văn bản qua Typesense với hỗ trợ tiếng Việt
• Tìm kiếm địa lý không gian bằng PostGIS (truy vấn lat/long + bán kính)
• Lọc nhiều mặt theo giá, loại bất động sản, số phòng ngủ, quận huyện
• Cập nhật chỉ mục tìm kiếm theo sự kiện (listing approved/updated/sold -> re-index)
• Xóa cache theo tiền tố cho kết quả tìm kiếm

Thanh Toán

• Xử lý thanh toán với tích hợp các nhà cung cấp VNPay, MoMo và ZaloPay
• Xử lý webhook callback idempotent với xác minh chữ ký
• Hỗ trợ hoàn tiền
• Chuyển đổi trạng thái nguyên tử (PENDING -> COMPLETED/FAILED)
• Phát sự kiện khi hoàn thành/thất bại thanh toán cho xử lý downstream

Subscription & Thanh Toán Định Kỳ

• Các gói subscription với cờ tính năng phân tầng (cột JSON)
• Đo lường mức sử dụng và kiểm tra quota (được hỗ trợ bởi Redis)
• Nâng cấp và hủy gói
• Theo dõi lịch sử thanh toán
• Theo dõi mức sử dụng theo sự kiện (listing.created -> đo lường mức sử dụng)

Bảng Điều Khiển Admin

• Dashboard với thống kê toàn hệ thống
• Quản lý người dùng (liệt kê, xem, cấm/bỏ cấm)
• Hàng đợi phê duyệt KYC với hành động phê duyệt/từ chối
• Hàng đợi kiểm duyệt danh sách với kiểm duyệt hàng loạt
• Thống kê doanh thu và analytics
• Điều chỉnh subscription cho người dùng cá nhân

Analytics & Dữ Liệu Thị Trường

• Báo cáo thị trường theo quận huyện với tổng hợp không gian PostGIS
• Phân tích xu hướng giá theo loại bất động sản và quận huyện
• Dữ liệu heatmap quận huyện (tổng hợp địa lý)
• Theo dõi và cập nhật chỉ số thị trường
• Phân phối báo cáo dựa trên cache

Thông Báo

• Gửi thông báo đa kênh: EMAIL, SMS, PUSH (FCM), IN_APP
• 8 listener theo sự kiện: email chào mừng, phê duyệt KYC, phê duyệt/từ chối danh sách, xác nhận/thất bại thanh toán, hết hạn subscription, vượt quota
• Mẫu email Handlebars với bản địa hóa tiếng Việt
• Tùy chọn thông báo người dùng (từ chối nhận theo kênh/loại)

Đánh Giá

• Đánh giá bất động sản và agent với xếp hạng 1-5 sao
• CRUD đánh giá với tính đa hình đối tượng (agent hoặc bất động sản)
• Tính toán xếp hạng trung bình theo đối tượng

Máy Chủ MCP (Model Context Protocol)

• Property Search Server: search_properties, compare_properties, get_property_details
• Market Analytics Server: get_market_report, analyze_trends, get_price_indices
• Valuation Server: estimate_valuation, extract_features, compare_valuations (XGBoost qua FastAPI)
• HTTP transport controller với McpRegistryService

Dịch Vụ AI

• Microservice FastAPI với mô hình định giá bất động sản XGBoost
• Kiểm duyệt nội dung mô tả danh sách được hỗ trợ bởi Claude API
• Tiền xử lý NLP tiếng Việt với Underthesea

Hạ Tầng

• PostgreSQL 16 với extension PostGIS (22 model, chỉ mục không gian)
• Tầng Redis caching cho search, analytics, quota và dữ liệu phiên
• Công cụ tìm kiếm Typesense với hỗ trợ tiếng Việt
• Endpoint Prometheus metrics với histogram thời gian yêu cầu HTTP và bộ đếm tỷ lệ lỗi
• Dashboard Grafana tự động cấu hình từ thư mục monitoring/
• Ghi log JSON có cấu trúc Pino với correlation ID
• Prisma ORM với hệ thống migration và dữ liệu seed (quận huyện/phường Thành phố Hồ Chí Minh, bất động sản mẫu, các gói subscription)

Frontend (Next.js 15)

• App Router với Tailwind CSS và quản lý trạng thái Zustand
• Trang tìm kiếm bất động sản với tích hợp bản đồ Mapbox GL
• Trang chi tiết danh sách với thư viện media
• Dashboard agent với quản lý KYC, subscription và thanh toán
• Trực quan hóa heatmap quận huyện
• Giao diện định giá bất động sản với tích hợp AVM
• Nút chuyển đổi dark mode
• Skeleton loading và error boundary
• Văn bản giao diện tiếng Việt xuyên suốt (loại bất động sản, quận huyện, tiền tệ theo VND)

Trải Nghiệm Nhà Phát Triển

• Monorepo với pnpm workspaces và Turborepo
• ESLint với các quy tắc sắp xếp import
• Định dạng code Prettier
• Git hook Husky
• Kiểm thử E2E với Playwright (14 tệp kiểm thử web)
• CI pipeline GitHub Actions (lint -> typecheck -> test -> build)

Bảo Mật

• Lưu trữ token dựa trên cookie httpOnly với tăng cường CSRF
• Khóa idempotency trên các luồng thanh toán với kiểm tra số tiền
• Kiểm tra magic byte cho tệp tải lên media
• Ghi log kiểm tra admin
• Kiểm tra audience/issuer JWT
• Kiểm tra biến môi trường production
• .env.example được làm sạch (không rò rỉ bí mật)
• Hook tắt dịch vụ nhẹ nhàng để kết thúc tiến trình sạch