Hệ Sinh Thái Dịch Vụ Du Lịch
(Host ↔ End Client)
Nền tảng hai chiều kết nối Host và khách du lịch tại Việt Nam & Đông Nam Á — thanh toán trực tiếp, không hoa hồng giao dịch, được hỗ trợ bởi AI Agent ở cả hai đầu. v1.1 bổ sung Nhật ký Tương tác & Bằng chứng làm mục tiêu cốt lõi; v1.2 thêm gọi thoại CallSystem, chốt không dùng Convex.
Nền tảng hai chiều (two-sided marketplace)
Kết nối Bên cung (Host): khách sạn, homestay, nhà nghỉ, dịch vụ tour/vé tham quan, vận chuyển, reseller/đại lý — với Bên cầu (End Client): khách du lịch tìm và đặt phòng, mua vé, sử dụng dịch vụ.
1.1 Nguyên tắc cốt lõi
- Nền tảng toàn diện, không chỉ là chỗ đăng tin: công cụ quản lý vận hành + tiếp thị hiện đại cho host — từ quản lý phòng/giá/lịch đến SEO, nội dung — trong một hệ sinh thái duy nhất.
- Matching công bằng & minh bạch: xếp hạng dựa trên tín hiệu chất lượng thực, không phải "ai trả nhiều hơn thì lên top". Vị trí tài trợ (mục 8) phải gắn nhãn rõ ràng, tách khỏi kết quả tự nhiên.
- Giảm giá thành thực chất: không thu hoa hồng trên từng giao dịch → host không cộng phí OTA vào giá bán → khách thấy giá thực tế thấp hơn. Đây là giá trị cốt lõi chọn có chủ đích, không phải hệ quả phụ.
- Kết nối & xác nhận theo thời gian thực: yêu cầu đặt chỗ, phản hồi host, trạng thái đơn — cập nhật real-time. v1.1 Cơ chế thực thi là Nhật ký Tương tác & Bằng chứng (mục 4.10) — chat riêng tư Host↔Client gắn theo booking, vừa là kênh liên lạc realtime vừa là nhật ký vận hành có giá trị bằng chứng.
- Thanh toán trực tiếp = dòng tiền minh bạch: tiền đi thẳng từ khách đến host thật, không pha loãng qua trung gian — kèm chính sách giá/huỷ/hoàn tiền công khai.
Giai đoạn đầu: miễn phí hoàn toàn cho host và end-client để tối đa hoá network effect. Giai đoạn sau: thu phí vận hành qua tài trợ/thuê bao (xem mục 8).
6 vai trò trong hệ sinh thái
| Vai trò | Mô tả | Nhu cầu chính |
|---|---|---|
| End Client | Khách du lịch cá nhân/nhóm | Tìm kiếm nhanh, đặt & thanh toán dễ, tư vấn cá nhân hoá (AI) |
| Host — chủ cơ sở | Khách sạn, homestay, nhà nghỉ | Quản lý phòng/giá/lịch, không cần biết kỹ thuật, tăng khách qua SEO |
| Host — dịch vụ | Tour, vé tham quan, vận chuyển | Quản lý lịch trình, tồn kho vé, combo dịch vụ |
| Reseller/Đại lý | Bán lại dịch vụ qua kênh riêng | Cần API/embed widget, hoa hồng minh bạch |
| Admin vận hành | Đội vận hành nền tảng | Kiểm duyệt, hỗ trợ tranh chấp, giám sát chất lượng |
| AI Agent (hệ thống) | Trợ lý ảo cho cả 2 phía | Tự động hoá tương tác, gợi ý, tối ưu nội dung |
Kiến trúc tổng thể — đã có lớp Nhật ký Tương tác
Lớp ★ Nhật ký Tương tác & Bằng chứng nằm giữa các ứng dụng Client/Host và hệ thống Ký quỹ & Tranh chấp — nơi mọi hội thoại, xác nhận, bằng chứng thanh toán được ghi lại có cấu trúc.
9 module nền tảng + 1 module trọng tâm mới
4.1 Client-side (End User)
Web SEO-first + PWA/app. Tìm kiếm thông minh, AI Concierge tư vấn tự nhiên, gửi booking request ngay trong hội thoại.
4.2 Host Portal (PMS/CMS)
Quản lý phòng/dịch vụ, giá theo mùa, tồn kho. AI Copilot tự sinh mô tả chuẩn SEO, gợi ý giá, tự động trả lời câu hỏi thường gặp.
4.3 AI Agent Layer
Đã xây (v2.3–v2.5): AI cho Host theo mô hình BYOK — Host tự kết nối key OpenAI/Gemini/Claude, bot tư vấn trước khi đặt chỗ (chữ + giọng nói) trong khung chat của chính Listing đó, Host tự trả phí. Ý tưởng tương lai (Phase 3, chưa xây): Agent Client dạng Concierge — RAG/semantic search xuyên suốt mọi Listing, phục vụ khách còn ẩn danh, do nền tảng vận hành/trả phí — khác hẳn nguyên tắc BYOK ở trên.
4.4 Marketing & Tăng trưởng
Landing page tự sinh có kiểm soát, structured data schema.org, sitemap tự động, bộ công cụ tiếp thị cho host. SSR/SSG bắt buộc.
4.5 Admin & Vận hành
Kiểm duyệt host mới, xử lý tranh chấp, dashboard GMV/tỷ lệ huỷ/NPS.
4.6 Reseller/API Layer
API cho đại lý nhúng widget đặt phòng, cơ chế hoa hồng & tracking nguồn đơn minh bạch.
4.7 Booking Request & Matching Engine
Soft-hold tồn kho (khoá hàng chống race condition — đã tìm & vá 1 lỗi overbooking thật, chứng minh bằng test 2 luồng chạy đồng thời v2.7), xác nhận real-time, tỉ lệ đặt trước công khai, sức chứa default_quantity/max_guests khai báo trên từng dịch vụ v2.8. Không xử lý thanh toán giao dịch chính.
4.8 Trust & Verification Layer
Xác minh Host, đánh giá 2 chiều đa tiêu chí (8 tiêu chí Host / 5 tiêu chí Client) v2.2, điểm tổng tự tính + hiển thị song song "gần đây" (180 ngày) và "toàn thời gian" cho công bằng, response rate công khai, báo cáo vi phạm.
4.9 Ký Quỹ & Giải Quyết Tranh Chấp
Sức chứa ký quỹ v1.9 ràng buộc thật dung tích nhận booking với số dư, host rút được tiền dư an toàn. Tranh chấp 2 giai đoạn v2.0: tự thoả thuận trước (hội thoại không khoá) → escalate mới khoá & vào bước trung gian (người hoặc AI gợi ý) → lịch hẹn thoại 3 bên nếu cần. Mức trần bồi thường rõ ràng.
4.10 Nhật ký Tương tác & Bằng chứngMỚI · ĐÃ CODE
Không phải "chat phụ trợ" — mà là trung tâm vận hành hàng ngày của Host: trả lời khách, xác nhận đặt phòng, xác nhận thanh toán, xác nhận hoàn tiền — tất cả trong 1 luồng hội thoại, mỗi mốc quan trọng được ghi lại có cấu trúc làm bằng chứng, nuôi trực tiếp quy trình mục 4.9.
app/models/conversation.py, conversation_service.py,
api/v1/endpoints/conversations.py — không chỉ là đề xuất kiến trúc. Đã test end-to-end
(30+ test case) và test realtime SSE thật qua HTTP streaming.
Kiến trúc dữ liệu
- Conversation: 1 hội thoại riêng tư Host↔Client, tự động tạo khi có booking request, gắn
booking_id1–1. - Message:
text / voice / image / system. Voice tự chuyển text (Speech-to-Text); ảnh được AI gợi ý phân tích (VD: nhận diện ảnh chuyển khoản). AI chỉ gợi ý — không tự ghi bằng chứng chính thức. - ActionEvent (append-only): 11 loại bằng chứng có cấu trúc — xem bảng danh mục bên dưới.
- Realtime: Server-Sent Events (SSE) trên FastAPI — đã kiểm thử, tin nhắn mới đẩy tới client trong ~1.5s, không cần Firestore cho quy mô MVP.
- Khoá khi tranh chấp (cập nhật v2.0): KHÔNG khoá ngay khi
dispute_openednữa — 2 bên vẫn tự do trao đổi trong giai đoạn tự thoả thuận; chỉ khoá khi tranh chấp được escalate lên bước trung gian (mục 4.9). - Sửa/thu hồi tin nhắn cuối chưa đọc v2.1: soft-delete — nội dung thật không bao giờ mất khỏi hệ thống (vẫn hiện cho Admin khi điều tra tranh chấp), chỉ ẩn khỏi màn hình chat 2 bên.
ActionEventvẫn bất biến tuyệt đối, không áp dụng cơ chế này.
Danh mục Action (rút gọn — bảng đầy đủ ở tài liệu use-case)
| Action | Ai gắn được | Ghi chú |
|---|---|---|
booking_confirmed/rejected | Host | Tự động log khi Host xác nhận/từ chối qua API booking |
prepayment_received / balance_received | Host | Kèm ảnh chứng từ, AI gợi ý số tiền |
refund_issued | Host | Bắt buộc nhập lý do — validate cả frontend lẫn backend |
check_in/check_out_confirmed | Host hoặc Client | Điều kiện mở đánh giá 2 chiều |
dispute_opened | Host hoặc Client | Mở giai đoạn tự thoả thuận — không khoá hội thoại (xem mục 4.9) |
4.11 Gọi thoại realtime Host↔ClientMỚI · ĐÃ CODE
Sau khi có Nhật ký Tương tác (4.10), bước tiếp theo là gọi thoại — nhiều tình huống (hỏi gấp trước giờ nhận phòng, xử lý sự cố tại chỗ) cần nhanh hơn gõ chữ.
4.12 AI cho Host — mô hình BYOKMỚI · ĐÃ CODE
"Bring Your Own Key" — Host tự kết nối tài khoản AI của MÌNH và tự trả phí sử dụng. Nền tảng không bao giờ trả tiền AI thay Host, và AI không bao giờ tự ý hành động thay con người.
| Thành phần | Trạng thái | Ghi chú |
|---|---|---|
| Kết nối & mã hoá key (v2.3) | ✅ Đã code & test | Fernet, khoá mã hoá tách biệt hoàn toàn khoá ký JWT — lộ 1 bên không kéo sập bên kia |
| Phạm vi dùng key BYOK | ✅ Đã chốt, có chủ đích | CHỈ gợi ý trong Hộp thư + dịch listing — AI hoà giải tranh chấp & AI Concierge tương lai KHÔNG BAO GIỜ dùng key Host (xung đột lợi ích) |
| Bot tư vấn dạng chữ (v2.4) | ✅ Đã code & test | Trả lời trong khung chat của 1 Listing cụ thể, dựa system prompt Host tự cấu hình |
| Bot tư vấn giọng nói (v2.5) | ✅ Đã code & test logic | Hạ tầng CallSystem dùng chung (nền tảng trả phí), "bộ não" trả lời dùng key BYOK — Claude chưa hỗ trợ giọng nói nên giới hạn ở OpenAI/Gemini |
| Fire-test với key thật | ⏳ Chưa làm được | Sandbox phát triển không có quyền mạng ra ngoài tới OpenAI/Gemini/Claude — cần thử với 1 key thật trước khi mở cho Host thật dùng |
- Ranh giới an toàn cứng: module AI Bot KHÔNG import bất kỳ hàm tạo booking/trích ký quỹ nào — không thể tự ý đặt chỗ hay động vào tiền dù prompt bị thao túng thế nào.
- Khác hẳn "Agent Client" ở mục 4.3 (Concierge) — đó vẫn là ý tưởng tương lai do nền tảng vận hành/trả phí, phục vụ khách còn ẩn danh.
4.13 Công cụ quản lý cho HostMỚI · ĐÃ CODE
4 tiện ích giúp Host vận hành dịch vụ hằng ngày mà không cần rời khỏi nền tảng — Web + Mobile đều có, cùng 1 API.
Lên lịch đổi giá dịch vụ v2.6
Mọi thay đổi giá đều có effective_from — áp dụng ngay hoặc đặt lịch tương lai. Đồng bộ Google Hotel Center CHỈ xảy ra đúng lúc giá có hiệu lực, không sớm hơn — xem mục 4.9 và tài liệu Google Hotel Center riêng.
Trang cá nhân tĩnh của Host v2.6
Đường dẫn riêng /h/{host}/{page}, tự viết nội dung markdown/HTML, tự sinh đường dẫn, nội dung được kiểm tra hợp lệ tự động. Render markdown đầy đủ chuẩn CommonMark+GFM trên Web.
Lịch quản lý dịch vụ v2.7
Sơ đồ occupancy trực quan theo từng dịch vụ/ngày, danh sách đặt chỗ có ghi chú riêng, tóm tắt doanh thu, thao tác nhanh (xác nhận/từ chối/trả phòng) ngay tại chỗ. Đi kèm 1 race condition overbooking thật được tìm và vá.
Dịch vụ phụ trợ trong lúc lưu trú v2.8
Host tự lập danh mục dịch vụ tái sử dụng (nước uống, cafe, giặt đồ...), thêm phụ thu vào hoá đơn CHỈ khi booking đã xác nhận. Tích hợp vào Lịch quản lý dịch vụ: tổng tiền = tiền dịch vụ + phụ thu.
- Cũng ở phiên này: thêm sức chứa cho từng dịch vụ (
default_quantity/max_guests) — xem mục 4.7. - Đã kiểm thử: 15 file test end-to-end thật trên Postgres, kể cả 1 test mô phỏng 2 request đặt chỗ chạy THẬT SỰ đồng thời để chứng minh race condition đã vá đúng.
4.14 SEO, Giám sát Admin, Cảnh báo chỗ trống & Nhật ký kháchMỚI · ĐÃ CODE
4 vòng lặp tính năng tiếp theo — từ audit hệ thống tới công cụ quản lý tương tác khách hàng hoàn chỉnh cho Host.
SEO thật + Google Analytics v2.9
Sitemap/robots/JSON-LD qua endpoint chuyên biệt (không giới hạn kết quả, khác endpoint tìm kiếm) — phát hiện sitemap cũ chỉ có 50 listing đầu, đã sửa. Google Analytics (GA4) không cấu hình thì không tải gì cả.
Giám sát vận hành cho Admin v2.9
Trang /admin/monitoring mới: phễu booking, GMV ước tính, danh sách Host rủi ro ký quỹ (cảnh báo SỚM trước khi bị chặn), sức khoẻ đồng bộ Google Hotel Center. Cũng audit tìm & vá 1 bug thật: Google nhận sai sức chứa mọi listing.
Cảnh báo còn/hết chỗ v3.0
Khách thấy "Còn chỗ"/"Hết chỗ" NGAY khi chọn ngày (endpoint đọc thuần, không tạo dữ liệu), thay vì chỉ biết sau khi bị từ chối lúc gửi yêu cầu.
Đặt hộ khách quen v3.0
Host tự đánh dấu 1 lượt đặt của khách liên hệ qua điện thoại/trực tiếp — đi qua ĐÚNG CÙNG khoá chống race condition và rule ký quỹ như booking thật, không có đường tắt.
Nhật ký quản lý khách v3.1
Danh bạ khách riêng của từng Host (HostGuest), tách hẳn khỏi tài khoản Client — đa số khách tiếp trực tiếp không bao giờ đăng ký tài khoản. Tìm & tái sử dụng thông tin khách quen khi đặt hộ, dedupe thông minh theo số điện thoại.
Khách "đã có tài khoản" tự động vào nhật ký v3.2
Không cần Host tự liên kết thủ công — 1 Client đã đặt chỗ thật qua nền tảng tự xuất hiện trong nhật ký hợp nhất, kèm link thẳng tới hội thoại đã có sẵn trong Hộp thư.
- Đã kiểm thử: 19 file test end-to-end thật trên Postgres tính đến cuối v3.2 — mọi tính năng ở trên đều có test thật đi kèm, không chỉ đọc code suy luận.