Đặc tả Tính năng: Bộ kết nối Dữ liệu

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

Bộ kết nối Dữ liệu là đường ống dẫn tri thức tổ chức vào engine báo cáo. Chúng cung cấp một cách chuẩn hóa để thu thập, làm sạch và nén dữ liệu từ các module satellite (HRM, Drive, Docs), đảm bảo rằng LLM có ngữ cảnh liên quan nhất để tạo ra các báo cáo chính xác.

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

Vai trò	Mục tiêu
Quản trị viên	Cấu hình các điểm dữ liệu nào được đưa vào báo cáo.
Lập trình viên	Duy trì và mở rộng thư viện bộ kết nối cho các module mới.

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 thu thập "Yêu cầu nghỉ phép" của 7 ngày qua để tạo bản tóm tắt chuyên cần hàng tuần.
• Với tư cách là quản trị viên, tôi muốn thu thập "Tài liệu dự án" từ Drive để tạo báo cáo sức khỏe dự án hàng tháng.

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

• REQ-CON-001: Hỗ trợ các bộ kết nối module nội bộ (HRM, Drive, Document).
• REQ-CON-002: Thu thập dữ liệu đệ quy cho các đối tượng phức tạp (ví dụ: Thư mục + Tệp).
• REQ-CON-003: Làm sạch dữ liệu trong lúc truyền (loại bỏ HTML, ẩn dữ liệu PII).
• REQ-CON-004: Quản lý cửa sổ ngữ cảnh (tự động cắt bớt/tóm tắt).

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

• Bảo mật: Việc thu thập PHẢI sử dụng token dịch vụ-với-dịch vụ (S2S) với phạm vi hạn chế.
• Hiệu năng: Thu thập dữ liệu từ các module nội bộ < 2 giây.

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

• Ảnh chụp nhanh: Dữ liệu thu thập được lưu dưới dạng ảnh chụp nhanh JSON cùng với báo cáo.
• Nén: Các payload vượt quá 10.000 token sẽ tự động được tóm tắt bởi một mô hình nhỏ hơn trước khi chuyển đến mô hình tạo nội dung chính.
• Tính toàn vẹn thuê bao: Các bộ kết nối PHẢI truyền tiêu đề organizationId cho mọi lệnh gọi API satellite.

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

• Trình cấu hình nguồn: UI dạng cây để chọn các điểm cuối module cụ thể.
• Bảng ánh xạ: Danh sách trực quan hiển thị các trường dữ liệu đang được thu thập từ mỗi nguồn.

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

• Một phần của quy trình công việc "Cấu hình Mẫu báo cáo".

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

• Bảng: report_results (lưu trữ data_snapshot jsonb).
• Cấu hình: Được định nghĩa trong report_templates.sources.

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

• GET /internal/sources: Danh mục nội bộ các điểm cuối bộ kết nối có sẵn.
• IngestionService điều phối việc thu thập từ nhiều module.

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

• gRPC/Connect: Giao thức ưu tiên cho việc thu thập dữ liệu nội bộ.
• Platform JWT: Các token S2S được Shell cấp cho mỗi yêu cầu của bộ kết nối.

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

• Phạm vi: Các bộ kết nối chỉ được cấp quyền read đối với các tài nguyên yêu cầu.
• Quyền riêng tư dữ liệu: PII (Thông tin nhận dạng cá nhân) có thể tùy chọn được ẩn trong quá trình thu thập (dự kiến v1.2).

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

• Fail-fast: Nếu một nguồn dữ liệu bắt buộc bị lỗi, toàn bộ lượt chạy báo cáo sẽ được đánh dấu là "Lỗi".
• Ngữ cảnh một phần: (Tùy chọn) Cho phép tạo báo cáo ngay cả khi một số nguồn không thiết yếu không thể truy cập.

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

• Thu thập song song từ nhiều module satellite sử dụng Promise.all.
• Cache kết quả cho các báo cáo hàng ngày định kỳ.

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

• Hỗ trợ thu thập nội dung đa ngôn ngữ (UTF-8).

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

• Chế độ xem cây có thể tiếp cận cho việc lựa chọn nguồn.

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

• Theo dõi "Kích thước Payload" mỗi bộ kết nối để giám sát chi phí token.
• Giám sát độ trễ phản hồi từ các module satellite.

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

• Giả lập (Mock) các API satellite cho các bài kiểm tra đơn vị thu thập dữ liệu.
• Xác thực logic chuyển đổi từ JSON sang văn bản.

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

• Giả định các module satellite tuân theo định dạng phản hồi API tiêu chuẩn của VENI-AI.

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

• Các bộ kết nối bên ngoài (Google Sheets, Salesforce, HubSpot).
• Truyền phát dữ liệu thời gian thực (v2).