# Nội dung chi tiết

## 1.1. Giới Thiệu

Hệ thống được xây dựng theo mô hình **Enterprise Service Bus (ESB)** kết hợp **API Management (APIM)**, sử dụng nền tảng **LifeESB** làm trung gian điều phối giữa Client và các Backend Service. Tích hợp thêm **Apache Kafka** để xử lý tải lớn theo mô hình bất đồng bộ.

> **Tên hệ thống:** LifeESB **APIM:** API Manager **Message Queue:** Apache Kafka (Broker: `hdp-master:9092`)

---

## 1.2. Sơ Đồ Kiến Trúc Tổng Thể

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--1" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="40" data-line-number="40" data-line-start="40"></div></div></div></div></div>[![service-architecture-layered.jpg](https://docs.lifetex.vn/uploads/images/gallery/2026-02/scaled-1680-/service-architecture-layered.jpg)](https://docs.lifetex.vn/uploads/images/gallery/2026-02/service-architecture-layered.jpg)

---

## 1.3. Các Thành Phần Chính

### 1.3.1. APIM — API Manager

Cổng vào duy nhất (Single Entry Point) cho toàn bộ hệ thống.

<div class="my-4" id="bkmrk-ch%E1%BB%A9c-n%C4%83ng-m%C3%B4-t%E1%BA%A3-x%C3%A1c-"><table class="min-w-full border-collapse"><thead><tr><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Chức năng</th><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Mô tả</th></tr></thead><tbody><tr><td class="px-6 py-2">Xác thực</td><td class="px-6 py-2">Kiểm tra JWT / OAuth2 / API Key trước khi vào LifeESB</td></tr><tr><td class="px-6 py-2">Rate Limiting</td><td class="px-6 py-2">Giới hạn số request/giây theo từng API hoặc User</td></tr><tr><td class="px-6 py-2">Versioning</td><td class="px-6 py-2">Quản lý nhiều version API (`/v1`, `/v2`) song song</td></tr><tr><td class="px-6 py-2">Analytics</td><td class="px-6 py-2">Theo dõi lưu lượng, latency, error rate</td></tr><tr><td class="px-6 py-2">Portal</td><td class="px-6 py-2">Developer Portal để publish và subscribe API</td></tr></tbody></table>

</div>### 1.3.2. LifeESB

Lớp tích hợp trung gian, chịu trách nhiệm điều phối luồng dữ liệu.

<div class="my-4" id="bkmrk-th%C3%A0nh-ph%E1%BA%A7n-file-ch%E1%BB%A9c"><table class="min-w-full border-collapse"><thead><tr><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Thành phần</th><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">File</th><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Chức năng</th></tr></thead><tbody><tr><td class="px-6 py-2">**Sync API**</td><td class="px-6 py-2"><div>  
</div><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all">PlanningDirectApi.xml</span></span></td><td class="px-6 py-2">Gọi thẳng Backend, Client nhận kết quả ngay</td></tr><tr><td class="px-6 py-2">**Async API**</td><td class="px-6 py-2"><div>  
</div><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all">KafkaProducerApi.xml</span></span></td><td class="px-6 py-2">Đẩy vào Kafka, trả phản hồi ngay cho Client</td></tr><tr><td class="px-6 py-2">**Inbound Endpoint**</td><td class="px-6 py-2"><div>  
</div><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all">Load\_balance\_example.xml</span></span></td><td class="px-6 py-2">Lắng nghe Kafka, kích hoạt Sequence xử lý</td></tr><tr><td class="px-6 py-2">**Sequence**</td><td class="px-6 py-2"><div>  
</div><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all">Load\_balance\_example-inboundSequence.xml</span></span></td><td class="px-6 py-2">Logic xử lý message: gọi Backend + phân loại lỗi</td></tr><tr><td class="px-6 py-2">**Error Sequence**</td><td class="px-6 py-2"><div>  
</div><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all">Load\_balance\_example-inboundErrorSequence.xml</span></span></td><td class="px-6 py-2">Xử lý lỗi Kafka, đẩy vào `error_topic`</td></tr><tr><td class="px-6 py-2">**Local Entry**</td><td class="px-6 py-2"><div>  
</div><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all">KafkaConnection.xml</span></span></td><td class="px-6 py-2">Cấu hình kết nối Kafka tái sử dụng</td></tr></tbody></table>

</div>### 1.3.3. Apache Kafka

Message Broker xử lý tải lớn và đảm bảo không mất dữ liệu.

<div class="my-4" id="bkmrk-topic-m%E1%BB%A5c-%C4%91%C3%ADch-test_"><table class="min-w-full border-collapse"><thead><tr><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Topic</th><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Mục đích</th></tr></thead><tbody><tr><td class="px-6 py-2">`test_topic_01`</td><td class="px-6 py-2">Nhận message từ API Producer (đầu vào)</td></tr><tr><td class="px-6 py-2">`processed_topic`</td><td class="px-6 py-2">Lưu message đã xử lý thành công</td></tr><tr><td class="px-6 py-2">`error_topic`</td><td class="px-6 py-2">Lưu message lỗi để review thủ công</td></tr></tbody></table>

</div>### 1.3.4. Backend Service

REST API xử lý nghiệp vụ thực tế.

<div class="my-4" id="bkmrk-th%C3%B4ng-tin-gi%C3%A1-tr%E1%BB%8B-ba"><table class="min-w-full border-collapse"><thead><tr><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Thông tin</th><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Giá trị</th></tr></thead><tbody><tr><td class="px-6 py-2">Base URL</td><td class="px-6 py-2">`http://192.168.0.133:8080`</td></tr><tr><td class="px-6 py-2">Endpoint chính</td><td class="px-6 py-2">`POST /api/v1/plannings`</td></tr><tr><td class="px-6 py-2">Xác thực</td><td class="px-6 py-2">JWT Bearer Token</td></tr><tr><td class="px-6 py-2">Framework</td><td class="px-6 py-2">Spring Boot</td></tr></tbody></table>

</div>---

## 1.4. Hai Mô Hình Dịch Vụ

### 1.4.1. Đồng Bộ — Synchronous (Direct API)

Client gọi và **chờ kết quả** từ Backend.

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk-client-%E2%86%92-apim-%E2%86%92-life" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end">  
</div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"><span class="mtk1">Client → APIM → LifeESB (PlanningDirectApi)</span></div></div><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"><span class="mtk1"> │</span></div></div><div class="code-line" data-line-end="3" data-line-number="3" data-line-start="3"><div class="line-content"><span class="mtk1"> ▼</span></div></div><div class="code-line" data-line-end="4" data-line-number="4" data-line-start="4"><div class="line-content"><span class="mtk1"> Backend API \[chờ response\]</span></div></div><div class="code-line" data-line-end="5" data-line-number="5" data-line-start="5"><div class="line-content"><span class="mtk1"> │</span></div></div><div class="code-line" data-line-end="6" data-line-number="6" data-line-start="6"><div class="line-content"><span class="mtk1"> ▼</span></div></div><div class="code-line" data-line-end="7" data-line-number="7" data-line-start="7"><div class="line-content"><span class="mtk1"> LifeESB → Client \[trả kết quả thực\]</span></div></div></div></div></div></div>**Đặc điểm:**

- Client biết ngay kết quả thành công hay thất bại
- Backend bị quá tải → Client bị block, timeout
- Phù hợp: nghiệp vụ cần xác nhận ngay, lượng request vừa phải

**Endpoint:** `POST /plannings-direct`

### 1.4.2. Bất Đồng Bộ — Asynchronous (Kafka)

Client gửi và **nhận phản hồi ngay** (không chờ Backend xử lý xong).

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--5" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end">  
</div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"></div><div class="code-line" data-line-end="12" data-line-number="12" data-line-start="12"><div class="line-content"><span class="mtk1">[![ho-so-core-flow (1).jpg](https://docs.lifetex.vn/uploads/images/gallery/2026-02/scaled-1680-/ho-so-core-flow-1.jpg)](https://docs.lifetex.vn/uploads/images/gallery/2026-02/ho-so-core-flow-1.jpg)</span></div></div></div></div></div></div>**Đặc điểm:**

- Client không bị block dù Backend chậm hoặc quá tải
- Kafka buffer message, đảm bảo không mất dữ liệu
- Phù hợp: tải lớn, xử lý nền, không cần kết quả ngay

**Endpoint:** `POST /kafka-producer`

---

## 1.5. So Sánh Hai Mô Hình

<div class="my-4" id="bkmrk-ti%C3%AAu-ch%C3%AD-%C4%90%E1%BB%93ng-b%E1%BB%99-%28%2Fp"><table class="min-w-full border-collapse"><thead><tr><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Tiêu chí</th><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Đồng bộ (`/plannings-direct`)</th><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Bất đồng bộ (`/kafka-producer`)</th></tr></thead><tbody><tr><td class="px-6 py-2">Client chờ</td><td class="px-6 py-2">✅ Chờ kết quả thực</td><td class="px-6 py-2">❌ Nhận `success` ngay lập tức</td></tr><tr><td class="px-6 py-2">Khả năng chịu tải</td><td class="px-6 py-2">Thấp hơn (Backend block)</td><td class="px-6 py-2">Cao (Kafka buffer)</td></tr><tr><td class="px-6 py-2">Độ trễ</td><td class="px-6 py-2">Phụ thuộc Backend</td><td class="px-6 py-2">Gần như bằng 0 (phía Client)</td></tr><tr><td class="px-6 py-2">Đảm bảo dữ liệu</td><td class="px-6 py-2">Ghi ngay hoặc lỗi ngay</td><td class="px-6 py-2">Kafka lưu, retry nếu fail</td></tr><tr><td class="px-6 py-2">Xử lý lỗi</td><td class="px-6 py-2">`faultSequence` → trả ngay</td><td class="px-6 py-2">`error_topic` → review sau</td></tr><tr><td class="px-6 py-2">Phù hợp</td><td class="px-6 py-2">Tải vừa, cần confirm</td><td class="px-6 py-2">Tải lớn, xử lý nền</td></tr><tr><td class="px-6 py-2">Timeout</td><td class="px-6 py-2">15 giây</td><td class="px-6 py-2">Không (Kafka giữ message)</td></tr></tbody></table>

</div>---

## 1.6. Nguyên Tắc Kiến Trúc

1. **Single Entry Point**: Mọi request đi qua APIM, không gọi thẳng LifeESB từ ngoài.
2. **Stateless Mediator**: LifeESB không lưu trạng thái — toàn bộ state trong Kafka hoặc Backend DB.
3. **Error Isolation**: Lỗi phải được bắt trong Sequence, không để lỗi raw thoát ra ngoài.
4. **Dead Letter Pattern**: Message lỗi luôn được chuyển vào `error_topic`, không bao giờ bị drop.
5. **Observability**: Mọi bước xử lý đều có `log level="custom"` để trace theo luồng.

---

## 1.7. Môi Trường Triển Khai

<div class="my-4" id="bkmrk-th%C3%A0nh-ph%E1%BA%A7n-host-%2F-po"><table class="min-w-full border-collapse"><thead><tr><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Thành phần</th><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Host / Port</th><th class="bg-gray-500/20 px-6 py-2 text-left font-medium">Ghi chú</th></tr></thead><tbody><tr><td class="px-6 py-2">LifeESB</td><td class="px-6 py-2">`192.168.0.167:8290`</td><td class="px-6 py-2">HTTP endpoint</td></tr><tr><td class="px-6 py-2">LifeESB Management</td><td class="px-6 py-2">`192.168.0.167:9201`</td><td class="px-6 py-2">Deploy CAR file</td></tr><tr><td class="px-6 py-2">Kafka Broker</td><td class="px-6 py-2">`hdp-master:9092`</td><td class="px-6 py-2">PLAINTEXT</td></tr><tr><td class="px-6 py-2">Backend API</td><td class="px-6 py-2">`192.168.0.133:8080`</td><td class="px-6 py-2">Spring Boot</td></tr></tbody></table>

</div>> 📸 **\[Ảnh minh họa\]** — LifeESB Dashboard sau khi deploy

[![image.png](https://docs.lifetex.vn/uploads/images/gallery/2026-02/scaled-1680-/4aHimage.png)](https://docs.lifetex.vn/uploads/images/gallery/2026-02/4aHimage.png)

> 📸 **\[Ảnh minh họa\]** — Kafka UI / Kafka Manager hiển thị các topic