Cấu trúc Dữ liệu: Module Drive
Tài liệu này chi tiết về cấu trúc cơ sở dữ liệu cho module Drive.
1. Tổng quan
Module Drive sử dụng PostgreSQL với Drizzle ORM. Nó triển khai mô hình lưu trữ lớp kép: siêu dữ liệu (metadata) được lưu trong SQL, trong khi nội dung nhị phân được lưu trữ trong một Kho lưu trữ Đối tượng MinIO (tương thích S3).
Đa thuê bao: Không có bảng
organizations. Sự cô lập theo tổ chức được thực thi quaorg_id— một cột UUID có mặt trên mọi bảng miền dữ liệu, được trích xuất từ JWT của người dùng đã xác thực.
Mô hình Tên miền Cốt lõi
2. Định nghĩa Bảng Miền Dữ liệu
folders
Đại diện cho cấu trúc thư mục phân cấp.
| Trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | PK, tự động tạo. |
org_id | uuid | Phạm vi tổ chức (không phải FK — phi chuẩn hóa). |
parent_id | uuid | FK đến folders.id (tham chiếu chính nó). null cho thư mục gốc. |
name | text | Tên thư mục. |
user_id | uuid | Chủ sở hữu thư mục. |
created_by | uuid | Người dùng đã tạo thư mục. |
created_at | timestamptz | Thời điểm tạo. |
files
Siêu dữ liệu cho các đối tượng được lưu trữ.
| Trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | PK, tự động tạo. |
org_id | uuid | Phạm vi tổ chức (không phải FK — phi chuẩn hóa). |
folder_id | uuid | FK đến folders.id. null cho tệp ở cấp gốc. |
name | text | Tên hiển thị. |
original_name | text | Tên tệp gốc khi tải lên. |
size | bigint | Kích thước tệp tính bằng byte. |
mime_type | text | Kiểu MIME tiêu chuẩn (ví dụ: image/jpeg). |
storage_path | text | Khóa đối tượng trong MinIO: {orgId}/{timestamp}-{randomHex}-{filename}. |
storage_bucket | text | Tên bucket MinIO đích. |
user_id | uuid | Chủ sở hữu tệp. |
uploaded_by | uuid | Người dùng đã tải lên tệp. |
created_at | timestamptz | Thời điểm tải lên. |
share_links
Các token truy cập bên ngoài cho tệp.
| Trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | PK, tự động tạo. |
file_id | uuid | FK đến files.id. |
token | text | Token bảo mật duy nhất, mã hóa base64url. |
expires_at | timestamptz | Thời điểm hết hạn. |
created_by | uuid | Người dùng đã tạo liên kết chia sẻ. |
revoked_at | timestamptz | Timestamp xóa mềm. null nếu vẫn đang hoạt động. |
3. Định nghĩa Bảng Định danh
users
Bản ghi người dùng cục bộ được tạo từ quá trình trao đổi Shell JWT.
| Trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | PK, tự động tạo. |
shell_user_id | varchar(255) | Liên kết định danh người dùng Shell (duy nhất, nullable). |
email | varchar(320) | Email người dùng (duy nhất). |
name | varchar(255) | Tên hiển thị (nullable). |
status | varchar(20) | active hoặc suspended. Mặc định: active. |
created_at | timestamp | Thời điểm tạo tài khoản. |
updated_at | timestamp | Thời điểm sửa đổi gần nhất. |
roles
Nhóm quyền hạn có thể gán cho người dùng.
| Trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | PK, tự động tạo. |
name | varchar(100) | Tên vai trò duy nhất. |
is_default | boolean | Nếu true, tự động gán cho người dùng mới khi tạo tài khoản. |
user_roles
Bảng liên kết gán vai trò cho người dùng.
| Trường | Kiểu | Mô tả |
|---|---|---|
user_id | uuid | FK đến users.id (cascade delete). |
role_id | uuid | FK đến roles.id (cascade delete). |
permissions
Mã quyền hạn được gán cho vai trò.
| Trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | PK, tự động tạo. |
code | varchar(255) | Mã quyền hạn duy nhất (ví dụ: drive:read, drive:write). |
role_id | uuid | FK đến roles.id (cascade delete). |
4. Chi tiết Triển khai
- Xóa Nguyên tử: Khi một thư mục bị xóa, dịch vụ đệ quy xóa tất cả thư mục con, sau đó xóa tất cả tệp (bao gồm đối tượng MinIO và bản ghi share_links) trước khi xóa bản ghi thư mục.
- Định dạng Khóa Lưu trữ: Khóa đối tượng MinIO theo mẫu
{orgId}/{timestamp}-{randomHex}-{filename}để đảm bảo tính duy nhất toàn cầu. - Thu hồi Liên kết Chia sẻ: Xóa mềm qua timestamp
revokedAt. Xóa cứng xảy ra tự động khi tệp cha bị xóa. - Tạo Người dùng: Khi trao đổi Shell JWT lần đầu, Drive API tạo người dùng cục bộ và gán tất cả vai trò có
is_default = true.