5.Git Workflow & Pull Request

5.1. Mục tiêu chương

Chương này quy định cáchchuẩn quản lý cấu trúc databasecommit và cácquy thaytrình đổimerge schemacode nhằm:

• Đảm bảo tínhlịch ổnsử địnhthay củađổi dữrõ liệuràng, hệdễ thốngtruy vết
  
  

• TránhGiảm xung đột schema giữa các module và các đơn vịnhóm phát triển
  
  

• Đảm bảo khảchất nănglượng triểncode khaitrước tựkhi độngđưa quavào cácnhánh môi trườngchính
  
  

• KiểmChuẩn soáthóa lịchquy sửtrình thayphát đổitriển databasegiữa Core Team và Partner

5.2. Khái niệm / phạm vi áp dụng

Quy định này áp dụng cho:

• Toàn bộ database của hệ thống
  
  

• Core Team và Partner Team
  
  

• Tất cả các thay đổi liên quan đến:
  
  

• Bảng dữ liệu
  
  

• Cột dữ liệu
  
  

• Constraint
  
  

• Index
  
  

• Trigger
  
  

Hệ thống phân loại bảng dữ liệu thành hai nhóm:

---

1. Core tables (dùng chung toàn hệ thống)

Bao gồm các bảng:

• app_user
  
  

• theme_config
  
  

• feature_management
  
  

Đây là các bảng dữ liệu lõi, được dùng chung cho:

• Xác thực
  
  

• Phân quyền
  
  

• Cấu hình hệ thống
  
  

---

2. Module tables

Bao gồm:

• Các bảng thuộc từng module riêng
  
  

• Nằm trong phạm vi nghiệp vụrepository của module
  
  

  dự

Ví dụ:

• planning
  
  

• document
  
  

• task
  
  

• notification
  

5.3. Quy định chính

5.3.1. Quy định với Core tables

Partner không được phép:

• Thay đổi cấu trúc bảng
  
  

• Thêm cột
  
  

• Xóa cột
  
  

• Đổi kiểu dữ liệu
  
  

• Sửa constraint
  
  

• Sửa index
  
  

• Sửa trigger
  
  

Mọi thay đổi liên quan đến core tables phải thông qua:

DB Core Change Request -> sử dụng jira/… hoặc các phần mềm quản lý công việc nội bộ

Và do Core Team thực hiện.

---

5.3.2. Quy định với Module tables

Partner được phép:

• Tạo bảng mới cho module
  
  

• Thêm cột
  
  

• Sửa cấu trúc bảng module
  
  

Nhưng phải tuân thủ:

• Không ảnh hưởng core tables
  
  

• Có migration script
  
  

• Có mô tả rõ trong Pull Request
  
  

• Được Core Team review
  
  

---

5.3.3. Migration bắt buộc

Mọi thay đổi database phải tuân thủ các nguyên tắc sau:

• Không sửa trực tiếp database production
  
  

• Không chỉnh sửa thủ công trên DB staging
  
  

• Tất cả thay đổi phải qua migration script
  
  

• Migration phải được commit vào source code
  
  

Công cụ sử dụng:

• Flyway hoặc Liquibase
  
  

---

Format migration

Tên file migration:

V<timestamp>__<description>.sql

Ví dụ:

V20260209__create_planning_table.sql

V20260210__add_priority_to_planning.sql

5.4. Cách thực hiện / quy trình

Trường hợp 1: Thêm hoặc sửa bảng trong module

Bước 1: Cập nhật entity trong:

modules/<module>/entity/**

Bước 2: Tạo migration script:

V<timestamp>__<description>.sql

Bước 3: Commit:

• Entity
  
  

• Migration script
  
  

Bước 4: Tạo Pull Request

Bước 5: Core Team review:

• Migration hợp lệ
  
  

• Không ảnh hưởng core tables
  
  

Bước 6: Merge vào develop

---

Trường hợp 2: Thay đổi core tables

Bước 1: Tạo ticket:

[DB CORE CHANGE REQUEST] <mô tả thay đổi>

Bước 2: Cung cấp thông tin:

• Bảng bị ảnh hưởng
  
  

• Cột thay đổi
  
  

• Kiểu dữ liệu
  
  

• Migration script đề xuất
  
  

• Lý do thay đổi
  
  

Bước 3: Core Team review

Bước 4: Nếu được duyệt:

• Core Team thực hiện migration
  
  

Merge vào develop

5.5. Ví dụ minh họa

Trường hợp hợp lệ

Partner thêm bảng mới:

CREATE TABLE PLANNING (

    ID BIGINT PRIMARY KEY,

    NAME VARCHAR(255),

    DESCRIPTION VARCHAR(1000)

);

→ Thuộc module table → được phép.

---

Trường hợp không hợp lệ

Partner chạy trực tiếp trên production:

ALTER TABLE USER_ACCOUNT ADD PHONE VARCHAR(20);

→ Sai quy định vì:

• Sửa core table
  
  

• Sửa trực tiếp DB production
  
  

• Không có migration
  
  

---

Trường hợp cần xin phép

Partner muốn:

ALTER TABLE ROLE ADD DESCRIPTION VARCHAR(255);

→ Đây là core table.

Phải tạo: trên phần mềm quản lý công việc nội bộ hoặc phần mềm nghiệp vụ tương đương

[DB CORE CHANGE REQUEST]

5.6. Checklist áp dụng

Trước khi commit hoặc tạo PR:

• Có thay đổi database không?
  
  

• Nếu có → phải có migration script
  
  

• Có sửa core table không?
  
  

• Nếu có → phải tạo DB Core Change Request
  
  

• Migration có đúng format tên file không?
  
  

• Không sửa trực tiếp DB production
  
  

• Migration đã được commit vào source code

5.7. Quy định thay đổi cấu trúc dữ liệu (Entity & Database)

5.7.1. Mục tiêu chương

Chương này quy định cách kiểm soát các thay đổi liên quan đến cấu trúc dữ liệu nhằm:

• Tránh mất dữ liệu hoặc lỗi hệ thống
  
  

• Đảm bảo tương thích giữa các module
  
  

• Ngăn xung đột schema khi nhiều đơn vị cùng phát triển
  
  

• Bảo vệ các field và bảng dữ liệu chuẩn của hệ thống

4.7.2. Khái niệm / phạm vi áp dụng

Quy định này áp dụng cho:

• Tất cả các entity trong hệ thống
  
  

• Tất cả các bảng databaseán
  
  

• Core Team và Partner Team
  
  

• Mọi thaycommit đổivà liênPull quanRequest đến:(PR)
  
  

Các

Quy loạitrình thayphát đổitriển cầntuân kiểm soát

theo:

• ThêmChuẩn fieldformat mớicommit
  
  

• XóaChiến field
  

  lược

• Sửa field
  

• Đổi kiểu dữ liệu
  

• Thay đổi quan hệ entity

• Thêm/xóa bảng databasebranch
  
  

Điều kiện merge bắt buộc

5.7.3. Quy định chính

5.7.3.1. KhôngFormat được tự ý thay đổi các field chuẩncommit

CácTất fieldcả chuẩncommit hệphải thống:theo format:

<type>: <description>

Trong đó:

• id<type>: loại thay đổi
  
  

• created_at
  
  

  <description>:
mô
• tả

  created_by
  
  

  ngắn
gọn
• nội

  updated_at
  
  

  dung
thay

• updated_by
  
  

• deleted / status
  
  

• tenant_id (nếu có)
  đổi
  

Quy

Ví địnhdụ bắtcommit buộc

hợp lệ

Khôngfeat: được:add planning API

fix:

• validate file upload

  Xóarefactor: fieldoptimize chuẩn
  
  planning service

docs:

• update API guideline

  Đổitest: kiểuadd dữunit test for planning service

  chore: update dependency versions

  ---

  Type hợp lệ

  Các

  field

  Type	Ý nghĩa
  feat	Thêm chức năng mới
  fix	Sửa lỗi
  refactor	Tối ưu, không đổi logic
  docs	Cập nhật tài liệu
  Đổi tên field test	Thêm hoặc sửa test
  chore	Thay đổi ýcấu nghĩahình, nghiệpbuild, vụ của field dependency

  này được coi là system fields và được dùng chung cho:

  • Audit
    
    

  • Logging
    
    

  • Multi-tenant
    
    

  • Phân quyền
    
    

  • Tích hợp hệ thống
    
    

  ---

  5.7.3.2. ThêmBranch field mới trong modulestrategy

  PartnerHệ chỉthống đượcsử phépdụng thêmmô fieldhình khi:branch chuẩn:

  Branch	Mục đích
  main	Bản stable, dùng cho production
  develop	Bản tích hợp, nơi merge các feature
  feature/*	Phát triển chức năng mới
  fix/*	Sửa lỗi

  ---

  Quy tắc làm việc với branch

  • PhụcKhông vụcommit nghiệptrực vụtiếp củavào modulemain
    
    

  • Không trùngcommit vớitrực dữtiếp liệuvào coredevelop
    
    

  • KhôngMọi pháthay vỡđổi cấuphải trúc hiện tại
    
    

  • Có migration script
    
    

  • Có mô tả trongqua Pull Request
    
    

  • ĐượcBranch Corephải Teamđược reviewđặt tên đúng quy tắc
    
    

  ---

  Ví dụ tên branch hợp lệ

  feature/planning-create-api

  feature/document-upload

  fix/login-null-pointer

  fix/planning-date-validation

  ---

  5.7.3.3. CácĐiều thaykiện đổimerge bắtPull buộc xin phép Core Team

  Request

  CácPull thayRequest đổi sau khôngchỉ được tựmerge ýkhi thựcđáp hiện:ứng đầy đủ các điều kiện:

  1. ĐổiBuild kiểuthành dữ liệu fieldcông
     
     

  XóaKhông fieldsửa:
  
  common/**

  config/**

  2. ĐổiKhông tênsửa field
     
     

  3. Thay đổi quan hệshared entity
     
     

  ThêmCó fieldreview liêntừ quan:
  
  

  Core

  • user
    
    

  • role
    
    

  • permission
    
    

  • tenant
    
    

  • audit
    
    

  Tất cả các trường hợp trên phải qua:

  Data Model Change Request

  Team

  5.7.4. Cách thực hiện / quy trình

  
  

  TrườngQuy hợptrình 1:phát Thêmtriển fieldtính trong modulenăng

  Bước 1: CậpTạo nhậtbranch entitytừ trong:develop

  modules/<module>/entity/**git checkout develop

  git pull

  git checkout -b feature/planning-create-api

  
  

  Bước 2: TạoThực migrationhiện script:commit theo chuẩn

  V<timestamp>__add_<field>_to_<table>.sqlgit commit -m "feat: add planning create API"

  
  

  Bước 3: Push branch lên remote

  git push origin feature/planning-create-api

  
  

  Bước 4: Tạo Pull Request vào develop

  Bước 5: Core Team review

  Bước 6: Nếu đạt yêu cầu → merge vào develop

  ---

  Quy trình sửa lỗi

  Bước 1: Tạo branch fix

  git checkout develop

  git checkout -b fix/planning-null-error

  
  

  Bước 2: Commit

  git commit -m "fix: handle null planning name"

  
  

  Bước 3: Tạo Pull Request, trong PR phảivà có:chờ review

  5.5.

  Ví dụ minh họa

  Trường hợp commit sai

  Mô tả field mới
  
  

  Sai

  • Lý do nghiệp vụ
    
    

  • Migration script
    
    

  Bước 4: Core Team review:vì:

  • Không trùngtheo coreformat datachuẩn
    
    

  • Không phácó vỡ hệ thốngtype
    
    

  ---

  BướcTrường 5:hợp Mergecommit vàođúng

  develop

  fix: handle null planning name

  

  ---

  Trường hợp 2:merge Thay đổi field hoặc quan hệ entitysai

  Bước 1: Tạo ticket: các phần mềm quản lý công việc liên quan (Jira / Redmine / YouTrack) hoặc nội bộ

  [DATA MODEL CHANGE REQUEST] <mô tả thay đổi>

  

  Bước 2: Cung cấp thông tin:Partner:

  • EntityCommit bịtrực ảnhtiếp hưởngvào develop
    
    

  • FieldKhông thaytạo đổiPR
    
    

  • KiểuKhông dữcó liệu cũ và mới
    
    

  • Migration script
    
    

  • Lý do thay đổireview
    
    

  Bước 3: Core Team review:

  • Đánh giá ảnh hưởng hệ thống
    
    

  • Kiểm tra backward compatibility
    
    

  Bước 4: Nếu được duyệt:

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

  • Merge vào develop

  5.7.5. Ví dụ minh họa

  
  

  Trường hợp hợp lệ

  Partner thêm field vào entity module:

  @Column(name = "PRIORITY")

  private Integer priority;

  
  

  Và có migration:

  ALTER TABLE PLANNING ADD PRIORITY INT;

  
  

  → ĐượcVi phép.phạm quy trình.

  ---

  Trường hợp khôngmerge hợp lệđúng

  Partner sửa:

  @Column(name = "CREATED_AT")

  private String createdAt;

  
  

  → Đổi kiểu dữ liệu từ timestamp sang string.

  → Không được phép.

  Phải tạo:

  [DATA MODEL CHANGE REQUEST]

  
  

  ---

  Trường hợp cần xin phép

  Partner muốn:

  1. XóaTạo fieldbranch statusfeature/planning-api
     
     

  2. ĐổiCommit têntheo description → detailchuẩn
     
     

  3. ThêmTạo quanPR hệvào với bảng user_accountdevelop
     
     

• Core Team review
  
  

• Build pass
  
  

• Merge



5.7.6. Checklist áp dụng




Trước khi commit hoặc tạo PR:Pull Request:

• CóCommit thayđúng đổiformat field<type>: chuẩn<description>
  
  

  không?

• Branch đúng quy tắc feature/* hoặc fix/*
  
  

• Không commit trực tiếp vào main hoặc develop
  
  

• Build thành công
  
  

• Không sửa:
  
  

• Nếucommon/**
  
  

  có
→
• phải

  config/**
  
  

  tạo
Data
• Model

  shared Change Requestentity
  
  

• CóPR đổiđã kiểu dữ liệu field không?
  
  

• Nếu có → phải xin phépđược Core Team
  
   review

• Có migration script chưa?
  
  

• Field mới có trùng dữ liệu core không?
  
  

• PR đã mô tả rõ thay đổi chưa?