Đặc tả Tính năng: Xuất bản & Phân phối

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

Xuất bản & Phân phối là giai đoạn cuối cùng của vòng đời báo cáo. Nó đảm bảo rằng các thông tin chi tiết do AI tạo ra sẽ đến đúng người, đúng định dạng. Bằng cách cung cấp các bản xuất PDF chất lượng cao và thông báo đa kênh (Trong ứng dụng, Email), nó làm cho báo cáo trở nên có thể hành động và di động cho các bên liên quan bên ngoài nền tảng.

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

Vai trò	Mục tiêu
Ban điều hành	Nhận các báo cáo PDF chuyên nghiệp qua email cho các cuộc họp hội đồng quản trị.
Quản trị viên	Phân phối các bản tóm tắt tự động tới các kênh nhóm cụ thể.
Kiểm toán viên bên ngoài	Xem xét các ảnh chụp nhanh PDF lịch sử về trạng thái tổ chức.

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

• Với tư cách là quản trị viên, tôi muốn xuất một báo cáo đã tạo sang PDF để có thể in ra cho một cuộc họp trực tiếp.
• Với tư cách là quản lý, tôi muốn được thông báo trong Shell ngay khi báo cáo hàng tuần của tôi đã sẵn sàng.
• Với tư cách là quản trị viên, tôi muốn hệ thống tự động gửi email báo cáo tài sản hàng tháng cho CFO.

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

• REQ-DEL-001: Tạo tệp PDF chất lượng cao từ nội dung Markdown.
• REQ-DEL-002: Phân phối đa kênh: Trong ứng dụng, Email, và Slack (dự kiến).
• REQ-DEL-003: Danh sách phân phối có thể cấu hình (ai nhận báo cáo nào).
• REQ-DEL-004: Hỗ trợ gắn thương hiệu tùy chỉnh (Logo, Màu sắc) trong các bản xuất PDF.

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

• Hiệu năng: Tạo tệp PDF < 10 giây cho một báo cáo dài 5 trang.
• Độ trung thực: Bố cục PDF PHẢI khớp chính xác với bản xem trước trên web.

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

• Tính cuối cùng của ảnh chụp nhanh: Báo cáo là chỉ đọc một khi đã được phân phối.
• Bảo mật liên kết: Các liên kết trong email PHẢI sử dụng token sử dụng một lần an toàn để xác thực.
• Gắn thương hiệu: Sử dụng cài đặt organization_id để áp dụng đúng logo công ty vào đầu trang PDF.

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

• Cấu hình phân phối: Menu thả xuống chọn nhiều thành viên nhóm và nhập email bên ngoài.
• Menu xuất bản: Các hành động rõ ràng "Tải xuống PDF" và "Gửi Email" trên mỗi kết quả báo cáo.
• Chuông thông báo: Chỉ báo trực quan khi một tác vụ tạo báo cáo chạy ngầm hoàn thành.

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

• Một phần của chế độ xem "Kết quả Báo cáo".
• "Cài đặt Phân phối" bên trong Trình chỉnh sửa Mẫu báo cáo.

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

• Bảng: report_results (lưu trữ đường dẫn lưu trữ PDF).
• Cấu hình: Người nhận phân phối được lưu trong report_templates.delivery_config.

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

• GET /executions/:id/export: Kích hoạt tạo PDF.
• POST /executions/:id/deliver: Kích hoạt phân phối đa kênh.

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

• Puppeteer: Dịch vụ Chrome không giao diện được sử dụng để render HTML-sang-PDF.
• SendGrid: Tích hợp để phân phối email đáng tin cậy.
• Drive: Các tệp PDF đã tạo được tự động lưu trữ trong một thư mục "Báo cáo" ẩn trong Drive.

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

• RBAC: Yêu cầu quyền reports:view để tải xuống hoặc kích hoạt phân phối.
• Ẩn thông tin: (Tương lai) Khả năng ẩn dữ liệu nhạy cảm dựa trên vai trò của người nhận.

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

• Theo dõi thư rác: Ghi nhật ký nếu việc phân phối email thất bại.
• Thử lại việc tạo: Tự động thử lại việc tạo PDF nếu trình duyệt không giao diện bị treo.

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

• Việc tạo PDF được chuyển sang hàng đợi tác vụ chạy ngầm.
• Hỗ trợ tạo hơn 100 tệp PDF đồng thời.

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

• Hỗ trợ phông chữ và ký tự tiếng Việt trong việc tạo PDF.

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

• Các tệp PDF được tạo tuân theo tiêu chuẩn Tagged PDF cho trình đọc màn hình.

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

• Theo dõi "Tỷ lệ mở" cho các báo cáo được gửi qua email.
• Giám sát "Độ trễ tạo PDF".

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

• Kiểm thử hồi quy hình ảnh cho bố cục PDF.
• Kiểm thử khả năng phân phối email trên các nhà cung cấp lớn (Gmail, Outlook).

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

• Giả định rằng dịch vụ Puppeteer có quyền truy cập vào các phông chữ và tài sản phong cách yêu cầu.

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

• Hook phân phối Slack / Microsoft Teams.
• PDF tương tác (với các liên kết có thể nhấp quay lại VENI-AI).
• Xuất hàng loạt (Tải xuống tất cả báo cáo cho Quý 1).