Tổng quan tích hợp

Mục đích

Tài liệu này là điểm bắt đầu cho các đội bên ngoài cần tích hợp với Heliuos hoặc cần hiểu cách Heliuos trao đổi bối cảnh với một hệ thống khác.

Bạn có thể dùng trang này để mô tả bề mặt sản phẩm, luồng dữ liệu, trách nhiệm của từng hệ thống và nguyên tắc tích hợp trước khi viết tài liệu API chi tiết.

Đối tượng đọc

• Đối tác sản phẩm đang đánh giá cách Heliuos phù hợp với workflow của họ.
• Đội kỹ thuật chuẩn bị tích hợp.
• Đội vận hành nội bộ cần tài liệu bàn giao rõ ràng.

Nguyên tắc tích hợp

1. Bối cảnh người dùng phải rõ ràng. Mọi dữ liệu gửi sang Heliuos cần có phạm vi cụ thể, dễ hiểu và có thể truy vết.
2. Riêng tư là mặc định. Không gửi dữ liệu cá nhân nếu workflow không thật sự cần hoặc người dùng chưa cho phép.
3. Hệ thống đối tác giữ vai trò nguồn sự thật. Heliuos có thể làm giàu, tóm tắt và hỗ trợ, nhưng hệ thống gốc nên là nơi lưu trạng thái chính.
4. Lỗi cần có đường phục hồi. Tích hợp bên ngoài nên hỗ trợ retry, audit log và trạng thái lỗi dễ hiểu.

Thông tin nên có trong mỗi tài liệu

Khi viết một tài liệu tích hợp mới, hãy mô tả:

• Chủ sở hữu hệ thống và đầu mối liên hệ.
• Mục tiêu tích hợp.
• Dữ liệu gửi vào Heliuos.
• Dữ liệu Heliuos trả về.
• Yêu cầu xác thực hoặc phân quyền.
• Hành trình người dùng mong đợi.
• Cách xử lý lỗi.
• Câu hỏi mở hoặc giới hạn hiện tại.

Workflow mẫu

1. Hệ thống đối tác gửi một bản tóm tắt dự án đã được giới hạn phạm vi sang Heliuos.
2. Heliuos dùng bối cảnh đó để chuẩn bị hỗ trợ phù hợp.
3. Người dùng xem lại, phê duyệt hoặc chỉnh sửa kết quả.
4. Hệ thống đối tác lưu kết quả cuối cùng đã được người dùng duyệt.

Trạng thái

Đây là tài liệu mẫu ban đầu. Khi bề mặt tích hợp rõ hơn, hãy mở rộng trang này bằng API contract, ví dụ payload và hướng dẫn riêng cho từng đối tác.