Đặc tả Tính năng: Tìm kiếm & Khám phá

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

Tìm kiếm & Khám phá đảm bảo rằng các tệp và thư mục luôn có thể tìm thấy khi tổ chức phát triển. Nó cung cấp một cơ chế tìm kiếm nhanh chóng, không phân biệt hoa thường, cho phép người dùng định vị các tài sản bằng tên và siêu dữ liệu mà không cần điều hướng qua các cây thư mục phức tạp.

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

Vai trò	Mục tiêu
Người dùng	Tìm nhanh một tài liệu bằng cách nhập vài ký tự của tên nó.
Quản trị viên	Khám phá các tài sản trên toàn bộ tổ chức để kiểm toá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 tìm kiếm "Hợp đồng" và xem tất cả các tệp có tên đó trong tổ chức của mình.
• Với tư cách là thành viên, tôi muốn xem đường dẫn thư mục của một kết quả tìm kiếm để biết ngữ cảnh của nó.

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

• REQ-SD-001: Tìm kiếm tệp theo tên trong thời gian thực (truy vấn tối thiểu 2 ký tự).
• REQ-SD-002: Kết quả tìm kiếm bao gồm folderId để điều hướng đến ngữ cảnh.
• REQ-SD-003: Lịch sử tìm kiếm gần đây cho mỗi người dùng (dự kiến v1.2).

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

• Độ trễ: Phản hồi tìm kiếm < 300ms cho tối đa 100.000 mục.
• Khả năng mở rộng: Hỗ trợ các truy vấn đa thuộc tính phức tạp.

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

• Phạm vi Tổ chức: Các kết quả bị giới hạn nghiêm ngặt trong organizationId của người dùng.
• Không phân biệt hoa thường: Các thuật ngữ tìm kiếm được xử lý không phân biệt hoa thường (ILIKE %q%).
• Độ dài tối thiểu: Truy vấn ngắn hơn 2 ký tự bị bỏ qua.
• Phân trang: Giới hạn mặc định 50 kết quả; hỗ trợ tham số limit và offset.

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

• Thanh tìm kiếm: Nhập liệu cố định trên thanh công cụ với các biểu tượng "Xóa" và "Gần đây".
• Kết quả thả xuống: Xem trước ngay lập tức 5 kết quả hàng đầu khi người dùng nhập.
• Trang kết quả đầy đủ: Chế độ xem chuyên dụng với các bộ lọc nâng cao và phân trang.

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

• Tìm kiếm toàn cầu có thể truy cập từ bất kỳ chế độ xem thư mục nào.
• Các thẻ kết quả tìm kiếm hiển thị: Biểu tượng, Tên, Đường dẫn thư mục và Kích thước.

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

• Các bảng: files, folders.
• Chỉ mục: Chỉ mục GIN hoặc B-tree trên các cột name và org_id.

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

• GET /api/files?q=term — tìm kiếm theo tên (tối thiểu 2 ký tự), hỗ trợ folderId, limit, offset

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

• Liên kết Shell: (Tương lai) Tìm kiếm toàn cầu của Shell có thể truy vấn API tìm kiếm của Drive qua gRPC.

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

• RBAC: Yêu cầu drive:read để thực hiện tìm kiếm.
• Quyền riêng tư: Chỉ tìm kiếm siêu dữ liệu (Tìm kiếm nội dung tệp được dự kiến cho v2 bằng cách tích hợp module AI Assistant).

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

• Trạng thái "Không tìm thấy kết quả" thân thiện với các mẹo tìm kiếm tốt hơn.
• Giới hạn tốc độ cho các yêu cầu tìm kiếm tần suất cao.

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

• Sử dụng các tính năng tìm kiếm toàn văn của cơ sở dữ liệu khi có thể.
• Giới hạn kết quả (Top 50) để ngăn chặn UI bị lag.

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

• Hỗ trợ tìm kiếm các ký tự tiếng Việt có dấu.

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

• Vùng Aria-live để thông báo cập nhật kết quả tìm kiếm.
• Các kết quả tìm kiếm thả xuống có thể truy cập bằng bàn phím.

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

• Theo dõi "Các thuật ngữ tìm kiếm hàng đầu" để hiểu tầm quan trọng của nội dung.
• Phân tích các tìm kiếm "Không có kết quả" để xác định nội dung còn thiếu.

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

• Kiểm thử tích hợp cho rò rỉ dữ liệu chéo thuê bao trong kết quả tìm kiếm.
• Kiểm thử hiệu năng với các tập dữ liệu lớn.

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

• Giả định việc đánh chỉ mục tên tổ chức là đủ cho nhu cầu khám phá v1.

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

• Lọc theo kiểu MIME (ví dụ: chỉ hình ảnh).
• Tìm kiếm toàn cầu trên cả tệp và thư mục.
• Ngữ cảnh đường dẫn phân cấp đầy đủ trong kết quả tìm kiếm.
• Tìm kiếm nội dung (OCR cho PDF và Hình ảnh).
• Tìm kiếm ngữ nghĩa thông qua tích hợp module AI Assistant.