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

6.Checklist kiểm tra trước khi merge

6.1. Mục tiêu chương


Chương này quy định cáchchecklist quảnbắt lýbuộc dữtrước liệukhi auditmerge code nhằm:

  • Đảm bảo khảchất nănglượng truycode vếttrước toànkhi bộtích hoạt động hệ thốnghợp

  • PhụcTránh vụvi kiểmphạm tra,các giámquy sátđịnh về kiến trúc và điềudữ tra sự cốliệu

  • ĐápGiảm ứngrủi yêuro cầulỗi kiểmkhi toánbuild vàhoặc tuântriển thủkhai

  • BảoChuẩn vệhóa dữquy liệutrình hệreview thốnggiữa khỏiCore việcTeam chỉnhvà sửa trái phépPartner

6.2. Khái niệm / phạm vi áp dụng


Audit log là dữ liệu ghi nhận:

  • Hành động của người dùng

  • Thay đổi dữ liệu quan trọng

  • Sự kiện hệ thống

  • Hoạt động bảo mật

Các bảng audit:

  • audit_log

  • action_history

  • system_event

Các bảng này được coi là dữ liệu core của hệ thống.

Quy địnhChecklist này áp dụng cho:

  • Tất cả modulePull trongRequest hệ thống(PR)

  • Core Team và Partner Team

  • Mọi module trong hệ thống

Checklist được dùng trong:

  • Code review

  • Kiểm tra trước khi merge vào develop

MọiKiểm thaytra đổitrước liênkhi quan đến auditrelease

6.3. Quy định chính


PartnerPull khôngRequest chỉ được phép merge khi đáp ứng đầy đủ các điều kiện sau:

Code nằm trong khu vực được phép:

modules/**

  1. Không sửa các khu vực bị cấm:


common/**

config/**

  1. Không sửa shared entity trong:


common/entity/**

  1. Nếu có thay đổi database:

    • ThayPhải đổicó cấumigration trúc bảng audit

    • Thêm hoặc xóa cột trong bảng audit

    • Xóa dữ liệu audit

    • Chỉnh sửa dữ liệu audit thủ công

    • Thay đổi logic ghi logscript

  2. CácAPI bảngphải auditđúng đượcchuẩn:

    coi
    3. là:

/api/v1/<module-name>

Core

system
    data

  1. Response phải dùng:

ApiResponse<T>


  • Cấu trúc bảng audit

  • Logic ghi log

  • Cơ chế lưu trữ audit

phải được:thành công

6.4. Cách thực hiện / quy trình


Quy

Trườngtrình hợpkiểm 1:tra Moduletrước cầnkhi ghi thêm auditmerge

Bước 1: SửDev dụnghoàn cơthành chếfeature audithoặc cófix sẵnbug
Bước của2: hệTạo thốngPull Request vào develop
Bước 3: Dev tự kiểm tra checklist
Bước 4: Core Team review theo checklist
Bước 5: Nếu đạt yêu cầu → merge


VíNếu dụ:không đạt:

  • AuditServicePR bị reject

  • AnnotationDev audit

    phải
    • sửa
  • lại

    Eventtheo audit

    checklist

Bước 2: Không được tự tạo bảng audit riêng

Bước 3: Nếu cần mở rộng dữ liệu audit:

Tạo ticket:

[AUDIT CHANGE REQUEST] <mô tả thay đổi>

Bước 4: Core Team review:

  • Xem xét nhu cầu

  • Đánh giá ảnh hưởng hệ thống

  • Quyết định phương án mở rộng

Trường hợp 2: Cần thay đổi cấu trúc bảng audit

Bước 1: Tạo ticket:

[DB CORE CHANGE REQUEST] Audit table change

Bước 2: Cung cấp thông tin:

  • Bảng audit bị ảnh hưởng

  • Field cần thêm/sửa

  • Lý do thay đổi

  • Migration script

Bước 3: Core Team review và quyết định

6.5. Ví dụ minh họa

Trường hợp hợp lệ

Module planning muốn ghi log khi tạo kế hoạch:PR:

auditService.logCreate("PLANNING",Chỉ planningId,sửa userId);code trong:

modules/planning/**

  • Có migration: V20260210__add_priority_to_planning.sql
  • API: /api/v1/planning

  • Build thành công

→ SửĐược dụng cơ chế audit có sẵn → hợp lệ.merge.

Trường hợp không hợp lệ

Partner tự tạo bảng:PR:

CREATESửa TABLE planning_audit (file:

common/entity/UserEntity.java

    id

    • BIGINT,

→ actionVi VARCHAR(50)

phạm

);quy định shared entity.

→ SaiPR quybị địnhtừ vì:chối.

  • Tự tạo bảng audit riêng

  • Không dùng hệ thống audit chung

Trường hợp bị cấmtừ chối do thiếu migration

Partner chạy trực tiếp:PR:

DELETEThêm FROMfield audit_logtrong WHEREentity:

private created_atInteger < '2024-01-01';priority;


  • Không có migration SQL

→ KhôngPR đượcbị phép xóa dữ liệu audit.reject.

6.6. Checklist áp dụng


TrướcDev phải tick đủ các mục sau trước khi commit hoặc tạo PR:merge:

    [

  • ] Code nằm trong modules/**

    [ ] Không sửa common/**

    [ ] Không sửa config/**

    [ ] Không sửa shared entity

    [ ] Có migration nếu thay đổi bảng audit không?

    DB

    • [

      ]
    • API

      Nếu có → phải xin Core Team

  • Có xóa dữ liệu audit không?

    • Nếu có → không được phép

  • Có tự tạo bảng audit riêng không?

    • Nếu có → phải chuyển sang audit chung

  • Có thay đổi logic audit không?

    • Nếu có → phải tạo Audit Change Request

6.7. Kiến trúc và cơ chế ghi Audit chuẩn

Để đảm bảo tính thống nhất và khả năng truy vết hệ thống, việc ghi Audit Log phải tuân thủ kiến trúcđúng chuẩn của backend./api/v1/

6.7.1.

[ Vị] tríResponse ghidùng Audit

ApiResponse

Audit[ Log] phải được ghi tại:

  • Service layer

  • Sau khi thao tác dữ liệuBuild thành công

  • Trong transaction nghiệp vụ

Không được ghi Audit tại:

  • Controller

  • Repository

  • Frontend

  • SQL trigger tự tạo

6.7.2. Sử dụng AuditService chuẩn

Tất cả module phải ghi Audit thông qua cơ chế chuẩn của hệ thống, ví dụ:


auditService.logCreate(module, objectId, userId); auditService.logUpdate(module, objectId, oldValue, newValue); auditService.logDelete(module, objectId, userId);

Không được:

  • Ghi trực tiếp DB audit

  • Tự dùng repository audit

  • Ghi log bằng logger thay cho audit

6.7.3. Nội dung bản ghi Audit chuẩn

Mỗi bản ghi Audit nên chứa tối thiểu các thông tin:

  • action (CREATE / UPDATE / DELETE / LOGIN / APPROVE…)

  • module (USER / PLANNING / DOCUMENT…)

  • objectId

  • objectType

  • username / userId

  • timestamp

  • oldValue

  • newValue

  • ipAddress

  • traceId

Thông tin này phục vụ:

  • truy vết thay đổi dữ liệu

  • điều tra sự cố

  • kiểm toán hệ thống

6.8. TraceId trong Audit Log

Mỗi Audit Log phải liên kết với request thông qua traceId.

TraceIdCore được:

Team
    chỉ

  • sinh tại filter/interceptor của backend

  • lưu trong context request

  • truyền vào AuditServicemerge khi ghichecklist log

    đạt
    • đầy

Mục đích:

  • liên kết audit với log hệ thống

  • truy vết API gây thay đổi dữ liệu

  • phục vụ điều tra production

6.9. Nguyên tắc ghi Audit trong Transaction

Audit Log phải được ghi cùng transaction với dữ liệu nghiệp vụ:

  • Nếu transaction nghiệp vụ rollback → audit không được ghi

  • Nếu thao tác dữ liệu thành công → audit phải tồn tại

Không được:

  • ghi audit trước khi lưu dữ liệu

  • ghi audit ngoài transaction

  • ghi audit async tách rời nghiệp vụ

6.10. Quy định bảo mật dữ liệu Audit

Dữ liệu Audit được coi là dữ liệu nhạy cảm và phải bảo vệ:đủ.

Không được lưu trong audit:

  • password

  • token

  • secret

  • private key

  • dữ liệu cá nhân đầy đủ

  • file nhạy cảm

Nếu cần ghi dữ liệu nhạy cảm → phải mask hoặc hash.

Ví dụ:


email: t***@gmail.com phone: 09****123 token: *****

6.11. Nguyên tắc bắt buộc bổ sung

Ngoài các quy định ở trên, hệ thống yêu cầu:

  • Audit phải ghi tại Service layer

  • Audit phải qua AuditService chuẩn

  • Audit phải nằm trong transaction

  • Audit phải có traceId

  • Không ghi audit trực tiếp DB

  • Không ghi audit bằng logger

Vi phạm các nguyên tắc này được xem là vi phạm kiến trúc hệ thống.

Lên đầu trang