User Story 01: Chức năng Chỉ đường (Wayfinding)

Mã tài liệu:	US-01	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 hàng, Tôi muốn hỏi đường đến một cửa hàng hoặc khu vực cụ thể (ví dụ: "Uniqlo ở đâu?"), Để tôi có thể tìm đường một cách dễ dàng và không bị lạc.

2. Mô tả (Description)

Đây là tính năng cốt lõi và quan trọng nhất của EZD AI Booth trong phiên bản MVP. Nó hiện thực hóa giá trị cốt lõi của sản phẩm: cung cấp thông tin chính xác, tức thì trong một trải nghiệm tương tác tự nhiên. Việc thực hiện thành công user story này sẽ chứng minh được năng lực của nền tảng AI, khả năng tương tác của Booth Device và mang lại giá trị thiết thực ngay lập tức cho người dùng cuối.

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

AC1: Khi người dùng hỏi đường đến một địa điểm hợp lệ, hệ thống phải trả lời bằng giọng nói với thông tin vị trí chính xác (ví dụ: tầng, khu vực).
AC2: Đồng thời với phản hồi giọng nói, màn hình phải hiển thị một bản đồ 2D/3D trực quan, làm nổi bật (highlight) vị trí hiện tại của booth và vị trí của điểm đến.
AC3: Đường đi được đề xuất trên bản đồ phải có hiệu ứng highlight chuyển động nhẹ nhàng (subtle animated path) để dẫn dắt ánh mắt của người dùng một cách tự nhiên từ điểm đầu đến điểm cuối.
AC4: Bản đồ hiển thị trên màn hình phải hỗ trợ các cử chỉ cảm ứng tiêu chuẩn bao gồm: chụm để phóng to/thu nhỏ (pinch-to-zoom) và kéo để di chuyển (pan).
AC5: Nếu địa điểm người dùng hỏi không tồn tại trong cơ sở dữ liệu, AI phải phản hồi một cách lịch sự, ví dụ: "Rất tiếc, tôi không tìm thấy cửa hàng này. Bạn có muốn tìm một địa điểm khác không?".
AC6 (Quy tắc Toàn cục): Nếu không có bất kỳ tương tác nào (giọng nói hoặc chạm) 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 - "Happy Path")

Bắt đầu: Người dùng tiếp cận Booth. Avatar 3D chuyển từ trạng thái chờ sang chào hỏi.
Ra lệnh: Người dùng hỏi: "Nhà vệ sinh gần nhất ở đâu?". Giao diện hiển thị trạng thái "Đang lắng nghe".
Xử lý: Hệ thống ghi nhận, chuyển giọng nói thành văn bản, gửi lên backend xử lý. Giao diện hiển thị trạng thái "Đang suy nghĩ".
Phản hồi: Hệ thống trả về kết quả.
- Giọng nói: "Dạ, nhà vệ sinh gần nhất ở cuối hành lang này, bên tay phải ạ."
- Hình ảnh: Màn hình hiển thị bản đồ với đường đi được tô sáng bằng hiệu ứng chuyển động.
Tương tác: Người dùng có thể phóng to, thu nhỏ bản đồ để xem chi tiết.
Kết thúc: Người dùng rời đi. Sau 15 giây, màn hình tự động 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 cần thiết kế:
- Idle State: Trạng thái chờ với "vòng lặp thu hút".
- Listening State: Trạng thái lắng nghe với hiệu ứng micro.
- Processing State: Trạng thái suy nghĩ với hiệu ứng xử lý.
- Result State (Map View): Trạng thái hiển thị bản đồ và kết quả.
- Result List (List View): Trạng thái hiển thị danh sách điểm tìm kiếm.

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: UI Application, Voice Client, Map Renderer, Avatar Engine, TTS Client.
- Backend: API Gateway, InteractionProcessingService, NLP Service, Primary DB, Audit Service.
Hợp đồng API (API Contract):
- Endpoint: POST /v1/ezd/interactions/query
- Request Body (Booth gửi lên):
```
{
  "booth_id": "string",
  "session_id": "string",
  "input_text": "string"
}
```
- Success Response (Backend trả về - 200 OK):
```
{
  "speech_text": "string",
  "display_type": "map_directions",
  "map_data": {
    "booth_coords": [number, number],
    "destination_coords": [number, number],
    "path": [[number, number], ...]
  }
}
```
- Error Responses (Backend trả về):
  - 404 Not Found: {"error_code": "LOCATION_NOT_FOUND", "speech_text": "..."}
  - 400 Bad Request: {"error_code": "NLP_INTENT_NOT_RECOGNIZED", "speech_text": "..."}

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

Dữ liệu: Phải có bản đồ số hóa và CSDL tọa độ các địa điểm (POI) từ Tenant trước khi bắt đầu Sprint.
Dịch vụ: Phải hoàn tất việc lựa chọn và tích hợp API cho các dịch vụ Speech-to-Text và Text-to-Speech.

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

Tỷ lệ Hoàn thành Tác vụ: > 85% các câu hỏi chỉ đường được trả lời thành công.
Thời gian Phản hồi: \< 3 giây (từ lúc người dùng hỏi xong đến khi hệ thống bắt đầu trả lời).
Tỷ lệ Lỗi NLP: \< 10% các câu hỏi chỉ đường bị trả lời "Tôi không hiể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 đặt câu hỏi"]:::userIo

    %% --- Xử lý & Phân loại Yêu cầu ---
    UserAsks --> SystemProcesses["<b>Hệ thống xử lý:</b><br>1. Speech-to-Text<br>2. NLP Phân tích Ý định & Thực thể"]:::process
    SystemProcesses --> DecisionType{Câu hỏi Rõ ràng<br>hỏi 1 địa điểm hay<br>Mơ hồ - hỏi 1 danh mục?}:::decision

    %% --- Nhánh 1: Xử lý Câu hỏi Rõ ràng ---
    DecisionType -- "Rõ ràng" --> FoundDecision{Tìm thấy địa điểm<br>cụ thể trong CSDL?}:::decision
    FoundDecision -- "Có" --> PrepareMapResponse["Chuẩn bị Phản hồi<br>Bản đồ & Chỉ dẫn"]:::process
    PrepareMapResponse --> DisplayMap["<b>Hiển thị Kết quả (Bản đồ):</b><br>- Avatar nói và chỉ dẫn<br>- Bản đồ hiện đường đi"]:::userIo

    %% --- Nhánh 2: Xử lý Câu hỏi Mơ hồ / Liệt kê ---
    DecisionType -- "Mơ hồ / Liệt kê" --> CategoryFound{Tìm thấy các địa điểm<br>trong danh mục không?}:::decision
    CategoryFound -- "Có" --> PrepareListResponse["Chuẩn bị Phản hồi<br>dạng Danh sách"]:::process
    PrepareListResponse --> DisplayList["<b>Hiển thị Kết quả (Danh sách):</b><br>- Avatar hỏi người dùng muốn chọn đâu<br>- Hiển thị danh sách các địa điểm"]:::userIo

    %% --- Các Nhánh Lỗi & Hợp nhất Luồng ---
    FoundDecision -- "Không" --> DisplayError["<b>Phản hồi Lỗi Lịch sự:</b><br>'Xin lỗi, tôi không tìm thấy...<br>Bạn thử lại được không?'"]:::userIo
    CategoryFound -- "Không" --> DisplayError

    DisplayMap --> InteractionLoop{Chờ tương tác tiếp theo...}:::decision
    DisplayList --> InteractionLoop
    DisplayError --> InteractionLoop

    %% --- Vòng lặp & Kết thúc ---
    InteractionLoop -- "Người dùng hỏi tiếp / Chọn từ danh sách" --> UserAsks
    InteractionLoop -- "Timeout sau 15 giây" --> ResetState["Reset Booth<br>về màn hình chờ"]:::process
    ResetState --> End([Kết thúc Phiên]):::startEnd

Diễn giải Sơ đồ:

Phân loại Yêu cầu: Sau khi xử lý ngôn ngữ tự nhiên, điểm quyết định đầu tiên (DecisionType) là quan trọng nhất. Hệ thống sẽ phân loại câu hỏi là "Rõ ràng" (hỏi về một địa điểm duy nhất) hay "Mơ hồ / Liệt kê" (hỏi về một nhóm địa điểm).
Nhánh 1 (Xử lý câu hỏi rõ ràng): Luồng này giống hệt như sơ đồ cũ. Nếu người dùng hỏi "Uniqlo ở đâu?", hệ thống sẽ đi theo nhánh này, kiểm tra xem có "Uniqlo" không và hiển thị bản đồ.
Nhánh 2 (Xử lý câu hỏi mơ hồ): Đây là luồng mới. Nếu người dùng hỏi "Ở đây có quán cà phê nào?", hệ thống sẽ đi theo nhánh này.
- Nó sẽ kiểm tra xem có tìm thấy các địa điểm thuộc danh mục "quán cà phê" không.
- Nếu có, nó sẽ hiển thị một danh sách và mời người dùng chọn một địa điểm cụ thể.
- Nếu người dùng chọn một quán từ danh sách, hành động đó sẽ được coi như một câu hỏi mới, rõ ràng và luồng sẽ quay lại từ đầu để xử lý.
Hợp nhất Luồng: Tất cả các kết quả (hiển thị bản đồ, hiển thị danh sách, thông báo lỗi) đều dẫn đến một trạng thái chờ chung, nơi hệ thống đợi hành động tiếp theo của người dùng hoặc tự động reset.

Ghi chú của Kiến trúc sư (Architect's Note): Đây là user story nền tảng. Sự thành công của nó phụ thuộc vào sự phối hợp nhịp nhàng giữa Frontend và Backend. Đội ngũ Backend phải đảm bảo API phản hồi nhanh và đúng theo hợp đồng. Đội ngũ Frontend phải tối ưu hóa việc render bản đồ và các hiệu ứng để tạo ra một trải nghiệm mượt mà, không giật cục. Hãy đảm bảo hai bên giao tiếp liên tục trong suốt quá trình phát triển.