Chuyển tới nội dung chính

Module Files

Overview​

Nhận file tải lên (ảnh đại diện, CV, logo công ty), kiểm tra theo chính sách từng thư mục, lưu trên đĩa và xóa file khi cần. File được phục vụ tĩnh từ thư mục public/.

Responsibilities​

  • Kiểm tra thư mục đích, loại file và dung lượng trước khi ghi.
  • Ghi file vào public/images/<thư mục>/.
  • Xóa file, và dọn file mồ côi theo yêu cầu của module khác.

Architecture​

Thành phầnFileVai trò
Controller (2 route, /api/v1/files)files.controller.tsPOST upload, DELETE remove
Cấu hình Multermulter.config.tsChọn thư mục, đặt tên file, lọc loại file
Chính sáchupload-policy.tsMIME, đuôi file, dung lượng, vai trò theo thư mục
Guardupload-auth.guard.tsĐọc header folder_type, kiểm tra vai trò
Servicefiles.service.tsXóa file, dọn file mồ côi

Dependencies​

Không import module nghiệp vụ. companies và cv-profiles import files.

Business Rules​

Thư mục đích lấy từ header folder_type (không phân biệt hoa thường). Giá trị không hợp lệ bị 400.

folder_typeLoại fileTối đaVai trò được phép
avatarjpg, jpeg, png, gif, webp5 MBMọi người dùng đăng nhập
cvpdf, doc, docx5 MBMọi người dùng đăng nhập
resumespdf, doc, docx, txt5 MBMọi người dùng đăng nhập
companyjpg, jpeg, png, gif (không có webp)5 MBChỉ HR và SUPER ADMIN (403 nếu không)

Nguồn: upload-policy.ts.

  • Đường dẫn ghi: <thư mục chạy>/public/images/<folder_type>/.
  • Đuôi file lấy từ bảng MIME khi có, nếu không thì dùng đuôi của tên gốc.
  • DELETE /files/remove chỉ SUPER ADMIN. Logo HR tải lên rồi không dùng do cron cleanupOrphanedLogos dọn (02:00 hằng ngày, file cũ hơn 24 giờ).

Data Model​

Không có collection. Đường dẫn file được lưu ở field của collection khác (users.avatar, companies.logo, resumes.url, cvprofiles.personalInfo.avatar).

API​

POST /files/upload, DELETE /files/remove. Chi tiết ở 05-api/endpoints/files.md (Phase 3).

Error Handling​

Tình huốngLỗi
folder_type thiếu hoặc sai400 kèm danh sách giá trị hợp lệ
Sai loại file400 kèm đuôi hợp lệ
Sai vai trò (thư mục company)403

Known Limitation​

  • File lưu trên đĩa cục bộ, không dùng chung giữa nhiều instance, xem scalability.
  • Chỉ kiểm tra MIME do client khai báo và đuôi file (theo cấu hình Multer), chưa thấy kiểm tra nội dung thật (magic bytes). Trạng thái: Chưa xác minh.
  • Thư mục public/ nằm trong .gitignore, nên file tải lên không thuộc repository.

Testing​

2 file test trong src/files/.

Source References​

src/files/, phục vụ tĩnh ở app.setup.ts (useStaticAssets).