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](https://keepachangelog.com/en/1.1.0/),
và dự án này tuân theo [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [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

[Unreleased]: https://github.com/goodgo/platform-ai/compare/v1.4.0...HEAD
[1.4.0]: https://github.com/goodgo/platform-ai/compare/v1.3.0...v1.4.0
[1.3.0]: https://github.com/goodgo/platform-ai/compare/v1.2.0...v1.3.0
[1.2.0]: https://github.com/goodgo/platform-ai/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/goodgo/platform-ai/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/goodgo/platform-ai/releases/tag/v1.0.0