Tài liệu kiến trúc nội bộ · Bản nháp để rà soát

Sơ đồ Quy trình & Use Case toàn diện của TravelSys

Tổng quan và chi tiết hoá toàn bộ luồng vận hành của hệ sinh thái — cập nhật trọng tâm mới: nền tảng quản lý Host với nhật ký tương tác realtime Host↔Khách (chat, giọng nói, hình ảnh, AI) đóng vai trò bằng chứng có giá trị pháp lý/vận hành.

★ Trọng tâm mới: Conversation & Evidence Log Realtime Chat Voice · Image · AI Nhật ký bằng chứng tranh chấp Host Portal
1Tổng quan hệ sinh thái

Kiến trúc tổng thể — cập nhật với lớp Nhật ký Tương tác

So với bản kiến trúc gốc, hệ thống bổ sung một lớp trung tâm mới: Nhật ký tương tác & bằng chứng (Conversation Layer) — nằm giữa các ứng dụng Client/Host và hệ thống Ký quỹ & Tranh chấp. Đây là 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, thay vì rải rác trong tin nhắn tự do.

LỚP AI AGENT Trợ lý Client · Host Copilot · Xử lý voice/image trong chat · Gợi ý gắn nhãn Action CLIENT APP / WEB Tìm kiếm, gửi yêu cầu đặt chỗ, chat với Host Next.js Expo BOOKING REQUEST & MATCHING ENGINE Soft-hold tồn kho · Xác nhận real-time · Xếp hạng công bằng FastAPI HOST PORTAL (PMS/CMS) Quản lý phòng/giá/lịch · Xác nhận yêu cầu · Ký quỹ Web Mobile NEW ★ NHẬT KÝ TƯƠNG TÁC & BẰNG CHỨNG (CONVERSATION LAYER) Chat realtime riêng tư Host ↔ Khách — gắn theo từng booking — lưu vĩnh viễn làm bằng chứng vận hành/tranh chấp Text Voice Image AI-tag Action Timeline SSE realtime (đã code) KÝ QUỸ & GIẢI QUYẾT TRANH CHẤP Deposit Ledger nội bộ · Xét duyệt tranh chấp · Dùng nhật ký chat làm bằng chứng ĐỐI TÁC NGÂN HÀNG / TGTT Bên thứ ba đã cấp phép — giữ tiền ký quỹ thật (nền tảng không tự custody) bằng chứng giữ tiền thật ADMIN / VẬN HÀNH / DATA PLATFORM Kiểm duyệt · Xét duyệt tranh chấp · BigQuery · Giám sát chi phí & chất lượng RESELLER / API LAYER Đại lý nhúng widget
Thay đổi so với kiến trúc gốc (tài liệu tổng quan v1.0) Mục 4.7 (Booking Engine) và mục 4.8 (Trust & Verification) trước đây xử lý tin nhắn/bằng chứng một cách ngầm định. Bản cập nhật này tách thành module riêng, tường minh, để có thể thiết kế data model + API + AI pipeline độc lập — không làm phình to Booking Engine.
2Vai trò & Use Case

4 vai trò chính trong hệ sinh thái

Use case của End Client và Host đều được mở rộng thêm nhóm hành vi liên quan tới Nhật ký tương tác (đánh dấu ★ MỚI). Đây là những use case nên ưu tiên thiết kế UI/UX kỹ nhất vì được dùng hàng ngày.

🧳

End Client — Khách du lịch

Tìm, đặt và theo dõi dịch vụ; giờ có thêm kênh trao đổi trực tiếp & minh bạch với Host.

  • Tìm kiếm & lọc dịch vụ theo địa điểm/ngày/giá/loại hình
  • Xem chi tiết listing, đọc đánh giá 2 chiều
  • Gửi yêu cầu đặt chỗ (booking request)
  • ★ Chat realtime riêng tư với Host — hỏi đáp trước/sau khi đặt
  • ★ Gửi ảnh (chứng từ chuyển khoản, giấy tờ) / ghi âm voice trong chat
  • Nhận thông báo real-time khi Host xác nhận / từ chối
  • ★ Xem lại timeline bằng chứng: đã đặt trước, đã thanh toán, đã hoàn tiền
  • Đánh giá Host sau chuyến đi
  • ★ Báo cáo vấn đề / mở tranh chấp — đính kèm trực tiếp đoạn chat làm bằng chứng
🏠

Host — Chủ cơ sở / dịch vụ

Người dùng nền tảng hàng ngày, nhiều nhất — Inbox hội thoại là màn hình trung tâm, không phải danh sách listing.

  • Đăng ký, xác minh danh tính (giấy phép KD / CCCD)
  • Tạo/quản lý listing, giá theo mùa, tồn kho
  • ★ Inbox hội thoại — trả lời tất cả yêu cầu/khách đang trò chuyện tại 1 nơi
  • Xác nhận / từ chối yêu cầu đặt chỗ trong luồng chat
  • ★ Gắn nhãn Action: "Đã nhận thanh toán" kèm ảnh chứng từ
  • ★ Gắn nhãn Action: "Đã hoàn tiền" kèm số tiền, lý do
  • ★ Xem lại toàn bộ timeline tương tác với 1 khách cụ thể
  • Quản lý ký quỹ — nạp quỹ, xem lịch sử trích/nạp
  • Phản hồi khi bị mở tranh chấp (dùng chính nhật ký chat để giải trình)
🛡️

Admin / Vận hành

Đội ngũ nội bộ nền tảng — vai trò trọng tài, dùng nhật ký chat làm nguồn sự thật khi có tranh chấp.

  • Kiểm duyệt hồ sơ Host mới, xác minh giấy tờ
  • Giám sát chất lượng: GMV, tỷ lệ huỷ, NPS
  • ★ Xét duyệt tranh chấp — truy xuất nguyên văn nhật ký chat + action đã gắn nhãn
  • Ra quyết định, gửi lệnh trích quỹ ký quỹ khi Host sai
  • ★ Giám sát AI: rà soát các Action do AI gợi ý nhưng bị Host bỏ qua/từ chối nhiều lần
  • Phát hiện gian lận / lạm dụng cơ chế tranh chấp từ 2 phía
🤖

AI Agent (hệ thống)

Không phải actor có giao diện riêng — chạy nền, hỗ trợ 3 vai trò trên ngay trong luồng chat.

  • Agent Client: tư vấn, tìm kiếm ngữ nghĩa (semantic search)
  • Agent Host: tự sinh mô tả chuẩn SEO, gợi ý giá theo mùa
  • ★ Speech-to-Text: chuyển voice message thành text có thể tìm kiếm
  • ★ Vision/OCR: đọc ảnh chứng từ chuyển khoản → gợi ý số tiền, thời gian, mã GD
  • ★ Gợi ý gắn nhãn Action từ nội dung tin nhắn — Host luôn phải xác nhận trước khi ghi log chính thức (tránh AI tự ý xác nhận sai)
  • Phát hiện bất thường trong hội thoại (ngôn từ đe doạ, dấu hiệu lừa đảo) → cảnh báo đội CS
3Quy trình đặt chỗ chi tiết

Từ tìm kiếm đến đánh giá — luồng đầy đủ (12 bước)

Sequence diagram dưới đây thêm hẳn 1 "lane" riêng cho Conversation Log để thấy rõ: không phải mọi tương tác đều chỉ nằm giữa Client↔Host — các mốc quan trọng (xác nhận, thanh toán, hoàn tiền) đều được ghi lại có cấu trúc vào hệ thống, không chỉ là chat tự do.

CLIENT APP Khách du lịch BOOKING ENGINE FastAPI Backend CONVERSATION LOG Nhật ký & bằng chứng HOST PORTAL Chủ cơ sở 1 Tìm kiếm & gửi yêu cầu đặt chỗ 2 Soft-hold tồn kho (giữ chỗ tạm) 3 Mở Conversation gắn theo booking_id 4 Thông báo yêu cầu mới + mở chat 5 Trao đổi chi tiết qua chat hai chiều, lưu lại trong Conversation Log 6 Xác nhận đặt chỗ 7 Lộ thông tin liên hệ + xác nhận 8 Thanh toán trực tiếp ngoài phạm vi nền tảng — Host↔Client tự thu xếp 9 Gắn nhãn "Đã nhận thanh toán" + ảnh ghi vào Action Audit Log 10 Gắn nhãn Check-in / Check-out 11 Đánh giá 2 chiều sau chuyến đi 12 (Nếu có vấn đề) Mở tranh chấp đính kèm nhật ký chat làm bằng chứng
Bước 5 — Trao đổi qua chat Không bắt buộc, nhưng khi có diễn ra thì toàn bộ nội dung được lưu vào Conversation Log — kể cả khi booking chưa được xác nhận.
Bước 9-10 — Gắn nhãn Action Đây là điểm khác biệt cốt lõi so với "chat thường": mỗi Action có schema riêng (loại, số tiền, ảnh đính kèm, thời điểm) — không phải chỉ là text tự do.
Bước 12 — Nhánh tranh chấp Admin xét duyệt sẽ đọc trực tiếp Conversation Log của booking đó — xem chi tiết ở Mục 05.
4★ Trọng tâm mới

Nhật ký Tương tác & Bằng chứng (Host ↔ Client)

Mục tiêu cốt lõi được nêu ra: TravelSys không chỉ là nơi đặt chỗ, mà là nền tảng quản lý toàn diện cho Host — trong đó, hội thoại với khách không phải "tính năng phụ", mà là nhật ký vận hành có giá trị bằng chứng: ai đã xác nhận gì, khi nào, kèm bằng chứng gì.

4.1 — Kiến trúc realtime

Tách 2 luồng dữ liệu: tin nhắn "sống" (realtime, cần độ trễ thấp) đi qua Firestore (client SDK lắng nghe trực tiếp — Cloud Run không giữ WebSocket lâu dài nên không phù hợp); còn Action đã được Host xác nhận thì ghi xuống Postgres làm nguồn sự thật có cấu trúc, cùng pattern append-only đã dùng cho Deposit Ledger (mục 4.9 tài liệu gốc).

CLIENT APP & HOST PORTAL Firestore SDK — lắng nghe realtime, không qua backend cho tin nhắn thường AI PROCESSING WORKER Cloud Run / Cloud Functions — Speech-to-Text, Vision/Gemini multimodal FIRESTORE — messages/{conversationId} Lưu tin nhắn realtime: text/voice-ref/image-ref, trạng thái AI xử lý CLOUD STORAGE File voice & ảnh gốc PUB/SUB Trigger khi có message mới kèm file đính kèm đọc/ghi realtime upload file trigger xử lý AI đọc file & ghi gợi ý FASTAPI BACKEND REST fallback · validate quyền truy cập · xác nhận Action từ Host CLOUD SQL (POSTGRES) Bảng action_events — append-only, giống pattern Deposit Ledger (mục 4.9) đối soát / fallback ghi Action (bất biến)

4.2 — Mô hình dữ liệu

3 entity mới (Conversation, Message, ActionEvent) gắn vào BookingRequest đã có sẵn — không phải viết lại module Booking Engine.

BookingRequest (đã có) id uuid listing_id uuid client_id uuid host_id uuid status enum Conversation ★ MỚI id uuid booking_id uuid client_id uuid host_id uuid last_message_at timestamp status enum Message ★ MỚI id uuid conversation_id uuid sender_id uuid type text|voice|image|system content_text text media_url text? ai_suggestion jsonb? created_at timestamp ActionEvent ★ MỚI (append-only) id uuid conversation_id uuid message_id uuid? booking_id uuid type enum (§4.3) amount numeric? evidence_urls jsonb confirmed_by uuid created_at timestamp 1—1 1—N 0—1 N—1 (booking_id)

4.3 — Danh mục Action (nhãn gắn trong chat)

Đây là bảng cần Founder rà soát kỹ nhất — danh sách Action quyết định UI nút bấm trong chat, và quyết định Admin sẽ thấy gì khi xét tranh chấp. Có thể thêm/bớt/đổi tên.

Action codeNhãn hiển thịAi gắn đượcBằng chứng đính kèmGhi chú
booking_requested Đã gửi yêu cầu Hệ thống (tự động) Snapshot booking Tạo tự động khi client gửi request — không cần Host thao tác
booking_confirmed Đã xác nhận đặt phòng Host — Mở khoá thông tin liên hệ 2 chiều
booking_rejected Đã từ chối yêu cầu Host Lý do (text, tuỳ chọn) Nhả soft-hold tồn kho ngay lập tức
prepayment_received Đã nhận tiền đặt trước Host Ảnh chuyển khoản (khuyến khích) AI gợi ý số tiền/thời gian từ ảnh — Host xác nhận
balance_received Đã nhận đủ số tiền còn lại Host Ảnh chuyển khoản (khuyến khích) Có thể lặp lại nếu thanh toán nhiều lần
refund_issued Đã hoàn tiền Host Ảnh chuyển khoản + lý do (bắt buộc) Không thể sửa/xoá sau khi lưu (append-only)
check_in_confirmed Đã nhận phòng Host hoặc Client Ảnh (tuỳ chọn) Có thể do 1 trong 2 bên xác nhận trước
check_out_confirmed Đã trả phòng Host hoặc Client — Điều kiện để mở tính năng đánh giá 2 chiều
issue_reported Báo cáo sự cố Host hoặc Client Ảnh/mô tả Mức nhẹ — chưa kích hoạt quy trình tranh chấp chính thức
dispute_opened Mở tranh chấp Client hoặc Host Toàn bộ Conversation Log Mở giai đoạn tự thoả thuận (mục 4.9, v2.0) — KHÔNG khoá log ngay; chỉ khoá khi escalate lên bước trung gian
dispute_resolved Tranh chấp đã xử lý Admin Quyết định + số tiền bồi thường (nếu có) Có mức trần bồi thường, không vô hạn (mục 4.9)

4.4 — Kịch bản chi tiết

Kịch bản A — Xác nhận đã nhận thanh toán (có AI hỗ trợ đọc ảnh) CLIENT Khách du lịch HOST Chủ cơ sở AI XỬ LÝ Vision / Speech-to-Text CONVERSATION & ACTION LOG Nguồn sự thật 1 Gửi ảnh chụp màn hình chuyển khoản 2 Ảnh tự động chuyển cho AI xử lý 3 Trích xuất số tiền/giờ/mã GD → lưu nháp chưa phải Action chính thức 4 Gợi ý: "Khách chuyển 1.950.000đ lúc 14:32" 5 Host xác nhận (hoặc sửa số tiền) gắn nhãn chính thức: payment_received 6 Thông báo: Host đã xác nhận nhận thanh toán
Vì sao tách bước "gợi ý" và bước "xác nhận"? Nếu để AI tự ghi Action ngay khi đọc ảnh, một ảnh mờ/sai góc có thể tạo ra bằng chứng thanh toán giả trong hồ sơ — rủi ro cho chính Host. Bắt buộc con người xác nhận giữ tính pháp lý của nhật ký.
Kịch bản B — Host xác nhận hoàn tiền cho khách CLIENT Khách du lịch HOST Chủ cơ sở AI XỬ LÝ Vision / Speech-to-Text CONVERSATION & ACTION LOG Nguồn sự thật 1 Thông báo lý do cần hoàn tiền (qua chat) 2 Gắn nhãn "Đã hoàn tiền" — số tiền + lý do bắt buộc nhập lý do trước khi lưu 3 Gửi ảnh chứng từ đã chuyển hoàn (khuyến khích) 4 Ghi bản ghi append-only — không thể sửa/xoá 5 Hiển thị xác nhận trong "Yêu cầu của tôi"
Vì sao bắt buộc nhập lý do khi hoàn tiền? Đây chính là dữ liệu Admin cần khi Host bị khách khiếu nại "hoàn tiền thiếu" — nếu không có lý do kèm theo, bản ghi chỉ có số tiền sẽ không đủ để đối chiếu.

4.5 — Xử lý đa phương tiện (Text · Voice · Image)

Quan trọng cho Host lớn tuổi/không rành công nghệ (nguyên tắc cốt lõi #1 của tài liệu gốc: "không yêu cầu kiến thức kỹ thuật") — Host có thể nói thay vì gõ, chụp ảnh thay vì nhập liệu.

💬 TEXT Tin nhắn gõ tay Lưu trực tiếp 🎙️ VOICE Ghi âm trong app Speech-to-Text 🖼️ IMAGE Ảnh chụp/chọn từ thư viện Vision · OCR LỚP XỬ LÝ AI Vertex AI (Gemini multimodal) — chạy async qua Pub/Sub, không chặn gửi tin nhắn kết quả MESSAGE OBJECT (đã làm giàu dữ liệu bởi AI) content_text — luôn có (kể cả voice đã transcribe) media_url — file gốc để nghe/xem lại ai_suggestion.type — 'payment' | 'id_card' | 'room_photo' | ... ai_suggestion.extracted — { amount, datetime, ref } ai_suggestion.confidence — 0..1 requires_host_confirmation — true Nguyên tắc: AI chỉ GỢI Ý (ai_suggestion) — không tự ghi ActionEvent chính thức. Host luôn là người bấm xác nhận cuối cùng.
5Tranh chấp dùng bằng chứng

Từ nhật ký chat rời rạc → gói bằng chứng có cấu trúc

Tài liệu kiến trúc gốc (mục 4.9) mô tả bằng chứng tranh chấp là "ảnh, tin nhắn, booking log" — nhưng không nói rõ định dạng. Với Conversation Layer, Admin không phải đọc lại hàng chục tin nhắn rời rạc — mà xem 1 timeline đã được cấu trúc hoá theo từng booking.

Quy trình xét duyệt tranh chấp — dùng Conversation Log làm nguồn bằng chứng chính CLIENT / HOST Bên báo cáo CONVERSATION LOG Bị khoá khi mở tranh chấp ADMIN / VẬN HÀNH Trọng tài ĐỐI TÁC GIỮ TIỀN Ký quỹ 1 Mở tranh chấp (dispute_opened) + mô tả 2 Khoá Conversation — không cho sửa/xoá thêm 3 Đưa vào hàng đợi xét duyệt kèm toàn bộ Conversation + ActionEvent timeline 4 Đọc lại nhật ký: text / voice transcript / ảnh 5 Ra quyết định theo chính sách công bố 6 (Nếu Host sai) Lệnh trích quỹ — có mức trần 7 Thông báo kết quả cho cả 2 bên

Minh hoạ: màn hình Admin xem xét tranh chấp

Booking #a1b2c3 — Homestay Gần Biển Mỹ Khê, Đà Nẵng
Trần Thu Khách ↔ Nguyễn Minh Host · Mở tranh chấp lúc 09:40, 24/12/2026
Đang xét duyệt
Th 12 20, 10:32
Chào host, mình muốn hỏi phòng có bãi đỗ ô tô không ạ?
10:35
Dạ có bãi đỗ riêng cho khách anh/chị nhé!
Th 12 20, 14:22
💰
payment_received — 1.950.000đ · gắn nhãn bởi Host
📎 anh_chuyen_khoan_142211.jpg (do AI trích số tiền, Host xác nhận)
Th 12 23
🎙️ Voice message (0:18) — đã chuyển văn bản: "Phòng bị ẩm, khác nhiều so với ảnh trên web..."
Th 12 24, 09:40
⚠️
dispute_opened — bởi Client
Lý do: "Phòng ẩm mốc, không giống ảnh listing" · 3 ảnh đính kèm
Toàn bộ mốc thời gian, người gắn nhãn, và file gốc đều được giữ nguyên — Admin không cần hỏi lại 2 bên "ai nói gì lúc nào".
★Quyết định kiến trúc mới — v1.2

Gọi thoại realtime Host↔Client — mục 4.11

Sau khi Nhật ký Tương tác (mục 4) đi vào code, bước tiếp theo được thống nhất: gọi thoại trực tiếp trong app cho các tình huống cần nhanh hơn gõ chữ (hỏi gấp trước giờ nhận phòng, xử lý sự cố tại chỗ). Đồng thời chốt không dùng Convex cho lớp realtime nói chung.

Đề xuấtQuyết địnhLý do
LiveKit (gọi thoại Host↔Client) ✅ Đã code & test LiveKit Agents là framework Python — khớp thẳng FastAPI, không tạo runtime thứ 2. Hạ tầng production-grade (cấp WebRTC cho ChatGPT voice mode, Salesforce Agentforce).
File storage (ảnh/voice trong chat) ✅ Google Cloud Storage Đúng định hướng tập trung hệ sinh thái Google — đã có abstraction layer local/gcs, đổi bằng 1 biến môi trường.
AI voice agent (Host Copilot nói chuyện thay Host) ⏸ Tiện ích mở rộng Giữ đúng định hướng đã thống nhất: chỉ phát triển khi có Host thực sự cần, không xây trước khi có người dùng thật. LiveKit Agents (Python) đã sẵn sàng cắm vào khi cần.

Kiến trúc — backend chỉ cấp token, không truyền tải audio

CLIENT APP / HOST PORTAL Bấm "Gọi thoại" trong khung chat FASTAPI BACKEND Cấp JWT token + nhận webhook LIVEKIT CLOUD WebRTC — audio truyền thẳng, không qua server TravelSys 1. yêu cầu / cấp JWT token 3. webhook room_finished 2. WebRTC trực tiếp (dùng token) — KHÔNG qua backend CONVERSATION LOG (mục 4.10) Ghi Message loại 'call' kèm thời lượng vào lịch sử hội thoại 4. verify + ghi log
Vì sao backend không chuyển tiếp audio? Đúng mô hình LiveKit khuyến nghị: backend chỉ có trách nhiệm xác thực (ai được join phòng nào) và cấp token ngắn hạn — audio đi thẳng Client↔LiveKit Cloud qua WebRTC. Giữ backend nhẹ, không phải lo băng thông/độ trễ audio.

Kịch bản chi tiết — Client gọi Host

Kịch bản: Client gọi thoại cho Host qua LiveKit CLIENT Khách du lịch BACKEND FastAPI LIVEKIT CLOUD WebRTC HOST Chủ cơ sở 1 Bấm "Gọi thoại" 2 Kiểm tra là thành viên hội thoại + chưa khoá 3 Trả JWT token (chỉ join đúng phòng) 4 Kết nối WebRTC bằng token 5 Đẩy thông báo "Cuộc gọi đến" (qua app) Host cần đang mở app hoặc có push notification 6 Host bấm nhận → xin token tương tự 7 Kết nối WebRTC bằng token 8 Nói chuyện trực tiếp qua LiveKit audio không đi qua backend TravelSys 9 Kết thúc cuộc gọi 10 Webhook room_finished 11 Verify chữ ký + tính thời lượng 12 📞 Ghi Message "call" vào lịch sử chat
Đã kiểm thử thật (không đoán API) Sinh JWT token và verify webhook bằng chính SDK livekit-api — ký một webhook giả lập đúng cách LiveKit server ký thật, verify thành công trước khi viết endpoint. Test luôn cả đường lỗi: người ngoài hội thoại không lấy được token, chữ ký webhook sai bị từ chối (401), và UI hiển thị đúng thông báo khi chưa cấu hình LIVEKIT_API_KEY (503, không crash).
6Mô hình dữ liệu tổng thể

Toàn bộ entity — bản gốc + 3 entity mới

Nhìn tổng thể để thấy rõ: Conversation/Message/ActionEvent chỉ "cắm thêm" vào giữa BookingRequest và Dispute đã có sẵn — không đụng vào cụm User/Listing hay cụm Ký quỹ.

NGƯỜI DÙNG & LISTING User role rating Listing host_id AvailabilitySlot listing_id BOOKING & NHẬT KÝ TƯƠNG TÁC ★ BookingRequest status NEW Conversation booking_id NEW Message conversation_id NEW ActionEvent conversation_id booking_id Review booking_id booking_id KÝ QUỸ & TRANH CHẤP DepositAccount host_id DepositLedgerEntry deposit_account_id Dispute booking_id dùng làm bằng chứng ApiClient (Reseller) Chip trong mỗi khối chỉ liệt kê field khoá ngoại quan trọng — xem field đầy đủ của Conversation/Message/ActionEvent ở mục 4.2.
7Tác động tới lộ trình

Nhật ký Tương tác chuyển từ "sau này" thành "cốt lõi"

Vì Founder xác nhận đây là mục tiêu chính của hệ sinh thái (không phải tính năng phụ), đề xuất đẩy phần lõi (chat text + gắn nhãn Action thủ công) lên ngay Phase 1 — còn phần AI xử lý voice/image vẫn ở Phase 3 như cũ, vì AI là "tăng tốc" chứ không phải điều kiện để chat hoạt động.

PhaseTrước (roadmap gốc)Sau (cập nhật)
Phase 0
Nền móng		 Kiến trúc DB, thiết kế UX, chọn 1 vertical + Thiết kế schema Conversation/Message/ActionEvent song song (mục 4.2)
Phase 1
MVP		 Client tìm & gửi yêu cầu, Host xác nhận/từ chối, trao đổi liên hệ sau xác nhận ★ Bổ sung Chat text realtime (Firestore) + gắn nhãn 6 Action cơ bản (confirmed/rejected/payment_received/refund_issued/check_in/check_out) — chưa cần AI
Phase 2
Ký Quỹ & Tranh chấp		 Đối tác ký quỹ, Deposit Ledger, quy trình xét duyệt tranh chấp Không đổi nghiệp vụ — nhưng Admin console xét duyệt giờ đọc trực tiếp Conversation Log (mục 05) thay vì hỏi thủ công 2 bên
Phase 3
AI Agent v1		 Chatbot tư vấn client, Host copilot sinh mô tả/SEO ★ Bổ sung Speech-to-Text cho voice message + Vision/OCR đọc ảnh chứng từ + gợi ý gắn nhãn Action (mục 4.5)
Phase 4-6 SEO/Scale, mở rộng dịch vụ/khu vực, vận hành bền vững Không đổi — Conversation Layer thiết kế đa ngôn ngữ ngay từ Phase 1 nên không chặn Phase 5
Rủi ro cần lường trước khi đẩy sớm Đưa chat vào Phase 1 nghĩa là MVP phải xong cả Firestore realtime + upload ảnh/voice lên Cloud Storage — tăng phạm vi kỹ thuật của bản MVP đầu tiên. Có thể cân nhắc bản rút gọn: Phase 1 chỉ có chat text + gắn nhãn Action, để Voice/Image lùi hẳn sang Phase 3 cùng AI — giảm rủi ro trễ tiến độ MVP.
8Câu hỏi cần chốt

8 quyết định Founder nên rà soát trước khi code

Tài liệu này là bản nháp để bạn đánh giá & thay đổi — dưới đây là những điểm có nhiều hơn 1 cách làm hợp lý, nên cố tình để mở thay vì tự quyết định thay bạn.

1

Firestore hay tự build WebSocket trên Cloud Run?

Đề xuất Firestore vì Cloud Run không giữ kết nối lâu dài tốt. Nhưng nếu sau này cần logic phức tạp hơn (VD: mã hoá đầu-cuối), có thể cần đổi hướng.

2

Danh mục 11 Action (mục 4.3) đã đủ chưa?

Có cần thêm cancelled_by_client, no_show, extra_charge_requested (phụ phí phát sinh) không?

3

Có cho phép sửa/thu hồi tin nhắn thường không?

✅ Đã quyết định & code (v2.1): Action vẫn append-only tuyệt đối. Tin nhắn chat thường (chưa gắn Action) thì CÓ cho sửa/thu hồi — nhưng chỉ đúng tin CUỐI CÙNG, và chỉ khi người nhận chưa đọc tới đó. Nội dung gốc không mất khỏi hệ thống (soft-delete), Admin vẫn thấy bản gốc khi xét tranh chấp — xem mục 4.10 tài liệu tổng quan.

4

Giới hạn & chi phí lưu trữ voice/image?

Giới hạn thời lượng voice (VD: 60s)? Lưu file gốc bao lâu — vĩnh viễn (chi phí Cloud Storage tăng dần) hay có chính sách archive sau N tháng?

5

Khi nào "issue_reported" tự leo thang thành "dispute_opened"?

Có ngưỡng thời gian tự động không (VD: Host không phản hồi issue trong 48h → gợi ý client mở tranh chấp), hay luôn cần client bấm thủ công?

6

Giới hạn lượt AI xử lý miễn phí / Host / tháng?

Speech-to-Text và Vision API tính phí theo lượt gọi — cần khung miễn phí bao nhiêu lượt trước khi tính vào chi phí vận hành (liên quan mục 7 ước tính chi phí tài liệu gốc)?

7

Đa ngôn ngữ trong Conversation Log?

Khách quốc tế chat tiếng Anh, Host trả lời tiếng Việt — có cần dịch tự động 2 chiều ngay trong khung chat không, hay để giai đoạn sau (đi cùng đa ngôn ngữ Phase 5)?

8

Có cần "read receipt" (đã xem) để tính response_rate không?

Một phần đã quyết định (v2.1): Read receipt đơn giản (2 cột thời điểm đọc cuối, không phải per-message) đã có — nhưng hiện chỉ dùng để gate việc sửa/thu hồi tin nhắn cuối, chưa dùng để tính lại response_rate. Founder vẫn cần chốt: có nên đổi công thức response_rate sang dựa trên thời điểm đọc thay vì thời điểm trả lời không, giờ đã có dữ liệu để làm việc đó nếu muốn.

3 quyết định mới phát sinh (v1.9–v2.2, tháng 09/2026)

3 tham số dưới đây đang dùng giá trị mặc định hợp lý trong code — Founder chưa xác nhận, đổi được ở đúng 1 chỗ trong code khi đã quyết định.

9

Tỉ lệ đảm bảo ký quỹ (coverage ratio) nên là bao nhiêu?

Rule hiện tại (v1.9): số dư ký quỹ phải ≥ 1.0× tổng nghĩa vụ đang treo (giá trị booking đang hoạt động × trần bồi thường 50%) — mới cho phép xác nhận booking mới. 1.0 là mặc định thận trọng, áp dụng như nhau cho MỌI host. Có nên nới cho host uy tín cao (VD 0.7×) và siết với host mới (VD 1.5×) không? DEFAULT_COVERAGE_RATIO trong deposit_service.py.

10

Cửa sổ tự thoả thuận trước khi tự động escalate là bao nhiêu ngày?

Mặc định 3 ngày (v2.0): nếu 1 tranh chấp nằm ở bước "tự thoả thuận" quá lâu mà không ai xử lý, hệ thống tự chuyển sang bước trung gian. 3 ngày có đủ cho 2 bên thật sự trao đổi chưa, hay nên dài/ngắn hơn tuỳ loại dịch vụ (homestay dài ngày vs vé/tour ngắn hạn)? DEFAULT_SELF_NEGOTIATION_DAYS trong dispute_service.py.

11

Cửa sổ "đánh giá gần đây" nên là bao nhiêu ngày?

Mặc định 180 ngày (v2.2): hồ sơ Host/Client hiển thị SONG SONG điểm toàn thời gian và điểm trong 180 ngày gần nhất, để 1 sai lầm cũ không đè mãi lên hồ sơ. 180 ngày (~6 tháng) có phải khoảng thời gian phù hợp với nhịp độ dùng thực tế của Host/Client không? REVIEW_RECENT_WINDOW_DAYS trong review_service.py.