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

6.Audit Log & System Metadata

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


Chương này quy định cách quản lý dữ liệu audit nhằm:

  • Đảm bảo khả năng truy vết toàn bộ hoạt động hệ thống

  • Phục vụ kiểm tra, giám sát và điều tra sự cố

  • Đáp ứng yêu cầu kiểm toán và tuân thủ

  • Bảo vệ dữ liệu hệ thống khỏi việc chỉnh sửa trái phép

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 định này áp dụng cho:

  • Tất cả module trong hệ thống

  • Core Team và Partner Team

Mọi thay đổi liên quan đến audit

6.3. Quy định chính


Partner không được phép:

  • Thay đổi cấu 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 log

Các bảng audit được coi là:

Core system data


Mọi thay đổi liên quan đến:

  • Cấu trúc bảng audit

  • Logic ghi log

  • Cơ chế lưu trữ audit

phải được:

Core Team phê duyệt

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


Trường hợp 1: Module cần ghi thêm audit

Bước 1: Sử dụng cơ chế audit có sẵn của hệ thống


Ví dụ:

  • AuditService

  • Annotation audit

  • Event audit

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:

auditService.logCreate("PLANNING", planningId, userId);


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

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

Partner tự tạo bảng:

CREATE TABLE planning_audit (

    id BIGINT,

    action VARCHAR(50)

);

→ Sai quy định vì:

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

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

Trường hợp bị cấm

Partner chạy trực tiếp:

DELETE FROM audit_log WHERE created_at < '2024-01-01';


→ Không được phép xóa dữ liệu audit.

6.6. Checklist áp dụng


Trước khi commit hoặc tạo PR:

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

    • 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 chuẩn của backend.

6.7.1. Vị trí ghi Audit

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

  • Service layer

  • Sau khi thao tác dữ liệu 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.

TraceId được:

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

  • lưu trong context request

  • truyền vào AuditService khi ghi log

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