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ý mã nguồnartifact giữa **Core TeamTeam** 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 mãcấu nguồnhình và artifact giữa các đơn vị phát triển

-

  • Chuẩn hóa cách tổ chức codeintegration artifact trong toàn dự án

    • -

  • Dễ dàng bảo trì, mở rộng và tíchtriển hợpkhai hệ thống


    • ---


    ## 1.2. Khái niệmNiệm / phạmPhạm viVi ápÁp dụng

    Dụng


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


    • -

      Tất cả các dự án sử dụng cấunền trúctảng chuẩn**WSO2 củaMicro hệIntegrator thống

      (WSO2
      • MI)**
  • -

    **Core TeamTeam** (đội phát triển lõi)

    lõi
    • —
  • quản

    lý hạ tầng, kết nối, cấu hình)

    • - **Partner TeamTeam** (đối tác phát triển module)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 trúchình dựruntime án& chuẩn: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

    com.example.demoVí 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 common/khi:

    (thành
    phần
    dùng
      chung)

    • retry

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

    + message-processors/

     Xử lý message từ store

     ├──Ví config/dụ:

    • retry gửi lại

    • xử lý batch

    + proxy-services/

     Proxy service (cấu hình hệ thống)SOAP/HTTP)

     ├──Thường modules/dùng khi:

    (các
    module
    nghiệp
      vụ)

    • wrap service cũ

    • expose service trung gian

    + data-services/

     Kết nối database

     └──Tạo DemoApplication.javaAPI CRUD trực tiếp DB


    Ý nghĩa từng khu vực

    +

    👉

    Giúp:

    data-sources/

    Thư👉 mụcCấu hình kết nối DB

    + tasks/

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

    + templates/

    Phạm👉 viTemplate tái sử dụng

    • commontránh lặp code sequence / endpoint

    Thành phần dùng chung toàn hệ thống

    Core quản lý

    config

    Cấu hình hệ thống, security, hạ tầng

    Core quản lý

    modules

    Các module nghiệp vụ

    Core + Partner

    + 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ínhChính


    ### Phân quyềnQuyền quảnQuản lýLý code

    Artifact

    | |||
    |---|---|---|
    |
    |||
    |
    |||
    |
    ||

    Khu vực

    Đơn vị quản lý

    Quyền chỉnh sửa

    common/`deployment/**

    `

    Core Team

    Partner không**không** được sửa

    config/`artifacts/local-entries/**

    `

    Core Team

    Partner không**không** được sửa

    modules/`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Định bắtBắt buộc

    Buộc


    > ⚠️ **Đối tác KHÔNG được phép sửa trực tiếp:

    common/**

    config/

    > - `deployment/**

    `

    > - `artifacts/local-entries/**`
    > - `resources/conf/**`
    > - `resources/connectors/**`

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

    **

    1. 1.

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

      Request**)
      2. 2.

    2. Được Core Team xem xét

      3. và
    3. đánh

      giá

      4. 3. 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

    Quy trìnhTrình thay
    đổi
    ### codeQuy dùngTrình chung

    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 vớitrên tiêuhệ đề: các phần mềmthống quản lý công việc liên quan (Jira / Redmine / YouTrack) hoặcvới nộitiêu bộ

    đề:


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

    > **Ví dụ:**
    > `[CORE CHANGE REQUEST] Thêm fieldKafka phonetopic mới vào user_account

    KafkaConnection

    local-entry`


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


      ```

    1. Partner tạo ticket

      2. →

    2. Core Team review

      3. →
    3. Cập

      Chuyểnnhật trạng thái:

      thái
      4. →
    Core thực hiện → Partner pull code
    ```

    **Bảng
    trạng||
    |---|---|
    |
    tạo|
    |
    ||
    |
    `Approved` |
    |
    `Rejected` (cólýdo)`Implemented`|
    |
    `Merged` `develop`
    thái

    ticket:**

    | Trạng thái

    Ý nghĩa
    `Open`

    Open

    |

    Ticket mới

    `Under Review

    Review`     		Core

    CoreTeam đang đánh giá
    |

    Approved

    Đồng ý thực hiện thay đổi
    |

    Rejected

    Từ chối
    |

    Implemented

    |
    		|

    Core Team đã hoàn thành code
    |

    Merged

    Đã merge vào develop

    nhánh
    |


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

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

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

    triển.


    ---

    ## 1.5. Ví dụDụ minhMinh họa

    Họa


    ### ✅ Trường hợpHợp hợpHợp lệ

    Lệ


    **Tình huống:** Partner cần thêmbổ logicsung trongxử modulelý planning:

    lỗi

    modules/planning/service/PlanningService.java

    cho

    inbound

    sequence Kafka:


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

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

    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ợpHợp khôngKhông hợpHợp lệLệ


    **Tình huống:** Partner muốn sửa:

    thêm

    common/security/JwtAuthenticationFilter.java

    Kafka

    topic

    mới vào connection:


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

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


    Phải thực hiện:

      1.

    1. Tạo Coreticket: Change`[CORE Request

      CHANGE
      2. REQUEST]
    2. Thêm

      topic planning_topic vào KafkaConnection`

      3. 2. Chờ Core Team phê duyệt

      3.

    3. Core Team thực hiện thay đổi

      4. 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Áp dụng

    Dụng


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


    ả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