Orbz trong microfrontend

Web Component là ranh giới hữu ích giữa các microfrontend vì hợp đồng khi chạy của nó thuộc về trình duyệt thay vì một framework cụ thể. Orbz có thể được hiển thị bởi mô-đun từ xa Vue, cập nhật bởi ứng dụng chủ Angular, rồi thay bằng giao diện React mà không cần đổi thẻ hay thuộc tính.

Orbz được thiết kế làm thành phần trực quan ở nút lá, không đảm nhiệm vai trò hệ thống định tuyến hay nền tảng microfrontend hoàn chỉnh. Hãy dùng chiến lược kết hợp hiện có cho điều hướng, dữ liệu, danh tính và triển khai. Dùng orb-z làm hình ảnh trợ lý dùng chung tại giao diện của các hệ thống đó.

Hợp đồng dùng chung

Cách tích hợp bền vững nhất là dùng mã đánh dấu của nền tảng web:

<orb-z
  state="idle"
  size="18rem"
  reduced-motion="system"
></orb-z>

Ứng dụng chủ hoặc mô-đun từ xa cập nhật các thuộc tính công khai khi trạng thái nghiệp vụ thay đổi:

import type { OrbzElement, OrbzState } from "@neongate-ai/orbz";
 
export function renderAssistantState(state: OrbzState) {
  const orb = document.querySelector<OrbzElement>("orb-z");
  if (orb) orb.state = state;
}

Không có đối tượng framework nào đi qua ranh giới này. Hợp đồng gồm chuỗi, số, thuộc tính boolean và ba phương thức.

Chọn bên đăng ký phần tử

Có ba mô hình thực tế.

1. Ứng dụng chủ đăng ký Orbz

Ứng dụng chủ nhập điểm vào dành cho trình duyệt một lần:

import "@neongate-ai/orbz/browser";

Các mô-đun từ xa chỉ hiển thị <orb-z>. Cách này giảm mã gói bị lặp và giao rõ trách nhiệm quản lý phiên bản cho ứng dụng chủ. Đây là lựa chọn mặc định rõ ràng nhất khi ứng dụng chủ đã quản lý các thành phần thiết kế cơ bản dùng chung.

2. Mỗi mô-đun từ xa nhập cùng một phiên bản cố định

Mỗi mô-đun từ xa có thể khai báo phụ thuộc và nhập Orbz độc lập. Việc đăng ký có tính lũy đẳng, nên các lần nhập sau nhận thấy định nghĩa orb-z đã tồn tại thay vì định nghĩa lại.

Hãy thống nhất chính xác phiên bản gói giữa các bản triển khai. Sổ đăng ký Custom Elements không thể thay thế thẻ đã được định nghĩa: phiên bản đăng ký đầu tiên trên trang sẽ được dùng. Vì vậy, chênh lệch phiên bản có thể khiến hành vi phụ thuộc vào thứ tự tải mô-đun từ xa, dù thao tác đăng ký không phát sinh lỗi.

3. Chia sẻ Orbz qua trình đóng gói hoặc import map

Module Federation, import map hoặc một cơ chế chia sẻ khi chạy khác có thể cung cấp một thể hiện gói duy nhất. Cách này có thể giảm số byte trùng lặp, nhưng chỉ là tối ưu hóa, không phải yêu cầu của Orbz. Hãy giữ quy tắc phiên bản rõ ràng ngay cả khi công cụ đánh dấu gói là singleton.

Phân định trách nhiệm rõ ràng

Chọn một bên phụ trách cho mỗi trách nhiệm:

Tránh để nhiều mô-đun từ xa ghi vào cùng một phần tử. Dịch vụ dùng chung có thể phát trạng thái nghiệp vụ của trợ lý, nhưng chỉ mô-đun từ xa hiển thị quả cầu mới nên ánh xạ và áp dụng trạng thái đó.

Truyền trạng thái nghiệp vụ thay vì lệnh DOM

Một hợp đồng kém chặt chẽ phát các lệnh như “đổi quả cầu sang màu tím” hoặc “tạm dừng lớp thứ ba”. Điều này đưa chi tiết trình bày vào bus của nền tảng.

Một hợp đồng vững chắc hơn phát trạng thái ứng dụng có ý nghĩa:

type AssistantStatus =
  | { phase: "ready" }
  | { phase: "capturing" }
  | { phase: "processing" }
  | { phase: "playing" }
  | { phase: "offline" }
  | { phase: "error"; message: string };

Mô-đun từ xa phụ trách hiển thị ánh xạ capturing sang listening, processing sang thinking, v.v. Lỗi vẫn được thể hiện bằng văn bản và hành động thực tế, thay vì biến thành hoạt ảnh không có tài liệu giải thích.

Triển khai độc lập

Cấu trúc kho mã và cấu trúc triển khai là hai lựa chọn riêng biệt. Kho mã dùng chung có thể giúp điều phối cục bộ thuận tiện hơn, trong khi mỗi ví dụ hoặc microfrontend vẫn là một dự án Vercel độc lập. Ngược lại, các kho mã không liên quan có thể dùng cùng phiên bản npm và hiển thị quả cầu giống hệt nhau.

Đối với giao diện được triển khai độc lập:

1. thêm @neongate-ai/orbz vào danh sách phụ thuộc riêng của ứng dụng;
2. cố định hoặc quản lý tập trung phiên bản được phép dùng;
3. nhập /browser từ điểm vào phía máy khách của ứng dụng;
4. cung cấp trạng thái trợ lý qua hợp đồng dữ liệu hiện có của ứng dụng;
5. triển khai mà không nhập mã nguồn Orbz hay một ứng dụng ví dụ khác.

Các bản trình diễn trực tuyến Vanilla , React , Vue , Svelte , Angular  và Next.js  minh họa sáu ứng dụng chủ độc lập sử dụng cùng một giao diện thành phần.

Hành vi khi lỗi và phương án dự phòng

Trước khi được đăng ký, phần tử tùy chỉnh chưa xác định vẫn là HTML hợp lệ nhưng chưa có hành vi. Đây là ranh giới hữu ích cho việc bổ sung chức năng dần dần: nhãn và điều khiển xung quanh vẫn có thể hiển thị trong khi gói thành phần đang tải.

Thiết kế ứng dụng chủ để người dùng vẫn hiểu trợ lý khi không có hoạt ảnh:

<div role="status" aria-live="polite">
  <orb-z state="thinking"></orb-z>
  <span>Assistant is preparing a response</span>
</div>

Nếu mô-đun từ xa không tải được, văn bản vẫn truyền đạt trạng thái. Nếu Orbz được đăng ký sau đó, phần tử sẽ được nâng cấp ngay tại chỗ.

Danh sách kiểm tra microfrontend

• Dùng gói npm làm ranh giới; không nhập src/ từ ứng dụng khác.
• Thống nhất chính xác một phiên bản Orbz giữa các mô-đun từ xa được tải đồng thời.
• Đăng ký tại một vị trí xác định duy nhất khi có thể.
• Duy trì một bên ghi duy nhất cho mỗi quả cầu được hiển thị.
• Phát trạng thái nghiệp vụ qua bus ứng dụng, không phát chi tiết trực quan nội bộ.
• Giữ văn bản trạng thái và điều khiển bên ngoài Shadow DOM đóng.
• Kiểm thử nâng cấp ứng dụng chủ khi bật giảm chuyển động và trì hoãn tải JavaScript.
• Xem tên thẻ và các thuộc tính được tài liệu hóa là API tích hợp ổn định.