5s.data.model.standard

✅ Checklist Tiêu Chuẩn 5★ cho File data-model.md (Mô hình Dữ liệu Service)

Một file data-model.md được đánh giá 5 sao cần đảm bảo các yếu tố sau, giúp đội ngũ phát triển, DBA, và kiến trúc sư có cái nhìn rõ ràng và chính xác nhất về cấu trúc dữ liệu của service:

1. 🎯 Giới thiệu và Phạm vi Rõ ràng (Clear Introduction & Scope):

• Mục đích của Service và Vai trò Mô hình Dữ liệu: Giới thiệu ngắn gọn về service và tầm quan trọng của mô hình dữ liệu này trong service đó.
• Phạm vi Dữ liệu Quản lý: Xác định rõ các thực thể/loại dữ liệu chính mà service này chịu trách nhiệm quản lý.
• Ngoài phạm vi (Out of Scope): Nêu rõ những thực thể/loại dữ liệu mà service này không quản lý hoặc không chịu trách nhiệm (nếu cần thiết để tránh nhầm lẫn).

2. 🗺️ Sơ đồ ERD Trực quan và Chính xác (Accurate & Visual ERD):

• Sơ đồ ERD (Entity Relationship Diagram): Cung cấp một sơ đồ ERD trực quan (ví dụ: sử dụng Mermaid, dbdiagram.io, hoặc công cụ khác) thể hiện tất cả các bảng chính và mối quan hệ giữa chúng (one-to-one, one-to-many, many-to-many).
• Tính Chính xác của Sơ đồ: Sơ đồ ERD phải phản ánh đúng cấu trúc bảng và các mối quan hệ được mô tả chi tiết bên dưới.
• Ghi chú cho Sơ đồ (nếu cần): Giải thích các quy ước hoặc điểm đặc biệt trong sơ đồ (ví dụ: cách thể hiện kiểu dữ liệu mảng, JSONB trong Mermaid).

3. 🧱 Chi tiết Từng Bảng/Thực thể (Detailed Table/Entity Specification):

• Cho mỗi bảng/thực thể:
  • Tên bảng (Table Name): Rõ ràng và tuân thủ quy ước đặt tên.
  • Mục đích (Purpose): Mô tả ngắn gọn vai trò và ý nghĩa của bảng.
  • Câu lệnh CREATE TABLE (ví dụ): Cung cấp ví dụ câu lệnh SQL CREATE TABLE (hoặc định nghĩa tương đương cho NoSQL) để thể hiện rõ cấu trúc.
  • Mô tả Chi tiết Từng Cột (Column Details):
    • Tên cột (Column Name): Tuân thủ quy ước.
    • Kiểu dữ liệu (Data Type): Chính xác và phù hợp (ví dụ: UUID, TEXT, VARCHAR(255), INTEGER, BOOLEAN, TIMESTAMPTZ, JSONB, ENUM, TEXT[]).
    • Khóa chính (Primary Key - PK): Đánh dấu rõ.
    • Khóa ngoại (Foreign Key - FK): Nêu rõ tham chiếu đến bảng và cột nào.
    • Ràng buộc (Constraints): NOT NULL, UNIQUE, CHECK (ví dụ: giá trị ENUM hợp lệ).
    • Giá trị mặc định (Default Value): Nếu có.
    • Mô tả (Description): Giải thích ý nghĩa nghiệp vụ của cột.
  • Chỉ mục (Indexes): Liệt kê các chỉ mục quan trọng (ngoài PK, FK) và lý do tạo (ví dụ: tối ưu query thường xuyên, đảm bảo unique).
  • Mối liên hệ và Sử dụng (Relationships & Usage): Mô tả ngắn gọn cách bảng này liên kết với các bảng khác và được sử dụng trong các luồng nghiệp vụ chính của service.

4. 🔗 Quản lý Mối Quan Hệ và Tính Toàn Vẹn Dữ liệu (Relationship Management & Data Integrity):

• Mô tả rõ các mối quan hệ chính: Giải thích logic nghiệp vụ đằng sau các mối quan hệ one-to-many, many-to-many.
• Chính sách Cascade (nếu có): Nêu rõ hành vi ON DELETE hoặc ON UPDATE cho các khóa ngoại (ví dụ: CASCADE, SET NULL, RESTRICT).
• Tính toàn vẹn tham chiếu: Đảm bảo các khóa ngoại được định nghĩa đúng và logic.

5. 🔄 Đồng Bộ Dữ Liệu và Sự Kiện (Data Synchronization & Events - nếu có):

• Sự kiện liên quan đến dữ liệu: Nếu việc thay đổi dữ liệu trong các bảng này phát ra sự kiện (để các service khác consume), cần mô tả tên sự kiện và mục đích.
• Dữ liệu được đồng bộ từ nguồn khác: Nếu một số bảng/trường là bản sao hoặc được đồng bộ từ service khác (như UserLocal trong user-service/sub), cần ghi rõ nguồn và cơ chế đồng bộ.

6. 📄 Thông Tin Bổ Sung và Quản Trị (Supplementary Information & Governance):

• Phụ lục về ENUMs và Giá trị Đặc biệt: Định nghĩa các giá trị ENUM được sử dụng trong các bảng (như status, auth_provider).
• Chính sách Lưu trữ và Xóa Dữ liệu (Data Retention & Deletion): Tham chiếu đến các ADRs liên quan (ví dụ: ADR-024, ADR-026) hoặc tóm tắt chính sách áp dụng cho các bảng trong mô hình này.
• Chiến lược Migration Schema: Tham chiếu đến ADR-023 hoặc mô tả ngắn gọn cách thay đổi schema sẽ được quản lý.
• Liên kết đến tài liệu liên quan: Ví dụ: file design chi tiết của service, interface contract, OpenAPI spec, các ADRs.
• Thông tin phiên bản tài liệu: Ghi rõ phiên bản, ngày cập nhật cuối cùng, tác giả, người review.

7. 📖 Tính Dễ Đọc, Dễ Tra Cứu và Bảo trì (Readability, Navigability & Maintainability):

• Markdown Formatting: Sử dụng hiệu quả các tính năng của Markdown (headings, tables, code blocks) để tài liệu sáng sủa, dễ đọc.
• Cấu trúc logic: Phân chia tài liệu thành các mục, tiểu mục một cách hợp lý.
• Mục lục (Table of Contents): Đối với tài liệu dài, có mục lục là cần thiết.
• Dễ cập nhật: Thiết kế tài liệu theo cách dễ dàng chỉnh sửa khi mô hình dữ liệu có thay đổi.