User Story 03: Chức năng Cung cấp Thông tin Chung (FAQs)

Mã tài liệu:	US-03	Phiên bản:	1.0
Epic:	Trải nghiệm Người dùng tại Booth	Người tạo:	Stephen
Ngày hiệu lực:	13/09/2025	Người phê duyệt:	Stephen

1. User Story

Với vai trò là một khách tham quan, Tôi muốn hỏi các câu hỏi chung về tiện ích và quy định tại địa điểm này (ví dụ: giờ mở cửa, bãi đỗ xe, quy định về thú cưng...), Để tôi có được thông tin cần thiết một cách nhanh chóng và thuận tiện, bất kể câu hỏi của tôi là phổ biến hay cụ thể.

2. Mô tả (Description)

Đây là user story bao quát các câu hỏi thường gặp (FAQs) mà một nhân viên lễ tân thường trả lời. Để mang lại trải nghiệm vừa chính xác, nhanh chóng vừa linh hoạt, thông minh, tính năng này sẽ được triển khai theo mô hình lai (hybrid).

Hệ thống sẽ ưu tiên tra cứu trong một bộ kiến thức FAQ được quản lý chặt chẽ để trả lời các câu hỏi phổ biến. Nếu không tìm thấy, hệ thống sẽ tự động chuyển sang sử dụng một AI Tạo sinh (Generative AI) mạnh mẽ để tạo ra câu trả lời dựa trên các tài liệu nguồn do Tenant cung cấp. Cách tiếp cận này đảm bảo hiệu suất và độ tin cậy cho các câu hỏi cốt lõi, đồng thời mở rộng đáng kể phạm vi kiến thức của AI.

3. Tiêu chí Chấp nhận (Acceptance Criteria - AC)

• AC1 (Luồng FAQ): Khi câu hỏi của người dùng khớp với một câu hỏi trong bộ kiến thức FAQ, hệ thống PHẢI trả về câu trả lời đã được soạn sẵn một cách nhanh chóng.
• AC2 (Luồng Generative AI): NẾU không tìm thấy câu trả lời trong bộ FAQ, hệ thống PHẢI chuyển sang dùng AI Tạo sinh để tạo ra câu trả lời. Câu trả lời này phải được tạo ra chỉ dựa trên các tài liệu nguồn được Tenant cung cấp.
• AC3 (Hiển thị nhất quán): Dù câu trả lời đến từ nguồn nào (FAQ hay AI Tạo sinh), nó đều phải được phản hồi bằng giọng nói rõ ràng và hiển thị dưới dạng văn bản lớn, dễ đọc trên màn hình, có thể đi kèm icon.
• AC4 (Xử lý lỗi cuối cùng): NẾU cả hai luồng trên đều không thể đưa ra câu trả lời, AI PHẢI phản hồi một cách lịch sự rằng nó không có thông tin.
• AC5 (Quy tắc Toàn cục): Nếu không có bất kỳ tương tác nào trong vòng 15 giây, hệ thống phải tự động quay trở về màn hình chờ mặc định.

4. Luồng Tương tác (Interaction Flow - Hybrid Path)

1. Bắt đầu: Người dùng tiếp cận Booth.
2. Ra lệnh: Người dùng hỏi: "Thú cưng có được vào khu vực ăn uống không?".
3. Xử lý: Hệ thống ghi nhận và gửi yêu cầu lên backend. Backend thực hiện: a. Bước 1: Tra cứu trong bộ kiến thức FAQ. (Giả sử không tìm thấy câu hỏi chính xác này). b. Bước 2: Chuyển sang luồng Generative AI. Hệ thống lấy các tài liệu về "Nội quy" của Tenant làm ngữ cảnh và yêu cầu AI Tạo sinh trả lời câu hỏi.
4. Phản hồi: Hệ thống trả về kết quả do AI Tạo sinh tạo ra.
   • Giọng nói: "Dạ, theo nội quy, thú cưng được phép vào trung tâm thương mại nhưng không được vào khu vực nhà hàng và quán cà phê ạ."
   • Hình ảnh: Màn hình hiển thị câu trả lời dưới dạng văn bản.
5. Kết thúc: Người dùng rời đi. Sau 15 giây, màn hình quay về trạng thái chờ.

5. Thiết kế & Giao diện Người dùng (UX/UI Design)

• Toàn bộ thiết kế phải tuân thủ nghiêm ngặt "Tiêu chuẩn Thiết kế UX/UI cho EZD AI Booth v1.0".
• Link tới Figma: [Link đến file Figma chứa thiết kế chi tiết cho luồng này]
• Các trạng thái màn hình chính: Result State (Text/Info View).

6. Phân tích Kỹ thuật & Hợp đồng API (Technical & API Contract)

• Các thành phần liên quan:
  • Frontend: Không thay đổi nhiều.
  • Backend: InteractionProcessingService giờ đây sẽ chứa logic điều phối phức tạp hơn để quyết định khi nào dùng FAQ, khi nào gọi đến Generative AI Engine (LLM Provider).
• Hợp đồng API (API Contract):
  • Endpoint: POST /v1/ezd/interactions/query
  • Request Body: (Không thay đổi)
  • Success Response (Cập nhật): Thêm một trường source để frontend và hệ thống analytics biết câu trả lời đến từ đâu.

    {
      "speech_text": "...",
      "display_type": "text_only",
      "display_data": {
        "title": "Quy định về Thú cưng",
        "text_content": "...",
        "icon_id": "pet_icon" 
      },
      "source": "GENERATIVE_AI" 
      // Giá trị có thể là: "FAQ_KNOWLEDGE_BASE" hoặc "GENERATIVE_AI"
    }
    

  • Error Responses:
    • 404 Not Found: {"error_code": "FAQ_NOT_FOUND", "speech_text": "..."} (Áp dụng khi intent là FAQ nhưng không tìm thấy câu trả lời).

7. Các Yếu tố Phụ thuộc (Dependencies)

• Hệ thống Quản lý Nội dung (CMS): Vẫn cực kỳ quan trọng cho các câu hỏi phổ biến nhất.
• (Mới) Dữ liệu Nguồn cho AI: Tenant cần cung cấp các tài liệu dạng văn bản (nội quy, mô tả dịch vụ, danh sách cửa hàng...) để làm ngữ cảnh cho AI Tạo sinh.
• (Mới) Tích hợp Dịch vụ LLM: Phải hoàn tất việc lựa chọn và tích hợp API của một nhà cung cấp Mô hình Ngôn ngữ Lớn (ví dụ: Google Gemini, OpenAI).

8. Thước đo Thành công (Success Metrics)

• Tỷ lệ Trả lời từ FAQ (FAQ Hit Rate): % các câu hỏi được giải quyết bởi hệ thống FAQ nhanh và rẻ. Mục tiêu > 70%.
• Tỷ lệ Trả lời Thành công của Generative AI: Với các câu hỏi phải chuyển sang luồng AI tạo sinh, tỷ lệ người dùng đánh giá câu trả lời là hữu ích (qua nút 👍/👎).
• Tỷ lệ Hoàn thành Tác vụ Tổng thể: Tổng % các câu hỏi được trả lời thành công bởi cả hai luồng. Mục tiêu > 90%.
• Chi phí Vận hành API: Theo dõi chi phí gọi API đến LLM Provider để có kế hoạch tối ưu.

9. Business Flow

flowchart TD
    %% --- Định nghĩa Style cho các khối để dễ đọc hơn ---
    classDef startEnd fill:#2DA44E,stroke:#fff,color:#fff,font-weight:bold,shape:stadium
    classDef process fill:#161B22,stroke:#0A74DA,color:#F0F6FC
    classDef decision fill:#D18A06,stroke:#fff,color:#0D1117,shape:diamond
    classDef userIo fill:#0A74DA,stroke:#fff,color:#fff,shape:parallelogram

    %% --- Bắt đầu Luồng ---
    Start([Bắt đầu: Người dùng<br>tiếp cận Booth]):::startEnd
    Start --> UserAsks["Người dùng hỏi câu hỏi chung"]:::userIo

    %% --- Bước 1: Xử lý bằng FAQ (Ưu tiên) ---
    UserAsks --> ProcessFAQ["<b>Hệ thống xử lý (Bước 1 - Ưu tiên):</b><br>Đối sánh câu hỏi với bộ kiến thức FAQ"]:::process
    ProcessFAQ --> DecisionFAQ{Tìm thấy câu trả lời<br>chính xác trong FAQ?}:::decision

    %% --- Nhánh Thành công 1: Trả lời từ FAQ ---
    DecisionFAQ -- "Có" --> PrepareFAQResponse["Chuẩn bị câu trả lời<br>đã soạn sẵn từ CMS"]:::process
    PrepareFAQResponse --> DisplayResult["<b>Hiển thị Kết quả cho Người dùng:</b><br>- Avatar nói câu trả lời<br>- Hiển thị text & icon"]:::userIo

    %% --- Bước 2: Xử lý bằng AI Tạo sinh (Dự phòng) ---
    DecisionFAQ -- "Không" --> ProcessGenAI["<b>Hệ thống xử lý (Bước 2 - Dự phòng):</b><br>Gọi Generative AI Engine (LLM)<br>với ngữ cảnh liên quan"]:::process
    ProcessGenAI --> DecisionGenAI{AI tạo sinh được<br>câu trả lời hợp lệ?}:::decision

    %% --- Nhánh Thành công 2: Trả lời từ AI Tạo sinh ---
    DecisionGenAI -- "Có" --> DisplayResult

    %% --- Nhánh Thất bại cuối cùng ---
    DecisionGenAI -- "Không" --> DisplayError["<b>Phản hồi Lỗi Cuối cùng:</b><br>'Xin lỗi, về câu hỏi này<br>tôi chưa có thông tin...'"]:::userIo

    %% --- Vòng lặp Tương tác & Kết thúc ---
    DisplayResult --> InteractionLoop{Chờ tương tác tiếp theo...}:::decision
    DisplayError --> InteractionLoop

    InteractionLoop -- "Người dùng hỏi tiếp" --> UserAsks
    InteractionLoop -- "Timeout sau 15 giây" --> ResetState["Reset Booth<br>về màn hình chờ mặc định"]:::process
    ResetState --> End([Kết thúc Phiên]):::startEnd

Diễn giải Sơ đồ:

1. Bắt đầu & Xử lý bước 1: Luồng bắt đầu như bình thường, nhưng hệ thống sẽ ưu tiên xử lý bằng cách tra cứu trong bộ kiến thức FAQ trước. Đây là con đường nhanh, rẻ và an toàn nhất.
2. Điểm Quyết định 1: Hệ thống kiểm tra xem có tìm thấy câu trả lời chính xác trong FAQ không.
3. Nhánh Thành công 1: Nếu "Có", hệ thống sẽ ngay lập tức chuẩn bị và hiển thị câu trả lời đã được soạn sẵn, sau đó đi đến trạng thái chờ tương tác tiếp theo.
4. Nhánh Dự phòng: Nếu "Không" tìm thấy trong FAQ, luồng sẽ chuyển sang Bước 2, gọi đến AI Tạo sinh (Generative AI) để xử lý.
5. Điểm Quyết định 2: Hệ thống kiểm tra xem AI Tạo sinh có thể tạo ra một câu trả lời hợp lệ và an toàn dựa trên ngữ cảnh được cung cấp hay không.
6. Nhánh Thành công 2: Nếu "Có", câu trả lời được tạo ra cũng sẽ được hiển thị cho người dùng theo cùng một định dạng.
7. Nhánh Thất bại Cuối cùng: Chỉ khi cả hai hệ thống (FAQ và AI Tạo sinh) đều không thể đưa ra câu trả lời, hệ thống mới thông báo cho người dùng rằng nó không có thông tin.
8. Vòng lặp & Kết thúc: Tương tự như các luồng khác, sau mỗi phản hồi, hệ thống sẽ chờ đợi hành động kế tiếp hoặc tự động reset.

Sơ đồ này thể hiện rõ ràng chiến lược "Hybrid" của chúng ta, đảm bảo đội ngũ kỹ thuật hiểu đúng và xây dựng được luồng logic hai tầng một cách chính xác.

---

Ghi chú của Kiến trúc sư (Architect's Note): Mô hình Hybrid này là một bước tiến lớn. Nó đòi hỏi chúng ta phải có một chiến lược "prompt engineering" tốt để ra lệnh cho AI Tạo sinh một cách hiệu quả và an toàn. Việc ghi log lại trường source của mỗi câu trả lời là cực kỳ quan trọng; nó sẽ là mỏ vàng để chúng ta phân tích và liên tục tối ưu hóa hệ thống: chuyển các câu trả lời "tạo sinh" phổ biến thành câu trả lời FAQ để giảm chi phí và tăng tốc độ. Đây là cách chúng ta xây dựng một hệ thống thông minh thực thụ.