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