# 4. Quy định thay đổi cấu trúc dữ liệu (Entity & Database)
### 4.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.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
### 4.3. Quy định chính
#### 4.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
---
#### 4.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
---
#### 4.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
### 4.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
### 4.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
### 4.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?