PTX Channel Manager - Tổng Quan Dự Án & PDR
| Dự Án | PTX Channel Manager (ptx-cm) |
| Phiên Bản | 2.0.0 |
| Trạng Thái | Đang hoạt động - Sau Sprint Bảo Mật |
| Cập Nhật | 2026-02-20 |
1. Tóm Tắt
PTX Channel Manager là nền tảng quản lý kênh OTA thống nhất, ngăn chặn overbooking bằng cách tự động đồng bộ phòng trống giữa Booking.com, Agoda, Traveloka và Expedia trong vòng 60 giây. Được xây dựng cho hơn 100 property tại Việt Nam, Indonesia và Malaysia, với kiểm soát truy cập theo quốc gia và quản lý credential OTA được mã hóa.
Thành tựu chính: Giảm 95% công việc xử lý overbooking thủ công nhờ cảnh báo thời gian thực và đồng bộ tự động trên 4 nền tảng OTA.
2. Vấn Đề Cần Giải Quyết
Trước PTX-CM
- Rủi ro Overbooking thủ công: Property phải theo dõi thủ công trên 4 dashboard OTA riêng biệt
- Lỗi con người: Lỗi nhập liệu gây 5-10% sự cố overbooking hàng tháng
- Đồng bộ chậm: Thay đổi mất 2-4 giờ để cập nhật trên tất cả kênh
- Thiếu cảnh báo: Không có hệ thống cảnh báo thời gian thực cho overbooking
- Quản lý credential: Credential OTA lưu trong bảng tính không mã hóa
- Phức tạp đa quốc gia: Không có kiểm soát truy cập theo quốc gia
Giải Pháp
Dashboard thống nhất với polling tự động, cảnh báo overbooking thời gian thực, lưu trữ credential mã hóa và truy cập phân quyền theo quốc gia.
3. Người Dùng & Trường Hợp Sử Dụng
Người Dùng Chính
| Vai Trò | Trường Hợp Sử Dụng | Tần Suất |
|---|---|---|
| Quản lý Property | Theo dõi công suất, xem timeline booking, quản lý kết nối OTA | Hàng ngày |
| Nhân viên Đặt phòng | Kiểm tra phòng trống, xác nhận booking, xử lý cảnh báo overbooking | Hàng giờ |
| Tài chính | Xem chỉ số doanh thu, xuất dữ liệu booking cho kế toán | Hàng tuần |
| Vận hành OTA | Cấu hình tài khoản OTA, test kết nối, quản lý room mapping | Hàng tuần |
| Chăm sóc khách hàng | Kiểm tra lịch sử booking, xem thông tin khách, xử lý khiếu nại | Hàng ngày |
| Admin/Super Admin | Quản lý user, vai trò, quyền hạn, cài đặt hệ thống | Hàng tuần |
Quy Trình Chính
Quy trình 1: Kết Nối OTA Mới
- Quản lý vào OTA Accounts → Connect
- Nhập credential OTA (được mã hóa an toàn)
- Test kết nối để xác minh xác thực
- Map room type với rate plan OTA
- Kích hoạt đồng bộ cho property
Quy trình 2: Booking Mới
- OTA gửi booking mới qua API
- Hệ thống polling OTA extranet mỗi 2-3 phút
- Kéo bản ghi booking → loại trùng theo OTA booking ID
- Tính toán lại phòng trống theo room type
- Nếu phát hiện overbooking → Tạo cảnh báo + thông báo nhân viên
- Đẩy cập nhật phòng trống lên tất cả OTA đã kết nối
Quy trình 3: Xử Lý Overbooking
- Quản lý thấy cảnh báo trên dashboard
- Mở chi tiết booking → xem timeline + lịch sử trạng thái
- Chuyển trạng thái booking qua state machine (VD: Confirmed → CheckedIn)
- Hệ thống tự động tính toán lại phòng trống
- Gửi cập nhật giá/phòng trống lên OTA
4. Yêu Cầu Chức Năng (Tính Năng)
Giai đoạn 1: Xác Thực & Phân Quyền (HOÀN THÀNH)
- Đăng nhập JWT với email/mật khẩu
- Refresh token xoay vòng với thu hồi token
- Kiểm soát truy cập theo vai trò với quyền hạn bitmask
- Truy cập phân quyền theo quốc gia (nhân viên chỉ thấy quốc gia của mình)
- Lưu mật khẩu mã hóa với bcrypt
- Quy trình đặt lại mật khẩu (quên mật khẩu, reset token, đổi mật khẩu)
- Lưu token HttpOnly cookie
- Giới hạn tốc độ đăng nhập (5/phút) và refresh (10/phút)
Giai đoạn 2: Quản Lý Property & Inventory (HOÀN THÀNH)
- CRUD property với gán timezone/tiền tệ
- Định nghĩa room type theo property (tên, số lượng, giá cơ bản)
- Quản lý supplier/chủ phòng với thông tin ngân hàng
- Phân bổ supplier ↔ room với quy tắc inventory
- Danh sách property với lọc theo quốc gia và phân trang
Giai đoạn 3: Tích Hợp OTA (HOÀN THÀNH)
- Quản lý tài khoản OTA với credential mã hóa AES-256-GCM
- Hỗ trợ đa OTA: Booking.com, Agoda, Traveloka, Expedia
- Mẫu OTA adapter factory cho triển khai linh hoạt
- Quản lý kết nối OTA (liên kết property ↔ tài khoản OTA)
- Mapping room type ↔ OTA rate plan/room ID
- Khám phá OTA và tự động import property
- Test kết nối với báo cáo lỗi
Giai đoạn 4: Đồng Bộ & Quản Lý Booking (HOÀN THÀNH)
- Lịch polling tự động (interval 150 giây mỗi property)
- Dịch vụ kéo booking với mẫu OTA adapter
- Loại trùng booking theo OTA booking ID
- Lưu trữ booking thời gian thực trong PostgreSQL
- Danh sách booking với bộ lọc (khoảng ngày, trạng thái, nguồn OTA)
- Xem chi tiết booking với timeline audit đầy đủ
- Dialog chuyển trạng thái với workflow phân quyền
- Hiển thị metadata booking (tên khách, room type, giá, v.v.)
Giai đoạn 5: Phòng Trống & Cảnh Báo (HOÀN THÀNH)
- Tính toán phòng trống tự động sau mỗi booking
- Theo dõi phòng trống hàng ngày theo room type
- Phát hiện overbooking (đã đặt ≥ tổng phòng)
- Tạo cảnh báo cho điều kiện nghiêm trọng
- Danh sách cảnh báo với theo dõi trạng thái (mới, đã xử lý, tạm ẩn)
- Thông báo nhân viên qua email/dashboard
- Chi tiết cảnh báo với phân tích nguyên nhân
Giai đoạn 6: Dashboard & Giám Sát (HOÀN THÀNH)
- Thẻ KPI: Tỷ lệ lấp đầy, doanh thu, giá bình quân, tỷ lệ đồng bộ thành công
- Hiển thị trạng thái đồng bộ: kích thước queue, số lượng job, tỷ lệ lỗi
- Bảng booking gần đây
- Tóm tắt cảnh báo đang hoạt động
- Chỉ báo sức khỏe hệ thống (postgres, redis, kết nối OTA)
Giai đoạn 7: Cài Đặt & Cấu Hình (HOÀN THÀNH)
- Cài đặt toàn cục: Interval kéo booking, bật/tắt thông báo, số phòng đệm
- Quản lý user: CRUD tài khoản nhân viên, gán vai trò, phân quyền quốc gia
- Định nghĩa vai trò với bitmask permission
- Quản lý dữ liệu quốc gia
- Tùy chỉnh trạng thái booking với màu/icon
- Trình soạn thảo state machine chuyển trạng thái booking (workflow trực quan)
- Tùy chọn thông báo (email, LINE, Slack)
Giai đoạn 8: Audit & Tuân Thủ (HOÀN THÀNH)
- Theo dõi activity log tất cả HTTP request (email, method, path, status)
- Timeline lịch sử booking với sự kiện thay đổi trạng thái
- Audit trail hành động user
- Xuất dữ liệu: Booking sang CSV, property sang CSV
- Tuân thủ: Cài đặt lưu trữ dữ liệu GDPR
5. Yêu Cầu Phi Chức Năng
Mục Tiêu Hiệu Suất
| Chỉ Số | Mục Tiêu | Trạng Thái |
|---|---|---|
| Độ trễ đồng bộ booking | < 60 giây (từ poll đến push OTA) | Đang hoạt động |
| Thời gian tải dashboard | < 2 giây | Đang hoạt động |
| Thời gian phản hồi API (p95) | < 500ms | Đang hoạt động |
| Thời gian truy vấn DB (p95) | < 100ms | Đang hoạt động |
| Người dùng đồng thời | 50+ | Đang hoạt động |
| Throughput booking | 1000 booking/giờ | Đang hoạt động |
Khả Năng Mở Rộng
- Monorepo hỗ trợ 100+ property mỗi instance
- Sẵn sàng multi-tenant (cô lập theo quốc gia)
- BullMQ với Redis cho xử lý bất đồng bộ
- PostgreSQL với index cho truy vấn nhanh
- Backend stateless cho mở rộng ngang
Tiêu Chuẩn Bảo Mật
- JWT với access token 15 phút + refresh token 7 ngày
- Mã hóa AES-256-GCM cho credential OTA
- Hash mật khẩu bcrypt với salt rounds: 12
- Truy vấn phân quyền quốc gia ngăn rò rỉ dữ liệu
- Giới hạn tốc độ trên endpoint nhạy cảm
- HTTPS/TLS cho toàn bộ traffic
- Cookie HttpOnly cho lưu trữ token
Khả Dụng
- Mục tiêu: 99.5% uptime
- Sao lưu database: Hàng ngày + snapshot tự động
- Redis persistence: AOF bật
- Giảm cấp uyển chuyển: Job bất đồng bộ retry khi lỗi
- Health check: Liveness probe trên endpoint /health
Bảo Trì
- TypeScript cho an toàn kiểu
- Tiêu chuẩn kiến trúc NestJS
- Tài liệu code qua JSDoc
- Test coverage: 80% service, 60% controller
- Semantic versioning cho release
- Duy trì changelog
6. Tham Khảo Kỹ Thuật
Để biết thông tin kỹ thuật chi tiết, xem:
- Kiến Trúc Hệ Thống — Tech stack, design pattern, luồng sync engine, luồng xác thực, ER diagram
- Thiết Kế Database — Schema đầy đủ với DDL, index, constraint và ER diagram
- Tóm Tắt Mã Nguồn — Module map, cấu trúc thư mục, route frontend
9. Lộ Trình Phát Triển
Đã Hoàn Thành (v2.0.0)
- [x] Xác thực JWT với refresh token
- [x] Kiểm soát truy cập theo vai trò (6 vai trò mặc định)
- [x] Cô lập dữ liệu theo quốc gia
- [x] Framework OTA adapter (4 adapter)
- [x] Pipeline đồng bộ booking tự động
- [x] Tính toán phòng trống & cảnh báo overbooking
- [x] KPI dashboard
- [x] Timeline booking & lịch sử audit
- [x] Quản lý user & vai trò
- [x] Lưu trữ credential OTA mã hóa
- [x] Giới hạn tốc độ & tăng cường bảo mật
Đang Triển Khai / Kế Hoạch
- [ ] Module Quản Lý Giá - Cấu hình giá động theo kênh, quy tắc mùa, markup/discount
- [ ] Hỗ Trợ Webhook - Nhận sự kiện booking thời gian thực từ đối tác OTA
- [ ] Ứng Dụng Di Động - React Native cho thông báo nhân viên
- [ ] Phân Tích Nâng Cao - Dự báo doanh thu, xu hướng lấp đầy, phân tích giá đối thủ
- [ ] Hỗ Trợ 2FA - Xác thực hai yếu tố TOTP/SMS cho tài khoản user
- [ ] Thao Tác Hàng Loạt - Cập nhật hàng loạt room type, giá, phòng trống
- [ ] API Keys - Cho phép tích hợp bên ngoài (PMS, channel manager, revenue mgmt)
- [ ] Adapter Airbnb/Vrbo - Mở rộng sang các nền tảng OTA khác
- [ ] Kênh Thông Báo - Tích hợp Slack, LINE, Telegram ngoài email
- [ ] Đa Ngôn Ngữ - Mở rộng i18n ngoài tiếng Anh/tiếng Việt
10. Chỉ Số Thành Công
Chỉ Số Kinh Doanh
| Chỉ Số | Baseline | Mục Tiêu (6 tháng) | Hiện Tại |
|---|---|---|---|
| Sự cố overbooking | 50/tháng | < 5/tháng | Đang theo dõi |
| Thời gian đồng bộ thủ công | 4 giờ/ngày | 0 giờ | Giảm 95% |
| Độ phủ property | 0% | 100% (100+ property) | 85% |
| Tỷ lệ sử dụng nhân viên | 0% | 90% | 70% |
| Khả dụng hệ thống | N/A | 99.5% | 99.8% |
Chỉ Số Kỹ Thuật
| Chỉ Số | Mục Tiêu | Trạng Thái |
|---|---|---|
| Test coverage (service) | 80% | Đang triển khai |
| Tần suất deploy | Hàng tuần | Đang hoạt động |
| Thời gian phản hồi sự cố | < 15 phút | < 10 phút |
| Tần suất backup database | Hàng ngày | Tự động |
11. Đánh Giá Rủi Ro
| Rủi Ro | Ảnh Hưởng | Khả Năng | Giảm Thiểu |
|---|---|---|---|
| API OTA thay đổi làm hỏng tích hợp | Cao | Trung bình | Adapter version, test tương thích ngược |
| Lộ credential (rò rỉ key AES-256) | Nghiêm trọng | Thấp | Xoay key mã hóa hàng năm, audit log |
| Database quá tải (booking lượng lớn) | Cao | Thấp | Connection pooling, tối ưu truy vấn, read replica |
| Nhân viên lạm dụng bypass phân quyền | Trung bình | Thấp | Phân tách vai trò, activity logging, review audit |
| Redis lỗi (mất queue) | Trung bình | Thấp | AOF persistence, cảnh báo giám sát |
12. Ràng Buộc & Phụ Thuộc
Phụ Thuộc Bên Ngoài
- Booking.com API - Ổn định phòng trống, giá cho đồng bộ
- Agoda Extranet - Ổn định parsing cho web scraping
- PostgreSQL 16 - Đảm bảo ACID cho tính nhất quán booking
- Redis 7 - Queue persistence cho theo dõi job bất đồng bộ
Phụ Thuộc Nội Bộ
packages/database(Prisma schema) phải đồng bộ với tất cả servicepackages/types(enum) dùng chung giữa frontend và backend- Triển khai OTA adapter phải tuân theo interface
IOtaAdapter
Ràng Buộc
- Interval polling tối đa 150 giây (giới hạn tốc độ API OTA)
- Key mã hóa phải ≥ 256 bit (AES-256)
- Token JWT phải hết hạn: access=15 phút, refresh=7 ngày
- Phân quyền quốc gia giới hạn: VN, ID, MY (có thể mở rộng)
13. Tiêu Chí Thành Công & Nghiệm Thu
Nghiệm Thu MVP (v1.0.0 - HOÀN THÀNH)
- [x] User có thể đăng nhập bằng email/mật khẩu
- [x] Property kết nối với tài khoản OTA an toàn
- [x] Booking tự động đồng bộ mỗi 2-3 phút
- [x] Phòng trống tính toán lại thời gian thực
- [x] Cảnh báo overbooking khi inventory vượt công suất
- [x] Nhân viên chỉ thấy quốc gia được gán
- [x] Quản lý có thể chuyển đổi giữa các quốc gia
Sẵn Sàng Production (v2.0.0 - HOÀN THÀNH)
- [x] Tất cả endpoint bảo mật sau JWT auth
- [x] Truy vấn phân quyền quốc gia ngăn rò rỉ dữ liệu
- [x] Credential OTA mã hóa AES-256-GCM
- [x] Giới hạn tốc độ ngăn tấn công brute-force
- [x] Activity log audit tất cả hành động user
- [x] 99.5% uptime trong môi trường staging
- [x] Backup database tự động hàng ngày
- [x] Security audit hoàn thành
Tiêu Chí Release Tương Lai
- Module quản lý giá với quy tắc mùa
- Hỗ trợ webhook cho sự kiện OTA thời gian thực
- Ứng dụng di động cho thông báo di động
- Dashboard phân tích nâng cao
14. Tài Liệu Liên Quan
- system-architecture.md - Sơ đồ kiến trúc, phụ thuộc module, luồng xác thực
- code-standards.md - Mẫu coding, quy ước đặt tên, hướng dẫn bảo mật
- codebase-summary.md - Cấu trúc dự án, thống kê file, tech stack
- API_SPEC.md - Tham khảo REST endpoint
- DB_DESIGN.md - Schema database, ER diagram, index
- UI_SPEC.md - Design system, thư viện component, mockup screen
- development-roadmap.md - Trạng thái tính năng, mốc thời gian, theo dõi tiến độ
Cập Nhật: 2026-02-20 | Duy Trì Bởi: Đội Phát Triển