Đặc tả Tính năng: Tổ chức Thư mục

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

Tổ chức Thư mục cho phép người dùng cấu trúc không gian làm việc kỹ thuật số của họ một cách logic. Nó cung cấp một hệ thống phân cấp đệ quy để nhóm các tệp, phản ánh các hệ thống tệp truyền thống đồng thời thêm các lợi ích thuần đám mây (cloud-native) như cô lập đa thuê bao và quản lý theo chương trình.

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

Vai trò	Mục tiêu
Người dùng	Tạo các danh mục logic cho tài liệu (ví dụ: "Dự án X", "Hóa đơn").
Quản lý	Tổ chức các tài sản của nhóm để dễ tìm kiếm hơn.
Quản trị viên HR	Duy trì các bản ghi có cấu trúc cho nhân viê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ạo các thư mục lồng nhau để có thể tổ chức các tài sản dự án của mình theo từng giai đoạn.
• Với tư cách là người dùng, tôi muốn di chuyển các tệp giữa các thư mục để có thể lưu trữ các công việc đã hoàn thành.
• Với tư cách là quản trị viên, tôi muốn xóa một thư mục và tất cả nội dung của nó chỉ trong một hành động.

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

• REQ-FO-001: Hỗ trợ độ sâu thư mục lồng nhau không giới hạn.
• REQ-FO-002: Tên thư mục duy nhất trong cùng một thư mục cha (không phân biệt hoa thường).
• REQ-FO-003: Đổi tên thư mục bằng một yêu cầu PATCH đơn lẻ.
• REQ-FO-004: Xóa đệ quy các thư mục và tất cả tệp cùng liên kết chia sẻ liên quan.

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

• Hiệu năng: Liệt kê thư mục cho 1000+ mục < 300ms.
• Toàn vẹn: Các tệp mồ côi PHẢI không tồn tại sau khi xóa thư mục.

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

• Xác thực: Tên thư mục không được chứa các ký tự hệ thống dành riêng (ví dụ: /, \).
• Kế thừa Chủ sở hữu: Các thư mục mới kế thừa organizationId của người tạo.
• Phân quyền Đổi tên: Người dùng thường chỉ có thể đổi tên thư mục do họ tạo (created_by).

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

• Điều hướng Breadcrumb: Đường dẫn động để điều hướng nhanh lên trên.
• Chế độ xem Cây: Cấu trúc thư mục có thể mở rộng ở thanh bên trái.
• Tương tác: Kéo-và-thả để di chuyển; Menu ngữ cảnh khi chuột phải.

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

• Được tích hợp bên trong Trình khám phá Drive chính.
• Định tuyến URL dựa trên đường dẫn (ví dụ: /drive/folders/:id).

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

• Bảng: folders.
• Ràng buộc: parentId tham chiếu chính nó với ON DELETE CASCADE (chỉ siêu dữ liệu).

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

• GET /api/folders — liệt kê thư mục, lọc theo parentId
• POST /api/folders — tạo thư mục
• PATCH /api/folders/:id — đổi tên thư mục ({ name: string })
• DELETE /api/folders/:id — xóa đệ quy

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

• Sự kiện: Di chuyển một thư mục sẽ kích hoạt một job chạy ngầm để cập nhật bất kỳ chỉ mục tìm kiếm bên ngoài nào.

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

• RBAC: Yêu cầu drive:write để tạo hoặc sửa đổi thư mục.
• Khóa Thuê bao: API ngăn chặn việc truy xuất hoặc sửa đổi các thư mục thuộc về orgId khác.

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

• Dọn dẹp Đệ quy: Lớp dịch vụ đảm bảo các đối tượng S3 được xóa khi các thư mục SQL bị gỡ bỏ.
• Phát hiện Xung đột: Phản hồi 409 Conflict tiêu chuẩn cho các tên trùng lặp.

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

• Materialized paths (dự kiến v1.3) để tối ưu hóa các truy vấn cây sâu.
• Phân trang cho các danh sách thư mục lớn.

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

• Hỗ trợ tên thư mục đa byte (Unicode).

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

• Các thành phần cây có thể tiếp cận với điều hướng bàn phím (Lên/Xuống/Trái/Phải).
• Nhãn Aria cho các hành động thư mục.

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

• Theo dõi "Độ sâu Thư mục" để xác định các điểm ma sát UX tiềm ẩn.

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

• Kiểm thử đơn vị cho logic đệ quy.
• Kiểm thử E2E cho luồng đổi tên và xóa đệ quy.

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

• Giả định các trigger cấp SQL hoặc logic ứng dụng xử lý việc dọn dẹp S3 đệ quy.

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

• Di chuyển thư mục sang thư mục cha khác (thay đổi parentId).
• Thao tác đổi tên và di chuyển hàng loạt.
• Thư mục Chia sẻ (quyền hạn chéo người dùng trong một tổ chức).
• Các biểu tượng thư mục mã hóa theo màu sắc.