Đặc tả Tính năng: Cấu hình Mẫu báo cáo

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

Cấu hình Mẫu báo cáo là giao diện tại thời điểm thiết kế cho việc báo cáo tự động. Nó cho phép quản trị viên định nghĩa "Cách thức" và "Nội dung" của một báo cáo bằng cách chọn các nguồn dữ liệu và cung cấp các hướng dẫn LLM tùy chỉnh, cho phép nền tảng tạo ra các bản tóm tắt chuyên nghiệp, nhất quán mà không cần sự can thiệp thủ công.

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

Vai trò	Mục tiêu
Quản trị viên	Tạo các bản thiết kế báo cáo có thể tái sử dụng cho tổ chức.
Ban điều hành	Nhận được các thông tin chi tiết có cấu trúc phù hợp với nhu cầu cụ thể của họ.
Lập trình viên	Định nghĩa các điểm cuối nguồn dữ liệu mới cho engine mẫu báo cáo.

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 tạo một mẫu "Tuyển dụng hàng tuần" thu thập dữ liệu HRM để không phải viết tay vào mỗi Thứ Hai.
• Với tư cách là quản trị viên, tôi muốn cung cấp một system prompt cụ thể (ví dụ: "Hãy ngắn gọn và sử dụng các gạch đầu dòng") để kiểm soát tông giọng của AI.
• Với tư cách là quản lý, tôi muốn xem trước một báo cáo trước khi kích hoạt lịch trình của nó.

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

• REQ-TEMP-001: Các thao tác CRUD cho mẫu báo cáo.
• REQ-TEMP-002: Lựa chọn nguồn dữ liệu đa module (HRM, Drive, Document).
• REQ-TEMP-003: Trình chỉnh sửa System Prompt tùy chỉnh với hỗ trợ biến (ví dụ: ).
• REQ-TEMP-004: Tạo "Xem trước" thời gian thực sử dụng dữ liệu mẫu.

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

• Độ trễ: Lưu mẫu báo cáo < 200ms.
• Tốc độ xem trước: Tạo báo cáo mẫu < 30 giây.

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

• Kế thừa tách biệt: Các thay đổi đối với một mẫu báo cáo không sửa đổi hồi tố các báo cáo đã được tạo.
• Xác thực: Các system prompt không được vượt quá 4000 token.
• Trạng thái nháp: Các mẫu PHẢI ở trạng thái "Hoạt động" (Active) mới được bộ lập lịch ghi nhận.

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

• Trình chỉnh sửa mẫu: Chế độ xem song song với Lựa chọn nguồn ở bên trái và Trình chỉnh sửa Prompt ở bên phải.
• Trình chọn nguồn: Lựa chọn dạng cây các điểm cuối module có sẵn.
• Bảng xem trước: Cửa sổ modal hiển thị đầu ra Markdown của AI.

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

• Tab "Mẫu báo cáo" trong bảng điều khiển Auto Report.
• Một phần của điều hướng chính cho module báo cáo.

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

• Bảng: report_templates.
• Các trường: name, description, sources (jsonb), system_prompt, status.

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

• GET /templates
• POST /templates
• POST /templates/:id/preview

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

• Khám phá Module: Truy xuất các nguồn dữ liệu có sẵn từ Sổ đăng ký Shell.
• OpenAI: Sử dụng GPT-4o-mini để tạo bản xem trước.

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

• RBAC: Yêu cầu quyền reports:manage để tạo hoặc chỉnh sửa mẫu.
• Cô lập: Các mẫu được giới hạn nghiêm ngặt trong organizationId.

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

• Nguồn không hợp lệ: Cảnh báo quản trị viên nếu một điểm cuối nguồn dữ liệu đã chọn không thể truy cập được.
• Lỗi Prompt: Xác thực cho các prompt trống hoặc tiêm mã độc.

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

• Siêu dữ liệu được cache ở lớp API.
• Các yêu cầu xem trước được giới hạn tốc độ để ngăn chặn chi phí LLM tăng đột biến.

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

• Hỗ trợ đa ngôn ngữ cho tên và mô tả mẫu báo cáo.

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

• Các trường biểu mẫu có thể tiếp cận với thông báo lỗi phù hợp (Aria-invalid).

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

• Theo dõi "Tỷ lệ tạo thành công" trên mỗi mẫu báo cáo.

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

• Kiểm thử tích hợp cho đường ống xem trước.
• Xác thực lược đồ cho trường JSON sources.

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

• Giả định rằng các module satellite cung cấp một điểm cuối báo cáo JSON tiêu chuẩn.

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

• Trình xây dựng prompt trực quan "Kéo-và-Thả".
• Thư viện mẫu cộng đồng (Các mẫu công khai được chia sẻ giữa các tổ chức).