Đặc tả Tính năng: Chia sẻ Bên ngoài

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

Chia sẻ Bên ngoài cho phép hợp tác an toàn với các cá nhân bên ngoài tổ chức. Nó cho phép người dùng tạo các liên kết tạm thời, được mã hóa bằng token đến các tệp, cung cấp một giải pháp thay thế an toàn cho các tệp đính kèm email trong khi vẫn duy trì sự kiểm soát và khả năng kiểm toán tập trung đối với các tài sản được chia sẻ.

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

Vai trò	Mục tiêu
Người dùng	Chia sẻ các sản phẩm dự án với khách hàng hoặc đối tác.
Người nhận bên ngoài	Tải xuống an toàn các tệp được chia sẻ mà không cần tài khoản.
Quản trị viên	Giám sát và thu hồi các liên kết truy cập bên ngoài trong toàn tổ chức.

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 chia sẻ một liên kết PDF hết hạn trong 3 ngày để khách hàng có thể xem xét đề xuất.
• Với tư cách là người dùng, tôi muốn thu hồi một liên kết ngay lập tức nếu tôi đã chia sẻ sai phiên bản.
• Với tư cách là người nhận, tôi muốn tải xuống tệp trực tiếp từ liên kết mà không cần đăng nhập.

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

• REQ-SH-001: Tạo các token chia sẻ duy nhất, không thể đoán trước (base64url random bytes).
• REQ-SH-002: Thời hạn hết hạn liên kết có thể cấu hình: chính xác 1, 3, hoặc 7 ngày (ttlDays).
• REQ-SH-003: Thu hồi thủ công các liên kết chia sẻ đang hoạt động (xóa mềm qua revokedAt).
• REQ-SH-004: Bảo vệ bằng mật khẩu cho các liên kết chia sẻ (dự kiến v1.2).

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

• Bảo mật: Các token PHẢI an toàn về mặt mã hóa (UUID v4 hoặc tương đương).
• Độ trễ: Tạo liên kết chia sẻ < 100ms.

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

• Định dạng Token: drive.venizia.ai/s/{token}.
• Logic Hết hạn: Các liên kết trở nên không hợp lệ ngay khi dấu thời gian expires_at trôi qua.
• Nhật ký Truy cập: Mỗi lần tải xuống qua một liên kết chia sẻ đều được ghi lại (dự kiến).

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

• Modal "Chia sẻ" với lựa chọn hết hạn và nút "Sao chép liên kết".
• Tab quản lý "Liên kết đã chia sẻ" hiển thị các liên kết đang hoạt động và trạng thái của chúng.
• Trang đích công khai cho người nhận với siêu dữ liệu tệp và nút tải xuống.

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

• Hành động trong menu ngữ cảnh trên bất kỳ tệp nào.
• Chế độ xem trung tâm "Chia sẻ bên ngoài" trong cài đặt Drive.

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

• Bảng: share_links.
• Các trường: fileId, token, expiresAt, createdBy, revokedAt.

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

• POST /api/files/:id/share — tạo liên kết chia sẻ ({ ttlDays: 1 | 3 | 7 })
• GET /api/files/:id/share — liệt kê các liên kết chia sẻ đang hoạt động của tệp
• DELETE /api/files/:id/share/:linkId — thu hồi liên kết chia sẻ
• GET /api/public/files/:token — tải xuống công khai (không yêu cầu xác thực)

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

• Truyền Trực tiếp: Trình xử lý chia sẻ công khai xác minh token (kiểm tra hết hạn + thu hồi), sau đó truyền trực tiếp nội dung nhị phân từ MinIO vào HTTP response. Không tạo presigned URL.

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

• RBAC: Yêu cầu quyền drive:share để tạo liên kết.
• Truy cập Công khai: Các liên kết chia sẻ bỏ qua Shell SSO nhưng bị giới hạn nghiêm ngặt trong siêu dữ liệu tệp cụ thể và nội dung nhị phân.

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

• Token không hợp lệ: Trang đích "Liên kết này không còn khả dụng" thân thiện.
• Tệp bị xóa: Các liên kết chia sẻ tự động mất hiệu lực nếu tệp nguồn bị xóa.

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

• Tra cứu token được đánh chỉ mục để truy cập công khai đồng thời cao.

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

• Trang chia sẻ công khai có sẵn bằng tiếng Anh và tiếng Việt.

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

• Trang đích công khai tuân thủ WCAG 2.2 để dễ dàng tải xuống trên di động/máy tính để bàn.

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

• Theo dõi "Các lần tải xuống bên ngoài" để xác định các tài sản được chia sẻ có lưu lượng truy cập cao.

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

• Kiểm thử tích hợp cho việc hết hạn token.
• Kiểm toán bảo mật của điểm cuối công khai để ngăn chặn việc giả mạo tham số.

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

• Giả định người nhận có trình duyệt web tiêu chuẩn để truy cập liên kết.

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

• Chế độ chỉ xem (Không tải xuống) sử dụng trình xem PDF trong trình duyệt.
• Danh sách "Được chia sẻ với tôi" nội bộ cho hợp tác chéo tổ chức (v2).