Nhảy đến nội dung chính

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?

Lên đầu trang