Đặc tả Tính năng: Phân tích & Phản hồi

1. Tổng quan & Tầm nhìn

Phân tích & Phản hồi cung cấp các thông tin chi tiết dựa trên dữ liệu cần thiết để cải thiện hiệu suất của AI Assistant theo thời gian. Bằng cách thu thập các đánh giá của người dùng và theo dõi các mẫu truy vấn, nó xác định các lỗ hổng trong cơ sở tri thức và đảm bảo rằng AI đang mang lại giá trị hữu hình cho tổ chức.

2. Các Vai trò & Bên liên quan

Vai trò	Mục tiêu
Thành viên	Cung cấp phản hồi về độ chính xác của AI để cải thiện các câu trả lời trong tương lai.
Quản trị viên Tri thức	Xác định các truy vấn "Không tìm thấy câu trả lời" để ưu tiên các nguồn dữ liệu mới.
Ban điều hành	Đo lường ROI của AI Assistant (ví dụ: thời gian tiết kiệm được so với chi phí truy vấn).

3. Câu chuyện Người dùng (User Stories)

• Với tư cách là người dùng, tôi muốn nhấp vào biểu tượng "Ngón tay xuống" để có thể báo cáo một ảo giác hoặc câu trả lời sai.
• Với tư cách là quản trị viên, tôi muốn xem biểu đồ về các câu hỏi được đặt ra thường xuyên nhất trong tháng này.
• Với tư cách là quản trị viên, tôi muốn biết tài liệu nào đang được AI trích dẫn nhiều nhất.

4. Yêu cầu Chức năng (FR)

• REQ-ANA-001: Hệ thống đánh giá ở cấp độ tin nhắn (Hữu ích/Không hữu ích).
• REQ-ANA-002: Bảng điều khiển sử dụng toàn tổ chức (Truy vấn, Phiên hoạt động).
• REQ-ANA-003: Modal thu thập phản hồi cho các đánh giá "Không hữu ích".
• REQ-ANA-004: Tự động theo dõi các sự kiện "Không tìm thấy ngữ cảnh liên quan".

5. Yêu cầu Phi chức năng (NFR)

• Ẩn danh: ID người dùng cá nhân PHẢI được ẩn danh trong các chế độ xem quản trị tổng hợp (dự kiến v1.1).
• Độ trễ: Thời gian tải bảng điều khiển phân tích < 1 giây.

6. Logic & Quy tắc Nghiệp vụ

• Tổng hợp: Dữ liệu được nhóm theo orgId và có thể được lọc theo Phạm vi ngày (Ngày, Tuần, Tháng).
• Điểm cảm xúc: Hệ thống tính toán "Điểm hữu ích" (Hữu ích / Tổng số đánh giá) cho mỗi nguồn.
• Tính toán chi phí: (Tùy chọn) Ước tính chi phí token dựa trên giá của từng mô hình.

7. Giao diện Người dùng (UI/UX)

• Widget đánh giá: Các biểu tượng 👍/👎 đơn giản dưới mỗi tin nhắn của AI.
• Hộp thoại phản hồi: Vùng văn bản cho câu hỏi "Làm thế nào để chúng tôi cải thiện câu trả lời này?".
• Bảng điều khiển quản trị: Lưới trực quan với Recharts (Biểu đồ đường cho xu hướng, Biểu đồ thanh cho các nguồn hàng đầu).

8. Kiến trúc Thông tin

• Tab "Phân tích" trong cổng Quản trị AI Assistant.
• Các widget phản hồi được tích hợp vào cửa sổ Chat.

9. Mô hình Dữ liệu & Lưu trữ

• Bảng: message_feedback.
• Các trường: messageId, isHelpful, comment, orgId.

10. Lớp API & Dịch vụ

• POST /messages/:id/feedback
• GET /analytics/summary (Chỉ dành cho Admin).

11. Các Mẫu Tích hợp

• Recharts: Để trực quan hóa dữ liệu ở frontend.
• Worker: (Tương lai) Tổng hợp định kỳ các nhật ký thô vào các bảng tóm tắt.

12. Bảo mật & Quyền hạn

• RBAC: Yêu cầu quyền ai_assistant:view_analytics để truy cập bảng điều khiển.
• Quyền riêng tư: Nội dung của các cuộc hội thoại cá nhân bị ẩn đối với quản trị viên theo mặc định.

13. Xử lý Lỗi & Khả năng Phục hồi

• Lỗi gửi: Thử lại mượt mà nếu việc gửi phản hồi thất bại do lỗi mạng.
• Thiếu dữ liệu: Thông báo cho quản trị viên nếu không có đủ dữ liệu cho phạm vi thời gian đã chọn.

14. Hiệu năng & Khả năng Mở rộng

• Tối ưu hóa truy vấn sử dụng các chỉ mục tổng hợp.
• Hỗ trợ các tổ chức có hơn 100.000 truy vấn hàng tháng.

15. Toàn cầu hóa & Bản địa hóa

• Hỗ trợ các nhận xét phản hồi đa ngôn ngữ.

16. Khả năng Tiếp cận (a11y)

• Trạng thái Aria-pressed cho các nút đánh giá.
• Các biểu đồ có thể tiếp cận với các bảng dữ liệu ẩn cho trình đọc màn hình.

17. Khả năng Quan sát & Phân tích

• Theo dõi "Tỷ lệ phản hồi" (Đánh giá / Tổng số tin nhắn).

18. Kiểm thử & Chất lượng

• Kiểm thử tích hợp cho việc lưu trữ phản hồi.
• Xác thực logic tổng hợp dữ liệu qua các múi giờ khác nhau.

19. Các Ràng buộc & Giả định

• Giả định rằng người dùng sẵn lòng cung cấp phản hồi tự nguyện.

20. Các Cải tiến Tương lai

• Gợi ý chủ động dựa trên các truy vấn thường gặp.
• Quản lý "Câu trả lời vàng" (Ghi đè thủ công cho các câu hỏi cụ thể).
• Báo cáo ROI (Ước tính số giờ tiết kiệm được).