SYSTEM BUSINESS LOGIC: API INTERFACE & TASK MANAGEMENT

Phân hệ API (được xây dựng trên nền tảng ElysiaJS và Bun) đóng vai trò là Cổng giao tiếp trung tâm (API Gateway). Đây là điểm chạm duy nhất để các hệ thống bên ngoài (như CMS Admin Frontend) giao tiếp, phân phối lệnh và giám sát hệ thống Worker chạy ngầm.

1. Nghiệp vụ Tiếp nhận và Khởi tạo Tác vụ (Task Ingestion Business)

Tiếp nhận Đơn lẻ & Hàng loạt (Single vs. Bulk Ingestion): - Hệ thống cung cấp hai luồng khởi tạo riêng biệt: POST /api/task cho các yêu cầu kiểm tra tức thời (thủ công) và POST /api/task/list để nạp dữ liệu hàng loạt từ các chiến dịch quét quy mô lớn (auto-cronjob từ CMS).

Nghiệp vụ này giúp giảm thiểu số lượng kết nối HTTP (TCP Handshake) khi cần đẩy hàng nghìn tên miền vào hệ thống cùng lúc, tối ưu hóa băng thông và tài nguyên máy chủ.

Kiểm soát tính toàn vẹn dữ liệu: Mọi tác vụ khi được nạp vào qua API đều mang trạng thái mặc định là Khởi tạo (0 - Pending) để đảm bảo quy trình đưa vào Hàng đợi (Queue) phía sau diễn ra tuần tự, tránh tình trạng Race Condition (xung đột luồng).

Cập nhật & Thu hồi Tác vụ (Update & Delete): Thông qua PUT /api/task/:id và DELETE /api/task, hệ thống cho phép các hệ thống ngoại vi can thiệp vào vòng đời tác vụ. Ví dụ: Hủy bỏ hàng loạt các tác vụ đang chờ nếu chiến dịch quét bị tạm dừng, giúp giải phóng hàng đợi.

2. Nghiệp vụ Kiểm soát Tải và Đồng thời (Concurrency & Load Control)

Giám sát Khối lượng công việc (Workload Monitoring): Endpoint GET /api/task/count-processing thực thi nghiệp vụ đếm số lượng tác vụ đang ở trạng thái 1 - Running.

Cân bằng Tải (Load Balancing/Throttling): Dữ liệu từ endpoint đếm này được sử dụng làm chỉ báo (metric) quan trọng. Nếu số lượng task đang xử lý vượt quá ngưỡng chịu tải của Server (dựa trên PROCESS_LIMIT), hệ thống nguồn (CMS) có thể quyết định tạm dừng đẩy thêm task mới, giúp bảo vệ Worker Server khỏi tình trạng cạn kiệt bộ nhớ (OOM - Out of Memory) hoặc sập CPU.

3. Nghiệp vụ Điều phối Dữ liệu Nội bộ & Dự phòng (Fallback Webhook Business)

Về cơ bản, hệ thống tự động trả kết quả về hookUrl khi Worker chạy xong. Tuy nhiên, trong thực tế vận hành có thể xảy ra tình trạng rớt mạng nội bộ (Network Partition) đúng thời điểm trả kết quả.

Kích hoạt Webhook Thủ công (Manual Dispatch): Hệ thống API cung cấp các endpoint POST /api/task/sendToWebhook và POST /api/task/sendToWebhooks để thực thi nghiệp vụ Dự phòng (Fallback). Quản trị viên hoặc các script sửa lỗi có thể gọi API này để ép hệ thống đóng gói và gửi lại (Retry) kết quả của một hoặc nhiều tác vụ về CMS mà không cần phải chạy lại toàn bộ tiến trình quét trình duyệt (vốn tốn rất nhiều thời gian).

4. Nghiệp vụ Giám sát Vận hành & Tra cứu (Observability & Audit Business)

Truy xuất Nhật ký Tập trung (Centralized Log Access): Nghiệp vụ yêu cầu quản trị viên có thể theo dõi tình trạng sức khỏe của ứng dụng mà không cần quyền truy cập SSH trực tiếp vào Server vật lý.

Khai thác Log qua API: Endpoint GET /api/task/getLogs cho phép ứng dụng bên thứ ba truy xuất, lọc và đọc nội dung trực tiếp từ các tệp tin log vật lý lưu tại storage/log/. Việc này hỗ trợ đội ngũ kỹ thuật phát hiện sớm các vấn đề kẹt luồng, lỗi Proxy hay lỗi crash của FFmpeg một cách trực quan trên giao diện Admin.

5. Nghiệp vụ Tiêu chuẩn hóa Giao thức (API Standardization Business)

Để đảm bảo khả năng tích hợp mở rộng (Scalability) với nhiều hệ thống đối tác trong tương lai, toàn bộ hệ thống API được đặc tả và tự động sinh tài liệu chuẩn Swagger/OpenAPI.

Bất kỳ dịch vụ nào khi truy cập vào http://localhost:8080/swagger đều nắm được chính xác cấu trúc DTO (Data Transfer Object), Payload cần gửi và định dạng Response trả về, giúp chuẩn hóa quá trình giao tiếp giữa các Microservices.

API INTERFACE & TASK MANAGEMENT

SYSTEM BUSINESS LOGIC: API INTERFACE & TASK MANAGEMENT#

1. Nghiệp vụ Tiếp nhận và Khởi tạo Tác vụ (Task Ingestion Business)#

2. Nghiệp vụ Kiểm soát Tải và Đồng thời (Concurrency & Load Control)#

3. Nghiệp vụ Điều phối Dữ liệu Nội bộ & Dự phòng (Fallback Webhook Business)#