Nhảy đến nội dung chính

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:

- Đả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
- Dễ dàng bảo trì, mở rộng và triển khai hệ thống

---

## 1.2. Khái Niệm / Phạm Vi Áp Dụng

Tài liệu áp dụng cho:

- Tất cả các dự án sử dụng nền tảng **WSO2 Micro Integrator (WSO2 MI)**
- **Core Team** (đội phát triển lõi — quản lý hạ tầng, kết nối, cấu hình)
- **Partner Team** (đối tác phát triển luồng nghiệp vụ)

### Cấu Trúc Dự Án Chuẩn

image.png



### Ý Nghĩa Từng Khu Vực


* Root level

.mvn, mvnw, pom.xml

 Project build bằng Maven

  • pom.xml → quản lý dependency, plugin build WSO2

  • .mvn → config Maven wrapper

+ deployment/

 Cấu hình runtime & deploy

  • deployment.toml → config server (port, datasource, kafka...)

  • docker/ → chạy container (nếu có)

  • libs/ → thêm JAR custom (Kafka client, connector...)

+ docs/

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

 * Source chính

+ src/main/java

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

+ src/main/wso2mi ⭐ (QUAN TRỌNG NHẤT)

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

+ artifacts/ (TRÁI TIM HỆ THỐNG)

+ apis/

 API nhận request từ client

  • 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)

+ inbound-endpoints/

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

  • Load_balance_example.xml
    → Lắng nghe Kafka topic
    → Khi có message → trigger sequence xử lý

Đây chính là chỗ load balancing bằng Kafka

+ sequences/

 Logic xử lý nghiệp vụ

  • 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

+ endpoints/

 Định nghĩa backend service

Ví dụ:

  • HTTP endpoint

  • REST API backend

+ local-entries/

Config dùng chung

  • KafkaConnection.xml
    → cấu hình Kafka broker (host, port, topic...)

+ message-stores/

 Lưu message (queue trung gian)

 Dùng khi:

  • retry

  • đảm bảo không mất dữ liệu

+ message-processors/

 Xử lý message từ store

 Ví dụ:

  • retry gửi lại

  • xử lý batch

+ proxy-services/

 Proxy service (SOAP/HTTP)

 Thường dùng khi:

  • wrap service cũ

  • expose service trung gian

+ data-services/

 Kết nối database

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

+ data-sources/

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

+ tasks/

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

+ templates/

👉 Template tái sử dụng

👉 Giúp:

  • tránh lặp code sequence / endpoint

+ resources/

👉 Tài nguyên bổ trợ

  • conf/ → config runtime (properties)

  • connectors/ → Kafka connector JAR

  • api-definitions/ → Swagger/OpenAPI

  • metadata/ → metadata của artifact



---

## 1.3. Quy Định Chính

### Phân Quyền Quản Lý Artifact

| Khu vực | Đơn vị quản lý | Quyền chỉnh sửa |
|---|---|---|
| `deployment/**` | Core Team | Partner **không** được sửa |
| `artifacts/local-entries/**` | Core Team | Partner **không** được sửa |
| `resources/conf/**` | Core Team | Partner **không** được sửa |
| `resources/connectors/**` | Core Team | Partner **không** được sửa |
| `artifacts/apis/**` | Core + Partner | Được phép phát triển |
| `artifacts/sequences/**` | Core + Partner | Được phép phát triển |
| `artifacts/inbound-endpoints/**` | Core + Partner | Được phép phát triển |
| `artifacts/endpoints/**` | Core + Partner | Được phép phát triển |

### Quy Định Bắt Buộc

> ⚠️ **Đối tác KHÔNG được phép sửa trực tiếp:**
> - `deployment/**`
> - `artifacts/local-entries/**`
> - `resources/conf/**`
> - `resources/connectors/**`

**Mọi thay đổi trong các khu vực trên phải:**

1. Tạo yêu cầu thay đổi (**Core Change Request**)
2. Được Core Team xem xét và đánh giá
3. Core Team phê duyệt và thực hiện thay đổi

---

## 1.4. Cách Thực Hiện / Quy Trình

### Quy Trình Thay Đổi Artifact Dùng Chung

**Bước 1:** Partner phát hiện nhu cầu thay đổi ở khu vực Core quản lý.

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

```
[CORE CHANGE REQUEST] <Mô tả ngắn gọn thay đổi>
```

> **Ví dụ:**
> `[CORE CHANGE REQUEST] Thêm Kafka topic mới vào KafkaConnection local-entry`

**Luồng xử lý:**

```
Partner tạo ticket → Core Team review → Cập nhật trạng thái → Core thực hiện → Partner pull code
```

**Bảng trạng thái ticket:**

| Trạng thái | Ý nghĩa |
|---|---|
| `Open` | Ticket mới tạo |
| `Under Review` | Core Team đang đánh giá |
| `Approved` | Đồng ý thực hiện thay đổi |
| `Rejected` | Từ chối (có lý do) |
| `Implemented` | Core Team đã hoàn thành code |
| `Merged` | Đã merge vào nhánh `develop` |

**Bước 3:** Core Team đánh giá:

- Phạm vi ảnh hưởng đến các luồng hiện có
- Rủi ro khi thay đổi cấu hình kết nối Kafka
- Tính cần thiết và tính ổn định của hệ thống

**Bước 4:** Nếu hợp lệ:

- Core Team thực hiện thay đổi
- Merge vào nhánh `develop`

**Bước 5:** Partner pull code mới và tiếp tục phát triển.

---

## 1.5. Ví Dụ Minh Họa

### ✅ Trường Hợp Hợp Lệ

**Tình huống:** Partner cần bổ sung xử lý lỗi cho inbound sequence Kafka:

```
artifacts/sequences/Load_balance_example-inboundSequence.xml
artifacts/sequences/Load_balance_example-inboundErrorSequence.xml
```

→ **Được phép** sửa trực tiếp và tạo Pull Request.

---

**Tình huống:** Partner cần thêm API endpoint mới để nhận dữ liệu:

```
artifacts/apis/PlanningDirectApi.xml
```

→ **Được phép** tạo file mới hoặc chỉnh sửa, sau đó tạo PR để Core review.

---

### ❌ Trường Hợp Không Hợp Lệ

**Tình huống:** Partner muốn thêm Kafka topic mới vào connection:

```
artifacts/local-entries/KafkaConnection.xml
```

→ **Không được** sửa trực tiếp.

Phải thực hiện:
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

---

**Tình huống:** Partner muốn thay đổi địa chỉ Kafka bootstrap server:

```
deployment/deployment.toml
resources/conf/config.properties
```

→ **Không được** sửa trực tiếp. Phải tạo Core Change Request.

---

## 1.6. Checklist Áp Dụng

Trước khi commit hoặc tạo PR(pull request), cần kiểm tra:

- [ ] Artifact nằm trong `artifacts/apis/`, `artifacts/sequences/`, `artifacts/inbound-endpoints/`, hoặc `artifacts/endpoints/`
- [ ] Không sửa `artifacts/local-entries/**`
- [ ] Không sửa `deployment/**`
- [ ] Không sửa `resources/conf/**`
- [ ] Không sửa `resources/connectors/**`
- [ ] PR đã được Core Team review (nếu thay đổi ảnh hưởng đến luồng chung)
- [ ] Đã test luồng Kafka producer/consumer sau thay đổi (nếu có)

---

*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.*
Lên đầu trang