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?