Đặc tả Tính năng: Lưu trữ & Tải lên Tệp

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

Tính năng Lưu trữ Tệp cung cấp khả năng cơ bản để tải lên, lưu trữ và truy xuất các tài sản kỹ thuật số. Nó hướng tới việc trở thành "Ổ cứng" của hệ sinh thái VENI-AI, cung cấp khả năng lưu trữ hiệu năng cao, an toàn và được phân tách theo tổ chức cho tất cả các module.

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

Vai trò	Mục tiêu
Người dùng	Tải lên và quản lý các tệp cá nhân và dự án.
Quản trị viên	Quản lý hạn mức lưu trữ toàn tổ chức và các tài sản.
Dịch vụ Satellite	Lưu trữ và truy xuất tệp theo chương trình (ví dụ: avatar HRM).

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 kéo nhiều tài liệu vào Drive để chúng được lưu trữ an toàn trên đám mây.
• Với tư cách là thành viên, tôi muốn tải xuống phiên bản mới nhất của một bản tóm tắt dự án để làm việc ngoại tuyến.
• Với tư cách là quản trị viên, tôi muốn xóa các tệp cũ để giải phóng không gian lưu trữ của tổ chức.

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

• REQ-DR-001: Hỗ trợ tải lên nhiều tệp (Kéo-và-Thả).
• REQ-DR-002: Hỗ trợ kích thước tệp tối đa lên đến 100MB.
• REQ-DR-003: Xác thực kiểu MIME và giữ nguyên tên tệp gốc.
• REQ-DR-004: Stream trực tiếp đến S3 an toàn cho các lần tải lên lớn.

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

• Khả năng mở rộng: Hỗ trợ hàng triệu tệp trên mỗi tổ chức.
• Tính sẵn sàng: Tỷ lệ thành công 99.9% cho việc truy xuất tệp.
• Bảo mật: Các tệp PHẢI được mã hóa khi lưu trữ trong backend lưu trữ.

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

• Kiểm tra Hạn mức: Việc tải lên bị chặn nếu vượt quá storage_quota của tổ chức.
• Streaming: Các tệp được stream trực tiếp đến S3 để giảm thiểu việc sử dụng bộ nhớ API.
• Tính nhất quán: Siêu dữ liệu chỉ được ghi vào SQL sau khi có xác nhận thành công từ S3.

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

• Trình khám phá tệp: Chế độ xem Lưới và Danh sách với siêu dữ liệu (kích thước, ngày, người sở hữu).
• Hàng đợi tải lên: Ngăn kéo bên cạnh hiển thị các tiến trình tải lên đang hoạt động.
• Xem trước: Trình xem tích hợp cho Hình ảnh, PDF và Văn bản thuần túy.

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

• Điều hướng "Drive" gốc.
• Cấu trúc thư mục lồng nhau (Xem tính năng Tổ chức Thư mục).

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

• Bảng: files.
• Backend: Tương thích S3 (MinIO / AWS S3).
• Đường dẫn: s3://{orgId}/{fileId}_{filename}.

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

• POST /files (multipart/form-data)
• GET /files/:id/download (Chuyển hướng đến URL có chữ ký)
• DELETE /files/:id

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

• URL có chữ ký: Được API tạo ra để tải xuống trực tiếp từ S3 một cách an toàn và có thời hạn.
• Liên dịch vụ: HRM sử dụng StorageService nội bộ để quản lý ảnh đại diện.

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

• RBAC: drive:read để xem/tải xuống; drive:write để tải lên/xóa.
• Cô lập: Mọi yêu cầu đều được xác thực dựa trên organizationId của người dùng.

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

• Lỗi Multipart: Logic tự động thử lại cho các chunk bị lỗi (dự kiến).
• Lỗi thân thiện: Thông báo người dùng rõ ràng cho "Vượt quá hạn mức" hoặc "Tệp quá lớn".

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

• Tải lên song song cho nhiều tệp.
• Tích hợp CDN cho các tài sản công khai (dự kiến v1.5).

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

• Hỗ trợ các bộ ký tự không phải Latinh trong tên tệp (UTF-8).

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

• Vùng Aria-live để thông báo tiến trình tải lên.
• Chọn tệp và menu ngữ cảnh 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 xu hướng "Tiêu thụ lưu trữ" trên mỗi tổ chức.
• Giám sát "Độ trễ tải lên" và "Tỷ lệ lỗi".

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

• Kiểm thử tích hợp sử dụng container MinIO cục bộ.
• Kiểm thử áp lực cho các kịch bản tải lên đồng thời cao.

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

• Giả định tổ chức có đăng ký gói cước đang hoạt động với hạn mức lưu trữ.

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

• Chuyển mã và phát trực tuyến video (transcoding & streaming).
• Gắn thẻ thông minh sử dụng thị giác máy tính (v2).