5.Quy định về Database, Schema và Migration

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

Chương này quy định cách quản lý cấu trúc database và các thay đổi schema nhằm:

• Đảm bảo tính ổn định của dữ liệu hệ thống
  
  

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

• Đảm bảo khả năng triển khai tự động qua các môi trường
  
  

• Kiểm soát lịch sử thay đổi database

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ụ của module
  
  

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
  
  

• Core Team và Partner Team
  
  

• Mọi thay đổi liên quan đến:
  
  

Các loại thay đổi cần kiểm soát

• Thêm field mới
  

• Xóa field
  

• Sửa field
  

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

• Thay đổi quan hệ entity

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

5.7.3. Quy định chính

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

Các field chuẩn hệ thống:

• id
  
  

• created_at
  
  

• created_by
  
  

• updated_at
  
  

• updated_by
  
  

• deleted / status
  
  

• tenant_id (nếu có)
  
  

Quy định bắt buộc

Không được:

• Xóa field chuẩn
  
  

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

• Đổi tên field
  
  

• Thay đổi ý nghĩa nghiệp vụ của field
  
  

Các field 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êm field mới trong module

Partner chỉ được phép thêm field khi:

• Phục vụ nghiệp vụ của module
  
  

• Không trùng với dữ liệu core
  
  

• Không phá vỡ cấu trúc hiện tại
  
  

• Có migration script
  
  

• Có mô tả trong Pull Request
  
  

• Được Core Team review
  
  

---

5.7.3.3. Các thay đổi bắt buộc xin phép Core Team

Các thay đổi sau không được tự ý thực hiện:

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

• Xóa field
  
  

• Đổi tên field
  
  

• Thay đổi quan hệ entity
  
  

• Thêm field liên quan:
  
  

• user
  
  

• role
  
  

• permission
  
  

• tenant
  
  

• audit
  
  

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

Data Model Change Request

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

Trường hợp 1: Thêm field trong module

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

modules/<module>/entity/**

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

V<timestamp>__add_<field>_to_<table>.sql

Bước 3: Tạo Pull Request, trong PR phải có:

• Mô tả field mới
  
  

• Lý do nghiệp vụ
  
  

• Migration script
  
  

Bước 4: Core Team review:

• Không trùng core data
  
  

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

Bước 5: Merge vào develop

---

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

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:

• Entity bị ảnh hưởng
  
  

• Field thay đổi
  
  

• Kiểu dữ liệu cũ và mới
  
  

• Migration script
  
  

• Lý do thay đổi
  
  

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;

→ Được phép.

---

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

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:

• Xóa field status
  
  

• Đổi tên description → detail
  
  

• Thêm quan hệ với bảng user_account

5.7.6. Checklist áp dụng

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

• Có thay đổi field chuẩn không?
  
  

• Nếu có → phải tạo Data Model Change Request
  
  

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

• Nếu có → phải xin phép Core Team
  
  

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