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ý mã nguồn giữa Core Team và các đơn vị Partner nhằm:
-
Đảm bảo tính ổn định của hệ thống
-
Tránh xung đột mã nguồn giữa các đơn vị phát triển
-
Chuẩn hóa cách tổ chức code trong toàn dự án
-
Dễ dàng bảo trì, mở rộng và tích hợp 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 cấu trúc chuẩn của hệ thống
-
Core Team (đội phát triển lõi)
-
Partner Team (đối tác phát triển module)
Cấu trúc dự án chuẩn:
com.example.demo
├── common/ (thành phần dùng chung)
├── config/ (cấu hình hệ thống)
├── modules/ (các module nghiệp vụ)
└── DemoApplication.java
Ý nghĩa từng khu vực
|
Thư mục |
Vai trò |
Phạm vi sử dụng |
|
common |
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 |
1.3. Quy định chính
Phân quyền quản lý code
|
Khu vực |
Đơn vị quản lý |
Quyền chỉnh sửa |
|
common/** |
Core Team |
Partner không được sửa |
|
config/** |
Core Team |
Partner không được sửa |
|
modules/** |
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:
common/**
config/**
Mọi thay đổi trong các khu vực này phải:
-
Tạo yêu cầu thay đổi (Core Change Request)
-
Được Core Team xem xét
-
Core Team phê duyệt và thực hiện
1.4. Cách thực hiện / quy trình
Quy trình thay đổi code dùng chung
Bước 1: Partner phát hiện nhu cầu thay đổi
Bước 2: Tạo ticket với tiêu đề: các phần mềm quản lý công việc liên quan (Jira / Redmine / YouTrack) hoặc nội bộ
[CORE CHANGE REQUEST] Thêm field phone vào user_account
Luồng xử lý:
-
Partner tạo ticket
-
Core Team review
-
Chuyển trạng thái:
|
Trạng thái |
Ý nghĩa |
|
Open |
Ticket mới |
|
Under Review |
Core đang đánh giá |
|
Approved |
Đồng ý thay đổi |
|
Rejected |
Từ chối |
|
Implemented |
Core đã code |
|
Merged |
Đã merge vào develop |
Bước 3: Core Team đánh giá:
-
Phạm vi ảnh hưởng
-
Rủi ro hệ thống
-
Tính cần thiết
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ề và tiếp tục phát triển
1.5. Ví dụ minh họa
Trường hợp hợp lệ
Partner cần thêm logic trong module planning:
modules/planning/service/PlanningService.java
→ Được phép sửa trực tiếp và tạo PR.
Trường hợp không hợp lệ
Partner muốn sửa:
common/security/JwtAuthenticationFilter.java
→ Không được sửa trực tiếp.
Phải thực hiện:
-
Tạo Core Change Request
-
Chờ Core Team phê duyệt
-
Core Team thực hiện thay đổi
1.6. Checklist áp dụng
Trước khi commit hoặc tạo PR, cần kiểm tra:
-
Code nằm trong modules/**
-
Không sửa common/**
-
Không sửa config/**
-
PR đã được Core Team review (nếu cần)