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

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


##

1.1. Mục Tiêutiêu Chương
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**Team và các đơn vị **Partner**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

    Tăng khả năng bảo trì, mở rộng và triển khai hệ thống


    • ---

    ##

    1.2. Khái Niệmniệm /và Phạmphạm Vivi Ápáp Dụng

    dụng

    Tài liệu này được á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**Team: (độiĐội phát triển lõilõi, —chịu trách nhiệm quản lý hạ tầng, kết nối, cấu hình)

    hình
    -hệ **thống và các thành phần dùng chung

  • Partner Team**Team: (Các đơn vị đối táctác, chịu trách nhiệm phát triển các luồng nghiệp vụ)vụ cụ thể


    • ###

    1.3. Cấu Trúctrúc Dựdự Ánán Chuẩ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



    ### Ý Nghĩa Từng Khuthư Vực
    mụ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định Chính

    chính
    ###

    1.3.1. Phân Quyềnquyền Quảnquản Lýlý Artifact


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

    ###

    1.3.2. Quy Địnhđịnh Bắtbắt Buộc

    buộc

    Partner

    > ⚠️ **Đối tác KHÔNGkhông được phép chỉnh sửa trực tiếp:**
    tiếp các khu vực sau:

    > -
    `

    • deployment/**`

    > -
  • `

    artifacts/local-entries/**`

    • > -
  • `

    resources/conf/**`

    • > -
  • `

    resources/connectors/**`


    • **

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

    phải
    tuân theo quy trình kiểm soát của Core Team, bao gồm:

    1.

    1. Tạo yêu cầu thay đổi (**Core Change Request**)

    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


    • ---

    ##

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

    trình
    ###

    1.4.1. Quy Trìnhtrình Thaythay Đổiđổi Artifactartifact Dùngdùng Chung

    chung
    **

    Bước 1:** Partner phátxác hiệnđị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 /Jira, Redmine /hoặc 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`entry


    **

    Luồng xử lý:**


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

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


    |

    Trạng thái |ticket

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

    **

    Bước 3:** Core Team thực hiện đánh giá:

    giá
    dựa trên các tiêu chí:

    -

    • Phạm vi ảnh hưởng đến các luồng hiện có

    tại

    -

  • Rủi ro khiliên thayquan đổiđến cấu hình kết(ví nốidụ: Kafka

    • Kafka,
    -endpoint, connection)

  • Tính cần thiết và tínhmức ổnđộ địnhảnh củahưởng đến hệ thống


    • **

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

    đổi
    được chấp thuận:

    -

    • Core Team thực hiện thaycập đổi

    nhật

    -

  • Merge vào nhánh `develop`develop


    • **

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


    ---

    ##

    1.5. Ví Dụdụ Minhminh Họa

    họa
    ### ✅

    1.5.1. Trường Hợphợp Hợphợp Lệ

    lệ
    **

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


    Kafka

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

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


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


    ---

    **

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


    liệu

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


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


    ---

    ### ❌

    1.5.2. Trường Hợphợp Khôngkhông Hợphợp Lệ

    lệ
    **

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

    cấu
    hình kết nối

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


    → **Không được**được phép chỉnh sửa trực tiếp.


    Phải thực hiện:

    hiện theo quy trình:

    1.

    1. Tạo ticket: `
      [CORE CHANGE REQUEST] Thêm topic planning_topic vào KafkaConnection`

    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 thayThay đổi địacấu chỉhình Kafka bootstrap server:


    server

    ```
    deployment/deployment.toml

    resources/conf/config.properties
    ```


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


    ---

    ##

    1.6. Checklist Ápáp Dụng

    dụng

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


    bảo:

    - [
    ]

    • Artifact nằm trong `các thư mục được phép chỉnh sửa (artifacts/apis/`, `artifacts/sequences/`, `artifacts/inbound-endpoints/`, hoặc `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/**`

    • - [
  • ]

    PRPull Request đã được Core Team review (nếu thay đổi ảnh hưởng đến luồng chung)

    • - [
  • ]

    Đã testkiểm thử luồng Kafka producer/consumer sau khi thay đổi (nếu có)


    • ---

    *

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


    Lên đầu trang