Đặc tả Tính năng: Điều phối Dịch vụ

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

Điều phối Dịch vụ là cơ chế liên kết Shell Host với các ứng dụng SCS (Hệ thống Tự vận hành) liên minh. Nó xử lý việc khám phá dịch vụ động, quản lý vòng đời micro-frontend (Gắn kết/Gỡ bỏ) và tiêm môi trường thực thi, đảm bảo rằng nền tảng có thể mở rộng bằng cách thêm các module mới mà không cần biên dịch lại Shell cốt lõi.

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

Vai trò	Mục tiêu
Quản trị viên Hệ thống	Đăng ký và kích hoạt các module nền tảng mới thông qua các URL entry.
Lập trình viên	Tích hợp một ứng dụng SCS mới vào hệ sinh thái Shell.
Người dùng cuối	Trải nghiệm chuyển đổi ứng dụng trang đơn liền mạch giữa các module.

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

• Với tư cách là lập trình viên, tôi muốn cung cấp một URL remoteEntry.js duy nhất cho Shell để ứng dụng của tôi có sẵn ngay lập tức.
• Với tư cách là quản trị viên, tôi muốn tạm dừng một module để bảo trì mà không ảnh hưởng đến phần còn lại của nền tảng.

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

• REQ-ORC-001: Sổ đăng ký dịch vụ tập trung cho siêu dữ liệu (Tên, Slug, URL API, URL UI).
• REQ-ORC-002: Tải động các điểm vào từ xa thông qua Module Federation.
• REQ-ORC-003: Giám sát sức khỏe của các dịch vụ satellite.
• REQ-ORC-004: Kiểm tra khả năng tương thích phiên bản giữa Shell và các ứng dụng từ xa.

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

• Hiệu năng: Tra cứu khám phá dịch vụ < 100ms.
• Khả năng phục hồi: Lỗi trong một ứng dụng từ xa không được làm treo Shell Host (Ranh giới lỗi cô lập).

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

• Hợp đồng Entry: Tất cả các ứng dụng từ xa PHẢI xuất một hàm mount và unmount thông qua ./ShellEntry.
• Slug: Mỗi dịch vụ phải có một slug duy nhất toàn cầu được sử dụng để định tuyến (ví dụ: /drive, /hrm).
• Cô lập: Các ứng dụng từ xa chạy trong cây React DOM riêng nhưng chia sẻ cấu hình Tailwind của Shell.

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

• Launchpad: Lưới trực quan hiển thị các dịch vụ đang hoạt động.
• Trạng thái Dịch vụ: Chỉ báo trực quan (Xanh/Đỏ) trong cổng Quản trị cho sức khỏe dịch vụ.
• Trạng thái Tải: Màn hình Shimmer/Skeleton trong khi một module từ xa đang được tải.

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

• Một phần của miền "Quản lý Nền tảng".
• Hiển thị qua trang ServicesPage của Shell dành cho quản trị viên.

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

• Bảng: apps.
• Các trường: id, name, slug, ui_url, api_url, status, metadata.

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

• GET /api/config/apps: Điểm cuối khám phá công khai.
• POST /api/admin/apps: Điểm cuối đăng ký.
• ServiceRegistryService: Logic nghiệp vụ cho quản lý ứng dụng.

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

• Module Federation: Giao thức chính cho tích hợp UI.
• Đồng bộ Siêu dữ liệu Từ xa: Shell truy xuất xuất khẩu meta từ xa để tự động cấu hình các tuyến đường.

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

• RBAC: apps:read cho người dùng; apps:write cho Quản trị viên hệ thống.
• Xác thực: Tất cả các URL entry phải được xác thực cho các nguồn gốc an toàn.

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

• Logic Thử lại: Shell cố gắng tải lại entry từ xa nếu lần truy xuất ban đầu thất bại.
• UI Dự phòng: Thông báo "Dịch vụ tạm thời không khả dụng" khi một ứng dụng từ xa bị treo.

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

• Tải chậm (Lazy loading) các module từ xa (chỉ truy xuất khi được truy cập).
• Chia sẻ các thư viện vendor (React, Ardor UI) để giảm kích thước tải xuống.

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

• Hỗ trợ tên hiển thị được bản địa hóa trong sổ đăng ký.

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

• Thông báo các chuyển đổi dịch vụ cho trình đọc màn hình thông qua các vùng ARIA live.

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

• Theo dõi "Thời gian tải dịch vụ" và "Tần suất treo từ xa".

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

• Kiểm thử tích hợp đảm bảo tiện ích loadRemote xử lý các lỗi mạng khác nhau.

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

• Giả định các ứng dụng từ xa được lưu trữ trên S3/Nginx với các tiêu đề CORS chính xác.

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

• Triển khai canary tự động cho các ứng dụng từ xa.
• Chế độ xem đa module song song (Chia màn hình).