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__.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//entity/** Bước 2: Tạo migration script: V__.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] 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//entity/** Bước 2: Tạo migration script: V__add__to_.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] 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?