1. Tổng quan

1.1 Mục đích

Tài liệu này mô tả các quyết định thiết kế kỹ thuật cho module Quản lý Tệp tin.

1.2 Yêu cầu được Giải quyết

2. Kiến trúc

2.1 Kiểu Kiến trúc

2.2 Các Quyết định Thiết kế Chính

3. Thiết kế Thành phần

3.1 Sơ đồ Thành phần

Hình 1: Các Thành phần Module FILE

3.2 Cấu trúc Module

src/
  file/
    file.module.ts
    file.controller.ts
    file.service.ts
    file.guard.ts
    permission.guard.ts       # Kiểm tra quyền truy cập
    dto/
      create-file.dto.ts
      confirm-file.dto.ts
      list-files.dto.ts
      create-folder.dto.ts
      rename-file.dto.ts
      move-file.dto.ts
      copy-file.dto.ts
      search-files.dto.ts
      batch-upload.dto.ts
      manage-permissions.dto.ts
      storage-quota.dto.ts
      storage-policy.dto.ts
    workers/
      file.worker.ts          # Bộ tiêu thụ xóa file vật lý
    events/
      file.events.ts          # Định nghĩa sự kiện
    services/
      folder.service.ts       # Quản lý thư mục
      permission.service.ts   # Quản lý quyền
      search.service.ts       # Tìm kiếm toàn văn
      storage.service.ts      # Theo dõi lưu trữ & hạn ngạch
      audit.service.ts        # Ghi nhật ký lịch sử truy cập
    utils/
      multer.util.ts          # Cấu hình Multer (local upload)
      file.util.ts            # Thao tác filesystem (đọc, xóa, copy)
      name-resolver.util.ts   # Xử lý tên trùng lặp

3.3 Ánh xạ Thành phần đến Yêu cầu

3.4 Thiết kế Lớp

FileController

FileService

FolderService

PermissionService

SearchService

StorageService

AuditService

FileWorker

4. Kiến trúc Dữ liệu

4.1 Cơ sở dữ liệu

Cơ sở dữ liệu: file_db (PostgreSQL)

Tham khảo: Thiết kế Cơ sở dữ liệu

4.2 Giải quyết Yêu cầu Dữ liệu

5. Thiết kế API

5.1 Ánh xạ Endpoint đến Yêu cầu

5.2 Pipeline Middleware

Request
  → AuthGuard (Xác thực JWT)
    → FileGuard (Kiểm tra quyền sở hữu/RBAC)
      → FileController (handler)
        → FileService (logic nghiệp vụ)
          → Response

6. Lưu trình Tích hợp

6.1 Lưu trình Tải lên Tệp tin

Sơ đồ Hoạt động

Hình 2: Lưu trình Hoạt động Tải lên Tệp tin

Sơ đồ Tuần tự

Hình 3: Lưu trình Tích hợp Tải lên Tệp tin

Mô tả Lưu trình:

1. Client gửi POST /files/upload (multipart/form-data) với tệp tin và category
2. FileService kiểm tra MIME types và giới hạn kích thước của danh mục
3. MulterUtil lưu tệp tin vào disk: uploads/{user_id}/{category}/{uuid_filename}
4. FileService chèn bản ghi sys_files với trạng thái ACTIVE và file_path
5. Bản ghi tệp tin được trả về cho client

6.2 Lưu trình Tải xuống Tệp tin

Sơ đồ Hoạt động

Hình 4: Lưu trình Hoạt động Tải xuống Tệp tin

Sơ đồ Tuần tự

Hình 5: Lưu trình Tích hợp Tải xuống Tệp tin

Mô tả Lưu trình:

1. Client gửi GET /files/:id/download
2. AuthGuard xác thực token JWT
3. FileGuard kiểm tra truy cập (chủ sở hữu hoặc admin/HR tổ chức)
4. FileService tra cứu bản ghi sys_files, lấy file_path
5. FileUtil đọc tệp tin từ local filesystem
6. Phản hồi được gửi đến client với nội dung tệp tin (file stream)

6.3 Lưu trình Xóa Tệp tin

Sơ đồ Hoạt động

Hình 6: Lưu trình Hoạt động Xóa Tệp tin

Sơ đồ Tuần tự

Hình 7: Lưu trình Tích hợp Xóa Tệp tin

Mô tả Lưu trình:

1. Client gửi DELETE /files/:id
2. AuthGuard xác thực token JWT
3. FileGuard kiểm tra quyền sở hữu hoặc vai trò admin
4. FileService đặt trạng thái thành DELETED và timestamp deleted_at
5. FileService gọi FileUtil để xóa tệp tin trên filesystem (fs.unlink)
6. Phản hồi thành công được gửi đến client

6.4 Lưu trình Dọn dẹp Tệp tin Tạm

Sơ đồ Hoạt động

Hình 8: Lưu trình Hoạt động Dọn dẹp Tệp tin Tạm

Sơ đồ Tuần tự

Hình 9: Lưu trình Tích hợp Dọn dẹp Tệp tin Tạm

Mô tả Lưu trình:

1. NestJS Scheduler kích hoạt tác vụ cron mỗi 1 giờ
2. TempCleanupJob truy vấn sys_files where status=TEMP AND created_at < NOW() - 24h
3. Đối với mỗi tệp tin TEMP hết hạn:
   • Xóa bản ghi sys_files
   • Xóa file trên filesystem
4. FileUtil xóa file trên filesystem

6.5 Lưu trình Quản lý Thư mục

Mô tả Lưu trình:

1. Client gửi POST /files/folders với name và parent_folder_id
2. FolderService kiểm tra tên (không có ký tự đặc biệt, duy nhất trong thư mục cha)
3. FolderService tạo bản ghi sys_files với type=FOLDER
4. Nếu thư mục cha có quyền: kế thừa quyền cho thư mục mới
5. Bản ghi thư mục được trả về cho client

6.6 Lưu trình Di chuyển/Sao chép Tệp tin

Mô tả Lưu trình (Di chuyển):

1. Client gửi POST /files/:id/move với destination_folder_id
2. PermissionGuard kiểm tra quyền EDIT trên nguồn và WRITE trên đích
3. FileService cập nhật parent_folder_id
4. NameResolverUtil xử lý tên trùng lặp tại đích
5. AuditService ghi nhật ký sự kiện di chuyển
6. Bản ghi tệp tin đã cập nhật được trả về

Mô tả Lưu trình (Sao chép):

1. Client gửi POST /files/:id/copy với destination_folder_id
2. PermissionGuard kiểm tra VIEW trên nguồn và WRITE trên đích
3. FileService tạo bản ghi mới với cùng file_path (không sao chép file vật lý)
4. NameResolverUtil xử lý tên trùng lặp tại đích
5. Bản ghi tệp tin mới được trả về

6.7 Lưu trình Ghi nhật ký Truy cập

Mô tả Lưu trình:

1. Truy cập tệp tin xảy ra (xem, tải xuống, sửa, xóa)
2. AuditService thu thập: user_id, file_id, action, timestamp, IP
3. AuditService phát sự kiện đến RabbitMQ (hàng đợi: log.events)
4. Module LOG tiêu thụ sự kiện và lưu trữ
5. Lịch sử truy cập sẵn sàng cho các truy vấn kiểm toán

7. Thiết kế Bảo mật

7.1 Quy tắc Kiểm soát Truy cập

7.2 Kế thừa Quyền

• Quyền kế thừa từ thư mục cha đến các tệp tin/thư mục con
• Quyền rõ ràng trên mục con ghi đè quyền kế thừa
• Xóa thư mục cha cascade dọn dẹp quyền
• Hệ thống kiểm tra: chủ sở hữu → vai trò (admin/HR) → quyền rõ ràng → quyền kế thừa → DENY

7.3 Bảo mật Local Filesystem

• Path traversal prevention: kiểm tra và sanitize file path, không cho phép truy cập ngoài thư mục uploads/
• File type validation: kiểm tra MIME type theo danh mục trước khi lưu
• File size validation: kiểm tra kích thước theo danh mục trước khi lưu
• Thư mục uploads/ nằm ngoài web root, không accessible trực tiếp qua HTTP
• Chỉ serve file qua endpoint có xác thực (FILE Service)

8. Tóm tắt Truy xuất Nguồn gốc