Lộ Trình Phát Triển

Dự Án	PTX Channel Manager (ptx-cm)
Phiên Bản Hiện Tại	2.0.0
Cập Nhật	2026-02-20

---

Các Giai Đoạn Dự Án

Giai Đoạn 01: Chống Overbooking Cốt Lõi

Trạng Thái	⚠️ MỘT PHẦN (hạ tầng hoàn thành, tích hợp OTA chưa triển khai)
Ưu Tiên	P1
Timeline	MVP ban đầu
Cập Nhật	2026-02-18

Tính Năng Đã Giao:

• [x] Quản Lý Tài Khoản OTA (FR-01) - Lưu trữ credential mã hóa, theo dõi session. ⚠️ testConnection/refreshSession là stub.
• [ ] Khám Phá & Import Property (FR-02) - ❌ OTA adapter là stub. Không có auto-discover, không có UI import.
• [x] Kéo Booking (FR-03) - Điều phối BullMQ + loại trùng. ⚠️ OTA fetchBookings() trả về rỗng. Không có kéo tăng dần.
• [x] Đồng Bộ Phòng Trống Tự Động (FR-04) - Logic tính toán + phát hiện overbooking. ⚠️ OTA pushAvailability() là stub.
• [x] Quản Lý Property & Phòng (FR-05) - CRUD cho property, room type, mapping
• [x] Dashboard Trạng Thái Đồng Bộ (FR-06) - Tổng quan thời gian thực theo property/OTA
• [x] Cảnh Báo Overbooking (FR-07) - Tạo/giải quyết cảnh báo ✅. ⚠️ LINE Notify stub. Email phụ thuộc cấu hình SMTP.
• [x] Truy Cập Theo Quốc Gia (FR-08) - Nhân viên giới hạn theo quốc gia, quản lý thấy tất cả

Sản Phẩm:

• Schema database (15 bảng)
• Backend NestJS với 10 module cốt lõi
• Frontend Next.js với 6 trang (login, dashboard, properties, bookings, alerts, sync-jobs)
• OTA adapter (Booking.com, Agoda, Traveloka, Expedia) — CẢ 4 LÀ STUB (không có HTTP/scraping thực)
• BullMQ job queue cho đồng bộ bất đồng bộ (điều phối đã nối, adapter trống)

Thiếu Sót Đã Biết:

• Cả 4 OTA adapter trả về rỗng/false — sync engine chạy nhưng không tạo dữ liệu thực
• Trang chi tiết /ota-accounts/[id] → 404 (danh sách link đến route không tồn tại)
• Màn hình Import Property (S-07) chưa xây dựng
• Không có nút Force Sync trong UI sync-jobs (backend endpoint tồn tại)
• OtaConnection + OtaRoomMapping chưa seed

---

Giai Đoạn 02: Hiệu Quả Vận Hành

Trạng Thái	❌ CHƯA TRIỂN KHAI
Ưu Tiên	P2
Timeline	Sau MVP
Cập Nhật	2026-02-18

Tính Năng CHƯA Xây Dựng:

• [ ] Cập Nhật Giá Hàng Loạt (FR-09) - ❌ Không có service, controller, API, UI. Model DB (Rate, RateRule) tồn tại nhưng chưa dùng.
• [ ] Lịch Phòng Trống (FR-10) - ❌ Không có route, component, trang.
• [ ] Timeline Booking (FR-11) - ❌ Không có route, component, trang.
• [ ] Đồng Bộ Hủy (FR-12) - ❌ Không có cancelBooking trong interface adapter. Workflow trạng thái có thể đánh dấu hủy nhưng không phát hiện phía OTA.

Trạng Thái Theo Tính Năng Con:

• FR-09: Thiết kế ✅ | Triển khai ❌ | Testing ❌
• FR-10: Thiết kế ✅ | Triển khai ❌ | Testing ❌
• FR-11: Thiết kế ✅ | Triển khai ❌ | Testing ❌
• FR-12: Thiết kế ✅ | Triển khai ❌ | Testing ❌

---

Giai Đoạn 2.5: Hồ Sơ User & Cải Thiện Auth

Trạng Thái	✅ HOÀN THÀNH (tính đến 2026-02-13)
Ưu Tiên	P2
Timeline	Cải tiến giữa chu kỳ

Tính Năng Đã Giao:

• [x] Quản Lý Hồ Sơ User (FR-16) - Chỉnh sửa tên, email, ngôn ngữ
• [x] Đổi Mật Khẩu (FR-17) - Cập nhật mật khẩu an toàn với xác minh
• [x] Auth Hydration (FR-18) - GET /users/me khi mount app
• [x] Theme Client-Side (FR-19) - Chuyển đổi sáng/tối với localStorage
• [x] Admin Reset Mật Khẩu (FR-20) - Mật khẩu tạm & link reset qua email
• [x] Quên Mật Khẩu (FR-21) - Tự reset mật khẩu

Sản Phẩm:

• Trang /profile với form chỉnh sửa
• Modal đổi mật khẩu với luồng mustChangePassword
• Endpoint GET /users/me cho khôi phục auth
• Chuyển đổi theme trong TopBar
• Trang công khai: /forgot-password, /reset-password, /change-password
• Endpoint admin: POST /users/:id/reset-password, POST /users/:id/send-reset-link
• Endpoint công khai: POST /auth/forgot-password, POST /auth/reset-password
• Model PasswordResetToken với hash SHA-256
• Tích hợp dịch vụ email (HTML reset email)
• Cron job hàng ngày cho dọn dẹp token

Chi Tiết Triển Khai:

• Form hồ sơ: zod validation trên frontend, class-validator trên backend
• Đổi mật khẩu: Xác minh mật khẩu hiện tại, tối thiểu 8 ký tự, hỗ trợ mustChangePassword
• Auth hydration: Gọi khi mount app, 401 → chuyển hướng đăng nhập
• Theme: Lưu trong localStorage, không lưu backend
• Password reset: Hash token SHA-256, hết hạn 1 giờ, dùng một lần
• Giới hạn tốc độ: 3 token mỗi user mỗi giờ, throttle trên endpoint
• Ngăn chặn liệt kê email: Luôn trả thành công cho forgot-password
• Bảo vệ phân cấp Superadmin: Không thể reset mật khẩu SA
• Vô hiệu session: Tất cả refresh token bị thu hồi khi reset mật khẩu

---

Giai Đoạn 03: Sprint Tăng Cường Bảo Mật

Trạng Thái	✅ HOÀN THÀNH (tính đến 2026-02-12)
Ưu Tiên	P1 (Bảo Mật)
Timeline	Cải thiện bảo mật liên tục

Các Pha Đã Triển Khai:

Pha 03.0: Activity Logging (12/02)

• [x] Middleware NestJS cho ghi log HTTP request
• [x] Đọc đuôi file log hiệu quả (buffer 64KB)
• [x] SuperAdminGuard bảo vệ endpoint activity log
• [x] Activity log dashboard panel với SWR polling
• [x] Toggle biến môi trường (ACTIVITY_LOG_ENABLED)

Thay Đổi Code:

• apps/api/src/common/middleware/activity-log.middleware.ts - Middleware mới ghi log tất cả request
• apps/api/src/modules/activity-logs/ - Module mới với controller & service
• apps/api/src/common/guards/super-admin.guard.ts - Guard mới cho endpoint activity log
• apps/web/components/dashboard/activity-log-panel.tsx - Trình xem activity kiểu terminal
• logs/ thêm vào .gitignore (file log loại khỏi version control)
• .env.example - Thêm ACTIVITY_LOG_ENABLED=true

Tính Năng:

• Format log: TIMESTAMP | EMAIL | METHOD | PATH | STATUS | SCREEN
• Loại trừ chính endpoint activity-logs khỏi logging
• Badge phương thức HTTP có mã màu (GET/POST/PATCH/PUT/DELETE)
• Highlight trạng thái (2xx/3xx trắng, 4xx vàng, 5xx đỏ)
• SWR polling mỗi 5 giây với điều khiển tạm dừng/tiếp tục
• Chọn giới hạn (1-500 mục, mặc định 100)
• Panel tối kiểu terminal trên dashboard (chỉ super admin)

Pha 03.1: Tăng Cường Auth (10/02)

• [x] Refresh token lưu DB (RefreshToken model)
• [x] Xoay token mỗi lần refresh
• [x] Thu hồi token khi logout & đổi mật khẩu
• [x] Theo dõi JWT ID (jti) để quản lý session
• [x] Giới hạn tốc độ: 5/phút đăng nhập, 10/phút refresh
• [x] Cookie HttpOnly cho lưu trữ token

Thay Đổi Code:

• packages/database/prisma/schema.prisma - Thêm model RefreshToken
• apps/api/src/modules/auth/auth.service.ts - Lưu trữ & thu hồi token
• apps/api/src/modules/auth/auth.controller.ts - Xử lý token dựa cookie
• .env.example - Thêm JWT_REFRESH_SECRET

Pha 03.2: Kiểm Soát Truy Cập (11/02)

• [x] Guard & decorator phân quyền quốc gia
• [x] Helper assertPropertyAccess()
• [x] Guard @Roles(manager) trên mutation
• [x] Validation quốc gia cho phép (TH, VN, ID)
• [x] Whitelist sortBy trên DTO danh sách

Thay Đổi Code:

• apps/api/src/common/guards/country-scope.guard.ts - Guard mới
• apps/api/src/common/decorators/country-scope.decorator.ts - Decorator mới
• apps/api/src/common/helpers/country-scope.helper.ts - Helper assertPropertyAccess
• Tất cả DTO danh sách cập nhật validation sortBy

Pha 03.3: Bảo Mật Frontend (11/02)

• [x] Edge middleware cho bảo vệ route
• [x] Queue refresh token dựa Promise (sửa race condition)
• [x] Chuyển tiếp Content-Type header trong proxy
• [x] Luồng token chỉ cookie

Thay Đổi Code:

• apps/web/middleware.ts - Bảo vệ route, chuyển hướng đến /login
• apps/web/lib/api-client.ts - Queue refresh token, interceptor
• apps/web/app/api/[...proxy]/route.ts - Proxy với chuyển tiếp header

Pha 03.4: Bảo Mật Hạ Tầng (12/02)

• [x] Docker port chỉ bind 127.0.0.1
• [x] Xác thực mật khẩu Redis
• [x] Placeholder ENCRYPTION_KEY trong .env.example

Thay Đổi Code:

• docker-compose.yml - Port binding đến 127.0.0.1
• .env.example - Tài liệu ENCRYPTION_KEY

Kết Quả Audit Bảo Mật:

• ✅ Không có credential plaintext trong code
• ✅ Tất cả token HttpOnly + SameSite=lax
• ✅ Giới hạn tốc độ trên endpoint auth
• ✅ Phân quyền quốc gia thực thi 100% truy vấn
• ✅ Quyền sở hữu property được xác minh
• ✅ Kiểm soát truy cập theo vai trò đang hoạt động
• ✅ Kết nối database chỉ localhost
• ✅ Activity logging cho audit trail admin
• ✅ SuperAdminGuard bảo vệ endpoint nhạy cảm

---

Giai Đoạn 04: Thông Minh & Phân Tích (Tương Lai)

Trạng Thái	🔄 ĐÃ LÊN KẾ HOẠCH
Ưu Tiên	P3
Timeline Dự Kiến	Q2 2026

Tính Năng:

• [ ] FR-13: Kiểm Tra Giá Đồng Nhất - So sánh giá giữa các OTA
• [ ] FR-14: Phân Tích Doanh Thu - Doanh thu theo OTA/property/quốc gia, xu hướng lấp đầy, ADR
• [ ] FR-15: Rate Rules Engine - Tự động áp dụng quy tắc markup/discount/mùa

Tiêu Chí Nghiệm Thu:

• Báo cáo giá đồng nhất hiển thị chênh lệch với ngưỡng
• Dashboard doanh thu với bộ lọc khoảng ngày, tùy chọn nhóm
• Rate rule cấu hình theo property/OTA với khoảng ngày hiệu lực
• Tính toán giá tự động tuân theo ưu tiên quy tắc

Cách Tiếp Cận Kỹ Thuật:

• AnalyticsService mới với truy vấn tổng hợp
• RateRulesService cho áp dụng quy tắc trong định giá
• Trang dashboard với trực quan hóa recharts

---

Giai Đoạn 05: Hiệu Suất & Cache (Tương Lai)

Trạng Thái	📋 BACKLOG
Ưu Tiên	P3
Timeline Dự Kiến	Q3 2026

Mục Tiêu:

• Cache Redis cho danh sách property/booking (TTL 5 phút)
• Tối ưu truy vấn với Prisma select()
• Rà soát và tối ưu index database

Chỉ Số Mục Tiêu:

• Thời gian phản hồi API P95 < 200ms (hiện tại ~500ms)
• Endpoint danh sách < 100ms

---

Giai Đoạn 06: Cập Nhật Thời Gian Thực (Tương Lai)

Trạng Thái	📋 BACKLOG
Ưu Tiên	P2
Timeline Dự Kiến	Q3 2026

Tính Năng:

• WebSocket cho cập nhật trạng thái đồng bộ
• Thông báo cảnh báo thời gian thực
• Auto-refresh lưới phòng trống

Công Nghệ:

• Socket.io hoặc thư viện ws
• RxJS cho luồng sự kiện
• Frontend subscription qua useSWRSubscription hoặc hook tùy chỉnh

---

Trạng Thái Mốc Thời Gian

Mốc	Mục Tiêu	Trạng Thái	Hoàn Thành %
MVP (P1)	2026-01-31	⚠️ Một phần	~70% (hạ tầng xong, OTA adapter đều là stub)
Vận Hành (P2)	2026-02-07	❌ Chưa bắt đầu	0% (FR-09/10/11/12 chưa xây)
Hồ Sơ User (P2.5)	2026-02-13	✅ Hoàn thành	100%
Sprint Bảo Mật (P1)	2026-02-12	✅ Hoàn thành	100%
Activity Logging (P1)	2026-02-12	✅ Hoàn thành	100%
Thông Minh (P3)	2026-04-30	🔄 Đang lên kế hoạch	0%
Hiệu Suất (P3)	2026-05-31	📋 Backlog	0%
Thời Gian Thực (P2)	2026-06-30	📋 Backlog	0%

---

Vấn Đề Đã Biết & Nợ Kỹ Thuật

Nợ Code

• [ ] Audit trail chưa nối với AuditLogInterceptor (nhỏ)
• [ ] OTA adapter dùng Playwright (mong manh, chưa sẵn sàng production quy mô)
• [ ] Không có chiến lược retry lỗi toàn diện cho OTA API call
• [ ] Cấu hình giới hạn tốc độ hardcoded (nên cấu hình được)

Thiếu Tính Năng

• [ ] Luồng mời/tiếp nhận user
• [ ] Template email cho thông báo
• [ ] Import user hàng loạt (CSV)
• [ ] Thao tác property hàng loạt (bật/tắt)
• [ ] Lọc cảnh báo nâng cao & workflow giải quyết

Hiệu Suất

• [ ] Không có cache cho truy vấn hay truy cập
• [ ] Danh sách booking lớn (1000+) có thể chậm
• [ ] Không có index DB trên (room_type_id, date, otaType)

Tài Liệu

• [ ] Hướng dẫn triển khai OTA adapter
• [ ] Deploy lên production (Docker/K8s)
• [ ] Thiết lập giám sát & cảnh báo
• [ ] Quy trình khôi phục thảm họa

---

Chỉ Số Thành Công

Q1 2026

• ✅ Không sự cố overbooking (trước đây 5-10/tuần)
• ✅ Độ trễ đồng bộ trung bình 60 giây (mục tiêu: <60 giây)
• ✅ 99% uptime trong giờ làm việc
• ✅ Tất cả 4 kênh OTA đồng bộ ổn định

Bảo Mật (02/2026)

• ✅ Tất cả auth token được theo dõi DB
• ✅ Phân quyền quốc gia thực thi 100% truy vấn
• ✅ Giới hạn tốc độ hoạt động trên tất cả endpoint auth
• ✅ Không lưu credential plaintext

Tỷ Lệ Sử Dụng

• ✅ 15 tài khoản nhân viên đang hoạt động
• ✅ 100+ property được quản lý
• ✅ < 5 phút thời gian trung bình tìm/quản lý booking

---

Quy Tắc & Ràng Buộc Phát Triển

Đội: 1 developer duy nhất

Tech Stack: Xem Kiến Trúc Hệ Thống để biết chi tiết stack đầy đủ.

Tiêu Chuẩn:

• Tất cả tính năng branch từ main, yêu cầu PR
• Test phải pass trước khi merge (jest + coverage 80%+)
• Code review bởi: [chủ dự án]
• Format commit: Conventional Commits
• Tài liệu: Cập nhật docs/ khi merge tính năng

Triển Khai:

• Deploy thủ công (chưa có CI/CD)
• Chiến lược blue-green (nếu nhiều máy chủ)
• Migration database: Prisma migrate

---

30 Ngày Tiếp Theo (02 - 03/2026)

Tuần 1 (13-19/02)

• [x] Hoàn thành tính năng admin reset mật khẩu (mật khẩu tạm + link email)
• [x] Hoàn thành luồng tự quên mật khẩu
• [ ] User acceptance testing với đội vận hành
• [ ] Sửa lỗi từ testing Giai đoạn 2.5

Tuần 2-3 (19/02 - 05/03)

• [ ] Profiling hiệu suất & phân tích cache
• [ ] Bắt đầu thiết kế Rate Rules engine
• [ ] Thu thập feedback UI/UX từ user

Tuần 4 (05-12/03)

• [ ] Sprint kế hoạch cho Giai đoạn 04 (Analytics)
• [ ] Tinh chỉnh hiệu suất hạ tầng
• [ ] Deploy production nếu cần

---

Phụ Thuộc Quan Trọng

• PostgreSQL 16 database (cần backup production)
• Redis 7 cho BullMQ (đường dẫn quan trọng cho job bất đồng bộ)
• Ổn định API OTA (Booking.com, Agoda, Traveloka, Expedia)
• Chứng chỉ SSL cho HTTPS (production)
• Máy chủ SMTP cho thông báo email

---

Kế Hoạch Giao Tiếp

• Standup hàng tuần: [sẽ xác định]
• Theo dõi issue: [GitHub Issues, nếu áp dụng]
• Tài liệu: Cập nhật mỗi lần merge tính năng
• Cập nhật stakeholder: [sẽ xác định]

---

Tài Liệu Liên Quan

• SRD.md - Yêu cầu chức năng
• API_SPEC.md - Tham khảo API endpoint
• DB_DESIGN.md - Schema database
• system-architecture.md - Kiến trúc & chi tiết bảo mật
• code-standards.md - Hướng dẫn phát triển
• codebase-summary.md - Cấu trúc dự án

---

Lịch Sử Thay Đổi

Ngày	Phiên Bản	Thay Đổi
2026-02-18	2.1.0	Audit triển khai: sửa Giai đoạn 01 thành MỘT PHẦN (OTA adapter đều là stub), Giai đoạn 02 thành CHƯA TRIỂN KHAI (FR-09/10/11/12 chưa xây), cập nhật mốc
2026-02-13	2.2.0	Thêm admin reset mật khẩu (mật khẩu tạm, link email) và tự quên mật khẩu vào Giai đoạn 2.5
2026-02-12	2.1.0	Thêm Pha 03.0 Activity Logging (middleware, API, dashboard panel), SuperAdminGuard
2026-02-12	2.0.0	Thêm các pha sprint bảo mật (01-04), Giai đoạn 2.5 hồ sơ user hoàn thành
2026-02-10	1.9.0	Giai đoạn 01 MVP + Giai đoạn 02 hoàn thành
2026-02-01	1.0.0	Lộ trình ban đầu (skeleton)