🗃️ User Service Sub - Data Model¶

📘 Giới thiệu¶

user-service/sub/ là một service chỉ đọc (read-only) theo kiến trúc master/sub. Service này quản lý dữ liệu người dùng trong phạm vi một tenant cụ thể. Dữ liệu được đồng bộ một chiều từ user-service/master thông qua các sự kiện Pub/Sub, không cho phép ghi trực tiếp từ phía client.

Tài liệu này mô tả toàn bộ mô hình dữ liệu nội bộ của Sub Service, bao gồm các bảng: UserLocal, UserTenantRole, RoleTemplateLite, và PermissionTemplateLite.
Dữ liệu này không bao gồm thông tin xác thực (auth), cũng không quản lý RBAC template gốc (chỉ giữ bản sao).

1. Sơ đồ ERD (Entity Relationship Diagram)¶

erDiagram
  UserLocal ||--o{ UserTenantRole : has
  UserTenantRole }o--|| RoleTemplateLite : references
  RoleTemplateLite ||--o{ PermissionTemplateLite : includes

  UserLocal {
    UUID user_id PK
    STRING email
    STRING full_name
    STRING auth_provider
    STRING status
    BOOLEAN is_active_in_tenant
    DATETIME created_at
    DATETIME updated_at
  }

  UserTenantRole {
    UUID user_id FK
    STRING role_code FK
    STRING[] permissions
  }

  RoleTemplateLite {
    STRING role_code PK
    STRING name
    STRING description
  }

  PermissionTemplateLite {
    STRING code PK
    STRING resource
    STRING action
    STRING description
  }

💡 Ghi chú: Mối quan hệ RoleTemplateLite → PermissionTemplateLite là logic, thể hiện việc một role "bao gồm" các permissions. RBACResolver sẽ tự động "expand" quyền dựa trên cache template – không có bảng join vật lý giữa 2 bảng này.

2. Chi tiết Bảng¶

📌 UserLocal¶

Bảng này chứa thông tin người dùng nội bộ đã được đồng bộ từ Master. Dùng để truy xuất dữ liệu user và trạng thái kích hoạt trong tenant hiện tại.

CREATE TABLE user_local (
  user_id UUID PRIMARY KEY,
  email VARCHAR(255) NOT NULL,
  full_name VARCHAR(255),
  auth_provider VARCHAR(32) NOT NULL,
  status VARCHAR(32) NOT NULL,
  is_active_in_tenant BOOLEAN NOT NULL DEFAULT TRUE,
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ
);

📌 UserTenantRole¶

Liên kết người dùng với các role trong tenant, dùng để expand quyền của user trong RBACResolver.

CREATE TABLE user_tenant_role (
  user_id UUID REFERENCES user_local(user_id) ON DELETE CASCADE,
  role_code VARCHAR(64) REFERENCES role_template_lite(role_code),
  permissions TEXT[],
  PRIMARY KEY (user_id, role_code)
);

📌 RoleTemplateLite¶

Bản sao role template đã đồng bộ từ Master. Không chỉnh sửa tại Sub.

CREATE TABLE role_template_lite (
  role_code VARCHAR(64) PRIMARY KEY,
  name VARCHAR(255),
  description TEXT
);

📌 PermissionTemplateLite¶

Danh sách các quyền có thể sử dụng tại tenant, được đồng bộ từ Master.

CREATE TABLE permission_template_lite (
  code VARCHAR(128) PRIMARY KEY,
  resource VARCHAR(64),
  action VARCHAR(64),
  description TEXT
);

3. Ràng buộc, Chỉ mục & Hành vi Cascade¶

🔐 Ràng buộc & Hành vi Cascade¶

• UserTenantRole.user_id có ON DELETE CASCADE → nếu user bị purge, các vai trò sẽ tự động bị xóa.
• UserTenantRole.role_code dùng ON DELETE RESTRICT → tránh lỗi do mất role đồng bộ.
• Không có bảng join giữa role và permission – mapping logic nằm trong memory (RBACResolver cache).

📌 Chỉ mục (Indexes)¶

💡 Các bảng template là dữ liệu tĩnh chỉ đọc, thường không cần index bổ sung ngoài khóa chính.

4. Enum sử dụng¶

auth_provider¶

• local
• google

status¶

• active
• invited
• suspended
• deleted

5. Tuân thủ ADR & Chính sách¶

6. Liên kết tài liệu¶

• Design Document
• Interface Contract
• OpenAPI Spec