Đặc tả Tính năng: Lập lịch & Thực thi
1. Tổng quan & Tầm nhìn
Lập lịch & Thực thi là động cơ vận hành của module Auto Report. Nó quản lý vòng đời của việc tạo báo cáo, từ các kích hoạt cron dựa trên thời gian đến các yêu cầu "Chạy ngay" thủ công, đảm bảo rằng các báo cáo được tạo ra một cách đáng tin cậy và mọi lần chạy đều được ghi lại để phục vụ kiểm toán.
2. Các Vai trò & Bên liên quan
| Vai trò | Mục tiêu |
|---|---|
| Quản trị viên | Thiết lập các báo cáo định kỳ và giám sát sự thành công của chúng. |
| DevOps | Đảm bảo các worker chạy ngầm khỏe mạnh và đang xử lý các công việ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 đặt một báo cáo chạy vào mỗi Thứ Sáu lúc 5 giờ chiều để tôi có sẵn một bản tóm tắt cho cuối tuần.
- Với tư cách là quản trị viên, tôi muốn kích hoạt chạy báo cáo thủ công để thu thập ảnh chụp nhanh dữ liệu hiện tại trước một cuộc họp lớn.
- Với tư cách là quản trị viên, tôi muốn xem lý do tại sao một báo cáo đã lên lịch bị thất bại để tôi có thể sửa lỗi nguồn dữ liệu.
4. Yêu cầu Chức năng (FR)
- REQ-SCH-001: Lập lịch tự động dựa trên cron (Hàng ngày, Hàng tuần, Hàng tháng).
- REQ-SCH-002: Kích hoạt "Chạy ngay" thủ công cho bất kỳ mẫu nào đang hoạt động.
- REQ-SCH-003: Lưu trữ lịch sử tạo báo cáo (
execution_logs). - REQ-SCH-004: Theo dõi trạng thái thời gian thực (Đang chờ, Đang chạy, Thành công, Lỗi).
5. Yêu cầu Phi chức năng (NFR)
- Độ tin cậy: Các lần chạy thất bại PHẢI thu thập được stack trace hoặc thông báo lỗi chi tiết.
- Tính đồng thời: Hỗ trợ thực thi song song nhiều mẫu báo cáo.
6. Logic & Quy tắc Nghiệp vụ
- Độ chính xác Cron: Độ chính xác trong vòng 1 phút so với thời gian đã lên lịch.
- Logic thử lại: Tự động thử lại (lên đến 3 lần) cho các lỗi mạng tạm thời.
- Chụp ảnh nhanh: Mọi lần chạy thành công PHẢI lưu lại một ảnh chụp nhanh (snapshot) của ngữ cảnh đầu vào đã sử dụng.
7. Giao diện Người dùng (UI/UX)
- Lịch sử chạy: Chế độ xem bảng với các nhật ký theo trình tự thời gian và biểu tượng trạng thái.
- Trình chỉnh sửa lịch trình: Các menu thả xuống đơn giản cho các tần suất phổ biến + nhập Cron tùy chỉnh.
- Giám sát thực thi: Thông báo Toast khi một lần chạy thủ công hoàn thành.
8. Kiến trúc Thông tin
- Tab "Lịch sử chạy" trong bảng điều khiển module.
- Liên kết đến chi tiết thực thi từ danh sách mẫu báo cáo.
9. Mô hình Dữ liệu & Lưu trữ
- Bảng:
execution_logs. - Các trường:
templateId,status,startedAt,completedAt,errorMessage.
10. Lớp API & Dịch vụ
POST /templates/:id/runGET /executionsGET /executions/:id
11. Các Mẫu Tích hợp
- Mastra: Sử dụng engine workflow Mastra để quản lý hàng đợi tác vụ và cron.
- Sự kiện Shell: (Tương lai) Kích hoạt một sự kiện toàn nền tảng khi tạo báo cáo thành công.
12. Bảo mật & Quyền hạn
- RBAC: Yêu cầu quyền
reports:runcho các kích hoạt thủ công;reports:viewcho lịch sử. - Cô lập: Lịch sử chạy được giới hạn nghiêm ngặt trong
organizationIdcủa người dùng.
13. Xử lý Lỗi & Khả năng Phục hồi
- Timeout: Thời gian chờ tối đa 5 phút cho việc tạo báo cáo để ngăn chặn worker bị treo.
- Thất bại một phần: Ghi nhật ký nếu một số nguồn dữ liệu bị lỗi nhưng AI vẫn tạo ra được báo cáo.
14. Hiệu năng & Khả năng Mở rộng
- Kiến trúc worker phân tán để xử lý việc lập lịch khối lượng lớn trên nhiều thuê bao.
- Đánh chỉ mục cơ sở dữ liệu trên trường
startedAtđể truy xuất lịch sử nhanh chóng.
15. Toàn cầu hóa & Bản địa hóa
- Lập lịch nhận biết múi giờ dựa trên múi giờ đã cấu hình của tổ chức.
16. Khả năng Tiếp cận (a11y)
- Vùng Aria-live cho các cập nhật trạng thái trong trình giám sát thực thi.
17. Khả năng Quan sát & Phân tích
- Theo dõi "Thời gian thực thi trung bình" trên mỗi mẫu báo cáo.
- Giám sát "Độ sâu hàng đợi của Worker".
18. Kiểm thử & Chất lượng
- Kiểm thử đơn vị cho logic phân tích cú pháp cron.
- Kiểm thử tích hợp cho vòng đời worker Mastra.
19. Các Ràng buộc & Giả định
- Giả định rằng tiến trình Mastra worker đang chạy và được kết nối với cơ sở dữ liệu.
20. Các Cải tiến Tương lai
- Kích hoạt qua Webhook (Chạy báo cáo khi sự kiện X bên ngoài xảy ra).
- Tích hợp Slack/Discord để nhận cảnh báo trạng thái.