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?