# 1.Cấu trúc dự án

## 1.1. Mục tiêu chương

Chương này quy định cấu trúc dự án chuẩn và phạm vi quản lý artifact giữa **Core Team** và các đơn vị **Partner**, nhằm:

<div id="bkmrk-%C4%90%E1%BA%A3m-b%E1%BA%A3o-t%C3%ADnh-%E1%BB%95n-%C4%91%E1%BB%8Bnh">- Đảm bảo tính ổn định của hệ thống tích hợp
- Tránh xung đột cấu hình và artifact giữa các đơn vị phát triển
- Chuẩn hóa cách tổ chức integration artifact trong toàn dự án
- Tăng khả năng bảo trì, mở rộng và triển khai hệ thống

---

</div>## 1.2. Khái niệm và phạm vi áp dụng

Tài liệu này được áp dụng cho:

<div id="bkmrk-t%E1%BA%A5t-c%E1%BA%A3-c%C3%A1c-d%E1%BB%B1-%C3%A1n-s%E1%BB%AD-">- Tất cả các dự án sử dụng nền tảng **<span class="hover:entity-accent entity-underline inline cursor-pointer align-baseline"><span class="whitespace-normal">WSO2 Micro Integrator</span></span>**
- **Core Team**: Đội phát triển lõi, chịu trách nhiệm quản lý hạ tầng, cấu hình hệ thống và các thành phần dùng chung
- **Partner Team**: Các đơn vị đối tác, chịu trách nhiệm phát triển các luồng nghiệp vụ cụ thể

</div>## 1.3. Cấu trúc dự án chuẩn

Cấu trúc dự án được tổ chức theo tiêu chuẩn nhằm phân tách rõ ràng giữa cấu hình hệ thống, tài nguyên tích hợp và logic nghiệp vụ, đảm bảo tính nhất quán và khả năng mở rộng trong quá trình phát triển.

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

<div id="bkmrk-%23%23%23-%C3%9D-ngh%C4%A9a-t%E1%BB%ABng-khu">  
Ý Nghĩa Từng thư mục  
<div>  
</div></div>## \* Root level

### `.mvn`, `mvnw`, `pom.xml`

 Project build bằng Maven

<div id="bkmrk-pom.xml-%E2%86%92-qu%E1%BA%A3n-l%C3%BD-de"><div>- `pom.xml` → quản lý dependency, plugin build WSO2
- `.mvn` → config Maven wrapper

---

</div></div>### `+ deployment/`

 Cấu hình runtime &amp; deploy

<div id="bkmrk-deployment.toml-%E2%86%92-co"><div>- `deployment.toml` → config server (port, datasource, kafka...)
- `docker/` → chạy container (nếu có)
- `libs/` → thêm JAR custom (Kafka client, connector...)

---

</div></div>### `+ docs/`

Tài liệu project (thiết kế, API spec...)

<div id="bkmrk--1"><div>---

</div></div>##  \* Source chính

### `+ src/main/java`

 Nếu có custom Java (hiện tại bạn chưa dùng)

<div id="bkmrk--2"><div>---

</div></div>### + `src/main/wso2mi`

Đây là toàn bộ logic integration

<div id="bkmrk--3"><div>---

</div></div># + artifacts/

<div id="bkmrk--4"><div>---

</div></div>## `+ apis/`

 API nhận request từ client

<div id="bkmrk-kafkaproducerapi.xml"><div>- `KafkaProducerApi.xml`  
    → API nhận request → đẩy vào Kafka (producer)
- `PlanningDirectApi.xml`  
    → API gọi trực tiếp backend (không qua Kafka)

---

</div></div>## `+ inbound-endpoints/`

Kafka Consumer (cực kỳ quan trọng)

<div id="bkmrk-load_balance_example"><div>- `Load_balance_example.xml`  
    → Lắng nghe Kafka topic  
    → Khi có message → trigger sequence xử lý

</div></div>Đây chính là chỗ **load balancing bằng Kafka**

<div id="bkmrk--5"><div>---

</div></div>## `+ sequences/`

 Logic xử lý nghiệp vụ

<div id="bkmrk-load_balance_example-1"><div>- `Load_balance_example-inboundSequence.xml`  
    → Xử lý message lấy từ Kafka  
    → gọi backend
- `Load_balance_example-inboundErrorSequence.xml`  
    → xử lý lỗi khi fail

---

</div></div>## `+ endpoints/`

 Định nghĩa backend service

Ví dụ:

<div id="bkmrk-http-endpoint-rest-a"><div>- HTTP endpoint
- REST API backend

---

</div></div>## `+ local-entries/`

Config dùng chung

<div id="bkmrk-kafkaconnection.xml%E2%86%92"><div>- `KafkaConnection.xml`  
    → cấu hình Kafka broker (host, port, topic...)

---

</div></div>## `+ message-stores/`

 Lưu message (queue trung gian)

 Dùng khi:

<div id="bkmrk-retry-%C4%91%E1%BA%A3m-b%E1%BA%A3o-kh%C3%B4ng-"><div>- retry
- đảm bảo không mất dữ liệu

---

</div></div>## `+ message-processors/`

 Xử lý message từ store

 Ví dụ:

<div id="bkmrk-retry-g%E1%BB%ADi-l%E1%BA%A1i-x%E1%BB%AD-l%C3%BD-"><div>- retry gửi lại
- xử lý batch

---

</div></div>## `+ proxy-services/`

 Proxy service (SOAP/HTTP)

 Thường dùng khi:

<div id="bkmrk-wrap-service-c%C5%A9-expo"><div>- wrap service cũ
- expose service trung gian

---

</div></div>## `+ data-services/`

 Kết nối database

 Tạo API CRUD trực tiếp DB

<div id="bkmrk--6"><div>---

</div></div>## `+ data-sources/`

 Cấu hình kết nối DB

<div id="bkmrk--7"><div>---

</div></div>## `+ tasks/`

 Job chạy định kỳ (cron job)

<div id="bkmrk--8"><div>---

</div></div>## `+ templates/`

 Template tái sử dụng

 Giúp:

<div id="bkmrk-tr%C3%A1nh-l%E1%BA%B7p-code-seque"><div>- tránh lặp code sequence / endpoint

---

</div></div># `+ resources/`

 Tài nguyên bổ trợ

<div id="bkmrk-conf%2F-%E2%86%92-config-runti"><div>- `conf/` → config runtime (properties)
- `connectors/` → Kafka connector JAR
- `api-definitions/` → Swagger/OpenAPI
- `metadata/` → metadata của artifact

  
</div>  
<div>  
</div></div>## 1.4. Quy định chính

### 1.4.1. Phân quyền quản lý artifact

<div id="bkmrk-khu-v%E1%BB%B1c-%C4%90%C6%A1n-v%E1%BB%8B-qu%E1%BA%A3n-"><div><div class="TyagGW_tableContainer"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)" data-end="860" data-start="202"><thead data-end="248" data-start="202"><tr data-end="248" data-start="202"><th class="" data-col-size="sm" data-end="212" data-start="202">Khu vực</th><th class="" data-col-size="sm" data-end="229" data-start="212">Đơn vị quản lý</th><th class="" data-col-size="sm" data-end="248" data-start="229">Quyền chỉnh sửa</th></tr></thead><tbody data-end="860" data-start="263"><tr data-end="330" data-start="263"><td data-col-size="sm" data-end="281" data-start="263">`deployment/**`</td><td data-col-size="sm" data-end="293" data-start="281">Core Team</td><td data-col-size="sm" data-end="330" data-start="293">Partner không được phép chỉnh sửa</td></tr><tr data-end="411" data-start="331"><td data-col-size="sm" data-end="362" data-start="331">`artifacts/local-entries/**`</td><td data-col-size="sm" data-end="374" data-start="362">Core Team</td><td data-col-size="sm" data-end="411" data-start="374">Partner không được phép chỉnh sửa</td></tr><tr data-end="483" data-start="412"><td data-col-size="sm" data-end="434" data-start="412">`resources/conf/**`</td><td data-col-size="sm" data-end="446" data-start="434">Core Team</td><td data-col-size="sm" data-end="483" data-start="446">Partner không được phép chỉnh sửa</td></tr><tr data-end="561" data-start="484"><td data-col-size="sm" data-end="512" data-start="484">`resources/connectors/**`</td><td data-col-size="sm" data-end="524" data-start="512">Core Team</td><td data-col-size="sm" data-end="561" data-start="524">Partner không được phép chỉnh sửa</td></tr><tr data-end="630" data-start="562"><td data-col-size="sm" data-end="584" data-start="562">`artifacts/apis/**`</td><td data-col-size="sm" data-end="606" data-start="584">Core Team + Partner</td><td data-col-size="sm" data-end="630" data-start="606">Được phép phát triển</td></tr><tr data-end="704" data-start="631"><td data-col-size="sm" data-end="658" data-start="631">`artifacts/sequences/**`</td><td data-col-size="sm" data-end="680" data-start="658">Core Team + Partner</td><td data-col-size="sm" data-end="704" data-start="680">Được phép phát triển</td></tr><tr data-end="786" data-start="705"><td data-col-size="sm" data-end="740" data-start="705">`artifacts/inbound-endpoints/**`</td><td data-col-size="sm" data-end="762" data-start="740">Core Team + Partner</td><td data-col-size="sm" data-end="786" data-start="762">Được phép phát triển</td></tr><tr data-end="860" data-start="787"><td data-col-size="sm" data-end="814" data-start="787">`artifacts/endpoints/**`</td><td data-col-size="sm" data-end="836" data-start="814">Core Team + Partner</td><td data-col-size="sm" data-end="860" data-start="836">Được phép phát triển</td></tr></tbody></table>

</div></div>---

</div></div>### 1.4.2. Quy định bắt buộc

Partner không được phép chỉnh sửa trực tiếp các khu vực sau:

<div id="bkmrk-deployment%2F%2A%2A-artifa"><div>- `deployment/**`
- `artifacts/local-entries/**`
- `resources/conf/**`
- `resources/connectors/**`

</div></div>Mọi thay đổi liên quan đến các khu vực trên phải tuân theo quy trình kiểm soát của Core Team, bao gồm:

<div id="bkmrk-t%E1%BA%A1o-y%C3%AAu-c%E1%BA%A7u-thay-%C4%91%E1%BB%95i"><div>1. Tạo yêu cầu thay đổi (Core Change Request)
2. Được Core Team xem xét và đánh giá
3. Được Core Team phê duyệt và thực hiện thay đổi

---

</div></div>## 1.5. Cách thực hiện / Quy trình

### 1.5.1. Quy trình thay đổi artifact dùng chung

**Bước 1:** Partner xác định nhu cầu thay đổi đối với các khu vực do Core Team quản lý.

**Bước 2:** Tạo ticket trên hệ thống quản lý công việc (Jira, Redmine hoặc YouTrack) với tiêu đề:

<div id="bkmrk-%5Bcore-change-request"><div><div class="relative w-full my-4"><div class=""><div class="relative"><div class="h-full min-h-0 min-w-0"><div class="h-full min-h-0 min-w-0"><div class="border corner-superellipse/1.1 border-token-border-light bg-token-bg-elevated-secondary rounded-3xl"><div class="corner-superellipse/1.1 rounded-3xl bg-token-bg-elevated-secondary"><div class="relative z-0 flex max-w-full"><div class="q9tKkq_viewer cm-editor z-10 light:cm-light dark:cm-light flex h-full w-full flex-col items-stretch ͼk ͼy" dir="ltr" id="bkmrk-%5Bcore-change-request-1"><div class="cm-scroller"><div class="cm-content q9tKkq_readonly">[CORE CHANGE REQUEST] &lt;Mô tả ngắn gọn thay đổi&gt;</div></div></div></div></div></div></div></div><div class=""><div class="">  
</div></div></div></div></div></div></div>**Ví dụ:**  
`[CORE CHANGE REQUEST] Thêm Kafka topic mới vào KafkaConnection local-entry`

<div id="bkmrk--9"><div>---

</div></div>### Luồng xử lý

<div id="bkmrk-partner-t%E1%BA%A1o-ticket-%E2%86%92"><div><div class="relative w-full my-4"><div class=""><div class="relative"><div class="h-full min-h-0 min-w-0"><div class="h-full min-h-0 min-w-0"><div class="border corner-superellipse/1.1 border-token-border-light bg-token-bg-elevated-secondary rounded-3xl"><div class="corner-superellipse/1.1 rounded-3xl bg-token-bg-elevated-secondary"><div class="relative z-0 flex max-w-full"><div class="q9tKkq_viewer cm-editor z-10 light:cm-light dark:cm-light flex h-full w-full flex-col items-stretch ͼk ͼy" dir="ltr" id="bkmrk-partner-t%E1%BA%A1o-ticket-%E2%86%92-1"><div class="cm-scroller"><div class="cm-content q9tKkq_readonly">Partner tạo ticket → Core Team review → Cập nhật trạng thái → Core thực hiện → Partner cập nhật code</div></div></div></div></div></div></div></div><div class=""><div class="">  
</div></div></div></div></div>---

</div></div>### Trạng thái ticket

<div id="bkmrk-tr%E1%BA%A1ng-th%C3%A1i-%C3%9D-ngh%C4%A9a-o"><div><div class="TyagGW_tableContainer"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)" data-end="2194" data-start="1902"><thead data-end="1926" data-start="1902"><tr data-end="1926" data-start="1902"><th class="" data-col-size="sm" data-end="1915" data-start="1902">Trạng thái</th><th class="" data-col-size="sm" data-end="1926" data-start="1915">Ý nghĩa</th></tr></thead><tbody data-end="2194" data-start="1937"><tr data-end="1969" data-start="1937"><td data-col-size="sm" data-end="1946" data-start="1937">`Open`</td><td data-col-size="sm" data-end="1969" data-start="1946">Ticket được tạo mới</td></tr><tr data-end="2014" data-start="1970"><td data-col-size="sm" data-end="1987" data-start="1970">`Under Review`</td><td data-col-size="sm" data-end="2014" data-start="1987">Core Team đang đánh giá</td></tr><tr data-end="2057" data-start="2015"><td data-col-size="sm" data-end="2028" data-start="2015">`Approved`</td><td data-col-size="sm" data-end="2057" data-start="2028">Được chấp thuận thực hiện</td></tr><tr data-end="2097" data-start="2058"><td data-col-size="sm" data-end="2071" data-start="2058">`Rejected`</td><td data-col-size="sm" data-end="2097" data-start="2071">Bị từ chối (kèm lý do)</td></tr><tr data-end="2150" data-start="2098"><td data-col-size="sm" data-end="2114" data-start="2098">`Implemented`</td><td data-col-size="sm" data-end="2150" data-start="2114">Core Team đã hoàn thành thay đổi</td></tr><tr data-end="2194" data-start="2151"><td data-col-size="sm" data-end="2162" data-start="2151">`Merged`</td><td data-col-size="sm" data-end="2194" data-start="2162">Đã merge vào nhánh `develop`</td></tr></tbody></table>

</div></div>---

</div></div>**Bước 3:** Core Team thực hiện đánh giá dựa trên các tiêu chí:

<div id="bkmrk-ph%E1%BA%A1m-vi-%E1%BA%A3nh-h%C6%B0%E1%BB%9Fng-%C4%91%E1%BA%BF"><div>- Phạm vi ảnh hưởng đến các luồng hiện tại
- Rủi ro liên quan đến cấu hình (ví dụ: Kafka, endpoint, connection)
- Tính cần thiết và mức độ ảnh hưởng đến hệ thống

---

</div></div>**Bước 4:** Nếu thay đổi được chấp thuận:

<div id="bkmrk-core-team-th%E1%BB%B1c-hi%E1%BB%87n-"><div>- Core Team thực hiện cập nhật
- Merge vào nhánh `develop`

---

</div></div>**Bước 5:** Partner cập nhật code mới và tiếp tục phát triển.

<div id="bkmrk--10"><div>---

</div></div>## 1.6. Ví dụ minh họa

### 1.6.1. Trường hợp hợp lệ

**Tình huống:** Bổ sung xử lý lỗi cho inbound sequence Kafka

<div id="bkmrk-artifacts%2Fsequences%2F"><div><div class="relative w-full my-4"><div class=""><div class="relative"><div class="h-full min-h-0 min-w-0"><div class="h-full min-h-0 min-w-0"><div class="border corner-superellipse/1.1 border-token-border-light bg-token-bg-elevated-secondary rounded-3xl"><div class="corner-superellipse/1.1 rounded-3xl bg-token-bg-elevated-secondary"><div class="relative z-0 flex max-w-full"><div class="q9tKkq_viewer cm-editor z-10 light:cm-light dark:cm-light flex h-full w-full flex-col items-stretch ͼk ͼy" dir="ltr" id="bkmrk-artifacts%2Fsequences%2F-1"><div class="cm-scroller"><div class="cm-content q9tKkq_readonly">artifacts/sequences/Load_balance_example-inboundSequence.xml  
artifacts/sequences/Load_balance_example-inboundErrorSequence.xml</div></div></div></div></div></div></div></div><div class=""><div class="">  
</div></div></div></div></div></div></div>→ Được phép chỉnh sửa trực tiếp và tạo Pull Request.

<div id="bkmrk--11"><div>---

</div></div>**Tình huống:** Thêm API mới để nhận dữ liệu

<div id="bkmrk-artifacts%2Fapis%2Fplann"><div><div class="relative w-full my-4"><div class=""><div class="relative"><div class="h-full min-h-0 min-w-0"><div class="h-full min-h-0 min-w-0"><div class="border corner-superellipse/1.1 border-token-border-light bg-token-bg-elevated-secondary rounded-3xl"><div class="corner-superellipse/1.1 rounded-3xl bg-token-bg-elevated-secondary"><div class="relative z-0 flex max-w-full"><div class="q9tKkq_viewer cm-editor z-10 light:cm-light dark:cm-light flex h-full w-full flex-col items-stretch ͼk ͼy" dir="ltr" id="bkmrk-artifacts%2Fapis%2Fplann-1"><div class="cm-scroller"><div class="cm-content q9tKkq_readonly">artifacts/apis/PlanningDirectApi.xml</div></div></div></div></div></div></div></div><div class=""><div class="">  
</div></div></div></div></div></div></div>→ Được phép tạo mới hoặc chỉnh sửa, sau đó tạo Pull Request để Core Team review.

<div id="bkmrk--12"><div>---

</div></div>### 1.6.2. Trường hợp không hợp lệ

**Tình huống:** Thêm Kafka topic vào cấu hình kết nối

<div id="bkmrk-artifacts%2Flocal-entr"><div><div class="relative w-full my-4"><div class=""><div class="relative"><div class="h-full min-h-0 min-w-0"><div class="h-full min-h-0 min-w-0"><div class="border corner-superellipse/1.1 border-token-border-light bg-token-bg-elevated-secondary rounded-3xl"><div class="corner-superellipse/1.1 rounded-3xl bg-token-bg-elevated-secondary"><div class="relative z-0 flex max-w-full"><div class="q9tKkq_viewer cm-editor z-10 light:cm-light dark:cm-light flex h-full w-full flex-col items-stretch ͼk ͼy" dir="ltr" id="bkmrk-artifacts%2Flocal-entr-1"><div class="cm-scroller"><div class="cm-content q9tKkq_readonly">artifacts/local-entries/KafkaConnection.xml</div></div></div></div></div></div></div></div><div class=""><div class="">  
</div></div></div></div></div></div></div>→ Không được phép chỉnh sửa trực tiếp.

Phải thực hiện theo quy trình:

<div id="bkmrk-t%E1%BA%A1o-ticket%3A%5Bcore-cha"><div>1. Tạo ticket:  
    `[CORE CHANGE REQUEST] Thêm topic planning_topic vào KafkaConnection`
2. Chờ Core Team phê duyệt
3. Core Team thực hiện thay đổi và merge

---

</div></div>**Tình huống:** Thay đổi cấu hình Kafka bootstrap server

<div id="bkmrk-deployment%2Fdeploymen"><div><div class="relative w-full my-4"><div class=""><div class="relative"><div class="h-full min-h-0 min-w-0"><div class="h-full min-h-0 min-w-0"><div class="border corner-superellipse/1.1 border-token-border-light bg-token-bg-elevated-secondary rounded-3xl"><div class="corner-superellipse/1.1 rounded-3xl bg-token-bg-elevated-secondary"><div class="relative z-0 flex max-w-full"><div class="q9tKkq_viewer cm-editor z-10 light:cm-light dark:cm-light flex h-full w-full flex-col items-stretch ͼk ͼy" dir="ltr" id="bkmrk-deployment%2Fdeploymen-1"><div class="cm-scroller"><div class="cm-content q9tKkq_readonly">deployment/deployment.toml  
resources/conf/config.properties</div></div></div></div></div></div></div></div><div class=""><div class="">  
</div></div></div></div></div></div></div>→ Không được phép chỉnh sửa trực tiếp. Phải tạo Core Change Request.

<div id="bkmrk--13"><div>---

</div></div>## 1.7. Checklist áp dụng

Trước khi commit hoặc tạo Pull Request, cần đảm bảo:

<div id="bkmrk-artifact-n%E1%BA%B1m-trong-c"><div>- [ ] Artifact nằm trong các thư mục được phép chỉnh sửa (`artifacts/apis/`, `artifacts/sequences/`, `artifacts/inbound-endpoints/`, `artifacts/endpoints/`)
- [ ] Không chỉnh sửa `artifacts/local-entries/**`
- [ ] Không chỉnh sửa `deployment/**`
- [ ] Không chỉnh sửa `resources/conf/**`
- [ ] Không chỉnh sửa `resources/connectors/**`
- [ ] Pull Request đã được Core Team review (nếu ảnh hưởng đến luồng chung)
- [ ] Đã kiểm thử luồng Kafka producer/consumer sau khi thay đổi (nếu có)

---

</div></div>*Tài liệu này thuộc phạm vi quản lý của Core Team. Mọi thay đổi nội dung phải được Core Team phê duyệt.*

<div id="bkmrk--14"><div>  
</div></div><div align="left" dir="ltr" id="bkmrk--15"></div>